0
# Wrapt
1

2
A module for transparent object proxies and decorator wrappers that preserves function signatures, supports introspection, and enables sophisticated monkey patching. The wrapt module focuses heavily on correctness, maintaining function metadata, and providing consistent behavior across different wrapping scenarios.
3

4
## Package Information
5

6
- **Package Name**: wrapt
7
- **Language**: Python
8
- **Installation**: `pip install wrapt`
9

10
## Core Imports
11

12
```python
13
import wrapt
14
```
15

16
Common imports for specific functionality:
17

18
```python
19
from wrapt import ObjectProxy, FunctionWrapper, decorator
20
from wrapt import wrap_function_wrapper, synchronized
21
```
22

23
## Basic Usage
24

25
```python
26
import wrapt
27

28
# Using ObjectProxy for transparent wrapping
29
class MyProxy(wrapt.ObjectProxy):
30
    def __init__(self, wrapped):
31
        super().__init__(wrapped)
32
        self._self_extra_data = "custom data"
33

34
# Creating a function decorator
35
@wrapt.decorator
36
def my_decorator(wrapped, instance, args, kwargs):
37
    print(f"Calling {wrapped.__name__}")
38
    return wrapped(*args, **kwargs)
39

40
@my_decorator
41
def my_function():
42
    return "Hello, World!"
43

44
# Monkey patching with proper wrapper
45
def timing_wrapper(wrapped, instance, args, kwargs):
46
    import time
47
    start = time.time()
48
    result = wrapped(*args, **kwargs)
49
    end = time.time()
50
    print(f"{wrapped.__name__} took {end - start:.4f} seconds")
51
    return result
52

53
wrapt.wrap_function_wrapper('time', 'sleep', timing_wrapper)
54
```
55

56
## Architecture
57

58
The wrapt module is built around several key design patterns:
59

60
- **Transparent Proxies**: ObjectProxy provides seamless delegation to wrapped objects while allowing interception
61
- **Function Wrappers**: Specialized wrappers that handle method binding, descriptor protocol, and function metadata preservation
62
- **Universal Decorators**: The decorator function creates decorators that work correctly across functions, methods, and classes
63
- **Patching Framework**: Comprehensive tools for monkey patching with proper cleanup and context management
64

65
## Capabilities
66

67
### Proxy Objects
68

69
Transparent proxy objects that wrap other objects and delegate operations while allowing interception and modification of behavior.
70

71
```python { .api }
72
class ObjectProxy:
73
    def __init__(self, wrapped): ...
74

75
class CallableObjectProxy(ObjectProxy):
76
    def __init__(self, wrapped): ...
77

78
class PartialCallableObjectProxy(ObjectProxy):
79
    def __init__(self, wrapped, *args, **kwargs): ...
80
```
81

82
[Proxy Objects](./proxy-objects.md)
83

84
### Function Wrappers
85

86
Specialized wrappers for functions that handle method binding, descriptor protocol, and function-specific behavior with proper signature preservation.
87

88
```python { .api }
89
class FunctionWrapper(ObjectProxy):
90
    def __init__(self, wrapped, wrapper, enabled=None): ...
91

92
class BoundFunctionWrapper:
93
    pass  # Created automatically by FunctionWrapper.__get__
94
```
95

96
[Function Wrappers](./function-wrappers.md)
97

98
### Patching and Monkey Patching
99

100
Comprehensive utilities for applying patches, wrapping objects, and monkey patching with proper cleanup and context management.
101

102
```python { .api }
103
def wrap_function_wrapper(module, name, wrapper): ...
104
def wrap_object(module, name, factory, args=(), kwargs={}): ...
105
def patch_function_wrapper(module, name, enabled=None): ...
106
def transient_function_wrapper(module, name): ...
107
```
108

109
[Patching and Monkey Patching](./patching.md)
110

111
### Decorator Creation
112

113
Universal decorator factory and synchronization utilities for creating robust decorators with proper signature preservation.
114

115
```python { .api }
116
def decorator(wrapper=None, enabled=None, adapter=None, proxy=FunctionWrapper): ...
117
def synchronized(wrapped): ...
118
class AdapterFactory: ...
119
```
120

121
[Decorator Creation](./decorators.md)
122

123
### Utilities
124

125
Import hooks, weak references, and utility functions for advanced wrapping scenarios and compatibility.
126

127
```python { .api }
128
class WeakFunctionProxy:
129
    def __init__(self, wrapped, callback=None): ...
130

131
def register_post_import_hook(hook, name): ...
132
def when_imported(name): ...
133
def formatargspec(args, varargs=None, varkw=None, defaults=None, **kwargs): ...
134
```
135

136
[Utilities](./utilities.md)
137

138
## Version Information
139

140
```python { .api }
141
__version__: str = "1.17.3"
142
__version_info__: tuple = ('1', '17', '3')
143
```
144

145
## Types
146

147
```python { .api }
148
# Core type aliases and interfaces  
149
from typing import Callable, Any, Optional, Union
150

151
WrapperFunction = Callable[[Any, Optional[object], tuple, dict], Any]
152
# Signature: (wrapped, instance, args, kwargs) -> result
153

154
AdapterFunction = Callable[[Any], Any]  
155
# Function used for signature adaptation
156

157
EnabledFunction = Callable[[], bool]
158
# Function returning boolean for enable/disable logic
159

160
CallbackFunction = Callable[[Any], None]
161
# Callback function for weak reference expiration
162

163
HookFunction = Union[Callable[[Any], None], str]
164
# Hook function or string in format 'module:function'
165
```