O que são decoradores e como você escreve um?

Question

Accepted Answer

Um **decorador** é uma função que **envolve outra função** para adicionar comportamento sem modificar o código original. É aplicado com a sintaxe `@decorator` acima de uma função — uma forma limpa de adicionar cross-cutting concerns como logging, timing, caching ou controle de acesso.

## Como decoradores funcionam

```python
def my_decorator(func):
    def wrapper(*args, **kwargs):       # wraps the original function
        print("before")
        result = func(*args, **kwargs)  # call the original
        print("after")
        return result
    return wrapper                       # return the wrapped version

@my_decorator
def greet(name):
    print(f"Hello {name}")

greet("Ann")
# Output: before / Hello Ann / after
```

A sintaxe `@my_decorator` é açúcar para `greet = my_decorator(greet)` — ela substitui `greet` pelo `wrapper`, que executa código extra em torno da chamada original. O `*args, **kwargs` torna o wrapper funcional para qualquer assinatura de função.

## Um exemplo prático: timing

```python
import time, functools

def timed(func):
    @functools.wraps(func)        # preserves func's name/docstring (important!)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        print(f"{func.__name__} took {time.perf_counter() - start:.3f}s")
        return result
    return wrapper

@timed
def slow_task():
    time.sleep(1)
```

`@functools.wraps(func)` é importante — sem ele, a função envolvida perde seu nome original e docstring.

## Decoradores com argumentos

```python
def repeat(times):               # outer takes the decorator's argument
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for _ in range(times):
                func(*args, **kwargs)
        return wrapper
    return decorator

@repeat(times=3)
def hello(): print("hi")  # prints "hi" three times
```

Um decorador parametrizado precisa de uma camada extra (uma função que retorna um decorador).

## Decoradores comuns built-in / da biblioteca

```text
@property            → turn a method into a computed attribute
@staticmethod / @classmethod → method types
@functools.lru_cache → memoize results
@app.route("/")      → web framework routing (Flask)
@pytest.fixture      → test fixtures
```

## Por que isso importa

Decoradores são uma funcionalidade poderosa e distintamente pythônica para **adicionar comportamento reutilizável** (logging, timing, caching, autenticação, validação, roteamento) a funções de forma limpa e declarativa — separando cross-cutting concerns da lógica principal.

Estão em todo lugar no Python real: frameworks web (`@app.route`), caching (`@lru_cache`), classes (`@property`) e testes.

Compreender como escrevê-los (uma função wrapper, `*args/**kwargs`, `functools.wraps`) e a forma parametrizada permite usar os decoradores do ecossistema corretamente e construir suas próprias abstrações reutilizáveis.