abc

  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
  7def 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.  abstractmethod() may be used to declare
 15    abstract methods for properties and descriptors.
 16
 17    Usage:
 18
 19        class C(metaclass=ABCMeta):
 20            @abstractmethod
 21            def my_abstract_method(self, arg1, arg2, argN):
 22                ...
 23    """
 24    funcobj.__isabstractmethod__ = True
 25    return funcobj
 26
 27
 28class abstractclassmethod(classmethod):
 29    """A decorator indicating abstract classmethods.
 30
 31    Deprecated, use 'classmethod' with 'abstractmethod' instead:
 32
 33        class C(ABC):
 34            @classmethod
 35            @abstractmethod
 36            def my_abstract_classmethod(cls, ...):
 37                ...
 38
 39    """
 40
 41    __isabstractmethod__ = True
 42
 43    def __init__(self, callable):
 44        callable.__isabstractmethod__ = True
 45        super().__init__(callable)
 46
 47
 48class abstractstaticmethod(staticmethod):
 49    """A decorator indicating abstract staticmethods.
 50
 51    Deprecated, use 'staticmethod' with 'abstractmethod' instead:
 52
 53        class C(ABC):
 54            @staticmethod
 55            @abstractmethod
 56            def my_abstract_staticmethod(...):
 57                ...
 58
 59    """
 60
 61    __isabstractmethod__ = True
 62
 63    def __init__(self, callable):
 64        callable.__isabstractmethod__ = True
 65        super().__init__(callable)
 66
 67
 68class abstractproperty(property):
 69    """A decorator indicating abstract properties.
 70
 71    Deprecated, use 'property' with 'abstractmethod' instead:
 72
 73        class C(ABC):
 74            @property
 75            @abstractmethod
 76            def my_abstract_property(self):
 77                ...
 78
 79    """
 80
 81    __isabstractmethod__ = True
 82
 83
 84try:
 85    from _abc import (get_cache_token, _abc_init, _abc_register,
 86                      _abc_instancecheck, _abc_subclasscheck, _get_dump,
 87                      _reset_registry, _reset_caches)
 88except ImportError:
 89    from _py_abc import ABCMeta, get_cache_token
 90    ABCMeta.__module__ = 'abc'
 91else:
 92    class ABCMeta(type):
 93        """Metaclass for defining Abstract Base Classes (ABCs).
 94
 95        Use this metaclass to create an ABC.  An ABC can be subclassed
 96        directly, and then acts as a mix-in class.  You can also register
 97        unrelated concrete classes (even built-in classes) and unrelated
 98        ABCs as 'virtual subclasses' -- these and their descendants will
 99        be considered subclasses of the registering ABC by the built-in
100        issubclass() function, but the registering ABC won't show up in
101        their MRO (Method Resolution Order) nor will method
102        implementations defined by the registering ABC be callable (not
103        even via super()).
104        """
105        def __new__(mcls, name, bases, namespace, /, **kwargs):
106            cls = super().__new__(mcls, name, bases, namespace, **kwargs)
107            _abc_init(cls)
108            return cls
109
110        def register(cls, subclass):
111            """Register a virtual subclass of an ABC.
112
113            Returns the subclass, to allow usage as a class decorator.
114            """
115            return _abc_register(cls, subclass)
116
117        def __instancecheck__(cls, instance):
118            """Override for isinstance(instance, cls)."""
119            return _abc_instancecheck(cls, instance)
120
121        def __subclasscheck__(cls, subclass):
122            """Override for issubclass(subclass, cls)."""
123            return _abc_subclasscheck(cls, subclass)
124
125        def _dump_registry(cls, file=None):
126            """Debug helper to print the ABC registry."""
127            print(f"Class: {cls.__module__}.{cls.__qualname__}", file=file)
128            print(f"Inv. counter: {get_cache_token()}", file=file)
129            (_abc_registry, _abc_cache, _abc_negative_cache,
130             _abc_negative_cache_version) = _get_dump(cls)
131            print(f"_abc_registry: {_abc_registry!r}", file=file)
132            print(f"_abc_cache: {_abc_cache!r}", file=file)
133            print(f"_abc_negative_cache: {_abc_negative_cache!r}", file=file)
134            print(f"_abc_negative_cache_version: {_abc_negative_cache_version!r}",
135                  file=file)
136
137        def _abc_registry_clear(cls):
138            """Clear the registry (for debugging or testing)."""
139            _reset_registry(cls)
140
141        def _abc_caches_clear(cls):
142            """Clear the caches (for debugging or testing)."""
143            _reset_caches(cls)
144
145
146def update_abstractmethods(cls):
147    """Recalculate the set of abstract methods of an abstract class.
148
149    If a class has had one of its abstract methods implemented after the
150    class was created, the method will not be considered implemented until
151    this function is called. Alternatively, if a new abstract method has been
152    added to the class, it will only be considered an abstract method of the
153    class after this function is called.
154
155    This function should be called before any use is made of the class,
156    usually in class decorators that add methods to the subject class.
157
158    Returns cls, to allow usage as a class decorator.
159
160    If cls is not an instance of ABCMeta, does nothing.
161    """
162    if not hasattr(cls, '__abstractmethods__'):
163        # We check for __abstractmethods__ here because cls might by a C
164        # implementation or a python implementation (especially during
165        # testing), and we want to handle both cases.
166        return cls
167
168    abstracts = set()
169    # Check the existing abstract methods of the parents, keep only the ones
170    # that are not implemented.
171    for scls in cls.__bases__:
172        for name in getattr(scls, '__abstractmethods__', ()):
173            value = getattr(cls, name, None)
174            if getattr(value, "__isabstractmethod__", False):
175                abstracts.add(name)
176    # Also add any other newly added abstract methods.
177    for name, value in cls.__dict__.items():
178        if getattr(value, "__isabstractmethod__", False):
179            abstracts.add(name)
180    cls.__abstractmethods__ = frozenset(abstracts)
181    return cls
182
183
184class ABC(metaclass=ABCMeta):
185    """Helper class that provides a standard way to create an ABC using
186    inheritance.
187    """
188    __slots__ = ()