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-2026 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:: 

34 

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

36""" 

37import sys 

38from functools import wraps 

39from types import FunctionType 

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

41 

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

43 

44 

45try: 

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

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

48 

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

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

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

52except ImportError: # pragma: no cover 

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

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

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

56 

57 

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

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

60 

61 

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

63 """ 

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

65 

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

67 name of the decorated entity. 

68 

69 +---------------------------------------------+------------------------------------------------+ 

70 | ``to_export.py`` | ``another_file.py`` | 

71 +=============================================+================================================+ 

72 | .. code-block:: python | .. code-block:: python | 

73 | | | 

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

75 | | | 

76 | @export | | 

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

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

79 | | | 

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

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

82 | | | 

83 +---------------------------------------------+------------------------------------------------+ 

84 

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

86 :returns: The unmodified function or class. 

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

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

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

90 """ 

91 # * Based on an idea by Duncan Booth: 

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

93 # * Improved via a suggestion by Dave Angel: 

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

95 

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

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

98 

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

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

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

102 

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

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

105 

106 try: 

107 module = sys.modules[entity.__module__] 

108 except KeyError: 

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

110 

111 if hasattr(module, "__all__"): 

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

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

114 else: 

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

116 

117 return entity 

118 

119 

120@export 

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

122 """ 

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

124 

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

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

127 

128 .. admonition:: ``example.py`` 

129 

130 .. code-block:: python 

131 

132 class Data: 

133 @notimplemented 

134 def method(self) -> bool: 

135 '''This method needs to be implemented''' 

136 return True 

137 

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

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

140 

141 .. seealso:: 

142 

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

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

145 """ 

146 

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

148 @wraps(method) 

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

150 raise NotImplementedError(message) 

151 

152 func.__notImplemented__ = True 

153 return func 

154 

155 return decorator 

156 

157 

158@export 

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

160 """ 

161 Marks a property as *read-only*. 

162 

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

164 

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

166 

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

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

169 

170 .. seealso:: 

171 

172 :class:`property` 

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

174 """ 

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

176 

177 return prop 

178 

179 

180@export 

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

182 """ 

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

184 

185 .. admonition:: ``example.py`` 

186 

187 .. code-block:: python 

188 

189 from pyTooling.Decorators import InheritDocString 

190 

191 class Class1: 

192 def method(self): 

193 '''Method's doc-string.''' 

194 

195 class Class2(Class1): 

196 @InheritDocString(Class1) 

197 def method(self): 

198 super().method() 

199 

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

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

202 """ 

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

204 """ 

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

206 

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

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

209 """ 

210 if isinstance(param, type): 

211 baseDoc = baseClass.__doc__ 

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

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

214 else: 

215 return param 

216 

217 if merge: 

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

219 param.__doc__ = baseDoc 

220 elif baseDoc is not None: 

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

222 else: 

223 param.__doc__ = baseDoc 

224 

225 return param 

226 

227 return decorator