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
6import types
7
8from _weakrefset import WeakSet
9
10# Instance of old-style class
11class _C: pass
12_InstanceType = type(_C())
13
14
15def 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
36class 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
65class 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