AppPkg/Applications/Python/Python-2.7.2/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 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