865 lines
61 KiB
HTML
865 lines
61 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="4. Execution model" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/reference/executionmodel.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="Structure of a program: A Python program is constructed from code blocks. A block is a piece of Python program text that is executed as a unit. The following are blocks: a module, a function body, ..." />
|
||
<meta property="og:image" content="_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="Structure of a program: A Python program is constructed from code blocks. A block is a piece of Python program text that is executed as a unit. The following are blocks: a module, a function body, ..." />
|
||
<meta name="theme-color" content="#3776ab">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
|
||
<title>4. Execution model — Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
|
||
|
||
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.15.0 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="5. The import system" href="import.html" />
|
||
<link rel="prev" title="3. Data model" href="datamodel.html" />
|
||
|
||
|
||
<link rel="canonical" href="https://docs.python.org/3/reference/executionmodel.html">
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo">
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">4. Execution model</a><ul>
|
||
<li><a class="reference internal" href="#structure-of-a-program">4.1. Structure of a program</a></li>
|
||
<li><a class="reference internal" href="#naming-and-binding">4.2. Naming and binding</a><ul>
|
||
<li><a class="reference internal" href="#binding-of-names">4.2.1. Binding of names</a></li>
|
||
<li><a class="reference internal" href="#resolution-of-names">4.2.2. Resolution of names</a></li>
|
||
<li><a class="reference internal" href="#annotation-scopes">4.2.3. Annotation scopes</a></li>
|
||
<li><a class="reference internal" href="#lazy-evaluation">4.2.4. Lazy evaluation</a></li>
|
||
<li><a class="reference internal" href="#builtins-and-restricted-execution">4.2.5. Builtins and restricted execution</a></li>
|
||
<li><a class="reference internal" href="#interaction-with-dynamic-features">4.2.6. Interaction with dynamic features</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#exceptions">4.3. Exceptions</a></li>
|
||
<li><a class="reference internal" href="#runtime-components">4.4. Runtime Components</a><ul>
|
||
<li><a class="reference internal" href="#general-computing-model">4.4.1. General Computing Model</a></li>
|
||
<li><a class="reference internal" href="#python-runtime-model">4.4.2. Python Runtime Model</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="datamodel.html"
|
||
title="previous chapter"><span class="section-number">3. </span>Data model</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="import.html"
|
||
title="next chapter"><span class="section-number">5. </span>The import system</a></p>
|
||
</div>
|
||
<script>
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
const title = document.querySelector('meta[property="og:title"]').content;
|
||
const elements = document.querySelectorAll('.improvepage');
|
||
const pageurl = window.location.href.split('?')[0];
|
||
elements.forEach(element => {
|
||
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
|
||
url.searchParams.set('pagetitle', title);
|
||
url.searchParams.set('pageurl', pageurl);
|
||
url.searchParams.set('pagesource', "reference/executionmodel.rst");
|
||
element.href = url.toString();
|
||
});
|
||
});
|
||
</script>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a bug</a></li>
|
||
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.15/Doc/reference/executionmodel.rst?plain=1"
|
||
rel="nofollow">Show source
|
||
</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="import.html" title="5. The import system"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="datamodel.html" title="3. Data model"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.15.0 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Python Language Reference</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><span class="section-number">4. </span>Execution model</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="execution-model">
|
||
<span id="execmodel"></span><h1><span class="section-number">4. </span>Execution model<a class="headerlink" href="#execution-model" title="Link to this heading">¶</a></h1>
|
||
<section id="structure-of-a-program">
|
||
<span id="prog-structure"></span><span id="index-0"></span><h2><span class="section-number">4.1. </span>Structure of a program<a class="headerlink" href="#structure-of-a-program" title="Link to this heading">¶</a></h2>
|
||
<p id="index-1">A Python program is constructed from code blocks.
|
||
A <em class="dfn">block</em> is a piece of Python program text that is executed as a unit.
|
||
The following are blocks: a module, a function body, and a class definition.
|
||
Each command typed interactively is a block. A script file (a file given as
|
||
standard input to the interpreter or specified as a command line argument to the
|
||
interpreter) is a code block. A script command (a command specified on the
|
||
interpreter command line with the <a class="reference internal" href="../using/cmdline.html#cmdoption-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">-c</span></code></a> option) is a code block.
|
||
A module run as a top level script (as module <code class="docutils literal notranslate"><span class="pre">__main__</span></code>) from the command
|
||
line using a <a class="reference internal" href="../using/cmdline.html#cmdoption-m"><code class="xref std std-option docutils literal notranslate"><span class="pre">-m</span></code></a> argument is also a code block. The string
|
||
argument passed to the built-in functions <a class="reference internal" href="../builtins/functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> and <a class="reference internal" href="../builtins/functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a> is a
|
||
code block.</p>
|
||
<p id="index-2">A code block is executed in an <em class="dfn">execution frame</em>. A frame contains some
|
||
administrative information (used for debugging) and determines where and how
|
||
execution continues after the code block’s execution has completed.</p>
|
||
</section>
|
||
<section id="naming-and-binding">
|
||
<span id="naming"></span><h2><span class="section-number">4.2. </span>Naming and binding<a class="headerlink" href="#naming-and-binding" title="Link to this heading">¶</a></h2>
|
||
<section id="binding-of-names">
|
||
<span id="bind-names"></span><span id="index-3"></span><h3><span class="section-number">4.2.1. </span>Binding of names<a class="headerlink" href="#binding-of-names" title="Link to this heading">¶</a></h3>
|
||
<p id="index-4"><em class="dfn">Names</em> refer to objects. Names are introduced by name binding operations.</p>
|
||
<p id="index-5">The following constructs bind names:</p>
|
||
<ul class="simple">
|
||
<li><p>formal parameters to functions,</p></li>
|
||
<li><p>class definitions,</p></li>
|
||
<li><p>function definitions,</p></li>
|
||
<li><p>assignment expressions,</p></li>
|
||
<li><p><a class="reference internal" href="simple_stmts.html#assignment"><span class="std std-ref">targets</span></a> that are identifiers if occurring in
|
||
an assignment:</p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> loop header,</p></li>
|
||
<li><p>after <code class="xref std std-keyword docutils literal notranslate"><span class="pre">as</span></code> in a <a class="reference internal" href="compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement, <a class="reference internal" href="compound_stmts.html#except"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">except</span></code></a>
|
||
clause, <a class="reference internal" href="compound_stmts.html#except-star"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">except*</span></code></a> clause, or in the as-pattern in structural pattern matching,</p></li>
|
||
<li><p>in a capture pattern in structural pattern matching</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference internal" href="simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statements.</p></li>
|
||
<li><p><a class="reference internal" href="simple_stmts.html#type"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">type</span></code></a> statements.</p></li>
|
||
<li><p><a class="reference internal" href="compound_stmts.html#type-params"><span class="std std-ref">type parameter lists</span></a>.</p></li>
|
||
</ul>
|
||
<p>The <code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code> statement of the form <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">...</span> <span class="pre">import</span> <span class="pre">*</span></code> binds all
|
||
names defined in the imported module, except those beginning with an underscore.
|
||
This form may only be used at the module level.</p>
|
||
<p>A target occurring in a <a class="reference internal" href="simple_stmts.html#del"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">del</span></code></a> statement is also considered bound for
|
||
this purpose (though the actual semantics are to unbind the name).</p>
|
||
<p>Each assignment or import statement occurs within a block defined by a class or
|
||
function definition or at the module level (the top-level code block).</p>
|
||
<p id="index-6">If a name is bound in a block, it is a local variable of that block, unless
|
||
declared as <a class="reference internal" href="simple_stmts.html#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a> or <a class="reference internal" href="simple_stmts.html#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a>. If a name is bound at
|
||
the module level, it is a global variable. (The variables of the module code
|
||
block are local and global.) If a variable is used in a code block but not
|
||
defined there, it is a <a class="reference internal" href="../glossary.html#term-free-variable"><span class="xref std std-term">free variable</span></a>.</p>
|
||
<p>Each occurrence of a name in the program text refers to the <em class="dfn">binding</em> of
|
||
that name established by the following name resolution rules.</p>
|
||
</section>
|
||
<section id="resolution-of-names">
|
||
<span id="resolve-names"></span><h3><span class="section-number">4.2.2. </span>Resolution of names<a class="headerlink" href="#resolution-of-names" title="Link to this heading">¶</a></h3>
|
||
<p id="index-7">A <em class="dfn">scope</em> defines the visibility of a name within a block. If a local
|
||
variable is defined in a block, its scope includes that block. If the
|
||
definition occurs in a function block, the scope extends to any blocks contained
|
||
within the defining one, unless a contained block introduces a different binding
|
||
for the name.</p>
|
||
<p id="index-8">When a name is used in a code block, it is resolved using the nearest enclosing
|
||
scope. The set of all such scopes visible to a code block is called the block’s
|
||
<em class="dfn">environment</em>.</p>
|
||
<p id="index-9">When a name is not found at all, a <a class="reference internal" href="../builtins/exceptions.html#NameError" title="NameError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NameError</span></code></a> exception is raised.
|
||
If the current scope is a function scope, and the name refers to a local
|
||
variable that has not yet been bound to a value at the point where the name is
|
||
used, an <a class="reference internal" href="../builtins/exceptions.html#UnboundLocalError" title="UnboundLocalError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnboundLocalError</span></code></a> exception is raised.
|
||
<code class="xref py py-exc docutils literal notranslate"><span class="pre">UnboundLocalError</span></code> is a subclass of <code class="xref py py-exc docutils literal notranslate"><span class="pre">NameError</span></code>.</p>
|
||
<p>If a name binding operation occurs anywhere within a code block, all uses of the
|
||
name within the block are treated as references to the current block. This can
|
||
lead to errors when a name is used within a block before it is bound. This rule
|
||
is subtle. Python lacks declarations and allows name binding operations to
|
||
occur anywhere within a code block. The local variables of a code block can be
|
||
determined by scanning the entire text of the block for name binding operations.
|
||
See <a class="reference internal" href="../faq/programming.html#faq-unboundlocalerror"><span class="std std-ref">the FAQ entry on UnboundLocalError</span></a>
|
||
for examples.</p>
|
||
<p>If the <a class="reference internal" href="simple_stmts.html#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> statement occurs within a block, all uses of the names
|
||
specified in the statement refer to the bindings of those names in the top-level
|
||
namespace. Names are resolved in the top-level namespace by searching the
|
||
global namespace, i.e. the namespace of the module containing the code block,
|
||
and the builtins namespace, the namespace of the module <a class="reference internal" href="../library/builtins.html#module-builtins" title="builtins: The module that provides the built-in namespace."><code class="xref py py-mod docutils literal notranslate"><span class="pre">builtins</span></code></a>. The
|
||
global namespace is searched first. If the names are not found there, the
|
||
builtins namespace is searched next. If the names are also not found in the
|
||
builtins namespace, new variables are created in the global namespace.
|
||
The global statement must precede all uses of the listed names.</p>
|
||
<p>The <a class="reference internal" href="simple_stmts.html#global"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">global</span></code></a> statement has the same scope as a name binding operation
|
||
in the same block. If the nearest enclosing scope for a free variable contains
|
||
a global statement, the free variable is treated as a global.</p>
|
||
<p>The <a class="reference internal" href="simple_stmts.html#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a> statement causes corresponding names to refer
|
||
to previously bound variables in the nearest enclosing function scope.
|
||
<a class="reference internal" href="../builtins/exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a> is raised at compile time if the given name does not
|
||
exist in any enclosing function scope. <a class="reference internal" href="compound_stmts.html#type-params"><span class="std std-ref">Type parameters</span></a>
|
||
cannot be rebound with the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code> statement.</p>
|
||
<p id="index-10">The namespace for a module is automatically created the first time a module is
|
||
imported. The main module for a script is always called <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where top-level code is run. Covers command-line interfaces, import-time behavior, and ``__name__ == '__main__'``."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a>.</p>
|
||
<p>Class definition blocks and arguments to <a class="reference internal" href="../builtins/functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a> and <a class="reference internal" href="../builtins/functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> are
|
||
special in the context of name resolution.
|
||
A class definition is an executable statement that may use and define names.
|
||
These references follow the normal rules for name resolution with an exception
|
||
that unbound local variables are looked up in the global namespace.
|
||
The namespace of the class definition becomes the attribute dictionary of
|
||
the class. The scope of names defined in a class block is limited to the
|
||
class block; it does not extend to the code blocks of methods. This includes
|
||
comprehensions and generator expressions, but it does not include
|
||
<a class="reference internal" href="#annotation-scopes"><span class="std std-ref">annotation scopes</span></a>,
|
||
which have access to their enclosing class scopes.
|
||
This means that the following will fail:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">A</span><span class="p">:</span>
|
||
<span class="n">a</span> <span class="o">=</span> <span class="mi">42</span>
|
||
<span class="n">b</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">a</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>
|
||
</pre></div>
|
||
</div>
|
||
<p>However, the following will succeed:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">A</span><span class="p">:</span>
|
||
<span class="nb">type</span> <span class="n">Alias</span> <span class="o">=</span> <span class="n">Nested</span>
|
||
<span class="k">class</span><span class="w"> </span><span class="nc">Nested</span><span class="p">:</span> <span class="k">pass</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">A</span><span class="o">.</span><span class="n">Alias</span><span class="o">.</span><span class="n">__value__</span><span class="p">)</span> <span class="c1"># <type 'A.Nested'></span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="annotation-scopes">
|
||
<span id="id1"></span><h3><span class="section-number">4.2.3. </span>Annotation scopes<a class="headerlink" href="#annotation-scopes" title="Link to this heading">¶</a></h3>
|
||
<p><a class="reference internal" href="../glossary.html#term-annotation"><span class="xref std std-term">Annotations</span></a>, <a class="reference internal" href="compound_stmts.html#type-params"><span class="std std-ref">type parameter lists</span></a>
|
||
and <a class="reference internal" href="simple_stmts.html#type"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">type</span></code></a> statements
|
||
introduce <em>annotation scopes</em>, which behave mostly like function scopes,
|
||
but with some exceptions discussed below.</p>
|
||
<p>Annotation scopes are used in the following contexts:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="../glossary.html#term-function-annotation"><span class="xref std std-term">Function annotations</span></a>.</p></li>
|
||
<li><p><a class="reference internal" href="../glossary.html#term-variable-annotation"><span class="xref std std-term">Variable annotations</span></a>.</p></li>
|
||
<li><p>Type parameter lists for <a class="reference internal" href="compound_stmts.html#generic-type-aliases"><span class="std std-ref">generic type aliases</span></a>.</p></li>
|
||
<li><p>Type parameter lists for <a class="reference internal" href="compound_stmts.html#generic-functions"><span class="std std-ref">generic functions</span></a>.
|
||
A generic function’s annotations are
|
||
executed within the annotation scope, but its defaults and decorators are not.</p></li>
|
||
<li><p>Type parameter lists for <a class="reference internal" href="compound_stmts.html#generic-classes"><span class="std std-ref">generic classes</span></a>.
|
||
A generic class’s base classes and
|
||
keyword arguments are executed within the annotation scope, but its decorators are not.</p></li>
|
||
<li><p>The bounds, constraints, and default values for type parameters
|
||
(<a class="reference internal" href="#lazy-evaluation"><span class="std std-ref">lazily evaluated</span></a>).</p></li>
|
||
<li><p>The value of type aliases (<a class="reference internal" href="#lazy-evaluation"><span class="std std-ref">lazily evaluated</span></a>).</p></li>
|
||
</ul>
|
||
<p>Annotation scopes differ from function scopes in the following ways:</p>
|
||
<ul class="simple">
|
||
<li><p>Annotation scopes have access to their enclosing class namespace.
|
||
If an annotation scope is immediately within a class scope, or within another
|
||
annotation scope that is immediately within a class scope, the code in the
|
||
annotation scope can use names defined in the class scope as if it were
|
||
executed directly within the class body. This contrasts with regular
|
||
functions defined within classes, which cannot access names defined in the class scope.</p></li>
|
||
<li><p>Expressions in annotation scopes cannot contain <a class="reference internal" href="simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a>, <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span></code>,
|
||
<a class="reference internal" href="expressions.html#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a>, or <a class="reference internal" href="expressions.html#grammar-token-python-grammar-assignment_expression"><code class="xref std std-token docutils literal notranslate"><span class="pre">:=</span></code></a>
|
||
expressions. (These expressions are allowed in other scopes contained within the
|
||
annotation scope.)</p></li>
|
||
<li><p>Names defined in annotation scopes cannot be rebound with <a class="reference internal" href="simple_stmts.html#nonlocal"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">nonlocal</span></code></a>
|
||
statements in inner scopes. This includes only type parameters, as no other
|
||
syntactic elements that can appear within annotation scopes can introduce new names.</p></li>
|
||
<li><p>While annotation scopes have an internal name, that name is not reflected in the
|
||
<a class="reference internal" href="../glossary.html#term-qualified-name"><span class="xref std std-term">qualified name</span></a> of objects defined within the scope.
|
||
Instead, the <a class="reference internal" href="../builtins/stdtypes.html#definition.__qualname__" title="definition.__qualname__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__qualname__</span></code></a>
|
||
of such objects is as if the object were defined in the enclosing scope.</p></li>
|
||
</ul>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.12: </span>Annotation scopes were introduced in Python 3.12 as part of <span class="target" id="index-11"></span><a class="pep reference external" href="https://peps.python.org/pep-0695/"><strong>PEP 695</strong></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.13: </span>Annotation scopes are also used for type parameter defaults, as
|
||
introduced by <span class="target" id="index-12"></span><a class="pep reference external" href="https://peps.python.org/pep-0696/"><strong>PEP 696</strong></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.14: </span>Annotation scopes are now also used for annotations, as specified in
|
||
<span class="target" id="index-13"></span><a class="pep reference external" href="https://peps.python.org/pep-0649/"><strong>PEP 649</strong></a> and <span class="target" id="index-14"></span><a class="pep reference external" href="https://peps.python.org/pep-0749/"><strong>PEP 749</strong></a>.</p>
|
||
</div>
|
||
</section>
|
||
<section id="lazy-evaluation">
|
||
<span id="id2"></span><h3><span class="section-number">4.2.4. </span>Lazy evaluation<a class="headerlink" href="#lazy-evaluation" title="Link to this heading">¶</a></h3>
|
||
<p>Most annotation scopes are <em>lazily evaluated</em>. This includes annotations,
|
||
the values of type aliases created through the <a class="reference internal" href="simple_stmts.html#type"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">type</span></code></a> statement, and
|
||
the bounds, constraints, and default values of type
|
||
variables created through the <a class="reference internal" href="compound_stmts.html#type-params"><span class="std std-ref">type parameter syntax</span></a>.
|
||
This means that they are not evaluated when the type alias or type variable is
|
||
created, or when the object carrying annotations is created. Instead, they
|
||
are only evaluated when necessary, for example when the <code class="docutils literal notranslate"><span class="pre">__value__</span></code>
|
||
attribute on a type alias is accessed.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">type</span> <span class="n">Alias</span> <span class="o">=</span> <span class="mi">1</span><span class="o">/</span><span class="mi">0</span>
|
||
<span class="gp">>>> </span><span class="n">Alias</span><span class="o">.</span><span class="n">__value__</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="w"> </span><span class="c">...</span>
|
||
<span class="gr">ZeroDivisionError</span>: <span class="n">division by zero</span>
|
||
<span class="gp">>>> </span><span class="k">def</span><span class="w"> </span><span class="nf">func</span><span class="p">[</span><span class="n">T</span><span class="p">:</span> <span class="mi">1</span><span class="o">/</span><span class="mi">0</span><span class="p">]():</span> <span class="k">pass</span>
|
||
<span class="gp">>>> </span><span class="n">T</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">__type_params__</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
|
||
<span class="gp">>>> </span><span class="n">T</span><span class="o">.</span><span class="n">__bound__</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="w"> </span><span class="c">...</span>
|
||
<span class="gr">ZeroDivisionError</span>: <span class="n">division by zero</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Here the exception is raised only when the <code class="docutils literal notranslate"><span class="pre">__value__</span></code> attribute
|
||
of the type alias or the <code class="docutils literal notranslate"><span class="pre">__bound__</span></code> attribute of the type variable
|
||
is accessed.</p>
|
||
<p>This behavior is primarily useful for references to types that have not
|
||
yet been defined when the type alias or type variable is created. For example,
|
||
lazy evaluation enables creation of mutually recursive type aliases:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Literal</span>
|
||
|
||
<span class="nb">type</span> <span class="n">SimpleExpr</span> <span class="o">=</span> <span class="nb">int</span> <span class="o">|</span> <span class="n">Parenthesized</span>
|
||
<span class="nb">type</span> <span class="n">Parenthesized</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">[</span><span class="n">Literal</span><span class="p">[</span><span class="s2">"("</span><span class="p">],</span> <span class="n">Expr</span><span class="p">,</span> <span class="n">Literal</span><span class="p">[</span><span class="s2">")"</span><span class="p">]]</span>
|
||
<span class="nb">type</span> <span class="n">Expr</span> <span class="o">=</span> <span class="n">SimpleExpr</span> <span class="o">|</span> <span class="nb">tuple</span><span class="p">[</span><span class="n">SimpleExpr</span><span class="p">,</span> <span class="n">Literal</span><span class="p">[</span><span class="s2">"+"</span><span class="p">,</span> <span class="s2">"-"</span><span class="p">],</span> <span class="n">Expr</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Lazily evaluated values are evaluated in <a class="reference internal" href="#annotation-scopes"><span class="std std-ref">annotation scope</span></a>,
|
||
which means that names that appear inside the lazily evaluated value are looked up
|
||
as if they were used in the immediately enclosing scope.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.12.</span></p>
|
||
</div>
|
||
</section>
|
||
<section id="builtins-and-restricted-execution">
|
||
<span id="restrict-exec"></span><h3><span class="section-number">4.2.5. </span>Builtins and restricted execution<a class="headerlink" href="#builtins-and-restricted-execution" title="Link to this heading">¶</a></h3>
|
||
<div class="impl-detail compound" id="index-15">
|
||
<p><strong>CPython implementation detail:</strong> Users should not touch <code class="docutils literal notranslate"><span class="pre">__builtins__</span></code>; it is strictly an implementation
|
||
detail. Users wanting to override values in the builtins namespace should
|
||
<a class="reference internal" href="simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> the <a class="reference internal" href="../library/builtins.html#module-builtins" title="builtins: The module that provides the built-in namespace."><code class="xref py py-mod docutils literal notranslate"><span class="pre">builtins</span></code></a> module and modify its
|
||
attributes appropriately.</p>
|
||
</div>
|
||
<p>The builtins namespace associated with the execution of a code block
|
||
is actually found by looking up the name <code class="docutils literal notranslate"><span class="pre">__builtins__</span></code> in its
|
||
global namespace; this should be a dictionary or a module (in the
|
||
latter case the module’s dictionary is used). By default, when in the
|
||
<a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where top-level code is run. Covers command-line interfaces, import-time behavior, and ``__name__ == '__main__'``."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> module, <code class="docutils literal notranslate"><span class="pre">__builtins__</span></code> is the built-in module
|
||
<a class="reference internal" href="../library/builtins.html#module-builtins" title="builtins: The module that provides the built-in namespace."><code class="xref py py-mod docutils literal notranslate"><span class="pre">builtins</span></code></a>; when in any other module, <code class="docutils literal notranslate"><span class="pre">__builtins__</span></code> is an
|
||
alias for the dictionary of the <code class="xref py py-mod docutils literal notranslate"><span class="pre">builtins</span></code> module itself.</p>
|
||
</section>
|
||
<section id="interaction-with-dynamic-features">
|
||
<span id="dynamic-features"></span><h3><span class="section-number">4.2.6. </span>Interaction with dynamic features<a class="headerlink" href="#interaction-with-dynamic-features" title="Link to this heading">¶</a></h3>
|
||
<p>Name resolution of free variables occurs at runtime, not at compile time.
|
||
This means that the following code will print 42:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">i</span> <span class="o">=</span> <span class="mi">10</span>
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">():</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>
|
||
<span class="n">i</span> <span class="o">=</span> <span class="mi">42</span>
|
||
<span class="n">f</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <a class="reference internal" href="../builtins/functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> and <a class="reference internal" href="../builtins/functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a> functions do not have access to the full
|
||
environment for resolving names. Names may be resolved in the local and global
|
||
namespaces of the caller. Free variables are not resolved in the nearest
|
||
enclosing namespace, but in the global namespace. <a class="footnote-reference brackets" href="#id5" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> The <code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code> and
|
||
<code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code> functions have optional arguments to override the global and local
|
||
namespace. If only one namespace is specified, it is used for both.</p>
|
||
</section>
|
||
</section>
|
||
<section id="exceptions">
|
||
<span id="id4"></span><h2><span class="section-number">4.3. </span>Exceptions<a class="headerlink" href="#exceptions" title="Link to this heading">¶</a></h2>
|
||
<p id="index-17"><span id="index-16"></span>Exceptions are a means of breaking out of the normal flow of control of a code
|
||
block in order to handle errors or other exceptional conditions. An exception
|
||
is <em>raised</em> at the point where the error is detected; it may be <em>handled</em> by the
|
||
surrounding code block or by any code block that directly or indirectly invoked
|
||
the code block where the error occurred.</p>
|
||
<p>The Python interpreter raises an exception when it detects a run-time error
|
||
(such as division by zero). A Python program can also explicitly raise an
|
||
exception with the <a class="reference internal" href="simple_stmts.html#raise"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">raise</span></code></a> statement. Exception handlers are specified
|
||
with the <a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> … <a class="reference internal" href="compound_stmts.html#except"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">except</span></code></a> statement. The <a class="reference internal" href="compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a>
|
||
clause of such a statement can be used to specify cleanup code which does not
|
||
handle the exception, but is executed whether an exception occurred or not in
|
||
the preceding code.</p>
|
||
<p id="index-18">Python uses the “termination” model of error handling: an exception handler can
|
||
find out what happened and continue execution at an outer level, but it cannot
|
||
repair the cause of the error and retry the failing operation (except by
|
||
re-entering the offending piece of code from the top).</p>
|
||
<p id="index-19">When an exception is not handled at all, the interpreter terminates execution of
|
||
the program, or returns to its interactive main loop. In either case, it prints
|
||
a stack traceback, except when the exception is <a class="reference internal" href="../builtins/exceptions.html#SystemExit" title="SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a>.</p>
|
||
<p>Exceptions are identified by class instances. The <a class="reference internal" href="compound_stmts.html#except"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">except</span></code></a> clause is
|
||
selected depending on the class of the instance: it must reference the class of
|
||
the instance or a <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">non-virtual base class</span></a> thereof.
|
||
The instance can be received by the handler and can carry additional information
|
||
about the exceptional condition.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Exception messages are not part of the Python API. Their contents may change
|
||
from one version of Python to the next without warning and should not be
|
||
relied on by code which will run under multiple versions of the interpreter.</p>
|
||
</div>
|
||
<p>See also the description of the <a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> statement in section <a class="reference internal" href="compound_stmts.html#try"><span class="std std-ref">The try statement</span></a>
|
||
and <a class="reference internal" href="simple_stmts.html#raise"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">raise</span></code></a> statement in section <a class="reference internal" href="simple_stmts.html#raise"><span class="std std-ref">The raise statement</span></a>.</p>
|
||
</section>
|
||
<section id="runtime-components">
|
||
<span id="execcomponents"></span><h2><span class="section-number">4.4. </span>Runtime Components<a class="headerlink" href="#runtime-components" title="Link to this heading">¶</a></h2>
|
||
<section id="general-computing-model">
|
||
<h3><span class="section-number">4.4.1. </span>General Computing Model<a class="headerlink" href="#general-computing-model" title="Link to this heading">¶</a></h3>
|
||
<p>Python’s execution model does not operate in a vacuum. It runs on
|
||
a host machine and through that host’s runtime environment, including
|
||
its operating system (OS), if there is one. When a program runs,
|
||
the conceptual layers of how it runs on the host look something
|
||
like this:</p>
|
||
<blockquote>
|
||
<div><div class="line-block">
|
||
<div class="line"><strong>host machine</strong></div>
|
||
<div class="line-block">
|
||
<div class="line"><strong>process</strong> (global resources)</div>
|
||
<div class="line-block">
|
||
<div class="line"><strong>thread</strong> (runs machine code)</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div></blockquote>
|
||
<p>Each process represents a program running on the host. Think of each
|
||
process itself as the data part of its program. Think of the process’
|
||
threads as the execution part of the program. This distinction will
|
||
be important to understand the conceptual Python runtime.</p>
|
||
<p>The process, as the data part, is the execution context in which the
|
||
program runs. It mostly consists of the set of resources assigned to
|
||
the program by the host, including memory, signals, file handles,
|
||
sockets, and environment variables.</p>
|
||
<p>Processes are isolated and independent from one another. (The same
|
||
is true for hosts.) The host manages the process’ access to its
|
||
assigned resources, in addition to coordinating between processes.</p>
|
||
<p>Each thread represents the actual execution of the program’s machine
|
||
code, running relative to the resources assigned to the program’s
|
||
process. It’s strictly up to the host how and when that execution
|
||
takes place.</p>
|
||
<p>From the point of view of Python, a program always starts with exactly
|
||
one thread. However, the program may grow to run in multiple
|
||
simultaneous threads. Not all hosts support multiple threads per
|
||
process, but most do. Unlike processes, threads in a process are not
|
||
isolated and independent from one another. Specifically, all threads
|
||
in a process share all of the process’ resources.</p>
|
||
<p>The fundamental point of threads is that each one does <em>run</em>
|
||
independently, at the same time as the others. That may be only
|
||
conceptually at the same time (“concurrently”) or physically
|
||
(“in parallel”). Either way, the threads effectively run
|
||
at a non-synchronized rate.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>That non-synchronized rate means none of the process’ memory is
|
||
guaranteed to stay consistent for the code running in any given
|
||
thread. Thus multi-threaded programs must take care to coordinate
|
||
access to intentionally shared resources. Likewise, they must take
|
||
care to be absolutely diligent about not accessing any <em>other</em>
|
||
resources in multiple threads; otherwise two threads running at the
|
||
same time might accidentally interfere with each other’s use of some
|
||
shared data. All this is true for both Python programs and the
|
||
Python runtime.</p>
|
||
<p>The cost of this broad, unstructured requirement is the tradeoff for
|
||
the kind of raw concurrency that threads provide. The alternative
|
||
to the required discipline generally means dealing with
|
||
non-deterministic bugs and data corruption.</p>
|
||
</div>
|
||
</section>
|
||
<section id="python-runtime-model">
|
||
<h3><span class="section-number">4.4.2. </span>Python Runtime Model<a class="headerlink" href="#python-runtime-model" title="Link to this heading">¶</a></h3>
|
||
<p>The same conceptual layers apply to each Python program, with some
|
||
extra data layers specific to Python:</p>
|
||
<blockquote>
|
||
<div><div class="line-block">
|
||
<div class="line"><strong>host machine</strong></div>
|
||
<div class="line-block">
|
||
<div class="line"><strong>process</strong> (global resources)</div>
|
||
<div class="line-block">
|
||
<div class="line">Python global runtime (<em>state</em>)</div>
|
||
<div class="line-block">
|
||
<div class="line">Python interpreter (<em>state</em>)</div>
|
||
<div class="line-block">
|
||
<div class="line"><strong>thread</strong> (runs Python bytecode and “C-API”)</div>
|
||
<div class="line-block">
|
||
<div class="line">Python thread <em>state</em></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div></blockquote>
|
||
<p>At the conceptual level: when a Python program starts, it looks exactly
|
||
like that diagram, with one of each. The runtime may grow to include
|
||
multiple interpreters, and each interpreter may grow to include
|
||
multiple thread states.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>A Python implementation won’t necessarily implement the runtime
|
||
layers distinctly or even concretely. The only exception is places
|
||
where distinct layers are directly specified or exposed to users,
|
||
like through the <a class="reference internal" href="../library/threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The initial interpreter is typically called the “main” interpreter.
|
||
Some Python implementations, like CPython, assign special roles
|
||
to the main interpreter.</p>
|
||
<p>Likewise, the host thread where the runtime was initialized is known
|
||
as the “main” thread. It may be different from the process’ initial
|
||
thread, though they are often the same. In some cases “main thread”
|
||
may be even more specific and refer to the initial thread state.
|
||
A Python runtime might assign specific responsibilities
|
||
to the main thread, such as handling signals.</p>
|
||
</div>
|
||
<p>As a whole, the Python runtime consists of the global runtime state,
|
||
interpreters, and thread states. The runtime ensures all that state
|
||
stays consistent over its lifetime, particularly when used with
|
||
multiple host threads.</p>
|
||
<p>The global runtime, at the conceptual level, is just a set of
|
||
interpreters. While those interpreters are otherwise isolated and
|
||
independent from one another, they may share some data or other
|
||
resources. The runtime is responsible for managing these global
|
||
resources safely. The actual nature and management of these resources
|
||
is implementation-specific. Ultimately, the external utility of the
|
||
global runtime is limited to managing interpreters.</p>
|
||
<p>In contrast, an “interpreter” is conceptually what we would normally
|
||
think of as the (full-featured) “Python runtime”. When machine code
|
||
executing in a host thread interacts with the Python runtime, it calls
|
||
into Python in the context of a specific interpreter.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The term “interpreter” here is not the same as the “bytecode
|
||
interpreter”, which is what regularly runs in threads, executing
|
||
compiled Python code.</p>
|
||
<p>In an ideal world, “Python runtime” would refer to what we currently
|
||
call “interpreter”. However, it’s been called “interpreter” at least
|
||
since introduced in 1997 (<a class="reference external" href="https://github.com/python/cpython/commit/a027efa5b">CPython:a027efa5b</a>).</p>
|
||
</div>
|
||
<p>Each interpreter completely encapsulates all of the non-process-global,
|
||
non-thread-specific state needed for the Python runtime to work.
|
||
Notably, the interpreter’s state persists between uses. It includes
|
||
fundamental data like <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>. The runtime ensures
|
||
multiple threads using the same interpreter will safely
|
||
share it between them.</p>
|
||
<p>A Python implementation may support using multiple interpreters at the
|
||
same time in the same process. They are independent and isolated from
|
||
one another. For example, each interpreter has its own
|
||
<a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>.</p>
|
||
<p>For thread-specific runtime state, each interpreter has a set of thread
|
||
states, which it manages, in the same way the global runtime contains
|
||
a set of interpreters. It can have thread states for as many host
|
||
threads as it needs. It may even have multiple thread states for
|
||
the same host thread, though that isn’t as common.</p>
|
||
<p>Each thread state, conceptually, has all the thread-specific runtime
|
||
data an interpreter needs to operate in one host thread. The thread
|
||
state includes the current raised exception and the thread’s Python
|
||
call stack. It may include other thread-specific resources.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The term “Python thread” can sometimes refer to a thread state, but
|
||
normally it means a thread created using the <a class="reference internal" href="../library/threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module.</p>
|
||
</div>
|
||
<p>Each thread state, over its lifetime, is always tied to exactly one
|
||
interpreter and exactly one host thread. It will only ever be used in
|
||
that thread and with that interpreter.</p>
|
||
<p>Multiple thread states may be tied to the same host thread, whether for
|
||
different interpreters or even the same interpreter. However, for any
|
||
given host thread, only one of the thread states tied to it can be used
|
||
by the thread at a time.</p>
|
||
<p>Thread states are isolated and independent from one another and don’t
|
||
share any data, except for possibly sharing an interpreter and objects
|
||
or other resources belonging to that interpreter.</p>
|
||
<p>Once a program is running, new Python threads can be created using the
|
||
<a class="reference internal" href="../library/threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module (on platforms and Python implementations that
|
||
support threads). Additional processes can be created using the
|
||
<a class="reference internal" href="../library/os.html#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a>, <a class="reference internal" href="../library/subprocess.html#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a>, and <a class="reference internal" href="../library/multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> modules.
|
||
Interpreters can be created and used with the
|
||
<a class="reference internal" href="../library/concurrent.interpreters.html#module-concurrent.interpreters" title="concurrent.interpreters: Multiple interpreters in the same process"><code class="xref py py-mod docutils literal notranslate"><span class="pre">interpreters</span></code></a> module. Coroutines (async) can
|
||
be run using <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> in each interpreter, typically only
|
||
in a single thread (often the main thread).</p>
|
||
<p class="rubric">Footnotes</p>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id5" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">1</a><span class="fn-bracket">]</span></span>
|
||
<p>This limitation occurs because the code that is executed by these operations
|
||
is not available at the time the module is compiled.</p>
|
||
</aside>
|
||
</aside>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">4. Execution model</a><ul>
|
||
<li><a class="reference internal" href="#structure-of-a-program">4.1. Structure of a program</a></li>
|
||
<li><a class="reference internal" href="#naming-and-binding">4.2. Naming and binding</a><ul>
|
||
<li><a class="reference internal" href="#binding-of-names">4.2.1. Binding of names</a></li>
|
||
<li><a class="reference internal" href="#resolution-of-names">4.2.2. Resolution of names</a></li>
|
||
<li><a class="reference internal" href="#annotation-scopes">4.2.3. Annotation scopes</a></li>
|
||
<li><a class="reference internal" href="#lazy-evaluation">4.2.4. Lazy evaluation</a></li>
|
||
<li><a class="reference internal" href="#builtins-and-restricted-execution">4.2.5. Builtins and restricted execution</a></li>
|
||
<li><a class="reference internal" href="#interaction-with-dynamic-features">4.2.6. Interaction with dynamic features</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#exceptions">4.3. Exceptions</a></li>
|
||
<li><a class="reference internal" href="#runtime-components">4.4. Runtime Components</a><ul>
|
||
<li><a class="reference internal" href="#general-computing-model">4.4.1. General Computing Model</a></li>
|
||
<li><a class="reference internal" href="#python-runtime-model">4.4.2. Python Runtime Model</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="datamodel.html"
|
||
title="previous chapter"><span class="section-number">3. </span>Data model</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="import.html"
|
||
title="next chapter"><span class="section-number">5. </span>The import system</a></p>
|
||
</div>
|
||
<script>
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
const title = document.querySelector('meta[property="og:title"]').content;
|
||
const elements = document.querySelectorAll('.improvepage');
|
||
const pageurl = window.location.href.split('?')[0];
|
||
elements.forEach(element => {
|
||
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
|
||
url.searchParams.set('pagetitle', title);
|
||
url.searchParams.set('pageurl', pageurl);
|
||
url.searchParams.set('pagesource', "reference/executionmodel.rst");
|
||
element.href = url.toString();
|
||
});
|
||
});
|
||
</script>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a bug</a></li>
|
||
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.15/Doc/reference/executionmodel.rst?plain=1"
|
||
rel="nofollow">Show source
|
||
</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="import.html" title="5. The import system"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="datamodel.html" title="3. Data model"
|
||
>previous</a> |</li>
|
||
|
||
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.15.0 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Language Reference</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><span class="section-number">4. </span>Execution model</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 Python Software Foundation.
|
||
<br>
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br>
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br>
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br>
|
||
|
||
|
||
<br>
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br>
|
||
<br>
|
||
Last updated on Oct 09, 2026 (11:35 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br>
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |