Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

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__all__ = ['deprecate_pybind11', 'suppress_deprecations'] 

23 

24import deprecated.sphinx 

25import functools 

26import unittest.mock 

27import warnings 

28 

29from contextlib import contextmanager 

30 

31 

32def deprecate_pybind11(obj, reason, version=None, category=FutureWarning): 

33 """Deprecate a pybind11-wrapped C++ interface function, method or class. 

34 

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. 

38 

39 Note that this is not a decorator; its output must be assigned to 

40 replace the method being deprecated. 

41 

42 Parameters 

43 ---------- 

44 obj : function, method, or class 

45 The function, method, or class to deprecate. 

46 reason : `str` 

47 Reason for deprecation, passed to `~deprecated.sphinx.deprecated` 

48 version : 'str' 

49 Next major version in which the interface will be deprecated, 

50 passed to `~deprecated.sphinx.deprecated` 

51 category : `Warning` 

52 Warning category, passed to `~deprecated.sphinx.deprecated` 

53 

54 Returns 

55 ------- 

56 obj : function, method, or class 

57 Wrapped function, method, or class 

58 

59 Examples 

60 -------- 

61 .. code-block:: python 

62 

63 ExposureF.getCalib = deprecate_pybind11(ExposureF.getCalib, 

64 reason="Replaced by getPhotoCalib. (Will be removed in 18.0)", 

65 version="17.0", category=FutureWarning)) 

66 """ 

67 

68 @functools.wraps(obj) 

69 def internal(*args, **kwargs): 

70 return obj(*args, **kwargs) 

71 

72 return deprecated.sphinx.deprecated( 

73 reason=reason, 

74 version=version, 

75 category=category)(internal) 

76 

77 

78@contextmanager 

79def suppress_deprecations(category=FutureWarning): 

80 """Suppress warnings generated by `deprecated.sphinx.deprecated`. 

81 

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 

87 call. 

88 

89 Parameters 

90 ---------- 

91 category : `Warning` or subclass 

92 The category of warning to suppress. 

93 """ 

94 with warnings.catch_warnings(): 

95 warnings.simplefilter("ignore", category) 

96 with unittest.mock.patch.object(warnings, "simplefilter"): 

97 yield