mirror of
https://gitflic.ru/project/openide/openide.git
synced 2026-09-27 10:03:11 +07:00
fixed PY-14822 Show external documentation about Python keywords
added builtin documentation for python keywords
This commit is contained in:
Ekaterina Tuzova
@@ -0,0 +1,5 @@
|
||||
<div class="section" id="false">
|
||||
<tt class="descname">False</tt>
|
||||
<p>The false value of the <a class="reference internal" href="functions.html#bool" title="bool"><tt class="xref py py-class docutils literal"><span class="pre">bool</span></tt></a> type. Assignments to <tt class="docutils literal"><span class="pre">False</span></tt>
|
||||
are illegal and raise a <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><tt class="xref py py-exc docutils literal"><span class="pre">SyntaxError</span></tt></a>.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,6 @@
|
||||
<div class="section" id="none">
|
||||
<tt class="descname">None</tt>
|
||||
<p>The sole value of the type <tt class="docutils literal"><span class="pre">NoneType</span></tt>. <tt class="docutils literal"><span class="pre">None</span></tt> is frequently used to
|
||||
represent the absence of a value, as when default arguments are not passed to a
|
||||
function. Assignments to <tt class="docutils literal"><span class="pre">None</span></tt> are illegal and raise a <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><tt class="xref py py-exc docutils literal"><span class="pre">SyntaxError</span></tt></a>.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,5 @@
|
||||
<div class="section" id="true">
|
||||
<tt class="descname">True</tt>
|
||||
<p>The true value of the <a class="reference internal" href="functions.html#bool" title="bool"><tt class="xref py py-class docutils literal"><span class="pre">bool</span></tt></a> type. Assignments to <tt class="docutils literal"><span class="pre">True</span></tt>
|
||||
are illegal and raise a <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><tt class="xref py py-exc docutils literal"><span class="pre">SyntaxError</span></tt></a>.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,5 @@
|
||||
<div class="section" id="__debug__">
|
||||
<tt class="descname">__debug__</tt>
|
||||
<p>This constant is true if Python was not started with an <a class="reference internal" href="../using/cmdline.html#cmdoption-O"><em class="xref std std-option">-O</em></a> option.
|
||||
See also the <a class="reference internal" href="../reference/simple_stmts.html#assert"><tt class="xref std std-keyword docutils literal"><span class="pre">assert</span></tt></a> statement.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,27 @@
|
||||
<div class="section" id="boolean-operations">
|
||||
<span id="not"></span><span id="or"></span><span id="and"></span><span id="booleans"></span><h2>Boolean operations</h2>
|
||||
<pre id="index-65">
|
||||
<strong id="grammar-token-or_test">or_test </strong> ::= <a class="reference internal" href="#grammar-token-and_test"><tt class="xref docutils literal"><span class="pre">and_test</span></tt></a> | <a class="reference internal" href="#grammar-token-or_test"><tt class="xref docutils literal"><span class="pre">or_test</span></tt></a> "or" <a class="reference internal" href="#grammar-token-and_test"><tt class="xref docutils literal"><span class="pre">and_test</span></tt></a>
|
||||
<strong id="grammar-token-and_test">and_test</strong> ::= <a class="reference internal" href="#grammar-token-not_test"><tt class="xref docutils literal"><span class="pre">not_test</span></tt></a> | <a class="reference internal" href="#grammar-token-and_test"><tt class="xref docutils literal"><span class="pre">and_test</span></tt></a> "and" <a class="reference internal" href="#grammar-token-not_test"><tt class="xref docutils literal"><span class="pre">not_test</span></tt></a>
|
||||
<strong id="grammar-token-not_test">not_test</strong> ::= <a class="reference internal" href="#grammar-token-comparison"><tt class="xref docutils literal"><span class="pre">comparison</span></tt></a> | "not" <a class="reference internal" href="#grammar-token-not_test"><tt class="xref docutils literal"><span class="pre">not_test</span></tt></a>
|
||||
</pre>
|
||||
<p>In the context of Boolean operations, and also when expressions are used by
|
||||
control flow statements, the following values are interpreted as false:
|
||||
<tt class="docutils literal"><span class="pre">False</span></tt>, <tt class="docutils literal"><span class="pre">None</span></tt>, numeric zero of all types, and empty strings and containers
|
||||
(including strings, tuples, lists, dictionaries, sets and frozensets). All
|
||||
other values are interpreted as true. User-defined objects can customize their
|
||||
truth value by providing a <a class="reference internal" href="datamodel.html#object.__bool__" title="object.__bool__"><tt class="xref py py-meth docutils literal"><span class="pre">__bool__()</span></tt></a> method.</p>
|
||||
<p id="index-66">The operator <a class="reference internal" href="#not"><tt class="xref std std-keyword docutils literal"><span class="pre">not</span></tt></a> yields <tt class="docutils literal"><span class="pre">True</span></tt> if its argument is false, <tt class="docutils literal"><span class="pre">False</span></tt>
|
||||
otherwise.</p>
|
||||
<p id="index-67">The expression <tt class="docutils literal"><span class="pre">x</span> <span class="pre">and</span> <span class="pre">y</span></tt> first evaluates <em>x</em>; if <em>x</em> is false, its value is
|
||||
returned; otherwise, <em>y</em> is evaluated and the resulting value is returned.</p>
|
||||
<p id="index-68">The expression <tt class="docutils literal"><span class="pre">x</span> <span class="pre">or</span> <span class="pre">y</span></tt> first evaluates <em>x</em>; if <em>x</em> is true, its value is
|
||||
returned; otherwise, <em>y</em> is evaluated and the resulting value is returned.</p>
|
||||
<p>(Note that neither <a class="reference internal" href="#and"><tt class="xref std std-keyword docutils literal"><span class="pre">and</span></tt></a> nor <a class="reference internal" href="#or"><tt class="xref std std-keyword docutils literal"><span class="pre">or</span></tt></a> restrict the value and type
|
||||
they return to <tt class="docutils literal"><span class="pre">False</span></tt> and <tt class="docutils literal"><span class="pre">True</span></tt>, but rather return the last evaluated
|
||||
argument. This is sometimes useful, e.g., if <tt class="docutils literal"><span class="pre">s</span></tt> is a string that should be
|
||||
replaced by a default value if it is empty, the expression <tt class="docutils literal"><span class="pre">s</span> <span class="pre">or</span> <span class="pre">'foo'</span></tt> yields
|
||||
the desired value. Because <a class="reference internal" href="#not"><tt class="xref std std-keyword docutils literal"><span class="pre">not</span></tt></a> has to create a new value, it
|
||||
returns a boolean value regardless of the type of its argument
|
||||
(for example, <tt class="docutils literal"><span class="pre">not</span> <span class="pre">'foo'</span></tt> produces <tt class="docutils literal"><span class="pre">False</span></tt> rather than <tt class="docutils literal"><span class="pre">''</span></tt>.)</p>
|
||||
</div>
|
||||
@@ -0,0 +1,96 @@
|
||||
<div class="section" id="the-import-statement">
|
||||
<span id="from"></span><span id="import"></span><h2>The <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement</h2>
|
||||
<pre id="index-31">
|
||||
<strong id="grammar-token-import_stmt">import_stmt </strong> ::= "import" <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] ( "," <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
|
||||
| "from" <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> "import" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
|
||||
( "," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
|
||||
| "from" <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> "import" "(" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
|
||||
( "," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )* [","] ")"
|
||||
| "from" <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> "import" "*"
|
||||
<strong id="grammar-token-module">module </strong> ::= (<a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ".")* <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
|
||||
<strong id="grammar-token-relative_module">relative_module</strong> ::= "."* <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> | "."+
|
||||
<strong id="grammar-token-name">name </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
|
||||
</pre>
|
||||
<p>The basic import statement (no <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> clause) is executed in two
|
||||
steps:</p>
|
||||
<ol class="arabic simple">
|
||||
<li>find a module, loading and initializing it if necessary</li>
|
||||
<li>define a name or names in the local namespace for the scope where
|
||||
the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement occurs.</li>
|
||||
</ol>
|
||||
<p>When the statement contains multiple clauses (separated by
|
||||
commas) the two steps are carried out separately for each clause, just
|
||||
as though the clauses had been separated out into individiual import
|
||||
statements.</p>
|
||||
<p>The details of the first step, finding and loading modules are described in
|
||||
greater detail in the section on the <a class="reference internal" href="import.html#importsystem"><em>import system</em></a>,
|
||||
which also describes the various types of packages and modules that can
|
||||
be imported, as well as all the hooks that can be used to customize
|
||||
the import system. Note that failures in this step may indicate either
|
||||
that the module could not be located, <em>or</em> that an error occurred while
|
||||
initializing the module, which includes execution of the module’s code.</p>
|
||||
<p>If the requested module is retrieved successfully, it will be made
|
||||
available in the local namespace in one of three ways:</p>
|
||||
<ul class="simple" id="index-32">
|
||||
<li>If the module name is followed by <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a>, then the name
|
||||
following <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> is bound directly to the imported module.</li>
|
||||
<li>If no other name is specified, and the module being imported is a top
|
||||
level module, the module’s name is bound in the local namespace as a
|
||||
reference to the imported module</li>
|
||||
<li>If the module being imported is <em>not</em> a top level module, then the name
|
||||
of the top level package that contains the module is bound in the local
|
||||
namespace as a reference to the top level package. The imported module
|
||||
must be accessed using its full qualified name rather than directly</li>
|
||||
</ul>
|
||||
<p id="index-33">The <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> form uses a slightly more complex process:</p>
|
||||
<ol class="arabic simple">
|
||||
<li>find the module specified in the <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> clause, loading and
|
||||
initializing it if necessary;</li>
|
||||
<li>for each of the identifiers specified in the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> clauses:<ol class="arabic">
|
||||
<li>check if the imported module has an attribute by that name</li>
|
||||
<li>if not, attempt to import a submodule with that name and then
|
||||
check the imported module again for that attribute</li>
|
||||
<li>if the attribute is not found, <a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><tt class="xref py py-exc docutils literal"><span class="pre">ImportError</span></tt></a> is raised.</li>
|
||||
<li>otherwise, a reference to that value is stored in the local namespace,
|
||||
using the name in the <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> clause if it is present,
|
||||
otherwise using the attribute name</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
<p>Examples:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">foo</span> <span class="c"># foo imported and bound locally</span>
|
||||
<span class="kn">import</span> <span class="nn">foo.bar.baz</span> <span class="c"># foo.bar.baz imported, foo bound locally</span>
|
||||
<span class="kn">import</span> <span class="nn">foo.bar.baz</span> <span class="k">as</span> <span class="nn">fbb</span> <span class="c"># foo.bar.baz imported and bound as fbb</span>
|
||||
<span class="kn">from</span> <span class="nn">foo.bar</span> <span class="k">import</span> <span class="n">baz</span> <span class="c"># foo.bar.baz imported and bound as baz</span>
|
||||
<span class="kn">from</span> <span class="nn">foo</span> <span class="k">import</span> <span class="n">attr</span> <span class="c"># foo imported and foo.attr bound as attr</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If the list of identifiers is replaced by a star (<tt class="docutils literal"><span class="pre">'*'</span></tt>), all public
|
||||
names defined in the module are bound in the local namespace for the scope
|
||||
where the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement occurs.</p>
|
||||
<p id="index-34">The <em>public names</em> defined by a module are determined by checking the module’s
|
||||
namespace for a variable named <tt class="docutils literal"><span class="pre">__all__</span></tt>; if defined, it must be a sequence
|
||||
of strings which are names defined or imported by that module. The names
|
||||
given in <tt class="docutils literal"><span class="pre">__all__</span></tt> are all considered public and are required to exist. If
|
||||
<tt class="docutils literal"><span class="pre">__all__</span></tt> is not defined, the set of public names includes all names found
|
||||
in the module’s namespace which do not begin with an underscore character
|
||||
(<tt class="docutils literal"><span class="pre">'_'</span></tt>). <tt class="docutils literal"><span class="pre">__all__</span></tt> should contain the entire public API. It is intended
|
||||
to avoid accidentally exporting items that are not part of the API (such as
|
||||
library modules which were imported and used within the module).</p>
|
||||
<p>The wild card form of import — <tt class="docutils literal"><span class="pre">from</span> <span class="pre">module</span> <span class="pre">import</span> <span class="pre">*</span></tt> — is only allowed at
|
||||
the module level. Attempting to use it in class or function definitions will
|
||||
raise a <a class="reference internal" href="../library/exceptions.html#SyntaxError" title="SyntaxError"><tt class="xref py py-exc docutils literal"><span class="pre">SyntaxError</span></tt></a>.</p>
|
||||
<p id="index-35">When specifying what module to import you do not have to specify the absolute
|
||||
name of the module. When a module or package is contained within another
|
||||
package it is possible to make a relative import within the same top package
|
||||
without having to mention the package name. By using leading dots in the
|
||||
specified module or package after <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> you can specify how high to
|
||||
traverse up the current package hierarchy without specifying exact names. One
|
||||
leading dot means the current package where the module making the import
|
||||
exists. Two dots means up one package level. Three dots is up two levels, etc.
|
||||
So if you execute <tt class="docutils literal"><span class="pre">from</span> <span class="pre">.</span> <span class="pre">import</span> <span class="pre">mod</span></tt> from a module in the <tt class="docutils literal"><span class="pre">pkg</span></tt> package
|
||||
then you will end up importing <tt class="docutils literal"><span class="pre">pkg.mod</span></tt>. If you execute <tt class="docutils literal"><span class="pre">from</span> <span class="pre">..subpkg2</span>
|
||||
<span class="pre">import</span> <span class="pre">mod</span></tt> from within <tt class="docutils literal"><span class="pre">pkg.subpkg1</span></tt> you will import <tt class="docutils literal"><span class="pre">pkg.subpkg2.mod</span></tt>.
|
||||
The specification for relative imports is contained within <span class="target" id="index-36"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0328"><strong>PEP 328</strong></a>.</p>
|
||||
<p><a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><tt class="xref py py-func docutils literal"><span class="pre">importlib.import_module()</span></tt></a> is provided to support applications that
|
||||
determine dynamically the modules to be loaded.</p>
|
||||
@@ -0,0 +1,28 @@
|
||||
<div class="section" id="the-assert-statement">
|
||||
<span id="assert"></span><h2>The <a class="reference internal" href="#assert"><tt class="xref std std-keyword docutils literal"><span class="pre">assert</span></tt></a> statement</h2>
|
||||
<p id="index-15">Assert statements are a convenient way to insert debugging assertions into a
|
||||
program:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-assert_stmt">assert_stmt</strong> ::= "assert" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ["," <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a>]
|
||||
</pre>
|
||||
<p>The simple form, <tt class="docutils literal"><span class="pre">assert</span> <span class="pre">expression</span></tt>, is equivalent to</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">if</span> <span class="n">__debug__</span><span class="p">:</span>
|
||||
<span class="k">if</span> <span class="ow">not</span> <span class="n">expression</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">AssertionError</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The extended form, <tt class="docutils literal"><span class="pre">assert</span> <span class="pre">expression1,</span> <span class="pre">expression2</span></tt>, is equivalent to</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">if</span> <span class="n">__debug__</span><span class="p">:</span>
|
||||
<span class="k">if</span> <span class="ow">not</span> <span class="n">expression1</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">AssertionError</span><span class="p">(</span><span class="n">expression2</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p id="index-16">These equivalences assume that <a class="reference internal" href="../library/constants.html#__debug__" title="__debug__"><tt class="xref py py-const docutils literal"><span class="pre">__debug__</span></tt></a> and <a class="reference internal" href="../library/exceptions.html#AssertionError" title="AssertionError"><tt class="xref py py-exc docutils literal"><span class="pre">AssertionError</span></tt></a> refer to
|
||||
the built-in variables with those names. In the current implementation, the
|
||||
built-in variable <a class="reference internal" href="../library/constants.html#__debug__" title="__debug__"><tt class="xref py py-const docutils literal"><span class="pre">__debug__</span></tt></a> is <tt class="docutils literal"><span class="pre">True</span></tt> under normal circumstances,
|
||||
<tt class="docutils literal"><span class="pre">False</span></tt> when optimization is requested (command line option -O). The current
|
||||
code generator emits no code for an assert statement when optimization is
|
||||
requested at compile time. Note that it is unnecessary to include the source
|
||||
code for the expression that failed in the error message; it will be displayed
|
||||
as part of the stack trace.</p>
|
||||
<p>Assignments to <a class="reference internal" href="../library/constants.html#__debug__" title="__debug__"><tt class="xref py py-const docutils literal"><span class="pre">__debug__</span></tt></a> are illegal. The value for the built-in variable
|
||||
is determined when the interpreter starts.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,16 @@
|
||||
<div class="section" id="the-break-statement">
|
||||
<span id="break"></span><h2>The <a class="reference internal" href="#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a> statement</h2>
|
||||
<pre id="index-27">
|
||||
<strong id="grammar-token-break_stmt">break_stmt</strong> ::= "break"
|
||||
</pre>
|
||||
<p><a class="reference internal" href="#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a> may only occur syntactically nested in a <a class="reference internal" href="compound_stmts.html#for"><tt class="xref std std-keyword docutils literal"><span class="pre">for</span></tt></a> or
|
||||
<a class="reference internal" href="compound_stmts.html#while"><tt class="xref std std-keyword docutils literal"><span class="pre">while</span></tt></a> loop, but not nested in a function or class definition within
|
||||
that loop.</p>
|
||||
<p id="index-28">It terminates the nearest enclosing loop, skipping the optional <a class="reference internal" href="compound_stmts.html#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a>
|
||||
clause if the loop has one.</p>
|
||||
<p>If a <a class="reference internal" href="compound_stmts.html#for"><tt class="xref std std-keyword docutils literal"><span class="pre">for</span></tt></a> loop is terminated by <a class="reference internal" href="#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a>, the loop control
|
||||
target keeps its current value.</p>
|
||||
<p id="index-29">When <a class="reference internal" href="#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a> passes control out of a <a class="reference internal" href="compound_stmts.html#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement with a
|
||||
<a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause, that <a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause is executed before
|
||||
really leaving the loop.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,93 @@
|
||||
<div class="section" id="class-definitions">
|
||||
<span id="class"></span><h2>Class definitions</h2>
|
||||
<p id="index-26">A class definition defines a class object (see section <a class="reference internal" href="datamodel.html#types"><em>The standard type hierarchy</em></a>):</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-classdef">classdef </strong> ::= [<a class="reference internal" href="#grammar-token-decorators"><tt class="xref docutils literal"><span class="pre">decorators</span></tt></a>] "class" <a class="reference internal" href="#grammar-token-classname"><tt class="xref docutils literal"><span class="pre">classname</span></tt></a> [<a class="reference internal" href="#grammar-token-inheritance"><tt class="xref docutils literal"><span class="pre">inheritance</span></tt></a>] ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
<strong id="grammar-token-inheritance">inheritance</strong> ::= "(" [<a class="reference internal" href="#grammar-token-parameter_list"><tt class="xref docutils literal"><span class="pre">parameter_list</span></tt></a>] ")"
|
||||
<strong id="grammar-token-classname">classname </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
|
||||
</pre>
|
||||
<p>A class definition is an executable statement. The inheritance list usually
|
||||
gives a list of base classes (see <a class="reference internal" href="datamodel.html#metaclasses"><em>Customizing class creation</em></a> for more advanced uses), so
|
||||
each item in the list should evaluate to a class object which allows
|
||||
subclassing. Classes without an inheritance list inherit, by default, from the
|
||||
base class <a class="reference internal" href="../library/functions.html#object" title="object"><tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></a>; hence,</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span><span class="p">:</span>
|
||||
<span class="k">pass</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>is equivalent to</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
|
||||
<span class="k">pass</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The class’s suite is then executed in a new execution frame (see <a class="reference internal" href="executionmodel.html#naming"><em>Naming and binding</em></a>),
|
||||
using a newly created local namespace and the original global namespace.
|
||||
(Usually, the suite contains mostly function definitions.) When the class’s
|
||||
suite finishes execution, its execution frame is discarded but its local
|
||||
namespace is saved. <a class="footnote-reference" href="#id8" id="id4">[4]</a> A class object is then created using the inheritance
|
||||
list for the base classes and the saved local namespace for the attribute
|
||||
dictionary. The class name is bound to this class object in the original local
|
||||
namespace.</p>
|
||||
<p>Class creation can be customized heavily using <a class="reference internal" href="datamodel.html#metaclasses"><em>metaclasses</em></a>.</p>
|
||||
<p>Classes can also be decorated: just like when decorating functions,</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="nd">@f1</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>
|
||||
<span class="nd">@f2</span>
|
||||
<span class="k">class</span> <span class="nc">Foo</span><span class="p">:</span> <span class="k">pass</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>is equivalent to</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span><span class="p">:</span> <span class="k">pass</span>
|
||||
<span class="n">Foo</span> <span class="o">=</span> <span class="n">f1</span><span class="p">(</span><span class="n">arg</span><span class="p">)(</span><span class="n">f2</span><span class="p">(</span><span class="n">Foo</span><span class="p">))</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The evaluation rules for the decorator expressions are the same as for function
|
||||
decorators. The result must be a class object, which is then bound to the class
|
||||
name.</p>
|
||||
<p><strong>Programmer’s note:</strong> Variables defined in the class definition are class
|
||||
attributes; they are shared by instances. Instance attributes can be set in a
|
||||
method with <tt class="docutils literal"><span class="pre">self.name</span> <span class="pre">=</span> <span class="pre">value</span></tt>. Both class and instance attributes are
|
||||
accessible through the notation “<tt class="docutils literal"><span class="pre">self.name</span></tt>”, and an instance attribute hides
|
||||
a class attribute with the same name when accessed in this way. Class
|
||||
attributes can be used as defaults for instance attributes, but using mutable
|
||||
values there can lead to unexpected results. <a class="reference internal" href="datamodel.html#descriptors"><em>Descriptors</em></a>
|
||||
can be used to create instance variables with different implementation details.</p>
|
||||
<div class="admonition seealso">
|
||||
<p class="first admonition-title">See also</p>
|
||||
<p class="last"><span class="target" id="index-27"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-3115"><strong>PEP 3115</strong></a> - Metaclasses in Python 3
|
||||
<span class="target" id="index-28"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-3129"><strong>PEP 3129</strong></a> - Class Decorators</p>
|
||||
</div>
|
||||
<p class="rubric">Footnotes</p>
|
||||
<table class="docutils footnote" frame="void" id="id5" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>The exception is propagated to the invocation stack unless
|
||||
there is a <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause which happens to raise another
|
||||
exception. That new exception causes the old one to be lost.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table class="docutils footnote" frame="void" id="id6" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Currently, control “flows off the end” except in the case of an exception
|
||||
or the execution of a <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a>, <a class="reference internal" href="simple_stmts.html#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a>, or
|
||||
<a class="reference internal" href="simple_stmts.html#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a> statement.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table class="docutils footnote" frame="void" id="id7" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>A string literal appearing as the first statement in the function body is
|
||||
transformed into the function’s <tt class="docutils literal"><span class="pre">__doc__</span></tt> attribute and therefore the
|
||||
function’s <a class="reference internal" href="../glossary.html#term-docstring"><em class="xref std std-term">docstring</em></a>.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table class="docutils footnote" frame="void" id="id8" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td>A string literal appearing as the first statement in the class body is
|
||||
transformed into the namespace’s <tt class="docutils literal"><span class="pre">__doc__</span></tt> item and therefore the class’s
|
||||
<a class="reference internal" href="../glossary.html#term-docstring"><em class="xref std std-term">docstring</em></a>.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
@@ -0,0 +1,13 @@
|
||||
<div class="section" id="the-continue-statement">
|
||||
<span id="continue"></span><h2>The <a class="reference internal" href="#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a> statement</h2>
|
||||
<pre id="index-30">
|
||||
<strong id="grammar-token-continue_stmt">continue_stmt</strong> ::= "continue"
|
||||
</pre>
|
||||
<p><a class="reference internal" href="#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a> may only occur syntactically nested in a <a class="reference internal" href="compound_stmts.html#for"><tt class="xref std std-keyword docutils literal"><span class="pre">for</span></tt></a> or
|
||||
<a class="reference internal" href="compound_stmts.html#while"><tt class="xref std std-keyword docutils literal"><span class="pre">while</span></tt></a> loop, but not nested in a function or class definition or
|
||||
<a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause within that loop. It continues with the next
|
||||
cycle of the nearest enclosing loop.</p>
|
||||
<p>When <a class="reference internal" href="#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a> passes control out of a <a class="reference internal" href="compound_stmts.html#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement with a
|
||||
<a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause, that <a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause is executed before
|
||||
really starting the next loop cycle.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,102 @@
|
||||
<div class="section" id="function-definitions">
|
||||
<span id="def"></span><span id="function"></span><span id="index-18"></span><h2>Function definitions</h2>
|
||||
<p id="index-19">A function definition defines a user-defined function object (see section
|
||||
<a class="reference internal" href="datamodel.html#types"><em>The standard type hierarchy</em></a>):</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-funcdef">funcdef </strong> ::= [<a class="reference internal" href="#grammar-token-decorators"><tt class="xref docutils literal"><span class="pre">decorators</span></tt></a>] "def" <a class="reference internal" href="#grammar-token-funcname"><tt class="xref docutils literal"><span class="pre">funcname</span></tt></a> "(" [<a class="reference internal" href="#grammar-token-parameter_list"><tt class="xref docutils literal"><span class="pre">parameter_list</span></tt></a>] ")" ["->" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a>] ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
<strong id="grammar-token-decorators">decorators </strong> ::= <a class="reference internal" href="#grammar-token-decorator"><tt class="xref docutils literal"><span class="pre">decorator</span></tt></a>+
|
||||
<strong id="grammar-token-decorator">decorator </strong> ::= "@" <a class="reference internal" href="#grammar-token-dotted_name"><tt class="xref docutils literal"><span class="pre">dotted_name</span></tt></a> ["(" [<a class="reference internal" href="#grammar-token-parameter_list"><tt class="xref docutils literal"><span class="pre">parameter_list</span></tt></a> [","]] ")"] NEWLINE
|
||||
<strong id="grammar-token-dotted_name">dotted_name </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ("." <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>)*
|
||||
<strong id="grammar-token-parameter_list">parameter_list</strong> ::= (<a class="reference internal" href="#grammar-token-defparameter"><tt class="xref docutils literal"><span class="pre">defparameter</span></tt></a> ",")*
|
||||
| "*" [<a class="reference internal" href="#grammar-token-parameter"><tt class="xref docutils literal"><span class="pre">parameter</span></tt></a>] ("," <a class="reference internal" href="#grammar-token-defparameter"><tt class="xref docutils literal"><span class="pre">defparameter</span></tt></a>)* ["," "**" <a class="reference internal" href="#grammar-token-parameter"><tt class="xref docutils literal"><span class="pre">parameter</span></tt></a>]
|
||||
| "**" <a class="reference internal" href="#grammar-token-parameter"><tt class="xref docutils literal"><span class="pre">parameter</span></tt></a>
|
||||
| <a class="reference internal" href="#grammar-token-defparameter"><tt class="xref docutils literal"><span class="pre">defparameter</span></tt></a> [","] )
|
||||
<strong id="grammar-token-parameter">parameter </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> [":" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a>]
|
||||
<strong id="grammar-token-defparameter">defparameter </strong> ::= <a class="reference internal" href="#grammar-token-parameter"><tt class="xref docutils literal"><span class="pre">parameter</span></tt></a> ["=" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a>]
|
||||
<strong id="grammar-token-funcname">funcname </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
|
||||
</pre>
|
||||
<p>A function definition is an executable statement. Its execution binds the
|
||||
function name in the current local namespace to a function object (a wrapper
|
||||
around the executable code for the function). This function object contains a
|
||||
reference to the current global namespace as the global namespace to be used
|
||||
when the function is called.</p>
|
||||
<p>The function definition does not execute the function body; this gets executed
|
||||
only when the function is called. <a class="footnote-reference" href="#id7" id="id3">[3]</a></p>
|
||||
<p id="index-20">A function definition may be wrapped by one or more <a class="reference internal" href="../glossary.html#term-decorator"><em class="xref std std-term">decorator</em></a> expressions.
|
||||
Decorator expressions are evaluated when the function is defined, in the scope
|
||||
that contains the function definition. The result must be a callable, which is
|
||||
invoked with the function object as the only argument. The returned value is
|
||||
bound to the function name instead of the function object. Multiple decorators
|
||||
are applied in nested fashion. For example, the following code</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="nd">@f1</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>
|
||||
<span class="nd">@f2</span>
|
||||
<span class="k">def</span> <span class="nf">func</span><span class="p">():</span> <span class="k">pass</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>is equivalent to</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">def</span> <span class="nf">func</span><span class="p">():</span> <span class="k">pass</span>
|
||||
<span class="n">func</span> <span class="o">=</span> <span class="n">f1</span><span class="p">(</span><span class="n">arg</span><span class="p">)(</span><span class="n">f2</span><span class="p">(</span><span class="n">func</span><span class="p">))</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p id="index-21">When one or more <a class="reference internal" href="../glossary.html#term-parameter"><em class="xref std std-term">parameters</em></a> have the form <em>parameter</em> <tt class="docutils literal"><span class="pre">=</span></tt>
|
||||
<em>expression</em>, the function is said to have “default parameter values.” For a
|
||||
parameter with a default value, the corresponding <a class="reference internal" href="../glossary.html#term-argument"><em class="xref std std-term">argument</em></a> may be
|
||||
omitted from a call, in which
|
||||
case the parameter’s default value is substituted. If a parameter has a default
|
||||
value, all following parameters up until the “<tt class="docutils literal"><span class="pre">*</span></tt>” must also have a default
|
||||
value — this is a syntactic restriction that is not expressed by the grammar.</p>
|
||||
<p><strong>Default parameter values are evaluated from left to right when the function
|
||||
definition is executed.</strong> This means that the expression is evaluated once, when
|
||||
the function is defined, and that the same “pre-computed” value is used for each
|
||||
call. This is especially important to understand when a default parameter is a
|
||||
mutable object, such as a list or a dictionary: if the function modifies the
|
||||
object (e.g. by appending an item to a list), the default value is in effect
|
||||
modified. This is generally not what was intended. A way around this is to use
|
||||
<tt class="docutils literal"><span class="pre">None</span></tt> as the default, and explicitly test for it in the body of the function,
|
||||
e.g.:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">def</span> <span class="nf">whats_on_the_telly</span><span class="p">(</span><span class="n">penguin</span><span class="o">=</span><span class="k">None</span><span class="p">):</span>
|
||||
<span class="k">if</span> <span class="n">penguin</span> <span class="ow">is</span> <span class="k">None</span><span class="p">:</span>
|
||||
<span class="n">penguin</span> <span class="o">=</span> <span class="p">[]</span>
|
||||
<span class="n">penguin</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">"property of the zoo"</span><span class="p">)</span>
|
||||
<span class="k">return</span> <span class="n">penguin</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p id="index-22">Function call semantics are described in more detail in section <a class="reference internal" href="expressions.html#calls"><em>Calls</em></a>. A
|
||||
function call always assigns values to all parameters mentioned in the parameter
|
||||
list, either from position arguments, from keyword arguments, or from default
|
||||
values. If the form “<tt class="docutils literal"><span class="pre">*identifier</span></tt>” is present, it is initialized to a tuple
|
||||
receiving any excess positional parameters, defaulting to the empty tuple. If
|
||||
the form “<tt class="docutils literal"><span class="pre">**identifier</span></tt>” is present, it is initialized to a new dictionary
|
||||
receiving any excess keyword arguments, defaulting to a new empty dictionary.
|
||||
Parameters after “<tt class="docutils literal"><span class="pre">*</span></tt>” or “<tt class="docutils literal"><span class="pre">*identifier</span></tt>” are keyword-only parameters and
|
||||
may only be passed used keyword arguments.</p>
|
||||
<p id="index-23">Parameters may have annotations of the form “<tt class="docutils literal"><span class="pre">:</span> <span class="pre">expression</span></tt>” following the
|
||||
parameter name. Any parameter may have an annotation even those of the form
|
||||
<tt class="docutils literal"><span class="pre">*identifier</span></tt> or <tt class="docutils literal"><span class="pre">**identifier</span></tt>. Functions may have “return” annotation of
|
||||
the form “<tt class="docutils literal"><span class="pre">-></span> <span class="pre">expression</span></tt>” after the parameter list. These annotations can be
|
||||
any valid Python expression and are evaluated when the function definition is
|
||||
executed. Annotations may be evaluated in a different order than they appear in
|
||||
the source code. The presence of annotations does not change the semantics of a
|
||||
function. The annotation values are available as values of a dictionary keyed
|
||||
by the parameters’ names in the <tt class="xref py py-attr docutils literal"><span class="pre">__annotations__</span></tt> attribute of the
|
||||
function object.</p>
|
||||
<p id="index-24">It is also possible to create anonymous functions (functions not bound to a
|
||||
name), for immediate use in expressions. This uses lambda expressions, described in
|
||||
section <a class="reference internal" href="expressions.html#lambda"><em>Lambdas</em></a>. Note that the lambda expression is merely a shorthand for a
|
||||
simplified function definition; a function defined in a “<a class="reference internal" href="#def"><tt class="xref std std-keyword docutils literal"><span class="pre">def</span></tt></a>”
|
||||
statement can be passed around or assigned to another name just like a function
|
||||
defined by a lambda expression. The “<a class="reference internal" href="#def"><tt class="xref std std-keyword docutils literal"><span class="pre">def</span></tt></a>” form is actually more powerful
|
||||
since it allows the execution of multiple statements and annotations.</p>
|
||||
<p><strong>Programmer’s note:</strong> Functions are first-class objects. A “<tt class="docutils literal"><span class="pre">def</span></tt>” statement
|
||||
executed inside a function definition defines a local function that can be
|
||||
returned or passed around. Free variables used in the nested function can
|
||||
access the local variables of the function containing the def. See section
|
||||
<a class="reference internal" href="executionmodel.html#naming"><em>Naming and binding</em></a> for details.</p>
|
||||
<div class="admonition seealso">
|
||||
<p class="first admonition-title">See also</p>
|
||||
<dl class="last docutils">
|
||||
<dt><span class="target" id="index-25"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-3107"><strong>PEP 3107</strong></a> - Function Annotations</dt>
|
||||
<dd>The original specification for function annotations.</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
@@ -0,0 +1,21 @@
|
||||
<div class="section" id="the-del-statement">
|
||||
<span id="del"></span><h2>The <a class="reference internal" href="#del"><tt class="xref std std-keyword docutils literal"><span class="pre">del</span></tt></a> statement</h2>
|
||||
<pre id="index-18">
|
||||
<strong id="grammar-token-del_stmt">del_stmt</strong> ::= "del" <a class="reference internal" href="#grammar-token-target_list"><tt class="xref docutils literal"><span class="pre">target_list</span></tt></a>
|
||||
</pre>
|
||||
<p>Deletion is recursively defined very similar to the way assignment is defined.
|
||||
Rather than spelling it out in full details, here are some hints.</p>
|
||||
<p>Deletion of a target list recursively deletes each target, from left to right.</p>
|
||||
<p id="index-19">Deletion of a name removes the binding of that name from the local or global
|
||||
namespace, depending on whether the name occurs in a <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statement
|
||||
in the same code block. If the name is unbound, a <a class="reference internal" href="../library/exceptions.html#NameError" title="NameError"><tt class="xref py py-exc docutils literal"><span class="pre">NameError</span></tt></a> exception
|
||||
will be raised.</p>
|
||||
<p id="index-20">Deletion of attribute references, subscriptions and slicings is passed to the
|
||||
primary object involved; deletion of a slicing is in general equivalent to
|
||||
assignment of an empty slice of the right type (but even this is determined by
|
||||
the sliced object).</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified">Changed in version 3.2: </span>Previously it was illegal to delete a name from the local namespace if it
|
||||
occurs as a free variable in a nested block.</p>
|
||||
</div>
|
||||
</div>
|
||||
@@ -0,0 +1,14 @@
|
||||
<div class="section" id="the-if-statement">
|
||||
<span id="else"></span><span id="elif"></span><span id="if"></span><h2>The <a class="reference internal" href="#if"><tt class="xref std std-keyword docutils literal"><span class="pre">if</span></tt></a> statement</h2>
|
||||
<p id="index-3">The <a class="reference internal" href="#if"><tt class="xref std std-keyword docutils literal"><span class="pre">if</span></tt></a> statement is used for conditional execution:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-if_stmt">if_stmt</strong> ::= "if" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
( "elif" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a> )*
|
||||
["else" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
</pre>
|
||||
<p>It selects exactly one of the suites by evaluating the expressions one by one
|
||||
until one is found to be true (see section <a class="reference internal" href="expressions.html#booleans"><em>Boolean operations</em></a> for the definition of
|
||||
true and false); then that suite is executed (and no other part of the
|
||||
<a class="reference internal" href="#if"><tt class="xref std std-keyword docutils literal"><span class="pre">if</span></tt></a> statement is executed or evaluated). If all expressions are
|
||||
false, the suite of the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause, if present, is executed.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,14 @@
|
||||
<div class="section" id="the-if-statement">
|
||||
<span id="else"></span><span id="elif"></span><span id="if"></span><h2>The <a class="reference internal" href="#if"><tt class="xref std std-keyword docutils literal"><span class="pre">if</span></tt></a> statement</h2>
|
||||
<p id="index-3">The <a class="reference internal" href="#if"><tt class="xref std std-keyword docutils literal"><span class="pre">if</span></tt></a> statement is used for conditional execution:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-if_stmt">if_stmt</strong> ::= "if" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
( "elif" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a> )*
|
||||
["else" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
</pre>
|
||||
<p>It selects exactly one of the suites by evaluating the expressions one by one
|
||||
until one is found to be true (see section <a class="reference internal" href="expressions.html#booleans"><em>Boolean operations</em></a> for the definition of
|
||||
true and false); then that suite is executed (and no other part of the
|
||||
<a class="reference internal" href="#if"><tt class="xref std std-keyword docutils literal"><span class="pre">if</span></tt></a> statement is executed or evaluated). If all expressions are
|
||||
false, the suite of the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause, if present, is executed.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,109 @@
|
||||
<div class="section" id="the-try-statement">
|
||||
<span id="finally"></span><span id="except"></span><span id="try"></span><h2>The <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement</h2>
|
||||
<span class="target" id="index-10"></span><p id="index-11">The <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement specifies exception handlers and/or cleanup code
|
||||
for a group of statements:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-try_stmt">try_stmt </strong> ::= try1_stmt | try2_stmt
|
||||
<strong id="grammar-token-try1_stmt">try1_stmt</strong> ::= "try" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
("except" [<a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>]] ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>)+
|
||||
["else" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
["finally" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
<strong id="grammar-token-try2_stmt">try2_stmt</strong> ::= "try" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
"finally" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
</pre>
|
||||
<p>The <a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a> clause(s) specify one or more exception handlers. When no
|
||||
exception occurs in the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> clause, no exception handler is executed.
|
||||
When an exception occurs in the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> suite, a search for an exception
|
||||
handler is started. This search inspects the except clauses in turn until one
|
||||
is found that matches the exception. An expression-less except clause, if
|
||||
present, must be last; it matches any exception. For an except clause with an
|
||||
expression, that expression is evaluated, and the clause matches the exception
|
||||
if the resulting object is “compatible” with the exception. An object is
|
||||
compatible with an exception if it is the class or a base class of the exception
|
||||
object or a tuple containing an item compatible with the exception.</p>
|
||||
<p>If no except clause matches the exception, the search for an exception handler
|
||||
continues in the surrounding code and on the invocation stack. <a class="footnote-reference" href="#id5" id="id1">[1]</a></p>
|
||||
<p>If the evaluation of an expression in the header of an except clause raises an
|
||||
exception, the original search for a handler is canceled and a search starts for
|
||||
the new exception in the surrounding code and on the call stack (it is treated
|
||||
as if the entire <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement raised the exception).</p>
|
||||
<p>When a matching except clause is found, the exception is assigned to the target
|
||||
specified after the <a class="reference internal" href="#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> keyword in that except clause, if present, and
|
||||
the except clause’s suite is executed. All except clauses must have an
|
||||
executable block. When the end of this block is reached, execution continues
|
||||
normally after the entire try statement. (This means that if two nested
|
||||
handlers exist for the same exception, and the exception occurs in the try
|
||||
clause of the inner handler, the outer handler will not handle the exception.)</p>
|
||||
<p>When an exception has been assigned using <tt class="docutils literal"><span class="pre">as</span> <span class="pre">target</span></tt>, it is cleared at the
|
||||
end of the except clause. This is as if</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">except</span> <span class="n">E</span> <span class="k">as</span> <span class="n">N</span><span class="p">:</span>
|
||||
<span class="n">foo</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>was translated to</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">except</span> <span class="n">E</span> <span class="k">as</span> <span class="n">N</span><span class="p">:</span>
|
||||
<span class="k">try</span><span class="p">:</span>
|
||||
<span class="n">foo</span>
|
||||
<span class="k">finally</span><span class="p">:</span>
|
||||
<span class="k">del</span> <span class="n">N</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This means the exception must be assigned to a different name to be able to
|
||||
refer to it after the except clause. Exceptions are cleared because with the
|
||||
traceback attached to them, they form a reference cycle with the stack frame,
|
||||
keeping all locals in that frame alive until the next garbage collection occurs.</p>
|
||||
<p id="index-12">Before an except clause’s suite is executed, details about the exception are
|
||||
stored in the <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><tt class="xref py py-mod docutils literal"><span class="pre">sys</span></tt></a> module and can be accessed via <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><tt class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></tt></a>.
|
||||
<a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><tt class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></tt></a> returns a 3-tuple consisting of the exception class, the
|
||||
exception instance and a traceback object (see section <a class="reference internal" href="datamodel.html#types"><em>The standard type hierarchy</em></a>) identifying
|
||||
the point in the program where the exception occurred. <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><tt class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></tt></a>
|
||||
values are restored to their previous values (before the call) when returning
|
||||
from a function that handled an exception.</p>
|
||||
<p id="index-13">The optional <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause is executed if and when control flows off
|
||||
the end of the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> clause. <a class="footnote-reference" href="#id6" id="id2">[2]</a> Exceptions in the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a>
|
||||
clause are not handled by the preceding <a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a> clauses.</p>
|
||||
<p id="index-14">If <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> is present, it specifies a ‘cleanup’ handler. The
|
||||
<a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> clause is executed, including any <a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a> and
|
||||
<a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clauses. If an exception occurs in any of the clauses and is
|
||||
not handled, the exception is temporarily saved. The <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause
|
||||
is executed. If there is a saved exception it is re-raised at the end of the
|
||||
<a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause. If the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause raises another
|
||||
exception, the saved exception is set as the context of the new exception.
|
||||
If the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause executes a <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> or <a class="reference internal" href="simple_stmts.html#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a>
|
||||
statement, the saved exception is discarded:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
|
||||
<span class="gp">... </span> <span class="k">try</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="mi">1</span><span class="o">/</span><span class="mi">0</span>
|
||||
<span class="gp">... </span> <span class="k">finally</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">return</span> <span class="mi">42</span>
|
||||
<span class="gp">...</span>
|
||||
<span class="gp">>>> </span><span class="n">f</span><span class="p">()</span>
|
||||
<span class="go">42</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The exception information is not available to the program during execution of
|
||||
the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause.</p>
|
||||
<p id="index-15">When a <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a>, <a class="reference internal" href="simple_stmts.html#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a> or <a class="reference internal" href="simple_stmts.html#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a> statement is
|
||||
executed in the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> suite of a <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a>...<a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a>
|
||||
statement, the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause is also executed ‘on the way out.’ A
|
||||
<a class="reference internal" href="simple_stmts.html#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a> statement is illegal in the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause. (The
|
||||
reason is a problem with the current implementation — this restriction may be
|
||||
lifted in the future).</p>
|
||||
<p>The return value of a function is determined by the last <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a>
|
||||
statement executed. Since the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause always executes, a
|
||||
<a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> statement executed in the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause will
|
||||
always be the last one executed:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">foo</span><span class="p">():</span>
|
||||
<span class="gp">... </span> <span class="k">try</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">return</span> <span class="s">'try'</span>
|
||||
<span class="gp">... </span> <span class="k">finally</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">return</span> <span class="s">'finally'</span>
|
||||
<span class="gp">...</span>
|
||||
<span class="gp">>>> </span><span class="n">foo</span><span class="p">()</span>
|
||||
<span class="go">'finally'</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Additional information on exceptions can be found in section <a class="reference internal" href="executionmodel.html#exceptions"><em>Exceptions</em></a>,
|
||||
and information on using the <a class="reference internal" href="simple_stmts.html#raise"><tt class="xref std std-keyword docutils literal"><span class="pre">raise</span></tt></a> statement to generate exceptions
|
||||
may be found in section <a class="reference internal" href="simple_stmts.html#raise"><em>The raise statement</em></a>.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,43 @@
|
||||
<div class="section" id="the-exec-statement">
|
||||
<span id="exec"></span><h2>The <a class="reference internal" href="#exec"><tt class="xref docutils literal"><span class="pre">exec</span></tt></a> statement</h2>
|
||||
<pre id="index-1068">
|
||||
<strong id="grammar-token-exec_stmt">exec_stmt</strong> ::= "exec" <a class="reference external" href="expressions.html#grammar-token-or_expr"><tt class="xref docutils literal"><span class="pre">or_expr</span></tt></a> ["in" <a class="reference external" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ["," <a class="reference external" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a>]]
|
||||
</pre>
|
||||
<p>This statement supports dynamic execution of Python code. The first expression
|
||||
should evaluate to either a string, an open file object, or a code object. If
|
||||
it is a string, the string is parsed as a suite of Python statements which is
|
||||
then executed (unless a syntax error occurs). <a class="footnote-reference" href="#id3" id="id2">[1]</a> If it is an open file, the file
|
||||
is parsed until EOF and executed. If it is a code object, it is simply
|
||||
executed. In all cases, the code that’s executed is expected to be valid as
|
||||
file input (see section <a class="reference external" href="toplevel_components.html#file-input"><em>File input</em></a>). Be aware that the
|
||||
<a class="reference internal" href="#return"><tt class="xref docutils literal"><span class="pre">return</span></tt></a> and <a class="reference internal" href="#yield"><tt class="xref docutils literal"><span class="pre">yield</span></tt></a> statements may not be used outside of
|
||||
function definitions even within the context of code passed to the
|
||||
<a class="reference internal" href="#exec"><tt class="xref docutils literal"><span class="pre">exec</span></tt></a> statement.</p>
|
||||
<p>In all cases, if the optional parts are omitted, the code is executed in the
|
||||
current scope. If only the first expression after <a class="reference external" href="expressions.html#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a> is specified,
|
||||
it should be a dictionary, which will be used for both the global and the local
|
||||
variables. If two expressions are given, they are used for the global and local
|
||||
variables, respectively. If provided, <em>locals</em> can be any mapping object.</p>
|
||||
<p class="versionchanged">
|
||||
<span class="versionmodified">Changed in version 2.4: </span>Formerly, <em>locals</em> was required to be a dictionary.</p>
|
||||
<p id="index-1069">As a side effect, an implementation may insert additional keys into the
|
||||
dictionaries given besides those corresponding to variable names set by the
|
||||
executed code. For example, the current implementation may add a reference to
|
||||
the dictionary of the built-in module <a title="The module that provides the built-in namespace." class="reference external" href="../library/__builtin__.html#module-__builtin__"><tt class="xref docutils literal"><span class="pre">__builtin__</span></tt></a> under the key
|
||||
<tt class="docutils literal"><span class="pre">__builtins__</span></tt> (!).</p>
|
||||
<p id="index-1070"><strong>Programmer’s hints:</strong> dynamic evaluation of expressions is supported by the
|
||||
built-in function <a title="eval" class="reference external" href="../library/functions.html#eval"><tt class="xref docutils literal"><span class="pre">eval()</span></tt></a>. The built-in functions <a title="globals" class="reference external" href="../library/functions.html#globals"><tt class="xref docutils literal"><span class="pre">globals()</span></tt></a> and
|
||||
<a title="locals" class="reference external" href="../library/functions.html#locals"><tt class="xref docutils literal"><span class="pre">locals()</span></tt></a> return the current global and local dictionary, respectively,
|
||||
which may be useful to pass around for use by <a class="reference internal" href="#exec"><tt class="xref docutils literal"><span class="pre">exec</span></tt></a>.</p>
|
||||
<p class="rubric">Footnotes</p>
|
||||
<table class="docutils footnote" frame="void" id="id3" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>Note that the parser only accepts the Unix-style end of line convention.
|
||||
If you are reading the code from a file, make sure to use universal
|
||||
newline mode to convert Windows or Mac-style newlines.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
<div class="section" id="the-try-statement">
|
||||
<span id="finally"></span><span id="except"></span><span id="try"></span><h2>The <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement</h2>
|
||||
<span class="target" id="index-10"></span><p id="index-11">The <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement specifies exception handlers and/or cleanup code
|
||||
for a group of statements:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-try_stmt">try_stmt </strong> ::= try1_stmt | try2_stmt
|
||||
<strong id="grammar-token-try1_stmt">try1_stmt</strong> ::= "try" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
("except" [<a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>]] ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>)+
|
||||
["else" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
["finally" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
<strong id="grammar-token-try2_stmt">try2_stmt</strong> ::= "try" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
"finally" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
</pre>
|
||||
<p>The <a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a> clause(s) specify one or more exception handlers. When no
|
||||
exception occurs in the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> clause, no exception handler is executed.
|
||||
When an exception occurs in the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> suite, a search for an exception
|
||||
handler is started. This search inspects the except clauses in turn until one
|
||||
is found that matches the exception. An expression-less except clause, if
|
||||
present, must be last; it matches any exception. For an except clause with an
|
||||
expression, that expression is evaluated, and the clause matches the exception
|
||||
if the resulting object is “compatible” with the exception. An object is
|
||||
compatible with an exception if it is the class or a base class of the exception
|
||||
object or a tuple containing an item compatible with the exception.</p>
|
||||
<p>If no except clause matches the exception, the search for an exception handler
|
||||
continues in the surrounding code and on the invocation stack. <a class="footnote-reference" href="#id5" id="id1">[1]</a></p>
|
||||
<p>If the evaluation of an expression in the header of an except clause raises an
|
||||
exception, the original search for a handler is canceled and a search starts for
|
||||
the new exception in the surrounding code and on the call stack (it is treated
|
||||
as if the entire <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement raised the exception).</p>
|
||||
<p>When a matching except clause is found, the exception is assigned to the target
|
||||
specified after the <a class="reference internal" href="#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> keyword in that except clause, if present, and
|
||||
the except clause’s suite is executed. All except clauses must have an
|
||||
executable block. When the end of this block is reached, execution continues
|
||||
normally after the entire try statement. (This means that if two nested
|
||||
handlers exist for the same exception, and the exception occurs in the try
|
||||
clause of the inner handler, the outer handler will not handle the exception.)</p>
|
||||
<p>When an exception has been assigned using <tt class="docutils literal"><span class="pre">as</span> <span class="pre">target</span></tt>, it is cleared at the
|
||||
end of the except clause. This is as if</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">except</span> <span class="n">E</span> <span class="k">as</span> <span class="n">N</span><span class="p">:</span>
|
||||
<span class="n">foo</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>was translated to</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">except</span> <span class="n">E</span> <span class="k">as</span> <span class="n">N</span><span class="p">:</span>
|
||||
<span class="k">try</span><span class="p">:</span>
|
||||
<span class="n">foo</span>
|
||||
<span class="k">finally</span><span class="p">:</span>
|
||||
<span class="k">del</span> <span class="n">N</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This means the exception must be assigned to a different name to be able to
|
||||
refer to it after the except clause. Exceptions are cleared because with the
|
||||
traceback attached to them, they form a reference cycle with the stack frame,
|
||||
keeping all locals in that frame alive until the next garbage collection occurs.</p>
|
||||
<p id="index-12">Before an except clause’s suite is executed, details about the exception are
|
||||
stored in the <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><tt class="xref py py-mod docutils literal"><span class="pre">sys</span></tt></a> module and can be accessed via <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><tt class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></tt></a>.
|
||||
<a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><tt class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></tt></a> returns a 3-tuple consisting of the exception class, the
|
||||
exception instance and a traceback object (see section <a class="reference internal" href="datamodel.html#types"><em>The standard type hierarchy</em></a>) identifying
|
||||
the point in the program where the exception occurred. <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><tt class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></tt></a>
|
||||
values are restored to their previous values (before the call) when returning
|
||||
from a function that handled an exception.</p>
|
||||
<p id="index-13">The optional <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause is executed if and when control flows off
|
||||
the end of the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> clause. <a class="footnote-reference" href="#id6" id="id2">[2]</a> Exceptions in the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a>
|
||||
clause are not handled by the preceding <a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a> clauses.</p>
|
||||
<p id="index-14">If <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> is present, it specifies a ‘cleanup’ handler. The
|
||||
<a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> clause is executed, including any <a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a> and
|
||||
<a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clauses. If an exception occurs in any of the clauses and is
|
||||
not handled, the exception is temporarily saved. The <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause
|
||||
is executed. If there is a saved exception it is re-raised at the end of the
|
||||
<a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause. If the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause raises another
|
||||
exception, the saved exception is set as the context of the new exception.
|
||||
If the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause executes a <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> or <a class="reference internal" href="simple_stmts.html#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a>
|
||||
statement, the saved exception is discarded:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
|
||||
<span class="gp">... </span> <span class="k">try</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="mi">1</span><span class="o">/</span><span class="mi">0</span>
|
||||
<span class="gp">... </span> <span class="k">finally</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">return</span> <span class="mi">42</span>
|
||||
<span class="gp">...</span>
|
||||
<span class="gp">>>> </span><span class="n">f</span><span class="p">()</span>
|
||||
<span class="go">42</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The exception information is not available to the program during execution of
|
||||
the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause.</p>
|
||||
<p id="index-15">When a <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a>, <a class="reference internal" href="simple_stmts.html#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a> or <a class="reference internal" href="simple_stmts.html#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a> statement is
|
||||
executed in the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> suite of a <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a>...<a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a>
|
||||
statement, the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause is also executed ‘on the way out.’ A
|
||||
<a class="reference internal" href="simple_stmts.html#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a> statement is illegal in the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause. (The
|
||||
reason is a problem with the current implementation — this restriction may be
|
||||
lifted in the future).</p>
|
||||
<p>The return value of a function is determined by the last <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a>
|
||||
statement executed. Since the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause always executes, a
|
||||
<a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> statement executed in the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause will
|
||||
always be the last one executed:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">foo</span><span class="p">():</span>
|
||||
<span class="gp">... </span> <span class="k">try</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">return</span> <span class="s">'try'</span>
|
||||
<span class="gp">... </span> <span class="k">finally</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">return</span> <span class="s">'finally'</span>
|
||||
<span class="gp">...</span>
|
||||
<span class="gp">>>> </span><span class="n">foo</span><span class="p">()</span>
|
||||
<span class="go">'finally'</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Additional information on exceptions can be found in section <a class="reference internal" href="executionmodel.html#exceptions"><em>Exceptions</em></a>,
|
||||
and information on using the <a class="reference internal" href="simple_stmts.html#raise"><tt class="xref std std-keyword docutils literal"><span class="pre">raise</span></tt></a> statement to generate exceptions
|
||||
may be found in section <a class="reference internal" href="simple_stmts.html#raise"><em>The raise statement</em></a>.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,55 @@
|
||||
<div class="section" id="the-for-statement">
|
||||
<span id="for"></span><h2>The <a class="reference internal" href="#for"><tt class="xref std std-keyword docutils literal"><span class="pre">for</span></tt></a> statement</h2>
|
||||
<p id="index-6">The <a class="reference internal" href="#for"><tt class="xref std std-keyword docutils literal"><span class="pre">for</span></tt></a> statement is used to iterate over the elements of a sequence
|
||||
(such as a string, tuple or list) or other iterable object:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-for_stmt">for_stmt</strong> ::= "for" <a class="reference internal" href="simple_stmts.html#grammar-token-target_list"><tt class="xref docutils literal"><span class="pre">target_list</span></tt></a> "in" <a class="reference internal" href="expressions.html#grammar-token-expression_list"><tt class="xref docutils literal"><span class="pre">expression_list</span></tt></a> ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
["else" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
</pre>
|
||||
<p>The expression list is evaluated once; it should yield an iterable object. An
|
||||
iterator is created for the result of the <tt class="docutils literal"><span class="pre">expression_list</span></tt>. The suite is
|
||||
then executed once for each item provided by the iterator, in the order returned
|
||||
by the iterator. Each item in turn is assigned to the target list using the
|
||||
standard rules for assignments (see <a class="reference internal" href="simple_stmts.html#assignment"><em>Assignment statements</em></a>), and then the suite is
|
||||
executed. When the items are exhausted (which is immediately when the sequence
|
||||
is empty or an iterator raises a <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><tt class="xref py py-exc docutils literal"><span class="pre">StopIteration</span></tt></a> exception), the suite in
|
||||
the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause, if present, is executed, and the loop terminates.</p>
|
||||
<p id="index-7">A <a class="reference internal" href="simple_stmts.html#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a> statement executed in the first suite terminates the loop
|
||||
without executing the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause’s suite. A <a class="reference internal" href="simple_stmts.html#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a>
|
||||
statement executed in the first suite skips the rest of the suite and continues
|
||||
with the next item, or with the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause if there is no next
|
||||
item.</p>
|
||||
<p>The for-loop makes assignments to the variables(s) in the target list.
|
||||
This overwrites all previous assignments to those variables including
|
||||
those made in the suite of the for-loop:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><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="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">5</span> <span class="c"># this will not affect the for-loop</span>
|
||||
<span class="c"># because i will be overwritten with the next</span>
|
||||
<span class="c"># index in the range</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p id="index-8">Names in the target list are not deleted when the loop is finished, but if the
|
||||
sequence is empty, they will not have been assigned to at all by the loop. Hint:
|
||||
the built-in function <a class="reference internal" href="../library/stdtypes.html#range" title="range"><tt class="xref py py-func docutils literal"><span class="pre">range()</span></tt></a> returns an iterator of integers suitable to
|
||||
emulate the effect of Pascal’s <tt class="docutils literal"><span class="pre">for</span> <span class="pre">i</span> <span class="pre">:=</span> <span class="pre">a</span> <span class="pre">to</span> <span class="pre">b</span> <span class="pre">do</span></tt>; e.g., <tt class="docutils literal"><span class="pre">list(range(3))</span></tt>
|
||||
returns the list <tt class="docutils literal"><span class="pre">[0,</span> <span class="pre">1,</span> <span class="pre">2]</span></tt>.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p id="index-9">There is a subtlety when the sequence is being modified by the loop (this can
|
||||
only occur for mutable sequences, i.e. lists). An internal counter is used
|
||||
to keep track of which item is used next, and this is incremented on each
|
||||
iteration. When this counter has reached the length of the sequence the loop
|
||||
terminates. This means that if the suite deletes the current (or a previous)
|
||||
item from the sequence, the next item will be skipped (since it gets the
|
||||
index of the current item which has already been treated). Likewise, if the
|
||||
suite inserts an item in the sequence before the current item, the current
|
||||
item will be treated again the next time through the loop. This can lead to
|
||||
nasty bugs that can be avoided by making a temporary copy using a slice of
|
||||
the whole sequence, e.g.,</p>
|
||||
<div class="last highlight-python3"><div class="highlight"><pre><span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">a</span><span class="p">[:]:</span>
|
||||
<span class="k">if</span> <span class="n">x</span> <span class="o"><</span> <span class="mi">0</span><span class="p">:</span> <span class="n">a</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -0,0 +1,96 @@
|
||||
<div class="section" id="the-import-statement">
|
||||
<span id="from"></span><span id="import"></span><h2>The <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement</h2>
|
||||
<pre id="index-31">
|
||||
<strong id="grammar-token-import_stmt">import_stmt </strong> ::= "import" <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] ( "," <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
|
||||
| "from" <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> "import" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
|
||||
( "," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
|
||||
| "from" <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> "import" "(" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
|
||||
( "," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )* [","] ")"
|
||||
| "from" <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> "import" "*"
|
||||
<strong id="grammar-token-module">module </strong> ::= (<a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ".")* <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
|
||||
<strong id="grammar-token-relative_module">relative_module</strong> ::= "."* <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> | "."+
|
||||
<strong id="grammar-token-name">name </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
|
||||
</pre>
|
||||
<p>The basic import statement (no <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> clause) is executed in two
|
||||
steps:</p>
|
||||
<ol class="arabic simple">
|
||||
<li>find a module, loading and initializing it if necessary</li>
|
||||
<li>define a name or names in the local namespace for the scope where
|
||||
the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement occurs.</li>
|
||||
</ol>
|
||||
<p>When the statement contains multiple clauses (separated by
|
||||
commas) the two steps are carried out separately for each clause, just
|
||||
as though the clauses had been separated out into individiual import
|
||||
statements.</p>
|
||||
<p>The details of the first step, finding and loading modules are described in
|
||||
greater detail in the section on the <a class="reference internal" href="import.html#importsystem"><em>import system</em></a>,
|
||||
which also describes the various types of packages and modules that can
|
||||
be imported, as well as all the hooks that can be used to customize
|
||||
the import system. Note that failures in this step may indicate either
|
||||
that the module could not be located, <em>or</em> that an error occurred while
|
||||
initializing the module, which includes execution of the module’s code.</p>
|
||||
<p>If the requested module is retrieved successfully, it will be made
|
||||
available in the local namespace in one of three ways:</p>
|
||||
<ul class="simple" id="index-32">
|
||||
<li>If the module name is followed by <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a>, then the name
|
||||
following <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> is bound directly to the imported module.</li>
|
||||
<li>If no other name is specified, and the module being imported is a top
|
||||
level module, the module’s name is bound in the local namespace as a
|
||||
reference to the imported module</li>
|
||||
<li>If the module being imported is <em>not</em> a top level module, then the name
|
||||
of the top level package that contains the module is bound in the local
|
||||
namespace as a reference to the top level package. The imported module
|
||||
must be accessed using its full qualified name rather than directly</li>
|
||||
</ul>
|
||||
<p id="index-33">The <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> form uses a slightly more complex process:</p>
|
||||
<ol class="arabic simple">
|
||||
<li>find the module specified in the <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> clause, loading and
|
||||
initializing it if necessary;</li>
|
||||
<li>for each of the identifiers specified in the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> clauses:<ol class="arabic">
|
||||
<li>check if the imported module has an attribute by that name</li>
|
||||
<li>if not, attempt to import a submodule with that name and then
|
||||
check the imported module again for that attribute</li>
|
||||
<li>if the attribute is not found, <a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><tt class="xref py py-exc docutils literal"><span class="pre">ImportError</span></tt></a> is raised.</li>
|
||||
<li>otherwise, a reference to that value is stored in the local namespace,
|
||||
using the name in the <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> clause if it is present,
|
||||
otherwise using the attribute name</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
<p>Examples:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">foo</span> <span class="c"># foo imported and bound locally</span>
|
||||
<span class="kn">import</span> <span class="nn">foo.bar.baz</span> <span class="c"># foo.bar.baz imported, foo bound locally</span>
|
||||
<span class="kn">import</span> <span class="nn">foo.bar.baz</span> <span class="k">as</span> <span class="nn">fbb</span> <span class="c"># foo.bar.baz imported and bound as fbb</span>
|
||||
<span class="kn">from</span> <span class="nn">foo.bar</span> <span class="k">import</span> <span class="n">baz</span> <span class="c"># foo.bar.baz imported and bound as baz</span>
|
||||
<span class="kn">from</span> <span class="nn">foo</span> <span class="k">import</span> <span class="n">attr</span> <span class="c"># foo imported and foo.attr bound as attr</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If the list of identifiers is replaced by a star (<tt class="docutils literal"><span class="pre">'*'</span></tt>), all public
|
||||
names defined in the module are bound in the local namespace for the scope
|
||||
where the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement occurs.</p>
|
||||
<p id="index-34">The <em>public names</em> defined by a module are determined by checking the module’s
|
||||
namespace for a variable named <tt class="docutils literal"><span class="pre">__all__</span></tt>; if defined, it must be a sequence
|
||||
of strings which are names defined or imported by that module. The names
|
||||
given in <tt class="docutils literal"><span class="pre">__all__</span></tt> are all considered public and are required to exist. If
|
||||
<tt class="docutils literal"><span class="pre">__all__</span></tt> is not defined, the set of public names includes all names found
|
||||
in the module’s namespace which do not begin with an underscore character
|
||||
(<tt class="docutils literal"><span class="pre">'_'</span></tt>). <tt class="docutils literal"><span class="pre">__all__</span></tt> should contain the entire public API. It is intended
|
||||
to avoid accidentally exporting items that are not part of the API (such as
|
||||
library modules which were imported and used within the module).</p>
|
||||
<p>The wild card form of import — <tt class="docutils literal"><span class="pre">from</span> <span class="pre">module</span> <span class="pre">import</span> <span class="pre">*</span></tt> — is only allowed at
|
||||
the module level. Attempting to use it in class or function definitions will
|
||||
raise a <a class="reference internal" href="../library/exceptions.html#SyntaxError" title="SyntaxError"><tt class="xref py py-exc docutils literal"><span class="pre">SyntaxError</span></tt></a>.</p>
|
||||
<p id="index-35">When specifying what module to import you do not have to specify the absolute
|
||||
name of the module. When a module or package is contained within another
|
||||
package it is possible to make a relative import within the same top package
|
||||
without having to mention the package name. By using leading dots in the
|
||||
specified module or package after <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> you can specify how high to
|
||||
traverse up the current package hierarchy without specifying exact names. One
|
||||
leading dot means the current package where the module making the import
|
||||
exists. Two dots means up one package level. Three dots is up two levels, etc.
|
||||
So if you execute <tt class="docutils literal"><span class="pre">from</span> <span class="pre">.</span> <span class="pre">import</span> <span class="pre">mod</span></tt> from a module in the <tt class="docutils literal"><span class="pre">pkg</span></tt> package
|
||||
then you will end up importing <tt class="docutils literal"><span class="pre">pkg.mod</span></tt>. If you execute <tt class="docutils literal"><span class="pre">from</span> <span class="pre">..subpkg2</span>
|
||||
<span class="pre">import</span> <span class="pre">mod</span></tt> from within <tt class="docutils literal"><span class="pre">pkg.subpkg1</span></tt> you will import <tt class="docutils literal"><span class="pre">pkg.subpkg2.mod</span></tt>.
|
||||
The specification for relative imports is contained within <span class="target" id="index-36"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0328"><strong>PEP 328</strong></a>.</p>
|
||||
<p><a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><tt class="xref py py-func docutils literal"><span class="pre">importlib.import_module()</span></tt></a> is provided to support applications that
|
||||
determine dynamically the modules to be loaded.</p>
|
||||
@@ -0,0 +1,28 @@
|
||||
<div class="section" id="the-global-statement">
|
||||
<span id="global"></span><h2>The <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statement</h2>
|
||||
<pre id="index-39">
|
||||
<strong id="grammar-token-global_stmt">global_stmt</strong> ::= "global" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ("," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>)*
|
||||
</pre>
|
||||
<p>The <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statement is a declaration which holds for the entire
|
||||
current code block. It means that the listed identifiers are to be interpreted
|
||||
as globals. It would be impossible to assign to a global variable without
|
||||
<a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a>, although free variables may refer to globals without being
|
||||
declared global.</p>
|
||||
<p>Names listed in a <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statement must not be used in the same code
|
||||
block textually preceding that <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statement.</p>
|
||||
<p>Names listed in a <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statement must not be defined as formal
|
||||
parameters or in a <a class="reference internal" href="compound_stmts.html#for"><tt class="xref std std-keyword docutils literal"><span class="pre">for</span></tt></a> loop control target, <a class="reference internal" href="compound_stmts.html#class"><tt class="xref std std-keyword docutils literal"><span class="pre">class</span></tt></a>
|
||||
definition, function definition, or <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement.</p>
|
||||
<div class="impl-detail compound">
|
||||
<p><strong>CPython implementation detail:</strong> The current implementation does not enforce the two restrictions, but
|
||||
programs should not abuse this freedom, as future implementations may enforce
|
||||
them or silently change the meaning of the program.</p>
|
||||
</div>
|
||||
<p id="index-40"><strong>Programmer’s note:</strong> the <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> is a directive to the parser. It
|
||||
applies only to code parsed at the same time as the <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statement.
|
||||
In particular, a <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statement contained in a string or code
|
||||
object supplied to the built-in <a class="reference internal" href="../library/functions.html#exec" title="exec"><tt class="xref py py-func docutils literal"><span class="pre">exec()</span></tt></a> function does not affect the code
|
||||
block <em>containing</em> the function call, and code contained in such a string is
|
||||
unaffected by <a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statements in the code containing the function
|
||||
call. The same applies to the <a class="reference internal" href="../library/functions.html#eval" title="eval"><tt class="xref py py-func docutils literal"><span class="pre">eval()</span></tt></a> and <a class="reference internal" href="../library/functions.html#compile" title="compile"><tt class="xref py py-func docutils literal"><span class="pre">compile()</span></tt></a> functions.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,14 @@
|
||||
<div class="section" id="the-if-statement">
|
||||
<span id="else"></span><span id="elif"></span><span id="if"></span><h2>The <a class="reference internal" href="#if"><tt class="xref std std-keyword docutils literal"><span class="pre">if</span></tt></a> statement</h2>
|
||||
<p id="index-3">The <a class="reference internal" href="#if"><tt class="xref std std-keyword docutils literal"><span class="pre">if</span></tt></a> statement is used for conditional execution:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-if_stmt">if_stmt</strong> ::= "if" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
( "elif" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a> )*
|
||||
["else" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
</pre>
|
||||
<p>It selects exactly one of the suites by evaluating the expressions one by one
|
||||
until one is found to be true (see section <a class="reference internal" href="expressions.html#booleans"><em>Boolean operations</em></a> for the definition of
|
||||
true and false); then that suite is executed (and no other part of the
|
||||
<a class="reference internal" href="#if"><tt class="xref std std-keyword docutils literal"><span class="pre">if</span></tt></a> statement is executed or evaluated). If all expressions are
|
||||
false, the suite of the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause, if present, is executed.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,96 @@
|
||||
<div class="section" id="the-import-statement">
|
||||
<span id="from"></span><span id="import"></span><h2>The <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement</h2>
|
||||
<pre id="index-31">
|
||||
<strong id="grammar-token-import_stmt">import_stmt </strong> ::= "import" <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] ( "," <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
|
||||
| "from" <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> "import" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
|
||||
( "," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
|
||||
| "from" <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> "import" "(" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
|
||||
( "," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )* [","] ")"
|
||||
| "from" <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> "import" "*"
|
||||
<strong id="grammar-token-module">module </strong> ::= (<a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ".")* <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
|
||||
<strong id="grammar-token-relative_module">relative_module</strong> ::= "."* <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> | "."+
|
||||
<strong id="grammar-token-name">name </strong> ::= <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
|
||||
</pre>
|
||||
<p>The basic import statement (no <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> clause) is executed in two
|
||||
steps:</p>
|
||||
<ol class="arabic simple">
|
||||
<li>find a module, loading and initializing it if necessary</li>
|
||||
<li>define a name or names in the local namespace for the scope where
|
||||
the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement occurs.</li>
|
||||
</ol>
|
||||
<p>When the statement contains multiple clauses (separated by
|
||||
commas) the two steps are carried out separately for each clause, just
|
||||
as though the clauses had been separated out into individiual import
|
||||
statements.</p>
|
||||
<p>The details of the first step, finding and loading modules are described in
|
||||
greater detail in the section on the <a class="reference internal" href="import.html#importsystem"><em>import system</em></a>,
|
||||
which also describes the various types of packages and modules that can
|
||||
be imported, as well as all the hooks that can be used to customize
|
||||
the import system. Note that failures in this step may indicate either
|
||||
that the module could not be located, <em>or</em> that an error occurred while
|
||||
initializing the module, which includes execution of the module’s code.</p>
|
||||
<p>If the requested module is retrieved successfully, it will be made
|
||||
available in the local namespace in one of three ways:</p>
|
||||
<ul class="simple" id="index-32">
|
||||
<li>If the module name is followed by <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a>, then the name
|
||||
following <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> is bound directly to the imported module.</li>
|
||||
<li>If no other name is specified, and the module being imported is a top
|
||||
level module, the module’s name is bound in the local namespace as a
|
||||
reference to the imported module</li>
|
||||
<li>If the module being imported is <em>not</em> a top level module, then the name
|
||||
of the top level package that contains the module is bound in the local
|
||||
namespace as a reference to the top level package. The imported module
|
||||
must be accessed using its full qualified name rather than directly</li>
|
||||
</ul>
|
||||
<p id="index-33">The <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> form uses a slightly more complex process:</p>
|
||||
<ol class="arabic simple">
|
||||
<li>find the module specified in the <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> clause, loading and
|
||||
initializing it if necessary;</li>
|
||||
<li>for each of the identifiers specified in the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> clauses:<ol class="arabic">
|
||||
<li>check if the imported module has an attribute by that name</li>
|
||||
<li>if not, attempt to import a submodule with that name and then
|
||||
check the imported module again for that attribute</li>
|
||||
<li>if the attribute is not found, <a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><tt class="xref py py-exc docutils literal"><span class="pre">ImportError</span></tt></a> is raised.</li>
|
||||
<li>otherwise, a reference to that value is stored in the local namespace,
|
||||
using the name in the <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> clause if it is present,
|
||||
otherwise using the attribute name</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
<p>Examples:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">foo</span> <span class="c"># foo imported and bound locally</span>
|
||||
<span class="kn">import</span> <span class="nn">foo.bar.baz</span> <span class="c"># foo.bar.baz imported, foo bound locally</span>
|
||||
<span class="kn">import</span> <span class="nn">foo.bar.baz</span> <span class="k">as</span> <span class="nn">fbb</span> <span class="c"># foo.bar.baz imported and bound as fbb</span>
|
||||
<span class="kn">from</span> <span class="nn">foo.bar</span> <span class="k">import</span> <span class="n">baz</span> <span class="c"># foo.bar.baz imported and bound as baz</span>
|
||||
<span class="kn">from</span> <span class="nn">foo</span> <span class="k">import</span> <span class="n">attr</span> <span class="c"># foo imported and foo.attr bound as attr</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If the list of identifiers is replaced by a star (<tt class="docutils literal"><span class="pre">'*'</span></tt>), all public
|
||||
names defined in the module are bound in the local namespace for the scope
|
||||
where the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement occurs.</p>
|
||||
<p id="index-34">The <em>public names</em> defined by a module are determined by checking the module’s
|
||||
namespace for a variable named <tt class="docutils literal"><span class="pre">__all__</span></tt>; if defined, it must be a sequence
|
||||
of strings which are names defined or imported by that module. The names
|
||||
given in <tt class="docutils literal"><span class="pre">__all__</span></tt> are all considered public and are required to exist. If
|
||||
<tt class="docutils literal"><span class="pre">__all__</span></tt> is not defined, the set of public names includes all names found
|
||||
in the module’s namespace which do not begin with an underscore character
|
||||
(<tt class="docutils literal"><span class="pre">'_'</span></tt>). <tt class="docutils literal"><span class="pre">__all__</span></tt> should contain the entire public API. It is intended
|
||||
to avoid accidentally exporting items that are not part of the API (such as
|
||||
library modules which were imported and used within the module).</p>
|
||||
<p>The wild card form of import — <tt class="docutils literal"><span class="pre">from</span> <span class="pre">module</span> <span class="pre">import</span> <span class="pre">*</span></tt> — is only allowed at
|
||||
the module level. Attempting to use it in class or function definitions will
|
||||
raise a <a class="reference internal" href="../library/exceptions.html#SyntaxError" title="SyntaxError"><tt class="xref py py-exc docutils literal"><span class="pre">SyntaxError</span></tt></a>.</p>
|
||||
<p id="index-35">When specifying what module to import you do not have to specify the absolute
|
||||
name of the module. When a module or package is contained within another
|
||||
package it is possible to make a relative import within the same top package
|
||||
without having to mention the package name. By using leading dots in the
|
||||
specified module or package after <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> you can specify how high to
|
||||
traverse up the current package hierarchy without specifying exact names. One
|
||||
leading dot means the current package where the module making the import
|
||||
exists. Two dots means up one package level. Three dots is up two levels, etc.
|
||||
So if you execute <tt class="docutils literal"><span class="pre">from</span> <span class="pre">.</span> <span class="pre">import</span> <span class="pre">mod</span></tt> from a module in the <tt class="docutils literal"><span class="pre">pkg</span></tt> package
|
||||
then you will end up importing <tt class="docutils literal"><span class="pre">pkg.mod</span></tt>. If you execute <tt class="docutils literal"><span class="pre">from</span> <span class="pre">..subpkg2</span>
|
||||
<span class="pre">import</span> <span class="pre">mod</span></tt> from within <tt class="docutils literal"><span class="pre">pkg.subpkg1</span></tt> you will import <tt class="docutils literal"><span class="pre">pkg.subpkg2.mod</span></tt>.
|
||||
The specification for relative imports is contained within <span class="target" id="index-36"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0328"><strong>PEP 328</strong></a>.</p>
|
||||
<p><a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><tt class="xref py py-func docutils literal"><span class="pre">importlib.import_module()</span></tt></a> is provided to support applications that
|
||||
determine dynamically the modules to be loaded.</p>
|
||||
@@ -0,0 +1,97 @@
|
||||
<div class="section" id="notin">
|
||||
<span id="in"></span><span id="isnot"></span><span id="is"></span><span id="comparisons"></span><span id="id12"></span><h2>Comparisons</h2>
|
||||
<span class="target" id="index-970"></span><p id="index-971">Unlike C, all comparison operations in Python have the same priority, which is
|
||||
lower than that of any arithmetic, shifting or bitwise operation. Also unlike
|
||||
C, expressions like <tt class="docutils literal"><span class="pre">a</span> <span class="pre"><</span> <span class="pre">b</span> <span class="pre"><</span> <span class="pre">c</span></tt> have the interpretation that is conventional
|
||||
in mathematics:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-comparison">comparison </strong> ::= <a class="reference internal" href="#grammar-token-or_expr"><tt class="xref docutils literal"><span class="pre">or_expr</span></tt></a> ( <a class="reference internal" href="#grammar-token-comp_operator"><tt class="xref docutils literal"><span class="pre">comp_operator</span></tt></a> <a class="reference internal" href="#grammar-token-or_expr"><tt class="xref docutils literal"><span class="pre">or_expr</span></tt></a> )*
|
||||
<strong id="grammar-token-comp_operator">comp_operator</strong> ::= "<" | ">" | "==" | ">=" | "<=" | "<>" | "!="
|
||||
| "is" ["not"] | ["not"] "in"
|
||||
</pre>
|
||||
<p>Comparisons yield boolean values: <tt class="xref docutils literal"><span class="pre">True</span></tt> or <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p>
|
||||
<p id="index-972">Comparisons can be chained arbitrarily, e.g., <tt class="docutils literal"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre"><=</span> <span class="pre">z</span></tt> is equivalent to
|
||||
<tt class="docutils literal"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre">and</span> <span class="pre">y</span> <span class="pre"><=</span> <span class="pre">z</span></tt>, except that <tt class="docutils literal"><span class="pre">y</span></tt> is evaluated only once (but in both
|
||||
cases <tt class="docutils literal"><span class="pre">z</span></tt> is not evaluated at all when <tt class="docutils literal"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span></tt> is found to be false).</p>
|
||||
<p>Formally, if <em>a</em>, <em>b</em>, <em>c</em>, ..., <em>y</em>, <em>z</em> are expressions and <em>op1</em>, <em>op2</em>, ...,
|
||||
<em>opN</em> are comparison operators, then <tt class="docutils literal"><span class="pre">a</span> <span class="pre">op1</span> <span class="pre">b</span> <span class="pre">op2</span> <span class="pre">c</span> <span class="pre">...</span> <span class="pre">y</span> <span class="pre">opN</span> <span class="pre">z</span></tt> is equivalent
|
||||
to <tt class="docutils literal"><span class="pre">a</span> <span class="pre">op1</span> <span class="pre">b</span> <span class="pre">and</span> <span class="pre">b</span> <span class="pre">op2</span> <span class="pre">c</span> <span class="pre">and</span> <span class="pre">...</span> <span class="pre">y</span> <span class="pre">opN</span> <span class="pre">z</span></tt>, except that each expression is
|
||||
evaluated at most once.</p>
|
||||
<p>Note that <tt class="docutils literal"><span class="pre">a</span> <span class="pre">op1</span> <span class="pre">b</span> <span class="pre">op2</span> <span class="pre">c</span></tt> doesn’t imply any kind of comparison between <em>a</em> and
|
||||
<em>c</em>, so that, e.g., <tt class="docutils literal"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre">></span> <span class="pre">z</span></tt> is perfectly legal (though perhaps not
|
||||
pretty).</p>
|
||||
<p>The forms <tt class="docutils literal"><span class="pre"><></span></tt> and <tt class="docutils literal"><span class="pre">!=</span></tt> are equivalent; for consistency with C, <tt class="docutils literal"><span class="pre">!=</span></tt> is
|
||||
preferred; where <tt class="docutils literal"><span class="pre">!=</span></tt> is mentioned below <tt class="docutils literal"><span class="pre"><></span></tt> is also accepted. The <tt class="docutils literal"><span class="pre"><></span></tt>
|
||||
spelling is considered obsolescent.</p>
|
||||
<p>The operators <tt class="docutils literal"><span class="pre"><</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, <tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">>=</span></tt>, <tt class="docutils literal"><span class="pre"><=</span></tt>, and <tt class="docutils literal"><span class="pre">!=</span></tt> compare the
|
||||
values of two objects. The objects need not have the same type. If both are
|
||||
numbers, they are converted to a common type. Otherwise, objects of different
|
||||
types <em>always</em> compare unequal, and are ordered consistently but arbitrarily.
|
||||
You can control comparison behavior of objects of non-built-in types by defining
|
||||
a <tt class="docutils literal"><span class="pre">__cmp__</span></tt> method or rich comparison methods like <tt class="docutils literal"><span class="pre">__gt__</span></tt>, described in
|
||||
section <a class="reference external" href="datamodel.html#specialnames"><em>Special method names</em></a>.</p>
|
||||
<p>(This unusual definition of comparison was used to simplify the definition of
|
||||
operations like sorting and the <a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a> and <a class="reference internal" href="#notin"><tt class="xref docutils literal"><span class="pre">not</span> <span class="pre">in</span></tt></a> operators.
|
||||
In the future, the comparison rules for objects of different types are likely to
|
||||
change.)</p>
|
||||
<p>Comparison of objects of the same type depends on the type:</p>
|
||||
<ul>
|
||||
<li><p class="first">Numbers are compared arithmetically.</p>
|
||||
</li>
|
||||
<li><p class="first">Strings are compared lexicographically using the numeric equivalents (the
|
||||
result of the built-in function <a title="ord" class="reference external" href="../library/functions.html#ord"><tt class="xref docutils literal"><span class="pre">ord()</span></tt></a>) of their characters. Unicode and
|
||||
8-bit strings are fully interoperable in this behavior. <a class="footnote-reference" href="#id22" id="id13">[4]</a></p>
|
||||
</li>
|
||||
<li><p class="first">Tuples and lists are compared lexicographically using comparison of
|
||||
corresponding elements. This means that to compare equal, each element must
|
||||
compare equal and the two sequences must be of the same type and have the same
|
||||
length.</p>
|
||||
<p>If not equal, the sequences are ordered the same as their first differing
|
||||
elements. For example, <tt class="docutils literal"><span class="pre">cmp([1,2,x],</span> <span class="pre">[1,2,y])</span></tt> returns the same as
|
||||
<tt class="docutils literal"><span class="pre">cmp(x,y)</span></tt>. If the corresponding element does not exist, the shorter sequence
|
||||
is ordered first (for example, <tt class="docutils literal"><span class="pre">[1,2]</span> <span class="pre"><</span> <span class="pre">[1,2,3]</span></tt>).</p>
|
||||
</li>
|
||||
<li><p class="first">Mappings (dictionaries) compare equal if and only if their sorted (key, value)
|
||||
lists compare equal. <a class="footnote-reference" href="#id23" id="id14">[5]</a> Outcomes other than equality are resolved
|
||||
consistently, but are not otherwise defined. <a class="footnote-reference" href="#id24" id="id15">[6]</a></p>
|
||||
</li>
|
||||
<li><p class="first">Most other objects of built-in types compare unequal unless they are the same
|
||||
object; the choice whether one object is considered smaller or larger than
|
||||
another one is made arbitrarily but consistently within one execution of a
|
||||
program.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p id="membership-test-details">The operators <a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a> and <a class="reference internal" href="#notin"><tt class="xref docutils literal"><span class="pre">not</span> <span class="pre">in</span></tt></a> test for collection
|
||||
membership. <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">s</span></tt> evaluates to true if <em>x</em> is a member of the collection
|
||||
<em>s</em>, and false otherwise. <tt class="docutils literal"><span class="pre">x</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">s</span></tt> returns the negation of <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">s</span></tt>.
|
||||
The collection membership test has traditionally been bound to sequences; an
|
||||
object is a member of a collection if the collection is a sequence and contains
|
||||
an element equal to that object. However, it make sense for many other object
|
||||
types to support membership tests without being a sequence. In particular,
|
||||
dictionaries (for keys) and sets support membership testing.</p>
|
||||
<p>For the list and tuple types, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></tt> is true if and only if there exists an
|
||||
index <em>i</em> such that <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y[i]</span></tt> is true.</p>
|
||||
<p>For the Unicode and string types, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></tt> is true if and only if <em>x</em> is a
|
||||
substring of <em>y</em>. An equivalent test is <tt class="docutils literal"><span class="pre">y.find(x)</span> <span class="pre">!=</span> <span class="pre">-1</span></tt>. Note, <em>x</em> and <em>y</em>
|
||||
need not be the same type; consequently, <tt class="docutils literal"><span class="pre">u'ab'</span> <span class="pre">in</span> <span class="pre">'abc'</span></tt> will return
|
||||
<tt class="xref docutils literal"><span class="pre">True</span></tt>. Empty strings are always considered to be a substring of any other
|
||||
string, so <tt class="docutils literal"><span class="pre">""</span> <span class="pre">in</span> <span class="pre">"abc"</span></tt> will return <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
|
||||
<p class="versionchanged">
|
||||
<span class="versionmodified">Changed in version 2.3: </span>Previously, <em>x</em> was required to be a string of length <tt class="docutils literal"><span class="pre">1</span></tt>.</p>
|
||||
<p>For user-defined classes which define the <a title="object.__contains__" class="reference external" href="datamodel.html#object.__contains__"><tt class="xref docutils literal"><span class="pre">__contains__()</span></tt></a> method, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span>
|
||||
<span class="pre">y</span></tt> is true if and only if <tt class="docutils literal"><span class="pre">y.__contains__(x)</span></tt> is true.</p>
|
||||
<p>For user-defined classes which do not define <a title="object.__contains__" class="reference external" href="datamodel.html#object.__contains__"><tt class="xref docutils literal"><span class="pre">__contains__()</span></tt></a> but do define
|
||||
<a title="object.__iter__" class="reference external" href="datamodel.html#object.__iter__"><tt class="xref docutils literal"><span class="pre">__iter__()</span></tt></a>, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></tt> is true if some value <tt class="docutils literal"><span class="pre">z</span></tt> with <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">z</span></tt> is
|
||||
produced while iterating over <tt class="docutils literal"><span class="pre">y</span></tt>. If an exception is raised during the
|
||||
iteration, it is as if <a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a> raised that exception.</p>
|
||||
<p>Lastly, the old-style iteration protocol is tried: if a class defines
|
||||
<a title="object.__getitem__" class="reference external" href="datamodel.html#object.__getitem__"><tt class="xref docutils literal"><span class="pre">__getitem__()</span></tt></a>, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></tt> is true if and only if there is a non-negative
|
||||
integer index <em>i</em> such that <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y[i]</span></tt>, and all lower integer indices do not
|
||||
raise <a title="exceptions.IndexError" class="reference external" href="../library/exceptions.html#exceptions.IndexError"><tt class="xref docutils literal"><span class="pre">IndexError</span></tt></a> exception. (If any other exception is raised, it is as
|
||||
if <a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a> raised that exception).</p>
|
||||
<p id="index-973">The operator <a class="reference internal" href="#notin"><tt class="xref docutils literal"><span class="pre">not</span> <span class="pre">in</span></tt></a> is defined to have the inverse true value of
|
||||
<a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a>.</p>
|
||||
<p id="index-974">The operators <a class="reference internal" href="#is"><tt class="xref docutils literal"><span class="pre">is</span></tt></a> and <a class="reference internal" href="#isnot"><tt class="xref docutils literal"><span class="pre">is</span> <span class="pre">not</span></tt></a> test for object identity: <tt class="docutils literal"><span class="pre">x</span>
|
||||
<span class="pre">is</span> <span class="pre">y</span></tt> is true if and only if <em>x</em> and <em>y</em> are the same object. <tt class="docutils literal"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">y</span></tt>
|
||||
yields the inverse truth value. <a class="footnote-reference" href="#id25" id="id16">[7]</a></p>
|
||||
</div>
|
||||
@@ -0,0 +1,97 @@
|
||||
<div class="section" id="notin">
|
||||
<span id="in"></span><span id="isnot"></span><span id="is"></span><span id="comparisons"></span><span id="id12"></span><h2>Comparisons</h2>
|
||||
<span class="target" id="index-970"></span><p id="index-971">Unlike C, all comparison operations in Python have the same priority, which is
|
||||
lower than that of any arithmetic, shifting or bitwise operation. Also unlike
|
||||
C, expressions like <tt class="docutils literal"><span class="pre">a</span> <span class="pre"><</span> <span class="pre">b</span> <span class="pre"><</span> <span class="pre">c</span></tt> have the interpretation that is conventional
|
||||
in mathematics:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-comparison">comparison </strong> ::= <a class="reference internal" href="#grammar-token-or_expr"><tt class="xref docutils literal"><span class="pre">or_expr</span></tt></a> ( <a class="reference internal" href="#grammar-token-comp_operator"><tt class="xref docutils literal"><span class="pre">comp_operator</span></tt></a> <a class="reference internal" href="#grammar-token-or_expr"><tt class="xref docutils literal"><span class="pre">or_expr</span></tt></a> )*
|
||||
<strong id="grammar-token-comp_operator">comp_operator</strong> ::= "<" | ">" | "==" | ">=" | "<=" | "<>" | "!="
|
||||
| "is" ["not"] | ["not"] "in"
|
||||
</pre>
|
||||
<p>Comparisons yield boolean values: <tt class="xref docutils literal"><span class="pre">True</span></tt> or <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p>
|
||||
<p id="index-972">Comparisons can be chained arbitrarily, e.g., <tt class="docutils literal"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre"><=</span> <span class="pre">z</span></tt> is equivalent to
|
||||
<tt class="docutils literal"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre">and</span> <span class="pre">y</span> <span class="pre"><=</span> <span class="pre">z</span></tt>, except that <tt class="docutils literal"><span class="pre">y</span></tt> is evaluated only once (but in both
|
||||
cases <tt class="docutils literal"><span class="pre">z</span></tt> is not evaluated at all when <tt class="docutils literal"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span></tt> is found to be false).</p>
|
||||
<p>Formally, if <em>a</em>, <em>b</em>, <em>c</em>, ..., <em>y</em>, <em>z</em> are expressions and <em>op1</em>, <em>op2</em>, ...,
|
||||
<em>opN</em> are comparison operators, then <tt class="docutils literal"><span class="pre">a</span> <span class="pre">op1</span> <span class="pre">b</span> <span class="pre">op2</span> <span class="pre">c</span> <span class="pre">...</span> <span class="pre">y</span> <span class="pre">opN</span> <span class="pre">z</span></tt> is equivalent
|
||||
to <tt class="docutils literal"><span class="pre">a</span> <span class="pre">op1</span> <span class="pre">b</span> <span class="pre">and</span> <span class="pre">b</span> <span class="pre">op2</span> <span class="pre">c</span> <span class="pre">and</span> <span class="pre">...</span> <span class="pre">y</span> <span class="pre">opN</span> <span class="pre">z</span></tt>, except that each expression is
|
||||
evaluated at most once.</p>
|
||||
<p>Note that <tt class="docutils literal"><span class="pre">a</span> <span class="pre">op1</span> <span class="pre">b</span> <span class="pre">op2</span> <span class="pre">c</span></tt> doesn’t imply any kind of comparison between <em>a</em> and
|
||||
<em>c</em>, so that, e.g., <tt class="docutils literal"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre">></span> <span class="pre">z</span></tt> is perfectly legal (though perhaps not
|
||||
pretty).</p>
|
||||
<p>The forms <tt class="docutils literal"><span class="pre"><></span></tt> and <tt class="docutils literal"><span class="pre">!=</span></tt> are equivalent; for consistency with C, <tt class="docutils literal"><span class="pre">!=</span></tt> is
|
||||
preferred; where <tt class="docutils literal"><span class="pre">!=</span></tt> is mentioned below <tt class="docutils literal"><span class="pre"><></span></tt> is also accepted. The <tt class="docutils literal"><span class="pre"><></span></tt>
|
||||
spelling is considered obsolescent.</p>
|
||||
<p>The operators <tt class="docutils literal"><span class="pre"><</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, <tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">>=</span></tt>, <tt class="docutils literal"><span class="pre"><=</span></tt>, and <tt class="docutils literal"><span class="pre">!=</span></tt> compare the
|
||||
values of two objects. The objects need not have the same type. If both are
|
||||
numbers, they are converted to a common type. Otherwise, objects of different
|
||||
types <em>always</em> compare unequal, and are ordered consistently but arbitrarily.
|
||||
You can control comparison behavior of objects of non-built-in types by defining
|
||||
a <tt class="docutils literal"><span class="pre">__cmp__</span></tt> method or rich comparison methods like <tt class="docutils literal"><span class="pre">__gt__</span></tt>, described in
|
||||
section <a class="reference external" href="datamodel.html#specialnames"><em>Special method names</em></a>.</p>
|
||||
<p>(This unusual definition of comparison was used to simplify the definition of
|
||||
operations like sorting and the <a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a> and <a class="reference internal" href="#notin"><tt class="xref docutils literal"><span class="pre">not</span> <span class="pre">in</span></tt></a> operators.
|
||||
In the future, the comparison rules for objects of different types are likely to
|
||||
change.)</p>
|
||||
<p>Comparison of objects of the same type depends on the type:</p>
|
||||
<ul>
|
||||
<li><p class="first">Numbers are compared arithmetically.</p>
|
||||
</li>
|
||||
<li><p class="first">Strings are compared lexicographically using the numeric equivalents (the
|
||||
result of the built-in function <a title="ord" class="reference external" href="../library/functions.html#ord"><tt class="xref docutils literal"><span class="pre">ord()</span></tt></a>) of their characters. Unicode and
|
||||
8-bit strings are fully interoperable in this behavior. <a class="footnote-reference" href="#id22" id="id13">[4]</a></p>
|
||||
</li>
|
||||
<li><p class="first">Tuples and lists are compared lexicographically using comparison of
|
||||
corresponding elements. This means that to compare equal, each element must
|
||||
compare equal and the two sequences must be of the same type and have the same
|
||||
length.</p>
|
||||
<p>If not equal, the sequences are ordered the same as their first differing
|
||||
elements. For example, <tt class="docutils literal"><span class="pre">cmp([1,2,x],</span> <span class="pre">[1,2,y])</span></tt> returns the same as
|
||||
<tt class="docutils literal"><span class="pre">cmp(x,y)</span></tt>. If the corresponding element does not exist, the shorter sequence
|
||||
is ordered first (for example, <tt class="docutils literal"><span class="pre">[1,2]</span> <span class="pre"><</span> <span class="pre">[1,2,3]</span></tt>).</p>
|
||||
</li>
|
||||
<li><p class="first">Mappings (dictionaries) compare equal if and only if their sorted (key, value)
|
||||
lists compare equal. <a class="footnote-reference" href="#id23" id="id14">[5]</a> Outcomes other than equality are resolved
|
||||
consistently, but are not otherwise defined. <a class="footnote-reference" href="#id24" id="id15">[6]</a></p>
|
||||
</li>
|
||||
<li><p class="first">Most other objects of built-in types compare unequal unless they are the same
|
||||
object; the choice whether one object is considered smaller or larger than
|
||||
another one is made arbitrarily but consistently within one execution of a
|
||||
program.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p id="membership-test-details">The operators <a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a> and <a class="reference internal" href="#notin"><tt class="xref docutils literal"><span class="pre">not</span> <span class="pre">in</span></tt></a> test for collection
|
||||
membership. <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">s</span></tt> evaluates to true if <em>x</em> is a member of the collection
|
||||
<em>s</em>, and false otherwise. <tt class="docutils literal"><span class="pre">x</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">s</span></tt> returns the negation of <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">s</span></tt>.
|
||||
The collection membership test has traditionally been bound to sequences; an
|
||||
object is a member of a collection if the collection is a sequence and contains
|
||||
an element equal to that object. However, it make sense for many other object
|
||||
types to support membership tests without being a sequence. In particular,
|
||||
dictionaries (for keys) and sets support membership testing.</p>
|
||||
<p>For the list and tuple types, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></tt> is true if and only if there exists an
|
||||
index <em>i</em> such that <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y[i]</span></tt> is true.</p>
|
||||
<p>For the Unicode and string types, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></tt> is true if and only if <em>x</em> is a
|
||||
substring of <em>y</em>. An equivalent test is <tt class="docutils literal"><span class="pre">y.find(x)</span> <span class="pre">!=</span> <span class="pre">-1</span></tt>. Note, <em>x</em> and <em>y</em>
|
||||
need not be the same type; consequently, <tt class="docutils literal"><span class="pre">u'ab'</span> <span class="pre">in</span> <span class="pre">'abc'</span></tt> will return
|
||||
<tt class="xref docutils literal"><span class="pre">True</span></tt>. Empty strings are always considered to be a substring of any other
|
||||
string, so <tt class="docutils literal"><span class="pre">""</span> <span class="pre">in</span> <span class="pre">"abc"</span></tt> will return <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
|
||||
<p class="versionchanged">
|
||||
<span class="versionmodified">Changed in version 2.3: </span>Previously, <em>x</em> was required to be a string of length <tt class="docutils literal"><span class="pre">1</span></tt>.</p>
|
||||
<p>For user-defined classes which define the <a title="object.__contains__" class="reference external" href="datamodel.html#object.__contains__"><tt class="xref docutils literal"><span class="pre">__contains__()</span></tt></a> method, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span>
|
||||
<span class="pre">y</span></tt> is true if and only if <tt class="docutils literal"><span class="pre">y.__contains__(x)</span></tt> is true.</p>
|
||||
<p>For user-defined classes which do not define <a title="object.__contains__" class="reference external" href="datamodel.html#object.__contains__"><tt class="xref docutils literal"><span class="pre">__contains__()</span></tt></a> but do define
|
||||
<a title="object.__iter__" class="reference external" href="datamodel.html#object.__iter__"><tt class="xref docutils literal"><span class="pre">__iter__()</span></tt></a>, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></tt> is true if some value <tt class="docutils literal"><span class="pre">z</span></tt> with <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">z</span></tt> is
|
||||
produced while iterating over <tt class="docutils literal"><span class="pre">y</span></tt>. If an exception is raised during the
|
||||
iteration, it is as if <a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a> raised that exception.</p>
|
||||
<p>Lastly, the old-style iteration protocol is tried: if a class defines
|
||||
<a title="object.__getitem__" class="reference external" href="datamodel.html#object.__getitem__"><tt class="xref docutils literal"><span class="pre">__getitem__()</span></tt></a>, <tt class="docutils literal"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">y</span></tt> is true if and only if there is a non-negative
|
||||
integer index <em>i</em> such that <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y[i]</span></tt>, and all lower integer indices do not
|
||||
raise <a title="exceptions.IndexError" class="reference external" href="../library/exceptions.html#exceptions.IndexError"><tt class="xref docutils literal"><span class="pre">IndexError</span></tt></a> exception. (If any other exception is raised, it is as
|
||||
if <a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a> raised that exception).</p>
|
||||
<p id="index-973">The operator <a class="reference internal" href="#notin"><tt class="xref docutils literal"><span class="pre">not</span> <span class="pre">in</span></tt></a> is defined to have the inverse true value of
|
||||
<a class="reference internal" href="#in"><tt class="xref docutils literal"><span class="pre">in</span></tt></a>.</p>
|
||||
<p id="index-974">The operators <a class="reference internal" href="#is"><tt class="xref docutils literal"><span class="pre">is</span></tt></a> and <a class="reference internal" href="#isnot"><tt class="xref docutils literal"><span class="pre">is</span> <span class="pre">not</span></tt></a> test for object identity: <tt class="docutils literal"><span class="pre">x</span>
|
||||
<span class="pre">is</span> <span class="pre">y</span></tt> is true if and only if <em>x</em> and <em>y</em> are the same object. <tt class="docutils literal"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">y</span></tt>
|
||||
yields the inverse truth value. <a class="footnote-reference" href="#id25" id="id16">[7]</a></p>
|
||||
</div>
|
||||
@@ -0,0 +1,17 @@
|
||||
<div class="section" id="lambda">
|
||||
<span id="lambdas"></span><span id="id13"></span><h2>Lambdas</h2>
|
||||
<pre id="index-71">
|
||||
<strong id="grammar-token-lambda_expr">lambda_expr </strong> ::= "lambda" [<a class="reference internal" href="compound_stmts.html#grammar-token-parameter_list"><tt class="xref docutils literal"><span class="pre">parameter_list</span></tt></a>]: <a class="reference internal" href="#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a>
|
||||
<strong id="grammar-token-lambda_expr_nocond">lambda_expr_nocond</strong> ::= "lambda" [<a class="reference internal" href="compound_stmts.html#grammar-token-parameter_list"><tt class="xref docutils literal"><span class="pre">parameter_list</span></tt></a>]: <a class="reference internal" href="#grammar-token-expression_nocond"><tt class="xref docutils literal"><span class="pre">expression_nocond</span></tt></a>
|
||||
</pre>
|
||||
<p>Lambda expressions (sometimes called lambda forms) are used to create anonymous
|
||||
functions. The expression <tt class="docutils literal"><span class="pre">lambda</span> <span class="pre">arguments:</span> <span class="pre">expression</span></tt> yields a function
|
||||
object. The unnamed object behaves like a function object defined with</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre>def <lambda>(arguments):
|
||||
return expression
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>See section <a class="reference internal" href="compound_stmts.html#function"><em>Function definitions</em></a> for the syntax of parameter lists. Note that
|
||||
functions created with lambda expressions cannot contain statements or
|
||||
annotations.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,25 @@
|
||||
<div class="section" id="the-nonlocal-statement">
|
||||
<span id="nonlocal"></span><h2>The <a class="reference internal" href="#nonlocal"><tt class="xref std std-keyword docutils literal"><span class="pre">nonlocal</span></tt></a> statement</h2>
|
||||
<pre id="index-41">
|
||||
<strong id="grammar-token-nonlocal_stmt">nonlocal_stmt</strong> ::= "nonlocal" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ("," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>)*
|
||||
</pre>
|
||||
<p>The <a class="reference internal" href="#nonlocal"><tt class="xref std std-keyword docutils literal"><span class="pre">nonlocal</span></tt></a> statement causes the listed identifiers to refer to
|
||||
previously bound variables in the nearest enclosing scope excluding globals.
|
||||
This is important because the default behavior for binding is to search the
|
||||
local namespace first. The statement allows encapsulated code to rebind
|
||||
variables outside of the local scope besides the global (module) scope.</p>
|
||||
<p>Names listed in a <a class="reference internal" href="#nonlocal"><tt class="xref std std-keyword docutils literal"><span class="pre">nonlocal</span></tt></a> statement, unlike those listed in a
|
||||
<a class="reference internal" href="#global"><tt class="xref std std-keyword docutils literal"><span class="pre">global</span></tt></a> statement, must refer to pre-existing bindings in an
|
||||
enclosing scope (the scope in which a new binding should be created cannot
|
||||
be determined unambiguously).</p>
|
||||
<p>Names listed in a <a class="reference internal" href="#nonlocal"><tt class="xref std std-keyword docutils literal"><span class="pre">nonlocal</span></tt></a> statement must not collide with
|
||||
pre-existing bindings in the local scope.</p>
|
||||
<div class="admonition seealso">
|
||||
<p class="first admonition-title">See also</p>
|
||||
<dl class="last docutils">
|
||||
<dt><span class="target" id="index-42"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-3104"><strong>PEP 3104</strong></a> - Access to Names in Outer Scopes</dt>
|
||||
<dd>The specification for the <a class="reference internal" href="#nonlocal"><tt class="xref std std-keyword docutils literal"><span class="pre">nonlocal</span></tt></a> statement.</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -0,0 +1,27 @@
|
||||
<div class="section" id="boolean-operations">
|
||||
<span id="not"></span><span id="or"></span><span id="and"></span><span id="booleans"></span><h2>Boolean operations</h2>
|
||||
<pre id="index-65">
|
||||
<strong id="grammar-token-or_test">or_test </strong> ::= <a class="reference internal" href="#grammar-token-and_test"><tt class="xref docutils literal"><span class="pre">and_test</span></tt></a> | <a class="reference internal" href="#grammar-token-or_test"><tt class="xref docutils literal"><span class="pre">or_test</span></tt></a> "or" <a class="reference internal" href="#grammar-token-and_test"><tt class="xref docutils literal"><span class="pre">and_test</span></tt></a>
|
||||
<strong id="grammar-token-and_test">and_test</strong> ::= <a class="reference internal" href="#grammar-token-not_test"><tt class="xref docutils literal"><span class="pre">not_test</span></tt></a> | <a class="reference internal" href="#grammar-token-and_test"><tt class="xref docutils literal"><span class="pre">and_test</span></tt></a> "and" <a class="reference internal" href="#grammar-token-not_test"><tt class="xref docutils literal"><span class="pre">not_test</span></tt></a>
|
||||
<strong id="grammar-token-not_test">not_test</strong> ::= <a class="reference internal" href="#grammar-token-comparison"><tt class="xref docutils literal"><span class="pre">comparison</span></tt></a> | "not" <a class="reference internal" href="#grammar-token-not_test"><tt class="xref docutils literal"><span class="pre">not_test</span></tt></a>
|
||||
</pre>
|
||||
<p>In the context of Boolean operations, and also when expressions are used by
|
||||
control flow statements, the following values are interpreted as false:
|
||||
<tt class="docutils literal"><span class="pre">False</span></tt>, <tt class="docutils literal"><span class="pre">None</span></tt>, numeric zero of all types, and empty strings and containers
|
||||
(including strings, tuples, lists, dictionaries, sets and frozensets). All
|
||||
other values are interpreted as true. User-defined objects can customize their
|
||||
truth value by providing a <a class="reference internal" href="datamodel.html#object.__bool__" title="object.__bool__"><tt class="xref py py-meth docutils literal"><span class="pre">__bool__()</span></tt></a> method.</p>
|
||||
<p id="index-66">The operator <a class="reference internal" href="#not"><tt class="xref std std-keyword docutils literal"><span class="pre">not</span></tt></a> yields <tt class="docutils literal"><span class="pre">True</span></tt> if its argument is false, <tt class="docutils literal"><span class="pre">False</span></tt>
|
||||
otherwise.</p>
|
||||
<p id="index-67">The expression <tt class="docutils literal"><span class="pre">x</span> <span class="pre">and</span> <span class="pre">y</span></tt> first evaluates <em>x</em>; if <em>x</em> is false, its value is
|
||||
returned; otherwise, <em>y</em> is evaluated and the resulting value is returned.</p>
|
||||
<p id="index-68">The expression <tt class="docutils literal"><span class="pre">x</span> <span class="pre">or</span> <span class="pre">y</span></tt> first evaluates <em>x</em>; if <em>x</em> is true, its value is
|
||||
returned; otherwise, <em>y</em> is evaluated and the resulting value is returned.</p>
|
||||
<p>(Note that neither <a class="reference internal" href="#and"><tt class="xref std std-keyword docutils literal"><span class="pre">and</span></tt></a> nor <a class="reference internal" href="#or"><tt class="xref std std-keyword docutils literal"><span class="pre">or</span></tt></a> restrict the value and type
|
||||
they return to <tt class="docutils literal"><span class="pre">False</span></tt> and <tt class="docutils literal"><span class="pre">True</span></tt>, but rather return the last evaluated
|
||||
argument. This is sometimes useful, e.g., if <tt class="docutils literal"><span class="pre">s</span></tt> is a string that should be
|
||||
replaced by a default value if it is empty, the expression <tt class="docutils literal"><span class="pre">s</span> <span class="pre">or</span> <span class="pre">'foo'</span></tt> yields
|
||||
the desired value. Because <a class="reference internal" href="#not"><tt class="xref std std-keyword docutils literal"><span class="pre">not</span></tt></a> has to create a new value, it
|
||||
returns a boolean value regardless of the type of its argument
|
||||
(for example, <tt class="docutils literal"><span class="pre">not</span> <span class="pre">'foo'</span></tt> produces <tt class="docutils literal"><span class="pre">False</span></tt> rather than <tt class="docutils literal"><span class="pre">''</span></tt>.)</p>
|
||||
</div>
|
||||
@@ -0,0 +1,27 @@
|
||||
<div class="section" id="boolean-operations">
|
||||
<span id="not"></span><span id="or"></span><span id="and"></span><span id="booleans"></span><h2>Boolean operations</h2>
|
||||
<pre id="index-65">
|
||||
<strong id="grammar-token-or_test">or_test </strong> ::= <a class="reference internal" href="#grammar-token-and_test"><tt class="xref docutils literal"><span class="pre">and_test</span></tt></a> | <a class="reference internal" href="#grammar-token-or_test"><tt class="xref docutils literal"><span class="pre">or_test</span></tt></a> "or" <a class="reference internal" href="#grammar-token-and_test"><tt class="xref docutils literal"><span class="pre">and_test</span></tt></a>
|
||||
<strong id="grammar-token-and_test">and_test</strong> ::= <a class="reference internal" href="#grammar-token-not_test"><tt class="xref docutils literal"><span class="pre">not_test</span></tt></a> | <a class="reference internal" href="#grammar-token-and_test"><tt class="xref docutils literal"><span class="pre">and_test</span></tt></a> "and" <a class="reference internal" href="#grammar-token-not_test"><tt class="xref docutils literal"><span class="pre">not_test</span></tt></a>
|
||||
<strong id="grammar-token-not_test">not_test</strong> ::= <a class="reference internal" href="#grammar-token-comparison"><tt class="xref docutils literal"><span class="pre">comparison</span></tt></a> | "not" <a class="reference internal" href="#grammar-token-not_test"><tt class="xref docutils literal"><span class="pre">not_test</span></tt></a>
|
||||
</pre>
|
||||
<p>In the context of Boolean operations, and also when expressions are used by
|
||||
control flow statements, the following values are interpreted as false:
|
||||
<tt class="docutils literal"><span class="pre">False</span></tt>, <tt class="docutils literal"><span class="pre">None</span></tt>, numeric zero of all types, and empty strings and containers
|
||||
(including strings, tuples, lists, dictionaries, sets and frozensets). All
|
||||
other values are interpreted as true. User-defined objects can customize their
|
||||
truth value by providing a <a class="reference internal" href="datamodel.html#object.__bool__" title="object.__bool__"><tt class="xref py py-meth docutils literal"><span class="pre">__bool__()</span></tt></a> method.</p>
|
||||
<p id="index-66">The operator <a class="reference internal" href="#not"><tt class="xref std std-keyword docutils literal"><span class="pre">not</span></tt></a> yields <tt class="docutils literal"><span class="pre">True</span></tt> if its argument is false, <tt class="docutils literal"><span class="pre">False</span></tt>
|
||||
otherwise.</p>
|
||||
<p id="index-67">The expression <tt class="docutils literal"><span class="pre">x</span> <span class="pre">and</span> <span class="pre">y</span></tt> first evaluates <em>x</em>; if <em>x</em> is false, its value is
|
||||
returned; otherwise, <em>y</em> is evaluated and the resulting value is returned.</p>
|
||||
<p id="index-68">The expression <tt class="docutils literal"><span class="pre">x</span> <span class="pre">or</span> <span class="pre">y</span></tt> first evaluates <em>x</em>; if <em>x</em> is true, its value is
|
||||
returned; otherwise, <em>y</em> is evaluated and the resulting value is returned.</p>
|
||||
<p>(Note that neither <a class="reference internal" href="#and"><tt class="xref std std-keyword docutils literal"><span class="pre">and</span></tt></a> nor <a class="reference internal" href="#or"><tt class="xref std std-keyword docutils literal"><span class="pre">or</span></tt></a> restrict the value and type
|
||||
they return to <tt class="docutils literal"><span class="pre">False</span></tt> and <tt class="docutils literal"><span class="pre">True</span></tt>, but rather return the last evaluated
|
||||
argument. This is sometimes useful, e.g., if <tt class="docutils literal"><span class="pre">s</span></tt> is a string that should be
|
||||
replaced by a default value if it is empty, the expression <tt class="docutils literal"><span class="pre">s</span> <span class="pre">or</span> <span class="pre">'foo'</span></tt> yields
|
||||
the desired value. Because <a class="reference internal" href="#not"><tt class="xref std std-keyword docutils literal"><span class="pre">not</span></tt></a> has to create a new value, it
|
||||
returns a boolean value regardless of the type of its argument
|
||||
(for example, <tt class="docutils literal"><span class="pre">not</span> <span class="pre">'foo'</span></tt> produces <tt class="docutils literal"><span class="pre">False</span></tt> rather than <tt class="docutils literal"><span class="pre">''</span></tt>.)</p>
|
||||
</div>
|
||||
@@ -0,0 +1,14 @@
|
||||
<div class="section" id="the-pass-statement">
|
||||
<span id="pass"></span><h2>The <a class="reference internal" href="#pass"><tt class="xref std std-keyword docutils literal"><span class="pre">pass</span></tt></a> statement</h2>
|
||||
<pre id="index-17">
|
||||
<strong id="grammar-token-pass_stmt">pass_stmt</strong> ::= "pass"
|
||||
</pre>
|
||||
<p><a class="reference internal" href="#pass"><tt class="xref std std-keyword docutils literal"><span class="pre">pass</span></tt></a> is a null operation — when it is executed, nothing happens.
|
||||
It is useful as a placeholder when a statement is required syntactically, but no
|
||||
code needs to be executed, for example:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span> <span class="k">pass</span> <span class="c"># a function that does nothing (yet)</span>
|
||||
|
||||
<span class="k">class</span> <span class="nc">C</span><span class="p">:</span> <span class="k">pass</span> <span class="c"># a class with no methods (yet)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -0,0 +1,66 @@
|
||||
<div class="section" id="the-raise-statement">
|
||||
<span id="raise"></span><h2>The <a class="reference internal" href="#raise"><tt class="xref std std-keyword docutils literal"><span class="pre">raise</span></tt></a> statement</h2>
|
||||
<pre id="index-24">
|
||||
<strong id="grammar-token-raise_stmt">raise_stmt</strong> ::= "raise" [<a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ["from" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a>]]
|
||||
</pre>
|
||||
<p>If no expressions are present, <a class="reference internal" href="#raise"><tt class="xref std std-keyword docutils literal"><span class="pre">raise</span></tt></a> re-raises the last exception
|
||||
that was active in the current scope. If no exception is active in the current
|
||||
scope, a <a class="reference internal" href="../library/exceptions.html#RuntimeError" title="RuntimeError"><tt class="xref py py-exc docutils literal"><span class="pre">RuntimeError</span></tt></a> exception is raised indicating that this is an
|
||||
error.</p>
|
||||
<p>Otherwise, <a class="reference internal" href="#raise"><tt class="xref std std-keyword docutils literal"><span class="pre">raise</span></tt></a> evaluates the first expression as the exception
|
||||
object. It must be either a subclass or an instance of <a class="reference internal" href="../library/exceptions.html#BaseException" title="BaseException"><tt class="xref py py-class docutils literal"><span class="pre">BaseException</span></tt></a>.
|
||||
If it is a class, the exception instance will be obtained when needed by
|
||||
instantiating the class with no arguments.</p>
|
||||
<p>The <em class="dfn">type</em> of the exception is the exception instance’s class, the
|
||||
<em class="dfn">value</em> is the instance itself.</p>
|
||||
<p id="index-25">A traceback object is normally created automatically when an exception is raised
|
||||
and attached to it as the <tt class="xref py py-attr docutils literal"><span class="pre">__traceback__</span></tt> attribute, which is writable.
|
||||
You can create an exception and set your own traceback in one step using the
|
||||
<tt class="xref py py-meth docutils literal"><span class="pre">with_traceback()</span></tt> exception method (which returns the same exception
|
||||
instance, with its traceback set to its argument), like so:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s">"foo occurred"</span><span class="p">)</span><span class="o">.</span><span class="n">with_traceback</span><span class="p">(</span><span class="n">tracebackobj</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p id="index-26">The <tt class="docutils literal"><span class="pre">from</span></tt> clause is used for exception chaining: if given, the second
|
||||
<em>expression</em> must be another exception class or instance, which will then be
|
||||
attached to the raised exception as the <tt class="xref py py-attr docutils literal"><span class="pre">__cause__</span></tt> attribute (which is
|
||||
writable). If the raised exception is not handled, both exceptions will be
|
||||
printed:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="nb">print</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="gp">... </span><span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s">"Something bad happened"</span><span class="p">)</span> <span class="kn">from</span> <span class="nn">exc</span>
|
||||
<span class="gp">...</span>
|
||||
<span class="gt">Traceback (most recent call last):</span>
|
||||
File <span class="nb">"<stdin>"</span>, line <span class="m">2</span>, in <span class="n"><module></span>
|
||||
<span class="gr">ZeroDivisionError</span>: <span class="n">int division or modulo by zero</span>
|
||||
|
||||
<span class="go">The above exception was the direct cause of the following exception:</span>
|
||||
|
||||
<span class="gt">Traceback (most recent call last):</span>
|
||||
File <span class="nb">"<stdin>"</span>, line <span class="m">4</span>, in <span class="n"><module></span>
|
||||
<span class="gr">RuntimeError</span>: <span class="n">Something bad happened</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>A similar mechanism works implicitly if an exception is raised inside an
|
||||
exception handler or a <a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause: the previous exception is then
|
||||
attached as the new exception’s <tt class="xref py py-attr docutils literal"><span class="pre">__context__</span></tt> attribute:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="nb">print</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="gp">... </span><span class="k">except</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s">"Something bad happened"</span><span class="p">)</span>
|
||||
<span class="gp">...</span>
|
||||
<span class="gt">Traceback (most recent call last):</span>
|
||||
File <span class="nb">"<stdin>"</span>, line <span class="m">2</span>, in <span class="n"><module></span>
|
||||
<span class="gr">ZeroDivisionError</span>: <span class="n">int division or modulo by zero</span>
|
||||
|
||||
<span class="go">During handling of the above exception, another exception occurred:</span>
|
||||
|
||||
<span class="gt">Traceback (most recent call last):</span>
|
||||
File <span class="nb">"<stdin>"</span>, line <span class="m">4</span>, in <span class="n"><module></span>
|
||||
<span class="gr">RuntimeError</span>: <span class="n">Something bad happened</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Additional information on exceptions can be found in section <a class="reference internal" href="executionmodel.html#exceptions"><em>Exceptions</em></a>,
|
||||
and information about handling exceptions is in section <a class="reference internal" href="compound_stmts.html#try"><em>The try statement</em></a>.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,18 @@
|
||||
<div class="section" id="the-return-statement">
|
||||
<span id="return"></span><h2>The <a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> statement</h2>
|
||||
<pre id="index-21">
|
||||
<strong id="grammar-token-return_stmt">return_stmt</strong> ::= "return" [<a class="reference internal" href="expressions.html#grammar-token-expression_list"><tt class="xref docutils literal"><span class="pre">expression_list</span></tt></a>]
|
||||
</pre>
|
||||
<p><a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> may only occur syntactically nested in a function definition,
|
||||
not within a nested class definition.</p>
|
||||
<p>If an expression list is present, it is evaluated, else <tt class="docutils literal"><span class="pre">None</span></tt> is substituted.</p>
|
||||
<p><a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> leaves the current function call with the expression list (or
|
||||
<tt class="docutils literal"><span class="pre">None</span></tt>) as return value.</p>
|
||||
<p id="index-22">When <a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> passes control out of a <a class="reference internal" href="compound_stmts.html#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement with a
|
||||
<a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause, that <a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause is executed before
|
||||
really leaving the function.</p>
|
||||
<p>In a generator function, the <a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> statement indicates that the
|
||||
generator is done and will cause <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><tt class="xref py py-exc docutils literal"><span class="pre">StopIteration</span></tt></a> to be raised. The returned
|
||||
value (if any) is used as an argument to construct <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><tt class="xref py py-exc docutils literal"><span class="pre">StopIteration</span></tt></a> and
|
||||
becomes the <tt class="xref py py-attr docutils literal"><span class="pre">StopIteration.value</span></tt> attribute.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,109 @@
|
||||
<div class="section" id="the-try-statement">
|
||||
<span id="finally"></span><span id="except"></span><span id="try"></span><h2>The <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement</h2>
|
||||
<span class="target" id="index-10"></span><p id="index-11">The <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement specifies exception handlers and/or cleanup code
|
||||
for a group of statements:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-try_stmt">try_stmt </strong> ::= try1_stmt | try2_stmt
|
||||
<strong id="grammar-token-try1_stmt">try1_stmt</strong> ::= "try" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
("except" [<a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ["as" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>]] ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>)+
|
||||
["else" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
["finally" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
<strong id="grammar-token-try2_stmt">try2_stmt</strong> ::= "try" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
"finally" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
</pre>
|
||||
<p>The <a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a> clause(s) specify one or more exception handlers. When no
|
||||
exception occurs in the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> clause, no exception handler is executed.
|
||||
When an exception occurs in the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> suite, a search for an exception
|
||||
handler is started. This search inspects the except clauses in turn until one
|
||||
is found that matches the exception. An expression-less except clause, if
|
||||
present, must be last; it matches any exception. For an except clause with an
|
||||
expression, that expression is evaluated, and the clause matches the exception
|
||||
if the resulting object is “compatible” with the exception. An object is
|
||||
compatible with an exception if it is the class or a base class of the exception
|
||||
object or a tuple containing an item compatible with the exception.</p>
|
||||
<p>If no except clause matches the exception, the search for an exception handler
|
||||
continues in the surrounding code and on the invocation stack. <a class="footnote-reference" href="#id5" id="id1">[1]</a></p>
|
||||
<p>If the evaluation of an expression in the header of an except clause raises an
|
||||
exception, the original search for a handler is canceled and a search starts for
|
||||
the new exception in the surrounding code and on the call stack (it is treated
|
||||
as if the entire <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement raised the exception).</p>
|
||||
<p>When a matching except clause is found, the exception is assigned to the target
|
||||
specified after the <a class="reference internal" href="#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> keyword in that except clause, if present, and
|
||||
the except clause’s suite is executed. All except clauses must have an
|
||||
executable block. When the end of this block is reached, execution continues
|
||||
normally after the entire try statement. (This means that if two nested
|
||||
handlers exist for the same exception, and the exception occurs in the try
|
||||
clause of the inner handler, the outer handler will not handle the exception.)</p>
|
||||
<p>When an exception has been assigned using <tt class="docutils literal"><span class="pre">as</span> <span class="pre">target</span></tt>, it is cleared at the
|
||||
end of the except clause. This is as if</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">except</span> <span class="n">E</span> <span class="k">as</span> <span class="n">N</span><span class="p">:</span>
|
||||
<span class="n">foo</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>was translated to</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">except</span> <span class="n">E</span> <span class="k">as</span> <span class="n">N</span><span class="p">:</span>
|
||||
<span class="k">try</span><span class="p">:</span>
|
||||
<span class="n">foo</span>
|
||||
<span class="k">finally</span><span class="p">:</span>
|
||||
<span class="k">del</span> <span class="n">N</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This means the exception must be assigned to a different name to be able to
|
||||
refer to it after the except clause. Exceptions are cleared because with the
|
||||
traceback attached to them, they form a reference cycle with the stack frame,
|
||||
keeping all locals in that frame alive until the next garbage collection occurs.</p>
|
||||
<p id="index-12">Before an except clause’s suite is executed, details about the exception are
|
||||
stored in the <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><tt class="xref py py-mod docutils literal"><span class="pre">sys</span></tt></a> module and can be accessed via <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><tt class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></tt></a>.
|
||||
<a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><tt class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></tt></a> returns a 3-tuple consisting of the exception class, the
|
||||
exception instance and a traceback object (see section <a class="reference internal" href="datamodel.html#types"><em>The standard type hierarchy</em></a>) identifying
|
||||
the point in the program where the exception occurred. <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><tt class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></tt></a>
|
||||
values are restored to their previous values (before the call) when returning
|
||||
from a function that handled an exception.</p>
|
||||
<p id="index-13">The optional <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause is executed if and when control flows off
|
||||
the end of the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> clause. <a class="footnote-reference" href="#id6" id="id2">[2]</a> Exceptions in the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a>
|
||||
clause are not handled by the preceding <a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a> clauses.</p>
|
||||
<p id="index-14">If <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> is present, it specifies a ‘cleanup’ handler. The
|
||||
<a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> clause is executed, including any <a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a> and
|
||||
<a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clauses. If an exception occurs in any of the clauses and is
|
||||
not handled, the exception is temporarily saved. The <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause
|
||||
is executed. If there is a saved exception it is re-raised at the end of the
|
||||
<a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause. If the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause raises another
|
||||
exception, the saved exception is set as the context of the new exception.
|
||||
If the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause executes a <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> or <a class="reference internal" href="simple_stmts.html#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a>
|
||||
statement, the saved exception is discarded:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
|
||||
<span class="gp">... </span> <span class="k">try</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="mi">1</span><span class="o">/</span><span class="mi">0</span>
|
||||
<span class="gp">... </span> <span class="k">finally</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">return</span> <span class="mi">42</span>
|
||||
<span class="gp">...</span>
|
||||
<span class="gp">>>> </span><span class="n">f</span><span class="p">()</span>
|
||||
<span class="go">42</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The exception information is not available to the program during execution of
|
||||
the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause.</p>
|
||||
<p id="index-15">When a <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a>, <a class="reference internal" href="simple_stmts.html#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a> or <a class="reference internal" href="simple_stmts.html#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a> statement is
|
||||
executed in the <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> suite of a <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a>...<a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a>
|
||||
statement, the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause is also executed ‘on the way out.’ A
|
||||
<a class="reference internal" href="simple_stmts.html#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a> statement is illegal in the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause. (The
|
||||
reason is a problem with the current implementation — this restriction may be
|
||||
lifted in the future).</p>
|
||||
<p>The return value of a function is determined by the last <a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a>
|
||||
statement executed. Since the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause always executes, a
|
||||
<a class="reference internal" href="simple_stmts.html#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> statement executed in the <a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause will
|
||||
always be the last one executed:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">foo</span><span class="p">():</span>
|
||||
<span class="gp">... </span> <span class="k">try</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">return</span> <span class="s">'try'</span>
|
||||
<span class="gp">... </span> <span class="k">finally</span><span class="p">:</span>
|
||||
<span class="gp">... </span> <span class="k">return</span> <span class="s">'finally'</span>
|
||||
<span class="gp">...</span>
|
||||
<span class="gp">>>> </span><span class="n">foo</span><span class="p">()</span>
|
||||
<span class="go">'finally'</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Additional information on exceptions can be found in section <a class="reference internal" href="executionmodel.html#exceptions"><em>Exceptions</em></a>,
|
||||
and information on using the <a class="reference internal" href="simple_stmts.html#raise"><tt class="xref std std-keyword docutils literal"><span class="pre">raise</span></tt></a> statement to generate exceptions
|
||||
may be found in section <a class="reference internal" href="simple_stmts.html#raise"><em>The raise statement</em></a>.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,17 @@
|
||||
<div class="section" id="the-while-statement">
|
||||
<span id="while"></span><h2>The <a class="reference internal" href="#while"><tt class="xref std std-keyword docutils literal"><span class="pre">while</span></tt></a> statement</h2>
|
||||
<p id="index-4">The <a class="reference internal" href="#while"><tt class="xref std std-keyword docutils literal"><span class="pre">while</span></tt></a> statement is used for repeated execution as long as an
|
||||
expression is true:</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-while_stmt">while_stmt</strong> ::= "while" <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
["else" ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>]
|
||||
</pre>
|
||||
<p>This repeatedly tests the expression and, if it is true, executes the first
|
||||
suite; if the expression is false (which may be the first time it is tested) the
|
||||
suite of the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause, if present, is executed and the loop
|
||||
terminates.</p>
|
||||
<p id="index-5">A <a class="reference internal" href="simple_stmts.html#break"><tt class="xref std std-keyword docutils literal"><span class="pre">break</span></tt></a> statement executed in the first suite terminates the loop
|
||||
without executing the <a class="reference internal" href="#else"><tt class="xref std std-keyword docutils literal"><span class="pre">else</span></tt></a> clause’s suite. A <a class="reference internal" href="simple_stmts.html#continue"><tt class="xref std std-keyword docutils literal"><span class="pre">continue</span></tt></a>
|
||||
statement executed in the first suite skips the rest of the suite and goes back
|
||||
to testing the expression.</p>
|
||||
</div>
|
||||
@@ -0,0 +1,69 @@
|
||||
<div class="section" id="the-with-statement">
|
||||
<span id="as"></span><span id="with"></span><h2>The <a class="reference internal" href="#with"><tt class="xref std std-keyword docutils literal"><span class="pre">with</span></tt></a> statement</h2>
|
||||
<p id="index-16">The <a class="reference internal" href="#with"><tt class="xref std std-keyword docutils literal"><span class="pre">with</span></tt></a> statement is used to wrap the execution of a block with
|
||||
methods defined by a context manager (see section <a class="reference internal" href="datamodel.html#context-managers"><em>With Statement Context Managers</em></a>).
|
||||
This allows common <a class="reference internal" href="#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a>...<a class="reference internal" href="#except"><tt class="xref std std-keyword docutils literal"><span class="pre">except</span></tt></a>...<a class="reference internal" href="#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a>
|
||||
usage patterns to be encapsulated for convenient reuse.</p>
|
||||
<pre>
|
||||
<strong id="grammar-token-with_stmt">with_stmt</strong> ::= "with" with_item ("," with_item)* ":" <a class="reference internal" href="#grammar-token-suite"><tt class="xref docutils literal"><span class="pre">suite</span></tt></a>
|
||||
<strong id="grammar-token-with_item">with_item</strong> ::= <a class="reference internal" href="expressions.html#grammar-token-expression"><tt class="xref docutils literal"><span class="pre">expression</span></tt></a> ["as" <a class="reference internal" href="simple_stmts.html#grammar-token-target"><tt class="xref docutils literal"><span class="pre">target</span></tt></a>]
|
||||
</pre>
|
||||
<p>The execution of the <a class="reference internal" href="#with"><tt class="xref std std-keyword docutils literal"><span class="pre">with</span></tt></a> statement with one “item” proceeds as follows:</p>
|
||||
<ol class="arabic">
|
||||
<li><p class="first">The context expression (the expression given in the <a class="reference internal" href="#grammar-token-with_item"><tt class="xref std std-token docutils literal"><span class="pre">with_item</span></tt></a>) is
|
||||
evaluated to obtain a context manager.</p>
|
||||
</li>
|
||||
<li><p class="first">The context manager’s <a class="reference internal" href="datamodel.html#object.__exit__" title="object.__exit__"><tt class="xref py py-meth docutils literal"><span class="pre">__exit__()</span></tt></a> is loaded for later use.</p>
|
||||
</li>
|
||||
<li><p class="first">The context manager’s <a class="reference internal" href="datamodel.html#object.__enter__" title="object.__enter__"><tt class="xref py py-meth docutils literal"><span class="pre">__enter__()</span></tt></a> method is invoked.</p>
|
||||
</li>
|
||||
<li><p class="first">If a target was included in the <a class="reference internal" href="#with"><tt class="xref std std-keyword docutils literal"><span class="pre">with</span></tt></a> statement, the return value
|
||||
from <a class="reference internal" href="datamodel.html#object.__enter__" title="object.__enter__"><tt class="xref py py-meth docutils literal"><span class="pre">__enter__()</span></tt></a> is assigned to it.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">The <a class="reference internal" href="#with"><tt class="xref std std-keyword docutils literal"><span class="pre">with</span></tt></a> statement guarantees that if the <a class="reference internal" href="datamodel.html#object.__enter__" title="object.__enter__"><tt class="xref py py-meth docutils literal"><span class="pre">__enter__()</span></tt></a>
|
||||
method returns without an error, then <a class="reference internal" href="datamodel.html#object.__exit__" title="object.__exit__"><tt class="xref py py-meth docutils literal"><span class="pre">__exit__()</span></tt></a> will always be
|
||||
called. Thus, if an error occurs during the assignment to the target list,
|
||||
it will be treated the same as an error occurring within the suite would
|
||||
be. See step 6 below.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li><p class="first">The suite is executed.</p>
|
||||
</li>
|
||||
<li><p class="first">The context manager’s <a class="reference internal" href="datamodel.html#object.__exit__" title="object.__exit__"><tt class="xref py py-meth docutils literal"><span class="pre">__exit__()</span></tt></a> method is invoked. If an exception
|
||||
caused the suite to be exited, its type, value, and traceback are passed as
|
||||
arguments to <a class="reference internal" href="datamodel.html#object.__exit__" title="object.__exit__"><tt class="xref py py-meth docutils literal"><span class="pre">__exit__()</span></tt></a>. Otherwise, three <a class="reference internal" href="../library/constants.html#None" title="None"><tt class="xref py py-const docutils literal"><span class="pre">None</span></tt></a> arguments are
|
||||
supplied.</p>
|
||||
<p>If the suite was exited due to an exception, and the return value from the
|
||||
<a class="reference internal" href="datamodel.html#object.__exit__" title="object.__exit__"><tt class="xref py py-meth docutils literal"><span class="pre">__exit__()</span></tt></a> method was false, the exception is reraised. If the return
|
||||
value was true, the exception is suppressed, and execution continues with the
|
||||
statement following the <a class="reference internal" href="#with"><tt class="xref std std-keyword docutils literal"><span class="pre">with</span></tt></a> statement.</p>
|
||||
<p>If the suite was exited for any reason other than an exception, the return
|
||||
value from <a class="reference internal" href="datamodel.html#object.__exit__" title="object.__exit__"><tt class="xref py py-meth docutils literal"><span class="pre">__exit__()</span></tt></a> is ignored, and execution proceeds at the normal
|
||||
location for the kind of exit that was taken.</p>
|
||||
</li>
|
||||
</ol>
|
||||
<p>With more than one item, the context managers are processed as if multiple
|
||||
<a class="reference internal" href="#with"><tt class="xref std std-keyword docutils literal"><span class="pre">with</span></tt></a> statements were nested:</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">with</span> <span class="n">A</span><span class="p">()</span> <span class="k">as</span> <span class="n">a</span><span class="p">,</span> <span class="n">B</span><span class="p">()</span> <span class="k">as</span> <span class="n">b</span><span class="p">:</span>
|
||||
<span class="n">suite</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>is equivalent to</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">with</span> <span class="n">A</span><span class="p">()</span> <span class="k">as</span> <span class="n">a</span><span class="p">:</span>
|
||||
<span class="k">with</span> <span class="n">B</span><span class="p">()</span> <span class="k">as</span> <span class="n">b</span><span class="p">:</span>
|
||||
<span class="n">suite</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified">Changed in version 3.1: </span>Support for multiple context expressions.</p>
|
||||
</div>
|
||||
<div class="admonition seealso">
|
||||
<p class="first admonition-title">See also</p>
|
||||
<dl class="last docutils">
|
||||
<dt><span class="target" id="index-17"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0343"><strong>PEP 0343</strong></a> - The “with” statement</dt>
|
||||
<dd>The specification, background, and examples for the Python <a class="reference internal" href="#with"><tt class="xref std std-keyword docutils literal"><span class="pre">with</span></tt></a>
|
||||
statement.</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
@@ -0,0 +1,25 @@
|
||||
<div class="section" id="the-yield-statement">
|
||||
<span id="yield"></span><h2>The <a class="reference internal" href="#yield"><tt class="xref std std-keyword docutils literal"><span class="pre">yield</span></tt></a> statement</h2>
|
||||
<pre id="index-23">
|
||||
<strong id="grammar-token-yield_stmt">yield_stmt</strong> ::= <a class="reference internal" href="expressions.html#grammar-token-yield_expression"><tt class="xref docutils literal"><span class="pre">yield_expression</span></tt></a>
|
||||
</pre>
|
||||
<p>A <a class="reference internal" href="#yield"><tt class="xref std std-keyword docutils literal"><span class="pre">yield</span></tt></a> statement is semantically equivalent to a <a class="reference internal" href="expressions.html#yieldexpr"><em>yield
|
||||
expression</em></a>. The yield statement can be used to omit the parentheses
|
||||
that would otherwise be required in the equivalent yield expression
|
||||
statement. For example, the yield statements</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="k">yield</span> <span class="o"><</span><span class="n">expr</span><span class="o">></span>
|
||||
<span class="k">yield from</span> <span class="o"><</span><span class="n">expr</span><span class="o">></span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>are equivalent to the yield expression statements</p>
|
||||
<div class="highlight-python3"><div class="highlight"><pre><span class="p">(</span><span class="k">yield</span> <span class="o"><</span><span class="n">expr</span><span class="o">></span><span class="p">)</span>
|
||||
<span class="p">(</span><span class="k">yield from</span> <span class="o"><</span><span class="n">expr</span><span class="o">></span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Yield expressions and statements are only used when defining a <a class="reference internal" href="../glossary.html#term-generator"><em class="xref std std-term">generator</em></a>
|
||||
function, and are only used in the body of the generator function. Using yield
|
||||
in a function definition is sufficient to cause that definition to create a
|
||||
generator function instead of a normal function.</p>
|
||||
<p>For full details of <a class="reference internal" href="#yield"><tt class="xref std std-keyword docutils literal"><span class="pre">yield</span></tt></a> semantics, refer to the
|
||||
<a class="reference internal" href="expressions.html#yieldexpr"><em>Yield expressions</em></a> section.</p>
|
||||
</div>
|
||||
@@ -19,6 +19,7 @@ import com.intellij.openapi.module.Module;
|
||||
import com.intellij.openapi.project.Project;
|
||||
import com.intellij.openapi.projectRoots.Sdk;
|
||||
import com.intellij.openapi.util.Pair;
|
||||
import com.intellij.openapi.util.io.FileUtil;
|
||||
import com.intellij.openapi.util.text.LineTokenizer;
|
||||
import com.intellij.openapi.util.text.StringUtil;
|
||||
import com.intellij.openapi.vfs.VfsUtilCore;
|
||||
@@ -27,9 +28,7 @@ import com.intellij.psi.PsiElement;
|
||||
import com.intellij.psi.codeStyle.CodeStyleSettingsManager;
|
||||
import com.intellij.psi.util.PsiTreeUtil;
|
||||
import com.intellij.util.ArrayUtil;
|
||||
import com.jetbrains.python.PyBundle;
|
||||
import com.jetbrains.python.PyNames;
|
||||
import com.jetbrains.python.PythonFileType;
|
||||
import com.jetbrains.python.*;
|
||||
import com.jetbrains.python.console.PyConsoleUtil;
|
||||
import com.jetbrains.python.psi.*;
|
||||
import com.jetbrains.python.psi.impl.PyBuiltinCache;
|
||||
@@ -45,6 +44,9 @@ import com.jetbrains.python.toolbox.Maybe;
|
||||
import org.jetbrains.annotations.NotNull;
|
||||
import org.jetbrains.annotations.Nullable;
|
||||
|
||||
import java.io.FileNotFoundException;
|
||||
import java.io.FileReader;
|
||||
import java.io.IOException;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.regex.Matcher;
|
||||
@@ -100,6 +102,11 @@ class PyDocumentationBuilder {
|
||||
myBody.addItem(combUp("\nInferred type: "));
|
||||
PythonDocumentationProvider.describeExpressionTypeWithLinks(myBody, (PyReferenceExpression)outerElement, context);
|
||||
}
|
||||
|
||||
if (elementDefinition != null &&
|
||||
PythonDialectsTokenSetProvider.INSTANCE.getKeywordTokens().contains(elementDefinition.getNode().getElementType())) {
|
||||
buildForKeyword(elementDefinition.getText());
|
||||
}
|
||||
if (myBody.isEmpty() && myEpilog.isEmpty()) {
|
||||
return null; // got nothing substantial to say!
|
||||
}
|
||||
@@ -108,6 +115,27 @@ class PyDocumentationBuilder {
|
||||
}
|
||||
}
|
||||
|
||||
private void buildForKeyword(@NotNull final String name) {
|
||||
try {
|
||||
final FileReader reader = new FileReader(PythonHelpersLocator.getHelperPath("/tools/python_keywords/" + name));
|
||||
try {
|
||||
final String text = FileUtil.loadTextAndClose(reader);
|
||||
myEpilog.addItem(text);
|
||||
}
|
||||
catch (IOException ignored) {
|
||||
}
|
||||
finally {
|
||||
try {
|
||||
reader.close();
|
||||
}
|
||||
catch (IOException ignored) {
|
||||
}
|
||||
}
|
||||
}
|
||||
catch (FileNotFoundException ignored) {
|
||||
}
|
||||
}
|
||||
|
||||
private void buildFromParameter(@NotNull final TypeEvalContext context, @Nullable final PsiElement outerElement,
|
||||
@NotNull final PsiElement elementDefinition) {
|
||||
myBody.addItem(combUp("Parameter " + PyUtil.getReadableRepr(elementDefinition, false)));
|
||||
|
||||
@@ -35,6 +35,7 @@ import com.intellij.psi.util.PsiTreeUtil;
|
||||
import com.intellij.psi.util.QualifiedName;
|
||||
import com.intellij.util.Function;
|
||||
import com.jetbrains.python.PyNames;
|
||||
import com.jetbrains.python.PythonDialectsTokenSetProvider;
|
||||
import com.jetbrains.python.codeInsight.PyCodeInsightSettings;
|
||||
import com.jetbrains.python.console.PydevConsoleRunner;
|
||||
import com.jetbrains.python.console.PydevDocumentationProvider;
|
||||
@@ -487,6 +488,18 @@ public class PythonDocumentationProvider extends AbstractDocumentationProvider i
|
||||
}
|
||||
}
|
||||
|
||||
@Nullable
|
||||
@Override
|
||||
public PsiElement getCustomDocumentationElement(@NotNull Editor editor,
|
||||
@NotNull PsiFile file,
|
||||
@Nullable PsiElement contextElement) {
|
||||
if (contextElement != null &&
|
||||
PythonDialectsTokenSetProvider.INSTANCE.getKeywordTokens().contains(contextElement.getNode().getElementType())) {
|
||||
return contextElement;
|
||||
}
|
||||
return super.getCustomDocumentationElement(editor, file, contextElement);
|
||||
}
|
||||
|
||||
@Nullable
|
||||
private static PyClass inferContainingClassOf(PsiElement context) {
|
||||
if (context instanceof PyClass) return (PyClass)context;
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
<html><body><code></code><div class="section" id="the-return-statement">
|
||||
<span id="return"></span><h2>The <a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> statement</h2>
|
||||
<pre id="index-21">
|
||||
<strong id="grammar-token-return_stmt">return_stmt</strong> ::= "return" [<a class="reference internal" href="expressions.html#grammar-token-expression_list"><tt class="xref docutils literal"><span class="pre">expression_list</span></tt></a>]
|
||||
</pre>
|
||||
<p><a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> may only occur syntactically nested in a function definition,
|
||||
not within a nested class definition.</p>
|
||||
<p>If an expression list is present, it is evaluated, else <tt class="docutils literal"><span class="pre">None</span></tt> is substituted.</p>
|
||||
<p><a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> leaves the current function call with the expression list (or
|
||||
<tt class="docutils literal"><span class="pre">None</span></tt>) as return value.</p>
|
||||
<p id="index-22">When <a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> passes control out of a <a class="reference internal" href="compound_stmts.html#try"><tt class="xref std std-keyword docutils literal"><span class="pre">try</span></tt></a> statement with a
|
||||
<a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause, that <a class="reference internal" href="compound_stmts.html#finally"><tt class="xref std std-keyword docutils literal"><span class="pre">finally</span></tt></a> clause is executed before
|
||||
really leaving the function.</p>
|
||||
<p>In a generator function, the <a class="reference internal" href="#return"><tt class="xref std std-keyword docutils literal"><span class="pre">return</span></tt></a> statement indicates that the
|
||||
generator is done and will cause <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><tt class="xref py py-exc docutils literal"><span class="pre">StopIteration</span></tt></a> to be raised. The returned
|
||||
value (if any) is used as an argument to construct <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><tt class="xref py py-exc docutils literal"><span class="pre">StopIteration</span></tt></a> and
|
||||
becomes the <tt class="xref py py-attr docutils literal"><span class="pre">StopIteration.value</span></tt> attribute.</p>
|
||||
</div></body></html>
|
||||
@@ -0,0 +1,5 @@
|
||||
class A(object):
|
||||
"doc of A"
|
||||
|
||||
def f(self):
|
||||
re<the_ref>turn 1
|
||||
@@ -233,7 +233,6 @@ public class PyQuickDocTest extends LightMarkedTestCase {
|
||||
checkHover();
|
||||
}
|
||||
|
||||
|
||||
public void testHoverOverFunction() {
|
||||
checkHover();
|
||||
}
|
||||
@@ -250,6 +249,12 @@ public class PyQuickDocTest extends LightMarkedTestCase {
|
||||
checkHover();
|
||||
}
|
||||
|
||||
public void testReturnKeyword() {
|
||||
Map<String, PsiElement> marks = loadTest();
|
||||
final PsiElement originalElement = marks.get("<the_ref>");
|
||||
checkByHTML(myProvider.generateDoc(originalElement, originalElement));
|
||||
}
|
||||
|
||||
// PY-13422
|
||||
public void testNumPyOnesDoc() {
|
||||
myFixture.copyDirectoryToProject("/quickdoc/" + getTestName(false), "");
|
||||
|
||||
Reference in New Issue
Block a user