6.1.Expression statements¶

Expression statements are used (mostly interactively) to compute and write avalue, or (usually) to call a procedure (a function that returns no meaningfulresult; in Python, procedures return the valueNone). Other uses ofexpression statements are allowed and occasionally useful. The syntax for anexpression statement is:

expression_stmt ::=expression_list

An expression statement evaluates the expression list (which may be a singleexpression).

In interactive mode, if the value is notNone, it is converted to a stringusing the built-inrepr() function and the resulting string is written tostandard output (see sectionThe print statement) on a line by itself. (Expressionstatements yieldingNone are not written, so that procedure calls do notcause any output.)

6.2.Assignment statements¶

Assignment statements are used to (re)bind names to values and to modifyattributes or items of mutable objects:

assignment_stmt ::=  (target_list "=")+ (expression_list |yield_expression)target_list ::=target (","target)* [","]target ::=identifier                     | "("target_list ")"                     | "[" [target_list] "]"                     |attributeref                     |subscription                     |slicing

(See sectionPrimaries for the syntax definitions for the last threesymbols.)

An assignment statement evaluates the expression list (remember that this can bea single expression or a comma-separated list, the latter yielding a tuple) andassigns the single resulting object to each of the target lists, from left toright.

Assignment is defined recursively depending on the form of the target (list).When a target is part of a mutable object (an attribute reference, subscriptionor slicing), the mutable object must ultimately perform the assignment anddecide about its validity, and may raise an exception if the assignment isunacceptable. The rules observed by various types and the exceptions raised aregiven with the definition of the object types (see sectionThe standard type hierarchy).

Assignment of an object to a target list is recursively defined as follows.

• If the target list is a single target: The object is assigned to that target.

• If the target list is a comma-separated list of targets: The object must be aniterable with the same number of items as there are targets in the target list,and the items are assigned, from left to right, to the corresponding targets.

Assignment of an object to a single target is recursively defined as follows.

• If the target is an identifier (name):

  • If the name does not occur in aglobal statement in the currentcode block: the name is bound to the object in the current local namespace.

  • Otherwise: the name is bound to the object in the current global namespace.

  The name is rebound if it was already bound. This may cause the reference countfor the object previously bound to the name to reach zero, causing the object tobe deallocated and its destructor (if it has one) to be called.

• If the target is a target list enclosed in parentheses or in square brackets:The object must be an iterable with the same number of items as there aretargets in the target list, and its items are assigned, from left to right,to the corresponding targets.

• If the target is an attribute reference: The primary expression in thereference is evaluated. It should yield an object with assignable attributes;if this is not the case,TypeError is raised. That object is thenasked to assign the assigned object to the given attribute; if it cannotperform the assignment, it raises an exception (usually but not necessarilyAttributeError).

  Note: If the object is a class instance and the attribute reference occurs onboth sides of the assignment operator, the RHS expression,a.x can accesseither an instance attribute or (if no instance attribute exists) a classattribute. The LHS targeta.x is always set as an instance attribute,creating it if necessary. Thus, the two occurrences ofa.x do notnecessarily refer to the same attribute: if the RHS expression refers to aclass attribute, the LHS creates a new instance attribute as the target of theassignment:

  classCls:x=3# class variableinst=Cls()inst.x=inst.x+1# writes inst.x as 4 leaving Cls.x as 3

  This description does not necessarily apply to descriptor attributes, such asproperties created withproperty().

• If the target is a subscription: The primary expression in the reference isevaluated. It should yield either a mutable sequence object (such as a list) ora mapping object (such as a dictionary). Next, the subscript expression isevaluated.

  If the primary is a mutable sequence object (such as a list), the subscript mustyield a plain integer. If it is negative, the sequence’s length is added to it.The resulting value must be a nonnegative integer less than the sequence’slength, and the sequence is asked to assign the assigned object to its item withthat index. If the index is out of range,IndexError is raised(assignment to a subscripted sequence cannot add new items to a list).

  If the primary is a mapping object (such as a dictionary), the subscript musthave a type compatible with the mapping’s key type, and the mapping is thenasked to create a key/datum pair which maps the subscript to the assignedobject. This can either replace an existing key/value pair with the same keyvalue, or insert a new key/value pair (if no key with the same value existed).

