Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/git/compat.py: 64%

1# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors 

2# 

3# This module is part of GitPython and is released under the 

4# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ 

5 

6"""Utilities to help provide compatibility with Python 3. 

7 

8This module exists for historical reasons. Code outside GitPython may make use of public 

9members of this module, but is unlikely to benefit from doing so. GitPython continues to 

10use some of these utilities, in some cases for compatibility across different platforms. 

11""" 

12 

13import locale 

14import os 

15import sys 

16import warnings 

17 

18from gitdb.utils.encoding import force_bytes, force_text # noqa: F401 

19 

20# typing -------------------------------------------------------------------- 

21 

22from typing import ( 

23 Any, # noqa: F401 

24 AnyStr, 

25 Dict, # noqa: F401 

26 IO, # noqa: F401 

27 List, 

28 Optional, 

29 TYPE_CHECKING, 

30 Tuple, # noqa: F401 

31 Type, # noqa: F401 

32 Union, 

33 overload, 

34) 

35 

36# --------------------------------------------------------------------------- 

37 

38 

39_deprecated_platform_aliases = { 

40 "is_win": os.name == "nt", 

41 "is_posix": os.name == "posix", 

42 "is_darwin": sys.platform == "darwin", 

43} 

44 

45 

46def _getattr(name: str) -> Any: 

47 try: 

48 value = _deprecated_platform_aliases[name] 

49 except KeyError: 

50 raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None 

51 

52 warnings.warn( 

53 f"{__name__}.{name} and other is_<platform> aliases are deprecated. " 

54 "Write the desired os.name or sys.platform check explicitly instead.", 

55 DeprecationWarning, 

56 stacklevel=2, 

57 ) 

58 return value 

59 

60 

61if not TYPE_CHECKING: # Preserve static checking for undefined/misspelled attributes. 

62 __getattr__ = _getattr 

63 

64 

65def __dir__() -> List[str]: 

66 return [*globals(), *_deprecated_platform_aliases] 

67 

68 

69is_win: bool 

70"""Deprecated alias for ``os.name == "nt"`` to check for native Windows. 

71 

72This is deprecated because it is clearer to write out :attr:`os.name` or 

73:attr:`sys.platform` checks explicitly, especially in cases where it matters which is 

74used. 

75 

76:note: 

77 ``is_win`` is ``False`` on Cygwin, but is often wrongly assumed ``True``. To detect 

78 Cygwin, use ``sys.platform == "cygwin"``. 

79""" 

80 

81is_posix: bool 

82"""Deprecated alias for ``os.name == "posix"`` to check for Unix-like ("POSIX") systems. 

83 

84This is deprecated because it clearer to write out :attr:`os.name` or 

85:attr:`sys.platform` checks explicitly, especially in cases where it matters which is 

86used. 

87 

88:note: 

89 For POSIX systems, more detailed information is available in :attr:`sys.platform`, 

90 while :attr:`os.name` is always ``"posix"`` on such systems, including macOS 

91 (Darwin). 

92""" 

93 

94is_darwin: bool 

95"""Deprecated alias for ``sys.platform == "darwin"`` to check for macOS (Darwin). 

96 

97This is deprecated because it clearer to write out :attr:`os.name` or 

98:attr:`sys.platform` checks explicitly. 

99 

100:note: 

101 For macOS (Darwin), ``os.name == "posix"`` as in other Unix-like systems, while 

102 ``sys.platform == "darwin"``. 

103""" 

104 

105defenc = sys.getfilesystemencoding() 

106"""The encoding used to convert between Unicode and bytes filenames.""" 

107 

108 

109@overload 

110def safe_decode(s: None) -> None: ... 

111 

112 

113@overload 

114def safe_decode(s: AnyStr) -> str: ... 

115 

116 

117def safe_decode(s: Union[AnyStr, None]) -> Optional[str]: 

118 """Safely decode a binary string to Unicode.""" 

119 if isinstance(s, str): 

120 return s 

121 elif isinstance(s, bytes): 

122 return s.decode(defenc, "surrogateescape") 

123 elif s is None: 

124 return None 

125 else: 

126 raise TypeError("Expected bytes or text, but got %r" % (s,)) 

127 

128 

129@overload 

130def safe_encode(s: None) -> None: ... 

131 

132 

133@overload 

134def safe_encode(s: AnyStr) -> bytes: ... 

135 

136 

137def safe_encode(s: Optional[AnyStr]) -> Optional[bytes]: 

138 """Safely encode a binary string to Unicode.""" 

139 if isinstance(s, str): 

140 return s.encode(defenc) 

141 elif isinstance(s, bytes): 

142 return s 

143 elif s is None: 

144 return None 

145 else: 

146 raise TypeError("Expected bytes or text, but got %r" % (s,)) 

147 

148 

149@overload 

150def win_encode(s: None) -> None: ... 

151 

152 

153@overload 

154def win_encode(s: AnyStr) -> bytes: ... 

155 

156 

157def win_encode(s: Optional[AnyStr]) -> Optional[bytes]: 

158 """Encode Unicode strings for process arguments on Windows.""" 

159 if isinstance(s, str): 

160 return s.encode(locale.getpreferredencoding(False)) 

161 elif isinstance(s, bytes): 

162 return s 

163 elif s is not None: 

164 raise TypeError("Expected bytes or text, but got %r" % (s,)) 

165 return None