target = expression
target1 = target2 = expression
target1, target2 = expression1, expression2
target1 += expression
target1, target2,  ...  = same-length-iterable
(target1, target2, ...) = same-length-iterable
[target1, target2, ...] = same-length-iterable
target1, *target2, ...  = matching–length-iterable

Assignments store references to objects in targets. Expressions yield objects. Targets can be simple names (X), qualified attributes (X.attr), or indexes and slices (X[i], X[i:j]).

The second format assigns an expression object to each target. The third format pairs targets with expressions, left to right. The last three formats assign components of any sequence (or other iterable) to corresponding targets, from left to right. The sequence or iterable on the right must be the same length but can be any type, unless a single starred-name appears in the targets on the left to collect arbitrarily many items (Python 3.0 extended sequence assignment, discussed ahead):

target1, *target2, ... = iterable

X = X + Y
X += Y

>>> a, b, c, d = [1, 2, 3, 4]
>>> a, d
(1, 4)

>>> for (a, b, c) in [[1, 2, 3], [4, 5, 6]]:
...     print(a, b, c)
...
1 2 3
4 5 6

>>> a, *b = [1, 2, 3, 4]
>>> a, b
(1, [2, 3, 4])

>>> a, *b, c = [1, 2, 3, 4]
>>> a, b, c
(1, [2, 3], 4)

>>> *a, b = [1, 2, 3, 4]
>>> a, b
([1, 2, 3], 4)

>>> for (a, *b) in [[1, 2, 3], [4, 5, 6]]: print(a, b)
...
1 [2, 3]
4 [5, 6]

expression
function([value, name=value, *name, **name...])
object.method([value, name=value, *name, **name...])

Any expression can appear on a line by itself as a statement (but statements cannot appear as expressions). Expressions are commonly used for calling functions and methods, and for interactive-mode printing. Expression statements are also the most common coding for yield expressions and Python 3.0 print() built-in function calls (though they are documented as specific statements in this book).

f(*pargs, **kargs)

>>> def f(a, b, c, d): print(a, b, c, d)
...
>>> f(*[1, 2], **dict(c=3, d=4))
1 2 3 4

apply(f, pargs, kargs)

Printing takes the form of a built-in function call in Python 3.0, which is commonly coded as an expression statement (on a line by itself). Its call signature is as follows:

print([value [, value]*] 
   [, sep=string] [, end=string] [, file=file])

Each value denotes an object to be printed. This call is configured by its three keyword-only arguments:

Pass empty or custom strings to suppress space separators and line feeds, and pass a file or file-like object to redirect output in your script:

>>> print(2 ** 32, 'spam')
4294967296 spam

>>> print(2 ** 32, 'spam', sep='')
4294967296spam

>>> print(2 ** 32, 'spam', end=' '), print(1, 2, 3)
4294967296 spam 1 2 3

>>> print(2 ** 32, 'spam', sep='', file=open('out', 'w'))
>>> open('out').read()
'4294967296spam
'

Because by default print simply calls the write method of the object currently referenced by sys.stdout, the following is equivalent to print(X):

