File: //usr/share/doc/python3-all/html/library/collections.abc.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>collections.abc — Abstract Base Classes for Containers — Python 3.10.12 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?2022.1" />
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.10.12 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="heapq — Heap queue algorithm" href="heapq.html" />
<link rel="prev" title="collections — Container datatypes" href="collections.html" />
<link rel="canonical" href="file:///usr/share/doc/python3.10/html/library/collections.abc.html" />
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<nav class="nav-content" role="navigation">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Logo"/>
</a>
<div class="version_switcher_placeholder"></div>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero"
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
</svg>
<input type="text" name="q" aria-label="Quick search"/>
<input type="submit" value="Go"/>
</form>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code> — Abstract Base Classes for Containers</a><ul>
<li><a class="reference internal" href="#collections-abstract-base-classes">Collections Abstract Base Classes</a></li>
<li><a class="reference internal" href="#collections-abstract-base-classes-detailed-descriptions">Collections Abstract Base Classes – Detailed Descriptions</a></li>
<li><a class="reference internal" href="#examples-and-recipes">Examples and Recipes</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="collections.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections</span></code> — Container datatypes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="heapq.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">heapq</span></code> — Heap queue algorithm</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.10/Doc/library/collections.abc.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="heapq.html" title="heapq — Heap queue algorithm"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="collections.html" title="collections — Container datatypes"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.10.12 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="datatypes.html" accesskey="U">Data Types</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code> — Abstract Base Classes for Containers</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-collections.abc">
<span id="collections-abc-abstract-base-classes-for-containers"></span><h1><a class="reference internal" href="#module-collections.abc" title="collections.abc: Abstract base classes for containers"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code></a> — Abstract Base Classes for Containers<a class="headerlink" href="#module-collections.abc" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.3: </span>Formerly, this module was part of the <a class="reference internal" href="collections.html#module-collections" title="collections: Container datatypes"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections</span></code></a> module.</p>
</div>
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.10/Lib/_collections_abc.py">Lib/_collections_abc.py</a></p>
<hr class="docutils" />
<p>This module provides <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base classes</span></a> that
can be used to test whether a class provides a particular interface; for
example, whether it is <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a> or whether it is a mapping.</p>
<p>An <a class="reference internal" href="functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">issubclass()</span></code></a> or <a class="reference internal" href="functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a> test for an interface works in one
of three ways.</p>
<p>1) A newly written class can inherit directly from one of the
abstract base classes. The class must supply the required abstract
methods. The remaining mixin methods come from inheritance and can be
overridden if desired. Other methods may be added as needed:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">C</span><span class="p">(</span><span class="n">Sequence</span><span class="p">):</span> <span class="c1"># Direct inheritance</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># Extra method not required by the ABC</span>
<span class="k">def</span> <span class="fm">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">index</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># Required abstract method</span>
<span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># Required abstract method</span>
<span class="k">def</span> <span class="nf">count</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># Optionally override a mixin method</span>
</pre></div>
</div>
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">issubclass</span><span class="p">(</span><span class="n">C</span><span class="p">,</span> <span class="n">Sequence</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">C</span><span class="p">(),</span> <span class="n">Sequence</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
<p>2) Existing classes and built-in classes can be registered as “virtual
subclasses” of the ABCs. Those classes should define the full API
including all of the abstract methods and all of the mixin methods.
This lets users rely on <a class="reference internal" href="functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">issubclass()</span></code></a> or <a class="reference internal" href="functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a> tests
to determine whether the full interface is supported. The exception to
this rule is for methods that are automatically inferred from the rest
of the API:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">D</span><span class="p">:</span> <span class="c1"># No inheritance</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># Extra method not required by the ABC</span>
<span class="k">def</span> <span class="fm">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">index</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># Abstract method</span>
<span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># Abstract method</span>
<span class="k">def</span> <span class="nf">count</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># Mixin method</span>
<span class="k">def</span> <span class="nf">index</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># Mixin method</span>
<span class="n">Sequence</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="n">D</span><span class="p">)</span> <span class="c1"># Register instead of inherit</span>
</pre></div>
</div>
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">issubclass</span><span class="p">(</span><span class="n">D</span><span class="p">,</span> <span class="n">Sequence</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">D</span><span class="p">(),</span> <span class="n">Sequence</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
<p>In this example, class <code class="xref py py-class docutils literal notranslate"><span class="pre">D</span></code> does not need to define
<code class="docutils literal notranslate"><span class="pre">__contains__</span></code>, <code class="docutils literal notranslate"><span class="pre">__iter__</span></code>, and <code class="docutils literal notranslate"><span class="pre">__reversed__</span></code> because the
<a class="reference internal" href="../reference/expressions.html#comparisons"><span class="std std-ref">in-operator</span></a>, the <a class="reference internal" href="../glossary.html#term-iterable"><span class="xref std std-term">iteration</span></a>
logic, and the <a class="reference internal" href="functions.html#reversed" title="reversed"><code class="xref py py-func docutils literal notranslate"><span class="pre">reversed()</span></code></a> function automatically fall back to
using <code class="docutils literal notranslate"><span class="pre">__getitem__</span></code> and <code class="docutils literal notranslate"><span class="pre">__len__</span></code>.</p>
<p>3) Some simple interfaces are directly recognizable by the presence of
the required methods (unless those methods have been set to
<a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>):</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">E</span><span class="p">:</span>
<span class="k">def</span> <span class="fm">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
<span class="k">def</span> <span class="fm">__next__</span><span class="p">(</span><span class="nb">next</span><span class="p">):</span> <span class="o">...</span>
</pre></div>
</div>
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">issubclass</span><span class="p">(</span><span class="n">E</span><span class="p">,</span> <span class="n">Iterable</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">E</span><span class="p">(),</span> <span class="n">Iterable</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Complex interfaces do not support this last technique because an
interface is more than just the presence of method names. Interfaces
specify semantics and relationships between methods that cannot be
inferred solely from the presence of specific method names. For
example, knowing that a class supplies <code class="docutils literal notranslate"><span class="pre">__getitem__</span></code>, <code class="docutils literal notranslate"><span class="pre">__len__</span></code>, and
<code class="docutils literal notranslate"><span class="pre">__iter__</span></code> is insufficient for distinguishing a <a class="reference internal" href="#collections.abc.Sequence" title="collections.abc.Sequence"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sequence</span></code></a> from
a <a class="reference internal" href="#collections.abc.Mapping" title="collections.abc.Mapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mapping</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.9: </span>These abstract classes now support <code class="docutils literal notranslate"><span class="pre">[]</span></code>. See <a class="reference internal" href="stdtypes.html#types-genericalias"><span class="std std-ref">Generic Alias Type</span></a>
and <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0585"><strong>PEP 585</strong></a>.</p>
</div>
<section id="collections-abstract-base-classes">
<span id="id1"></span><h2>Collections Abstract Base Classes<a class="headerlink" href="#collections-abstract-base-classes" title="Permalink to this headline">¶</a></h2>
<p>The collections module offers the following <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">ABCs</span></a>:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 24%" />
<col style="width: 17%" />
<col style="width: 18%" />
<col style="width: 41%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>ABC</p></th>
<th class="head"><p>Inherits from</p></th>
<th class="head"><p>Abstract Methods</p></th>
<th class="head"><p>Mixin Methods</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.Container" title="collections.abc.Container"><code class="xref py py-class docutils literal notranslate"><span class="pre">Container</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id2">1</a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.Hashable" title="collections.abc.Hashable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Hashable</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id3">1</a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__hash__</span></code></p></td>
<td></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.Iterable" title="collections.abc.Iterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterable</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id4">1</a> <a class="footnote-reference brackets" href="#id18" id="id5">2</a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__iter__</span></code></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.Iterator" title="collections.abc.Iterator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterator</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id6">1</a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Iterable" title="collections.abc.Iterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterable</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__next__</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__iter__</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.Reversible" title="collections.abc.Reversible"><code class="xref py py-class docutils literal notranslate"><span class="pre">Reversible</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id7">1</a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Iterable" title="collections.abc.Iterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterable</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__reversed__</span></code></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.Generator" title="collections.abc.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id8">1</a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Iterator" title="collections.abc.Iterator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterator</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">send</span></code>, <code class="docutils literal notranslate"><span class="pre">throw</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">close</span></code>, <code class="docutils literal notranslate"><span class="pre">__iter__</span></code>, <code class="docutils literal notranslate"><span class="pre">__next__</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.Sized" title="collections.abc.Sized"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sized</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id9">1</a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__len__</span></code></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.Callable" title="collections.abc.Callable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Callable</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id10">1</a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__call__</span></code></p></td>
<td></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.Collection" title="collections.abc.Collection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Collection</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id11">1</a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Sized" title="collections.abc.Sized"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sized</span></code></a>,
<a class="reference internal" href="#collections.abc.Iterable" title="collections.abc.Iterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterable</span></code></a>,
<a class="reference internal" href="#collections.abc.Container" title="collections.abc.Container"><code class="xref py py-class docutils literal notranslate"><span class="pre">Container</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__iter__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__len__</span></code></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.Sequence" title="collections.abc.Sequence"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sequence</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Reversible" title="collections.abc.Reversible"><code class="xref py py-class docutils literal notranslate"><span class="pre">Reversible</span></code></a>,
<a class="reference internal" href="#collections.abc.Collection" title="collections.abc.Collection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Collection</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__getitem__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__len__</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code>, <code class="docutils literal notranslate"><span class="pre">__iter__</span></code>, <code class="docutils literal notranslate"><span class="pre">__reversed__</span></code>,
<code class="docutils literal notranslate"><span class="pre">index</span></code>, and <code class="docutils literal notranslate"><span class="pre">count</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.MutableSequence" title="collections.abc.MutableSequence"><code class="xref py py-class docutils literal notranslate"><span class="pre">MutableSequence</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Sequence" title="collections.abc.Sequence"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sequence</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__getitem__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__setitem__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__delitem__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__len__</span></code>,
<code class="docutils literal notranslate"><span class="pre">insert</span></code></p></td>
<td><p>Inherited <a class="reference internal" href="#collections.abc.Sequence" title="collections.abc.Sequence"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sequence</span></code></a> methods and
<code class="docutils literal notranslate"><span class="pre">append</span></code>, <code class="docutils literal notranslate"><span class="pre">reverse</span></code>, <code class="docutils literal notranslate"><span class="pre">extend</span></code>, <code class="docutils literal notranslate"><span class="pre">pop</span></code>,
<code class="docutils literal notranslate"><span class="pre">remove</span></code>, and <code class="docutils literal notranslate"><span class="pre">__iadd__</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.ByteString" title="collections.abc.ByteString"><code class="xref py py-class docutils literal notranslate"><span class="pre">ByteString</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Sequence" title="collections.abc.Sequence"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sequence</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__getitem__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__len__</span></code></p></td>
<td><p>Inherited <a class="reference internal" href="#collections.abc.Sequence" title="collections.abc.Sequence"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sequence</span></code></a> methods</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Collection" title="collections.abc.Collection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Collection</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__iter__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__len__</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__le__</span></code>, <code class="docutils literal notranslate"><span class="pre">__lt__</span></code>, <code class="docutils literal notranslate"><span class="pre">__eq__</span></code>, <code class="docutils literal notranslate"><span class="pre">__ne__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__gt__</span></code>, <code class="docutils literal notranslate"><span class="pre">__ge__</span></code>, <code class="docutils literal notranslate"><span class="pre">__and__</span></code>, <code class="docutils literal notranslate"><span class="pre">__or__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__sub__</span></code>, <code class="docutils literal notranslate"><span class="pre">__xor__</span></code>, and <code class="docutils literal notranslate"><span class="pre">isdisjoint</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.MutableSet" title="collections.abc.MutableSet"><code class="xref py py-class docutils literal notranslate"><span class="pre">MutableSet</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__iter__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__len__</span></code>,
<code class="docutils literal notranslate"><span class="pre">add</span></code>,
<code class="docutils literal notranslate"><span class="pre">discard</span></code></p></td>
<td><p>Inherited <a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a> methods and
<code class="docutils literal notranslate"><span class="pre">clear</span></code>, <code class="docutils literal notranslate"><span class="pre">pop</span></code>, <code class="docutils literal notranslate"><span class="pre">remove</span></code>, <code class="docutils literal notranslate"><span class="pre">__ior__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__iand__</span></code>, <code class="docutils literal notranslate"><span class="pre">__ixor__</span></code>, and <code class="docutils literal notranslate"><span class="pre">__isub__</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.Mapping" title="collections.abc.Mapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mapping</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Collection" title="collections.abc.Collection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Collection</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__getitem__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__iter__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__len__</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code>, <code class="docutils literal notranslate"><span class="pre">keys</span></code>, <code class="docutils literal notranslate"><span class="pre">items</span></code>, <code class="docutils literal notranslate"><span class="pre">values</span></code>,
<code class="docutils literal notranslate"><span class="pre">get</span></code>, <code class="docutils literal notranslate"><span class="pre">__eq__</span></code>, and <code class="docutils literal notranslate"><span class="pre">__ne__</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.MutableMapping" title="collections.abc.MutableMapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">MutableMapping</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Mapping" title="collections.abc.Mapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mapping</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__getitem__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__setitem__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__delitem__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__iter__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__len__</span></code></p></td>
<td><p>Inherited <a class="reference internal" href="#collections.abc.Mapping" title="collections.abc.Mapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mapping</span></code></a> methods and
<code class="docutils literal notranslate"><span class="pre">pop</span></code>, <code class="docutils literal notranslate"><span class="pre">popitem</span></code>, <code class="docutils literal notranslate"><span class="pre">clear</span></code>, <code class="docutils literal notranslate"><span class="pre">update</span></code>,
and <code class="docutils literal notranslate"><span class="pre">setdefault</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.MappingView" title="collections.abc.MappingView"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappingView</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Sized" title="collections.abc.Sized"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sized</span></code></a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__len__</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.ItemsView" title="collections.abc.ItemsView"><code class="xref py py-class docutils literal notranslate"><span class="pre">ItemsView</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.MappingView" title="collections.abc.MappingView"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappingView</span></code></a>,
<a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__iter__</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.KeysView" title="collections.abc.KeysView"><code class="xref py py-class docutils literal notranslate"><span class="pre">KeysView</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.MappingView" title="collections.abc.MappingView"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappingView</span></code></a>,
<a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code>,
<code class="docutils literal notranslate"><span class="pre">__iter__</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.ValuesView" title="collections.abc.ValuesView"><code class="xref py py-class docutils literal notranslate"><span class="pre">ValuesView</span></code></a></p></td>
<td><p><a class="reference internal" href="#collections.abc.MappingView" title="collections.abc.MappingView"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappingView</span></code></a>,
<a class="reference internal" href="#collections.abc.Collection" title="collections.abc.Collection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Collection</span></code></a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code>, <code class="docutils literal notranslate"><span class="pre">__iter__</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.Awaitable" title="collections.abc.Awaitable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Awaitable</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id12">1</a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__await__</span></code></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.Coroutine" title="collections.abc.Coroutine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Coroutine</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id13">1</a></p></td>
<td><p><a class="reference internal" href="#collections.abc.Awaitable" title="collections.abc.Awaitable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Awaitable</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">send</span></code>, <code class="docutils literal notranslate"><span class="pre">throw</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">close</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.AsyncIterable" title="collections.abc.AsyncIterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncIterable</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id14">1</a></p></td>
<td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__aiter__</span></code></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#collections.abc.AsyncIterator" title="collections.abc.AsyncIterator"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncIterator</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id15">1</a></p></td>
<td><p><a class="reference internal" href="#collections.abc.AsyncIterable" title="collections.abc.AsyncIterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncIterable</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__anext__</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">__aiter__</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#collections.abc.AsyncGenerator" title="collections.abc.AsyncGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncGenerator</span></code></a> <a class="footnote-reference brackets" href="#id17" id="id16">1</a></p></td>
<td><p><a class="reference internal" href="#collections.abc.AsyncIterator" title="collections.abc.AsyncIterator"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncIterator</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">asend</span></code>, <code class="docutils literal notranslate"><span class="pre">athrow</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">aclose</span></code>, <code class="docutils literal notranslate"><span class="pre">__aiter__</span></code>, <code class="docutils literal notranslate"><span class="pre">__anext__</span></code></p></td>
</tr>
</tbody>
</table>
<p class="rubric">Footnotes</p>
<dl class="footnote brackets">
<dt class="label" id="id17"><span class="brackets">1</span><span class="fn-backref">(<a href="#id2">1</a>,<a href="#id3">2</a>,<a href="#id4">3</a>,<a href="#id6">4</a>,<a href="#id7">5</a>,<a href="#id8">6</a>,<a href="#id9">7</a>,<a href="#id10">8</a>,<a href="#id11">9</a>,<a href="#id12">10</a>,<a href="#id13">11</a>,<a href="#id14">12</a>,<a href="#id15">13</a>,<a href="#id16">14</a>)</span></dt>
<dd><p>These ABCs override <code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__subclasshook__()</span></code> to support
testing an interface by verifying the required methods are present
and have not been set to <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>. This only works for simple
interfaces. More complex interfaces require registration or direct
subclassing.</p>
</dd>
<dt class="label" id="id18"><span class="brackets"><a class="fn-backref" href="#id5">2</a></span></dt>
<dd><p>Checking <code class="docutils literal notranslate"><span class="pre">isinstance(obj,</span> <span class="pre">Iterable)</span></code> detects classes that are
registered as <a class="reference internal" href="#collections.abc.Iterable" title="collections.abc.Iterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterable</span></code></a> or that have an <code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code>
method, but it does not detect classes that iterate with the
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code> method. The only reliable way to determine
whether an object is <a class="reference internal" href="../glossary.html#term-iterable"><span class="xref std std-term">iterable</span></a> is to call <code class="docutils literal notranslate"><span class="pre">iter(obj)</span></code>.</p>
</dd>
</dl>
</section>
<section id="collections-abstract-base-classes-detailed-descriptions">
<h2>Collections Abstract Base Classes – Detailed Descriptions<a class="headerlink" href="#collections-abstract-base-classes-detailed-descriptions" title="Permalink to this headline">¶</a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Container">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Container</span></span><a class="headerlink" href="#collections.abc.Container" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for classes that provide the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code> method.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Hashable">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Hashable</span></span><a class="headerlink" href="#collections.abc.Hashable" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for classes that provide the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> method.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Sized">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Sized</span></span><a class="headerlink" href="#collections.abc.Sized" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for classes that provide the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code> method.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Callable">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Callable</span></span><a class="headerlink" href="#collections.abc.Callable" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for classes that provide the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code> method.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Iterable">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Iterable</span></span><a class="headerlink" href="#collections.abc.Iterable" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for classes that provide the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code> method.</p>
<p>Checking <code class="docutils literal notranslate"><span class="pre">isinstance(obj,</span> <span class="pre">Iterable)</span></code> detects classes that are registered
as <a class="reference internal" href="#collections.abc.Iterable" title="collections.abc.Iterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterable</span></code></a> or that have an <code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code> method, but it does
not detect classes that iterate with the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code> method.
The only reliable way to determine whether an object is <a class="reference internal" href="../glossary.html#term-iterable"><span class="xref std std-term">iterable</span></a>
is to call <code class="docutils literal notranslate"><span class="pre">iter(obj)</span></code>.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Collection">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Collection</span></span><a class="headerlink" href="#collections.abc.Collection" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for sized iterable container classes.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.6.</span></p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Iterator">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Iterator</span></span><a class="headerlink" href="#collections.abc.Iterator" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for classes that provide the <a class="reference internal" href="stdtypes.html#iterator.__iter__" title="iterator.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> and
<a class="reference internal" href="stdtypes.html#iterator.__next__" title="iterator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a> methods. See also the definition of
<a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a>.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Reversible">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Reversible</span></span><a class="headerlink" href="#collections.abc.Reversible" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for iterable classes that also provide the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__reversed__()</span></code>
method.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.6.</span></p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Generator">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Generator</span></span><a class="headerlink" href="#collections.abc.Generator" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for generator classes that implement the protocol defined in
<span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0342"><strong>PEP 342</strong></a> that extends iterators with the <a class="reference internal" href="../reference/expressions.html#generator.send" title="generator.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a>,
<a class="reference internal" href="../reference/expressions.html#generator.throw" title="generator.throw"><code class="xref py py-meth docutils literal notranslate"><span class="pre">throw()</span></code></a> and <a class="reference internal" href="../reference/expressions.html#generator.close" title="generator.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> methods.
See also the definition of <a class="reference internal" href="../glossary.html#term-generator"><span class="xref std std-term">generator</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Sequence">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Sequence</span></span><a class="headerlink" href="#collections.abc.Sequence" title="Permalink to this definition">¶</a></dt>
<dt class="sig sig-object py" id="collections.abc.MutableSequence">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">MutableSequence</span></span><a class="headerlink" href="#collections.abc.MutableSequence" title="Permalink to this definition">¶</a></dt>
<dt class="sig sig-object py" id="collections.abc.ByteString">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">ByteString</span></span><a class="headerlink" href="#collections.abc.ByteString" title="Permalink to this definition">¶</a></dt>
<dd><p>ABCs for read-only and mutable <a class="reference internal" href="../glossary.html#term-sequence"><span class="xref std std-term">sequences</span></a>.</p>
<p>Implementation note: Some of the mixin methods, such as
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__reversed__()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">index()</span></code>, make
repeated calls to the underlying <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code> method.
Consequently, if <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code> is implemented with constant
access speed, the mixin methods will have linear performance;
however, if the underlying method is linear (as it would be with a
linked list), the mixins will have quadratic performance and will
likely need to be overridden.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.5: </span>The index() method added support for <em>stop</em> and <em>start</em>
arguments.</p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Set">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Set</span></span><a class="headerlink" href="#collections.abc.Set" title="Permalink to this definition">¶</a></dt>
<dt class="sig sig-object py" id="collections.abc.MutableSet">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">MutableSet</span></span><a class="headerlink" href="#collections.abc.MutableSet" title="Permalink to this definition">¶</a></dt>
<dd><p>ABCs for read-only and mutable sets.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Mapping">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Mapping</span></span><a class="headerlink" href="#collections.abc.Mapping" title="Permalink to this definition">¶</a></dt>
<dt class="sig sig-object py" id="collections.abc.MutableMapping">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">MutableMapping</span></span><a class="headerlink" href="#collections.abc.MutableMapping" title="Permalink to this definition">¶</a></dt>
<dd><p>ABCs for read-only and mutable <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mappings</span></a>.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.MappingView">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">MappingView</span></span><a class="headerlink" href="#collections.abc.MappingView" title="Permalink to this definition">¶</a></dt>
<dt class="sig sig-object py" id="collections.abc.ItemsView">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">ItemsView</span></span><a class="headerlink" href="#collections.abc.ItemsView" title="Permalink to this definition">¶</a></dt>
<dt class="sig sig-object py" id="collections.abc.KeysView">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">KeysView</span></span><a class="headerlink" href="#collections.abc.KeysView" title="Permalink to this definition">¶</a></dt>
<dt class="sig sig-object py" id="collections.abc.ValuesView">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">ValuesView</span></span><a class="headerlink" href="#collections.abc.ValuesView" title="Permalink to this definition">¶</a></dt>
<dd><p>ABCs for mapping, items, keys, and values <a class="reference internal" href="../glossary.html#term-dictionary-view"><span class="xref std std-term">views</span></a>.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Awaitable">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Awaitable</span></span><a class="headerlink" href="#collections.abc.Awaitable" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for <a class="reference internal" href="../glossary.html#term-awaitable"><span class="xref std std-term">awaitable</span></a> objects, which can be used in <a class="reference internal" href="../reference/expressions.html#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a>
expressions. Custom implementations must provide the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code>
method.</p>
<p><a class="reference internal" href="../glossary.html#term-coroutine"><span class="xref std std-term">Coroutine</span></a> objects and instances of the
<a class="reference internal" href="#collections.abc.Coroutine" title="collections.abc.Coroutine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Coroutine</span></code></a> ABC are all instances of this ABC.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>In CPython, generator-based coroutines (generators decorated with
<a class="reference internal" href="types.html#types.coroutine" title="types.coroutine"><code class="xref py py-func docutils literal notranslate"><span class="pre">types.coroutine()</span></code></a> or <a class="reference internal" href="asyncio-task.html#asyncio.coroutine" title="asyncio.coroutine"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.coroutine()</span></code></a>) are
<em>awaitables</em>, even though they do not have an <code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code> method.
Using <code class="docutils literal notranslate"><span class="pre">isinstance(gencoro,</span> <span class="pre">Awaitable)</span></code> for them will return <code class="docutils literal notranslate"><span class="pre">False</span></code>.
Use <a class="reference internal" href="inspect.html#inspect.isawaitable" title="inspect.isawaitable"><code class="xref py py-func docutils literal notranslate"><span class="pre">inspect.isawaitable()</span></code></a> to detect them.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.Coroutine">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">Coroutine</span></span><a class="headerlink" href="#collections.abc.Coroutine" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for coroutine compatible classes. These implement the
following methods, defined in <a class="reference internal" href="../reference/datamodel.html#coroutine-objects"><span class="std std-ref">Coroutine Objects</span></a>:
<a class="reference internal" href="../reference/datamodel.html#coroutine.send" title="coroutine.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#coroutine.throw" title="coroutine.throw"><code class="xref py py-meth docutils literal notranslate"><span class="pre">throw()</span></code></a>, and
<a class="reference internal" href="../reference/datamodel.html#coroutine.close" title="coroutine.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a>. Custom implementations must also implement
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code>. All <a class="reference internal" href="#collections.abc.Coroutine" title="collections.abc.Coroutine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Coroutine</span></code></a> instances are also instances of
<a class="reference internal" href="#collections.abc.Awaitable" title="collections.abc.Awaitable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Awaitable</span></code></a>. See also the definition of <a class="reference internal" href="../glossary.html#term-coroutine"><span class="xref std std-term">coroutine</span></a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>In CPython, generator-based coroutines (generators decorated with
<a class="reference internal" href="types.html#types.coroutine" title="types.coroutine"><code class="xref py py-func docutils literal notranslate"><span class="pre">types.coroutine()</span></code></a> or <a class="reference internal" href="asyncio-task.html#asyncio.coroutine" title="asyncio.coroutine"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.coroutine()</span></code></a>) are
<em>awaitables</em>, even though they do not have an <code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code> method.
Using <code class="docutils literal notranslate"><span class="pre">isinstance(gencoro,</span> <span class="pre">Coroutine)</span></code> for them will return <code class="docutils literal notranslate"><span class="pre">False</span></code>.
Use <a class="reference internal" href="inspect.html#inspect.isawaitable" title="inspect.isawaitable"><code class="xref py py-func docutils literal notranslate"><span class="pre">inspect.isawaitable()</span></code></a> to detect them.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.AsyncIterable">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">AsyncIterable</span></span><a class="headerlink" href="#collections.abc.AsyncIterable" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for classes that provide <code class="docutils literal notranslate"><span class="pre">__aiter__</span></code> method. See also the
definition of <a class="reference internal" href="../glossary.html#term-asynchronous-iterable"><span class="xref std std-term">asynchronous iterable</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.AsyncIterator">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">AsyncIterator</span></span><a class="headerlink" href="#collections.abc.AsyncIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for classes that provide <code class="docutils literal notranslate"><span class="pre">__aiter__</span></code> and <code class="docutils literal notranslate"><span class="pre">__anext__</span></code>
methods. See also the definition of <a class="reference internal" href="../glossary.html#term-asynchronous-iterator"><span class="xref std std-term">asynchronous iterator</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="collections.abc.AsyncGenerator">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">collections.abc.</span></span><span class="sig-name descname"><span class="pre">AsyncGenerator</span></span><a class="headerlink" href="#collections.abc.AsyncGenerator" title="Permalink to this definition">¶</a></dt>
<dd><p>ABC for asynchronous generator classes that implement the protocol
defined in <span class="target" id="index-2"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0525"><strong>PEP 525</strong></a> and <span class="target" id="index-3"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0492"><strong>PEP 492</strong></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.6.</span></p>
</div>
</dd></dl>
</section>
<section id="examples-and-recipes">
<h2>Examples and Recipes<a class="headerlink" href="#examples-and-recipes" title="Permalink to this headline">¶</a></h2>
<p>ABCs allow us to ask classes or instances if they provide
particular functionality, for example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">size</span> <span class="o">=</span> <span class="kc">None</span>
<span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">myvar</span><span class="p">,</span> <span class="n">collections</span><span class="o">.</span><span class="n">abc</span><span class="o">.</span><span class="n">Sized</span><span class="p">):</span>
<span class="n">size</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">myvar</span><span class="p">)</span>
</pre></div>
</div>
<p>Several of the ABCs are also useful as mixins that make it easier to develop
classes supporting container APIs. For example, to write a class supporting
the full <a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a> API, it is only necessary to supply the three underlying
abstract methods: <code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code>, and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code>.
The ABC supplies the remaining methods such as <code class="xref py py-meth docutils literal notranslate"><span class="pre">__and__()</span></code> and
<code class="xref py py-meth docutils literal notranslate"><span class="pre">isdisjoint()</span></code>:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ListBasedSet</span><span class="p">(</span><span class="n">collections</span><span class="o">.</span><span class="n">abc</span><span class="o">.</span><span class="n">Set</span><span class="p">):</span>
<span class="sd">''' Alternate set implementation favoring space over speed</span>
<span class="sd"> and not requiring the set elements to be hashable. '''</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">elements</span> <span class="o">=</span> <span class="n">lst</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span>
<span class="k">if</span> <span class="n">value</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">lst</span><span class="p">:</span>
<span class="n">lst</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<span class="k">def</span> <span class="fm">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="nb">iter</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">elements</span><span class="p">)</span>
<span class="k">def</span> <span class="fm">__contains__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
<span class="k">return</span> <span class="n">value</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">elements</span>
<span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">elements</span><span class="p">)</span>
<span class="n">s1</span> <span class="o">=</span> <span class="n">ListBasedSet</span><span class="p">(</span><span class="s1">'abcdef'</span><span class="p">)</span>
<span class="n">s2</span> <span class="o">=</span> <span class="n">ListBasedSet</span><span class="p">(</span><span class="s1">'defghi'</span><span class="p">)</span>
<span class="n">overlap</span> <span class="o">=</span> <span class="n">s1</span> <span class="o">&</span> <span class="n">s2</span> <span class="c1"># The __and__() method is supported automatically</span>
</pre></div>
</div>
<p>Notes on using <a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a> and <a class="reference internal" href="#collections.abc.MutableSet" title="collections.abc.MutableSet"><code class="xref py py-class docutils literal notranslate"><span class="pre">MutableSet</span></code></a> as a mixin:</p>
<ol class="arabic simple">
<li><p>Since some set operations create new sets, the default mixin methods need
a way to create new instances from an iterable. The class constructor is
assumed to have a signature in the form <code class="docutils literal notranslate"><span class="pre">ClassName(iterable)</span></code>.
That assumption is factored-out to an internal classmethod called
<code class="xref py py-meth docutils literal notranslate"><span class="pre">_from_iterable()</span></code> which calls <code class="docutils literal notranslate"><span class="pre">cls(iterable)</span></code> to produce a new set.
If the <a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a> mixin is being used in a class with a different
constructor signature, you will need to override <code class="xref py py-meth docutils literal notranslate"><span class="pre">_from_iterable()</span></code>
with a classmethod or regular method that can construct new instances from
an iterable argument.</p></li>
<li><p>To override the comparisons (presumably for speed, as the
semantics are fixed), redefine <code class="xref py py-meth docutils literal notranslate"><span class="pre">__le__()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__ge__()</span></code>,
then the other operations will automatically follow suit.</p></li>
<li><p>The <a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a> mixin provides a <code class="xref py py-meth docutils literal notranslate"><span class="pre">_hash()</span></code> method to compute a hash value
for the set; however, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> is not defined because not all sets
are <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a> or immutable. To add set hashability using mixins,
inherit from both <a class="reference internal" href="#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Set()</span></code></a> and <a class="reference internal" href="#collections.abc.Hashable" title="collections.abc.Hashable"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Hashable()</span></code></a>, then define
<code class="docutils literal notranslate"><span class="pre">__hash__</span> <span class="pre">=</span> <span class="pre">Set._hash</span></code>.</p></li>
</ol>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<ul class="simple">
<li><p><a class="reference external" href="https://code.activestate.com/recipes/576694/">OrderedSet recipe</a> for an
example built on <a class="reference internal" href="#collections.abc.MutableSet" title="collections.abc.MutableSet"><code class="xref py py-class docutils literal notranslate"><span class="pre">MutableSet</span></code></a>.</p></li>
<li><p>For more about ABCs, see the <a class="reference internal" href="abc.html#module-abc" title="abc: Abstract base classes according to :pep:`3119`."><code class="xref py py-mod docutils literal notranslate"><span class="pre">abc</span></code></a> module and <span class="target" id="index-4"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-3119"><strong>PEP 3119</strong></a>.</p></li>
</ul>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code> — Abstract Base Classes for Containers</a><ul>
<li><a class="reference internal" href="#collections-abstract-base-classes">Collections Abstract Base Classes</a></li>
<li><a class="reference internal" href="#collections-abstract-base-classes-detailed-descriptions">Collections Abstract Base Classes – Detailed Descriptions</a></li>
<li><a class="reference internal" href="#examples-and-recipes">Examples and Recipes</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="collections.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections</span></code> — Container datatypes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="heapq.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">heapq</span></code> — Heap queue algorithm</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.10/Doc/library/collections.abc.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="heapq.html" title="heapq — Heap queue algorithm"
>next</a> |</li>
<li class="right" >
<a href="collections.html" title="collections — Container datatypes"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.10.12 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="datatypes.html" >Data Types</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code> — Abstract Base Classes for Containers</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001-2025, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
See <a href="/license.html">History and License</a> for more information.<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
Last updated on August 15, 2025.
<a href="/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.3.2.
</div>
</body>
</html>