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, 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 category : `Warning` 

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

50 

51 Returns 

52 ------- 

53 obj : function, method, or class 

54 Wrapped function, method, or class 

55 

56 Examples 

57 -------- 

58 .. code-block:: python 

59 

60 ExposureF.getCalib = deprecate_pybind11(ExposureF.getCalib, 

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

62 category=FutureWarning)) 

63 """ 

64 

65 @functools.wraps(obj) 

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

67 return obj(*args, **kwargs) 

68 

69 return deprecated.sphinx.deprecated(reason=reason, category=category)(internal) 

70 

71 

72@contextmanager 

73def suppress_deprecations(category=FutureWarning): 

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

75 

76 Naively, one might attempt to suppress these warnings by using 

77 `~warnings.catch_warnings`. However, `~deprecated.sphinx.deprecated` 

78 attempts to install its own filter, overriding that. This convenience 

79 method works around this and properly suppresses the warnings by providing 

80 a mock `~warnings.simplefilter` for `~deprecated.sphinx.deprecated` to 

81 call. 

82 

83 Parameters 

84 ---------- 

85 category : `Warning` or subclass 

86 The category of warning to suppress. 

87 """ 

88 with warnings.catch_warnings(): 

89 warnings.simplefilter("ignore", category) 

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

91 yield