Mga decorator sa Python: ano ang mga ito, paano gumagana, at paano gumawa ng sarili

Ang decorator sa Python ay function na tumatanggap ng isa pang function at nagbabalik ng bago — kadalasan ay wrapper sa paligid ng orihinal. Sa ganitong paraan, nadadagdagan ng gawi ang isang function — logging, pagsukat ng oras, cache, o muling pagsubok — nang hindi binabago ang code nito. Isinusulat ang mga decorator sa Python sa pamamagitan ng linyang @pangalan sa itaas ng deklarasyon ng function, at makikita ang mga ito kahit saan: sa Flask at FastAPI, sa pytest, at sa standard library.

Ano ang decorator sa simpleng salita

Isipin ang regalo at ang pambalot nito. Nananatiling pareho ang regalo (function), pero may patong sa labas na unang gumagana. Ganyan ang decorator: kapag tinawag ang function, unang tatakbo ang code ng wrapper, tatawagin nito ang orihinal na function, at maaari nitong gawin ang anuman sa resulta.

Gumagana ito dahil sa Python, ordinaryong object ang mga function. Maaari silang ipasa sa ibang function, ibalik mula sa function, at ideklara sa loob ng function. Nakabatay ang mga decorator sa tatlong katangiang ito.

Paano gumagana ang decorator: ang @ ay syntactic sugar

Narito ang pinakasimpleng decorator, na nagpi-print ng mensahe bago at pagkatapos ng tawag:

def log_calls(func):
    def wrapper():
        print(f"Tinatawag ang {func.__name__}")
        result = func()
        print(f"Natapos ang {func.__name__}")
        return result
    return wrapper

@log_calls
def hello():
    print("Kumusta!")

hello()

Tinatawag ang hello
Kumusta!
Natapos ang hello

Ang @log_calls sa itaas ng def ay ganap na katumbas ng linyang nasa ilalim ng deklarasyon:

def hello():
    print("Kumusta!")

hello = log_calls(hello)

Ngayon, ang pangalang hello ay tumuturo na sa wrapper, at nabubuhay ang orihinal na function sa loob ng closure — naaalala ng wrapper ang variable na func mula sa panlabas na function. Mahalagang detalye: isang beses lang nailalapat ang decorator, sa sandaling tumakbo ang def, ibig sabihin kapag na-import ang module; pero tumatakbo ang wrapper sa bawat tawag.

Mga closure at decorator

Ang closure ay nested na function na naaalala ang mga variable ng panlabas na function kahit tapos na ito. Kung walang closure, walang decorator: sa ganitong paraan nakukuha ng wrapper ang access sa func. Maaari ring mag-imbak ng estado sa closure, gaya ng counter ng tawag:

def count_calls(func):
    calls = 0
    def wrapper(*args, **kwargs):
        nonlocal calls
        calls += 1
        print(f"{func.__name__}: tawag blg. {calls}")
        return func(*args, **kwargs)
    return wrapper

Paano gumawa ng decorator sa Python: pangkalahatang template

May dalawang kahinaan ang unang halimbawa: hindi tumatanggap ng argumento ang wrapper, at "nilalamon" nito ang pangalan ng orihinal na function. Ito ang gumaganang template na dapat simulan sa anumang decorator:

import functools

def my_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # code bago tawagin
        result = func(*args, **kwargs)
        # code pagkatapos tawagin
        return result
    return wrapper

Tatlong tuntunin ng template:

1. *args, **kwargs — tumatanggap ang wrapper ng anumang argumento at ipinapasa ang mga ito nang hindi binabago.
2. return result — huwag kalimutang ibalik ang resulta, kung hindi, laging None ang ibibigay ng decorated na function.
3. @functools.wraps(func) — ilipat ang metadata ng orihinal na function sa wrapper.

Halimbawa ng decorator — pagsukat ng oras ng pagpapatakbo:

import functools
import time

def timer(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"Tumagal ng {elapsed:.3f} s ang {func.__name__}")
        return result
    return wrapper

@timer
def slow_sum(n):
    return sum(range(n))

slow_sum(10_000_000)   # Tumagal ng 0.142 s ang slow_sum