• If the target is a slicing: The primary expression in the reference isevaluated. It should yield a mutable sequence object (such as a list). Theassigned object should be a sequence object of the same type. Next, the lowerand upper bound expressions are evaluated, insofar they are present; defaultsare zero and the sequence’s length. The bounds should evaluate to (small)integers. If either bound is negative, the sequence’s length is added to it.The resulting bounds are clipped to lie between zero and the sequence’s length,inclusive. Finally, the sequence object is asked to replace the slice with theitems of the assigned sequence. The length of the slice may be different fromthe length of the assigned sequence, thus changing the length of the targetsequence, if the object allows it.

WARNING: Although the definition of assignment implies that overlaps between theleft-hand side and the right-hand side are ‘safe’ (for examplea,b=b,aswaps two variables), overlapswithin the collection of assigned-to variablesare not safe! For instance, the following program prints[0,2]:

x=[0,1]i=0i,x[i]=1,2printx

augmented_assignment_stmt ::=augtargetaugop (expression_list |yield_expression)augtarget ::=identifier |attributeref |subscription |slicingaugop ::=  "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**="                               | ">>=" | "<<=" | "&=" | "^=" | "|="

6.3.Theassert statement¶

Assert statements are a convenient way to insert debugging assertions into aprogram:

assert_stmt ::=  "assert"expression [","expression]

The simple form,assertexpression, is equivalent to

if__debug__:ifnotexpression:raiseAssertionError

The extended form,assertexpression1,expression2, is equivalent to

if__debug__:ifnotexpression1:raiseAssertionError(expression2)

These equivalences assume that__debug__ andAssertionError refer tothe built-in variables with those names. In the current implementation, thebuilt-in variable__debug__ isTrue under normal circumstances,False when optimization is requested (command line option -O). The currentcode generator emits no code for an assert statement when optimization isrequested at compile time. Note that it is unnecessary to include the sourcecode for the expression that failed in the error message; it will be displayedas part of the stack trace.

Assignments to__debug__ are illegal. The value for the built-in variableis determined when the interpreter starts.

6.4.Thepass statement¶

pass_stmt ::=  "pass"

pass is a null operation — when it is executed, nothing happens.It is useful as a placeholder when a statement is required syntactically, but nocode needs to be executed, for example:

deff(arg):pass# a function that does nothing (yet)classC:pass# a class with no methods (yet)

6.5.Thedel statement¶

del_stmt ::=  "del"target_list

Deletion is recursively defined very similar to the way assignment is defined.Rather than spelling it out in full details, here are some hints.

Deletion of a target list recursively deletes each target, from left to right.

Deletion of a name removes the binding of that name from the local or globalnamespace, depending on whether the name occurs in aglobal statementin the same code block. If the name is unbound, aNameError exceptionwill be raised.

It is illegal to delete a name from the local namespace if it occurs as a freevariable in a nested block.

Deletion of attribute references, subscriptions and slicings is passed to theprimary object involved; deletion of a slicing is in general equivalent toassignment of an empty slice of the right type (but even this is determined bythe sliced object).

6.6.Theprint statement¶

print_stmt ::=  "print" ([expression (","expression)* [","]]                | ">>"expression [(","expression)+ [","]])

print evaluates each expression in turn and writes the resultingobject to standard output (see below). If an object is not a string, it isfirst converted to a string using the rules for string conversions. The(resulting or original) string is then written. A space is written before eachobject is (converted and) written, unless the output system believes it ispositioned at the beginning of a line. This is the case (1) when no charactershave yet been written to standard output, (2) when the last character written tostandard output is a whitespace character except'', or (3) when the lastwrite operation on standard output was not aprint statement.(In some cases it may be functional to write an empty string to standard outputfor this reason.)

A'\n' character is written at the end, unless theprintstatement ends with a comma. This is the only action if the statement containsjust the keywordprint.

Standard output is defined as the file object namedstdout in the built-inmodulesys. If no such object exists, or if it does not have awrite() method, aRuntimeError exception is raised.

print also has an extended form, defined by the second portion of thesyntax described above. This form is sometimes referred to as “printchevron.” In this form, the first expression after the>> must evaluate to a“file-like” object, specifically an object that has awrite() method asdescribed above. With this extended form, the subsequent expressions areprinted to this file object. If the first expression evaluates toNone,thensys.stdout is used as the file for output.

6.7.Thereturn statement¶

return_stmt ::=  "return" [expression_list]

return may only occur syntactically nested in a function definition,not within a nested class definition.

