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 | import types |
---|
7 | |
---|
8 | from _weakrefset import WeakSet |
---|
9 | |
---|
10 | # Instance of old-style class |
---|
11 | class _C: pass |
---|
12 | _InstanceType = type(_C()) |
---|
13 | |
---|
14 | |
---|
15 | def abstractmethod(funcobj): |
---|
16 | """A decorator indicating abstract methods. |
---|
17 | |
---|
18 | Requires that the metaclass is ABCMeta or derived from it. A |
---|
19 | class that has a metaclass derived from ABCMeta cannot be |
---|
20 | instantiated unless all of its abstract methods are overridden. |
---|
21 | The abstract methods can be called using any of the normal |
---|
22 | 'super' call mechanisms. |
---|
23 | |
---|
24 | Usage: |
---|
25 | |
---|
26 | class C: |
---|
27 | __metaclass__ = ABCMeta |
---|
28 | @abstractmethod |
---|
29 | def my_abstract_method(self, ...): |
---|
30 | ... |
---|
31 | """ |
---|
32 | funcobj.__isabstractmethod__ = True |
---|
33 | return funcobj |
---|
34 | |
---|
35 | |
---|
36 | class abstractproperty(property): |
---|
37 | """A decorator indicating abstract properties. |
---|
38 | |
---|
39 | Requires that the metaclass is ABCMeta or derived from it. A |
---|
40 | class that has a metaclass derived from ABCMeta cannot be |
---|
41 | instantiated unless all of its abstract properties are overridden. |
---|
42 | The abstract properties can be called using any of the normal |
---|
43 | 'super' call mechanisms. |
---|
44 | |
---|
45 | Usage: |
---|
46 | |
---|
47 | class C: |
---|
48 | __metaclass__ = ABCMeta |
---|
49 | @abstractproperty |
---|
50 | def my_abstract_property(self): |
---|
51 | ... |
---|
52 | |
---|
53 | This defines a read-only property; you can also define a read-write |
---|
54 | abstract property using the 'long' form of property declaration: |
---|
55 | |
---|
56 | class C: |
---|
57 | __metaclass__ = ABCMeta |
---|
58 | def getx(self): ... |
---|
59 | def setx(self, value): ... |
---|
60 | x = abstractproperty(getx, setx) |
---|
61 | """ |
---|
62 | __isabstractmethod__ = True |
---|
63 | |
---|
64 | |
---|
65 | class ABCMeta(type): |
---|
66 | |
---|
67 | """Metaclass for defining Abstract Base Classes (ABCs). |
---|
68 | |
---|
69 | Use this metaclass to create an ABC. An ABC can be subclassed |
---|
70 | directly, and then acts as a mix-in class. You can also register |
---|
71 | unrelated concrete classes (even built-in classes) and unrelated |
---|
72 | ABCs as 'virtual subclasses' -- these and their descendants will |
---|
73 | be considered subclasses of the registering ABC by the built-in |
---|
74 | issubclass() function, but the registering ABC won't show up in |
---|
75 | their MRO (Method Resolution Order) nor will method |
---|
76 | implementations defined by the registering ABC be callable (not |
---|
77 | even via super()). |
---|
78 | |
---|
79 | """ |
---|
80 | |
---|
81 | # A global counter that is incremented each time a class is |
---|
82 | # registered as a virtual subclass of anything. It forces the |
---|
83 | # negative cache to be cleared before its next use. |
---|
84 | _abc_invalidation_counter = 0 |
---|
85 | |
---|
86 | def __new__(mcls, name, bases, namespace): |
---|
87 | cls = super(ABCMeta, mcls).__new__(mcls, name, bases, namespace) |
---|
88 | # Compute set of abstract method names |
---|
89 | abstracts = set(name |
---|
90 | for name, value in namespace.items() |
---|
91 | if getattr(value, "__isabstractmethod__", False)) |
---|
92 | for base in bases: |
---|
93 | for name in getattr(base, "__abstractmethods__", set()): |
---|
94 | value = getattr(cls, name, None) |
---|
95 | if getattr(value, "__isabstractmethod__", False): |
---|
96 | abstracts.add(name) |
---|
97 | cls.__abstractmethods__ = frozenset(abstracts) |
---|
98 | # Set up inheritance registry |
---|
99 | cls._abc_registry = WeakSet() |
---|
100 | cls._abc_cache = WeakSet() |
---|
101 | cls._abc_negative_cache = WeakSet() |
---|
102 | cls._abc_negative_cache_version = ABCMeta._abc_invalidation_counter |
---|
103 | return cls |
---|
104 | |
---|
105 | def register(cls, subclass): |
---|
106 | """Register a virtual subclass of an ABC.""" |
---|
107 | if not isinstance(subclass, (type, types.ClassType)): |
---|
108 | raise TypeError("Can only register classes") |
---|
109 | if issubclass(subclass, cls): |
---|
110 | return # Already a subclass |
---|
111 | # Subtle: test for cycles *after* testing for "already a subclass"; |
---|
112 | # this means we allow X.register(X) and interpret it as a no-op. |
---|
113 | if issubclass(cls, subclass): |
---|
114 | # This would create a cycle, which is bad for the algorithm below |
---|
115 | raise RuntimeError("Refusing to create an inheritance cycle") |
---|
116 | cls._abc_registry.add(subclass) |
---|
117 | ABCMeta._abc_invalidation_counter += 1 # Invalidate negative cache |
---|
118 | |
---|
119 | def _dump_registry(cls, file=None): |
---|
120 | """Debug helper to print the ABC registry.""" |
---|
121 | print >> file, "Class: %s.%s" % (cls.__module__, cls.__name__) |
---|
122 | print >> file, "Inv.counter: %s" % ABCMeta._abc_invalidation_counter |
---|
123 | for name in sorted(cls.__dict__.keys()): |
---|
124 | if name.startswith("_abc_"): |
---|
125 | value = getattr(cls, name) |
---|
126 | print >> file, "%s: %r" % (name, value) |
---|
127 | |
---|
128 | def __instancecheck__(cls, instance): |
---|
129 | """Override for isinstance(instance, cls).""" |
---|
130 | # Inline the cache checking when it's simple. |
---|
131 | subclass = getattr(instance, '__class__', None) |
---|
132 | if subclass is not None and subclass in cls._abc_cache: |
---|
133 | return True |
---|
134 | subtype = type(instance) |
---|
135 | # Old-style instances |
---|
136 | if subtype is _InstanceType: |
---|
137 | subtype = subclass |
---|
138 | if subtype is subclass or subclass is None: |
---|
139 | if (cls._abc_negative_cache_version == |
---|
140 | ABCMeta._abc_invalidation_counter and |
---|
141 | subtype in cls._abc_negative_cache): |
---|
142 | return False |
---|
143 | # Fall back to the subclass check. |
---|
144 | return cls.__subclasscheck__(subtype) |
---|
145 | return (cls.__subclasscheck__(subclass) or |
---|
146 | cls.__subclasscheck__(subtype)) |
---|
147 | |
---|
148 | def __subclasscheck__(cls, subclass): |
---|
149 | """Override for issubclass(subclass, cls).""" |
---|
150 | # Check cache |
---|
151 | if subclass in cls._abc_cache: |
---|
152 | return True |
---|
153 | # Check negative cache; may have to invalidate |
---|
154 | if cls._abc_negative_cache_version < ABCMeta._abc_invalidation_counter: |
---|
155 | # Invalidate the negative cache |
---|
156 | cls._abc_negative_cache = WeakSet() |
---|
157 | cls._abc_negative_cache_version = ABCMeta._abc_invalidation_counter |
---|
158 | elif subclass in cls._abc_negative_cache: |
---|
159 | return False |
---|
160 | # Check the subclass hook |
---|
161 | ok = cls.__subclasshook__(subclass) |
---|
162 | if ok is not NotImplemented: |
---|
163 | assert isinstance(ok, bool) |
---|
164 | if ok: |
---|
165 | cls._abc_cache.add(subclass) |
---|
166 | else: |
---|
167 | cls._abc_negative_cache.add(subclass) |
---|
168 | return ok |
---|
169 | # Check if it's a direct subclass |
---|
170 | if cls in getattr(subclass, '__mro__', ()): |
---|
171 | cls._abc_cache.add(subclass) |
---|
172 | return True |
---|
173 | # Check if it's a subclass of a registered class (recursive) |
---|
174 | for rcls in cls._abc_registry: |
---|
175 | if issubclass(subclass, rcls): |
---|
176 | cls._abc_cache.add(subclass) |
---|
177 | return True |
---|
178 | # Check if it's a subclass of a subclass (recursive) |
---|
179 | for scls in cls.__subclasses__(): |
---|
180 | if issubclass(subclass, scls): |
---|
181 | cls._abc_cache.add(subclass) |
---|
182 | return True |
---|
183 | # No dice; update negative cache |
---|
184 | cls._abc_negative_cache.add(subclass) |
---|
185 | return False |
---|