new repository

1 files changed, 144 insertions, 0 deletions

diff --git a/devdocs/python~3.12/library%2Fabc.html b/devdocs/python~3.12/library%2Fabc.html
new file mode 100644
index 00000000..a8ddfaf6
--- /dev/null
+++ b/devdocs/python~3.12/library%2Fabc.html
@@ -0,0 +1,144 @@
+ <span id="abc-abstract-base-classes"></span><h1>abc — Abstract Base Classes</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/abc.py">Lib/abc.py</a></p>  <p>This module provides the infrastructure for defining <a class="reference internal" href="../glossary#term-abstract-base-class"><span class="xref std std-term">abstract base classes</span></a> (ABCs) in Python, as outlined in <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-3119/"><strong>PEP 3119</strong></a>; see the PEP for why this was added to Python. (See also <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-3141/"><strong>PEP 3141</strong></a> and the <a class="reference internal" href="numbers#module-numbers" title="numbers: Numeric abstract base classes (Complex, Real, Integral, etc.)."><code>numbers</code></a> module regarding a type hierarchy for numbers based on ABCs.)</p> <p>The <a class="reference internal" href="collections#module-collections" title="collections: Container datatypes"><code>collections</code></a> module has some concrete classes that derive from ABCs; these can, of course, be further derived. In addition, the <a class="reference internal" href="collections.abc#module-collections.abc" title="collections.abc: Abstract base classes for containers"><code>collections.abc</code></a> submodule has some ABCs that can be used to test whether a class or instance provides a particular interface, for example, if it is <a class="reference internal" href="../glossary#term-hashable"><span class="xref std std-term">hashable</span></a> or if it is a <a class="reference internal" href="../glossary#term-mapping"><span class="xref std std-term">mapping</span></a>.</p> <p>This module provides the metaclass <a class="reference internal" href="#abc.ABCMeta" title="abc.ABCMeta"><code>ABCMeta</code></a> for defining ABCs and a helper class <a class="reference internal" href="#abc.ABC" title="abc.ABC"><code>ABC</code></a> to alternatively define ABCs through inheritance:</p> <dl class="py class"> <dt class="sig sig-object py" id="abc.ABC">
+<code>class abc.ABC</code> </dt> <dd>
+<p>A helper class that has <a class="reference internal" href="#abc.ABCMeta" title="abc.ABCMeta"><code>ABCMeta</code></a> as its metaclass. With this class, an abstract base class can be created by simply deriving from <code>ABC</code> avoiding sometimes confusing metaclass usage, for example:</p> <pre data-language="python">from abc import ABC
+
+class MyABC(ABC):
+    pass
+</pre> <p>Note that the type of <code>ABC</code> is still <a class="reference internal" href="#abc.ABCMeta" title="abc.ABCMeta"><code>ABCMeta</code></a>, therefore inheriting from <code>ABC</code> requires the usual precautions regarding metaclass usage, as multiple inheritance may lead to metaclass conflicts. One may also define an abstract base class by passing the metaclass keyword and using <code>ABCMeta</code> directly, for example:</p> <pre data-language="python">from abc import ABCMeta
+
+class MyABC(metaclass=ABCMeta):
+    pass
+</pre> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
+</dl> <dl class="py class"> <dt class="sig sig-object py" id="abc.ABCMeta">
+<code>class abc.ABCMeta</code> </dt> <dd>
+<p>Metaclass for defining Abstract Base Classes (ABCs).</p> <p>Use this metaclass to create an ABC. An ABC can be subclassed directly, and then acts as a mix-in class. You can also register unrelated concrete classes (even built-in classes) and unrelated ABCs as “virtual subclasses” – these and their descendants will be considered subclasses of the registering ABC by the built-in <a class="reference internal" href="functions#issubclass" title="issubclass"><code>issubclass()</code></a> function, but the registering ABC won’t show up in their MRO (Method Resolution Order) nor will method implementations defined by the registering ABC be callable (not even via <a class="reference internal" href="functions#super" title="super"><code>super()</code></a>). <a class="footnote-reference brackets" href="#id2" id="id1">1</a></p> <p>Classes created with a metaclass of <code>ABCMeta</code> have the following method:</p> <dl class="py method"> <dt class="sig sig-object py" id="abc.ABCMeta.register">
+<code>register(subclass)</code> </dt> <dd>
+<p>Register <em>subclass</em> as a “virtual subclass” of this ABC. For example:</p> <pre data-language="python">from abc import ABC
+
+class MyABC(ABC):
+    pass
+
+MyABC.register(tuple)
+
+assert issubclass(tuple, MyABC)
+assert isinstance((), MyABC)
+</pre> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span>Returns the registered subclass, to allow usage as a class decorator.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>To detect calls to <code>register()</code>, you can use the <a class="reference internal" href="#abc.get_cache_token" title="abc.get_cache_token"><code>get_cache_token()</code></a> function.</p> </div> </dd>
+</dl> <p>You can also override this method in an abstract base class:</p> <dl class="py method"> <dt class="sig sig-object py" id="abc.ABCMeta.__subclasshook__">
+<code>__subclasshook__(subclass)</code> </dt> <dd>
+<p>(Must be defined as a class method.)</p> <p>Check whether <em>subclass</em> is considered a subclass of this ABC. This means that you can customize the behavior of <a class="reference internal" href="functions#issubclass" title="issubclass"><code>issubclass()</code></a> further without the need to call <a class="reference internal" href="#abc.ABCMeta.register" title="abc.ABCMeta.register"><code>register()</code></a> on every class you want to consider a subclass of the ABC. (This class method is called from the <a class="reference internal" href="../reference/datamodel#class.__subclasscheck__" title="class.__subclasscheck__"><code>__subclasscheck__()</code></a> method of the ABC.)</p> <p>This method should return <code>True</code>, <code>False</code> or <code>NotImplemented</code>. If it returns <code>True</code>, the <em>subclass</em> is considered a subclass of this ABC. If it returns <code>False</code>, the <em>subclass</em> is not considered a subclass of this ABC, even if it would normally be one. If it returns <code>NotImplemented</code>, the subclass check is continued with the usual mechanism.</p> </dd>
+</dl> <p>For a demonstration of these concepts, look at this example ABC definition:</p> <pre data-language="python">class Foo:
+    def __getitem__(self, index):
+        ...
+    def __len__(self):
+        ...
+    def get_iterator(self):
+        return iter(self)
+
+class MyIterable(ABC):
+
+    @abstractmethod
+    def __iter__(self):
+        while False:
+            yield None
+
+    def get_iterator(self):
+        return self.__iter__()
+
+    @classmethod
+    def __subclasshook__(cls, C):
+        if cls is MyIterable:
+            if any("__iter__" in B.__dict__ for B in C.__mro__):
+                return True
+        return NotImplemented
+
+MyIterable.register(Foo)
+</pre> <p>The ABC <code>MyIterable</code> defines the standard iterable method, <a class="reference internal" href="stdtypes#iterator.__iter__" title="iterator.__iter__"><code>__iter__()</code></a>, as an abstract method. The implementation given here can still be called from subclasses. The <code>get_iterator()</code> method is also part of the <code>MyIterable</code> abstract base class, but it does not have to be overridden in non-abstract derived classes.</p> <p>The <a class="reference internal" href="#abc.ABCMeta.__subclasshook__" title="abc.ABCMeta.__subclasshook__"><code>__subclasshook__()</code></a> class method defined here says that any class that has an <a class="reference internal" href="stdtypes#iterator.__iter__" title="iterator.__iter__"><code>__iter__()</code></a> method in its <a class="reference internal" href="stdtypes#object.__dict__" title="object.__dict__"><code>__dict__</code></a> (or in that of one of its base classes, accessed via the <a class="reference internal" href="stdtypes#class.__mro__" title="class.__mro__"><code>__mro__</code></a> list) is considered a <code>MyIterable</code> too.</p> <p>Finally, the last line makes <code>Foo</code> a virtual subclass of <code>MyIterable</code>, even though it does not define an <a class="reference internal" href="stdtypes#iterator.__iter__" title="iterator.__iter__"><code>__iter__()</code></a> method (it uses the old-style iterable protocol, defined in terms of <a class="reference internal" href="../reference/datamodel#object.__len__" title="object.__len__"><code>__len__()</code></a> and <a class="reference internal" href="../reference/datamodel#object.__getitem__" title="object.__getitem__"><code>__getitem__()</code></a>). Note that this will not make <code>get_iterator</code> available as a method of <code>Foo</code>, so it is provided separately.</p> </dd>
+</dl> <p>The <code>abc</code> module also provides the following decorator:</p> <dl class="py function"> <dt class="sig sig-object py" id="abc.abstractmethod">
+<code>@abc.abstractmethod</code> </dt> <dd>
+<p>A decorator indicating abstract methods.</p> <p>Using this decorator requires that the class’s metaclass is <a class="reference internal" href="#abc.ABCMeta" title="abc.ABCMeta"><code>ABCMeta</code></a> or is derived from it. A class that has a metaclass derived from <code>ABCMeta</code> cannot be instantiated unless all of its abstract methods and properties are overridden. The abstract methods can be called using any of the normal ‘super’ call mechanisms. <code>abstractmethod()</code> may be used to declare abstract methods for properties and descriptors.</p> <p>Dynamically adding abstract methods to a class, or attempting to modify the abstraction status of a method or class once it is created, are only supported using the <a class="reference internal" href="#abc.update_abstractmethods" title="abc.update_abstractmethods"><code>update_abstractmethods()</code></a> function. The <code>abstractmethod()</code> only affects subclasses derived using regular inheritance; “virtual subclasses” registered with the ABC’s <a class="reference internal" href="#abc.ABCMeta.register" title="abc.ABCMeta.register"><code>register()</code></a> method are not affected.</p> <p>When <code>abstractmethod()</code> is applied in combination with other method descriptors, it should be applied as the innermost decorator, as shown in the following usage examples:</p> <pre data-language="python">class C(ABC):
+    @abstractmethod
+    def my_abstract_method(self, arg1):
+        ...
+    @classmethod
+    @abstractmethod
+    def my_abstract_classmethod(cls, arg2):
+        ...
+    @staticmethod
+    @abstractmethod
+    def my_abstract_staticmethod(arg3):
+        ...
+
+    @property
+    @abstractmethod
+    def my_abstract_property(self):
+        ...
+    @my_abstract_property.setter
+    @abstractmethod
+    def my_abstract_property(self, val):
+        ...
+
+    @abstractmethod
+    def _get_x(self):
+        ...
+    @abstractmethod
+    def _set_x(self, val):
+        ...
+    x = property(_get_x, _set_x)
+</pre> <p>In order to correctly interoperate with the abstract base class machinery, the descriptor must identify itself as abstract using <code>__isabstractmethod__</code>. In general, this attribute should be <code>True</code> if any of the methods used to compose the descriptor are abstract. For example, Python’s built-in <a class="reference internal" href="functions#property" title="property"><code>property</code></a> does the equivalent of:</p> <pre data-language="python">class Descriptor:
+    ...
+    @property
+    def __isabstractmethod__(self):
+        return any(getattr(f, '__isabstractmethod__', False) for
+                   f in (self._fget, self._fset, self._fdel))
+</pre> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Unlike Java abstract methods, these abstract methods may have an implementation. This implementation can be called via the <a class="reference internal" href="functions#super" title="super"><code>super()</code></a> mechanism from the class that overrides it. This could be useful as an end-point for a super-call in a framework that uses cooperative multiple-inheritance.</p> </div> </dd>
+</dl> <p>The <code>abc</code> module also supports the following legacy decorators:</p> <dl class="py function"> <dt class="sig sig-object py" id="abc.abstractclassmethod">
+<code>@abc.abstractclassmethod</code> </dt> <dd>
+<div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.3: </span>It is now possible to use <a class="reference internal" href="functions#classmethod" title="classmethod"><code>classmethod</code></a> with <a class="reference internal" href="#abc.abstractmethod" title="abc.abstractmethod"><code>abstractmethod()</code></a>, making this decorator redundant.</p> </div> <p>A subclass of the built-in <a class="reference internal" href="functions#classmethod" title="classmethod"><code>classmethod()</code></a>, indicating an abstract classmethod. Otherwise it is similar to <a class="reference internal" href="#abc.abstractmethod" title="abc.abstractmethod"><code>abstractmethod()</code></a>.</p> <p>This special case is deprecated, as the <a class="reference internal" href="functions#classmethod" title="classmethod"><code>classmethod()</code></a> decorator is now correctly identified as abstract when applied to an abstract method:</p> <pre data-language="python">class C(ABC):
+    @classmethod
+    @abstractmethod
+    def my_abstract_classmethod(cls, arg):
+        ...
+</pre> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="abc.abstractstaticmethod">
+<code>@abc.abstractstaticmethod</code> </dt> <dd>
+<div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.3: </span>It is now possible to use <a class="reference internal" href="functions#staticmethod" title="staticmethod"><code>staticmethod</code></a> with <a class="reference internal" href="#abc.abstractmethod" title="abc.abstractmethod"><code>abstractmethod()</code></a>, making this decorator redundant.</p> </div> <p>A subclass of the built-in <a class="reference internal" href="functions#staticmethod" title="staticmethod"><code>staticmethod()</code></a>, indicating an abstract staticmethod. Otherwise it is similar to <a class="reference internal" href="#abc.abstractmethod" title="abc.abstractmethod"><code>abstractmethod()</code></a>.</p> <p>This special case is deprecated, as the <a class="reference internal" href="functions#staticmethod" title="staticmethod"><code>staticmethod()</code></a> decorator is now correctly identified as abstract when applied to an abstract method:</p> <pre data-language="python">class C(ABC):
+    @staticmethod
+    @abstractmethod
+    def my_abstract_staticmethod(arg):
+        ...
+</pre> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="abc.abstractproperty">
+<code>@abc.abstractproperty</code> </dt> <dd>
+<div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.3: </span>It is now possible to use <a class="reference internal" href="functions#property" title="property"><code>property</code></a>, <a class="reference internal" href="functions#property.getter" title="property.getter"><code>property.getter()</code></a>, <a class="reference internal" href="functions#property.setter" title="property.setter"><code>property.setter()</code></a> and <a class="reference internal" href="functions#property.deleter" title="property.deleter"><code>property.deleter()</code></a> with <a class="reference internal" href="#abc.abstractmethod" title="abc.abstractmethod"><code>abstractmethod()</code></a>, making this decorator redundant.</p> </div> <p>A subclass of the built-in <a class="reference internal" href="functions#property" title="property"><code>property()</code></a>, indicating an abstract property.</p> <p>This special case is deprecated, as the <a class="reference internal" href="functions#property" title="property"><code>property()</code></a> decorator is now correctly identified as abstract when applied to an abstract method:</p> <pre data-language="python">class C(ABC):
+    @property
+    @abstractmethod
+    def my_abstract_property(self):
+        ...
+</pre> <p>The above example defines a read-only property; you can also define a read-write abstract property by appropriately marking one or more of the underlying methods as abstract:</p> <pre data-language="python">class C(ABC):
+    @property
+    def x(self):
+        ...
+
+    @x.setter
+    @abstractmethod
+    def x(self, val):
+        ...
+</pre> <p>If only some components are abstract, only those components need to be updated to create a concrete property in a subclass:</p> <pre data-language="python">class D(C):
+    @C.x.setter
+    def x(self, val):
+        ...
+</pre> </dd>
+</dl> <p>The <code>abc</code> module also provides the following functions:</p> <dl class="py function"> <dt class="sig sig-object py" id="abc.get_cache_token">
+<code>abc.get_cache_token()</code> </dt> <dd>
+<p>Returns the current abstract base class cache token.</p> <p>The token is an opaque object (that supports equality testing) identifying the current version of the abstract base class cache for virtual subclasses. The token changes with every call to <a class="reference internal" href="#abc.ABCMeta.register" title="abc.ABCMeta.register"><code>ABCMeta.register()</code></a> on any ABC.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="abc.update_abstractmethods">
+<code>abc.update_abstractmethods(cls)</code> </dt> <dd>
+<p>A function to recalculate an abstract class’s abstraction status. This function should be called if a class’s abstract methods have been implemented or changed after it was created. Usually, this function should be called from within a class decorator.</p> <p>Returns <em>cls</em>, to allow usage as a class decorator.</p> <p>If <em>cls</em> is not an instance of <a class="reference internal" href="#abc.ABCMeta" title="abc.ABCMeta"><code>ABCMeta</code></a>, does nothing.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This function assumes that <em>cls</em>’s superclasses are already updated. It does not update any subclasses.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
+</dl> <h4 class="rubric">Footnotes</h4> <dl class="footnote brackets"> <dt class="label" id="id2">
+<code>1</code> </dt> <dd>
+<p>C++ programmers should note that Python’s virtual base class concept is not the same as C++’s.</p> </dd> </dl> <div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
+    <a href="https://docs.python.org/3.12/library/abc.html" class="_attribution-link">https://docs.python.org/3.12/library/abc.html</a>
+  </p>
+</div>