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 186
