Lib/abc.py

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