Bakit kailangan ang functools.wraps

Kung wala ang wraps, mapapalitan ng decorated na function ang pangalan at docstring nito — makikita ang wrapper sa labas:

def plain(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@plain
def add(a, b):
    """Nagdaragdag ng dalawang numero."""
    return a + b

print(add.__name__, add.__doc__)   # wrapper None

Sa @functools.wraps(func), nakukuha ng wrapper ang __name__, __doc__, __module__, __qualname__, at __annotations__ ng orihinal, at nakatago sa attribute na __wrapped__ ang reference sa orihinal. Mahalaga ito para sa debugging at traceback, para sa help(), para sa mga framework na nagre-rehistro ng function ayon sa pangalan, at para sa inspect.signature, na nagpapakita ng tunay na signature.

Decorator na may parameter (na may argumento)

Minsan kailangan ng decorator ng mga setting: @retry(times=3), @app.route("/"). Para dito, nagdaragdag ng isa pang antas ng nesting. Tumatanggap ang panlabas na function ng mga parameter at nagbabalik ng tunay na decorator — ang ganitong konstruksiyon ay tinatawag na decorator factory.

import functools

def repeat(times):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            result = None
            for _ in range(times):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(times=3)
def ping():
    print("ping")

ping()   # ping, ping, ping — tatlong linya

Pagkakasunod ng mga tawag: ibinabalik ng repeat(times=3) ang decorator, na inilalapat sa ping at nagbabalik ng wrapper. Sa madaling sabi, ang @repeat(times=3) ay katumbas ng ping = repeat(times=3)(ping).

Praktikal na halimbawa — muling pagsubok kapag may error:

import functools
import time

def retry(times=3, delay=1.0, exceptions=(Exception,)):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except exceptions:
                    if attempt == times:
                        raise
                    time.sleep(delay)
        return wrapper
    return decorator

@retry(times=5, delay=0.5, exceptions=(ConnectionError,))
def fetch_rate():
    ...

Maraming decorator sa iisang function

Maaaring magkasunod-sunod na ilagay ang mga decorator. Inilalapat ang mga ito mula ibaba pataas: ang pinakamalapit sa def ang unang nailalapat.

@timer
@log_calls
def report():
    ...

# katumbas nito:
report = timer(log_calls(report))

Sa pagtawag, unang tumatakbo ang panlabas na layer (timer), kaya masusukat din nito ang oras ng log_calls. Mahalaga ang pagkakasunod, halimbawa kung ang isang decorator ay sumusuri ng pahintulot at ang isa pa ay nag-cache ng resulta.

Mga karaniwan at built-in na decorator ng Python

Marami nang kapaki-pakinabang na decorator sa wika at sa standard library:

Caching: functools.cache at lru_cache

Ang caching decorator ay nagtatandaan ng resulta para sa bawat hanay ng argumento, at sa susunod na tawag ay ibinabalik ito nang hindi na kinakalkula. Klasikong halimbawa ang recursive na Fibonacci, na kung walang cache ay napakabagal ng pagkalkula — exponential ang oras:

import functools

@functools.cache
def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)

print(fib(100))   # 354224848179261915075

Iniimbak ng functools.cache (lumitaw sa Python 3.9) ang lahat ng resulta nang walang limitasyon. Ang @functools.lru_cache(maxsize=128) ay nagtatago lamang ng pinakahuling mga entry at inaalis ang mga luma — mas ligtas ito para sa matagal nang tumatakbong serbisyo. Makikita ang estadistika gamit ang fib.cache_info(), at nililinis gamit ang fib.cache_clear(). Dapat hashable ang mga argumento ng ganitong function: ang list bilang argumento ay magbibigay ng TypeError: unhashable type: 'list'. Ang caching ay dapat gamitin lamang sa mga pure function — yaong laging nagbabalik ng parehong resulta sa parehong argumento at walang side effect.

Ano ang ginagawa ng decorator na property

Pinapayagan ng @property na tawagin ang method na parang attribute, nang walang panaklong, at kung kinakailangan, kontrolin ang pag-assign:

