A Python module for decorators, wrappers and monkey patching.
The wrapt module provides a transparent object proxy for Python, which can be used as the basis for the construction of function wrappers and decorator functions.
The wrapt module focuses very much on correctness. It goes way beyond existing mechanisms such as functools.wraps() to ensure that decorators preserve introspectability, signatures, type checking abilities etc. The decorators that can be constructed using this module will work in far more scenarios than typical decorators and provide more predictable and consistent behaviour.
To ensure that the overhead is as minimal as possible, a C extension module is used for performance critical components. An automatic fallback to a pure Python implementation is also provided where a target system does not have a compiler to allow the C extension to be compiled.
- Universal decorators that work with functions, methods, classmethods, staticmethods, and classes
- Transparent object proxies for advanced wrapping scenarios
- Monkey patching utilities for safe runtime modifications
- C extension for optimal performance with Python fallback
- Comprehensive introspection preservation (signatures, annotations, etc.)
- Thread-safe decorator implementations
pip install wraptimport wrapt
@wrapt.decorator
def pass_through(wrapped, instance, args, kwargs):
return wrapped(*args, **kwargs)
@pass_through
def function():
passimport wrapt
def with_arguments(myarg1, myarg2):
@wrapt.decorator
def wrapper(wrapped, instance, args, kwargs):
print(f"Arguments: {myarg1}, {myarg2}")
return wrapped(*args, **kwargs)
return wrapper
@with_arguments(1, 2)
def function():
passimport inspect
import wrapt
@wrapt.decorator
def universal(wrapped, instance, args, kwargs):
if instance is None:
if inspect.isclass(wrapped):
# Decorator was applied to a class
print("Decorating a class")
else:
# Decorator was applied to a function or staticmethod
print("Decorating a function")
else:
if inspect.isclass(instance):
# Decorator was applied to a classmethod
print("Decorating a classmethod")
else:
# Decorator was applied to an instancemethod
print("Decorating an instance method")
return wrapped(*args, **kwargs)For comprehensive documentation, examples, and advanced usage patterns, visit:
Two sets of guided, hands-on workshops run in JupyterLab and check your work as you go. Neither needs anything installed.
decorator-workshops teaches Python decorators using only the standard library, from what a decorator is through to writing your own for functions, methods, classes and coroutines. It is the place to start if decorators are new to you, and covers the ground the wrapt workshops build on. The badges above start the workshops in your browser with no account or server at all, on mybinder.org, or in GitHub Codespaces. The repository README explains each option and how to run the workshops locally.
wrapt-workshops holds three collections of workshops on wrapt itself: writing decorators with wrapt, monkey patching with wrapt, and object proxies with wrapt, each shown beside the standard library way of doing the same thing. The badges above start them on mybinder.org or in GitHub Codespaces. The repository README explains each option and how to run the workshops locally.
If the monkey patching side of wrapt is what brought you here, also look at wrapture. It is a sibling project built on the monkey patching machinery of wrapt, and provides a higher level API on top of it. A clean lifecycle and behaviour vocabulary over wrap_object() lets you point at a method by name and stub it, fail it, transform its arguments or result, or wrap it with a decorator, then remove it again. On top of that sit unit testing, where the real code runs and how calls flowed through it is recorded and asserted on, and ad-hoc tracing, where a running application emits a structured call tree with no code changes, with export to OpenTelemetry. The wrapture documentation has the details, and wrapture-workshops has guided workshops of its own.
- Python 3.9+
- CPython
- PyPy
We welcome contributions! This is a pretty casual process - if you're interested in suggesting changes, improvements, or have found a bug, please reach out via the GitHub issue tracker. Whether it's a small fix, new feature idea, or just a question about how something works, feel free to start a discussion.
Please note that wrapt is now considered a mature project. We're not expecting any significant new developments or major feature additions. The primary focus is on ensuring that the package continues to work correctly with newer Python versions and maintaining compatibility as the Python ecosystem evolves. Higher level functionality is being developed in wrapture rather than here.
For information about running tests, including Python version-specific test conventions and available test commands, see TESTING.md.
This project is licensed under the BSD License - see the LICENSE file for details.
- Documentation: https://wrapt.readthedocs.io/
- PyPI: https://pypi.python.org/pypi/wrapt
- Issues: https://github.com/GrahamDumpleton/wrapt/issues/
- Changelog: https://wrapt.readthedocs.io/en/latest/changes.html
This repository also contains a series of blog posts explaining the design and implementation of wrapt:
- How you implemented your Python decorator is wrong
- The interaction between decorators and descriptors
- Implementing a factory for creating decorators
- Implementing a universal decorator
- Decorators which accept arguments
- Maintaining decorator state using a class
- The missing synchronized decorator
- The synchronized decorator as context manager
- Performance overhead of using decorators
- Performance overhead when applying decorators to methods
- Safely applying monkey patches in Python
- Using wrapt to support testing of software
- Ordering issues when monkey patching in Python
- Automatic patching of Python applications