import sys
sys.stdout.write(str(X) + '
')

To redirect print text to files or class objects, either pass any object with a write method to the file keyword argument as shown earlier, or reassign sys.stdout to any such object:

sys.stdout = open('log', 'a')  # any object with a write()
print('Warning-bad spam!')     # goes to object's write()

Because sys.stdout can be reassigned, the file keyword argument is not strictly needed; however, it can often avoid both explicit write method calls, and saving and restoring the original sys.stdout value around a redirected print when the original stream is still required. See also Built-in Functions.

print [value [, value]* [,]]
print >> file [, value [, value]* [,]]

>>> print 2 ** 32, 'spam'
4294967296 spam

>>> print 2 ** 32, 'spam',; print 1, 2, 3
4294967296 spam 1 2 3

fileobj = open('log', 'a')
print >> fileobj, "Warning-bad spam!"

from __future__ import print_function

if test:
    suite
[elif test:
    suite]*
[else:
    suite]

The if statement selects from among one or more actions (statement blocks), and it runs the suite associated with the first if or elif test that is true, or the else suite if all are false.

while test:
    suite
[else:
    suite]

The while loop is a general loop that keeps running the first suite while the test at the top is true. It runs the else suite if the loop exits without hitting a break statement.

for target in iterable:
    suite
[else:
    suite]

The for loop is a sequence (or other iterable) iteration that assigns items in iterable to target and runs the first suite for each. The for statement runs the else suite if the loop exits without hitting a break statement. target can be anything that can appear on the left side of an = assignment statement (e.g., for (x, y) in tuplelist:).

Since Python 2.2, this works by first trying to obtain an iterator object I with iter(iterable) and then calling that object’s I.__next__() method repeatedly until StopIteration is raised (I.__next__() is named I.next() in Python 2); see The yield Statement for more on iteration. In earlier versions, or if no iterator object can be obtained (e.g., no __iter__ method is defined), this works instead by repeatedly indexing iterable at successively higher offsets until an IndexError is raised.

pass

This is a do-nothing placeholder statement, and is used when syntactically necessary. In Python 3.X only, ellipses (...) can achieve similar effects.

break

This immediately exits the closest enclosing while or for loop statement, skipping its associated else (if any).

continue

This immediately goes to the top of the closest enclosing while or for loop statement; it resumes in the loop header line.

del name
del name[i]
del name[i:j:k]
del name.attribute

The del statement deletes names, items, slices, and attributes, as well as removes bindings. In the last three forms, name can actually be any expression (with parentheses if required for priority). For instance: del a.b()[1].c.d.

[decoration]
def name([arg,... arg=value,... *arg, **arg]):
    suite

The def statement makes new functions. It creates a function object and assigns it to variable name. Each call to a function object generates a new, local scope, where assigned names are local to the function call by default (unless declared global). See also the section Namespace and Scope Rules. Arguments are passed by assignment; in a def header, they can be defined by any of the four formats in Table 1-14.

The argument forms in Table 1-14 can also be used in a function call, where they are interpreted as shown in Table 1-15 (see The Expression Statement for more on function call syntax).

>>> def f(a, *b, c): print(a, b, c)  # c required keyword
...
>>> f(1, 2, c=3)
1 (2,) 3

>>> def f(a, *, c=None): print(a, c) # c optional keyword
...
>>> f(1)
1 None
>>> f(1, c='spam')
1 spam

>>> def f(a:99, b:'spam'=None) -> float:
...     print(a, b)
...
>>> f(88)
88 None
>>> f.__annotations__
{'a': 99, 'b': 'spam', 'return': <class 'float'>}

lambda arg, arg,...: expression

>>> def grow(a, b=[]):       # ..., b=None)
...     b.append(a)          # if b == None: b = []
...     print(b)
...
>>> grow(1); grow(2)
[1]
[1, 2]

>>> grow.food = 'spam'
>>> grow.food
'spam'

@decorator
def F():
    ...

def F():
    ...
F = decorator(F)

class C:
    @decorator
    def M():            # same as M = decorator(M)
        ...

@A
@B
@C
def f(): ...

def f(): ...
f = A(B(C(f)))

@spam(1,2,3)
def f(): ...

return [expression]

The return statement exits the enclosing function and returns an expression value as the result of the call to the function. The expression defaults to None if it’s omitted. Hint: return a tuple for multiple-value function results.

yield expression

The yield expression, commonly coded as an expression statement (on a line by itself), suspends function state and returns an expression. On the next iteration, the function’s prior state is restored, and control resumes immediately after the yield statement. Use a return statement with no value to end the iteration, or simply fall off the end of the function:

def generateSquares(N):
    for i in range(N):
        yield i ** 2

>>> G =  generateSquares(5)
>>> list(G)                     # force results generation
[0, 1, 4, 9, 16]

When used as an expression, yield returns the object passed to the generator’s send() method at the caller (e.g., A = yield X), and must be enclosed in parenthesis unless it is the only item on the right of = (e.g., A = (yield X) + 42). In this mode, values are sent to a generator by calling send(value); the generator is resumed, and the yield expression returns value. If the regular __next__() method or next() built-in function is called to advance, yield returns None.

Generators also have a throw(type) method to raise an exception inside the generator at the latest yield, and a close() method that raises a new GeneratorExit exception inside the generator to terminate the iteration. yield is standard as of version 2.3 and later; generator send(), throw(), and close() methods are available as of Python 2.5.

global name [, name]*

The global statement is a namespace declaration: when used inside a class or function definition statement, it causes all appearances of name in that context to be treated as references to a global (module-level) variable of that name—whether name is assigned or not, and whether name already exists or not.

This statement allows globals to be created or changed within a function or class. Because of Python’s scope rules, you need to declare only global names that are assigned; undeclared names are made local if assigned, but global references are automatically located in the enclosing module. See also Namespace and Scope Rules.

nonlocal name [, name]*

Available in Python 3.0 only.

The nonlocal statement is a namespace declaration: when used inside a nested function, it causes all appearances of name in that context to be treated as references to a local variable of that name in an enclosing function’s scope—whether name is assigned or not.

name must exist in an enclosing function; this statement allows it to be changed by a nested function. Because of Python’s scope rules, you need to declare only nonlocal names that are assigned; undeclared names are made local if assigned, but nonlocal references are automatically located in enclosing functions. See also Namespace and Scope Rules.

import module [, module]*
import [package.]* module [, [package.]* module]*
import [package.]* module as name 
                   [, [package.]*module as name]*

The import statement provides module access: it imports a module as a whole. Modules in turn contain names fetched by qualification (e.g., module.attribute). Assignments at the top level of a Python file create module object attributes. The as clause assigns a variable name to the imported module object; it is useful to provide shorter synonyms for long module names.

module names the target module—usually a Python source file or compiled module—which must be located in a directory in sys.path. The module is given without its filename suffix (.py and other extensions are omitted). The sys.path module import search path is a directory list initialized from the program’s top-level directory, PYTHONPATH settings, .pth path file contents, and Python defaults.

Import operations compile a file’s source to byte-code if needed (and save it in a .pyc file if possible), then execute the compiled code from top to bottom to generate module object attributes by assignment. Use the imp.reload() built-in function to force recompilation and execution of already-loaded modules; see also __import__ used by import in the section Built-in Functions.

In the Jython implementation, imports can also name Java class libraries; Jython generates a Python module wrapper that interfaces with the Java library. In standard CPython, imports can also load compiled C and C++ extensions.

from [package.]* module import name [, name]*
from [package.]* module import *
from [package.]* module import name as othername
from [package.]* module import (name1, name2, ...)

The from statement imports variable names from a module so that you can use those names later without the need to qualify them with their module name. The from mod import * format copies all names assigned at the top level of the module, except names with a single leading underscore or names not listed in the module’s __all__ list-of-strings attribute (if defined).

If used, the as clause creates a name synonym. If used, package import paths work the same as in import statements (e.g., from dir1.dir2.mod import X), but the package path needs to be listed only in the from itself. Due to new scoping rules, the * format generates warnings in version 2.2 if it appears nested in a function or class (this generates errors in Python 3.0).

As of Python 2.4, the names being imported from a module can be enclosed in parentheses to span multiple lines without backslashes. As of Python 3.0, from module import * form is invalid within a function, because it makes it impossible to classify name scopes at definition time.

The from statement is also used to enable future (but still experimental) language additions, with from __future__ import featurename. This format must appear only at the top of a module file (preceded only by an optional doc string).

from module import name [, name]*    # sys.path: abs
from . import module [, module]*     # pkg dir only: rel
from .module import name [, name]*   # pkg dir only: rel
from .. import module [, module]*    # parent dir in pkg
from ..module import name [, name]*  # parent dir in pkg

from __future__ import  absolute_import

[decoration]
class name [ ( super [, super]* [, metaclass=M] ) ]:
    suite

The class statement makes new class objects, which are factories for instance objects. The new class object inherits from each listed super class in the order given, and is assigned to variable name. The class statement introduces a new local name scope, and all names assigned in the class statement generate class object attributes shared by all instances of the class.

Important class features include the following (see also the sections Object-Oriented Programming and Operator Overloading Methods):

@decorator
class C:
   def meth():
       ...

class C:
     def meth():
       ...
C = decorator(C)

class Meta(type):
    def __new__(meta, cname, supers, cdict):
        # run by inherited type.__call__
        return type.__new__(meta, cname, supers, cdict)

class C(metaclass=Meta): ...

class C:
    __metaclass__ = Meta
    ...

try:
    suite
except [type [as value]]:       # [, value] in Python 2
    suite
[except [type [as value]]:
    suite]*
[else:
    suite]
[finally:
    suite]

try:
    suite
finally:
    suite

The try statement catches exceptions. try statements can specify except clauses with suites that serve as handlers for exceptions raised during the try suite, else clauses that run if no exception occurs during the try suite, and finally clauses that run whether an exception happens or not. except clauses catch and recover from exceptions, and finally clauses define termination actions.

Exceptions can be raised by Python, or explicitly (see also the raise statement discussed in the next section, The raise Statement). In except clauses, type is an expression giving the exception class to be caught, and an extra variable name value can be used to intercept the instance of the exception class that was raised. Table 1-16 lists all the clauses that can appear in a try statement.

The try must have either an except or a finally, or both. The order of its parts must be: try→except→else→finally, where the else and finally are optional, and there may be zero or more except, but there must be at least one except if an else appears. finally interacts correctly with return, break, and continue (if any of these pass control out of the try block, the finally clause is executed on the way out).

Common variations include the following:

See also the sys.exc_info() call in The sys Module for generic access to the exception class and instance (a.k.a., type and value) after an exception is raised.

In Python 3.0, the raise statement takes the following forms:

The raise statement triggers exceptions. You can use it to explicitly raise either built-in exceptions, or user-defined exceptions. Without arguments, raise re-raises the most recent exception. See also Built-in Exceptions for exceptions raised by Python.

On a raise, control jumps to the matching except clause of the most recently entered matching try statement, or to the top level of the process (where it ends the program and prints a standard error message). The instance object raised is assigned to the as variable in the matching except clause (if given).

The optional from clause allows exception chaining in Python 3.0 (only): otherexc is another exception class or instance, and is attached to the raised exception’s __cause__ attribute. If the raised exception is not caught, Python prints both exceptions as part of the standard error message.

class General(Exception):
    def __init__(self, x):
        self.data = x

class Specific1(General): pass
class Specific2(General): pass

try:
    raise Specific1('spam')
except General as X:
    print(X.data)             # prints 'spam'

assert expression [, message]

The assert statement performs debugging checks. If expression is false, it raises AssertionError, passing message as an extra data item if specified. The -O command-line flag removes assertions (their tests are not run).

with expression [as variable]:      # Python 2.6 and 3.0
    suite

with expression [as variable]
        [, expression [as variable]]*:  # 3.1
    suite

The with statement wraps a nested block of code in a context manager, which ensures that block entry and/or exit actions are run. This is an alternative to try/finally for objects having context managers that perform termination actions whether exceptions are raised or not.

expression is assumed to return an object that supports the context management protocol. This object may also return a value that will be assigned to the name variable if the optional as clause is present. Classes may define custom context managers, and some built-in types such as files and threads provide context managers with exit actions that close files, release thread locks, etc.:

with open(r'C:miscscript', 'w') as myfile:
    ...process myfile, auto-closed on statement exit...

See Files for more details on file context manager usage, and Python manuals for other built-in types that support this protocol and statement, as well as details on the protocol itself.

This statement is supported as of Python 2.6 and 3.0, and may be enabled in 2.5 with the following:

from __future__ import with_statement

with A() as a, B() as b:
    ...statements...

with A() as a:
    with B() as b:
        ...statements...

with open('data') as fin, open('results', 'w') as fout:
    for line in fin:
        fout.write(transform(line))

Python 2.X supports the print statement described above, does not support nonlocal, and does not support with until 2.6. In addition, raise, try, and def have the slightly different syntaxes in Python 2.X as noted above.

The following additional statement is available in Python 2.X only:

exec codestring [in globaldict [, localdict]]

The exec statement compiles and runs code strings. codestring is any Python statement (or multiple statements separated by newlines) as a string; it is run in a namespace containing the exec, or the global/local namespace dictionaries if specified (localdict defaults to globaldict). codestring can also be a compiled code object. Also see compile(), eval(), and the Python 2.X execfile() in Built-in Functions.

In Python 3.0, this statement becomes the exec() function (see Built-in Functions). The backward- and forward-compatible syntax exec(a, b, c) is also accepted in Python 2.