Typing stubs for the decorator library

Warnings

• breaking Typeshed stub packages, including `types-decorator`, can sometimes introduce changes that might cause your code to fail type checking, even if the runtime `decorator` library itself hasn't changed. This is due to updates in the stub definitions for improved accuracy or to align with new Python typing features.
  Fix: It is highly recommended to pin the version of `types-decorator` to match the major.minor version of the `decorator` library you are using (e.g., `types-decorator==5.2.*` for `decorator==5.2.*`). This ensures the stubs are compatible with your runtime library. Regularly update and re-run your type checker to catch any new issues.
• gotcha When creating custom decorators manually (without using `decorator.decorator`), a common pitfall is that the decorated function loses its original metadata (like `__name__`, `__doc__`, `__module__`) and signature. This can hinder debugging, introspection, and tools that rely on function signatures.
  Fix: The `decorator` library's `decorator` function automatically handles preservation of metadata and signature. If writing a custom decorator without this library, always use `@functools.wraps(func)` on your inner wrapper function. For example: `import functools; def my_decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): return func(*args, **kwargs) return wrapper`
• gotcha When applying multiple decorators to a single function, their order of application matters. Decorators are applied in reverse order of their appearance in the code, meaning the decorator closest to the function definition is applied first, and the topmost decorator is applied last.
  Fix: Carefully consider the interaction between decorators and test functions with stacked decorators thoroughly. If the behavior is unexpected, try reordering the decorators.

Install

• pip install types-decorator Install types-decorator
• pip install decorator types-decorator Install decorator library and its stubs

Imports

• decorator

  from decorator import decorator

  This is the primary import for creating signature-preserving decorators using the 'decorator' library.

Quickstart

This quickstart demonstrates how to use the `decorator` library (for which `types-decorator` provides stubs) to create a custom decorator that warns if a function takes too long to execute. It showcases both a simple decorator application and a decorator factory with arguments, while automatically preserving the decorated function's signature and metadata.

import time
import logging
from decorator import decorator

logging.basicConfig(level=logging.INFO)

@decorator
def warn_slow(func, timelimit=60, *args, **kw):
    """A decorator factory that logs if a function call exceeds a timelimit."""
    t0 = time.time()
    result = func(*args, **kw)
    dt = time.time() - t0
    if dt > timelimit:
        logging.warning('%s took %.2f seconds (exceeded %d s)', func.__name__, dt, timelimit)
    else:
        logging.info('%s took %.2f seconds', func.__name__, dt)
    return result

@warn_slow
def process_data(duration: float):
    """Simulates a data processing operation."""
    time.sleep(duration)
    return f"Processed data in {duration} seconds"

@warn_slow(timelimit=1) # Override default timelimit
def analyze_report(duration: float):
    """Simulates a report analysis with a custom timelimit."""
    time.sleep(duration)
    return f"Analyzed report in {duration} seconds (custom timelimit)"

# Example usage:
print(process_data(0.5))
print(process_data(2.0))
print(analyze_report(0.8))
print(analyze_report(1.5))