If an expression list is present, it is evaluated, elseNone is substituted.

return leaves the current function call with the expression list (orNone) as return value.

Whenreturn passes control out of atry statement with afinally clause, thatfinally clause is executed beforereally leaving the function.

In a generator function, thereturn statement is not allowed toinclude anexpression_list. In that context, a barereturnindicates that the generator is done and will causeStopIteration to beraised.

6.8.Theyield statement¶

yield_stmt ::=yield_expression

Theyield statement is only used when defining a generator function,and is only used in the body of the generator function. Using ayieldstatement in a function definition is sufficient to cause that definition tocreate a generator function instead of a normal function.

When a generator function is called, it returns an iterator known as a generatoriterator, or more commonly, a generator. The body of the generator function isexecuted by calling the generator’snext() method repeatedlyuntil it raises an exception.

When ayield statement is executed, the state of the generator isfrozen and the value ofexpression_list is returned tonext()’s caller. By “frozen” we mean that all local state isretained, including the current bindings of local variables, the instructionpointer, and the internal evaluation stack: enough information is saved so thatthe next timenext() is invoked, the function can proceedexactly as if theyield statement were just another external call.

As of Python version 2.5, theyield statement is now allowed in thetry clause of atry …finally construct. Ifthe generator is not resumed before it is finalized (by reaching a zeroreference count or by being garbage collected), the generator-iterator’sclose() method will be called, allowing any pendingfinallyclauses to execute.

For full details ofyield semantics, refer to theYield expressionssection.

from__future__importgenerators

6.9.Theraise statement¶

raise_stmt ::=  "raise" [expression [","expression [","expression]]]

If no expressions are present,raise re-raises the last exceptionthat was active in the current scope. If no exception is active in the currentscope, aTypeError exception is raised indicating that this is an error(if running under IDLE, aQueue.Empty exception is raised instead).

Otherwise,raise evaluates the expressions to get three objects,usingNone as the value of omitted expressions. The first two objects areused to determine thetype andvalue of the exception.

If the first object is an instance, the type of the exception is the class ofthe instance, the instance itself is the value, and the second object must beNone.

If the first object is a class, it becomes the type of the exception. The secondobject is used to determine the exception value: If it is an instance of theclass, the instance becomes the exception value. If the second object is atuple, it is used as the argument list for the class constructor; if it isNone, an empty argument list is used, and any other object is treated as asingle argument to the constructor. The instance so created by calling theconstructor is used as the exception value.

If a third object is present and notNone, it must be a traceback object(see sectionThe standard type hierarchy), and it is substituted instead of the currentlocation as the place where the exception occurred. If the third object ispresent and not a traceback object orNone, aTypeError exception israised. The three-expression form ofraise is useful to re-raise anexception transparently in an except clause, butraise with noexpressions should be preferred if the exception to be re-raised was the mostrecently active exception in the current scope.

Additional information on exceptions can be found in sectionExceptions,and information about handling exceptions is in sectionThe try statement.

6.10.Thebreak statement¶

break_stmt ::=  "break"

break may only occur syntactically nested in afor orwhile loop, but not nested in a function or class definition withinthat loop.

It terminates the nearest enclosing loop, skipping the optionalelseclause if the loop has one.

If afor loop is terminated bybreak, the loop controltarget keeps its current value.

Whenbreak passes control out of atry statement with afinally clause, thatfinally clause is executed beforereally leaving the loop.

6.11.Thecontinue statement¶

continue_stmt ::=  "continue"

continue may only occur syntactically nested in afor orwhile loop, but not nested in a function or class definition orfinally clause within that loop. It continues with the nextcycle of the nearest enclosing loop.

Whencontinue passes control out of atry statement with afinally clause, thatfinally clause is executed beforereally starting the next loop cycle.

6.12.Theimport statement¶

import_stmt ::=  "import"module ["as"name] ( ","module ["as"name] )*                     | "from"relative_module "import"identifier ["as"name]                     ( ","identifier ["as"name] )*                     | "from"relative_module "import" "("identifier ["as"name]                     ( ","identifier ["as"name] )* [","] ")"                     | "from"module "import" "*"module ::=  (identifier ".")*identifierrelative_module ::=  "."*module | "."+name ::=identifier

