Coverage for pyTooling/Decorators/__init__.py: 85%

1# ==================================================================================================================== # 

2# _____ _ _ ____ _ # 

3# _ __ _ |_ _|__ ___ | (_)_ __ __ _ | _ \ ___ ___ ___ _ __ __ _| |_ ___ _ __ ___ # 

4# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` | | | | |/ _ \/ __/ _ \| '__/ _` | __/ _ \| '__/ __| # 

5# | |_) | |_| || | (_) | (_) | | | | | | (_| |_| |_| | __/ (_| (_) | | | (_| | || (_) | | \__ \ # 

6# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____/ \___|\___\___/|_| \__,_|\__\___/|_| |___/ # 

7# |_| |___/ |___/ # 

8# ==================================================================================================================== # 

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

13# ==================================================================================================================== # 

14# Copyright 2017-2025 Patrick Lehmann - Bötzingen, Germany # 

15# # 

16# Licensed under the Apache License, Version 2.0 (the "License"); # 

17# you may not use this file except in compliance with the License. # 

18# You may obtain a copy of the License at # 

19# # 

20# http://www.apache.org/licenses/LICENSE-2.0 # 

21# # 

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

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

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

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

26# limitations under the License. # 

27# # 

28# SPDX-License-Identifier: Apache-2.0 # 

29# ==================================================================================================================== # 

30# 

31"""Decorators controlling visibility of entities in a Python module. 

32 

33.. hint:: See :ref:`high-level help <DECO>` for explanations and usage examples. 

34""" 

35import sys 

36from functools import wraps 

37from types import FunctionType 

38from typing import Union, Type, TypeVar, Callable, Any, Optional as Nullable 

39 

40__all__ = ["export", "Param", "RetType", "Func", "T"] 

41 

42 

43try: 

44 # See https://stackoverflow.com/questions/47060133/python-3-type-hinting-for-decorator 

45 from typing import ParamSpec # WORKAROUND: exists since Python 3.10 

46 

47 Param = ParamSpec("Param") #: A parameter specification for function or method 

48 RetType = TypeVar("RetType") #: Type variable for a return type 

49 Func = Callable[Param, RetType] #: Type specification for a function 

50except ImportError: # pragma: no cover 

51 Param = ... #: A parameter specification for function or method 

52 RetType = TypeVar("RetType") #: Type variable for a return type 

53 Func = Callable[..., RetType] #: Type specification for a function 

54 

55 

56T = TypeVar("T", bound=Union[Type, FunctionType]) #: A type variable for a classes or functions. 

57C = TypeVar("C", bound=Callable) #: A type variable for functions or methods. 

58 

59 

60def export(entity: T) -> T: 

61 """ 

62 Register the given function or class as publicly accessible in a module. 

63 

64 Creates or updates the ``__all__`` attribute in the module in which the decorated entity is defined to include the 

65 name of the decorated entity. 

66 

67 +---------------------------------------------+------------------------------------------------+ 

68 | ``to_export.py`` | ``another_file.py`` | 

69 +=============================================+================================================+ 

70 | .. code-block:: python | .. code-block:: python | 

71 | | | 

72 | from pyTooling.Decorators import export | from .to_export import * | 

73 | | | 

74 | @export | | 

75 | def exported(): | # 'exported' will be listed in __all__ | 

76 | pass | assert "exported" in globals() | 

77 | | | 

78 | def not_exported(): | # 'not_exported' won't be listed in __all__ | 

79 | pass | assert "not_exported" not in globals() | 

80 | | | 

81 +---------------------------------------------+------------------------------------------------+ 

82 

83 :param entity: The function or class to include in `__all__`. 

84 :returns: The unmodified function or class. 

85 :raises AttributeError: If parameter ``entity`` has no ``__module__`` member. 

86 :raises TypeError: If parameter ``entity`` is not a top-level entity in a module. 

87 :raises TypeError: If parameter ``entity`` has no ``__name__``. 

88 """ 

89 # * Based on an idea by Duncan Booth: 

90 # http://groups.google.com/group/comp.lang.python/msg/11cbb03e09611b8a 

91 # * Improved via a suggestion by Dave Angel: 

92 # http://groups.google.com/group/comp.lang.python/msg/3d400fb22d8a42e1 

93 

94 if not hasattr(entity, "__module__"): 94 ↛ 95line 94 didn't jump to line 95 because the condition on line 94 was never true

95 raise AttributeError(f"{entity} has no __module__ attribute. Please ensure it is a top-level function or class reference defined in a module.") 

96 

97 if hasattr(entity, "__qualname__"): 97 ↛ 101line 97 didn't jump to line 101 because the condition on line 97 was always true

98 if any(i in entity.__qualname__ for i in (".", "<locals>", "<lambda>")): 

99 raise TypeError(f"Only named top-level functions and classes may be exported, not {entity}") 

100 

101 if not hasattr(entity, "__name__") or entity.__name__ == "<lambda>": 101 ↛ 102line 101 didn't jump to line 102 because the condition on line 101 was never true

102 raise TypeError(f"Entity must be a named top-level function or class, not {entity.__class__}") 

103 

104 try: 

105 module = sys.modules[entity.__module__] 

106 except KeyError: 

107 raise ValueError(f"Module {entity.__module__} is not present in sys.modules. Please ensure it is in the import path before calling export().") 

108 

109 if hasattr(module, "__all__"): 

110 if entity.__name__ not in module.__all__: # type: ignore 110 ↛ 115line 110 didn't jump to line 115 because the condition on line 110 was always true

111 module.__all__.append(entity.__name__) # type: ignore 

112 else: 

113 module.__all__ = [entity.__name__] # type: ignore 

114 

115 return entity 

116 

117 

118@export 

119def notimplemented(message: str) -> Callable: 

120 """ 

121 Mark a method as *not implemented* and replace the implementation with a new method raising a :exc:`NotImplementedError`. 

122 

123 The original method is stored in ``<method>.__wrapped__`` and it's doc-string is copied to the replacing method. In 

124 additional the field ``<method>.__notImplemented__`` is added. 

125 

126 .. admonition:: ``example.py`` 

127 

128 .. code-block:: python 

129 

130 class Data: 

131 @notimplemented 

132 def method(self) -> bool: 

133 '''This method needs to be implemented''' 

134 return True 

135 

136 :param method: Method that is marked as *not implemented*. 

137 :returns: Replacement method, which raises a :exc:`NotImplementedError`. 

138 

139 .. seealso:: 

140 

141 * :func:`~pyTooling.Metaclasses.abstractmethod` 

142 * :func:`~pyTooling.Metaclasses.mustoverride` 

143 """ 

144 

145 def decorator(method: C) -> C: 

146 @wraps(method) 

147 def func(*_, **__): 

148 raise NotImplementedError(message) 

149 

150 func.__notImplemented__ = True 

151 return func 

152 

153 return decorator 

154 

155 

156@export 

157def readonly(func: Callable) -> property: 

158 """ 

159 Marks a property as *read-only*. 

160 

161 The doc-string will be taken from the getter-function. 

162 

163 It will remove ``<property>.setter`` and ``<property>.deleter`` from the property descriptor. 

164 

165 :param func: Function to convert to a read-only property. 

166 :returns: A property object with just a getter. 

167 

168 .. seealso:: 

169 

170 :class:`property` 

171 A decorator to convert getter, setter and deleter methods into a property applying the descriptor protocol. 

172 """ 

173 prop = property(fget=func, fset=None, fdel=None, doc=func.__doc__) 

174 

175 return prop 

176 

177 

178@export 

179def InheritDocString(baseClass: type, merge: bool = False) -> Callable[[Union[Func, type]], Union[Func, type]]: 

180 """ 

181 Copy the doc-string from given base-class to the method this decorator is applied to. 

182 

183 .. admonition:: ``example.py`` 

184 

185 .. code-block:: python 

186 

187 from pyTooling.Decorators import InheritDocString 

188 

189 class Class1: 

190 def method(self): 

191 '''Method's doc-string.''' 

192 

193 class Class2(Class1): 

194 @InheritDocString(Class1) 

195 def method(self): 

196 super().method() 

197 

198 :param baseClass: Base-class to copy the doc-string from to the new method being decorated. 

199 :returns: Decorator function that copies the doc-string. 

200 """ 

201 def decorator(param: Union[Func, type]) -> Union[Func, type]: 

202 """ 

203 Decorator function, which copies the doc-string from base-class' method to method ``m``. 

204 

205 :param param: Method to which the doc-string from a method in ``baseClass`` (with same className) should be copied. 

206 :returns: Same method, but with overwritten doc-string field (``__doc__``). 

207 """ 

208 if isinstance(param, type): 

209 baseDoc = baseClass.__doc__ 

210 elif callable(param): 210 ↛ 213line 210 didn't jump to line 213 because the condition on line 210 was always true

211 baseDoc = getattr(baseClass, param.__name__).__doc__ 

212 else: 

213 return param 

214 

215 if merge: 

216 if param.__doc__ is None: 216 ↛ 217line 216 didn't jump to line 217 because the condition on line 216 was never true

217 param.__doc__ = baseDoc 

218 elif baseDoc is not None: 

219 param.__doc__ = baseDoc + "\n\n" + param.__doc__ 

220 else: 

221 param.__doc__ = baseDoc 

222 

223 return param 

224 

225 return decorator