| single |
wrapt
=====
|PyPI| |Documentation|
A Python module for decorators, wrappers and monkey patching.
Overview
--------
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.
Key Features
------------
* **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**
Installation
------------
Install from PyPI using pip::
pip install wrapt
Supported Python Versions
--------------------------
* Python 3.8+
* CPython and PyPy implementations
Documentation
-------------
For comprehensive documentation, examples, and advanced usage patterns,
visit:
* https://wrapt.readthedocs.io/
Quick Start
-----------
To implement your decorator you need to first define a wrapper function.
This will be called each time a decorated function is called. The wrapper
function needs to take four positional arguments:
* wrapped - The wrapped function which in turns needs to be called by your
wrapper function.
* instance - The object to which the wrapped function was bound when it was
called.
* args - The list of positional arguments supplied when the decorated
function was called.
* kwargs - The dictionary of keyword arguments supplied when the decorated
function was called.
The wrapper function would do whatever it needs to, but would usually in
turn call the wrapped function that is passed in via the wrapped
argument.
The decorator ``@wrapt.decorator`` then needs to be applied to the wrapper
function to convert it into a decorator which can in turn be applied to
other functions.
|