1 # Copyright 2007 Google, Inc. All Rights Reserved.
2 # Licensed to PSF under a Contributor Agreement.
4 """Abstract Base Classes (ABCs) according to PEP 3119."""
7 def abstractmethod(funcobj
):
8 """A decorator indicating abstract methods.
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 the normal
14 'super' call mechanisms.
18 class C(metaclass=ABCMeta):
20 def my_abstract_method(self, ...):
23 funcobj
.__isabstractmethod
__ = True
27 class abstractproperty(property):
28 """A decorator indicating abstract properties.
30 Requires that the metaclass is ABCMeta or derived from it. A
31 class that has a metaclass derived from ABCMeta cannot be
32 instantiated unless all of its abstract properties are overridden.
33 The abstract properties can be called using any of the the normal
34 'super' call mechanisms.
38 class C(metaclass=ABCMeta):
40 def my_abstract_property(self):
43 This defines a read-only property; you can also define a read-write
44 abstract property using the 'long' form of property declaration:
46 class C(metaclass=ABCMeta):
48 def setx(self, value): ...
49 x = abstractproperty(getx, setx)
51 __isabstractmethod__
= True
56 """Metaclass for defining Abstract Base Classes (ABCs).
58 Use this metaclass to create an ABC. An ABC can be subclassed
59 directly, and then acts as a mix-in class. You can also register
60 unrelated concrete classes (even built-in classes) and unrelated
61 ABCs as 'virtual subclasses' -- these and their descendants will
62 be considered subclasses of the registering ABC by the built-in
63 issubclass() function, but the registering ABC won't show up in
64 their MRO (Method Resolution Order) nor will method
65 implementations defined by the registering ABC be callable (not
70 # A global counter that is incremented each time a class is
71 # registered as a virtual subclass of anything. It forces the
72 # negative cache to be cleared before its next use.
73 _abc_invalidation_counter
= 0
75 def __new__(mcls
, name
, bases
, namespace
):
76 cls
= super(ABCMeta
, mcls
).__new
__(mcls
, name
, bases
, namespace
)
77 # Compute set of abstract method names
79 for name
, value
in namespace
.items()
80 if getattr(value
, "__isabstractmethod__", False))
82 for name
in getattr(base
, "__abstractmethods__", set()):
83 value
= getattr(cls
, name
, None)
84 if getattr(value
, "__isabstractmethod__", False):
86 cls
.__abstractmethods
__ = frozenset(abstracts
)
87 # Set up inheritance registry
88 cls
._abc
_registry
= set()
89 cls
._abc
_cache
= set()
90 cls
._abc
_negative
_cache
= set()
91 cls
._abc
_negative
_cache
_version
= ABCMeta
._abc
_invalidation
_counter
94 def register(cls
, subclass
):
95 """Register a virtual subclass of an ABC."""
96 if not isinstance(cls
, type):
97 raise TypeError("Can only register classes")
98 if issubclass(subclass
, cls
):
99 return # Already a subclass
100 # Subtle: test for cycles *after* testing for "already a subclass";
101 # this means we allow X.register(X) and interpret it as a no-op.
102 if issubclass(cls
, subclass
):
103 # This would create a cycle, which is bad for the algorithm below
104 raise RuntimeError("Refusing to create an inheritance cycle")
105 cls
._abc
_registry
.add(subclass
)
106 ABCMeta
._abc
_invalidation
_counter
+= 1 # Invalidate negative cache
108 def _dump_registry(cls
, file=None):
109 """Debug helper to print the ABC registry."""
110 print >> file, "Class: %s.%s" % (cls
.__module
__, cls
.__name
__)
111 print >> file, "Inv.counter: %s" % ABCMeta
._abc
_invalidation
_counter
112 for name
in sorted(cls
.__dict
__.keys()):
113 if name
.startswith("_abc_"):
114 value
= getattr(cls
, name
)
115 print >> file, "%s: %r" % (name
, value
)
117 def __instancecheck__(cls
, instance
):
118 """Override for isinstance(instance, cls)."""
119 # Inline the cache checking when it's simple.
120 subclass
= getattr(instance
, '__class__', None)
121 if subclass
in cls
._abc
_cache
:
123 subtype
= type(instance
)
124 if subtype
is subclass
or subclass
is None:
125 if (cls
._abc
_negative
_cache
_version
==
126 ABCMeta
._abc
_invalidation
_counter
and
127 subtype
in cls
._abc
_negative
_cache
):
129 # Fall back to the subclass check.
130 return cls
.__subclasscheck
__(subtype
)
131 return (cls
.__subclasscheck
__(subclass
) or
132 cls
.__subclasscheck
__(subtype
))
134 def __subclasscheck__(cls
, subclass
):
135 """Override for issubclass(subclass, cls)."""
137 if subclass
in cls
._abc
_cache
:
139 # Check negative cache; may have to invalidate
140 if cls
._abc
_negative
_cache
_version
< ABCMeta
._abc
_invalidation
_counter
:
141 # Invalidate the negative cache
142 cls
._abc
_negative
_cache
= set()
143 cls
._abc
_negative
_cache
_version
= ABCMeta
._abc
_invalidation
_counter
144 elif subclass
in cls
._abc
_negative
_cache
:
146 # Check the subclass hook
147 ok
= cls
.__subclasshook
__(subclass
)
148 if ok
is not NotImplemented:
149 assert isinstance(ok
, bool)
151 cls
._abc
_cache
.add(subclass
)
153 cls
._abc
_negative
_cache
.add(subclass
)
155 # Check if it's a direct subclass
156 if cls
in getattr(subclass
, '__mro__', ()):
157 cls
._abc
_cache
.add(subclass
)
159 # Check if it's a subclass of a registered class (recursive)
160 for rcls
in cls
._abc
_registry
:
161 if issubclass(subclass
, rcls
):
162 cls
._abc
_cache
.add(subclass
)
164 # Check if it's a subclass of a subclass (recursive)
165 for scls
in cls
.__subclasses
__():
166 if issubclass(subclass
, scls
):
167 cls
._abc
_cache
.add(subclass
)
169 # No dice; update negative cache
170 cls
._abc
_negative
_cache
.add(subclass
)