#!/usr/bin/env python3.0 """Abstract Base Classes, reloaded.""" import sys __all__ = ["ABCMeta"] 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 the normal 'super' call mechanisms. Usage: class C(metaclass=ABCMeta): @abstractmethod def my_abstract_method(self, ...): ... """ funcobj.__isabstractmethod__ = True return funcobj class _Abstract(object): """Helper class inserted into the bases by ABCMeta (using _fix_bases()). You should never need to explicitly subclass this class. """ def __new__(cls, *args, **kwds): am = cls.__dict__.get("__abstractmethods__") if am: raise TypeError("can't instantiate abstract class %s " "with abstract methods %s" % (cls.__name__, ", ".join(sorted(am)))) return super(_Abstract, cls).__new__(cls, *args, **kwds) def _fix_bases(bases): """Helper method that inserts _Abstract in the bases if needed.""" for base in bases: if issubclass(base, _Abstract): # _Abstract is already a base (maybe indirectly) return bases if object in bases: # Replace object with _Abstract return tuple([_Abstract if base is object else base for base in bases]) # Append _Abstract to the end return bases + (_Abstract,) 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. __invalidation_counter = 0 def __new__(mcls, name, bases, namespace): bases = _fix_bases(bases) cls = super(ABCMeta, mcls).__new__(mcls, name, bases, namespace) # Compute set of abstract method names abstracts = {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__ = abstracts # Set up inheritance registry cls.__abc_registry__ = set() cls.__abc_cache__ = set() cls.__abc_negative_cache__ = set() cls.__abc_negative_cache_version__ = ABCMeta.__invalidation_counter return cls def register(cls, subclass): """Register a virtual subclass of an ABC.""" if not isinstance(cls, type): 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.__invalidation_counter += 1 # Invalidate negative cache def _dump_registry(cls, file=None): """Debug helper to print the ABC registry.""" if file is None: file = sys.stdout print("Class: %s.%s" % (cls.__module__, cls.__name__), file=file) print("Inv.counter: %s" % ABCMeta.__invalidation_counter, file=file) for name in sorted(cls.__dict__.keys()): if name.startswith("__abc_"): value = getattr(cls, name) print("%s: %r" % (name, value), file=file) def __instancecheck__(cls, instance): """Override for isinstance(instance, cls).""" return any(cls.__subclasscheck__(c) for c in {instance.__class__, type(instance)}) 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.__invalidation_counter: # Invalidate the negative cache cls.__abc_negative_cache_version__ = ABCMeta.__invalidation_counter cls.__abc_negative_cache__ = set() elif subclass in cls.__abc_negative_cache__: return False # Check if it's a direct subclass if cls in 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_registry__.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_registry__.add(subclass) return True # No dice; update negative cache cls.__abc_negative_cache__.add(subclass) return False def _demo(): # Set up a bunch of trivial ABCs class Sequence(metaclass=ABCMeta): """A sequence without any behavior implementation.""" class Mapping(metaclass=ABCMeta): """A mapping.""" class MutableMapping(Mapping): """A mutable mapping.""" MutableMapping.register(dict) class Set(metaclass=ABCMeta): """A set.""" class ImmutableSet(metaclass=ABCMeta): """An immutable set.""" ImmutableSet.register(frozenset) class MutableSet(metaclass=ABCMeta): """A mutable set.""" Set.register(ImmutableSet) Set.register(MutableSet) MutableSet.register(set) class ImmutableSequence(Sequence): """An immutable sequence.""" ImmutableSequence.register(tuple) ImmutableSequence.register(basestring) class MutableSequence(Sequence): """A mutable sequence.""" MutableSequence.register(list) MutableSequence.register(bytes) Sequence.register(MutableSequence) # Test them SAMPLES = [0, b"", "", u"", [], (), {}, set(), frozenset()] def show(abc): print("%s: %s" % (abc.__name__, ", ".join([repr(sample) for sample in SAMPLES if isinstance(sample, abc)]))) ##abc._dump_registry() ##print() for abc in [Sequence, MutableSequence, ImmutableSequence, Mapping, MutableMapping, Set, ImmutableSet, MutableSet]: show(abc) # Add another one at the bottom class Collection(metaclass=ABCMeta): """A collection.""" Collection.register(Set) Collection.register(Sequence) Collection.register(Mapping) Collection.register(Collection) # And test it for abc in [Collection]: show(abc) abc._dump_registry() # Set up some tests for @abstractmethod class A(metaclass=ABCMeta): @abstractmethod def foo(self): pass @abstractmethod def bar(self): pass class B(A): def foo(self): pass class C(B): def bar(self): pass try: A() assert False except TypeError as err: print("as expected:", err) try: B() assert False except TypeError as err: print("as expected:", err) C() # Test a special Hashable class Hashable: @classmethod def __instancecheck__(self, x): return getattr(x, "__hash__", None) is not None @classmethod def __subclasscheck__(self, C): if not hasattr(C, "__bases__"): raise TypeError( "%.100s object %.100r is not a class" % (C.__class__.__name__, C)) return getattr(C, "__hash__", None) is not None assert isinstance(42, Hashable) assert not isinstance([], Hashable) assert issubclass(tuple, Hashable) assert issubclass(type, Hashable) assert not issubclass(dict, Hashable) assert isinstance(tuple, Hashable) # types are hashable x = ([], {}) # Unhashable tuple assert isinstance(x, Hashable) # Even though it raises TypeError try: issubclass(42, Hashable) assert False except TypeError as err: print("as expected:", err) if __name__ == "__main__": _demo()