Import statements are executed in two steps: (1) find a module, and initializeit if necessary; (2) define a name or names in the local namespace (of the scopewhere theimport statement occurs). The statement comes in twoforms differing on whether it uses thefrom keyword. The first form(withoutfrom) repeats these steps for each identifier in the list.The form withfrom performs step (1) once, and then performs step(2) repeatedly.

To understand how step (1) occurs, one must first understand how Python handleshierarchical naming of modules. To help organize modules and provide ahierarchy in naming, Python has a concept of packages. A package can containother packages and modules while modules cannot contain other modules orpackages. From a file system perspective, packages are directories and modulesare files.

Once the name of the module is known (unless otherwise specified, the term“module” will refer to both packages and modules), searchingfor the module or package can begin. The first place checked issys.modules, the cache of all modules that have been importedpreviously. If the module is found there then it is used in step (2) of import.

If the module is not found in the cache, thensys.meta_path is searched(the specification forsys.meta_path can be found inPEP 302).The object is a list offinder objects which are queried in order as towhether they know how to load the module by calling theirfind_module()method with the name of the module. If the module happens to be containedwithin a package (as denoted by the existence of a dot in the name), then asecond argument tofind_module() is given as the value of the__path__ attribute from the parent package (everything up to the lastdot in the name of the module being imported). If a finder can find the moduleit returns aloader (discussed later) or returnsNone.

If none of the finders onsys.meta_path are able to find the modulethen some implicitly defined finders are queried. Implementations of Pythonvary in what implicit meta path finders are defined. The one they all dodefine, though, is one that handlessys.path_hooks,sys.path_importer_cache, andsys.path.

The implicit finder searches for the requested module in the “paths” specifiedin one of two places (“paths” do not have to be file system paths). If themodule being imported is supposed to be contained within a package then thesecond argument passed tofind_module(),__path__ on the parentpackage, is used as the source of paths. If the module is not contained in apackage thensys.path is used as the source of paths.

Once the source of paths is chosen it is iterated over to find a finder thatcan handle that path. The dict atsys.path_importer_cache cachesfinders for paths and is checked for a finder. If the path does not have afinder cached thensys.path_hooks is searched by calling each object inthe list with a single argument of the path, returning a finder or raisesImportError. If a finder is returned then it is cached insys.path_importer_cache and then used for that path entry. If no findercan be found but the path exists then a value ofNone isstored insys.path_importer_cache to signify that an implicit,file-based finder that handles modules stored as individual files should beused for that path. If the path does not exist then a finder which alwaysreturnsNone is placed in the cache for the path.

If no finder can find the module thenImportError is raised. Otherwisesome finder returned a loader whoseload_module() method is called withthe name of the module to load (seePEP 302 for the original definition ofloaders). A loader has several responsibilities to perform on a module itloads. First, if the module already exists insys.modules (apossibility if the loader is called outside of the import machinery) then itis to use that module for initialization and not a new module. But if themodule does not exist insys.modules then it is to be added to thatdict before initialization begins. If an error occurs during loading of themodule and it was added tosys.modules it is to be removed from thedict. If an error occurs but the module was already insys.modules itis left in the dict.

The loader must set several attributes on the module.__name__ is to beset to the name of the module.__file__ is to be the “path” to the fileunless the module is built-in (and thus listed insys.builtin_module_names) in which case the attribute is not set.If what is being imported is a package then__path__ is to be set to alist of paths to be searched when looking for modules and packages containedwithin the package being imported.__package__ is optional but shouldbe set to the name of package that contains the module or package (the emptystring is used for module not contained in a package).__loader__ isalso optional but should be set to the loader object that is loading themodule.

If an error occurs during loading then the loader raisesImportError ifsome other exception is not already being propagated. Otherwise the loaderreturns the module that was loaded and initialized.

When step (1) finishes without raising an exception, step (2) can begin.

The first form ofimport statement binds the module name in the localnamespace to the module object, and then goes on to import the next identifier,if any. If the module name is followed byas, the name followingas is used as the local name for the module.

Thefrom form does not bind the module name: it goes through the listof identifiers, looks each one of them up in the module found in step (1), andbinds the name in the local namespace to the object thus found. As with thefirst form ofimport, an alternate local name can be supplied byspecifying “as localname”. If a name is not found,ImportError is raised. If the list of identifiers is replaced by a star('*'), all public names defined in the module are bound in the localnamespace of theimport statement..

Thepublic names defined by a module are determined by checking the module’snamespace for a variable named__all__; if defined, it must be a sequence ofstrings which are names defined or imported by that module. The names given in__all__ are all considered public and are required to exist. If__all__is not defined, the set of public names includes all names found in the module’snamespace which do not begin with an underscore character ('_').__all__ should contain the entire public API. It is intended to avoidaccidentally exporting items that are not part of the API (such as librarymodules which were imported and used within the module).

Thefrom form with* may only occur in a module scope. If thewild card form of import —import* — is used in a function and thefunction contains or is a nested block with free variables, the compiler willraise aSyntaxError.

When specifying what module to import you do not have to specify the absolutename of the module. When a module or package is contained within anotherpackage it is possible to make a relative import within the same top packagewithout having to mention the package name. By using leading dots in thespecified module or package afterfrom you can specify how high totraverse up the current package hierarchy without specifying exact names. Oneleading dot means the current package where the module making the importexists. Two dots means up one package level. Three dots is up two levels, etc.So if you executefrom.importmod from a module in thepkg packagethen you will end up importingpkg.mod. If you executefrom..subpkg2importmod from withinpkg.subpkg1 you will importpkg.subpkg2.mod.The specification for relative imports is contained withinPEP 328.

importlib.import_module() is provided to support applications thatdetermine which modules need to be loaded dynamically.

future_statement ::=  "from" "__future__" "import" feature ["as" name]                      ("," feature ["as" name])*                      | "from" "__future__" "import" "(" feature ["as" name]                      ("," feature ["as" name])* [","] ")"feature ::=  identifiername ::=  identifier

import__future__[asname]

6.13.Theglobal statement¶

global_stmt ::=  "global"identifier (","identifier)*

Theglobal statement is a declaration which holds for the entirecurrent code block. It means that the listed identifiers are to be interpretedas globals. It would be impossible to assign to a global variable withoutglobal, although free variables may refer to globals without beingdeclared global.

Names listed in aglobal statement must not be used in the same codeblock textually preceding thatglobal statement.

Names listed in aglobal statement must not be defined as formalparameters or in afor loop control target,classdefinition, function definition, orimport statement.

Programmer’s note:global is a directive to the parser. Itapplies only to code parsed at the same time as theglobal statement.In particular, aglobal statement contained in anexecstatement does not affect the code blockcontaining theexecstatement, and code contained in anexec statement is unaffected byglobal statements in the code containing theexecstatement. The same applies to theeval(),execfile() andcompile() functions.

6.14.Theexec statement¶

exec_stmt ::=  "exec"or_expr ["in"expression [","expression]]

This statement supports dynamic execution of Python code. The first expressionshould evaluate to either a Unicode string, aLatin-1 encoded string, an openfile object, a code object, or a tuple. If it is a string, the string is parsedas a suite of Python statements which is then executed (unless a syntax erroroccurs).1 If it is an open file, the file is parsed until EOF and executed.If it is a code object, it is simply executed. For the interpretation of atuple, see below. In all cases, the code that’s executed is expected to bevalid as file input (see sectionFile input). Be aware that thereturn andyield statements may not be used outside offunction definitions even within the context of code passed to theexec statement.

In all cases, if the optional parts are omitted, the code is executed in thecurrent scope. If only the first expression afterin is specified,it should be a dictionary, which will be used for both the global and the localvariables. If two expressions are given, they are used for the global and localvariables, respectively. If provided,locals can be any mapping object.Remember that at module level, globals and locals are the same dictionary. Iftwo separate objects are given asglobals andlocals, the code will beexecuted as if it were embedded in a class definition.

The first expression may also be a tuple of length 2 or 3. In this case, theoptional parts must be omitted. The formexec(expr,globals) is equivalenttoexecexpringlobals, while the formexec(expr,globals,locals) isequivalent toexecexpringlobals,locals. The tuple form ofexecprovides compatibility with Python 3, whereexec is a function rather thana statement.

As a side effect, an implementation may insert additional keys into thedictionaries given besides those corresponding to variable names set by theexecuted code. For example, the current implementation may add a reference tothe dictionary of the built-in module__builtin__ under the key__builtins__ (!).

Programmer’s hints: dynamic evaluation of expressions is supported by thebuilt-in functioneval(). The built-in functionsglobals() andlocals() return the current global and local dictionary, respectively,which may be useful to pass around for use byexec.

Footnotes

1

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 useuniversal newlines mode to convert Windows or Mac-style newlines.