22 __all__ = [
'deprecate_pybind11',
'suppress_deprecations']
24 import deprecated.sphinx
29 from contextlib
import contextmanager
33 """Deprecate a pybind11-wrapped C++ interface function, method or class.
35 This needs to use a pass-through Python wrapper so that
36 `~deprecated.sphinx.deprecated` can update its docstring; pybind11
37 docstrings are native and cannot be modified.
39 Note that this is not a decorator; its output must be assigned to
40 replace the method being deprecated.
44 obj : function, method, or class
45 The function, method, or class to deprecate.
47 Reason for deprecation, passed to `~deprecated.sphinx.deprecated`
49 Next major version in which the interface will be deprecated,
50 passed to `~deprecated.sphinx.deprecated`
52 Warning category, passed to `~deprecated.sphinx.deprecated`
56 obj : function, method, or class
57 Wrapped function, method, or class
61 .. code-block:: python
63 ExposureF.getCalib = deprecate_pybind11(ExposureF.getCalib,
64 reason="Replaced by getPhotoCalib. (Will be removed in 18.0)",
65 version="17.0", category=FutureWarning))
69 def internal(*args, **kwargs):
70 return obj(*args, **kwargs)
72 return deprecated.sphinx.deprecated(
75 category=category)(internal)
80 """Suppress warnings generated by `deprecated.sphinx.deprecated`.
82 Naively, one might attempt to suppress these warnings by using
83 `~warnings.catch_warnings`. However, `~deprecated.sphinx.deprecated`
84 attempts to install its own filter, overriding that. This convenience
85 method works around this and properly suppresses the warnings by providing
86 a mock `~warnings.simplefilter` for `~deprecated.sphinx.deprecated` to
91 category : `Warning` or subclass
92 The category of warning to suppress.
94 with warnings.catch_warnings():
95 warnings.simplefilter(
"ignore", category)
96 with unittest.mock.patch.object(warnings,
"simplefilter"):