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
```