| 'dangling :keyword:`else`' problem is solved in Python by requiring nested |
| :keyword:`if` statements to be indented). |
| |
| The formatting of the grammar rules in the following sections places each clause |
| on a separate line for clarity. |
| |
| |
| .. _if: |
n | .. _elif: |
| .. _else: |
| |
| The :keyword:`if` statement |
| =========================== |
| |
n | .. index:: statement: if |
| |
| The :keyword:`if` statement is used for conditional execution: |
| |
| .. productionlist:: |
| if_stmt: "if" `expression` ":" `suite` |
| : ( "elif" `expression` ":" `suite` )\* |
| : ["else" ":" `suite`] |
| |
| .. index:: |
n | statement: if |
| keyword: elif |
| keyword: else |
n | |
| The :keyword:`if` statement is used for conditional execution: |
| |
| .. productionlist:: |
| if_stmt: "if" `expression` ":" `suite` |
| : ( "elif" `expression` ":" `suite` )* |
| : ["else" ":" `suite`] |
| |
| It selects exactly one of the suites by evaluating the expressions one by one |
| until one is found to be true (see section :ref:`booleans` for the definition of |
| true and false); then that suite is executed (and no other part of the |
| :keyword:`if` statement is executed or evaluated). If all expressions are |
| false, the suite of the :keyword:`else` clause, if present, is executed. |
| |
| |
| .. _while: |
| |
| The :keyword:`while` statement |
| ============================== |
| |
| .. index:: |
| statement: while |
| pair: loop; statement |
n | keyword: else |
| |
| The :keyword:`while` statement is used for repeated execution as long as an |
| expression is true: |
| |
| .. productionlist:: |
| while_stmt: "while" `expression` ":" `suite` |
| : ["else" ":" `suite`] |
n | |
| .. index:: keyword: else |
| |
| 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 :keyword:`else` clause, if present, is executed and the loop |
| terminates. |
| |
| .. index:: |
| statement: break |
| .. _for: |
| |
| The :keyword:`for` statement |
| ============================ |
| |
| .. index:: |
| statement: for |
| pair: loop; statement |
n | |
| .. index:: object: sequence |
| |
| The :keyword:`for` statement is used to iterate over the elements of a sequence |
| (such as a string, tuple or list) or other iterable object: |
| |
| .. productionlist:: |
| for_stmt: "for" `target_list` "in" `expression_list` ":" `suite` |
| : ["else" ":" `suite`] |
| |
| .. index:: |
| keyword: in |
| keyword: else |
| pair: target; list |
n | object: sequence |
| |
| The :keyword:`for` statement is used to iterate over the elements of a sequence |
| (such as a string, tuple or list) or other iterable object: |
| |
| .. productionlist:: |
| for_stmt: "for" `target_list` "in" `expression_list` ":" `suite` |
| : ["else" ":" `suite`] |
| |
| The expression list is evaluated once; it should yield an iterable object. An |
| iterator is created for the result of the ``expression_list``. The suite is |
| then executed once for each item provided by the iterator, in the order of |
| ascending indices. Each item in turn is assigned to the target list using the |
| standard rules for assignments, and then the suite is executed. When the items |
| are exhausted (which is immediately when the sequence is empty), the suite in |
| the :keyword:`else` clause, if present, is executed, and the loop terminates. |
| |
| :: |
| |
| for x in a[:]: |
| if x < 0: a.remove(x) |
| |
| |
| .. _try: |
n | .. _except: |
| .. _finally: |
| |
| The :keyword:`try` statement |
| ============================ |
| |
n | .. index:: statement: try |
n | .. index:: |
| statement: try |
| keyword: except |
| keyword: finally |
| |
| The :keyword:`try` statement specifies exception handlers and/or cleanup code |
| for a group of statements: |
| |
| .. productionlist:: |
n | try_stmt: try1_stmt \| try2_stmt |
n | try_stmt: try1_stmt | try2_stmt |
| try1_stmt: "try" ":" `suite` |
n | : ("except" [`expression` ["," `target`]] ":" `suite`)+ |
n | : ("except" [`expression` [("as" | ",") `target`]] ":" `suite`)+ |
| : ["else" ":" `suite`] |
| : ["finally" ":" `suite`] |
| try2_stmt: "try" ":" `suite` |
| : "finally" ":" `suite` |
| |
| .. versionchanged:: 2.5 |
| In previous versions of Python, :keyword:`try`...\ :keyword:`except`...\ |
| :keyword:`finally` did not work. :keyword:`try`...\ :keyword:`except` had to be |
| nested in :keyword:`try`...\ :keyword:`finally`. |
n | |
| .. index:: keyword: except |
| |
| The :keyword:`except` clause(s) specify one or more exception handlers. When no |
| exception occurs in the :keyword:`try` clause, no exception handler is executed. |
| When an exception occurs in the :keyword:`try` 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 |
| single: exc_type (in module sys) |
| single: exc_value (in module sys) |
| single: exc_traceback (in module sys) |
| |
| Before an except clause's suite is executed, details about the exception are |
| assigned to three variables in the :mod:`sys` module: ``sys.exc_type`` receives |
| the object identifying the exception; ``sys.exc_value`` receives the exception's |
| parameter; ``sys.exc_traceback`` receives a traceback object (see section |
n | :ref:`traceback`) identifying the point in the program where the exception |
n | :ref:`types`) identifying the point in the program where the exception |
| occurred. These details are also available through the :func:`sys.exc_info` |
| function, which returns a tuple ``(exc_type, exc_value, exc_traceback)``. Use |
| of the corresponding variables is deprecated in favor of this function, since |
| their use is unsafe in a threaded program. As of Python 1.5, the variables are |
| restored to their previous values (before the call) when returning from a |
| function that handled an exception. |
| |
| .. index:: |
| lifted in the future). |
| |
| Additional information on exceptions can be found in section :ref:`exceptions`, |
| and information on using the :keyword:`raise` statement to generate exceptions |
| may be found in section :ref:`raise`. |
| |
| |
| .. _with: |
n | .. _as: |
| |
| The :keyword:`with` statement |
| ============================= |
| |
| .. index:: statement: with |
| |
| .. versionadded:: 2.5 |
| |
| The :keyword:`with` statement is used to wrap the execution of a block with |
| methods defined by a context manager (see section :ref:`context-managers`). This |
| allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` usage |
| patterns to be encapsulated for convenient reuse. |
| |
| .. productionlist:: |
n | with_stmt: "with" `expression` ["as" target] ":" `suite` |
n | with_stmt: "with" `expression` ["as" `target`] ":" `suite` |
| |
| The execution of the :keyword:`with` statement proceeds as follows: |
| |
| #. The context expression is evaluated to obtain a context manager. |
| |
| #. The context manager's :meth:`__enter__` method is invoked. |
| |
| #. If a target was included in the :keyword:`with` statement, the return value |
| |
| If the suite was exited for any reason other than an exception, the return value |
| from :meth:`__exit__` is ignored, and execution proceeds at the normal location |
| for the kind of exit that was taken. |
| |
| .. note:: |
| |
| In Python 2.5, the :keyword:`with` statement is only allowed when the |
n | ``with_statement`` feature has been enabled. It will always be enabled in |
n | ``with_statement`` feature has been enabled. It is always enabled in |
| Python 2.6. This ``__future__`` import statement can be used to enable the |
| Python 2.6. |
| feature:: |
| |
| from __future__ import with_statement |
| |
| |
| .. seealso:: |
| |
| :pep:`0343` - The "with" statement |
| The specification, background, and examples for the Python :keyword:`with` |
| statement. |
| |
| |
| .. _function: |
n | .. _def: |
| |
| Function definitions |
| ==================== |
| |
| .. index:: |
n | statement: def |
| pair: function; definition |
n | statement: def |
n | pair: function; name |
| |
| pair: name; binding |
| .. index:: |
| object: user-defined function |
| object: function |
| |
| A function definition defines a user-defined function object (see section |
| :ref:`types`): |
| |
| .. productionlist:: |
n | funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ":" `suite` |
n | decorated: decorators (classdef | funcdef) |
| decorators: `decorator`\ + |
| decorators: `decorator`+ |
| decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE |
n | funcdef: "def" `funcname` "(" [`parameter_list`] ")" ":" `suite` |
| dotted_name: `identifier` ("." `identifier`)\* |
| dotted_name: `identifier` ("." `identifier`)* |
| parameter_list: (`defparameter` ",")\* |
| parameter_list: (`defparameter` ",")* |
| : ( "\*" `identifier` [, "\*\*" `identifier`] |
| : ( "*" `identifier` [, "**" `identifier`] |
| : \| "\*\*" `identifier` |
| : | "**" `identifier` |
| : \| `defparameter` [","] ) |
| : | `defparameter` [","] ) |
| defparameter: `parameter` ["=" `expression`] |
n | sublist: `parameter` ("," `parameter`)\* [","] |
n | sublist: `parameter` ("," `parameter`)* [","] |
| parameter: `identifier` \| "(" `sublist` ")" |
| parameter: `identifier` | "(" `sublist` ")" |
| funcname: `identifier` |
n | |
| .. index:: |
| pair: function; name |
| pair: name; binding |
| |
| 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. |
| |
| The function definition does not execute the function body; this gets executed |
n | only when the function is called. |
n | only when the function is called. [#]_ |
| |
n | .. index:: |
| statement: @ |
| |
| A function definition may be wrapped by one or more decorator expressions. |
| A function definition may be wrapped by one or more :term:`decorator` 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:: |
| |
| @f1(arg) |
| @f2 |
| as the default, and explicitly test for it in the body of the function, e.g.:: |
| |
| def whats_on_the_telly(penguin=None): |
| if penguin is None: |
| penguin = [] |
| penguin.append("property of the zoo") |
| return penguin |
| |
n | .. index:: |
| statement: * |
| statement: ** |
| |
| Function call semantics are described in more detail in section :ref:`calls`. 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 "``*identifier``" is present, it is initialized to a tuple |
| receiving any excess positional parameters, defaulting to the empty tuple. If |
| the form "``**identifier``" is present, it is initialized to a new dictionary |
| receiving any excess keyword arguments, defaulting to a new empty dictionary. |
| |
| |
| |
| .. _class: |
| |
| Class definitions |
| ================= |
| |
| .. index:: |
n | object: class |
| statement: class |
| pair: class; definition |
n | statement: class |
n | pair: class; name |
| |
| pair: name; binding |
| .. index:: object: class |
| pair: execution; frame |
| single: inheritance |
| single: docstring |
| |
| A class definition defines a class object (see section :ref:`types`): |
| |
| .. productionlist:: |
| classdef: "class" `classname` [`inheritance`] ":" `suite` |
| inheritance: "(" [`expression_list`] ")" |
| classname: `identifier` |
n | |
| .. index:: |
| single: inheritance |
| pair: class; name |
| pair: name; binding |
| pair: execution; frame |
| |
| A class definition is an executable statement. It first evaluates the |
| inheritance list, if present. Each item in the inheritance list should evaluate |
| to a class object or class type which allows subclassing. The class's suite is |
| then executed in a new execution frame (see section :ref:`naming`), using a |
| newly created local namespace and the original global namespace. (Usually, the |
| suite contains only function definitions.) When the class's suite finishes |
n | execution, its execution frame is discarded but its local namespace is saved. A |
n | execution, its execution frame is discarded but its local namespace is |
| class object is then created using the inheritance list for the base classes and |
| saved. [#]_ A class object is then created using the inheritance list for the |
| the saved local namespace for the attribute dictionary. The class name is bound |
| base classes and the saved local namespace for the attribute dictionary. The |
| to this class object in the original local namespace. |
| class name is bound to this class object in the original local namespace. |
| |
| **Programmer's note:** Variables defined in the class definition are class |
n | variables; they are shared by all instances. To define instance variables, they |
n | variables; they are shared by all instances. To create instance variables, they |
| must be given a value in the :meth:`__init__` method or in another method. Both |
| can be set in a method with ``self.name = value``. Both class and instance |
| class and instance variables are accessible through the notation |
| variables are accessible through the notation "``self.name``", and an instance |
| "``self.name``", and an instance variable hides a class variable with the same |
| variable hides a class variable with the same name when accessed in this way. |
| name when accessed in this way. Class variables with immutable values can be |
| Class variables can be used as defaults for instance variables, but using |
| used as defaults for instance variables. For new-style classes, descriptors can |
| mutable values there can lead to unexpected results. For :term:`new-style |
| be used to create instance variables with different implementation details. |
| class`\es, descriptors can be used to create instance variables with different |
| implementation details. |
| |
| Class definitions, like function definitions, may be wrapped by one or more |
| :term:`decorator` expressions. The evaluation rules for the decorator |
| expressions are the same as for functions. The result must be a class object, |
| which is then bound to the class name. |
| |
| .. rubric:: Footnotes |
| |
n | .. [#] The exception is propogated to the invocation stack only if there is no |
n | .. [#] The exception is propagated to the invocation stack only if there is no |
| :keyword:`finally` clause that negates the exception. |
| |
| .. [#] Currently, control "flows off the end" except in the case of an exception or the |
| execution of a :keyword:`return`, :keyword:`continue`, or :keyword:`break` |
| statement. |
| |
t | .. [#] A string literal appearing as the first statement in the function body is |
| transformed into the function's ``__doc__`` attribute and therefore the |
| function's :term:`docstring`. |
| |
| .. [#] A string literal appearing as the first statement in the class body is |
| transformed into the namespace's ``__doc__`` item and therefore the class's |
| :term:`docstring`. |