Coverage for Lib/abc.py: 51%

1# Copyright 2007 Google, Inc. All Rights Reserved. 

2# Licensed to PSF under a Contributor Agreement. 

3 

4"""Abstract Base Classes (ABCs) according to PEP 3119.""" 

5 

6 

7def abstractmethod(funcobj): 

8 """A decorator indicating abstract methods. 

9 

10 Requires that the metaclass is ABCMeta or derived from it. A 

11 class that has a metaclass derived from ABCMeta cannot be 

12 instantiated unless all of its abstract methods are overridden. 

13 The abstract methods can be called using any of the normal 

14 'super' call mechanisms. abstractmethod() may be used to declare 

15 abstract methods for properties and descriptors. 

16 

17 Usage: 

18 

19 class C(metaclass=ABCMeta): 

20 @abstractmethod 

21 def my_abstract_method(self, arg1, arg2, argN): 

22 ... 

23 """ 

24 funcobj.__isabstractmethod__ = True 

25 return funcobj 

26 

27 

28class abstractclassmethod(classmethod): 

29 """A decorator indicating abstract classmethods. 

30 

31 Deprecated, use 'classmethod' with 'abstractmethod' instead: 

32 

33 class C(ABC): 

34 @classmethod 

35 @abstractmethod 

36 def my_abstract_classmethod(cls, ...): 

37 ... 

38 

39 """ 

40 

41 __isabstractmethod__ = True 

42 

43 def __init__(self, callable): 

44 callable.__isabstractmethod__ = True 

45 super().__init__(callable) 

46 

47 

48class abstractstaticmethod(staticmethod): 

49 """A decorator indicating abstract staticmethods. 

50 

51 Deprecated, use 'staticmethod' with 'abstractmethod' instead: 

52 

53 class C(ABC): 

54 @staticmethod 

55 @abstractmethod 

56 def my_abstract_staticmethod(...): 

57 ... 

58 

59 """ 

60 

61 __isabstractmethod__ = True 

62 

63 def __init__(self, callable): 

64 callable.__isabstractmethod__ = True 

65 super().__init__(callable) 

66 

67 

68class abstractproperty(property): 

69 """A decorator indicating abstract properties. 

70 

71 Deprecated, use 'property' with 'abstractmethod' instead: 

72 

73 class C(ABC): 

74 @property 

75 @abstractmethod 

76 def my_abstract_property(self): 

77 ... 

78 

79 """ 

80 

81 __isabstractmethod__ = True 

82 

83 

84try: 

85 from _abc import (get_cache_token, _abc_init, _abc_register, 

86 _abc_instancecheck, _abc_subclasscheck, _get_dump, 

87 _reset_registry, _reset_caches) 

88except ImportError: 

89 from _py_abc import ABCMeta, get_cache_token 

90 ABCMeta.__module__ = 'abc' 

91else: 

92 class ABCMeta(type): 

93 """Metaclass for defining Abstract Base Classes (ABCs). 

94 

95 Use this metaclass to create an ABC. An ABC can be subclassed 

96 directly, and then acts as a mix-in class. You can also register 

97 unrelated concrete classes (even built-in classes) and unrelated 

98 ABCs as 'virtual subclasses' -- these and their descendants will 

99 be considered subclasses of the registering ABC by the built-in 

100 issubclass() function, but the registering ABC won't show up in 

101 their MRO (Method Resolution Order) nor will method 

102 implementations defined by the registering ABC be callable (not 

103 even via super()). 

104 """ 

105 def __new__(mcls, name, bases, namespace, /, **kwargs): 

106 cls = super().__new__(mcls, name, bases, namespace, **kwargs) 

107 _abc_init(cls) 

108 return cls 

109 

110 def register(cls, subclass): 

111 """Register a virtual subclass of an ABC. 

112 

113 Returns the subclass, to allow usage as a class decorator. 

114 """ 

115 return _abc_register(cls, subclass) 

116 

117 def __instancecheck__(cls, instance): 

118 """Override for isinstance(instance, cls).""" 

119 return _abc_instancecheck(cls, instance) 

120 

121 def __subclasscheck__(cls, subclass): 

122 """Override for issubclass(subclass, cls).""" 

123 return _abc_subclasscheck(cls, subclass) 

124 

125 def _dump_registry(cls, file=None): 

126 """Debug helper to print the ABC registry.""" 

127 print(f"Class: {cls.__module__}.{cls.__qualname__}", file=file) 

128 print(f"Inv. counter: {get_cache_token()}", file=file) 

129 (_abc_registry, _abc_cache, _abc_negative_cache, 

130 _abc_negative_cache_version) = _get_dump(cls) 

131 print(f"_abc_registry: {_abc_registry!r}", file=file) 

132 print(f"_abc_cache: {_abc_cache!r}", file=file) 

133 print(f"_abc_negative_cache: {_abc_negative_cache!r}", file=file) 

134 print(f"_abc_negative_cache_version: {_abc_negative_cache_version!r}", 

135 file=file) 

136 

137 def _abc_registry_clear(cls): 

138 """Clear the registry (for debugging or testing).""" 

139 _reset_registry(cls) 

140 

141 def _abc_caches_clear(cls): 

142 """Clear the caches (for debugging or testing).""" 

143 _reset_caches(cls) 

144 

145 

146def update_abstractmethods(cls): 

147 """Recalculate the set of abstract methods of an abstract class. 

148 

149 If a class has had one of its abstract methods implemented after the 

150 class was created, the method will not be considered implemented until 

151 this function is called. Alternatively, if a new abstract method has been 

152 added to the class, it will only be considered an abstract method of the 

153 class after this function is called. 

154 

155 This function should be called before any use is made of the class, 

156 usually in class decorators that add methods to the subject class. 

157 

158 Returns cls, to allow usage as a class decorator. 

159 

160 If cls is not an instance of ABCMeta, does nothing. 

161 """ 

162 if not hasattr(cls, '__abstractmethods__'): 

163 # We check for __abstractmethods__ here because cls might by a C 

164 # implementation or a python implementation (especially during 

165 # testing), and we want to handle both cases. 

166 return cls 

167 

168 abstracts = set() 

169 # Check the existing abstract methods of the parents, keep only the ones 

170 # that are not implemented. 

171 for scls in cls.__bases__: 

172 for name in getattr(scls, '__abstractmethods__', ()): 

173 value = getattr(cls, name, None) 

174 if getattr(value, "__isabstractmethod__", False): 

175 abstracts.add(name) 

176 # Also add any other newly added abstract methods. 

177 for name, value in cls.__dict__.items(): 

178 if getattr(value, "__isabstractmethod__", False): 

179 abstracts.add(name) 

180 cls.__abstractmethods__ = frozenset(abstracts) 

181 return cls 

182 

183 

184class ABC(metaclass=ABCMeta): 

185 """Helper class that provides a standard way to create an ABC using 

186 inheritance. 

187 """ 

188 __slots__ = ()