Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/dulwich/__init__.py: 43%

1# __init__.py -- The git module of dulwich 

2# Copyright (C) 2007 James Westby <jw+debian@jameswestby.net> 

3# Copyright (C) 2008 Jelmer Vernooij <jelmer@jelmer.uk> 

4# 

5# SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 

6# Dulwich is dual-licensed under the Apache License, Version 2.0 and the GNU 

7# General Public License as published by the Free Software Foundation; version 2.0 

8# or (at your option) any later version. You can redistribute it and/or 

9# modify it under the terms of either of these two licenses. 

10# 

11# Unless required by applicable law or agreed to in writing, software 

12# distributed under the License is distributed on an "AS IS" BASIS, 

13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

14# See the License for the specific language governing permissions and 

15# limitations under the License. 

16# 

17# You should have received a copy of the licenses; if not, see 

18# <http://www.gnu.org/licenses/> for a copy of the GNU General Public License 

19# and <http://www.apache.org/licenses/LICENSE-2.0> for a copy of the Apache 

20# License, Version 2.0. 

21# 

22 

23"""Python implementation of the Git file formats and protocols.""" 

24 

25from collections.abc import Callable 

26from typing import TYPE_CHECKING, Any, ParamSpec, TypeVar 

27 

28__version__ = (1, 2, 17) 

29 

30__all__ = ["__version__", "replace_me"] 

31 

32P = ParamSpec("P") 

33R = TypeVar("R") 

34F = TypeVar("F", bound=Callable[..., Any]) 

35 

36 

37def _deprecated_aliases( 

38 module_name: str, aliases: dict[str, str] 

39) -> Callable[[str], object]: 

40 """Create a module ``__getattr__`` that serves deprecated aliases. 

41 

42 Use it for names that have moved to another module but should remain 

43 importable from their old location for a while:: 

44 

45 __getattr__ = _deprecated_aliases( 

46 __name__, {"SHA1Writer": "dulwich.pack.SHA1Writer"} 

47 ) 

48 

49 Args: 

50 module_name: Name of the module the aliases live in 

51 aliases: Maps each old attribute name to the fully qualified name of 

52 its new location; the target is only imported on first access 

53 

54 Returns: 

55 A function suitable for use as a module level ``__getattr__`` 

56 """ 

57 

58 def __getattr__(name: str) -> object: 

59 try: 

60 target = aliases[name] 

61 except KeyError: 

62 raise AttributeError( 

63 f"module {module_name!r} has no attribute {name!r}" 

64 ) from None 

65 import importlib 

66 import warnings 

67 

68 warnings.warn( 

69 f"{module_name}.{name} is deprecated; use {target} instead", 

70 DeprecationWarning, 

71 stacklevel=2, 

72 ) 

73 target_module, _, target_name = target.rpartition(".") 

74 return getattr(importlib.import_module(target_module), target_name) 

75 

76 return __getattr__ 

77 

78 

79if TYPE_CHECKING: 

80 # For type checking, always use our typed signature 

81 def replace_me( 

82 since: tuple[int, ...] | str | None = None, 

83 remove_in: tuple[int, ...] | str | None = None, 

84 ) -> Callable[[Callable[P, R]], Callable[P, R]]: 

85 """Decorator to mark functions as deprecated.""" 

86 ... 

87 

88else: 

89 try: 

90 from dissolve import replace_me as replace_me 

91 except ImportError: 

92 # if dissolve is not installed, then just provide a basic implementation 

93 # of its replace_me decorator 

94 def replace_me( 

95 since: tuple[int, ...] | str | None = None, 

96 remove_in: tuple[int, ...] | str | None = None, 

97 ) -> Callable[[Callable[P, R]], Callable[P, R]]: 

98 """Decorator to mark functions as deprecated. 

99 

100 Args: 

101 since: Version when the function was deprecated 

102 remove_in: Version when the function will be removed 

103 

104 Returns: 

105 Decorator function 

106 """ 

107 

108 def decorator(func: Callable[P, R]) -> Callable[P, R]: 

109 import functools 

110 import warnings 

111 

112 m = f"{func.__name__} is deprecated" 

113 since_str = str(since) if since is not None else None 

114 remove_in_str = str(remove_in) if remove_in is not None else None 

115 

116 if since_str is not None and remove_in_str is not None: 

117 m += f" since {since_str} and will be removed in {remove_in_str}" 

118 elif since_str is not None: 

119 m += f" since {since_str}" 

120 elif remove_in_str is not None: 

121 m += f" and will be removed in {remove_in_str}" 

122 else: 

123 m += " and will be removed in a future version" 

124 

125 @functools.wraps(func) 

126 def _wrapped_func(*args: P.args, **kwargs: P.kwargs) -> R: 

127 warnings.warn( 

128 m, 

129 DeprecationWarning, 

130 stacklevel=2, 

131 ) 

132 return func(*args, **kwargs) 

133 

134 return _wrapped_func 

135 

136 return decorator