# Copyright 2007 Google, Inc. All Rights Reserved. | |
# Licensed to PSF under a Contributor Agreement. | |
"""Abstract Base Classes (ABCs) according to PEP 3119.""" | |
import types | |
from _weakrefset import WeakSet | |
# Instance of old-style class | |
class _C: pass | |
_InstanceType = type(_C()) | |
def abstractmethod(funcobj): | |
"""A decorator indicating abstract methods. | |
Requires that the metaclass is ABCMeta or derived from it. A | |
class that has a metaclass derived from ABCMeta cannot be | |
instantiated unless all of its abstract methods are overridden. | |
The abstract methods can be called using any of the normal | |
'super' call mechanisms. | |
Usage: | |
class C: | |
__metaclass__ = ABCMeta | |
@abstractmethod | |
def my_abstract_method(self, ...): | |
... | |
""" | |
funcobj.__isabstractmethod__ = True | |
return funcobj | |
class abstractproperty(property): | |
"""A decorator indicating abstract properties. | |
Requires that the metaclass is ABCMeta or derived from it. A | |
class that has a metaclass derived from ABCMeta cannot be | |
instantiated unless all of its abstract properties are overridden. | |
The abstract properties can be called using any of the normal | |
'super' call mechanisms. | |
Usage: | |
class C: | |
__metaclass__ = ABCMeta | |
@abstractproperty | |
def my_abstract_property(self): | |
... | |
This defines a read-only property; you can also define a read-write | |
abstract property using the 'long' form of property declaration: | |
class C: | |
__metaclass__ = ABCMeta | |
def getx(self): ... | |
def setx(self, value): ... | |
x = abstractproperty(getx, setx) | |
""" | |
__isabstractmethod__ = True | |
class ABCMeta(type): | |
"""Metaclass for defining Abstract Base Classes (ABCs). | |
Use this metaclass to create an ABC. An ABC can be subclassed | |
directly, and then acts as a mix-in class. You can also register | |
unrelated concrete classes (even built-in classes) and unrelated | |
ABCs as 'virtual subclasses' -- these and their descendants will | |
be considered subclasses of the registering ABC by the built-in | |
issubclass() function, but the registering ABC won't show up in | |
their MRO (Method Resolution Order) nor will method | |
implementations defined by the registering ABC be callable (not | |
even via super()). | |
""" | |
# A global counter that is incremented each time a class is | |
# registered as a virtual subclass of anything. It forces the | |
# negative cache to be cleared before its next use. | |
_abc_invalidation_counter = 0 | |
def __new__(mcls, name, bases, namespace): | |
cls = super(ABCMeta, mcls).__new__(mcls, name, bases, namespace) | |
# Compute set of abstract method names | |
abstracts = set(name | |
for name, value in namespace.items() | |
if getattr(value, "__isabstractmethod__", False)) | |
for base in bases: | |
for name in getattr(base, "__abstractmethods__", set()): | |
value = getattr(cls, name, None) | |
if getattr(value, "__isabstractmethod__", False): | |
abstracts.add(name) | |
cls.__abstractmethods__ = frozenset(abstracts) | |
# Set up inheritance registry | |
cls._abc_registry = WeakSet() | |
cls._abc_cache = WeakSet() | |
cls._abc_negative_cache = WeakSet() | |
cls._abc_negative_cache_version = ABCMeta._abc_invalidation_counter | |
return cls | |
def register(cls, subclass): | |
"""Register a virtual subclass of an ABC.""" | |
if not isinstance(subclass, (type, types.ClassType)): | |
raise TypeError("Can only register classes") | |
if issubclass(subclass, cls): | |
return # Already a subclass | |
# Subtle: test for cycles *after* testing for "already a subclass"; | |
# this means we allow X.register(X) and interpret it as a no-op. | |
if issubclass(cls, subclass): | |
# This would create a cycle, which is bad for the algorithm below | |
raise RuntimeError("Refusing to create an inheritance cycle") | |
cls._abc_registry.add(subclass) | |
ABCMeta._abc_invalidation_counter += 1 # Invalidate negative cache | |
def _dump_registry(cls, file=None): | |
"""Debug helper to print the ABC registry.""" | |
print >> file, "Class: %s.%s" % (cls.__module__, cls.__name__) | |
print >> file, "Inv.counter: %s" % ABCMeta._abc_invalidation_counter | |
for name in sorted(cls.__dict__.keys()): | |
if name.startswith("_abc_"): | |
value = getattr(cls, name) | |
print >> file, "%s: %r" % (name, value) | |
def __instancecheck__(cls, instance): | |
"""Override for isinstance(instance, cls).""" | |
# Inline the cache checking when it's simple. | |
subclass = getattr(instance, '__class__', None) | |
if subclass is not None and subclass in cls._abc_cache: | |
return True | |
subtype = type(instance) | |
# Old-style instances | |
if subtype is _InstanceType: | |
subtype = subclass | |
if subtype is subclass or subclass is None: | |
if (cls._abc_negative_cache_version == | |
ABCMeta._abc_invalidation_counter and | |
subtype in cls._abc_negative_cache): | |
return False | |
# Fall back to the subclass check. | |
return cls.__subclasscheck__(subtype) | |
return (cls.__subclasscheck__(subclass) or | |
cls.__subclasscheck__(subtype)) | |
def __subclasscheck__(cls, subclass): | |
"""Override for issubclass(subclass, cls).""" | |
# Check cache | |
if subclass in cls._abc_cache: | |
return True | |
# Check negative cache; may have to invalidate | |
if cls._abc_negative_cache_version < ABCMeta._abc_invalidation_counter: | |
# Invalidate the negative cache | |
cls._abc_negative_cache = WeakSet() | |
cls._abc_negative_cache_version = ABCMeta._abc_invalidation_counter | |
elif subclass in cls._abc_negative_cache: | |
return False | |
# Check the subclass hook | |
ok = cls.__subclasshook__(subclass) | |
if ok is not NotImplemented: | |
assert isinstance(ok, bool) | |
if ok: | |
cls._abc_cache.add(subclass) | |
else: | |
cls._abc_negative_cache.add(subclass) | |
return ok | |
# Check if it's a direct subclass | |
if cls in getattr(subclass, '__mro__', ()): | |
cls._abc_cache.add(subclass) | |
return True | |
# Check if it's a subclass of a registered class (recursive) | |
for rcls in cls._abc_registry: | |
if issubclass(subclass, rcls): | |
cls._abc_cache.add(subclass) | |
return True | |
# Check if it's a subclass of a subclass (recursive) | |
for scls in cls.__subclasses__(): | |
if issubclass(subclass, scls): | |
cls._abc_cache.add(subclass) | |
return True | |
# No dice; update negative cache | |
cls._abc_negative_cache.add(subclass) | |
return False |