0
# Deprecated
1
2
Python `@deprecated` decorator to deprecate old python classes, functions or methods. This library provides comprehensive deprecation functionality with both simple warning-based decorators and advanced Sphinx integration for automatic documentation generation.
3
4
## Package Information
5
6
- **Package Name**: Deprecated
7
- **Language**: Python
8
- **Installation**: `pip install Deprecated`
9
- **Python Version**: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*
10
- **Dependencies**: wrapt < 2, >= 1.10
11
12
## Core Imports
13
14
Basic deprecation decorator:
15
16
```python
17
from deprecated import deprecated
18
```
19
20
Sphinx integration with documentation directives:
21
22
```python
23
from deprecated.sphinx import deprecated, versionadded, versionchanged
24
```
25
26
Advanced usage with custom adapters:
27
28
```python
29
from deprecated.classic import deprecated, ClassicAdapter
30
from deprecated.sphinx import SphinxAdapter
31
```
32
33
Warning types for custom categories (from Python's warnings module):
34
35
```python
36
from warnings import DeprecationWarning, FutureWarning, PendingDeprecationWarning
37
```
38
39
## Basic Usage
40
41
### Simple Deprecation
42
43
```python
44
from deprecated import deprecated
45
46
@deprecated
47
def some_old_function(x, y):
48
return x + y
49
50
@deprecated
51
class SomeOldClass:
52
pass
53
54
class SomeClass:
55
@deprecated
56
def some_old_method(self, x, y):
57
return x + y
58
```
59
60
### Deprecation with Details
61
62
```python
63
from deprecated import deprecated
64
65
@deprecated(reason="use another function", version='1.2.0')
66
def some_old_function(x, y):
67
return x + y
68
69
@deprecated(reason="This method is deprecated", version='1.3.0')
70
def some_old_method(self, x, y):
71
return x + y
72
```
73
74
### Sphinx Integration
75
76
```python
77
from deprecated.sphinx import deprecated, versionadded, versionchanged
78
79
@versionadded(version='1.0', reason="This function is new")
80
def new_function():
81
'''This function was added in version 1.0'''
82
83
@versionchanged(version='1.1', reason="This function behavior changed")
84
def modified_function():
85
'''This function was modified in version 1.1'''
86
87
@deprecated(version='1.2', reason="This function will be removed soon")
88
def old_function():
89
'''This function is deprecated as of version 1.2'''
90
```
91
92
## Capabilities
93
94
### Classic Deprecation Decorator
95
96
Simple deprecation decorator that emits DeprecationWarning when decorated functions, methods, or classes are used.
97
98
```python { .api }
99
def deprecated(*args, **kwargs):
100
"""
101
Decorator to mark functions, methods, or classes as deprecated.
102
103
Parameters:
104
- reason (str, optional): Reason message for deprecation
105
- version (str, optional): Version when deprecated
106
- action (str, optional): Warning filter action ("default", "error", "ignore", "always", "module", "once")
107
- category (Type[Warning], optional): Warning category class (default: DeprecationWarning)
108
- adapter_cls (Type, optional): Custom adapter class (default: ClassicAdapter)
109
- extra_stacklevel (int, optional): Additional stack levels for warnings (default: 0)
110
111
Returns:
112
Decorated function, method, or class
113
"""
114
```
115
116
Usage patterns:
117
- `@deprecated` - Simple deprecation
118
- `@deprecated("reason message")` - With reason string as positional argument
119
- `@deprecated(reason="...", version="1.2.3")` - With named parameters
120
- `@deprecated(action="error")` - With warning control
121
122
**Note**: The `@deprecated("reason")` syntax works because the function automatically
123
detects when the first argument is a string and treats it as the reason parameter.
124
125
### Classic Adapter
126
127
Base adapter class for implementing custom deprecation message formatting.
128
129
```python { .api }
130
class ClassicAdapter:
131
def __init__(self, reason="", version="", action=None, category=DeprecationWarning, extra_stacklevel=0):
132
"""
133
Construct a wrapper adapter.
134
135
Parameters:
136
- reason (str): Reason message for deprecation
137
- version (str): Version when deprecated
138
- action (str): Warning filter action
139
- category (Type[Warning]): Warning category class
140
- extra_stacklevel (int): Additional stack levels for warnings
141
"""
142
143
def get_deprecated_msg(self, wrapped, instance):
144
"""
145
Get the deprecation warning message for the user.
146
147
Parameters:
148
- wrapped: Wrapped class or function
149
- instance: The object to which the wrapped function was bound
150
151
Returns:
152
str: The warning message
153
"""
154
155
def __call__(self, wrapped):
156
"""
157
Decorate your class or function.
158
159
Parameters:
160
- wrapped: Wrapped class or function
161
162
Returns:
163
The decorated class or function
164
"""
165
```
166
167
### Sphinx Documentation Integration
168
169
Decorators that add Sphinx directives to docstrings for automatic documentation generation.
170
171
```python { .api }
172
def versionadded(reason="", version="", line_length=70):
173
"""
174
Insert a "versionadded" directive in docstring.
175
176
Parameters:
177
- reason (str): Reason message documenting the addition
178
- version (str): Version when added (required)
179
- line_length (int): Max line length for directive text (default: 70)
180
181
Returns:
182
SphinxAdapter: Decorator adapter that modifies docstring when applied
183
"""
184
185
def versionchanged(reason="", version="", line_length=70):
186
"""
187
Insert a "versionchanged" directive in docstring.
188
189
Parameters:
190
- reason (str): Reason message documenting the modification
191
- version (str): Version when changed (required)
192
- line_length (int): Max line length for directive text (default: 70)
193
194
Returns:
195
SphinxAdapter: Decorator adapter that modifies docstring when applied
196
"""
197
198
def deprecated(reason="", version="", line_length=70, **kwargs):
199
"""
200
Insert a "deprecated" directive in docstring and emit deprecation warning.
201
202
Parameters:
203
- reason (str): Reason message documenting the deprecation
204
- version (str): Version when deprecated (required for Sphinx directives)
205
- line_length (int): Max line length for directive text (default: 70)
206
- **kwargs: Additional keyword arguments:
207
- action (str): Warning filter action
208
- category (Type[Warning]): Warning category
209
- extra_stacklevel (int): Additional stack levels
210
- directive (str): Override directive type (default: "deprecated")
211
- adapter_cls (Type): Override adapter class (default: SphinxAdapter)
212
213
Returns:
214
Callable: Decorator function that applies SphinxAdapter with deprecation warning
215
216
Raises:
217
- ValueError: If version parameter is not provided (required for Sphinx directives)
218
"""
219
```
220
221
### Sphinx Adapter
222
223
Advanced adapter that extends ClassicAdapter to add Sphinx directives to docstrings.
224
225
```python { .api }
226
class SphinxAdapter(ClassicAdapter):
227
def __init__(self, directive, reason="", version="", action=None, category=DeprecationWarning, extra_stacklevel=0, line_length=70):
228
"""
229
Construct a Sphinx wrapper adapter.
230
231
Parameters:
232
- directive (str): Sphinx directive ("versionadded", "versionchanged", "deprecated")
233
- reason (str): Reason message
234
- version (str): Version (required - cannot be empty for Sphinx directives)
235
- action (str): Warning filter action
236
- category (Type[Warning]): Warning category (must be imported from warnings)
237
- extra_stacklevel (int): Additional stack levels
238
- line_length (int): Max line length for directive text (default: 70)
239
240
Raises:
241
- ValueError: If version parameter is empty or not provided
242
"""
243
244
def get_deprecated_msg(self, wrapped, instance):
245
"""
246
Get deprecation warning message with Sphinx cross-referencing syntax stripped.
247
248
This method first calls the parent ClassicAdapter.get_deprecated_msg() to get
249
the base warning message, then uses regex to strip Sphinx cross-reference
250
syntax (like :role:`foo` and :domain:role:`foo`) for cleaner warnings.
251
252
Parameters:
253
- wrapped: Wrapped class or function
254
- instance: The object to which the wrapped function was bound
255
256
Returns:
257
str: The warning message with Sphinx cross-reference syntax removed
258
"""
259
260
def __call__(self, wrapped):
261
"""
262
Add Sphinx directive to docstring and decorate class or function.
263
264
Parameters:
265
- wrapped: Wrapped class or function
266
267
Returns:
268
The decorated class or function with modified docstring
269
"""
270
```
271
272
## Advanced Usage Examples
273
274
### Custom Adapter
275
276
```python
277
import inspect
278
from deprecated.classic import ClassicAdapter, deprecated
279
280
class MyClassicAdapter(ClassicAdapter):
281
def get_deprecated_msg(self, wrapped, instance):
282
if instance is None:
283
if inspect.isclass(wrapped):
284
fmt = "The class {name} is deprecated."
285
else:
286
fmt = "The function {name} is deprecated."
287
else:
288
if inspect.isclass(instance):
289
fmt = "The class method {name} is deprecated."
290
else:
291
fmt = "The method {name} is deprecated."
292
if self.reason:
293
fmt += " ({reason})"
294
if self.version:
295
fmt += " -- Deprecated since version {version}."
296
return fmt.format(name=wrapped.__name__,
297
reason=self.reason or "",
298
version=self.version or "")
299
300
@deprecated(reason="use another function", adapter_cls=MyClassicAdapter)
301
def some_old_function(x, y):
302
return x + y
303
```
304
305
### Warning Control
306
307
```python
308
from deprecated import deprecated
309
310
# Raise error instead of warning
311
@deprecated(action="error")
312
def critical_old_function():
313
pass
314
315
# Ignore deprecation warnings
316
@deprecated(action="ignore")
317
def silent_old_function():
318
pass
319
320
# Show warning once per module
321
@deprecated(action="once")
322
def one_time_warning_function():
323
pass
324
```
325
326
### Custom Warning Categories
327
328
```python
329
from deprecated import deprecated
330
from warnings import DeprecationWarning, FutureWarning, PendingDeprecationWarning
331
332
class MyDeprecationWarning(DeprecationWarning):
333
pass
334
335
@deprecated(category=MyDeprecationWarning)
336
def function_with_custom_warning():
337
pass
338
339
# Can also use built-in warning types
340
@deprecated(category=FutureWarning)
341
def function_with_future_warning():
342
pass
343
344
@deprecated(category=PendingDeprecationWarning)
345
def function_with_pending_warning():
346
pass
347
```
348
349
### Stack Level Control
350
351
```python
352
from deprecated import deprecated
353
354
def wrapper_function():
355
@deprecated(extra_stacklevel=1)
356
def inner_function():
357
pass
358
return inner_function
359
360
# The warning will point to the caller of wrapper_function
361
# instead of the call to inner_function
362
```
363
364
## Error Handling
365
366
The decorators may raise the following exceptions:
367
368
- **ValueError**: When required parameters are missing (e.g., version parameter required for Sphinx directives)
369
- **TypeError**: When decorator is applied to unsupported object types (non-callable, non-class objects)
370
371
The decorated functions emit warnings of the specified category:
372
373
- **DeprecationWarning**: Default warning category for deprecated functionality (must be imported from warnings module)
374
- **FutureWarning**: Alternative warning category for future deprecations
375
- **PendingDeprecationWarning**: For deprecations that are not yet active
376
- **Custom Warning Categories**: User-defined warning classes for specialized handling
377
378
## Types
379
380
```python { .api }
381
# Warning filter actions
382
ActionType = Literal["default", "error", "ignore", "always", "module", "once"]
383
384
# Sphinx directive types
385
DirectiveType = Literal["versionadded", "versionchanged", "deprecated"]
386
387
# Base adapter interface
388
class AdapterProtocol:
389
def __init__(self, reason: str = "", version: str = "", action: ActionType = None,
390
category: Type[Warning] = DeprecationWarning, extra_stacklevel: int = 0): ...
391
def get_deprecated_msg(self, wrapped: Callable, instance: Any) -> str: ...
392
def __call__(self, wrapped: Callable) -> Callable: ...
393
```