1465 lines
170 KiB
HTML
1465 lines
170 KiB
HTML
<!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="Glossary" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/glossary.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content=">>>, The default Python prompt of the interactive shell. Often seen for code examples which can be executed interactively in the interpreter.,,..., Can refer to:- The default Python prompt of the i..." />
|
||
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content=">>>, The default Python prompt of the interactive shell. Often seen for code examples which can be executed interactively in the interpreter.,,..., Can refer to:- The default Python prompt of the i..." />
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="theme-color" content="#3776ab">
|
||
|
||
<title>Glossary — Python 3.13.3 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/pydoctheme.css?v=23252803" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="_static/pygments_dark.css?v=5349f25f" />
|
||
|
||
<script src="_static/documentation_options.js?v=5d57ca2d"></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.13.3 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="About this documentation" href="about.html" />
|
||
<link rel="prev" title="Deprecations" href="deprecations/index.html" />
|
||
|
||
<link rel="canonical" href="https://docs.python.org/3/glossary.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="deprecations/index.html"
|
||
title="previous chapter">Deprecations</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="about.html"
|
||
title="next chapter">About this documentation</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/glossary.rst"
|
||
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="about.html" title="About this documentation"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="deprecations/index.html" title="Deprecations"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li><img src="_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-this"><a href="">Glossary</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="glossary">
|
||
<span id="id1"></span><h1>Glossary<a class="headerlink" href="#glossary" title="Link to this heading">¶</a></h1>
|
||
<dl class="glossary">
|
||
<dt id="term-0"><code class="docutils literal notranslate"><span class="pre">>>></span></code><a class="headerlink" href="#term-0" title="Link to this term">¶</a></dt><dd><p>The default Python prompt of the <a class="reference internal" href="#term-interactive"><span class="xref std std-term">interactive</span></a> shell. Often
|
||
seen for code examples which can be executed interactively in the
|
||
interpreter.</p>
|
||
</dd>
|
||
<dt id="term-..."><code class="docutils literal notranslate"><span class="pre">...</span></code><a class="headerlink" href="#term-..." title="Link to this term">¶</a></dt><dd><p>Can refer to:</p>
|
||
<ul class="simple">
|
||
<li><p>The default Python prompt of the <a class="reference internal" href="#term-interactive"><span class="xref std std-term">interactive</span></a> shell when entering the
|
||
code for an indented code block, when within a pair of matching left and
|
||
right delimiters (parentheses, square brackets, curly braces or triple
|
||
quotes), or after specifying a decorator.</p></li>
|
||
<li><p>The <a class="reference internal" href="library/constants.html#Ellipsis" title="Ellipsis"><code class="xref py py-const docutils literal notranslate"><span class="pre">Ellipsis</span></code></a> built-in constant.</p></li>
|
||
</ul>
|
||
</dd>
|
||
<dt id="term-abstract-base-class">abstract base class<a class="headerlink" href="#term-abstract-base-class" title="Link to this term">¶</a></dt><dd><p>Abstract base classes complement <a class="reference internal" href="#term-duck-typing"><span class="xref std std-term">duck-typing</span></a> by
|
||
providing a way to define interfaces when other techniques like
|
||
<a class="reference internal" href="library/functions.html#hasattr" title="hasattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">hasattr()</span></code></a> would be clumsy or subtly wrong (for example with
|
||
<a class="reference internal" href="reference/datamodel.html#special-lookup"><span class="std std-ref">magic methods</span></a>). ABCs introduce virtual
|
||
subclasses, which are classes that don’t inherit from a class but are
|
||
still recognized by <a class="reference internal" href="library/functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a> and <a class="reference internal" href="library/functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">issubclass()</span></code></a>; see the
|
||
<a class="reference internal" href="library/abc.html#module-abc" title="abc: Abstract base classes according to :pep:`3119`."><code class="xref py py-mod docutils literal notranslate"><span class="pre">abc</span></code></a> module documentation. Python comes with many built-in ABCs for
|
||
data structures (in the <a class="reference internal" href="library/collections.abc.html#module-collections.abc" title="collections.abc: Abstract base classes for containers"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code></a> module), numbers (in the
|
||
<a class="reference internal" href="library/numbers.html#module-numbers" title="numbers: Numeric abstract base classes (Complex, Real, Integral, etc.)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">numbers</span></code></a> module), streams (in the <a class="reference internal" href="library/io.html#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code></a> module), import finders
|
||
and loaders (in the <a class="reference internal" href="library/importlib.html#module-importlib.abc" title="importlib.abc: Abstract base classes related to import"><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.abc</span></code></a> module). You can create your own
|
||
ABCs with the <a class="reference internal" href="library/abc.html#module-abc" title="abc: Abstract base classes according to :pep:`3119`."><code class="xref py py-mod docutils literal notranslate"><span class="pre">abc</span></code></a> module.</p>
|
||
</dd>
|
||
<dt id="term-annotation">annotation<a class="headerlink" href="#term-annotation" title="Link to this term">¶</a></dt><dd><p>A label associated with a variable, a class
|
||
attribute or a function parameter or return value,
|
||
used by convention as a <a class="reference internal" href="#term-type-hint"><span class="xref std std-term">type hint</span></a>.</p>
|
||
<p>Annotations of local variables cannot be accessed at runtime, but
|
||
annotations of global variables, class attributes, and functions
|
||
are stored in the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code>
|
||
special attribute of modules, classes, and functions,
|
||
respectively.</p>
|
||
<p>See <a class="reference internal" href="#term-variable-annotation"><span class="xref std std-term">variable annotation</span></a>, <a class="reference internal" href="#term-function-annotation"><span class="xref std std-term">function annotation</span></a>, <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a>
|
||
and <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0526/"><strong>PEP 526</strong></a>, which describe this functionality.
|
||
Also see <a class="reference internal" href="howto/annotations.html#annotations-howto"><span class="std std-ref">Annotations Best Practices</span></a>
|
||
for best practices on working with annotations.</p>
|
||
</dd>
|
||
<dt id="term-argument">argument<a class="headerlink" href="#term-argument" title="Link to this term">¶</a></dt><dd><p>A value passed to a <a class="reference internal" href="#term-function"><span class="xref std std-term">function</span></a> (or <a class="reference internal" href="#term-method"><span class="xref std std-term">method</span></a>) when calling the
|
||
function. There are two kinds of argument:</p>
|
||
<ul>
|
||
<li><p><em class="dfn">keyword argument</em>: an argument preceded by an identifier (e.g.
|
||
<code class="docutils literal notranslate"><span class="pre">name=</span></code>) in a function call or passed as a value in a dictionary
|
||
preceded by <code class="docutils literal notranslate"><span class="pre">**</span></code>. For example, <code class="docutils literal notranslate"><span class="pre">3</span></code> and <code class="docutils literal notranslate"><span class="pre">5</span></code> are both keyword
|
||
arguments in the following calls to <a class="reference internal" href="library/functions.html#complex" title="complex"><code class="xref py py-func docutils literal notranslate"><span class="pre">complex()</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">complex</span><span class="p">(</span><span class="n">real</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">imag</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
|
||
<span class="nb">complex</span><span class="p">(</span><span class="o">**</span><span class="p">{</span><span class="s1">'real'</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s1">'imag'</span><span class="p">:</span> <span class="mi">5</span><span class="p">})</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><em class="dfn">positional argument</em>: an argument that is not a keyword argument.
|
||
Positional arguments can appear at the beginning of an argument list
|
||
and/or be passed as elements of an <a class="reference internal" href="#term-iterable"><span class="xref std std-term">iterable</span></a> preceded by <code class="docutils literal notranslate"><span class="pre">*</span></code>.
|
||
For example, <code class="docutils literal notranslate"><span class="pre">3</span></code> and <code class="docutils literal notranslate"><span class="pre">5</span></code> are both positional arguments in the
|
||
following calls:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">complex</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>
|
||
<span class="nb">complex</span><span class="p">(</span><span class="o">*</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">5</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>Arguments are assigned to the named local variables in a function body.
|
||
See the <a class="reference internal" href="reference/expressions.html#calls"><span class="std std-ref">Calls</span></a> section for the rules governing this assignment.
|
||
Syntactically, any expression can be used to represent an argument; the
|
||
evaluated value is assigned to the local variable.</p>
|
||
<p>See also the <a class="reference internal" href="#term-parameter"><span class="xref std std-term">parameter</span></a> glossary entry, the FAQ question on
|
||
<a class="reference internal" href="faq/programming.html#faq-argument-vs-parameter"><span class="std std-ref">the difference between arguments and parameters</span></a>, and <span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0362/"><strong>PEP 362</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-asynchronous-context-manager">asynchronous context manager<a class="headerlink" href="#term-asynchronous-context-manager" title="Link to this term">¶</a></dt><dd><p>An object which controls the environment seen in an
|
||
<a class="reference internal" href="reference/compound_stmts.html#async-with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code></a> statement by defining <a class="reference internal" href="reference/datamodel.html#object.__aenter__" title="object.__aenter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aenter__()</span></code></a> and
|
||
<a class="reference internal" href="reference/datamodel.html#object.__aexit__" title="object.__aexit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aexit__()</span></code></a> methods. Introduced by <span class="target" id="index-3"></span><a class="pep reference external" href="https://peps.python.org/pep-0492/"><strong>PEP 492</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-asynchronous-generator">asynchronous generator<a class="headerlink" href="#term-asynchronous-generator" title="Link to this term">¶</a></dt><dd><p>A function which returns an <a class="reference internal" href="#term-asynchronous-generator-iterator"><span class="xref std std-term">asynchronous generator iterator</span></a>. It
|
||
looks like a coroutine function defined with <a class="reference internal" href="reference/compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> except
|
||
that it contains <a class="reference internal" href="reference/simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> expressions for producing a series of
|
||
values usable in an <a class="reference internal" href="reference/compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a> loop.</p>
|
||
<p>Usually refers to an asynchronous generator function, but may refer to an
|
||
<em>asynchronous generator iterator</em> in some contexts. In cases where the
|
||
intended meaning isn’t clear, using the full terms avoids ambiguity.</p>
|
||
<p>An asynchronous generator function may contain <a class="reference internal" href="reference/expressions.html#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a>
|
||
expressions as well as <a class="reference internal" href="reference/compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a>, and <a class="reference internal" href="reference/compound_stmts.html#async-with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code></a>
|
||
statements.</p>
|
||
</dd>
|
||
<dt id="term-asynchronous-generator-iterator">asynchronous generator iterator<a class="headerlink" href="#term-asynchronous-generator-iterator" title="Link to this term">¶</a></dt><dd><p>An object created by a <a class="reference internal" href="#term-asynchronous-generator"><span class="xref std std-term">asynchronous generator</span></a> function.</p>
|
||
<p>This is an <a class="reference internal" href="#term-asynchronous-iterator"><span class="xref std std-term">asynchronous iterator</span></a> which when called using the
|
||
<a class="reference internal" href="reference/datamodel.html#object.__anext__" title="object.__anext__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__anext__()</span></code></a> method returns an awaitable object which will execute
|
||
the body of the asynchronous generator function until the next
|
||
<a class="reference internal" href="reference/simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> expression.</p>
|
||
<p>Each <a class="reference internal" href="reference/simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> temporarily suspends processing, remembering the
|
||
execution state (including local variables and pending
|
||
try-statements). When the <em>asynchronous generator iterator</em> effectively
|
||
resumes with another awaitable returned by <a class="reference internal" href="reference/datamodel.html#object.__anext__" title="object.__anext__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__anext__()</span></code></a>, it
|
||
picks up where it left off. See <span class="target" id="index-4"></span><a class="pep reference external" href="https://peps.python.org/pep-0492/"><strong>PEP 492</strong></a> and <span class="target" id="index-5"></span><a class="pep reference external" href="https://peps.python.org/pep-0525/"><strong>PEP 525</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-asynchronous-iterable">asynchronous iterable<a class="headerlink" href="#term-asynchronous-iterable" title="Link to this term">¶</a></dt><dd><p>An object, that can be used in an <a class="reference internal" href="reference/compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a> statement.
|
||
Must return an <a class="reference internal" href="#term-asynchronous-iterator"><span class="xref std std-term">asynchronous iterator</span></a> from its
|
||
<a class="reference internal" href="reference/datamodel.html#object.__aiter__" title="object.__aiter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aiter__()</span></code></a> method. Introduced by <span class="target" id="index-6"></span><a class="pep reference external" href="https://peps.python.org/pep-0492/"><strong>PEP 492</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-asynchronous-iterator">asynchronous iterator<a class="headerlink" href="#term-asynchronous-iterator" title="Link to this term">¶</a></dt><dd><p>An object that implements the <a class="reference internal" href="reference/datamodel.html#object.__aiter__" title="object.__aiter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aiter__()</span></code></a> and <a class="reference internal" href="reference/datamodel.html#object.__anext__" title="object.__anext__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__anext__()</span></code></a>
|
||
methods. <a class="reference internal" href="reference/datamodel.html#object.__anext__" title="object.__anext__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__anext__()</span></code></a> must return an <a class="reference internal" href="#term-awaitable"><span class="xref std std-term">awaitable</span></a> object.
|
||
<a class="reference internal" href="reference/compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a> resolves the awaitables returned by an asynchronous
|
||
iterator’s <a class="reference internal" href="reference/datamodel.html#object.__anext__" title="object.__anext__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__anext__()</span></code></a> method until it raises a
|
||
<a class="reference internal" href="library/exceptions.html#StopAsyncIteration" title="StopAsyncIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopAsyncIteration</span></code></a> exception. Introduced by <span class="target" id="index-7"></span><a class="pep reference external" href="https://peps.python.org/pep-0492/"><strong>PEP 492</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-attribute">attribute<a class="headerlink" href="#term-attribute" title="Link to this term">¶</a></dt><dd><p>A value associated with an object which is usually referenced by name
|
||
using dotted expressions.
|
||
For example, if an object <em>o</em> has an attribute
|
||
<em>a</em> it would be referenced as <em>o.a</em>.</p>
|
||
<p>It is possible to give an object an attribute whose name is not an
|
||
identifier as defined by <a class="reference internal" href="reference/lexical_analysis.html#identifiers"><span class="std std-ref">Identifiers and keywords</span></a>, for example using
|
||
<a class="reference internal" href="library/functions.html#setattr" title="setattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">setattr()</span></code></a>, if the object allows it.
|
||
Such an attribute will not be accessible using a dotted expression,
|
||
and would instead need to be retrieved with <a class="reference internal" href="library/functions.html#getattr" title="getattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">getattr()</span></code></a>.</p>
|
||
</dd>
|
||
<dt id="term-awaitable">awaitable<a class="headerlink" href="#term-awaitable" title="Link to this term">¶</a></dt><dd><p>An object that can be used in an <a class="reference internal" href="reference/expressions.html#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a> expression. Can be
|
||
a <a class="reference internal" href="#term-coroutine"><span class="xref std std-term">coroutine</span></a> or an object with an <a class="reference internal" href="reference/datamodel.html#object.__await__" title="object.__await__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code></a> method.
|
||
See also <span class="target" id="index-8"></span><a class="pep reference external" href="https://peps.python.org/pep-0492/"><strong>PEP 492</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-BDFL">BDFL<a class="headerlink" href="#term-BDFL" title="Link to this term">¶</a></dt><dd><p>Benevolent Dictator For Life, a.k.a. <a class="reference external" href="https://gvanrossum.github.io/">Guido van Rossum</a>, Python’s creator.</p>
|
||
</dd>
|
||
<dt id="term-binary-file">binary file<a class="headerlink" href="#term-binary-file" title="Link to this term">¶</a></dt><dd><p>A <a class="reference internal" href="#term-file-object"><span class="xref std std-term">file object</span></a> able to read and write
|
||
<a class="reference internal" href="#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>.
|
||
Examples of binary files are files opened in binary mode (<code class="docutils literal notranslate"><span class="pre">'rb'</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">'wb'</span></code> or <code class="docutils literal notranslate"><span class="pre">'rb+'</span></code>), <a class="reference internal" href="library/sys.html#sys.stdin" title="sys.stdin"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdin.buffer</span></code></a>,
|
||
<a class="reference internal" href="library/sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout.buffer</span></code></a>, and instances of
|
||
<a class="reference internal" href="library/io.html#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BytesIO</span></code></a> and <a class="reference internal" href="library/gzip.html#gzip.GzipFile" title="gzip.GzipFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">gzip.GzipFile</span></code></a>.</p>
|
||
<p>See also <a class="reference internal" href="#term-text-file"><span class="xref std std-term">text file</span></a> for a file object able to read and write
|
||
<a class="reference internal" href="library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> objects.</p>
|
||
</dd>
|
||
<dt id="term-borrowed-reference">borrowed reference<a class="headerlink" href="#term-borrowed-reference" title="Link to this term">¶</a></dt><dd><p>In Python’s C API, a borrowed reference is a reference to an object,
|
||
where the code using the object does not own the reference.
|
||
It becomes a dangling
|
||
pointer if the object is destroyed. For example, a garbage collection can
|
||
remove the last <a class="reference internal" href="#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to the object and so destroy it.</p>
|
||
<p>Calling <a class="reference internal" href="c-api/refcounting.html#c.Py_INCREF" title="Py_INCREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_INCREF()</span></code></a> on the <a class="reference internal" href="#term-borrowed-reference"><span class="xref std std-term">borrowed reference</span></a> is
|
||
recommended to convert it to a <a class="reference internal" href="#term-strong-reference"><span class="xref std std-term">strong reference</span></a> in-place, except
|
||
when the object cannot be destroyed before the last usage of the borrowed
|
||
reference. The <a class="reference internal" href="c-api/refcounting.html#c.Py_NewRef" title="Py_NewRef"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_NewRef()</span></code></a> function can be used to create a new
|
||
<a class="reference internal" href="#term-strong-reference"><span class="xref std std-term">strong reference</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-bytes-like-object">bytes-like object<a class="headerlink" href="#term-bytes-like-object" title="Link to this term">¶</a></dt><dd><p>An object that supports the <a class="reference internal" href="c-api/buffer.html#bufferobjects"><span class="std std-ref">Buffer Protocol</span></a> and can
|
||
export a C-<a class="reference internal" href="#term-contiguous"><span class="xref std std-term">contiguous</span></a> buffer. This includes all <a class="reference internal" href="library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>,
|
||
<a class="reference internal" href="library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>, and <a class="reference internal" href="library/array.html#array.array" title="array.array"><code class="xref py py-class docutils literal notranslate"><span class="pre">array.array</span></code></a> objects, as well as many
|
||
common <a class="reference internal" href="library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> objects. Bytes-like objects can
|
||
be used for various operations that work with binary data; these include
|
||
compression, saving to a binary file, and sending over a socket.</p>
|
||
<p>Some operations need the binary data to be mutable. The documentation
|
||
often refers to these as “read-write bytes-like objects”. Example
|
||
mutable buffer objects include <a class="reference internal" href="library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> and a
|
||
<a class="reference internal" href="library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> of a <a class="reference internal" href="library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>.
|
||
Other operations require the binary data to be stored in
|
||
immutable objects (“read-only bytes-like objects”); examples
|
||
of these include <a class="reference internal" href="library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> and a <a class="reference internal" href="library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a>
|
||
of a <a class="reference internal" href="library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>
|
||
</dd>
|
||
<dt id="term-bytecode">bytecode<a class="headerlink" href="#term-bytecode" title="Link to this term">¶</a></dt><dd><p>Python source code is compiled into bytecode, the internal representation
|
||
of a Python program in the CPython interpreter. The bytecode is also
|
||
cached in <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files so that executing the same file is
|
||
faster the second time (recompilation from source to bytecode can be
|
||
avoided). This “intermediate language” is said to run on a
|
||
<a class="reference internal" href="#term-virtual-machine"><span class="xref std std-term">virtual machine</span></a> that executes the machine code corresponding to
|
||
each bytecode. Do note that bytecodes are not expected to work between
|
||
different Python virtual machines, nor to be stable between Python
|
||
releases.</p>
|
||
<p>A list of bytecode instructions can be found in the documentation for
|
||
<a class="reference internal" href="library/dis.html#bytecodes"><span class="std std-ref">the dis module</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-callable">callable<a class="headerlink" href="#term-callable" title="Link to this term">¶</a></dt><dd><p>A callable is an object that can be called, possibly with a set
|
||
of arguments (see <a class="reference internal" href="#term-argument"><span class="xref std std-term">argument</span></a>), with the following syntax:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">callable</span><span class="p">(</span><span class="n">argument1</span><span class="p">,</span> <span class="n">argument2</span><span class="p">,</span> <span class="n">argumentN</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A <a class="reference internal" href="#term-function"><span class="xref std std-term">function</span></a>, and by extension a <a class="reference internal" href="#term-method"><span class="xref std std-term">method</span></a>, is a callable.
|
||
An instance of a class that implements the <a class="reference internal" href="reference/datamodel.html#object.__call__" title="object.__call__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code></a>
|
||
method is also a callable.</p>
|
||
</dd>
|
||
<dt id="term-callback">callback<a class="headerlink" href="#term-callback" title="Link to this term">¶</a></dt><dd><p>A subroutine function which is passed as an argument to be executed at
|
||
some point in the future.</p>
|
||
</dd>
|
||
<dt id="term-class">class<a class="headerlink" href="#term-class" title="Link to this term">¶</a></dt><dd><p>A template for creating user-defined objects. Class definitions
|
||
normally contain method definitions which operate on instances of the
|
||
class.</p>
|
||
</dd>
|
||
<dt id="term-class-variable">class variable<a class="headerlink" href="#term-class-variable" title="Link to this term">¶</a></dt><dd><p>A variable defined in a class and intended to be modified only at
|
||
class level (i.e., not in an instance of the class).</p>
|
||
</dd>
|
||
<dt id="term-closure-variable">closure variable<a class="headerlink" href="#term-closure-variable" title="Link to this term">¶</a></dt><dd><p>A <a class="reference internal" href="#term-free-variable"><span class="xref std std-term">free variable</span></a> referenced from a <a class="reference internal" href="#term-nested-scope"><span class="xref std std-term">nested scope</span></a> that is defined in an outer
|
||
scope rather than being resolved at runtime from the globals or builtin namespaces.
|
||
May be explicitly defined with the <a class="reference internal" href="reference/simple_stmts.html#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a> keyword to allow write access,
|
||
or implicitly defined if the variable is only being read.</p>
|
||
<p>For example, in the <code class="docutils literal notranslate"><span class="pre">inner</span></code> function in the following code, both <code class="docutils literal notranslate"><span class="pre">x</span></code> and <code class="docutils literal notranslate"><span class="pre">print</span></code> are
|
||
<a class="reference internal" href="#term-free-variable"><span class="xref std std-term">free variables</span></a>, but only <code class="docutils literal notranslate"><span class="pre">x</span></code> is a <em>closure variable</em>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">outer</span><span class="p">():</span>
|
||
<span class="n">x</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">inner</span><span class="p">():</span>
|
||
<span class="k">nonlocal</span> <span class="n">x</span>
|
||
<span class="n">x</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
|
||
<span class="k">return</span> <span class="n">inner</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Due to the <a class="reference internal" href="reference/datamodel.html#codeobject.co_freevars" title="codeobject.co_freevars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">codeobject.co_freevars</span></code></a> attribute (which, despite its name, only
|
||
includes the names of closure variables rather than listing all referenced free
|
||
variables), the more general <a class="reference internal" href="#term-free-variable"><span class="xref std std-term">free variable</span></a> term is sometimes used even
|
||
when the intended meaning is to refer specifically to closure variables.</p>
|
||
</dd>
|
||
<dt id="term-complex-number">complex number<a class="headerlink" href="#term-complex-number" title="Link to this term">¶</a></dt><dd><p>An extension of the familiar real number system in which all numbers are
|
||
expressed as a sum of a real part and an imaginary part. Imaginary
|
||
numbers are real multiples of the imaginary unit (the square root of
|
||
<code class="docutils literal notranslate"><span class="pre">-1</span></code>), often written <code class="docutils literal notranslate"><span class="pre">i</span></code> in mathematics or <code class="docutils literal notranslate"><span class="pre">j</span></code> in
|
||
engineering. Python has built-in support for complex numbers, which are
|
||
written with this latter notation; the imaginary part is written with a
|
||
<code class="docutils literal notranslate"><span class="pre">j</span></code> suffix, e.g., <code class="docutils literal notranslate"><span class="pre">3+1j</span></code>. To get access to complex equivalents of the
|
||
<a class="reference internal" href="library/math.html#module-math" title="math: Mathematical functions (sin() etc.)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">math</span></code></a> module, use <a class="reference internal" href="library/cmath.html#module-cmath" title="cmath: Mathematical functions for complex numbers."><code class="xref py py-mod docutils literal notranslate"><span class="pre">cmath</span></code></a>. Use of complex numbers is a fairly
|
||
advanced mathematical feature. If you’re not aware of a need for them,
|
||
it’s almost certain you can safely ignore them.</p>
|
||
</dd>
|
||
<dt id="term-context">context<a class="headerlink" href="#term-context" title="Link to this term">¶</a></dt><dd><p>This term has different meanings depending on where and how it is used.
|
||
Some common meanings:</p>
|
||
<ul class="simple">
|
||
<li><p>The temporary state or environment established by a <a class="reference internal" href="#term-context-manager"><span class="xref std std-term">context
|
||
manager</span></a> via a <a class="reference internal" href="reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement.</p></li>
|
||
<li><p>The collection of keyvalue bindings associated with a particular
|
||
<a class="reference internal" href="library/contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">contextvars.Context</span></code></a> object and accessed via
|
||
<a class="reference internal" href="library/contextvars.html#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextVar</span></code></a> objects. Also see <a class="reference internal" href="#term-context-variable"><span class="xref std std-term">context
|
||
variable</span></a>.</p></li>
|
||
<li><p>A <a class="reference internal" href="library/contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">contextvars.Context</span></code></a> object. Also see <a class="reference internal" href="#term-current-context"><span class="xref std std-term">current
|
||
context</span></a>.</p></li>
|
||
</ul>
|
||
</dd>
|
||
<dt id="term-context-management-protocol">context management protocol<a class="headerlink" href="#term-context-management-protocol" title="Link to this term">¶</a></dt><dd><p>The <a class="reference internal" href="reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a> and <a class="reference internal" href="reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> methods called
|
||
by the <a class="reference internal" href="reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement. See <span class="target" id="index-9"></span><a class="pep reference external" href="https://peps.python.org/pep-0343/"><strong>PEP 343</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-context-manager">context manager<a class="headerlink" href="#term-context-manager" title="Link to this term">¶</a></dt><dd><p>An object which implements the <a class="reference internal" href="#term-context-management-protocol"><span class="xref std std-term">context management protocol</span></a> and
|
||
controls the environment seen in a <a class="reference internal" href="reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement. See
|
||
<span class="target" id="index-10"></span><a class="pep reference external" href="https://peps.python.org/pep-0343/"><strong>PEP 343</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-context-variable">context variable<a class="headerlink" href="#term-context-variable" title="Link to this term">¶</a></dt><dd><p>A variable whose value depends on which context is the <a class="reference internal" href="#term-current-context"><span class="xref std std-term">current
|
||
context</span></a>. Values are accessed via <a class="reference internal" href="library/contextvars.html#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">contextvars.ContextVar</span></code></a>
|
||
objects. Context variables are primarily used to isolate state between
|
||
concurrent asynchronous tasks.</p>
|
||
</dd>
|
||
<dt id="term-contiguous">contiguous<a class="headerlink" href="#term-contiguous" title="Link to this term">¶</a></dt><dd><p id="index-11">A buffer is considered contiguous exactly if it is either
|
||
<em>C-contiguous</em> or <em>Fortran contiguous</em>. Zero-dimensional buffers are
|
||
C and Fortran contiguous. In one-dimensional arrays, the items
|
||
must be laid out in memory next to each other, in order of
|
||
increasing indexes starting from zero. In multidimensional
|
||
C-contiguous arrays, the last index varies the fastest when
|
||
visiting items in order of memory address. However, in
|
||
Fortran contiguous arrays, the first index varies the fastest.</p>
|
||
</dd>
|
||
<dt id="term-coroutine">coroutine<a class="headerlink" href="#term-coroutine" title="Link to this term">¶</a></dt><dd><p>Coroutines are a more generalized form of subroutines. Subroutines are
|
||
entered at one point and exited at another point. Coroutines can be
|
||
entered, exited, and resumed at many different points. They can be
|
||
implemented with the <a class="reference internal" href="reference/compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> statement. See also
|
||
<span class="target" id="index-12"></span><a class="pep reference external" href="https://peps.python.org/pep-0492/"><strong>PEP 492</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-coroutine-function">coroutine function<a class="headerlink" href="#term-coroutine-function" title="Link to this term">¶</a></dt><dd><p>A function which returns a <a class="reference internal" href="#term-coroutine"><span class="xref std std-term">coroutine</span></a> object. A coroutine
|
||
function may be defined with the <a class="reference internal" href="reference/compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> statement,
|
||
and may contain <a class="reference internal" href="reference/expressions.html#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a>, <a class="reference internal" href="reference/compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a>, and
|
||
<a class="reference internal" href="reference/compound_stmts.html#async-with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code></a> keywords. These were introduced
|
||
by <span class="target" id="index-13"></span><a class="pep reference external" href="https://peps.python.org/pep-0492/"><strong>PEP 492</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-CPython">CPython<a class="headerlink" href="#term-CPython" title="Link to this term">¶</a></dt><dd><p>The canonical implementation of the Python programming language, as
|
||
distributed on <a class="reference external" href="https://www.python.org">python.org</a>. The term “CPython”
|
||
is used when necessary to distinguish this implementation from others
|
||
such as Jython or IronPython.</p>
|
||
</dd>
|
||
<dt id="term-current-context">current context<a class="headerlink" href="#term-current-context" title="Link to this term">¶</a></dt><dd><p>The <a class="reference internal" href="#term-context"><span class="xref std std-term">context</span></a> (<a class="reference internal" href="library/contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">contextvars.Context</span></code></a> object) that is
|
||
currently used by <a class="reference internal" href="library/contextvars.html#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextVar</span></code></a> objects to access (get
|
||
or set) the values of <a class="reference internal" href="#term-context-variable"><span class="xref std std-term">context variables</span></a>. Each
|
||
thread has its own current context. Frameworks for executing asynchronous
|
||
tasks (see <a class="reference internal" href="library/asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a>) associate each task with a context which
|
||
becomes the current context whenever the task starts or resumes execution.</p>
|
||
</dd>
|
||
<dt id="term-decorator">decorator<a class="headerlink" href="#term-decorator" title="Link to this term">¶</a></dt><dd><p>A function returning another function, usually applied as a function
|
||
transformation using the <code class="docutils literal notranslate"><span class="pre">@wrapper</span></code> syntax. Common examples for
|
||
decorators are <a class="reference internal" href="library/functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">classmethod()</span></code></a> and <a class="reference internal" href="library/functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticmethod()</span></code></a>.</p>
|
||
<p>The decorator syntax is merely syntactic sugar, the following two
|
||
function definitions are semantically equivalent:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
|
||
<span class="o">...</span>
|
||
<span class="n">f</span> <span class="o">=</span> <span class="nb">staticmethod</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
|
||
|
||
<span class="nd">@staticmethod</span>
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
|
||
<span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The same concept exists for classes, but is less commonly used there. See
|
||
the documentation for <a class="reference internal" href="reference/compound_stmts.html#function"><span class="std std-ref">function definitions</span></a> and
|
||
<a class="reference internal" href="reference/compound_stmts.html#class"><span class="std std-ref">class definitions</span></a> for more about decorators.</p>
|
||
</dd>
|
||
<dt id="term-descriptor">descriptor<a class="headerlink" href="#term-descriptor" title="Link to this term">¶</a></dt><dd><p>Any object which defines the methods <a class="reference internal" href="reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code></a>,
|
||
<a class="reference internal" href="reference/datamodel.html#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code></a>, or <a class="reference internal" href="reference/datamodel.html#object.__delete__" title="object.__delete__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delete__()</span></code></a>.
|
||
When a class attribute is a descriptor, its special
|
||
binding behavior is triggered upon attribute lookup. Normally, using
|
||
<em>a.b</em> to get, set or delete an attribute looks up the object named <em>b</em> in
|
||
the class dictionary for <em>a</em>, but if <em>b</em> is a descriptor, the respective
|
||
descriptor method gets called. Understanding descriptors is a key to a
|
||
deep understanding of Python because they are the basis for many features
|
||
including functions, methods, properties, class methods, static methods,
|
||
and reference to super classes.</p>
|
||
<p>For more information about descriptors’ methods, see <a class="reference internal" href="reference/datamodel.html#descriptors"><span class="std std-ref">Implementing Descriptors</span></a>
|
||
or the <a class="reference internal" href="howto/descriptor.html#descriptorhowto"><span class="std std-ref">Descriptor How To Guide</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-dictionary">dictionary<a class="headerlink" href="#term-dictionary" title="Link to this term">¶</a></dt><dd><p>An associative array, where arbitrary keys are mapped to values. The
|
||
keys can be any object with <a class="reference internal" href="reference/datamodel.html#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> and
|
||
<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> methods.
|
||
Called a hash in Perl.</p>
|
||
</dd>
|
||
<dt id="term-dictionary-comprehension">dictionary comprehension<a class="headerlink" href="#term-dictionary-comprehension" title="Link to this term">¶</a></dt><dd><p>A compact way to process all or part of the elements in an iterable and
|
||
return a dictionary with the results. <code class="docutils literal notranslate"><span class="pre">results</span> <span class="pre">=</span> <span class="pre">{n:</span> <span class="pre">n</span> <span class="pre">**</span> <span class="pre">2</span> <span class="pre">for</span> <span class="pre">n</span> <span class="pre">in</span>
|
||
<span class="pre">range(10)}</span></code> generates a dictionary containing key <code class="docutils literal notranslate"><span class="pre">n</span></code> mapped to
|
||
value <code class="docutils literal notranslate"><span class="pre">n</span> <span class="pre">**</span> <span class="pre">2</span></code>. See <a class="reference internal" href="reference/expressions.html#comprehensions"><span class="std std-ref">Displays for lists, sets and dictionaries</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-dictionary-view">dictionary view<a class="headerlink" href="#term-dictionary-view" title="Link to this term">¶</a></dt><dd><p>The objects returned from <a class="reference internal" href="library/stdtypes.html#dict.keys" title="dict.keys"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.keys()</span></code></a>, <a class="reference internal" href="library/stdtypes.html#dict.values" title="dict.values"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.values()</span></code></a>, and
|
||
<a class="reference internal" href="library/stdtypes.html#dict.items" title="dict.items"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.items()</span></code></a> are called dictionary views. They provide a dynamic
|
||
view on the dictionary’s entries, which means that when the dictionary
|
||
changes, the view reflects these changes. To force the
|
||
dictionary view to become a full list use <code class="docutils literal notranslate"><span class="pre">list(dictview)</span></code>. See
|
||
<a class="reference internal" href="library/stdtypes.html#dict-views"><span class="std std-ref">Dictionary view objects</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-docstring">docstring<a class="headerlink" href="#term-docstring" title="Link to this term">¶</a></dt><dd><p>A string literal which appears as the first expression in a class,
|
||
function or module. While ignored when the suite is executed, it is
|
||
recognized by the compiler and put into the <a class="reference internal" href="library/stdtypes.html#definition.__doc__" title="definition.__doc__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code></a> attribute
|
||
of the enclosing class, function or module. Since it is available via
|
||
introspection, it is the canonical place for documentation of the
|
||
object.</p>
|
||
</dd>
|
||
<dt id="term-duck-typing">duck-typing<a class="headerlink" href="#term-duck-typing" title="Link to this term">¶</a></dt><dd><p>A programming style which does not look at an object’s type to determine
|
||
if it has the right interface; instead, the method or attribute is simply
|
||
called or used (“If it looks like a duck and quacks like a duck, it
|
||
must be a duck.”) By emphasizing interfaces rather than specific types,
|
||
well-designed code improves its flexibility by allowing polymorphic
|
||
substitution. Duck-typing avoids tests using <a class="reference internal" href="library/functions.html#type" title="type"><code class="xref py py-func docutils literal notranslate"><span class="pre">type()</span></code></a> or
|
||
<a class="reference internal" href="library/functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a>. (Note, however, that duck-typing can be complemented
|
||
with <a class="reference internal" href="#term-abstract-base-class"><span class="xref std std-term">abstract base classes</span></a>.) Instead, it
|
||
typically employs <a class="reference internal" href="library/functions.html#hasattr" title="hasattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">hasattr()</span></code></a> tests or <a class="reference internal" href="#term-EAFP"><span class="xref std std-term">EAFP</span></a> programming.</p>
|
||
</dd>
|
||
<dt id="term-EAFP">EAFP<a class="headerlink" href="#term-EAFP" title="Link to this term">¶</a></dt><dd><p>Easier to ask for forgiveness than permission. This common Python coding
|
||
style assumes the existence of valid keys or attributes and catches
|
||
exceptions if the assumption proves false. This clean and fast style is
|
||
characterized by the presence of many <a class="reference internal" href="reference/compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> and <a class="reference internal" href="reference/compound_stmts.html#except"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">except</span></code></a>
|
||
statements. The technique contrasts with the <a class="reference internal" href="#term-LBYL"><span class="xref std std-term">LBYL</span></a> style
|
||
common to many other languages such as C.</p>
|
||
</dd>
|
||
<dt id="term-expression">expression<a class="headerlink" href="#term-expression" title="Link to this term">¶</a></dt><dd><p>A piece of syntax which can be evaluated to some value. In other words,
|
||
an expression is an accumulation of expression elements like literals,
|
||
names, attribute access, operators or function calls which all return a
|
||
value. In contrast to many other languages, not all language constructs
|
||
are expressions. There are also <a class="reference internal" href="#term-statement"><span class="xref std std-term">statement</span></a>s which cannot be used
|
||
as expressions, such as <a class="reference internal" href="reference/compound_stmts.html#while"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">while</span></code></a>. Assignments are also statements,
|
||
not expressions.</p>
|
||
</dd>
|
||
<dt id="term-extension-module">extension module<a class="headerlink" href="#term-extension-module" title="Link to this term">¶</a></dt><dd><p>A module written in C or C++, using Python’s C API to interact with the
|
||
core and with user code.</p>
|
||
</dd>
|
||
<dt id="term-f-string">f-string<a class="headerlink" href="#term-f-string" title="Link to this term">¶</a></dt><dd><p>String literals prefixed with <code class="docutils literal notranslate"><span class="pre">'f'</span></code> or <code class="docutils literal notranslate"><span class="pre">'F'</span></code> are commonly called
|
||
“f-strings” which is short for
|
||
<a class="reference internal" href="reference/lexical_analysis.html#f-strings"><span class="std std-ref">formatted string literals</span></a>. See also <span class="target" id="index-14"></span><a class="pep reference external" href="https://peps.python.org/pep-0498/"><strong>PEP 498</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-file-object">file object<a class="headerlink" href="#term-file-object" title="Link to this term">¶</a></dt><dd><p>An object exposing a file-oriented API (with methods such as
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code>) to an underlying resource. Depending
|
||
on the way it was created, a file object can mediate access to a real
|
||
on-disk file or to another type of storage or communication device
|
||
(for example standard input/output, in-memory buffers, sockets, pipes,
|
||
etc.). File objects are also called <em class="dfn">file-like objects</em> or
|
||
<em class="dfn">streams</em>.</p>
|
||
<p>There are actually three categories of file objects: raw
|
||
<a class="reference internal" href="#term-binary-file"><span class="xref std std-term">binary files</span></a>, buffered
|
||
<a class="reference internal" href="#term-binary-file"><span class="xref std std-term">binary files</span></a> and <a class="reference internal" href="#term-text-file"><span class="xref std std-term">text files</span></a>.
|
||
Their interfaces are defined in the <a class="reference internal" href="library/io.html#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code></a> module. The canonical
|
||
way to create a file object is by using the <a class="reference internal" href="library/functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function.</p>
|
||
</dd>
|
||
<dt id="term-file-like-object">file-like object<a class="headerlink" href="#term-file-like-object" title="Link to this term">¶</a></dt><dd><p>A synonym for <a class="reference internal" href="#term-file-object"><span class="xref std std-term">file object</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-filesystem-encoding-and-error-handler">filesystem encoding and error handler<a class="headerlink" href="#term-filesystem-encoding-and-error-handler" title="Link to this term">¶</a></dt><dd><p>Encoding and error handler used by Python to decode bytes from the
|
||
operating system and encode Unicode to the operating system.</p>
|
||
<p>The filesystem encoding must guarantee to successfully decode all bytes
|
||
below 128. If the file system encoding fails to provide this guarantee,
|
||
API functions can raise <a class="reference internal" href="library/exceptions.html#UnicodeError" title="UnicodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeError</span></code></a>.</p>
|
||
<p>The <a class="reference internal" href="library/sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a> and
|
||
<a class="reference internal" href="library/sys.html#sys.getfilesystemencodeerrors" title="sys.getfilesystemencodeerrors"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencodeerrors()</span></code></a> functions can be used to get the
|
||
filesystem encoding and error handler.</p>
|
||
<p>The <a class="reference internal" href="#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a> are configured at
|
||
Python startup by the <a class="reference internal" href="c-api/init_config.html#c.PyConfig_Read" title="PyConfig_Read"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyConfig_Read()</span></code></a> function: see
|
||
<a class="reference internal" href="c-api/init_config.html#c.PyConfig.filesystem_encoding" title="PyConfig.filesystem_encoding"><code class="xref c c-member docutils literal notranslate"><span class="pre">filesystem_encoding</span></code></a> and
|
||
<a class="reference internal" href="c-api/init_config.html#c.PyConfig.filesystem_errors" title="PyConfig.filesystem_errors"><code class="xref c c-member docutils literal notranslate"><span class="pre">filesystem_errors</span></code></a> members of <a class="reference internal" href="c-api/init_config.html#c.PyConfig" title="PyConfig"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyConfig</span></code></a>.</p>
|
||
<p>See also the <a class="reference internal" href="#term-locale-encoding"><span class="xref std std-term">locale encoding</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-finder">finder<a class="headerlink" href="#term-finder" title="Link to this term">¶</a></dt><dd><p>An object that tries to find the <a class="reference internal" href="#term-loader"><span class="xref std std-term">loader</span></a> for a module that is
|
||
being imported.</p>
|
||
<p>There are two types of finder: <a class="reference internal" href="#term-meta-path-finder"><span class="xref std std-term">meta path finders</span></a> for use with <a class="reference internal" href="library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a>, and <a class="reference internal" href="#term-path-entry-finder"><span class="xref std std-term">path
|
||
entry finders</span></a> for use with <a class="reference internal" href="library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a>.</p>
|
||
<p>See <a class="reference internal" href="reference/import.html#finders-and-loaders"><span class="std std-ref">Finders and loaders</span></a> and <a class="reference internal" href="library/importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code></a> for much more detail.</p>
|
||
</dd>
|
||
<dt id="term-floor-division">floor division<a class="headerlink" href="#term-floor-division" title="Link to this term">¶</a></dt><dd><p>Mathematical division that rounds down to nearest integer. The floor
|
||
division operator is <code class="docutils literal notranslate"><span class="pre">//</span></code>. For example, the expression <code class="docutils literal notranslate"><span class="pre">11</span> <span class="pre">//</span> <span class="pre">4</span></code>
|
||
evaluates to <code class="docutils literal notranslate"><span class="pre">2</span></code> in contrast to the <code class="docutils literal notranslate"><span class="pre">2.75</span></code> returned by float true
|
||
division. Note that <code class="docutils literal notranslate"><span class="pre">(-11)</span> <span class="pre">//</span> <span class="pre">4</span></code> is <code class="docutils literal notranslate"><span class="pre">-3</span></code> because that is <code class="docutils literal notranslate"><span class="pre">-2.75</span></code>
|
||
rounded <em>downward</em>. See <span class="target" id="index-15"></span><a class="pep reference external" href="https://peps.python.org/pep-0238/"><strong>PEP 238</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-free-threading">free threading<a class="headerlink" href="#term-free-threading" title="Link to this term">¶</a></dt><dd><p>A threading model where multiple threads can run Python bytecode
|
||
simultaneously within the same interpreter. This is in contrast to
|
||
the <a class="reference internal" href="#term-global-interpreter-lock"><span class="xref std std-term">global interpreter lock</span></a> which allows only one thread to
|
||
execute Python bytecode at a time. See <span class="target" id="index-16"></span><a class="pep reference external" href="https://peps.python.org/pep-0703/"><strong>PEP 703</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-free-variable">free variable<a class="headerlink" href="#term-free-variable" title="Link to this term">¶</a></dt><dd><p>Formally, as defined in the <a class="reference internal" href="reference/executionmodel.html#bind-names"><span class="std std-ref">language execution model</span></a>, a free
|
||
variable is any variable used in a namespace which is not a local variable in that
|
||
namespace. See <a class="reference internal" href="#term-closure-variable"><span class="xref std std-term">closure variable</span></a> for an example.
|
||
Pragmatically, due to the name of the <a class="reference internal" href="reference/datamodel.html#codeobject.co_freevars" title="codeobject.co_freevars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">codeobject.co_freevars</span></code></a> attribute,
|
||
the term is also sometimes used as a synonym for <a class="reference internal" href="#term-closure-variable"><span class="xref std std-term">closure variable</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-function">function<a class="headerlink" href="#term-function" title="Link to this term">¶</a></dt><dd><p>A series of statements which returns some value to a caller. It can also
|
||
be passed zero or more <a class="reference internal" href="#term-argument"><span class="xref std std-term">arguments</span></a> which may be used in
|
||
the execution of the body. See also <a class="reference internal" href="#term-parameter"><span class="xref std std-term">parameter</span></a>, <a class="reference internal" href="#term-method"><span class="xref std std-term">method</span></a>,
|
||
and the <a class="reference internal" href="reference/compound_stmts.html#function"><span class="std std-ref">Function definitions</span></a> section.</p>
|
||
</dd>
|
||
<dt id="term-function-annotation">function annotation<a class="headerlink" href="#term-function-annotation" title="Link to this term">¶</a></dt><dd><p>An <a class="reference internal" href="#term-annotation"><span class="xref std std-term">annotation</span></a> of a function parameter or return value.</p>
|
||
<p>Function annotations are usually used for
|
||
<a class="reference internal" href="#term-type-hint"><span class="xref std std-term">type hints</span></a>: for example, this function is expected to take two
|
||
<a class="reference internal" href="library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> arguments and is also expected to have an <a class="reference internal" href="library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>
|
||
return value:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">sum_two_numbers</span><span class="p">(</span><span class="n">a</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">a</span> <span class="o">+</span> <span class="n">b</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Function annotation syntax is explained in section <a class="reference internal" href="reference/compound_stmts.html#function"><span class="std std-ref">Function definitions</span></a>.</p>
|
||
<p>See <a class="reference internal" href="#term-variable-annotation"><span class="xref std std-term">variable annotation</span></a> and <span class="target" id="index-17"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a>,
|
||
which describe this functionality.
|
||
Also see <a class="reference internal" href="howto/annotations.html#annotations-howto"><span class="std std-ref">Annotations Best Practices</span></a>
|
||
for best practices on working with annotations.</p>
|
||
</dd>
|
||
<dt id="term-__future__">__future__<a class="headerlink" href="#term-__future__" title="Link to this term">¶</a></dt><dd><p>A <a class="reference internal" href="reference/simple_stmts.html#future"><span class="std std-ref">future statement</span></a>, <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span> <span class="pre"><feature></span></code>,
|
||
directs the compiler to compile the current module using syntax or
|
||
semantics that will become standard in a future release of Python.
|
||
The <a class="reference internal" href="library/__future__.html#module-__future__" title="__future__: Future statement definitions"><code class="xref py py-mod docutils literal notranslate"><span class="pre">__future__</span></code></a> module documents the possible values of
|
||
<em>feature</em>. By importing this module and evaluating its variables,
|
||
you can see when a new feature was first added to the language and
|
||
when it will (or did) become the default:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">__future__</span>
|
||
<span class="gp">>>> </span><span class="n">__future__</span><span class="o">.</span><span class="n">division</span>
|
||
<span class="go">_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt id="term-garbage-collection">garbage collection<a class="headerlink" href="#term-garbage-collection" title="Link to this term">¶</a></dt><dd><p>The process of freeing memory when it is not used anymore. Python
|
||
performs garbage collection via reference counting and a cyclic garbage
|
||
collector that is able to detect and break reference cycles. The
|
||
garbage collector can be controlled using the <a class="reference internal" href="library/gc.html#module-gc" title="gc: Interface to the cycle-detecting garbage collector."><code class="xref py py-mod docutils literal notranslate"><span class="pre">gc</span></code></a> module.</p>
|
||
</dd>
|
||
<dt id="term-generator">generator<a class="headerlink" href="#term-generator" title="Link to this term">¶</a></dt><dd><p>A function which returns a <a class="reference internal" href="#term-generator-iterator"><span class="xref std std-term">generator iterator</span></a>. It looks like a
|
||
normal function except that it contains <a class="reference internal" href="reference/simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> expressions
|
||
for producing a series of values usable in a for-loop or that can be
|
||
retrieved one at a time with the <a class="reference internal" href="library/functions.html#next" title="next"><code class="xref py py-func docutils literal notranslate"><span class="pre">next()</span></code></a> function.</p>
|
||
<p>Usually refers to a generator function, but may refer to a
|
||
<em>generator iterator</em> in some contexts. In cases where the intended
|
||
meaning isn’t clear, using the full terms avoids ambiguity.</p>
|
||
</dd>
|
||
<dt id="term-generator-iterator">generator iterator<a class="headerlink" href="#term-generator-iterator" title="Link to this term">¶</a></dt><dd><p>An object created by a <a class="reference internal" href="#term-generator"><span class="xref std std-term">generator</span></a> function.</p>
|
||
<p>Each <a class="reference internal" href="reference/simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> temporarily suspends processing, remembering the
|
||
execution state (including local variables and pending
|
||
try-statements). When the <em>generator iterator</em> resumes, it picks up where
|
||
it left off (in contrast to functions which start fresh on every
|
||
invocation).</p>
|
||
</dd>
|
||
<dt id="term-generator-expression">generator expression<a class="headerlink" href="#term-generator-expression" title="Link to this term">¶</a></dt><dd><p>An <a class="reference internal" href="#term-expression"><span class="xref std std-term">expression</span></a> that returns an <a class="reference internal" href="#term-iterator"><span class="xref std std-term">iterator</span></a>. It looks like a normal expression
|
||
followed by a <code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code> clause defining a loop variable, range,
|
||
and an optional <code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code> clause. The combined expression
|
||
generates values for an enclosing function:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">sum</span><span class="p">(</span><span class="n">i</span><span class="o">*</span><span class="n">i</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span> <span class="c1"># sum of squares 0, 1, 4, ... 81</span>
|
||
<span class="go">285</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt id="term-generic-function">generic function<a class="headerlink" href="#term-generic-function" title="Link to this term">¶</a></dt><dd><p>A function composed of multiple functions implementing the same operation
|
||
for different types. Which implementation should be used during a call is
|
||
determined by the dispatch algorithm.</p>
|
||
<p>See also the <a class="reference internal" href="#term-single-dispatch"><span class="xref std std-term">single dispatch</span></a> glossary entry, the
|
||
<a class="reference internal" href="library/functools.html#functools.singledispatch" title="functools.singledispatch"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.singledispatch()</span></code></a> decorator, and <span class="target" id="index-20"></span><a class="pep reference external" href="https://peps.python.org/pep-0443/"><strong>PEP 443</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-generic-type">generic type<a class="headerlink" href="#term-generic-type" title="Link to this term">¶</a></dt><dd><p>A <a class="reference internal" href="#term-type"><span class="xref std std-term">type</span></a> that can be parameterized; typically a
|
||
<a class="reference internal" href="reference/datamodel.html#sequence-types"><span class="std std-ref">container class</span></a> such as <a class="reference internal" href="library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> or
|
||
<a class="reference internal" href="library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>. Used for <a class="reference internal" href="#term-type-hint"><span class="xref std std-term">type hints</span></a> and
|
||
<a class="reference internal" href="#term-annotation"><span class="xref std std-term">annotations</span></a>.</p>
|
||
<p>For more details, see <a class="reference internal" href="library/stdtypes.html#types-genericalias"><span class="std std-ref">generic alias types</span></a>,
|
||
<span class="target" id="index-21"></span><a class="pep reference external" href="https://peps.python.org/pep-0483/"><strong>PEP 483</strong></a>, <span class="target" id="index-22"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a>, <span class="target" id="index-23"></span><a class="pep reference external" href="https://peps.python.org/pep-0585/"><strong>PEP 585</strong></a>, and the <a class="reference internal" href="library/typing.html#module-typing" title="typing: Support for type hints (see :pep:`484`)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> module.</p>
|
||
</dd>
|
||
<dt id="term-GIL">GIL<a class="headerlink" href="#term-GIL" title="Link to this term">¶</a></dt><dd><p>See <a class="reference internal" href="#term-global-interpreter-lock"><span class="xref std std-term">global interpreter lock</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-global-interpreter-lock">global interpreter lock<a class="headerlink" href="#term-global-interpreter-lock" title="Link to this term">¶</a></dt><dd><p>The mechanism used by the <a class="reference internal" href="#term-CPython"><span class="xref std std-term">CPython</span></a> interpreter to assure that
|
||
only one thread executes Python <a class="reference internal" href="#term-bytecode"><span class="xref std std-term">bytecode</span></a> at a time.
|
||
This simplifies the CPython implementation by making the object model
|
||
(including critical built-in types such as <a class="reference internal" href="library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>) implicitly
|
||
safe against concurrent access. Locking the entire interpreter
|
||
makes it easier for the interpreter to be multi-threaded, at the
|
||
expense of much of the parallelism afforded by multi-processor
|
||
machines.</p>
|
||
<p>However, some extension modules, either standard or third-party,
|
||
are designed so as to release the GIL when doing computationally intensive
|
||
tasks such as compression or hashing. Also, the GIL is always released
|
||
when doing I/O.</p>
|
||
<p>As of Python 3.13, the GIL can be disabled using the <a class="reference internal" href="using/configure.html#cmdoption-disable-gil"><code class="xref std std-option docutils literal notranslate"><span class="pre">--disable-gil</span></code></a>
|
||
build configuration. After building Python with this option, code must be
|
||
run with <a class="reference internal" href="using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span> <span class="pre">gil=0</span></code></a> or after setting the <span class="target" id="index-24"></span><a class="reference internal" href="using/cmdline.html#envvar-PYTHON_GIL"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHON_GIL=0</span></code></a>
|
||
environment variable. This feature enables improved performance for
|
||
multi-threaded applications and makes it easier to use multi-core CPUs
|
||
efficiently. For more details, see <span class="target" id="index-25"></span><a class="pep reference external" href="https://peps.python.org/pep-0703/"><strong>PEP 703</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-hash-based-pyc">hash-based pyc<a class="headerlink" href="#term-hash-based-pyc" title="Link to this term">¶</a></dt><dd><p>A bytecode cache file that uses the hash rather than the last-modified
|
||
time of the corresponding source file to determine its validity. See
|
||
<a class="reference internal" href="reference/import.html#pyc-invalidation"><span class="std std-ref">Cached bytecode invalidation</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-hashable">hashable<a class="headerlink" href="#term-hashable" title="Link to this term">¶</a></dt><dd><p>An object is <em>hashable</em> if it has a hash value which never changes during
|
||
its lifetime (it needs a <a class="reference internal" href="reference/datamodel.html#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> method), and can be
|
||
compared to other objects (it needs an <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> method).
|
||
Hashable objects which
|
||
compare equal must have the same hash value.</p>
|
||
<p>Hashability makes an object usable as a dictionary key and a set member,
|
||
because these data structures use the hash value internally.</p>
|
||
<p>Most of Python’s immutable built-in objects are hashable; mutable
|
||
containers (such as lists or dictionaries) are not; immutable
|
||
containers (such as tuples and frozensets) are only hashable if
|
||
their elements are hashable. Objects which are
|
||
instances of user-defined classes are hashable by default. They all
|
||
compare unequal (except with themselves), and their hash value is derived
|
||
from their <a class="reference internal" href="library/functions.html#id" title="id"><code class="xref py py-func docutils literal notranslate"><span class="pre">id()</span></code></a>.</p>
|
||
</dd>
|
||
<dt id="term-IDLE">IDLE<a class="headerlink" href="#term-IDLE" title="Link to this term">¶</a></dt><dd><p>An Integrated Development and Learning Environment for Python.
|
||
<a class="reference internal" href="library/idle.html#idle"><span class="std std-ref">IDLE — Python editor and shell</span></a> is a basic editor and interpreter environment
|
||
which ships with the standard distribution of Python.</p>
|
||
</dd>
|
||
<dt id="term-immortal">immortal<a class="headerlink" href="#term-immortal" title="Link to this term">¶</a></dt><dd><p><em>Immortal objects</em> are a CPython implementation detail introduced
|
||
in <span class="target" id="index-26"></span><a class="pep reference external" href="https://peps.python.org/pep-0683/"><strong>PEP 683</strong></a>.</p>
|
||
<p>If an object is immortal, its <a class="reference internal" href="#term-reference-count"><span class="xref std std-term">reference count</span></a> is never modified,
|
||
and therefore it is never deallocated while the interpreter is running.
|
||
For example, <a class="reference internal" href="library/constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> and <a class="reference internal" href="library/constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> are immortal in CPython.</p>
|
||
</dd>
|
||
<dt id="term-immutable">immutable<a class="headerlink" href="#term-immutable" title="Link to this term">¶</a></dt><dd><p>An object with a fixed value. Immutable objects include numbers, strings and
|
||
tuples. Such an object cannot be altered. A new object has to
|
||
be created if a different value has to be stored. They play an important
|
||
role in places where a constant hash value is needed, for example as a key
|
||
in a dictionary.</p>
|
||
</dd>
|
||
<dt id="term-import-path">import path<a class="headerlink" href="#term-import-path" title="Link to this term">¶</a></dt><dd><p>A list of locations (or <a class="reference internal" href="#term-path-entry"><span class="xref std std-term">path entries</span></a>) that are
|
||
searched by the <a class="reference internal" href="#term-path-based-finder"><span class="xref std std-term">path based finder</span></a> for modules to import. During
|
||
import, this list of locations usually comes from <a class="reference internal" href="library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>, but
|
||
for subpackages it may also come from the parent package’s <code class="docutils literal notranslate"><span class="pre">__path__</span></code>
|
||
attribute.</p>
|
||
</dd>
|
||
<dt id="term-importing">importing<a class="headerlink" href="#term-importing" title="Link to this term">¶</a></dt><dd><p>The process by which Python code in one module is made available to
|
||
Python code in another module.</p>
|
||
</dd>
|
||
<dt id="term-importer">importer<a class="headerlink" href="#term-importer" title="Link to this term">¶</a></dt><dd><p>An object that both finds and loads a module; both a
|
||
<a class="reference internal" href="#term-finder"><span class="xref std std-term">finder</span></a> and <a class="reference internal" href="#term-loader"><span class="xref std std-term">loader</span></a> object.</p>
|
||
</dd>
|
||
<dt id="term-interactive">interactive<a class="headerlink" href="#term-interactive" title="Link to this term">¶</a></dt><dd><p>Python has an interactive interpreter which means you can enter
|
||
statements and expressions at the interpreter prompt, immediately
|
||
execute them and see their results. Just launch <code class="docutils literal notranslate"><span class="pre">python</span></code> with no
|
||
arguments (possibly by selecting it from your computer’s main
|
||
menu). It is a very powerful way to test out new ideas or inspect
|
||
modules and packages (remember <code class="docutils literal notranslate"><span class="pre">help(x)</span></code>). For more on interactive
|
||
mode, see <a class="reference internal" href="tutorial/appendix.html#tut-interac"><span class="std std-ref">Interactive Mode</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-interpreted">interpreted<a class="headerlink" href="#term-interpreted" title="Link to this term">¶</a></dt><dd><p>Python is an interpreted language, as opposed to a compiled one,
|
||
though the distinction can be blurry because of the presence of the
|
||
bytecode compiler. This means that source files can be run directly
|
||
without explicitly creating an executable which is then run.
|
||
Interpreted languages typically have a shorter development/debug cycle
|
||
than compiled ones, though their programs generally also run more
|
||
slowly. See also <a class="reference internal" href="#term-interactive"><span class="xref std std-term">interactive</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-interpreter-shutdown">interpreter shutdown<a class="headerlink" href="#term-interpreter-shutdown" title="Link to this term">¶</a></dt><dd><p>When asked to shut down, the Python interpreter enters a special phase
|
||
where it gradually releases all allocated resources, such as modules
|
||
and various critical internal structures. It also makes several calls
|
||
to the <a class="reference internal" href="#term-garbage-collection"><span class="xref std std-term">garbage collector</span></a>. This can trigger
|
||
the execution of code in user-defined destructors or weakref callbacks.
|
||
Code executed during the shutdown phase can encounter various
|
||
exceptions as the resources it relies on may not function anymore
|
||
(common examples are library modules or the warnings machinery).</p>
|
||
<p>The main reason for interpreter shutdown is that the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module
|
||
or the script being run has finished executing.</p>
|
||
</dd>
|
||
<dt id="term-iterable">iterable<a class="headerlink" href="#term-iterable" title="Link to this term">¶</a></dt><dd><p>An object capable of returning its members one at a time. Examples of
|
||
iterables include all sequence types (such as <a class="reference internal" href="library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, <a class="reference internal" href="library/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="library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>) and some non-sequence types like <a class="reference internal" href="library/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="#term-file-object"><span class="xref std std-term">file objects</span></a>, and objects of any classes you define
|
||
with an <a class="reference internal" href="reference/datamodel.html#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> method or with a
|
||
<a class="reference internal" href="reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> method
|
||
that implements <a class="reference internal" href="#term-sequence"><span class="xref std std-term">sequence</span></a> semantics.</p>
|
||
<p>Iterables can be
|
||
used in a <a class="reference internal" href="reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> loop and in many other places where a sequence is
|
||
needed (<a class="reference internal" href="library/functions.html#zip" title="zip"><code class="xref py py-func docutils literal notranslate"><span class="pre">zip()</span></code></a>, <a class="reference internal" href="library/functions.html#map" title="map"><code class="xref py py-func docutils literal notranslate"><span class="pre">map()</span></code></a>, …). When an iterable object is passed
|
||
as an argument to the built-in function <a class="reference internal" href="library/functions.html#iter" title="iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">iter()</span></code></a>, it returns an
|
||
iterator for the object. This iterator is good for one pass over the set
|
||
of values. When using iterables, it is usually not necessary to call
|
||
<a class="reference internal" href="library/functions.html#iter" title="iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">iter()</span></code></a> or deal with iterator objects yourself. The <a class="reference internal" href="reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a>
|
||
statement does that automatically for you, creating a temporary unnamed
|
||
variable to hold the iterator for the duration of the loop. See also
|
||
<a class="reference internal" href="#term-iterator"><span class="xref std std-term">iterator</span></a>, <a class="reference internal" href="#term-sequence"><span class="xref std std-term">sequence</span></a>, and <a class="reference internal" href="#term-generator"><span class="xref std std-term">generator</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-iterator">iterator<a class="headerlink" href="#term-iterator" title="Link to this term">¶</a></dt><dd><p>An object representing a stream of data. Repeated calls to the iterator’s
|
||
<a class="reference internal" href="library/stdtypes.html#iterator.__next__" title="iterator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a> method (or passing it to the built-in function
|
||
<a class="reference internal" href="library/functions.html#next" title="next"><code class="xref py py-func docutils literal notranslate"><span class="pre">next()</span></code></a>) return successive items in the stream. When no more data
|
||
are available a <a class="reference internal" href="library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> exception is raised instead. At this
|
||
point, the iterator object is exhausted and any further calls to its
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code> method just raise <a class="reference internal" href="library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> again. Iterators
|
||
are required to have an <a class="reference internal" href="library/stdtypes.html#iterator.__iter__" title="iterator.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> method that returns the iterator
|
||
object itself so every iterator is also iterable and may be used in most
|
||
places where other iterables are accepted. One notable exception is code
|
||
which attempts multiple iteration passes. A container object (such as a
|
||
<a class="reference internal" href="library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>) produces a fresh new iterator each time you pass it to the
|
||
<a class="reference internal" href="library/functions.html#iter" title="iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">iter()</span></code></a> function or use it in a <a class="reference internal" href="reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> loop. Attempting this
|
||
with an iterator will just return the same exhausted iterator object used
|
||
in the previous iteration pass, making it appear like an empty container.</p>
|
||
<p>More information can be found in <a class="reference internal" href="library/stdtypes.html#typeiter"><span class="std std-ref">Iterator Types</span></a>.</p>
|
||
<div class="impl-detail compound">
|
||
<p><strong>CPython implementation detail:</strong> CPython does not consistently apply the requirement that an iterator
|
||
define <a class="reference internal" href="library/stdtypes.html#iterator.__iter__" title="iterator.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a>.
|
||
And also please note that the free-threading CPython does not guarantee
|
||
the thread-safety of iterator operations.</p>
|
||
</div>
|
||
</dd>
|
||
<dt id="term-key-function">key function<a class="headerlink" href="#term-key-function" title="Link to this term">¶</a></dt><dd><p>A key function or collation function is a callable that returns a value
|
||
used for sorting or ordering. For example, <a class="reference internal" href="library/locale.html#locale.strxfrm" title="locale.strxfrm"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.strxfrm()</span></code></a> is
|
||
used to produce a sort key that is aware of locale specific sort
|
||
conventions.</p>
|
||
<p>A number of tools in Python accept key functions to control how elements
|
||
are ordered or grouped. They include <a class="reference internal" href="library/functions.html#min" title="min"><code class="xref py py-func docutils literal notranslate"><span class="pre">min()</span></code></a>, <a class="reference internal" href="library/functions.html#max" title="max"><code class="xref py py-func docutils literal notranslate"><span class="pre">max()</span></code></a>,
|
||
<a class="reference internal" href="library/functions.html#sorted" title="sorted"><code class="xref py py-func docutils literal notranslate"><span class="pre">sorted()</span></code></a>, <a class="reference internal" href="library/stdtypes.html#list.sort" title="list.sort"><code class="xref py py-meth docutils literal notranslate"><span class="pre">list.sort()</span></code></a>, <a class="reference internal" href="library/heapq.html#heapq.merge" title="heapq.merge"><code class="xref py py-func docutils literal notranslate"><span class="pre">heapq.merge()</span></code></a>,
|
||
<a class="reference internal" href="library/heapq.html#heapq.nsmallest" title="heapq.nsmallest"><code class="xref py py-func docutils literal notranslate"><span class="pre">heapq.nsmallest()</span></code></a>, <a class="reference internal" href="library/heapq.html#heapq.nlargest" title="heapq.nlargest"><code class="xref py py-func docutils literal notranslate"><span class="pre">heapq.nlargest()</span></code></a>, and
|
||
<a class="reference internal" href="library/itertools.html#itertools.groupby" title="itertools.groupby"><code class="xref py py-func docutils literal notranslate"><span class="pre">itertools.groupby()</span></code></a>.</p>
|
||
<p>There are several ways to create a key function. For example. the
|
||
<a class="reference internal" href="library/stdtypes.html#str.lower" title="str.lower"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.lower()</span></code></a> method can serve as a key function for case insensitive
|
||
sorts. Alternatively, a key function can be built from a
|
||
<a class="reference internal" href="reference/expressions.html#lambda"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">lambda</span></code></a> expression such as <code class="docutils literal notranslate"><span class="pre">lambda</span> <span class="pre">r:</span> <span class="pre">(r[0],</span> <span class="pre">r[2])</span></code>. Also,
|
||
<a class="reference internal" href="library/operator.html#operator.attrgetter" title="operator.attrgetter"><code class="xref py py-func docutils literal notranslate"><span class="pre">operator.attrgetter()</span></code></a>, <a class="reference internal" href="library/operator.html#operator.itemgetter" title="operator.itemgetter"><code class="xref py py-func docutils literal notranslate"><span class="pre">operator.itemgetter()</span></code></a>, and
|
||
<a class="reference internal" href="library/operator.html#operator.methodcaller" title="operator.methodcaller"><code class="xref py py-func docutils literal notranslate"><span class="pre">operator.methodcaller()</span></code></a> are three key function constructors. See the <a class="reference internal" href="howto/sorting.html#sortinghowto"><span class="std std-ref">Sorting HOW TO</span></a> for examples of how to create and use key functions.</p>
|
||
</dd>
|
||
<dt id="term-keyword-argument">keyword argument<a class="headerlink" href="#term-keyword-argument" title="Link to this term">¶</a></dt><dd><p>See <a class="reference internal" href="#term-argument"><span class="xref std std-term">argument</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-lambda">lambda<a class="headerlink" href="#term-lambda" title="Link to this term">¶</a></dt><dd><p>An anonymous inline function consisting of a single <a class="reference internal" href="#term-expression"><span class="xref std std-term">expression</span></a>
|
||
which is evaluated when the function is called. The syntax to create
|
||
a lambda function is <code class="docutils literal notranslate"><span class="pre">lambda</span> <span class="pre">[parameters]:</span> <span class="pre">expression</span></code></p>
|
||
</dd>
|
||
<dt id="term-LBYL">LBYL<a class="headerlink" href="#term-LBYL" title="Link to this term">¶</a></dt><dd><p>Look before you leap. This coding style explicitly tests for
|
||
pre-conditions before making calls or lookups. This style contrasts with
|
||
the <a class="reference internal" href="#term-EAFP"><span class="xref std std-term">EAFP</span></a> approach and is characterized by the presence of many
|
||
<a class="reference internal" href="reference/compound_stmts.html#if"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code></a> statements.</p>
|
||
<p>In a multi-threaded environment, the LBYL approach can risk introducing a
|
||
race condition between “the looking” and “the leaping”. For example, the
|
||
code, <code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">key</span> <span class="pre">in</span> <span class="pre">mapping:</span> <span class="pre">return</span> <span class="pre">mapping[key]</span></code> can fail if another
|
||
thread removes <em>key</em> from <em>mapping</em> after the test, but before the lookup.
|
||
This issue can be solved with locks or by using the EAFP approach.</p>
|
||
</dd>
|
||
<dt id="term-lexical-analyzer">lexical analyzer<a class="headerlink" href="#term-lexical-analyzer" title="Link to this term">¶</a></dt><dd><p>Formal name for the <em>tokenizer</em>; see <a class="reference internal" href="#term-token"><span class="xref std std-term">token</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-list">list<a class="headerlink" href="#term-list" title="Link to this term">¶</a></dt><dd><p>A built-in Python <a class="reference internal" href="#term-sequence"><span class="xref std std-term">sequence</span></a>. Despite its name it is more akin
|
||
to an array in other languages than to a linked list since access to
|
||
elements is <em>O</em>(1).</p>
|
||
</dd>
|
||
<dt id="term-list-comprehension">list comprehension<a class="headerlink" href="#term-list-comprehension" title="Link to this term">¶</a></dt><dd><p>A compact way to process all or part of the elements in a sequence and
|
||
return a list with the results. <code class="docutils literal notranslate"><span class="pre">result</span> <span class="pre">=</span> <span class="pre">['{:#04x}'.format(x)</span> <span class="pre">for</span> <span class="pre">x</span> <span class="pre">in</span>
|
||
<span class="pre">range(256)</span> <span class="pre">if</span> <span class="pre">x</span> <span class="pre">%</span> <span class="pre">2</span> <span class="pre">==</span> <span class="pre">0]</span></code> generates a list of strings containing
|
||
even hex numbers (0x..) in the range from 0 to 255. The <a class="reference internal" href="reference/compound_stmts.html#if"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code></a>
|
||
clause is optional. If omitted, all elements in <code class="docutils literal notranslate"><span class="pre">range(256)</span></code> are
|
||
processed.</p>
|
||
</dd>
|
||
<dt id="term-loader">loader<a class="headerlink" href="#term-loader" title="Link to this term">¶</a></dt><dd><p>An object that loads a module.
|
||
It must define the <code class="xref py py-meth docutils literal notranslate"><span class="pre">exec_module()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">create_module()</span></code> methods
|
||
to implement the <a class="reference internal" href="library/importlib.html#importlib.abc.Loader" title="importlib.abc.Loader"><code class="xref py py-class docutils literal notranslate"><span class="pre">Loader</span></code></a> interface.
|
||
A loader is typically returned by a <a class="reference internal" href="#term-finder"><span class="xref std std-term">finder</span></a>.
|
||
See also:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="reference/import.html#finders-and-loaders"><span class="std std-ref">Finders and loaders</span></a></p></li>
|
||
<li><p><a class="reference internal" href="library/importlib.html#importlib.abc.Loader" title="importlib.abc.Loader"><code class="xref py py-class docutils literal notranslate"><span class="pre">importlib.abc.Loader</span></code></a></p></li>
|
||
<li><p><span class="target" id="index-27"></span><a class="pep reference external" href="https://peps.python.org/pep-0302/"><strong>PEP 302</strong></a></p></li>
|
||
</ul>
|
||
</dd>
|
||
<dt id="term-locale-encoding">locale encoding<a class="headerlink" href="#term-locale-encoding" title="Link to this term">¶</a></dt><dd><p>On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
|
||
<a class="reference internal" href="library/locale.html#locale.setlocale" title="locale.setlocale"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.setlocale(locale.LC_CTYPE,</span> <span class="pre">new_locale)</span></code></a>.</p>
|
||
<p>On Windows, it is the ANSI code page (ex: <code class="docutils literal notranslate"><span class="pre">"cp1252"</span></code>).</p>
|
||
<p>On Android and VxWorks, Python uses <code class="docutils literal notranslate"><span class="pre">"utf-8"</span></code> as the locale encoding.</p>
|
||
<p><a class="reference internal" href="library/locale.html#locale.getencoding" title="locale.getencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getencoding()</span></code></a> can be used to get the locale encoding.</p>
|
||
<p>See also the <a class="reference internal" href="#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-magic-method">magic method<a class="headerlink" href="#term-magic-method" title="Link to this term">¶</a></dt><dd><p id="index-28">An informal synonym for <a class="reference internal" href="#term-special-method"><span class="xref std std-term">special method</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-mapping">mapping<a class="headerlink" href="#term-mapping" title="Link to this term">¶</a></dt><dd><p>A container object that supports arbitrary key lookups and implements the
|
||
methods specified in the <a class="reference internal" href="library/collections.abc.html#collections.abc.Mapping" title="collections.abc.Mapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.abc.Mapping</span></code></a> or
|
||
<a class="reference internal" href="library/collections.abc.html#collections.abc.MutableMapping" title="collections.abc.MutableMapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.abc.MutableMapping</span></code></a>
|
||
<a class="reference internal" href="library/collections.abc.html#collections-abstract-base-classes"><span class="std std-ref">abstract base classes</span></a>. Examples
|
||
include <a class="reference internal" href="library/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="library/collections.html#collections.defaultdict" title="collections.defaultdict"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.defaultdict</span></code></a>,
|
||
<a class="reference internal" href="library/collections.html#collections.OrderedDict" title="collections.OrderedDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.OrderedDict</span></code></a> and <a class="reference internal" href="library/collections.html#collections.Counter" title="collections.Counter"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.Counter</span></code></a>.</p>
|
||
</dd>
|
||
<dt id="term-meta-path-finder">meta path finder<a class="headerlink" href="#term-meta-path-finder" title="Link to this term">¶</a></dt><dd><p>A <a class="reference internal" href="#term-finder"><span class="xref std std-term">finder</span></a> returned by a search of <a class="reference internal" href="library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a>. Meta path
|
||
finders are related to, but different from <a class="reference internal" href="#term-path-entry-finder"><span class="xref std std-term">path entry finders</span></a>.</p>
|
||
<p>See <a class="reference internal" href="library/importlib.html#importlib.abc.MetaPathFinder" title="importlib.abc.MetaPathFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">importlib.abc.MetaPathFinder</span></code></a> for the methods that meta path
|
||
finders implement.</p>
|
||
</dd>
|
||
<dt id="term-metaclass">metaclass<a class="headerlink" href="#term-metaclass" title="Link to this term">¶</a></dt><dd><p>The class of a class. Class definitions create a class name, a class
|
||
dictionary, and a list of base classes. The metaclass is responsible for
|
||
taking those three arguments and creating the class. Most object oriented
|
||
programming languages provide a default implementation. What makes Python
|
||
special is that it is possible to create custom metaclasses. Most users
|
||
never need this tool, but when the need arises, metaclasses can provide
|
||
powerful, elegant solutions. They have been used for logging attribute
|
||
access, adding thread-safety, tracking object creation, implementing
|
||
singletons, and many other tasks.</p>
|
||
<p>More information can be found in <a class="reference internal" href="reference/datamodel.html#metaclasses"><span class="std std-ref">Metaclasses</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-method">method<a class="headerlink" href="#term-method" title="Link to this term">¶</a></dt><dd><p>A function which is defined inside a class body. If called as an attribute
|
||
of an instance of that class, the method will get the instance object as
|
||
its first <a class="reference internal" href="#term-argument"><span class="xref std std-term">argument</span></a> (which is usually called <code class="docutils literal notranslate"><span class="pre">self</span></code>).
|
||
See <a class="reference internal" href="#term-function"><span class="xref std std-term">function</span></a> and <a class="reference internal" href="#term-nested-scope"><span class="xref std std-term">nested scope</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-method-resolution-order">method resolution order<a class="headerlink" href="#term-method-resolution-order" title="Link to this term">¶</a></dt><dd><p>Method Resolution Order is the order in which base classes are searched
|
||
for a member during lookup. See <a class="reference internal" href="howto/mro.html#python-2-3-mro"><span class="std std-ref">The Python 2.3 Method Resolution Order</span></a> for details of the
|
||
algorithm used by the Python interpreter since the 2.3 release.</p>
|
||
</dd>
|
||
<dt id="term-module">module<a class="headerlink" href="#term-module" title="Link to this term">¶</a></dt><dd><p>An object that serves as an organizational unit of Python code. Modules
|
||
have a namespace containing arbitrary Python objects. Modules are loaded
|
||
into Python by the process of <a class="reference internal" href="#term-importing"><span class="xref std std-term">importing</span></a>.</p>
|
||
<p>See also <a class="reference internal" href="#term-package"><span class="xref std std-term">package</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-module-spec">module spec<a class="headerlink" href="#term-module-spec" title="Link to this term">¶</a></dt><dd><p>A namespace containing the import-related information used to load a
|
||
module. An instance of <a class="reference internal" href="library/importlib.html#importlib.machinery.ModuleSpec" title="importlib.machinery.ModuleSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">importlib.machinery.ModuleSpec</span></code></a>.</p>
|
||
<p>See also <a class="reference internal" href="reference/import.html#module-specs"><span class="std std-ref">Module specs</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-MRO">MRO<a class="headerlink" href="#term-MRO" title="Link to this term">¶</a></dt><dd><p>See <a class="reference internal" href="#term-method-resolution-order"><span class="xref std std-term">method resolution order</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-mutable">mutable<a class="headerlink" href="#term-mutable" title="Link to this term">¶</a></dt><dd><p>Mutable objects can change their value but keep their <a class="reference internal" href="library/functions.html#id" title="id"><code class="xref py py-func docutils literal notranslate"><span class="pre">id()</span></code></a>. See
|
||
also <a class="reference internal" href="#term-immutable"><span class="xref std std-term">immutable</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-named-tuple">named tuple<a class="headerlink" href="#term-named-tuple" title="Link to this term">¶</a></dt><dd><p>The term “named tuple” applies to any type or class that inherits from
|
||
tuple and whose indexable elements are also accessible using named
|
||
attributes. The type or class may have other features as well.</p>
|
||
<p>Several built-in types are named tuples, including the values returned
|
||
by <a class="reference internal" href="library/time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.localtime()</span></code></a> and <a class="reference internal" href="library/os.html#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a>. Another example is
|
||
<a class="reference internal" href="library/sys.html#sys.float_info" title="sys.float_info"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.float_info</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">sys</span><span class="o">.</span><span class="n">float_info</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="c1"># indexed access</span>
|
||
<span class="go">1024</span>
|
||
<span class="gp">>>> </span><span class="n">sys</span><span class="o">.</span><span class="n">float_info</span><span class="o">.</span><span class="n">max_exp</span> <span class="c1"># named field access</span>
|
||
<span class="go">1024</span>
|
||
<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">float_info</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">)</span> <span class="c1"># kind of tuple</span>
|
||
<span class="go">True</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Some named tuples are built-in types (such as the above examples).
|
||
Alternatively, a named tuple can be created from a regular class
|
||
definition that inherits from <a class="reference internal" href="library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> and that defines named
|
||
fields. Such a class can be written by hand, or it can be created by
|
||
inheriting <a class="reference internal" href="library/typing.html#typing.NamedTuple" title="typing.NamedTuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">typing.NamedTuple</span></code></a>, or with the factory function
|
||
<a class="reference internal" href="library/collections.html#collections.namedtuple" title="collections.namedtuple"><code class="xref py py-func docutils literal notranslate"><span class="pre">collections.namedtuple()</span></code></a>. The latter techniques also add some
|
||
extra methods that may not be found in hand-written or built-in named
|
||
tuples.</p>
|
||
</dd>
|
||
<dt id="term-namespace">namespace<a class="headerlink" href="#term-namespace" title="Link to this term">¶</a></dt><dd><p>The place where a variable is stored. Namespaces are implemented as
|
||
dictionaries. There are the local, global and built-in namespaces as well
|
||
as nested namespaces in objects (in methods). Namespaces support
|
||
modularity by preventing naming conflicts. For instance, the functions
|
||
<a class="reference internal" href="library/functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">builtins.open</span></code></a> and <a class="reference internal" href="library/os.html#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.open()</span></code></a> are distinguished by
|
||
their namespaces. Namespaces also aid readability and maintainability by
|
||
making it clear which module implements a function. For instance, writing
|
||
<a class="reference internal" href="library/random.html#random.seed" title="random.seed"><code class="xref py py-func docutils literal notranslate"><span class="pre">random.seed()</span></code></a> or <a class="reference internal" href="library/itertools.html#itertools.islice" title="itertools.islice"><code class="xref py py-func docutils literal notranslate"><span class="pre">itertools.islice()</span></code></a> makes it clear that those
|
||
functions are implemented by the <a class="reference internal" href="library/random.html#module-random" title="random: Generate pseudo-random numbers with various common distributions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code></a> and <a class="reference internal" href="library/itertools.html#module-itertools" title="itertools: Functions creating iterators for efficient looping."><code class="xref py py-mod docutils literal notranslate"><span class="pre">itertools</span></code></a>
|
||
modules, respectively.</p>
|
||
</dd>
|
||
<dt id="term-namespace-package">namespace package<a class="headerlink" href="#term-namespace-package" title="Link to this term">¶</a></dt><dd><p>A <a class="reference internal" href="#term-package"><span class="xref std std-term">package</span></a> which serves only as a container for subpackages.
|
||
Namespace packages may have no physical representation,
|
||
and specifically are not like a <a class="reference internal" href="#term-regular-package"><span class="xref std std-term">regular package</span></a> because they
|
||
have no <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file.</p>
|
||
<p>Namespace packages allow several individually installable packages to have a common parent package.
|
||
Otherwise, it is recommended to use a <a class="reference internal" href="#term-regular-package"><span class="xref std std-term">regular package</span></a>.</p>
|
||
<p>For more information, see <span class="target" id="index-29"></span><a class="pep reference external" href="https://peps.python.org/pep-0420/"><strong>PEP 420</strong></a> and <a class="reference internal" href="reference/import.html#reference-namespace-package"><span class="std std-ref">Namespace packages</span></a>.</p>
|
||
<p>See also <a class="reference internal" href="#term-module"><span class="xref std std-term">module</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-nested-scope">nested scope<a class="headerlink" href="#term-nested-scope" title="Link to this term">¶</a></dt><dd><p>The ability to refer to a variable in an enclosing definition. For
|
||
instance, a function defined inside another function can refer to
|
||
variables in the outer function. Note that nested scopes by default work
|
||
only for reference and not for assignment. Local variables both read and
|
||
write in the innermost scope. Likewise, global variables read and write
|
||
to the global namespace. The <a class="reference internal" href="reference/simple_stmts.html#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a> allows writing to outer
|
||
scopes.</p>
|
||
</dd>
|
||
<dt id="term-new-style-class">new-style class<a class="headerlink" href="#term-new-style-class" title="Link to this term">¶</a></dt><dd><p>Old name for the flavor of classes now used for all class objects. In
|
||
earlier Python versions, only new-style classes could use Python’s newer,
|
||
versatile features like <a class="reference internal" href="reference/datamodel.html#object.__slots__" title="object.__slots__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code></a>, descriptors,
|
||
properties, <a class="reference internal" href="reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a>, class methods, and static
|
||
methods.</p>
|
||
</dd>
|
||
<dt id="term-object">object<a class="headerlink" href="#term-object" title="Link to this term">¶</a></dt><dd><p>Any data with state (attributes or value) and defined behavior
|
||
(methods). Also the ultimate base class of any <a class="reference internal" href="#term-new-style-class"><span class="xref std std-term">new-style
|
||
class</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-optimized-scope">optimized scope<a class="headerlink" href="#term-optimized-scope" title="Link to this term">¶</a></dt><dd><p>A scope where target local variable names are reliably known to the
|
||
compiler when the code is compiled, allowing optimization of read and
|
||
write access to these names. The local namespaces for functions,
|
||
generators, coroutines, comprehensions, and generator expressions are
|
||
optimized in this fashion. Note: most interpreter optimizations are
|
||
applied to all scopes, only those relying on a known set of local
|
||
and nonlocal variable names are restricted to optimized scopes.</p>
|
||
</dd>
|
||
<dt id="term-package">package<a class="headerlink" href="#term-package" title="Link to this term">¶</a></dt><dd><p>A Python <a class="reference internal" href="#term-module"><span class="xref std std-term">module</span></a> which can contain submodules or recursively,
|
||
subpackages. Technically, a package is a Python module with a
|
||
<code class="docutils literal notranslate"><span class="pre">__path__</span></code> attribute.</p>
|
||
<p>See also <a class="reference internal" href="#term-regular-package"><span class="xref std std-term">regular package</span></a> and <a class="reference internal" href="#term-namespace-package"><span class="xref std std-term">namespace package</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-parameter">parameter<a class="headerlink" href="#term-parameter" title="Link to this term">¶</a></dt><dd><p>A named entity in a <a class="reference internal" href="#term-function"><span class="xref std std-term">function</span></a> (or method) definition that
|
||
specifies an <a class="reference internal" href="#term-argument"><span class="xref std std-term">argument</span></a> (or in some cases, arguments) that the
|
||
function can accept. There are five kinds of parameter:</p>
|
||
<ul>
|
||
<li><p><em class="dfn">positional-or-keyword</em>: specifies an argument that can be passed
|
||
either <a class="reference internal" href="#term-argument"><span class="xref std std-term">positionally</span></a> or as a <a class="reference internal" href="#term-argument"><span class="xref std std-term">keyword argument</span></a>. This is the default kind of parameter, for example <em>foo</em>
|
||
and <em>bar</em> in the following:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">func</span><span class="p">(</span><span class="n">foo</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span> <span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<ul id="positional-only-parameter">
|
||
<li><p><em class="dfn">positional-only</em>: specifies an argument that can be supplied only
|
||
by position. Positional-only parameters can be defined by including a
|
||
<code class="docutils literal notranslate"><span class="pre">/</span></code> character in the parameter list of the function definition after
|
||
them, for example <em>posonly1</em> and <em>posonly2</em> in the following:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">func</span><span class="p">(</span><span class="n">posonly1</span><span class="p">,</span> <span class="n">posonly2</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="n">positional_or_keyword</span><span class="p">):</span> <span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<ul id="keyword-only-parameter">
|
||
<li><p><em class="dfn">keyword-only</em>: specifies an argument that can be supplied only
|
||
by keyword. Keyword-only parameters can be defined by including a
|
||
single var-positional parameter or bare <code class="docutils literal notranslate"><span class="pre">*</span></code> in the parameter list
|
||
of the function definition before them, for example <em>kw_only1</em> and
|
||
<em>kw_only2</em> in the following:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">func</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">kw_only1</span><span class="p">,</span> <span class="n">kw_only2</span><span class="p">):</span> <span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><em class="dfn">var-positional</em>: specifies that an arbitrary sequence of
|
||
positional arguments can be provided (in addition to any positional
|
||
arguments already accepted by other parameters). Such a parameter can
|
||
be defined by prepending the parameter name with <code class="docutils literal notranslate"><span class="pre">*</span></code>, for example
|
||
<em>args</em> in the following:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">func</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span> <span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><em class="dfn">var-keyword</em>: specifies that arbitrarily many keyword arguments
|
||
can be provided (in addition to any keyword arguments already accepted
|
||
by other parameters). Such a parameter can be defined by prepending
|
||
the parameter name with <code class="docutils literal notranslate"><span class="pre">**</span></code>, for example <em>kwargs</em> in the example
|
||
above.</p></li>
|
||
</ul>
|
||
<p>Parameters can specify both optional and required arguments, as well as
|
||
default values for some optional arguments.</p>
|
||
<p>See also the <a class="reference internal" href="#term-argument"><span class="xref std std-term">argument</span></a> glossary entry, the FAQ question on
|
||
<a class="reference internal" href="faq/programming.html#faq-argument-vs-parameter"><span class="std std-ref">the difference between arguments and parameters</span></a>, the <a class="reference internal" href="library/inspect.html#inspect.Parameter" title="inspect.Parameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">inspect.Parameter</span></code></a> class, the
|
||
<a class="reference internal" href="reference/compound_stmts.html#function"><span class="std std-ref">Function definitions</span></a> section, and <span class="target" id="index-30"></span><a class="pep reference external" href="https://peps.python.org/pep-0362/"><strong>PEP 362</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-path-entry">path entry<a class="headerlink" href="#term-path-entry" title="Link to this term">¶</a></dt><dd><p>A single location on the <a class="reference internal" href="#term-import-path"><span class="xref std std-term">import path</span></a> which the <a class="reference internal" href="#term-path-based-finder"><span class="xref std std-term">path
|
||
based finder</span></a> consults to find modules for importing.</p>
|
||
</dd>
|
||
<dt id="term-path-entry-finder">path entry finder<a class="headerlink" href="#term-path-entry-finder" title="Link to this term">¶</a></dt><dd><p>A <a class="reference internal" href="#term-finder"><span class="xref std std-term">finder</span></a> returned by a callable on <a class="reference internal" href="library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a>
|
||
(i.e. a <a class="reference internal" href="#term-path-entry-hook"><span class="xref std std-term">path entry hook</span></a>) which knows how to locate modules given
|
||
a <a class="reference internal" href="#term-path-entry"><span class="xref std std-term">path entry</span></a>.</p>
|
||
<p>See <a class="reference internal" href="library/importlib.html#importlib.abc.PathEntryFinder" title="importlib.abc.PathEntryFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">importlib.abc.PathEntryFinder</span></code></a> for the methods that path entry
|
||
finders implement.</p>
|
||
</dd>
|
||
<dt id="term-path-entry-hook">path entry hook<a class="headerlink" href="#term-path-entry-hook" title="Link to this term">¶</a></dt><dd><p>A callable on the <a class="reference internal" href="library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a> list which returns a <a class="reference internal" href="#term-path-entry-finder"><span class="xref std std-term">path
|
||
entry finder</span></a> if it knows how to find modules on a specific <a class="reference internal" href="#term-path-entry"><span class="xref std std-term">path
|
||
entry</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-path-based-finder">path based finder<a class="headerlink" href="#term-path-based-finder" title="Link to this term">¶</a></dt><dd><p>One of the default <a class="reference internal" href="#term-meta-path-finder"><span class="xref std std-term">meta path finders</span></a> which
|
||
searches an <a class="reference internal" href="#term-import-path"><span class="xref std std-term">import path</span></a> for modules.</p>
|
||
</dd>
|
||
<dt id="term-path-like-object">path-like object<a class="headerlink" href="#term-path-like-object" title="Link to this term">¶</a></dt><dd><p>An object representing a file system path. A path-like object is either
|
||
a <a class="reference internal" href="library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object representing a path, or an object
|
||
implementing the <a class="reference internal" href="library/os.html#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.PathLike</span></code></a> protocol. An object that supports
|
||
the <a class="reference internal" href="library/os.html#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.PathLike</span></code></a> protocol can be converted to a <a class="reference internal" href="library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or
|
||
<a class="reference internal" href="library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> file system path by calling the <a class="reference internal" href="library/os.html#os.fspath" title="os.fspath"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fspath()</span></code></a> function;
|
||
<a class="reference internal" href="library/os.html#os.fsdecode" title="os.fsdecode"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fsdecode()</span></code></a> and <a class="reference internal" href="library/os.html#os.fsencode" title="os.fsencode"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fsencode()</span></code></a> can be used to guarantee a
|
||
<a class="reference internal" href="library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> result instead, respectively. Introduced
|
||
by <span class="target" id="index-31"></span><a class="pep reference external" href="https://peps.python.org/pep-0519/"><strong>PEP 519</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-PEP">PEP<a class="headerlink" href="#term-PEP" title="Link to this term">¶</a></dt><dd><p>Python Enhancement Proposal. A PEP is a design document
|
||
providing information to the Python community, or describing a new
|
||
feature for Python or its processes or environment. PEPs should
|
||
provide a concise technical specification and a rationale for proposed
|
||
features.</p>
|
||
<p>PEPs are intended to be the primary mechanisms for proposing major new
|
||
features, for collecting community input on an issue, and for documenting
|
||
the design decisions that have gone into Python. The PEP author is
|
||
responsible for building consensus within the community and documenting
|
||
dissenting opinions.</p>
|
||
<p>See <span class="target" id="index-32"></span><a class="pep reference external" href="https://peps.python.org/pep-0001/"><strong>PEP 1</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-portion">portion<a class="headerlink" href="#term-portion" title="Link to this term">¶</a></dt><dd><p>A set of files in a single directory (possibly stored in a zip file)
|
||
that contribute to a namespace package, as defined in <span class="target" id="index-33"></span><a class="pep reference external" href="https://peps.python.org/pep-0420/"><strong>PEP 420</strong></a>.</p>
|
||
</dd>
|
||
<dt id="term-positional-argument">positional argument<a class="headerlink" href="#term-positional-argument" title="Link to this term">¶</a></dt><dd><p>See <a class="reference internal" href="#term-argument"><span class="xref std std-term">argument</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-provisional-API">provisional API<a class="headerlink" href="#term-provisional-API" title="Link to this term">¶</a></dt><dd><p>A provisional API is one which has been deliberately excluded from
|
||
the standard library’s backwards compatibility guarantees. While major
|
||
changes to such interfaces are not expected, as long as they are marked
|
||
provisional, backwards incompatible changes (up to and including removal
|
||
of the interface) may occur if deemed necessary by core developers. Such
|
||
changes will not be made gratuitously – they will occur only if serious
|
||
fundamental flaws are uncovered that were missed prior to the inclusion
|
||
of the API.</p>
|
||
<p>Even for provisional APIs, backwards incompatible changes are seen as
|
||
a “solution of last resort” - every attempt will still be made to find
|
||
a backwards compatible resolution to any identified problems.</p>
|
||
<p>This process allows the standard library to continue to evolve over
|
||
time, without locking in problematic design errors for extended periods
|
||
of time. See <span class="target" id="index-34"></span><a class="pep reference external" href="https://peps.python.org/pep-0411/"><strong>PEP 411</strong></a> for more details.</p>
|
||
</dd>
|
||
<dt id="term-provisional-package">provisional package<a class="headerlink" href="#term-provisional-package" title="Link to this term">¶</a></dt><dd><p>See <a class="reference internal" href="#term-provisional-API"><span class="xref std std-term">provisional API</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-Python-3000">Python 3000<a class="headerlink" href="#term-Python-3000" title="Link to this term">¶</a></dt><dd><p>Nickname for the Python 3.x release line (coined long ago when the
|
||
release of version 3 was something in the distant future.) This is also
|
||
abbreviated “Py3k”.</p>
|
||
</dd>
|
||
<dt id="term-Pythonic">Pythonic<a class="headerlink" href="#term-Pythonic" title="Link to this term">¶</a></dt><dd><p>An idea or piece of code which closely follows the most common idioms
|
||
of the Python language, rather than implementing code using concepts
|
||
common to other languages. For example, a common idiom in Python is
|
||
to loop over all elements of an iterable using a <a class="reference internal" href="reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a>
|
||
statement. Many other languages don’t have this type of construct, so
|
||
people unfamiliar with Python sometimes use a numerical counter instead:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">food</span><span class="p">)):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">food</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>As opposed to the cleaner, Pythonic method:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">piece</span> <span class="ow">in</span> <span class="n">food</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">piece</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt id="term-qualified-name">qualified name<a class="headerlink" href="#term-qualified-name" title="Link to this term">¶</a></dt><dd><p>A dotted name showing the “path” from a module’s global scope to a
|
||
class, function or method defined in that module, as defined in
|
||
<span class="target" id="index-35"></span><a class="pep reference external" href="https://peps.python.org/pep-3155/"><strong>PEP 3155</strong></a>. For top-level functions and classes, the qualified name
|
||
is the same as the object’s name:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="k">class</span><span class="w"> </span><span class="nc">D</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="nf">meth</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">pass</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">C</span><span class="o">.</span><span class="vm">__qualname__</span>
|
||
<span class="go">'C'</span>
|
||
<span class="gp">>>> </span><span class="n">C</span><span class="o">.</span><span class="n">D</span><span class="o">.</span><span class="vm">__qualname__</span>
|
||
<span class="go">'C.D'</span>
|
||
<span class="gp">>>> </span><span class="n">C</span><span class="o">.</span><span class="n">D</span><span class="o">.</span><span class="n">meth</span><span class="o">.</span><span class="vm">__qualname__</span>
|
||
<span class="go">'C.D.meth'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>When used to refer to modules, the <em>fully qualified name</em> means the
|
||
entire dotted path to the module, including any parent packages,
|
||
e.g. <code class="docutils literal notranslate"><span class="pre">email.mime.text</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">email.mime.text</span>
|
||
<span class="gp">>>> </span><span class="n">email</span><span class="o">.</span><span class="n">mime</span><span class="o">.</span><span class="n">text</span><span class="o">.</span><span class="vm">__name__</span>
|
||
<span class="go">'email.mime.text'</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt id="term-reference-count">reference count<a class="headerlink" href="#term-reference-count" title="Link to this term">¶</a></dt><dd><p>The number of references to an object. When the reference count of an
|
||
object drops to zero, it is deallocated. Some objects are
|
||
<a class="reference internal" href="#term-immortal"><span class="xref std std-term">immortal</span></a> and have reference counts that are never modified, and
|
||
therefore the objects are never deallocated. Reference counting is
|
||
generally not visible to Python code, but it is a key element of the
|
||
<a class="reference internal" href="#term-CPython"><span class="xref std std-term">CPython</span></a> implementation. Programmers can call the
|
||
<a class="reference internal" href="library/sys.html#sys.getrefcount" title="sys.getrefcount"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getrefcount()</span></code></a> function to return the
|
||
reference count for a particular object.</p>
|
||
</dd>
|
||
<dt id="term-regular-package">regular package<a class="headerlink" href="#term-regular-package" title="Link to this term">¶</a></dt><dd><p>A traditional <a class="reference internal" href="#term-package"><span class="xref std std-term">package</span></a>, such as a directory containing an
|
||
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file.</p>
|
||
<p>See also <a class="reference internal" href="#term-namespace-package"><span class="xref std std-term">namespace package</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-REPL">REPL<a class="headerlink" href="#term-REPL" title="Link to this term">¶</a></dt><dd><p>An acronym for the “read–eval–print loop”, another name for the
|
||
<a class="reference internal" href="#term-interactive"><span class="xref std std-term">interactive</span></a> interpreter shell.</p>
|
||
</dd>
|
||
<dt id="term-__slots__">__slots__<a class="headerlink" href="#term-__slots__" title="Link to this term">¶</a></dt><dd><p>A declaration inside a class that saves memory by pre-declaring space for
|
||
instance attributes and eliminating instance dictionaries. Though
|
||
popular, the technique is somewhat tricky to get right and is best
|
||
reserved for rare cases where there are large numbers of instances in a
|
||
memory-critical application.</p>
|
||
</dd>
|
||
<dt id="term-sequence">sequence<a class="headerlink" href="#term-sequence" title="Link to this term">¶</a></dt><dd><p>An <a class="reference internal" href="#term-iterable"><span class="xref std std-term">iterable</span></a> which supports efficient element access using integer
|
||
indices via the <a class="reference internal" href="reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> special method and defines a
|
||
<a class="reference internal" href="reference/datamodel.html#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code></a> method that returns the length of the sequence.
|
||
Some built-in sequence types are <a class="reference internal" href="library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, <a class="reference internal" href="library/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="library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>, and <a class="reference internal" href="library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>. Note that <a class="reference internal" href="library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> also
|
||
supports <a class="reference internal" href="reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code>, but is considered a
|
||
mapping rather than a sequence because the lookups use arbitrary
|
||
<a class="reference internal" href="#term-hashable"><span class="xref std std-term">hashable</span></a> keys rather than integers.</p>
|
||
<p>The <a class="reference internal" href="library/collections.abc.html#collections.abc.Sequence" title="collections.abc.Sequence"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.abc.Sequence</span></code></a> abstract base class
|
||
defines a much richer interface that goes beyond just
|
||
<a class="reference internal" href="reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> and <a class="reference internal" href="reference/datamodel.html#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code></a>, adding
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">count()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">index()</span></code>, <a class="reference internal" href="reference/datamodel.html#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a>, and
|
||
<a class="reference internal" href="reference/datamodel.html#object.__reversed__" title="object.__reversed__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__reversed__()</span></code></a>. Types that implement this expanded
|
||
interface can be registered explicitly using
|
||
<a class="reference internal" href="library/abc.html#abc.ABCMeta.register" title="abc.ABCMeta.register"><code class="xref py py-func docutils literal notranslate"><span class="pre">register()</span></code></a>. For more documentation on sequence
|
||
methods generally, see
|
||
<a class="reference internal" href="library/stdtypes.html#typesseq-common"><span class="std std-ref">Common Sequence Operations</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-set-comprehension">set comprehension<a class="headerlink" href="#term-set-comprehension" title="Link to this term">¶</a></dt><dd><p>A compact way to process all or part of the elements in an iterable and
|
||
return a set with the results. <code class="docutils literal notranslate"><span class="pre">results</span> <span class="pre">=</span> <span class="pre">{c</span> <span class="pre">for</span> <span class="pre">c</span> <span class="pre">in</span> <span class="pre">'abracadabra'</span> <span class="pre">if</span>
|
||
<span class="pre">c</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">'abc'}</span></code> generates the set of strings <code class="docutils literal notranslate"><span class="pre">{'r',</span> <span class="pre">'d'}</span></code>. See
|
||
<a class="reference internal" href="reference/expressions.html#comprehensions"><span class="std std-ref">Displays for lists, sets and dictionaries</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-single-dispatch">single dispatch<a class="headerlink" href="#term-single-dispatch" title="Link to this term">¶</a></dt><dd><p>A form of <a class="reference internal" href="#term-generic-function"><span class="xref std std-term">generic function</span></a> dispatch where the implementation is
|
||
chosen based on the type of a single argument.</p>
|
||
</dd>
|
||
<dt id="term-slice">slice<a class="headerlink" href="#term-slice" title="Link to this term">¶</a></dt><dd><p>An object usually containing a portion of a <a class="reference internal" href="#term-sequence"><span class="xref std std-term">sequence</span></a>. A slice is
|
||
created using the subscript notation, <code class="docutils literal notranslate"><span class="pre">[]</span></code> with colons between numbers
|
||
when several are given, such as in <code class="docutils literal notranslate"><span class="pre">variable_name[1:3:5]</span></code>. The bracket
|
||
(subscript) notation uses <a class="reference internal" href="library/functions.html#slice" title="slice"><code class="xref py py-class docutils literal notranslate"><span class="pre">slice</span></code></a> objects internally.</p>
|
||
</dd>
|
||
<dt id="term-soft-deprecated">soft deprecated<a class="headerlink" href="#term-soft-deprecated" title="Link to this term">¶</a></dt><dd><p>A soft deprecated API should not be used in new code,
|
||
but it is safe for already existing code to use it.
|
||
The API remains documented and tested, but will not be enhanced further.</p>
|
||
<p>Soft deprecation, unlike normal deprecation, does not plan on removing the API
|
||
and will not emit warnings.</p>
|
||
<p>See <a class="reference external" href="https://peps.python.org/pep-0387/#soft-deprecation">PEP 387: Soft Deprecation</a>.</p>
|
||
</dd>
|
||
<dt id="term-special-method">special method<a class="headerlink" href="#term-special-method" title="Link to this term">¶</a></dt><dd><p id="index-36">A method that is called implicitly by Python to execute a certain
|
||
operation on a type, such as addition. Such methods have names starting
|
||
and ending with double underscores. Special methods are documented in
|
||
<a class="reference internal" href="reference/datamodel.html#specialnames"><span class="std std-ref">Special method names</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-statement">statement<a class="headerlink" href="#term-statement" title="Link to this term">¶</a></dt><dd><p>A statement is part of a suite (a “block” of code). A statement is either
|
||
an <a class="reference internal" href="#term-expression"><span class="xref std std-term">expression</span></a> or one of several constructs with a keyword, such
|
||
as <a class="reference internal" href="reference/compound_stmts.html#if"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code></a>, <a class="reference internal" href="reference/compound_stmts.html#while"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">while</span></code></a> or <a class="reference internal" href="reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a>.</p>
|
||
</dd>
|
||
<dt id="term-static-type-checker">static type checker<a class="headerlink" href="#term-static-type-checker" title="Link to this term">¶</a></dt><dd><p>An external tool that reads Python code and analyzes it, looking for
|
||
issues such as incorrect types. See also <a class="reference internal" href="#term-type-hint"><span class="xref std std-term">type hints</span></a>
|
||
and the <a class="reference internal" href="library/typing.html#module-typing" title="typing: Support for type hints (see :pep:`484`)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> module.</p>
|
||
</dd>
|
||
<dt id="term-strong-reference">strong reference<a class="headerlink" href="#term-strong-reference" title="Link to this term">¶</a></dt><dd><p>In Python’s C API, a strong reference is a reference to an object
|
||
which is owned by the code holding the reference. The strong
|
||
reference is taken by calling <a class="reference internal" href="c-api/refcounting.html#c.Py_INCREF" title="Py_INCREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_INCREF()</span></code></a> when the
|
||
reference is created and released with <a class="reference internal" href="c-api/refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a>
|
||
when the reference is deleted.</p>
|
||
<p>The <a class="reference internal" href="c-api/refcounting.html#c.Py_NewRef" title="Py_NewRef"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_NewRef()</span></code></a> function can be used to create a strong reference
|
||
to an object. Usually, the <a class="reference internal" href="c-api/refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> function must be called on
|
||
the strong reference before exiting the scope of the strong reference, to
|
||
avoid leaking one reference.</p>
|
||
<p>See also <a class="reference internal" href="#term-borrowed-reference"><span class="xref std std-term">borrowed reference</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-text-encoding">text encoding<a class="headerlink" href="#term-text-encoding" title="Link to this term">¶</a></dt><dd><p>A string in Python is a sequence of Unicode code points (in range
|
||
<code class="docutils literal notranslate"><span class="pre">U+0000</span></code>–<code class="docutils literal notranslate"><span class="pre">U+10FFFF</span></code>). To store or transfer a string, it needs to be
|
||
serialized as a sequence of bytes.</p>
|
||
<p>Serializing a string into a sequence of bytes is known as “encoding”, and
|
||
recreating the string from the sequence of bytes is known as “decoding”.</p>
|
||
<p>There are a variety of different text serialization
|
||
<a class="reference internal" href="library/codecs.html#standard-encodings"><span class="std std-ref">codecs</span></a>, which are collectively referred to as
|
||
“text encodings”.</p>
|
||
</dd>
|
||
<dt id="term-text-file">text file<a class="headerlink" href="#term-text-file" title="Link to this term">¶</a></dt><dd><p>A <a class="reference internal" href="#term-file-object"><span class="xref std std-term">file object</span></a> able to read and write <a class="reference internal" href="library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> objects.
|
||
Often, a text file actually accesses a byte-oriented datastream
|
||
and handles the <a class="reference internal" href="#term-text-encoding"><span class="xref std std-term">text encoding</span></a> automatically.
|
||
Examples of text files are files opened in text mode (<code class="docutils literal notranslate"><span class="pre">'r'</span></code> or <code class="docutils literal notranslate"><span class="pre">'w'</span></code>),
|
||
<a class="reference internal" href="library/sys.html#sys.stdin" title="sys.stdin"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdin</span></code></a>, <a class="reference internal" href="library/sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a>, and instances of
|
||
<a class="reference internal" href="library/io.html#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.StringIO</span></code></a>.</p>
|
||
<p>See also <a class="reference internal" href="#term-binary-file"><span class="xref std std-term">binary file</span></a> for a file object able to read and write
|
||
<a class="reference internal" href="#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>.</p>
|
||
</dd>
|
||
<dt id="term-token">token<a class="headerlink" href="#term-token" title="Link to this term">¶</a></dt><dd><p>A small unit of source code, generated by the
|
||
<a class="reference internal" href="reference/lexical_analysis.html#lexical"><span class="std std-ref">lexical analyzer</span></a> (also called the <em>tokenizer</em>).
|
||
Names, numbers, strings, operators,
|
||
newlines and similar are represented by tokens.</p>
|
||
<p>The <a class="reference internal" href="library/tokenize.html#module-tokenize" title="tokenize: Lexical scanner for Python source code."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tokenize</span></code></a> module exposes Python’s lexical analyzer.
|
||
The <a class="reference internal" href="library/token.html#module-token" title="token: Constants representing terminal nodes of the parse tree."><code class="xref py py-mod docutils literal notranslate"><span class="pre">token</span></code></a> module contains information on the various types
|
||
of tokens.</p>
|
||
</dd>
|
||
<dt id="term-triple-quoted-string">triple-quoted string<a class="headerlink" href="#term-triple-quoted-string" title="Link to this term">¶</a></dt><dd><p>A string which is bound by three instances of either a quotation mark
|
||
(”) or an apostrophe (‘). While they don’t provide any functionality
|
||
not available with single-quoted strings, they are useful for a number
|
||
of reasons. They allow you to include unescaped single and double
|
||
quotes within a string and they can span multiple lines without the
|
||
use of the continuation character, making them especially useful when
|
||
writing docstrings.</p>
|
||
</dd>
|
||
<dt id="term-type">type<a class="headerlink" href="#term-type" title="Link to this term">¶</a></dt><dd><p>The type of a Python object determines what kind of object it is; every
|
||
object has a type. An object’s type is accessible as its
|
||
<a class="reference internal" href="reference/datamodel.html#object.__class__" title="object.__class__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__class__</span></code></a> attribute or can be retrieved with
|
||
<code class="docutils literal notranslate"><span class="pre">type(obj)</span></code>.</p>
|
||
</dd>
|
||
<dt id="term-type-alias">type alias<a class="headerlink" href="#term-type-alias" title="Link to this term">¶</a></dt><dd><p>A synonym for a type, created by assigning the type to an identifier.</p>
|
||
<p>Type aliases are useful for simplifying <a class="reference internal" href="#term-type-hint"><span class="xref std std-term">type hints</span></a>.
|
||
For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">remove_gray_shades</span><span class="p">(</span>
|
||
<span class="n">colors</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">]])</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="nb">tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">]]:</span>
|
||
<span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>could be made more readable like this:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Color</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">]</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">remove_gray_shades</span><span class="p">(</span><span class="n">colors</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Color</span><span class="p">])</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="n">Color</span><span class="p">]:</span>
|
||
<span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>See <a class="reference internal" href="library/typing.html#module-typing" title="typing: Support for type hints (see :pep:`484`)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> and <span class="target" id="index-37"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a>, which describe this functionality.</p>
|
||
</dd>
|
||
<dt id="term-type-hint">type hint<a class="headerlink" href="#term-type-hint" title="Link to this term">¶</a></dt><dd><p>An <a class="reference internal" href="#term-annotation"><span class="xref std std-term">annotation</span></a> that specifies the expected type for a variable, a class
|
||
attribute, or a function parameter or return value.</p>
|
||
<p>Type hints are optional and are not enforced by Python but
|
||
they are useful to <a class="reference internal" href="#term-static-type-checker"><span class="xref std std-term">static type checkers</span></a>.
|
||
They can also aid IDEs with code completion and refactoring.</p>
|
||
<p>Type hints of global variables, class attributes, and functions,
|
||
but not local variables, can be accessed using
|
||
<a class="reference internal" href="library/typing.html#typing.get_type_hints" title="typing.get_type_hints"><code class="xref py py-func docutils literal notranslate"><span class="pre">typing.get_type_hints()</span></code></a>.</p>
|
||
<p>See <a class="reference internal" href="library/typing.html#module-typing" title="typing: Support for type hints (see :pep:`484`)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> and <span class="target" id="index-38"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a>, which describe this functionality.</p>
|
||
</dd>
|
||
<dt id="term-universal-newlines">universal newlines<a class="headerlink" href="#term-universal-newlines" title="Link to this term">¶</a></dt><dd><p>A manner of interpreting text streams in which all of the following are
|
||
recognized as ending a line: the Unix end-of-line convention <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>,
|
||
the Windows convention <code class="docutils literal notranslate"><span class="pre">'\r\n'</span></code>, and the old Macintosh convention
|
||
<code class="docutils literal notranslate"><span class="pre">'\r'</span></code>. See <span class="target" id="index-39"></span><a class="pep reference external" href="https://peps.python.org/pep-0278/"><strong>PEP 278</strong></a> and <span class="target" id="index-40"></span><a class="pep reference external" href="https://peps.python.org/pep-3116/"><strong>PEP 3116</strong></a>, as well as
|
||
<a class="reference internal" href="library/stdtypes.html#bytes.splitlines" title="bytes.splitlines"><code class="xref py py-func docutils literal notranslate"><span class="pre">bytes.splitlines()</span></code></a> for an additional use.</p>
|
||
</dd>
|
||
<dt id="term-variable-annotation">variable annotation<a class="headerlink" href="#term-variable-annotation" title="Link to this term">¶</a></dt><dd><p>An <a class="reference internal" href="#term-annotation"><span class="xref std std-term">annotation</span></a> of a variable or a class attribute.</p>
|
||
<p>When annotating a variable or a class attribute, assignment is optional:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
|
||
<span class="n">field</span><span class="p">:</span> <span class="s1">'annotation'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Variable annotations are usually used for
|
||
<a class="reference internal" href="#term-type-hint"><span class="xref std std-term">type hints</span></a>: for example this variable is expected to take
|
||
<a class="reference internal" href="library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> values:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">count</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Variable annotation syntax is explained in section <a class="reference internal" href="reference/simple_stmts.html#annassign"><span class="std std-ref">Annotated assignment statements</span></a>.</p>
|
||
<p>See <a class="reference internal" href="#term-function-annotation"><span class="xref std std-term">function annotation</span></a>, <span class="target" id="index-41"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a>
|
||
and <span class="target" id="index-42"></span><a class="pep reference external" href="https://peps.python.org/pep-0526/"><strong>PEP 526</strong></a>, which describe this functionality.
|
||
Also see <a class="reference internal" href="howto/annotations.html#annotations-howto"><span class="std std-ref">Annotations Best Practices</span></a>
|
||
for best practices on working with annotations.</p>
|
||
</dd>
|
||
<dt id="term-virtual-environment">virtual environment<a class="headerlink" href="#term-virtual-environment" title="Link to this term">¶</a></dt><dd><p>A cooperatively isolated runtime environment that allows Python users
|
||
and applications to install and upgrade Python distribution packages
|
||
without interfering with the behaviour of other Python applications
|
||
running on the same system.</p>
|
||
<p>See also <a class="reference internal" href="library/venv.html#module-venv" title="venv: Creation of virtual environments."><code class="xref py py-mod docutils literal notranslate"><span class="pre">venv</span></code></a>.</p>
|
||
</dd>
|
||
<dt id="term-virtual-machine">virtual machine<a class="headerlink" href="#term-virtual-machine" title="Link to this term">¶</a></dt><dd><p>A computer defined entirely in software. Python’s virtual machine
|
||
executes the <a class="reference internal" href="#term-bytecode"><span class="xref std std-term">bytecode</span></a> emitted by the bytecode compiler.</p>
|
||
</dd>
|
||
<dt id="term-Zen-of-Python">Zen of Python<a class="headerlink" href="#term-Zen-of-Python" title="Link to this term">¶</a></dt><dd><p>Listing of Python design principles and philosophies that are helpful in
|
||
understanding and using the language. The listing can be found by typing
|
||
“<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">this</span></code>” at the interactive prompt.</p>
|
||
</dd>
|
||
</dl>
|
||
</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="deprecations/index.html"
|
||
title="previous chapter">Deprecations</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="about.html"
|
||
title="next chapter">About this documentation</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/glossary.rst"
|
||
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="about.html" title="About this documentation"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="deprecations/index.html" title="Deprecations"
|
||
>previous</a> |</li>
|
||
|
||
<li><img src="_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-this"><a href="">Glossary</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">
|
||
©
|
||
<a href="copyright.html">
|
||
|
||
Copyright
|
||
|
||
</a>
|
||
2001-2025, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br />
|
||
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
Last updated on Apr 08, 2025 (14:33 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> |