lsst.utils  19.0.0-6-gea0b9bf
deprecated.py
Go to the documentation of this file.
1 # This file is part of lsst.utils.
2 #
3 # Developed for the LSST Data Management System.
4 # This product includes software developed by the LSST Project
5 # (https://www.lsst.org).
6 # See the COPYRIGHT file at the top-level directory of this distribution
7 # for details of code ownership.
8 #
9 # This program is free software: you can redistribute it and/or modify
10 # it under the terms of the GNU General Public License as published by
11 # the Free Software Foundation, either version 3 of the License, or
12 # (at your option) any later version.
13 #
14 # This program is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 # GNU General Public License for more details.
18 #
19 # You should have received a copy of the GNU General Public License
20 # along with this program. If not, see <https://www.gnu.org/licenses/>.
21 
22 import deprecated.sphinx
23 import functools
24 import unittest.mock
25 import warnings
26 
27 from contextlib import contextmanager
28 
29 
30 def deprecate_pybind11(obj, reason, category=FutureWarning):
31  """Deprecate a pybind11-wrapped C++ interface function, method or class.
32 
33  This needs to use a pass-through Python wrapper so that
34  `~deprecated.sphinx.deprecated` can update its docstring; pybind11
35  docstrings are native and cannot be modified.
36 
37  Note that this is not a decorator; its output must be assigned to
38  replace the method being deprecated.
39 
40  Parameters
41  ----------
42  obj : function, method, or class
43  The function, method, or class to deprecate.
44  reason : `str`
45  Reason for deprecation, passed to `~deprecated.sphinx.deprecated`
46  category : `Warning`
47  Warning category, passed to `~deprecated.sphinx.deprecated`
48 
49  Returns
50  -------
51  obj : function, method, or class
52  Wrapped function, method, or class
53 
54  Examples
55  --------
56  .. code-block:: python
57 
58  ExposureF.getCalib = deprecate_pybind11(ExposureF.getCalib,
59  reason="Replaced by getPhotoCalib. (Will be removed in 18.0)",
60  category=FutureWarning))
61  """
62 
63  @functools.wraps(obj)
64  def internal(*args, **kwargs):
65  return obj(*args, **kwargs)
66 
67  return deprecated.sphinx.deprecated(reason=reason, category=category)(internal)
68 
69 
70 @contextmanager
71 def suppress_deprecations(category=FutureWarning):
72  """Suppress warnings generated by `deprecated.sphinx.deprecated`.
73 
74  Naively, one might attempt to suppress these warnings by using
75  `~warnings.catch_warnings`. However, `~deprecated.sphinx.deprecated`
76  attempts to install its own filter, overriding that. This convenience
77  method works around this and properly suppresses the warnings by providing
78  a mock `~warnings.simplefilter` for `~deprecated.sphinx.deprecated` to
79  call.
80 
81  Parameters
82  ----------
83  category : `Warning` or subclass
84  The category of warning to suppress.
85  """
86  with warnings.catch_warnings():
87  warnings.simplefilter("ignore", category)
88  with unittest.mock.patch.object(warnings, "simplefilter"):
89  yield
def suppress_deprecations(category=FutureWarning)
Definition: deprecated.py:71
def deprecate_pybind11(obj, reason, category=FutureWarning)
Definition: deprecated.py:30