{"id":4300,"library":"types-decorator","title":"Typing stubs for the decorator library","description":"types-decorator provides high-quality static type annotations (stubs) for the popular `decorator` Python library. It enables type checkers like MyPy and Pyright to analyze code using `decorator` for type correctness, enhancing maintainability and catching potential errors early. Maintained by the `typeshed` project, these stubs are automatically released to PyPI regularly, often daily, to reflect updates in the upstream library. The current version is 5.2.0.20260408.","status":"active","version":"5.2.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type hints","decorator","typeshed"],"install":[{"cmd":"pip install types-decorator","lang":"bash","label":"Install types-decorator"},{"cmd":"pip install decorator types-decorator","lang":"bash","label":"Install decorator library and its stubs"}],"dependencies":[{"reason":"This package provides typing stubs for the 'decorator' library, which is a runtime dependency for functionality.","package":"decorator","optional":false}],"imports":[{"note":"This is the primary import for creating signature-preserving decorators using the 'decorator' library.","symbol":"decorator","correct":"from decorator import decorator"}],"quickstart":{"code":"import time\nimport logging\nfrom decorator import decorator\n\nlogging.basicConfig(level=logging.INFO)\n\n@decorator\ndef warn_slow(func, timelimit=60, *args, **kw):\n    \"\"\"A decorator factory that logs if a function call exceeds a timelimit.\"\"\"\n    t0 = time.time()\n    result = func(*args, **kw)\n    dt = time.time() - t0\n    if dt > timelimit:\n        logging.warning('%s took %.2f seconds (exceeded %d s)', func.__name__, dt, timelimit)\n    else:\n        logging.info('%s took %.2f seconds', func.__name__, dt)\n    return result\n\n@warn_slow\ndef process_data(duration: float):\n    \"\"\"Simulates a data processing operation.\"\"\"\n    time.sleep(duration)\n    return f\"Processed data in {duration} seconds\"\n\n@warn_slow(timelimit=1) # Override default timelimit\ndef analyze_report(duration: float):\n    \"\"\"Simulates a report analysis with a custom timelimit.\"\"\"\n    time.sleep(duration)\n    return f\"Analyzed report in {duration} seconds (custom timelimit)\"\n\n# Example usage:\nprint(process_data(0.5))\nprint(process_data(2.0))\nprint(analyze_report(0.8))\nprint(analyze_report(1.5))\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions of types-decorator"},{"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`","message":"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.","severity":"gotcha","affected_versions":"All Python versions when writing manual decorators"},{"fix":"Carefully consider the interaction between decorators and test functions with stacked decorators thoroughly. If the behavior is unexpected, try reordering the decorators.","message":"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.","severity":"gotcha","affected_versions":"All Python versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}