class Account:
    def __init__(self, balance):
        self._balance = balance

    @property
    def balance(self):
        return self._balance

    @balance.setter
    def balance(self, value):
        if value < 0:
            raise ValueError("Hindi maaaring negatibo ang balanse")
        self._balance = value

acc = Account(100)
print(acc.balance)   # 100
acc.balance = -5     # ValueError

staticmethod at classmethod

class Money:
    def __init__(self, kopecks):
        self.kopecks = kopecks

    @classmethod
    def from_rubles(cls, rubles):
        return cls(round(rubles * 100))

    @staticmethod
    def is_valid(value):
        return value >= 0

m = Money.from_rubles(12.5)
print(m.kopecks, Money.is_valid(-1))   # 1250 False

Ang @classmethod ang nagbibigay-daan sa method na gumana sa mismong klase at hindi sa mga instance nito: tamang makakalikha ang from_rubles ng object ng subclass.

Mga decorator ng klase at mga klaseng decorator

Maaaring ilapat ang decorator sa klase: tumatanggap ito ng klase at nagbabalik ng klase (ang parehong klase o binago). Ganito gumagana ang @dataclass. Simpleng halimbawa — isang registry ng mga klase:

registry = {}

def register(cls):
    registry[cls.__name__] = cls
    return cls

@register
class CsvExporter:
    pass

print(registry)   # {'CsvExporter': <class '__main__.CsvExporter'>}

Ang kabaligtaran ay klase bilang decorator. Puwede ang anumang object na may method na __call__; kapaki-pakinabang na itago ang estado sa mga attribute ng instance:

import functools

class CountCalls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.calls = 0

    def __call__(self, *args, **kwargs):
        self.calls += 1
        return self.func(*args, **kwargs)

@CountCalls
def tick():
    pass

tick(); tick()
print(tick.calls)   # 2

Asynchronous na decorator

Para sa mga function na async def, dapat ding maging coroutine ang wrapper at maghintay ng resulta gamit ang await; kung hindi, ibabalik nito ang hindi pa natatapos na coroutine object:

import functools

def log_async(func):
    @functools.wraps(func)
    async def wrapper(*args, **kwargs):
        print(f"Nagsimula ang {func.__name__}")
        result = await func(*args, **kwargs)
        print(f"Tapos na ang {func.__name__}")
        return result
    return wrapper

Bakit gumagamit ng decorator sa Python

• Cross-cutting na lohika — logging, metrics, at pagsukat ng oras nang hindi kinokopya ang code sa bawat function.
• Caching — @functools.cache para sa mamahaling pure na kalkulasyon.
• Pagsusuri — pahintulot, pagbeberipika ng argumento, authorization sa web handler.
• Pagre-rehistro — mga ruta sa Flask at FastAPI (@app.get("/")), mga fixture ng pytest.
• Katatagan — muling pagsubok, timeout, pangangasiwa ng error.

Pangunahing bentahe ang paghihiwalay ng responsibilidad: ginagawa ng function ang sariling gawain, at isinasaksak ang karagdagang gawi sa isang linya, at ganoon din kadali itong alisin.

Karaniwang pagkakamali

• Hindi ibinabalik ng wrapper ang resulta — None ang ibinibigay ng function pagkatapos ma-decorate.
• Walang *args, **kwargs — TypeError kapag tinawag na may argumento.
• Nakalimutan ang wraps — maling __name__ at docstring, at kalituhan sa mga log.
• Nakalimutan ang panaklong sa factory — @repeat sa halip na @repeat(3): mapupunta ang function sa parameter na times.
• Mabigat na code sa katawan ng decorator — tumatakbo ito sa pag-import ng module, hindi sa pagtawag.

Buod

Ang mga decorator sa Python ay higher-order function: tumatanggap ng function, nagbabalik ng wrapper, at ang @ ay maikling anyo lamang ng assignment. Magsimula sa template na may *args, **kwargs, return result, at functools.wraps; para sa mga setting, magdagdag ng antas ng factory. Ang mga function, closure, at annotation na pinagbabatayan ng mga decorator ay tinalakay nang praktikal sa kurso ng Python.