feat(assessment): auto comprehensive assessment - rules engine from college scoring standard, per-semester stats, manual overrides, word export

This commit is contained in:
root
2026-10-17 15:40:07 +08:00
parent a0e2ded426
commit 49d8400722
2395 changed files with 1306906 additions and 94 deletions
@@ -0,0 +1,485 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Built-in Constants" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/builtins/constants.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="A small number of constants live in the built-in namespace. They are: Constants added by the site module: The site module (which is imported automatically during startup, except if the-S command-li..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="A small number of constants live in the built-in namespace. They are: Constants added by the site module: The site module (which is imported automatically during startup, except if the-S command-li..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>Built-in Constants &#8212; Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0 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="Built-in functions" href="functions.html" />
<link rel="prev" title="Built-in Types" href="stdtypes.html" />
<link rel="canonical" href="https://docs.python.org/3/builtins/constants.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<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>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</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">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<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" fill="currentColor" 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"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Built-in Constants</a><ul>
<li><a class="reference internal" href="#constants-added-by-the-site-module">Constants added by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> module</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="stdtypes.html"
title="previous chapter">Built-in Types</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="functions.html"
title="next chapter">Built-in functions</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "builtins/constants.rst");
element.href = url.toString();
});
});
</script>
<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 class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/builtins/constants.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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="functions.html" title="Built-in functions"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="stdtypes.html" title="Built-in Types"
accesskey="P">previous</a> |</li>
<li class="root-icon"><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> &#187;</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.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python built-ins reference</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Built-in Constants</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="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="built-in-constants">
<span id="built-in-consts"></span><h1>Built-in Constants<a class="headerlink" href="#built-in-constants" title="Link to this heading"></a></h1>
<p>A small number of constants live in the built-in namespace. They are:</p>
<dl class="py data">
<dt class="sig sig-object py" id="False">
<span class="sig-name descname"><span class="pre">False</span></span><a class="headerlink" href="#False" title="Link to this definition"></a></dt>
<dd><p>The false value of the <a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a> type. Assignments to <code class="docutils literal notranslate"><span class="pre">False</span></code>
are illegal and raise a <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a>.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="True">
<span class="sig-name descname"><span class="pre">True</span></span><a class="headerlink" href="#True" title="Link to this definition"></a></dt>
<dd><p>The true value of the <a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a> type. Assignments to <code class="docutils literal notranslate"><span class="pre">True</span></code>
are illegal and raise a <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a>.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="None">
<span class="sig-name descname"><span class="pre">None</span></span><a class="headerlink" href="#None" title="Link to this definition"></a></dt>
<dd><p>An object frequently used to represent the absence of a value, as when
default arguments are not passed to a function. Assignments to <code class="docutils literal notranslate"><span class="pre">None</span></code>
are illegal and raise a <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a>.
<code class="docutils literal notranslate"><span class="pre">None</span></code> is the sole instance of the <a class="reference internal" href="../library/types.html#types.NoneType" title="types.NoneType"><code class="xref py py-class docutils literal notranslate"><span class="pre">NoneType</span></code></a> type.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="NotImplemented">
<span class="sig-name descname"><span class="pre">NotImplemented</span></span><a class="headerlink" href="#NotImplemented" title="Link to this definition"></a></dt>
<dd><p>A special value which should be returned by the binary special methods
(e.g. <a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__lt__" title="object.__lt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__lt__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__rsub__" title="object.__rsub__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rsub__()</span></code></a>,
etc.) to indicate that the operation is not implemented with respect to
the other type; may be returned by the in-place binary special methods
(e.g. <a class="reference internal" href="../reference/datamodel.html#object.__imul__" title="object.__imul__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__imul__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__iand__" title="object.__iand__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iand__()</span></code></a>, etc.) for the same purpose.
It should not be evaluated in a boolean context.
<code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code> is the sole instance of the <a class="reference internal" href="../library/types.html#types.NotImplementedType" title="types.NotImplementedType"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.NotImplementedType</span></code></a> type.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When a binary (or in-place) method returns <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code> the
interpreter will try the reflected operation on the other type (or some
other fallback, depending on the operator). If all attempts return
<code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code>, the interpreter will raise an appropriate exception.
Incorrectly returning <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code> will result in a misleading
error message or the <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code> value being returned to Python code.</p>
<p>See <a class="reference internal" href="../library/numbers.html#implementing-the-arithmetic-operations"><span class="std std-ref">Implementing the arithmetic operations</span></a> for examples.</p>
</div>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code> and <code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code> are not
interchangeable. This constant should only be used as described
above; see <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a> for details on correct usage
of the exception.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.9: </span>Evaluating <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code> in a boolean context was deprecated.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span>Evaluating <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code> in a boolean context now raises a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.
It previously evaluated to <a class="reference internal" href="#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> and emitted a <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a>
since Python 3.9.</p>
</div>
</dd></dl>
<dl class="py data" id="index-0">
<dt class="sig sig-object py" id="Ellipsis">
<span class="sig-name descname"><span class="pre">Ellipsis</span></span><a class="headerlink" href="#Ellipsis" title="Link to this definition"></a></dt>
<dd><p>The same as the ellipsis literal “<code class="docutils literal notranslate"><span class="pre">...</span></code>”, an object frequently used to
indicate that something is omitted. Assignment to <code class="docutils literal notranslate"><span class="pre">Ellipsis</span></code> is possible, but
assignment to <code class="docutils literal notranslate"><span class="pre">...</span></code> raises a <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a>.
<code class="docutils literal notranslate"><span class="pre">Ellipsis</span></code> is the sole instance of the <a class="reference internal" href="../library/types.html#types.EllipsisType" title="types.EllipsisType"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.EllipsisType</span></code></a> type.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="debug__">
<span class="sig-name descname"><span class="pre">__debug__</span></span><a class="headerlink" href="#debug__" title="Link to this definition"></a></dt>
<dd><p>This constant is true if Python was not started with an <a class="reference internal" href="../using/cmdline.html#cmdoption-O"><code class="xref std std-option docutils literal notranslate"><span class="pre">-O</span></code></a> option.
See also the <a class="reference internal" href="../reference/simple_stmts.html#assert"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">assert</span></code></a> statement.</p>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The names <a class="reference internal" href="#None" title="None"><code class="xref py py-data docutils literal notranslate"><span class="pre">None</span></code></a>, <a class="reference internal" href="#False" title="False"><code class="xref py py-data docutils literal notranslate"><span class="pre">False</span></code></a>, <a class="reference internal" href="#True" title="True"><code class="xref py py-data docutils literal notranslate"><span class="pre">True</span></code></a> and <a class="reference internal" href="#debug__" title="__debug__"><code class="xref py py-data docutils literal notranslate"><span class="pre">__debug__</span></code></a>
cannot be reassigned (assignments to them, even as an attribute name, raise
<a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a>), so they can be considered “true” constants.</p>
</div>
<section id="constants-added-by-the-site-module">
<span id="site-consts"></span><h2>Constants added by the <a class="reference internal" href="../library/site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> module<a class="headerlink" href="#constants-added-by-the-site-module" title="Link to this heading"></a></h2>
<p>The <a class="reference internal" href="../library/site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> module (which is imported automatically during startup, except
if the <a class="reference internal" href="../using/cmdline.html#cmdoption-S"><code class="xref std std-option docutils literal notranslate"><span class="pre">-S</span></code></a> command-line option is given) adds several constants to the
built-in namespace. They are useful for the interactive interpreter shell and
should not be used in programs.</p>
<dl class="py data">
<dt class="sig sig-object py" id="quit">
<span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">code</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#quit" title="Link to this definition"></a></dt>
<dt class="sig sig-object py" id="exit">
<span class="sig-name descname"><span class="pre">exit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">code</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#exit" title="Link to this definition"></a></dt>
<dd><p>Objects that when printed, print a message like “Use quit() or Ctrl-D
(i.e. EOF) to exit”, and when accessed directly in the interactive
interpreter or called as functions, raise <a class="reference internal" href="exceptions.html#SystemExit" title="SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a> with the
specified exit code.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">help</span></span></dt>
<dd><p>Object that when printed, prints the message “Type help() for interactive
help, or help(object) for help about object.”, and when accessed directly
in the interactive interpreter, invokes the built-in help system
(see <a class="reference internal" href="functions.html#help" title="help"><code class="xref py py-func docutils literal notranslate"><span class="pre">help()</span></code></a>).</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="copyright">
<span class="sig-name descname"><span class="pre">copyright</span></span><a class="headerlink" href="#copyright" title="Link to this definition"></a></dt>
<dt class="sig sig-object py" id="credits">
<span class="sig-name descname"><span class="pre">credits</span></span><a class="headerlink" href="#credits" title="Link to this definition"></a></dt>
<dd><p>Objects that when printed or called, print the text of copyright or
credits, respectively.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="license">
<span class="sig-name descname"><span class="pre">license</span></span><a class="headerlink" href="#license" title="Link to this definition"></a></dt>
<dd><p>Object that when printed, prints the message “Type license() to see the
full license text”, and when called, displays the full license text in a
pager-like fashion (one screen at a time).</p>
</dd></dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Built-in Constants</a><ul>
<li><a class="reference internal" href="#constants-added-by-the-site-module">Constants added by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> module</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="stdtypes.html"
title="previous chapter">Built-in Types</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="functions.html"
title="next chapter">Built-in functions</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "builtins/constants.rst");
element.href = url.toString();
});
});
</script>
<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 class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/builtins/constants.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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="functions.html" title="Built-in functions"
>next</a> |</li>
<li class="right" >
<a href="stdtypes.html" title="Built-in Types"
>previous</a> |</li>
<li class="root-icon"><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> &#187;</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.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python built-ins reference</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Built-in Constants</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="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001 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 Oct 09, 2026 (11:35 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,409 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Python built-ins reference" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/builtins/index.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Python comes with a number of built-in functions and classes. The built-in classes include data types that would normally be considered part of the “core” of a language, such as numbers and lists. ..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Python comes with a number of built-in functions and classes. The built-in classes include data types that would normally be considered part of the “core” of a language, such as numbers and lists. ..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>Python built-ins reference &#8212; Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0 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="Built-in Types" href="stdtypes.html" />
<link rel="prev" title="10. Full Grammar specification" href="../reference/grammar.html" />
<link rel="canonical" href="https://docs.python.org/3/builtins/index.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<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>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</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">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<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" fill="currentColor" 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"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="../reference/grammar.html"
title="previous chapter"><span class="section-number">10. </span>Full Grammar specification</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="stdtypes.html"
title="next chapter">Built-in Types</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "builtins/index.rst");
element.href = url.toString();
});
});
</script>
<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 class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/builtins/index.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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="stdtypes.html" title="Built-in Types"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../reference/grammar.html" title="10. Full Grammar specification"
accesskey="P">previous</a> |</li>
<li class="root-icon"><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> &#187;</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.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-this"><a href="">Python built-ins reference</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="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="python-built-ins-reference">
<span id="builtins-index"></span><h1>Python built-ins reference<a class="headerlink" href="#python-built-ins-reference" title="Link to this heading"></a></h1>
<p>Python comes with a number of built-in functions and classes.</p>
<p>The built-in classes include data types that would normally be considered part
of the “core” of a language, such as numbers and lists. For these types, the
Python language core defines the form of literals and places some constraints
on their semantics, but does not fully define the semantics.</p>
<p>The built-ins also include functions and exceptions — objects that can
be used by all Python code without the need of an <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement.
Some of these are defined by the core language, but many are not essential for
the core semantics and are only described here.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>In addition to the built-ins, Python provides an extensive importable
standard library, see <a class="reference internal" href="../library/index.html#library-index"><span class="std std-ref">The Python standard library</span></a>.</p>
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="stdtypes.html">Built-in Types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#truth-value-testing">Truth Value Testing</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#boolean-operations-and-or-not">Boolean Operations — <code class="xref std std-keyword docutils literal notranslate"><span class="pre">and</span></code>, <code class="xref std std-keyword docutils literal notranslate"><span class="pre">or</span></code>, <code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#comparisons">Comparisons</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#numeric-types-int-float-complex">Numeric Types — <code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#boolean-type-bool">Boolean Type - <code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#iterator-types">Iterator Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#sequence-types-list-tuple-range">Sequence Types — <code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#text-and-binary-sequence-type-methods-summary">Text and Binary Sequence Type Methods Summary</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#text-sequence-type-str">Text Sequence Type — <code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#binary-sequence-types-bytes-bytearray-memoryview">Binary Sequence Types — <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#set-types-set-frozenset">Set Types — <code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#mapping-types-dict-frozendict">Mapping types — <code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#context-manager-types">Context Manager Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#type-annotation-types-generic-alias-union">Type Annotation Types — <span class="xref std std-ref">Generic Alias</span>, <span class="xref std std-ref">Union</span></a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#other-built-in-types">Other Built-in Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#special-attributes">Special Attributes</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdtypes.html#integer-string-conversion-length-limitation">Integer string conversion length limitation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="constants.html">Built-in Constants</a><ul>
<li class="toctree-l2"><a class="reference internal" href="constants.html#constants-added-by-the-site-module">Constants added by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> module</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="functions.html">Built-in functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="exceptions.html">Built-in Exceptions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#exception-context">Exception context</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#inheriting-from-built-in-exceptions">Inheriting from built-in exceptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#base-classes">Base classes</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#concrete-exceptions">Concrete exceptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#warnings">Warnings</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#exception-groups">Exception groups</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#exception-hierarchy">Exception hierarchy</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="threadsafety.html">Thread Safety Guarantees</a><ul>
<li class="toctree-l2"><a class="reference internal" href="threadsafety.html#thread-safety-levels">Thread safety levels</a></li>
<li class="toctree-l2"><a class="reference internal" href="threadsafety.html#thread-safety-for-list-objects">Thread safety for list objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="threadsafety.html#thread-safety-for-dict-objects">Thread safety for dict objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="threadsafety.html#thread-safety-for-set-objects">Thread safety for set objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="threadsafety.html#thread-safety-for-bytearray-objects">Thread safety for bytearray objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="threadsafety.html#thread-safety-for-memoryview-objects">Thread safety for memoryview objects</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="time-complexity.html">Time complexity of operations on built-in types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="time-complexity.html#list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="time-complexity.html#tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="time-complexity.html#dict-frozendict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="time-complexity.html#set-frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="time-complexity.html#str-bytes-bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="time-complexity.html#memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="time-complexity.html#range"><code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="time-complexity.html#notes">Notes</a></li>
</ul>
</li>
</ul>
</div>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="../reference/grammar.html"
title="previous chapter"><span class="section-number">10. </span>Full Grammar specification</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="stdtypes.html"
title="next chapter">Built-in Types</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "builtins/index.rst");
element.href = url.toString();
});
});
</script>
<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 class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/builtins/index.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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="stdtypes.html" title="Built-in Types"
>next</a> |</li>
<li class="right" >
<a href="../reference/grammar.html" title="10. Full Grammar specification"
>previous</a> |</li>
<li class="root-icon"><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> &#187;</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.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-this"><a href="">Python built-ins reference</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="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001 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 Oct 09, 2026 (11:35 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,827 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Thread Safety Guarantees" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/builtins/threadsafety.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="This page documents thread-safety guarantees for built-in types in Python’s free-threaded build. The guarantees described here apply when using Python with the GIL disabled (free-threaded mode). Wh..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="This page documents thread-safety guarantees for built-in types in Python’s free-threaded build. The guarantees described here apply when using Python with the GIL disabled (free-threaded mode). Wh..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>Thread Safety Guarantees &#8212; Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0 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="Time complexity of operations on built-in types" href="time-complexity.html" />
<link rel="prev" title="Built-in Exceptions" href="exceptions.html" />
<link rel="canonical" href="https://docs.python.org/3/builtins/threadsafety.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<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>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</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">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<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" fill="currentColor" 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"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Thread Safety Guarantees</a><ul>
<li><a class="reference internal" href="#thread-safety-levels">Thread safety levels</a><ul>
<li><a class="reference internal" href="#incompatible">Incompatible</a></li>
<li><a class="reference internal" href="#compatible">Compatible</a></li>
<li><a class="reference internal" href="#safe-on-distinct-objects">Safe on distinct objects</a></li>
<li><a class="reference internal" href="#safe-on-shared-objects">Safe on shared objects</a></li>
<li><a class="reference internal" href="#atomic">Atomic</a></li>
</ul>
</li>
<li><a class="reference internal" href="#thread-safety-for-list-objects">Thread safety for list objects</a></li>
<li><a class="reference internal" href="#thread-safety-for-dict-objects">Thread safety for dict objects</a></li>
<li><a class="reference internal" href="#thread-safety-for-set-objects">Thread safety for set objects</a></li>
<li><a class="reference internal" href="#thread-safety-for-bytearray-objects">Thread safety for bytearray objects</a></li>
<li><a class="reference internal" href="#thread-safety-for-memoryview-objects">Thread safety for memoryview objects</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="exceptions.html"
title="previous chapter">Built-in Exceptions</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="time-complexity.html"
title="next chapter">Time complexity of operations on built-in types</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "builtins/threadsafety.rst");
element.href = url.toString();
});
});
</script>
<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 class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/builtins/threadsafety.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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="time-complexity.html" title="Time complexity of operations on built-in types"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="exceptions.html" title="Built-in Exceptions"
accesskey="P">previous</a> |</li>
<li class="root-icon"><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> &#187;</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.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python built-ins reference</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Thread Safety Guarantees</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="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="thread-safety-guarantees">
<span id="threadsafety"></span><h1>Thread Safety Guarantees<a class="headerlink" href="#thread-safety-guarantees" title="Link to this heading"></a></h1>
<p>This page documents thread-safety guarantees for built-in types in Python’s
free-threaded build. The guarantees described here apply when using Python with
the <a class="reference internal" href="../glossary.html#term-GIL"><span class="xref std std-term">GIL</span></a> disabled (free-threaded mode). When the GIL is enabled, most
operations are implicitly serialized.</p>
<p>For general guidance on writing thread-safe code in free-threaded Python, see
<a class="reference internal" href="../howto/free-threading-python.html#freethreading-python-howto"><span class="std std-ref">Python support for free threading</span></a>.</p>
<section id="thread-safety-levels">
<span id="threadsafety-levels"></span><h2>Thread safety levels<a class="headerlink" href="#thread-safety-levels" title="Link to this heading"></a></h2>
<p>The C API documentation uses the following levels to describe the thread
safety guarantees of each function. The levels are listed from least to
most safe.</p>
<section id="incompatible">
<span id="threadsafety-level-incompatible"></span><h3>Incompatible<a class="headerlink" href="#incompatible" title="Link to this heading"></a></h3>
<p>A function or operation that cannot be made safe for concurrent use even
with external synchronization. Incompatible code typically accesses
global state in an unsynchronized way and must only be called from a single
thread throughout the program’s lifetime.</p>
<p>Example: a function that modifies process-wide state such as signal handlers
or environment variables, where concurrent calls from any threads, even with
external locking, can conflict with the runtime or other libraries.</p>
</section>
<section id="compatible">
<span id="threadsafety-level-compatible"></span><h3>Compatible<a class="headerlink" href="#compatible" title="Link to this heading"></a></h3>
<p>A function or operation that is safe to call from multiple threads
<em>provided</em> the caller supplies appropriate external synchronization, for
example by holding a <a class="reference internal" href="../glossary.html#term-lock"><span class="xref std std-term">lock</span></a> for the duration of each call. Without
such synchronization, concurrent calls may produce <a class="reference internal" href="../glossary.html#term-race-condition"><span class="xref std std-term">race conditions</span></a> or <a class="reference internal" href="../glossary.html#term-data-race"><span class="xref std std-term">data races</span></a>.</p>
<p>Example: a function that reads from or writes to an object whose internal
state is not protected by a lock. Callers must ensure that no two threads
access the same object at the same time.</p>
</section>
<section id="safe-on-distinct-objects">
<span id="threadsafety-level-distinct"></span><h3>Safe on distinct objects<a class="headerlink" href="#safe-on-distinct-objects" title="Link to this heading"></a></h3>
<p>A function or operation that is safe to call from multiple threads without
external synchronization, as long as each thread operates on a <strong>different</strong>
object. Two threads may call the function at the same time, but they must
not pass the same object (or objects that share underlying state) as
arguments.</p>
<p>Example: a function that modifies fields of a struct using non-atomic
writes. Two threads can each call the function on their own struct
instance safely, but concurrent calls on the <em>same</em> instance require
external synchronization.</p>
</section>
<section id="safe-on-shared-objects">
<span id="threadsafety-level-shared"></span><h3>Safe on shared objects<a class="headerlink" href="#safe-on-shared-objects" title="Link to this heading"></a></h3>
<p>A function or operation that is safe for concurrent use on the <strong>same</strong>
object. The implementation uses internal synchronization (such as
<a class="reference internal" href="../glossary.html#term-per-object-lock"><span class="xref std std-term">per-object locks</span></a> or
<a class="reference internal" href="../c-api/synchronization.html#python-critical-section-api"><span class="std std-ref">critical sections</span></a>) to protect shared
mutable state, so callers do not need to supply their own locking.</p>
<p>Example: <a class="reference internal" href="../c-api/list.html#c.PyList_GetItemRef" title="PyList_GetItemRef"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_GetItemRef()</span></code></a> can be called from multiple threads on the
same <a class="reference internal" href="../c-api/list.html#c.PyListObject" title="PyListObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyListObject</span></code></a> - it uses internal synchronization to serialize
access.</p>
</section>
<section id="atomic">
<span id="threadsafety-level-atomic"></span><h3>Atomic<a class="headerlink" href="#atomic" title="Link to this heading"></a></h3>
<p>A function or operation that appears <a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a> with
respect to other threads - it executes instantaneously from the perspective
of other threads. This is the strongest form of thread safety.</p>
<p>Example: <a class="reference internal" href="../c-api/synchronization.html#c.PyMutex_IsLocked" title="PyMutex_IsLocked"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMutex_IsLocked()</span></code></a> performs an atomic read of the mutex
state and can be called from any thread at any time.</p>
</section>
</section>
<section id="thread-safety-for-list-objects">
<span id="thread-safety-list"></span><h2>Thread safety for list objects<a class="headerlink" href="#thread-safety-for-list-objects" title="Link to this heading"></a></h2>
<p>Reading a single element from a <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> is
<a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a>:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">lst</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="c1"># list.__getitem__</span>
</pre></div>
</div>
<p>The following methods traverse the list and use <a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a>
reads of each item to perform their function. That means that they may
return results affected by concurrent modifications:</p>
<div class="maybe highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">item</span> <span class="ow">in</span> <span class="n">lst</span>
<span class="n">lst</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
<span class="n">lst</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
</pre></div>
</div>
<p>All of the above operations avoid acquiring <a class="reference internal" href="../glossary.html#term-per-object-lock"><span class="xref std std-term">per-object locks</span></a>. They do not block concurrent modifications. Other
operations that hold a lock will not block these from observing intermediate
states.</p>
<p>All other operations from here on block using the <a class="reference internal" href="../glossary.html#term-per-object-lock"><span class="xref std std-term">per-object lock</span></a>.</p>
<p>Writing a single item via <code class="docutils literal notranslate"><span class="pre">lst[i]</span> <span class="pre">=</span> <span class="pre">x</span></code> is safe to call from multiple
threads and will not corrupt the list.</p>
<p>The following operations return new objects and appear
<a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a> to other threads:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">lst1</span> <span class="o">+</span> <span class="n">lst2</span> <span class="c1"># concatenates two lists into a new list</span>
<span class="n">x</span> <span class="o">*</span> <span class="n">lst</span> <span class="c1"># repeats lst x times into a new list</span>
<span class="n">lst</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span> <span class="c1"># returns a shallow copy of the list</span>
</pre></div>
</div>
<p>The following methods that only operate on a single element with no shifting
required are <a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a>:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">lst</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="c1"># append to the end of the list, no shifting required</span>
<span class="n">lst</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span> <span class="c1"># pop element from the end of the list, no shifting required</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="stdtypes.html#list.clear" title="list.clear"><code class="xref py py-meth docutils literal notranslate"><span class="pre">clear()</span></code></a> method is also <a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a>.
Other threads cannot observe elements being removed.</p>
<p>The <a class="reference internal" href="stdtypes.html#list.sort" title="list.sort"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sort()</span></code></a> method is not <a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a>.
Other threads cannot observe intermediate states during sorting, but the
list appears empty for the duration of the sort.</p>
<p>The following operations may allow <a class="reference internal" href="../glossary.html#term-lock-free"><span class="xref std std-term">lock-free</span></a> operations to observe
intermediate states since they modify multiple elements in place:</p>
<div class="maybe highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">lst</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="n">idx</span><span class="p">,</span> <span class="n">item</span><span class="p">)</span> <span class="c1"># shifts elements</span>
<span class="n">lst</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="n">idx</span><span class="p">)</span> <span class="c1"># idx not at the end of the list, shifts elements</span>
<span class="n">lst</span> <span class="o">*=</span> <span class="n">x</span> <span class="c1"># copies elements in place</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="stdtypes.html#list.remove" title="list.remove"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remove()</span></code></a> method may allow concurrent modifications since
element comparison may execute arbitrary Python code (via
<a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a>).</p>
<p><a class="reference internal" href="stdtypes.html#list.extend" title="list.extend"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extend()</span></code></a> is safe to call from multiple threads. However, its
guarantees depend on the iterable passed to it. If it is a <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, a
<a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>, a <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>, a <a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>, a <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> or a
<a class="reference internal" href="stdtypes.html#dict-views"><span class="std std-ref">dictionary view object</span></a> (but not their subclasses), the
<code class="docutils literal notranslate"><span class="pre">extend</span></code> operation is safe from concurrent modifications to the iterable.
Otherwise, an iterator is created which can be concurrently modified by
another thread. The same applies to inplace concatenation of a list with
other iterables when using <code class="docutils literal notranslate"><span class="pre">lst</span> <span class="pre">+=</span> <span class="pre">iterable</span></code>.</p>
<p>Similarly, assigning to a list slice with <code class="docutils literal notranslate"><span class="pre">lst[i:j]</span> <span class="pre">=</span> <span class="pre">iterable</span></code> is safe
to call from multiple threads, but <code class="docutils literal notranslate"><span class="pre">iterable</span></code> is only locked when it is
also a <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> (but not its subclasses).</p>
<p>Operations that involve multiple accesses, as well as iteration, are never
atomic. For example:</p>
<div class="bad highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># NOT atomic: read-modify-write</span>
<span class="n">lst</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">lst</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">1</span>
<span class="c1"># NOT atomic: check-then-act</span>
<span class="k">if</span> <span class="n">lst</span><span class="p">:</span>
<span class="n">item</span> <span class="o">=</span> <span class="n">lst</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>
<span class="c1"># NOT thread-safe: iteration while modifying</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">lst</span><span class="p">:</span>
<span class="n">process</span><span class="p">(</span><span class="n">item</span><span class="p">)</span> <span class="c1"># another thread may modify lst</span>
</pre></div>
</div>
<p>Consider external synchronization when sharing <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> instances
across threads.</p>
</section>
<section id="thread-safety-for-dict-objects">
<span id="thread-safety-dict"></span><h2>Thread safety for dict objects<a class="headerlink" href="#thread-safety-for-dict-objects" title="Link to this heading"></a></h2>
<p>Creating a dictionary with the <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> constructor is atomic when the
argument to it is a <code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code> or a <a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>. When using the
<a class="reference internal" href="stdtypes.html#dict.fromkeys" title="dict.fromkeys"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.fromkeys()</span></code></a> method, dictionary creation is atomic when the
argument is a <code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code>, <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> or
<a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>.</p>
<p>The following operations and functions are <a class="reference internal" href="../glossary.html#term-lock-free"><span class="xref std std-term">lock-free</span></a> and
<a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a>.</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">d</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="c1"># dict.__getitem__</span>
<span class="n">d</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">key</span><span class="p">)</span> <span class="c1"># dict.get</span>
<span class="n">key</span> <span class="ow">in</span> <span class="n">d</span> <span class="c1"># dict.__contains__</span>
<span class="nb">len</span><span class="p">(</span><span class="n">d</span><span class="p">)</span> <span class="c1"># dict.__len__</span>
</pre></div>
</div>
<p>All other operations from here on hold the <a class="reference internal" href="../glossary.html#term-per-object-lock"><span class="xref std std-term">per-object lock</span></a>.</p>
<p>Writing or removing a single item is safe to call from multiple threads
and will not corrupt the dictionary:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">d</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span> <span class="c1"># write</span>
<span class="k">del</span> <span class="n">d</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="c1"># delete</span>
<span class="n">d</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="n">key</span><span class="p">)</span> <span class="c1"># remove and return</span>
<span class="n">d</span><span class="o">.</span><span class="n">popitem</span><span class="p">()</span> <span class="c1"># remove and return last item</span>
<span class="n">d</span><span class="o">.</span><span class="n">setdefault</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="n">v</span><span class="p">)</span> <span class="c1"># insert if missing</span>
</pre></div>
</div>
<p>These operations may compare keys using <a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a>, which can
execute arbitrary Python code. During such comparisons, the dictionary may
be modified by another thread. For built-in types like <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>,
<a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>, and <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, that implement <code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code> in C,
the underlying lock is not released during comparisons and this is not a
concern.</p>
<p>The following operations return new objects and hold the <a class="reference internal" href="../glossary.html#term-per-object-lock"><span class="xref std std-term">per-object lock</span></a>
for the duration of the operation:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">d</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span> <span class="c1"># returns a shallow copy of the dictionary</span>
<span class="n">d</span> <span class="o">|</span> <span class="n">other</span> <span class="c1"># merges two dicts into a new dict</span>
<span class="n">d</span><span class="o">.</span><span class="n">keys</span><span class="p">()</span> <span class="c1"># returns a new dict_keys view object</span>
<span class="n">d</span><span class="o">.</span><span class="n">values</span><span class="p">()</span> <span class="c1"># returns a new dict_values view object</span>
<span class="n">d</span><span class="o">.</span><span class="n">items</span><span class="p">()</span> <span class="c1"># returns a new dict_items view object</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="stdtypes.html#dict.clear" title="dict.clear"><code class="xref py py-meth docutils literal notranslate"><span class="pre">clear()</span></code></a> method holds the lock for its duration. Other
threads cannot observe elements being removed.</p>
<p>The following operations lock both dictionaries. For <a class="reference internal" href="stdtypes.html#dict.update" title="dict.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">update()</span></code></a>
and <code class="docutils literal notranslate"><span class="pre">|=</span></code>, this applies only when the other operand is a <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>
that uses the standard dict iterator (but not subclasses that override
iteration). For equality comparison, this applies to <code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code> and
its subclasses:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">d</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">other_dict</span><span class="p">)</span> <span class="c1"># both locked when other_dict is a dict</span>
<span class="n">d</span> <span class="o">|=</span> <span class="n">other_dict</span> <span class="c1"># both locked when other_dict is a dict</span>
<span class="n">d</span> <span class="o">==</span> <span class="n">other_dict</span> <span class="c1"># both locked for dict and subclasses</span>
</pre></div>
</div>
<p>All comparison operations also compare values using <a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a>,
so for non-built-in types the lock may be released during comparison.</p>
<p><a class="reference internal" href="stdtypes.html#dict.fromkeys" title="dict.fromkeys"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fromkeys()</span></code></a> locks both the new dictionary and the iterable
when the iterable is exactly a <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>, <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>, or
<a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> (not subclasses):</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">dict</span><span class="o">.</span><span class="n">fromkeys</span><span class="p">(</span><span class="n">a_dict</span><span class="p">)</span> <span class="c1"># locks both</span>
<span class="nb">dict</span><span class="o">.</span><span class="n">fromkeys</span><span class="p">(</span><span class="n">a_set</span><span class="p">)</span> <span class="c1"># locks both</span>
<span class="nb">dict</span><span class="o">.</span><span class="n">fromkeys</span><span class="p">(</span><span class="n">a_frozenset</span><span class="p">)</span> <span class="c1"># locks both</span>
</pre></div>
</div>
<p>When updating from a non-dict iterable, only the target dictionary is
locked. The iterable may be concurrently modified by another thread:</p>
<div class="maybe highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">d</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span> <span class="c1"># iterable is not a dict: only d locked</span>
<span class="n">d</span> <span class="o">|=</span> <span class="n">iterable</span> <span class="c1"># iterable is not a dict: only d locked</span>
<span class="nb">dict</span><span class="o">.</span><span class="n">fromkeys</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span> <span class="c1"># iterable is not a dict/set/frozenset: only result locked</span>
</pre></div>
</div>
<p>Operations that involve multiple accesses, as well as iteration, are never
atomic:</p>
<div class="bad highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># NOT atomic: read-modify-write</span>
<span class="n">d</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">+</span> <span class="mi">1</span>
<span class="c1"># NOT atomic: check-then-act (TOCTOU)</span>
<span class="k">if</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">d</span><span class="p">:</span>
<span class="k">del</span> <span class="n">d</span><span class="p">[</span><span class="n">key</span><span class="p">]</span>
<span class="c1"># NOT thread-safe: iteration while modifying</span>
<span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">d</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
<span class="n">process</span><span class="p">(</span><span class="n">key</span><span class="p">)</span> <span class="c1"># another thread may modify d</span>
</pre></div>
</div>
<p>To avoid time-of-check to time-of-use (TOCTOU) issues, use atomic
operations or handle exceptions:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Use pop() with default instead of check-then-delete</span>
<span class="n">d</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
<span class="c1"># Or handle the exception</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">del</span> <span class="n">d</span><span class="p">[</span><span class="n">key</span><span class="p">]</span>
<span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>To safely iterate over a dictionary that may be modified by another
thread, iterate over a copy:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Make a copy to iterate safely</span>
<span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">d</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
<span class="n">process</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
</pre></div>
</div>
<p>Consider external synchronization when sharing <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> instances
across threads.</p>
</section>
<section id="thread-safety-for-set-objects">
<span id="thread-safety-set"></span><h2>Thread safety for set objects<a class="headerlink" href="#thread-safety-for-set-objects" title="Link to this heading"></a></h2>
<p>The <a class="reference internal" href="functions.html#len" title="len"><code class="xref py py-func docutils literal notranslate"><span class="pre">len()</span></code></a> function is lock-free and <a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a>.</p>
<p>The following read operation is lock-free. It does not block concurrent
modifications and may observe intermediate states from operations that
hold the per-object lock:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">elem</span> <span class="ow">in</span> <span class="n">s</span> <span class="c1"># set.__contains__</span>
</pre></div>
</div>
<p>This operation may compare elements using <a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a>, which can
execute arbitrary Python code. During such comparisons, the set may be
modified by another thread. For built-in types like <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>,
<a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>, and <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code> does not release the
underlying lock during comparisons and this is not a concern.</p>
<p>All other operations from here on hold the per-object lock.</p>
<p>Adding or removing a single element is safe to call from multiple threads
and will not corrupt the set:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">s</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">elem</span><span class="p">)</span> <span class="c1"># add element</span>
<span class="n">s</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">elem</span><span class="p">)</span> <span class="c1"># remove element, raise if missing</span>
<span class="n">s</span><span class="o">.</span><span class="n">discard</span><span class="p">(</span><span class="n">elem</span><span class="p">)</span> <span class="c1"># remove element if present</span>
<span class="n">s</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span> <span class="c1"># remove and return arbitrary element</span>
</pre></div>
</div>
<p>These operations also compare elements, so the same <a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a>
considerations as above apply.</p>
<p>The <a class="reference internal" href="stdtypes.html#set.copy" title="set.copy"><code class="xref py py-meth docutils literal notranslate"><span class="pre">copy()</span></code></a> method returns a new object and holds the per-object lock
for the duration so that it is always atomic.</p>
<p>The <a class="reference internal" href="stdtypes.html#set.clear" title="set.clear"><code class="xref py py-meth docutils literal notranslate"><span class="pre">clear()</span></code></a> method holds the lock for its duration. Other
threads cannot observe elements being removed.</p>
<p>The following operations only accept <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> or <a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>
as operands and always lock both objects:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">s</span> <span class="o">|=</span> <span class="n">other</span> <span class="c1"># other must be set/frozenset</span>
<span class="n">s</span> <span class="o">&amp;=</span> <span class="n">other</span> <span class="c1"># other must be set/frozenset</span>
<span class="n">s</span> <span class="o">-=</span> <span class="n">other</span> <span class="c1"># other must be set/frozenset</span>
<span class="n">s</span> <span class="o">^=</span> <span class="n">other</span> <span class="c1"># other must be set/frozenset</span>
<span class="n">s</span> <span class="o">&amp;</span> <span class="n">other</span> <span class="c1"># other must be set/frozenset</span>
<span class="n">s</span> <span class="o">|</span> <span class="n">other</span> <span class="c1"># other must be set/frozenset</span>
<span class="n">s</span> <span class="o">-</span> <span class="n">other</span> <span class="c1"># other must be set/frozenset</span>
<span class="n">s</span> <span class="o">^</span> <span class="n">other</span> <span class="c1"># other must be set/frozenset</span>
</pre></div>
</div>
<p><a class="reference internal" href="stdtypes.html#set.update" title="set.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.update()</span></code></a>, <a class="reference internal" href="stdtypes.html#set.union" title="set.union"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.union()</span></code></a>, <a class="reference internal" href="stdtypes.html#set.intersection" title="set.intersection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.intersection()</span></code></a> and
<a class="reference internal" href="stdtypes.html#set.difference" title="set.difference"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.difference()</span></code></a> can take multiple iterables as arguments. They all
iterate through all the passed iterables and do the following:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="stdtypes.html#set.update" title="set.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.update()</span></code></a> and <a class="reference internal" href="stdtypes.html#set.union" title="set.union"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.union()</span></code></a> lock both objects only when
the other operand is a <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>, <a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>, or <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>.</p></li>
<li><p><a class="reference internal" href="stdtypes.html#set.intersection" title="set.intersection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.intersection()</span></code></a> and <a class="reference internal" href="stdtypes.html#set.difference" title="set.difference"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.difference()</span></code></a> always try to lock
all objects.</p></li>
</ul>
</div></blockquote>
<p><a class="reference internal" href="stdtypes.html#set.symmetric_difference" title="set.symmetric_difference"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.symmetric_difference()</span></code></a> tries to lock both objects.</p>
<p>The update variants of the above methods also have some differences between
them:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="stdtypes.html#set.difference_update" title="set.difference_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.difference_update()</span></code></a> and <a class="reference internal" href="stdtypes.html#set.intersection_update" title="set.intersection_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.intersection_update()</span></code></a> try
to lock all objects one-by-one.</p></li>
<li><p><a class="reference internal" href="stdtypes.html#set.symmetric_difference_update" title="set.symmetric_difference_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set.symmetric_difference_update()</span></code></a> only locks the arguments if it is
of type <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>, <a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>, or <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>.</p></li>
</ul>
</div></blockquote>
<p>The following methods always try to lock both objects:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">s</span><span class="o">.</span><span class="n">isdisjoint</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="c1"># both locked</span>
<span class="n">s</span><span class="o">.</span><span class="n">issubset</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="c1"># both locked</span>
<span class="n">s</span><span class="o">.</span><span class="n">issuperset</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="c1"># both locked</span>
</pre></div>
</div>
<p>Operations that involve multiple accesses, as well as iteration, are never
atomic:</p>
<div class="bad highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># NOT atomic: check-then-act</span>
<span class="k">if</span> <span class="n">elem</span> <span class="ow">in</span> <span class="n">s</span><span class="p">:</span>
<span class="n">s</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">elem</span><span class="p">)</span>
<span class="c1"># NOT thread-safe: iteration while modifying</span>
<span class="k">for</span> <span class="n">elem</span> <span class="ow">in</span> <span class="n">s</span><span class="p">:</span>
<span class="n">process</span><span class="p">(</span><span class="n">elem</span><span class="p">)</span> <span class="c1"># another thread may modify s</span>
</pre></div>
</div>
<p>Consider external synchronization when sharing <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> instances
across threads. See <a class="reference internal" href="../howto/free-threading-python.html#freethreading-python-howto"><span class="std std-ref">Python support for free threading</span></a> for more information.</p>
</section>
<section id="thread-safety-for-bytearray-objects">
<span id="thread-safety-bytearray"></span><h2>Thread safety for bytearray objects<a class="headerlink" href="#thread-safety-for-bytearray-objects" title="Link to this heading"></a></h2>
<blockquote>
<div><p>The <a class="reference internal" href="functions.html#len" title="len"><code class="xref py py-func docutils literal notranslate"><span class="pre">len()</span></code></a> function is lock-free and <a class="reference internal" href="../glossary.html#term-atomic-operation"><span class="xref std std-term">atomic</span></a>.</p>
<p>Concatenation and comparisons use the buffer protocol, which prevents
resizing but does not hold the per-object lock. These operations may
observe intermediate states from concurrent modifications:</p>
<div class="maybe highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ba</span> <span class="o">+</span> <span class="n">other</span> <span class="c1"># may observe concurrent writes</span>
<span class="n">ba</span> <span class="o">==</span> <span class="n">other</span> <span class="c1"># may observe concurrent writes</span>
<span class="n">ba</span> <span class="o">&lt;</span> <span class="n">other</span> <span class="c1"># may observe concurrent writes</span>
</pre></div>
</div>
<p>All other operations from here on hold the per-object lock.</p>
<p>Reading a single element or slice is safe to call from multiple threads:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ba</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="c1"># bytearray.__getitem__</span>
<span class="n">ba</span><span class="p">[</span><span class="n">i</span><span class="p">:</span><span class="n">j</span><span class="p">]</span> <span class="c1"># slice</span>
</pre></div>
</div>
<p>The following operations are safe to call from multiple threads and will
not corrupt the bytearray:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ba</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">x</span> <span class="c1"># write single byte</span>
<span class="n">ba</span><span class="p">[</span><span class="n">i</span><span class="p">:</span><span class="n">j</span><span class="p">]</span> <span class="o">=</span> <span class="n">values</span> <span class="c1"># write slice</span>
<span class="n">ba</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="c1"># append single byte</span>
<span class="n">ba</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="c1"># extend with iterable</span>
<span class="n">ba</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span> <span class="c1"># insert single byte</span>
<span class="n">ba</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span> <span class="c1"># remove and return last byte</span>
<span class="n">ba</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="n">i</span><span class="p">)</span> <span class="c1"># remove and return byte at index</span>
<span class="n">ba</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="c1"># remove first occurrence</span>
<span class="n">ba</span><span class="o">.</span><span class="n">reverse</span><span class="p">()</span> <span class="c1"># reverse in place</span>
<span class="n">ba</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span> <span class="c1"># remove all bytes</span>
</pre></div>
</div>
<p>Slice assignment locks both objects when <em>values</em> is a <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ba</span><span class="p">[</span><span class="n">i</span><span class="p">:</span><span class="n">j</span><span class="p">]</span> <span class="o">=</span> <span class="n">other_bytearray</span> <span class="c1"># both locked</span>
</pre></div>
</div>
<p>The following operations return new objects and hold the per-object lock
for the duration:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ba</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span> <span class="c1"># returns a shallow copy</span>
<span class="n">ba</span> <span class="o">*</span> <span class="n">n</span> <span class="c1"># repeat into new bytearray</span>
</pre></div>
</div>
<p>The membership test holds the lock for its duration:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="ow">in</span> <span class="n">ba</span> <span class="c1"># bytearray.__contains__</span>
</pre></div>
</div>
<p>All other bytearray methods (such as <a class="reference internal" href="stdtypes.html#bytearray.find" title="bytearray.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find()</span></code></a>,
<a class="reference internal" href="stdtypes.html#bytearray.replace" title="bytearray.replace"><code class="xref py py-meth docutils literal notranslate"><span class="pre">replace()</span></code></a>, <a class="reference internal" href="stdtypes.html#bytearray.split" title="bytearray.split"><code class="xref py py-meth docutils literal notranslate"><span class="pre">split()</span></code></a>,
<a class="reference internal" href="stdtypes.html#bytearray.decode" title="bytearray.decode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code></a>, etc.) hold the per-object lock for their
duration.</p>
<p>Operations that involve multiple accesses, as well as iteration, are never
atomic:</p>
<div class="bad highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># NOT atomic: check-then-act</span>
<span class="k">if</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">ba</span><span class="p">:</span>
<span class="n">ba</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
<span class="c1"># NOT thread-safe: iteration while modifying</span>
<span class="k">for</span> <span class="n">byte</span> <span class="ow">in</span> <span class="n">ba</span><span class="p">:</span>
<span class="n">process</span><span class="p">(</span><span class="n">byte</span><span class="p">)</span> <span class="c1"># another thread may modify ba</span>
</pre></div>
</div>
<p>To safely iterate over a bytearray that may be modified by another
thread, iterate over a copy:</p>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Make a copy to iterate safely</span>
<span class="k">for</span> <span class="n">byte</span> <span class="ow">in</span> <span class="n">ba</span><span class="o">.</span><span class="n">copy</span><span class="p">():</span>
<span class="n">process</span><span class="p">(</span><span class="n">byte</span><span class="p">)</span>
</pre></div>
</div>
<p>Consider external synchronization when sharing <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> instances
across threads. See <a class="reference internal" href="../howto/free-threading-python.html#freethreading-python-howto"><span class="std std-ref">Python support for free threading</span></a> for more information.</p>
</div></blockquote>
</section>
<section id="thread-safety-for-memoryview-objects">
<span id="thread-safety-memoryview"></span><h2>Thread safety for memoryview objects<a class="headerlink" href="#thread-safety-for-memoryview-objects" title="Link to this heading"></a></h2>
<p><a class="reference internal" href="stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> objects provide access to the internal data of an
underlying object without copying. Thread safety depends on both the
memoryview itself and the underlying buffer exporter.</p>
<p>The memoryview implementation uses atomic operations to track its own
exports in the <a class="reference internal" href="../glossary.html#term-free-threaded-build"><span class="xref std std-term">free-threaded build</span></a>. Creating and
releasing a memoryview are thread-safe. Attribute access (e.g.,
<a class="reference internal" href="stdtypes.html#memoryview.shape" title="memoryview.shape"><code class="xref py py-attr docutils literal notranslate"><span class="pre">shape</span></code></a>, <a class="reference internal" href="stdtypes.html#memoryview.format" title="memoryview.format"><code class="xref py py-attr docutils literal notranslate"><span class="pre">format</span></code></a>) reads fields that
are immutable for the lifetime of the memoryview, so concurrent reads
are safe as long as the memoryview has not been released.</p>
<p>However, the actual data accessed through the memoryview is owned by the
underlying object. Concurrent access to this data is only safe if the
underlying object supports it:</p>
<ul class="simple">
<li><p>For immutable objects like <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, concurrent reads through
multiple memoryviews are safe.</p></li>
<li><p>For mutable objects like <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>, reading and writing the
same memory region from multiple threads without external
synchronization is not safe and may result in data corruption.
Note that even read-only memoryviews of mutable objects do not
prevent data races if the underlying object is modified from
another thread.</p></li>
</ul>
<div class="bad highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># NOT safe: concurrent writes to the same buffer</span>
<span class="n">data</span> <span class="o">=</span> <span class="nb">bytearray</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
<span class="n">view</span> <span class="o">=</span> <span class="nb">memoryview</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="c1"># Thread 1: view[0:500] = b'x' * 500</span>
<span class="c1"># Thread 2: view[0:500] = b'y' * 500</span>
</pre></div>
</div>
<div class="good highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Safe: use a lock for concurrent access</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">threading</span>
<span class="n">lock</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Lock</span><span class="p">()</span>
<span class="n">data</span> <span class="o">=</span> <span class="nb">bytearray</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
<span class="n">view</span> <span class="o">=</span> <span class="nb">memoryview</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="k">with</span> <span class="n">lock</span><span class="p">:</span>
<span class="n">view</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">500</span><span class="p">]</span> <span class="o">=</span> <span class="sa">b</span><span class="s1">'x'</span> <span class="o">*</span> <span class="mi">500</span>
</pre></div>
</div>
<p>Resizing or reallocating the underlying object (such as calling
<a class="reference internal" href="stdtypes.html#bytearray.resize" title="bytearray.resize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bytearray.resize()</span></code></a>) while a memoryview is exported raises
<a class="reference internal" href="exceptions.html#BufferError" title="BufferError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BufferError</span></code></a>. This is enforced regardless of threading.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Thread Safety Guarantees</a><ul>
<li><a class="reference internal" href="#thread-safety-levels">Thread safety levels</a><ul>
<li><a class="reference internal" href="#incompatible">Incompatible</a></li>
<li><a class="reference internal" href="#compatible">Compatible</a></li>
<li><a class="reference internal" href="#safe-on-distinct-objects">Safe on distinct objects</a></li>
<li><a class="reference internal" href="#safe-on-shared-objects">Safe on shared objects</a></li>
<li><a class="reference internal" href="#atomic">Atomic</a></li>
</ul>
</li>
<li><a class="reference internal" href="#thread-safety-for-list-objects">Thread safety for list objects</a></li>
<li><a class="reference internal" href="#thread-safety-for-dict-objects">Thread safety for dict objects</a></li>
<li><a class="reference internal" href="#thread-safety-for-set-objects">Thread safety for set objects</a></li>
<li><a class="reference internal" href="#thread-safety-for-bytearray-objects">Thread safety for bytearray objects</a></li>
<li><a class="reference internal" href="#thread-safety-for-memoryview-objects">Thread safety for memoryview objects</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="exceptions.html"
title="previous chapter">Built-in Exceptions</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="time-complexity.html"
title="next chapter">Time complexity of operations on built-in types</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "builtins/threadsafety.rst");
element.href = url.toString();
});
});
</script>
<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 class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/builtins/threadsafety.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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="time-complexity.html" title="Time complexity of operations on built-in types"
>next</a> |</li>
<li class="right" >
<a href="exceptions.html" title="Built-in Exceptions"
>previous</a> |</li>
<li class="root-icon"><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> &#187;</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.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python built-ins reference</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Thread Safety Guarantees</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="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001 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 Oct 09, 2026 (11:35 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>
@@ -0,0 +1,815 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Time complexity of operations on built-in types" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/builtins/time-complexity.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="This page documents the time complexity of various operations on built-in types in CPython. Other Python implementations may have different performance characteristics. Additionally, the listed cos..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="This page documents the time complexity of various operations on built-in types in CPython. Other Python implementations may have different performance characteristics. Additionally, the listed cos..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>Time complexity of operations on built-in types &#8212; Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0 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="The Python standard library" href="../library/index.html" />
<link rel="prev" title="Thread Safety Guarantees" href="threadsafety.html" />
<link rel="canonical" href="https://docs.python.org/3/builtins/time-complexity.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<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>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</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">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<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" fill="currentColor" 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"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Time complexity of operations on built-in types</a><ul>
<li><a class="reference internal" href="#list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a></li>
<li><a class="reference internal" href="#tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a></li>
<li><a class="reference internal" href="#dict-frozendict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a></li>
<li><a class="reference internal" href="#set-frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a></li>
<li><a class="reference internal" href="#str-bytes-bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a></li>
<li><a class="reference internal" href="#memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a></li>
<li><a class="reference internal" href="#range"><code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code></a></li>
<li><a class="reference internal" href="#notes">Notes</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="threadsafety.html"
title="previous chapter">Thread Safety Guarantees</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="../library/index.html"
title="next chapter">The Python standard library</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "builtins/time-complexity.rst");
element.href = url.toString();
});
});
</script>
<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 class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/builtins/time-complexity.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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="../library/index.html" title="The Python standard library"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="threadsafety.html" title="Thread Safety Guarantees"
accesskey="P">previous</a> |</li>
<li class="root-icon"><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> &#187;</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.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python built-ins reference</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Time complexity of operations on built-in types</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="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="time-complexity-of-operations-on-built-in-types">
<span id="time-complexity"></span><h1>Time complexity of operations on built-in types<a class="headerlink" href="#time-complexity-of-operations-on-built-in-types" title="Link to this heading"></a></h1>
<p>This page documents the time complexity of various operations on built-in types
in CPython. Other Python implementations may have different performance
characteristics. Additionally, the listed costs assume exact built-in types, as
instances of subclasses may have different costs.</p>
<p>We use <a class="reference external" href="https://en.wikipedia.org/wiki/Big_O_notation">Big <em>O</em> notation</a> to describe how the running time of an operation grows
with the size of its inputs. Unless stated otherwise, <em>n</em> denotes the number of
elements currently in the container, and <em>k</em> is the value of a numeric
parameter, such as an index or a repeat count.</p>
<section id="list">
<h2><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code><a class="headerlink" href="#list" title="Link to this heading"></a></h2>
<p>Lists are mutable sequences; for more detail on the implementation see
<a class="reference internal" href="../faq/design.html#how-are-lists-implemented"><span class="std std-ref">How are lists implemented in CPython?</span></a>. The largest costs come from growing beyond the
current allocation size (because everything must move), or from inserting or
deleting somewhere near the beginning (because everything after that must move).
If you need to add or remove at both ends, consider using a
<a class="reference internal" href="../library/collections.html#collections.deque" title="collections.deque"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.deque</span></code></a> instead.</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Operation</p></th>
<th class="head"><p>Complexity</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Copy (<code class="docutils literal notranslate"><span class="pre">l.copy()</span></code>)</p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Append (<code class="docutils literal notranslate"><span class="pre">l.append(x)</span></code>) <a class="footnote-reference brackets" href="#id54" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-even"><td><p>Pop (<code class="docutils literal notranslate"><span class="pre">l.pop(k)</span></code>) <a class="footnote-reference brackets" href="#id54" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id55" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em> - <em>k</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Insert (<code class="docutils literal notranslate"><span class="pre">l.insert(k,</span> <span class="pre">x)</span></code>) <a class="footnote-reference brackets" href="#id54" id="id4" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id55" id="id5" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em> - <em>k</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Get item (<code class="docutils literal notranslate"><span class="pre">l[k]</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Set item (<code class="docutils literal notranslate"><span class="pre">l[k]</span> <span class="pre">=</span> <span class="pre">x</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-even"><td><p>Delete item (<code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">l[k]</span></code>) <a class="footnote-reference brackets" href="#id55" id="id6" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em> - <em>k</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Iteration</p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Get slice (<code class="docutils literal notranslate"><span class="pre">l[i:j]</span></code>)</p></td>
<td><p><em>O</em>(<em>j</em> - <em>i</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Set slice (<code class="docutils literal notranslate"><span class="pre">l[i:j]</span> <span class="pre">=</span> <span class="pre">t</span></code>) <a class="footnote-reference brackets" href="#id54" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>j</em> - <em>i</em>) if len(<em>t</em>) == <em>j</em> - <em>i</em>,
otherwise <em>O</em>(<em>n</em> - <em>i</em> + len(<em>t</em>))</p></td>
</tr>
<tr class="row-even"><td><p>Delete slice (<code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">l[i:j]</span></code>)</p></td>
<td><p><em>O</em>(<em>n</em> - <em>i</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Extend (<code class="docutils literal notranslate"><span class="pre">l.extend(t)</span></code>) <a class="footnote-reference brackets" href="#id54" id="id8" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id56" id="id9" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(len(<em>t</em>))</p></td>
</tr>
<tr class="row-even"><td><p>Sort (<code class="docutils literal notranslate"><span class="pre">l.sort()</span></code>) <a class="footnote-reference brackets" href="#id57" id="id10" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em> log <em>n</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Concatenate (<code class="docutils literal notranslate"><span class="pre">l1</span> <span class="pre">+</span> <span class="pre">l2</span></code>)</p></td>
<td><p><em>O</em>(len(<em>l1</em>) + len(<em>l2</em>))</p></td>
</tr>
<tr class="row-even"><td><p>Multiply (<code class="docutils literal notranslate"><span class="pre">l</span> <span class="pre">*</span> <span class="pre">k</span></code>)</p></td>
<td><p><em>O</em>(<em>nk</em>)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">l</span></code></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">min(l)</span></code>, <code class="docutils literal notranslate"><span class="pre">max(l)</span></code></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Get length (<code class="docutils literal notranslate"><span class="pre">len(l)</span></code>) <a class="footnote-reference brackets" href="#id58" id="id11" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
</tbody>
</table>
</section>
<section id="tuple">
<h2><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code><a class="headerlink" href="#tuple" title="Link to this heading"></a></h2>
<p>A <a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> is an <a class="reference internal" href="../glossary.html#term-immutable"><span class="xref std std-term">immutable</span></a> sequence. Because a tuple can never
change, there are no insertion or deletion costs, and making a copy simply
returns the same object, so is constant time (<em>O</em>(1)).</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Operation</p></th>
<th class="head"><p>Complexity</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Copy (<code class="docutils literal notranslate"><span class="pre">tuple(t)</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Get item (<code class="docutils literal notranslate"><span class="pre">t[k]</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-even"><td><p>Get slice (<code class="docutils literal notranslate"><span class="pre">t[i:j]</span></code>)</p></td>
<td><p><em>O</em>(<em>j</em> - <em>i</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Concatenate (<code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">+</span> <span class="pre">t2</span></code>)</p></td>
<td><p><em>O</em>(len(<em>t1</em>) + len(<em>t2</em>))</p></td>
</tr>
<tr class="row-even"><td><p>Multiply (<code class="docutils literal notranslate"><span class="pre">t</span> <span class="pre">*</span> <span class="pre">k</span></code>)</p></td>
<td><p><em>O</em>(<em>nk</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Iteration</p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">t</span></code></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">min(t)</span></code>, <code class="docutils literal notranslate"><span class="pre">max(t)</span></code></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Get length (<code class="docutils literal notranslate"><span class="pre">len(t)</span></code>) <a class="footnote-reference brackets" href="#id58" id="id12" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
</tbody>
</table>
</section>
<section id="dict-frozendict">
<h2><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code><a class="headerlink" href="#dict-frozendict" title="Link to this heading"></a></h2>
<p>The times listed for dict objects are average-case times, as they assume the
hash function for the objects is sufficiently robust to make collisions
uncommon. They also assume the keys are well-distributed among the set of
possible keys. In the worst case, when every key hashes to the same value,
each of the <em>O</em>(1) operations below instead takes <em>O</em>(<em>n</em>) time. They also
assume that hashing and comparing a key is <em>O</em>(1). For more detail on the
implementation, see <a class="reference internal" href="../faq/design.html#how-are-dictionaries-implemented"><span class="std std-ref">How are dictionaries implemented in CPython?</span></a>.</p>
<p>A <a class="reference internal" href="stdtypes.html#frozendict" title="frozendict"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a> is immutable, so it does not support setting, deleting,
or updating items. The other operations below apply to it at the same costs.</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Operation</p></th>
<th class="head"><p>Complexity</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">key</span> <span class="pre">in</span> <span class="pre">d</span></code></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Copy (<code class="docutils literal notranslate"><span class="pre">d.copy()</span></code>) <a class="footnote-reference brackets" href="#id59" id="id13" role="doc-noteref"><span class="fn-bracket">[</span>6<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id60" id="id14" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Get item (<code class="docutils literal notranslate"><span class="pre">d[key]</span></code>, <code class="docutils literal notranslate"><span class="pre">d.get(key)</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Set item (<code class="docutils literal notranslate"><span class="pre">d[key]</span> <span class="pre">=</span> <span class="pre">value</span></code>) <a class="footnote-reference brackets" href="#id54" id="id15" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-even"><td><p>Delete item (<code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">d[key]</span></code>, <code class="docutils literal notranslate"><span class="pre">d.pop(key)</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Update (<code class="docutils literal notranslate"><span class="pre">d.update(t)</span></code>, <code class="docutils literal notranslate"><span class="pre">d</span> <span class="pre">|=</span> <span class="pre">t</span></code>) <a class="footnote-reference brackets" href="#id54" id="id16" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id56" id="id17" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id60" id="id18" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(len(<em>t</em>))</p></td>
</tr>
<tr class="row-even"><td><p>Iteration <a class="footnote-reference brackets" href="#id60" id="id19" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Get length (<code class="docutils literal notranslate"><span class="pre">len(d)</span></code>) <a class="footnote-reference brackets" href="#id58" id="id20" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
</tbody>
</table>
</section>
<section id="set-frozenset">
<h2><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code><a class="headerlink" href="#set-frozenset" title="Link to this heading"></a></h2>
<p>See <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> as the <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> and <a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> implementations are
similar, and the same caveats apply.
In the worst case, <em>O</em>(1) operations instead take <em>O</em>(<em>n</em>) time,
and operations that look up every element degrade accordingly.</p>
<p>A <a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> is <a class="reference internal" href="../glossary.html#term-immutable"><span class="xref std std-term">immutable</span></a>, so it does not support adding,
discarding, or the in-place update operations. The others below apply to it at
the same costs.</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Operation</p></th>
<th class="head"><p>Complexity</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">s</span></code></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Copy (<code class="docutils literal notranslate"><span class="pre">s.copy()</span></code>) <a class="footnote-reference brackets" href="#id59" id="id21" role="doc-noteref"><span class="fn-bracket">[</span>6<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id60" id="id22" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Add (<code class="docutils literal notranslate"><span class="pre">s.add(x)</span></code>) <a class="footnote-reference brackets" href="#id54" id="id23" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Discard (<code class="docutils literal notranslate"><span class="pre">s.discard(x)</span></code>, <code class="docutils literal notranslate"><span class="pre">s.remove(x)</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-even"><td><p>Union (<code class="docutils literal notranslate"><span class="pre">s1</span> <span class="pre">|</span> <span class="pre">s2</span></code>, <code class="docutils literal notranslate"><span class="pre">s1.union(s2)</span></code>) <a class="footnote-reference brackets" href="#id60" id="id24" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(len(<em>s1</em>) + len(<em>s2</em>))</p></td>
</tr>
<tr class="row-odd"><td><p>Update (<code class="docutils literal notranslate"><span class="pre">s1</span> <span class="pre">|=</span> <span class="pre">s2</span></code>, <code class="docutils literal notranslate"><span class="pre">s1.update(s2)</span></code>) <a class="footnote-reference brackets" href="#id54" id="id25" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id60" id="id26" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(len(<em>s2</em>))</p></td>
</tr>
<tr class="row-even"><td><p>Intersection (<code class="docutils literal notranslate"><span class="pre">s1</span> <span class="pre">&amp;</span> <span class="pre">s2</span></code>, <code class="docutils literal notranslate"><span class="pre">s1.intersection(s2)</span></code>) <a class="footnote-reference brackets" href="#id60" id="id27" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id61" id="id28" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(min(len(<em>s1</em>), len(<em>s2</em>)))</p></td>
</tr>
<tr class="row-odd"><td><p>Intersection update (<code class="docutils literal notranslate"><span class="pre">s1</span> <span class="pre">&amp;=</span> <span class="pre">s2</span></code>, <code class="docutils literal notranslate"><span class="pre">s1.intersection_update(s2)</span></code>) <a class="footnote-reference brackets" href="#id54" id="id29" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id60" id="id30" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id61" id="id31" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(min(len(<em>s1</em>), len(<em>s2</em>)))</p></td>
</tr>
<tr class="row-even"><td><p>Difference (<code class="docutils literal notranslate"><span class="pre">s1</span> <span class="pre">-</span> <span class="pre">s2</span></code>, <code class="docutils literal notranslate"><span class="pre">s1.difference(s2)</span></code>) <a class="footnote-reference brackets" href="#id60" id="id32" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id62" id="id33" role="doc-noteref"><span class="fn-bracket">[</span>9<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(len(<em>s1</em>))</p></td>
</tr>
<tr class="row-odd"><td><p>Difference update (<code class="docutils literal notranslate"><span class="pre">s1</span> <span class="pre">-=</span> <span class="pre">s2</span></code>, <code class="docutils literal notranslate"><span class="pre">s1.difference_update(s2)</span></code>) <a class="footnote-reference brackets" href="#id54" id="id34" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id60" id="id35" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id61" id="id36" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(min(len(<em>s1</em>), len(<em>s2</em>)))</p></td>
</tr>
<tr class="row-even"><td><p>Symmetric difference (<code class="docutils literal notranslate"><span class="pre">s1</span> <span class="pre">^</span> <span class="pre">s2</span></code>, <code class="docutils literal notranslate"><span class="pre">s1.symmetric_difference(s2)</span></code>) <a class="footnote-reference brackets" href="#id60" id="id37" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(len(<em>s1</em>) + len(<em>s2</em>))</p></td>
</tr>
<tr class="row-odd"><td><p>Symmetric difference update (<code class="docutils literal notranslate"><span class="pre">s1</span> <span class="pre">^=</span> <span class="pre">s2</span></code>, <code class="docutils literal notranslate"><span class="pre">s1.symmetric_difference_update(s2)</span></code>) <a class="footnote-reference brackets" href="#id54" id="id38" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id60" id="id39" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(len(<em>s2</em>))</p></td>
</tr>
<tr class="row-even"><td><p>Get length (<code class="docutils literal notranslate"><span class="pre">len(s)</span></code>) <a class="footnote-reference brackets" href="#id58" id="id40" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
</tbody>
</table>
</section>
<section id="str-bytes-bytearray">
<h2><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code><a class="headerlink" href="#str-bytes-bytearray" title="Link to this heading"></a></h2>
<p><a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> and <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> objects are immutable sequences of characters and
bytes, respectively. As with tuples, copying one returns the original object.
A <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> is mutable, and additionally supports the mutating operations
of <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> (except <code class="xref py py-meth docutils literal notranslate"><span class="pre">sort()</span></code>), at the same costs. However, deleting at
the front with <code class="docutils literal notranslate"><span class="pre">del</span></code> (<code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">b[0]</span></code>, <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">b[:k]</span></code>) only advances the start of
the buffer instead of moving the remaining bytes, and is amortized <em>O</em>(1).</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Operation</p></th>
<th class="head"><p>Complexity</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Get item (<code class="docutils literal notranslate"><span class="pre">s[k]</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Get slice (<code class="docutils literal notranslate"><span class="pre">s[i:j]</span></code>)</p></td>
<td><p><em>O</em>(<em>j</em> - <em>i</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Concatenate (<code class="docutils literal notranslate"><span class="pre">s</span> <span class="pre">+</span> <span class="pre">t</span></code>) <a class="footnote-reference brackets" href="#id63" id="id41" role="doc-noteref"><span class="fn-bracket">[</span>10<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(len(<em>s</em>) + len(<em>t</em>))</p></td>
</tr>
<tr class="row-odd"><td><p>Multiply (<code class="docutils literal notranslate"><span class="pre">s</span> <span class="pre">*</span> <span class="pre">k</span></code>)</p></td>
<td><p><em>O</em>(<em>nk</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Substring search (<code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">s</span></code>, <code class="docutils literal notranslate"><span class="pre">s.find(x)</span></code>, <code class="docutils literal notranslate"><span class="pre">s.index(x)</span></code>) <a class="footnote-reference brackets" href="#id64" id="id42" role="doc-noteref"><span class="fn-bracket">[</span>11<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Reverse substring search (<code class="docutils literal notranslate"><span class="pre">s.rfind(x)</span></code>, <code class="docutils literal notranslate"><span class="pre">s.rindex(x)</span></code>) <a class="footnote-reference brackets" href="#id64" id="id43" role="doc-noteref"><span class="fn-bracket">[</span>11<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id65" id="id44" role="doc-noteref"><span class="fn-bracket">[</span>12<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em> × len(<em>x</em>))</p></td>
</tr>
<tr class="row-even"><td><p>Encode or decode <a class="footnote-reference brackets" href="#id66" id="id45" role="doc-noteref"><span class="fn-bracket">[</span>13<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Iteration</p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Get length (<code class="docutils literal notranslate"><span class="pre">len(s)</span></code>) <a class="footnote-reference brackets" href="#id58" id="id46" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
</tbody>
</table>
</section>
<section id="memoryview">
<h2><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code><a class="headerlink" href="#memoryview" title="Link to this heading"></a></h2>
<p><a class="reference internal" href="stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> objects allow Python code to access the internal data
of an object that supports the <a class="reference internal" href="../c-api/buffer.html#bufferobjects"><span class="std std-ref">buffer protocol</span></a> without
copying. In particular, slicing a memory view returns a new view onto the same
buffer.</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Operation</p></th>
<th class="head"><p>Complexity</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Create (<code class="docutils literal notranslate"><span class="pre">memoryview(obj)</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Get item (<code class="docutils literal notranslate"><span class="pre">v[k]</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-even"><td><p>Get slice (<code class="docutils literal notranslate"><span class="pre">v[i:j]</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Index (<code class="docutils literal notranslate"><span class="pre">v.index(x)</span></code>) <a class="footnote-reference brackets" href="#id64" id="id47" role="doc-noteref"><span class="fn-bracket">[</span>11<span class="fn-bracket">]</span></a> <a class="footnote-reference brackets" href="#id67" id="id48" role="doc-noteref"><span class="fn-bracket">[</span>14<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Count (<code class="docutils literal notranslate"><span class="pre">v.count(x)</span></code>) <a class="footnote-reference brackets" href="#id67" id="id49" role="doc-noteref"><span class="fn-bracket">[</span>14<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-odd"><td><p>Convert to bytes (<code class="docutils literal notranslate"><span class="pre">v.tobytes()</span></code>, <code class="docutils literal notranslate"><span class="pre">bytes(v)</span></code>)</p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Get length (<code class="docutils literal notranslate"><span class="pre">len(v)</span></code>) <a class="footnote-reference brackets" href="#id58" id="id50" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
</tbody>
</table>
</section>
<section id="range">
<h2><code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code><a class="headerlink" href="#range" title="Link to this heading"></a></h2>
<p>A <a class="reference internal" href="stdtypes.html#range" title="range"><code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code></a> object computes its items on demand from its <em>start</em>, <em>stop</em> and
<em>step</em> values, so most operations do not depend on the length of the range.</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Operation</p></th>
<th class="head"><p>Complexity</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Get item (<code class="docutils literal notranslate"><span class="pre">r[k]</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Get slice (<code class="docutils literal notranslate"><span class="pre">r[i:j]</span></code>)</p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">r</span></code> <a class="footnote-reference brackets" href="#id68" id="id51" role="doc-noteref"><span class="fn-bracket">[</span>15<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-odd"><td><p>Index and count (<code class="docutils literal notranslate"><span class="pre">r.index(x)</span></code>, <code class="docutils literal notranslate"><span class="pre">r.count(x)</span></code>) <a class="footnote-reference brackets" href="#id68" id="id52" role="doc-noteref"><span class="fn-bracket">[</span>15<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
<tr class="row-even"><td><p>Iteration</p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">min(r)</span></code>, <code class="docutils literal notranslate"><span class="pre">max(r)</span></code></p></td>
<td><p><em>O</em>(<em>n</em>)</p></td>
</tr>
<tr class="row-even"><td><p>Get length (<code class="docutils literal notranslate"><span class="pre">len(r)</span></code>) <a class="footnote-reference brackets" href="#id58" id="id53" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a></p></td>
<td><p><em>O</em>(1)</p></td>
</tr>
</tbody>
</table>
</section>
<section id="notes">
<h2>Notes<a class="headerlink" href="#notes" title="Link to this heading"></a></h2>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id54" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id2">2</a>,<a role="doc-backlink" href="#id4">3</a>,<a role="doc-backlink" href="#id7">4</a>,<a role="doc-backlink" href="#id8">5</a>,<a role="doc-backlink" href="#id15">6</a>,<a role="doc-backlink" href="#id16">7</a>,<a role="doc-backlink" href="#id23">8</a>,<a role="doc-backlink" href="#id25">9</a>,<a role="doc-backlink" href="#id29">10</a>,<a role="doc-backlink" href="#id34">11</a>,<a role="doc-backlink" href="#id38">12</a>)</span>
<p>Amortized. An individual operation may occasionally be <em>O</em>(<em>n</em>)
when the underlying storage is resized, but this cost is spread over
many operations, depending on the history of the container.</p>
</aside>
<aside class="footnote brackets" id="id55" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id3">1</a>,<a role="doc-backlink" href="#id5">2</a>,<a role="doc-backlink" href="#id6">3</a>)</span>
<p>Popping or deleting the element at index <em>k</em> of a list of size <em>n</em>
shifts all elements after <em>k</em> one slot to the left, moving <em>n</em> - <em>k</em> - 1
elements; inserting at index <em>k</em> shifts the elements from <em>k</em> onwards one
slot to the right, moving <em>n</em> - <em>k</em> elements. The worst case is index 0,
where the whole rest of the list has to be moved; the average case, an
index in the middle of the list, takes <em>O</em>(<em>n</em>/2) = <em>O</em>(<em>n</em>)
operations; and operating at the end of the list moves nothing and is
<em>O</em>(1).</p>
</aside>
<aside class="footnote brackets" id="id56" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id9">1</a>,<a role="doc-backlink" href="#id17">2</a>)</span>
<p>Plus the cost of iterating over <em>t</em>, which may be expensive for an
arbitrary iterable.</p>
</aside>
<aside class="footnote brackets" id="id57" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id10">4</a><span class="fn-bracket">]</span></span>
<p>This is the worst case scenario. Sorting is adaptive and input that is
already sorted or reverse-sorted takes only <em>O</em>(<em>n</em>) comparisons.
See <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Objects/listsort.txt">Objects/listsort.txt</a> for more information.</p>
</aside>
<aside class="footnote brackets" id="id58" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id11">1</a>,<a role="doc-backlink" href="#id12">2</a>,<a role="doc-backlink" href="#id20">3</a>,<a role="doc-backlink" href="#id40">4</a>,<a role="doc-backlink" href="#id46">5</a>,<a role="doc-backlink" href="#id50">6</a>,<a role="doc-backlink" href="#id53">7</a>)</span>
<p>The number of elements is stored in the object, so <code class="docutils literal notranslate"><span class="pre">len()</span></code> does
not need to count them.</p>
</aside>
<aside class="footnote brackets" id="id59" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>6<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id13">1</a>,<a role="doc-backlink" href="#id21">2</a>)</span>
<p>Copying a <a class="reference internal" href="stdtypes.html#frozendict" title="frozendict"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a> or a <a class="reference internal" href="stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> is <em>O</em>(1) as it
returns the original object.</p>
</aside>
<aside class="footnote brackets" id="id60" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id14">1</a>,<a role="doc-backlink" href="#id18">2</a>,<a role="doc-backlink" href="#id19">3</a>,<a role="doc-backlink" href="#id22">4</a>,<a role="doc-backlink" href="#id24">5</a>,<a role="doc-backlink" href="#id26">6</a>,<a role="doc-backlink" href="#id27">7</a>,<a role="doc-backlink" href="#id30">8</a>,<a role="doc-backlink" href="#id32">9</a>,<a role="doc-backlink" href="#id35">10</a>,<a role="doc-backlink" href="#id37">11</a>,<a role="doc-backlink" href="#id39">12</a>)</span>
<p>These operations scan the container’s internal hash table, which is
not shrunk when elements are removed. After removing most elements, they
still take time proportional to the container’s former size, until a
later insertion triggers a resize.</p>
</aside>
<aside class="footnote brackets" id="id61" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id28">1</a>,<a role="doc-backlink" href="#id31">2</a>,<a role="doc-backlink" href="#id36">3</a>)</span>
<p><em>O</em>(len(<em>t</em>)) if <em>t</em> is not a set.</p>
</aside>
<aside class="footnote brackets" id="id62" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id33">9</a><span class="fn-bracket">]</span></span>
<p><em>O</em>(len(<em>s</em>) + len(<em>t</em>)) if <em>t</em> is not a set.</p>
</aside>
<aside class="footnote brackets" id="id63" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id41">10</a><span class="fn-bracket">]</span></span>
<p>Each concatenation builds a new object, so building a string by
concatenating many pieces in a loop is quadratic in the total length.
See the <a class="reference internal" href="stdtypes.html#typesseq-repeated-concatenation"><span class="std std-ref">note on concatenating immutable sequences</span></a> for alternatives.</p>
</aside>
<aside class="footnote brackets" id="id64" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>11<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id42">1</a>,<a role="doc-backlink" href="#id43">2</a>,<a role="doc-backlink" href="#id47">3</a>)</span>
<p>With <em>start</em> and <em>end</em> arguments, <em>n</em> is the length of the region
searched rather than of <em>s</em>, and unlike slicing nothing is copied.</p>
</aside>
<aside class="footnote brackets" id="id65" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id44">12</a><span class="fn-bracket">]</span></span>
<p>This is the worst case. Reverse searches are <em>O</em>(<em>n</em>) on typical
input. Forward searches instead use a more elaborate algorithm with a
linear worst case, described in
<a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Objects/stringlib/stringlib_find_two_way_notes.txt">Objects/stringlib/stringlib_find_two_way_notes.txt</a>.</p>
</aside>
<aside class="footnote brackets" id="id66" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id45">13</a><span class="fn-bracket">]</span></span>
<p>This assumes a codec that does a constant amount of work per character.</p>
</aside>
<aside class="footnote brackets" id="id67" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>14<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id48">1</a>,<a role="doc-backlink" href="#id49">2</a>)</span>
<p>These unpack and compare each element individually, so they are much
slower than the equivalent <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> methods.</p>
</aside>
<aside class="footnote brackets" id="id68" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>15<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id51">1</a>,<a role="doc-backlink" href="#id52">2</a>)</span>
<p>Assuming <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> or <a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a> arguments. For other types,
the range is searched like any other sequence in <em>O</em>(<em>n</em>) time.</p>
</aside>
</aside>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Time complexity of operations on built-in types</a><ul>
<li><a class="reference internal" href="#list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a></li>
<li><a class="reference internal" href="#tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a></li>
<li><a class="reference internal" href="#dict-frozendict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a></li>
<li><a class="reference internal" href="#set-frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a></li>
<li><a class="reference internal" href="#str-bytes-bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a></li>
<li><a class="reference internal" href="#memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a></li>
<li><a class="reference internal" href="#range"><code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code></a></li>
<li><a class="reference internal" href="#notes">Notes</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="threadsafety.html"
title="previous chapter">Thread Safety Guarantees</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="../library/index.html"
title="next chapter">The Python standard library</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "builtins/time-complexity.rst");
element.href = url.toString();
});
});
</script>
<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 class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/builtins/time-complexity.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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="../library/index.html" title="The Python standard library"
>next</a> |</li>
<li class="right" >
<a href="threadsafety.html" title="Thread Safety Guarantees"
>previous</a> |</li>
<li class="root-icon"><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> &#187;</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.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python built-ins reference</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Time complexity of operations on built-in types</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="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001 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 Oct 09, 2026 (11:35 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>