This is /home/pdm/install/Python-2.1/Doc/ref/python-ref.info, produced by makeinfo version 4.0 from ref.texi. April 15, 2001 2.1  File: python-ref.info, Node: Future statements, Next: __future__, Prev: Future statements and nested scopes, Up: Future statements and nested scopes Future statements ================= A "future statement" is a directive to the compiler that a particular module should be compiled using syntax or semantics that will be available in a specified future release of Python. The future statement is intended to ease migration to future versions of Python that introduce incompatible changes to the language. It allows use of the new features on a per-module basis before the release in which the feature becomes standard. future_statement: "from" "__future__" "import" feature ["as" name] ("," feature ["as" name])* feature: identifier name: identifier A future statement must appear near the top of the module. The only lines that can appear before a future statement are: * the module docstring (if any), * comments, * blank lines, and * other future statements. The only feature recognized by Python 2.1 is `nested_scopes'. A future statement is recognized and treated specially at compile time: Changes to the semantics of core constructs are often implemented by generating different code. It may even be the case that a new feature introduces new incompatible syntax (such as a new reserved word), in which case the compiler may need to parse the module differently. Such decisions cannot be pushed off until runtime. For any given release, the compiler knows which feature names have been defined, and raises a compile-time error if a future statement contains a feature not known to it. The direct runtime semantics are the same as for any import statement: there is a standard module `__future__', described later, and it will be imported in the usual way at the time the future statement is executed. The interesting runtime semantics depend on the specific feature enabled by the future statement. Note that there is nothing special about the statement: import __future__ [as name] That is not a future statement; it's an ordinary import statement with no special semantics or syntax restrictions. Code compiled by an exec statement or calls to the builtin functions `compile()' and `execfile()' that occur in a module `M' containing a future statement will use the new syntax or semantics associated with the future statement. A future statement typed at an interactive interpreter prompt will take effect for the rest of the interpreter session. If an interpreter is started with the `-i' option, is passed a script name to execute, and the script includes a future statement, it will be in effect in the interactive session started after the script is executed.  File: python-ref.info, Node: __future__, Next: Nested scopes, Prev: Future statements, Up: Future statements and nested scopes Future statement definitions ============================ Future statement definitions `__future__' is a real module, and serves three purposes: * To avoid confusing existing tools that analyze import statements and expect to find the modules they're importing. * To ensure that future_statements run under releases prior to 2.1 at least yield runtime exceptions (the import of `__future__' will fail, because there was no module of that name prior to 2.1). * To document when incompatible changes were introduced, and when they will be -- or were -- made mandatory. This is a form of executable documentation, and can be inspected programatically via importing `__future__' and examining its contents. Each statment in `__future__.py' is of the form: FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ")" where, normally, OptionalRelease is less then MandatoryRelease, and both are 5-tuples of the same form as `sys.version_info': (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int PY_MINOR_VERSION, # the 1; an int PY_MICRO_VERSION, # the 0; an int PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string PY_RELEASE_SERIAL # the 3; an int ) OptionalRelease records the first release in which the feature was accepted. In the case of MandatoryReleases that have not yet occurred, MandatoryRelease predicts the release in which the feature will become part of the language. Else MandatoryRelease records when the feature became part of the language; in releases at or after that, modules no longer need a future statement to use the feature in question, but may continue to use such imports. MandatoryRelease may also be `None', meaning that a planned feature got dropped. Instances of class `_Feature' have two corresponding methods, `getOptionalRelease()' and `getMandatoryRelease()'. No feature description will ever be deleted from `__future__'.  File: python-ref.info, Node: Nested scopes, Prev: __future__, Up: Future statements and nested scopes Nested scopes ============= This section defines the new scoping semantics that will be introduced in Python 2.2. They are available in Python 2.1 by using the future statement `nested_scopes'. This section begins with a bit of terminology. * Menu: * Definitions and rules:: * Interaction with dynamic features::  File: python-ref.info, Node: Definitions and rules, Next: Interaction with dynamic features, Prev: Nested scopes, Up: Nested scopes Definitions and rules --------------------- "Names" refer to objects. Names are introduced by name binding operations. Each occurrence of a name in the program text refers to the binding of that name established in the innermost function block containing the use. A "block" is a pice of Python program text that can is executed as a unit. The following are blocks: a module, a function body, and a class defintion. A "scope" defines the visibility of a name within a block. If a local variable is defined in a block, it's scope includes that block. If the definition occurs in a function block, the scope extends to any blocks contained within the defining one, unless a contained block introduces a different binding for the name. The scope of names defined in a class block is limited to the class block; it does not extend to the code blocks of methods. When a name is used in a code block, it is resolved using the nearest enclosing scope. The set of all such scopes visible to a code block is called the block's "environment". If a name is bound in a block, it is a local variable of that block. If a name is bound at the module level, it is a global variable. (The variables of the module code block are local and global.) If a variable is used in a code block but not defined there, it is a "free variable". The name binding operations are assignment, class and function definition, import statements, for statements, and except statements. Each assignment or import statement occurs within a block defined by a class or function definition or at the module level (the top-level code block). If a name binding operation occurs anywhere within a code block, all uses of the name within the block are treated as references to the current block. This can lead to errors when a name is used within a block before it is bound. The previous rule is a subtle. Python lacks declarations and allows name binding operations to occur anywhere within a code block. The local variables of a code block can be determined by scanning the entire text of the block for name binding operations. If the global statement occurs within a block, all uses of the name specified in the statement refer to the binding of that name in the top-level namespace. Names are resolved in the top-level namespace by searching the global namespace, i.e. the namespace of the module containing the code block, and the builtin namespace, the namespace of the module `__builtin__'. The global namespace is searched first. If the name is not found there, the builtin namespace is searched. The global statement must precede all uses of the name. The global statement has the same scope as a name binding operation in the same block. If the nearest enclosing scope for a free variable contains a global statement, the free variable is treated as a global. A class definition is an executable statement that may use and define names. These references follow the normal rules for name resolution. The namespace of the class definition becomes the attribute dictionary of the class. Names defined at the class scope are not visible in methods.  File: python-ref.info, Node: Interaction with dynamic features, Prev: Definitions and rules, Up: Nested scopes Interaction with dynamic features --------------------------------- There are several cases where Python statements are illegal when used in conjunction with nested scopes that contain free variables. If a variable is referenced in an enclosing scope, it is illegal to delete the name. An error will be reported at compile time. If the wild card form of import -- `import *' -- is used in a function and the function contains or is a nested block with free variables, the compiler will raise a SyntaxError. If exec is used in a function and the function contains or is a nested block with free variables, the compiler will raise a SyntaxError unless the exec explicitly specifies the local namespace for the exec. (In other words, "exec obj" would be illegal, but "exec obj in ns" would be legal.) The builtin functions `eval()' and `input()' can not access free variables unless the variables are also referenced by the program text of the block that contains the call to `eval()' or `input()'. _Compatibility note_: The compiler for Python 2.1 will issue warnings for uses of nested functions that will behave differently with nested scopes. The warnings will not be issued if nested scopes are enabled via a future statement. If a name bound in a function scope and the function contains a nested function scope that uses the name, the compiler will issue a warning. The name resolution rules will result in different bindings under Python 2.1 than under Python 2.2. The warning indicates that the program may not run correctly with all versions of Python.  File: python-ref.info, Node: Module Index, Next: Class-Exception-Object Index, Prev: Future statements and nested scopes, Up: Top Module Index ************ * Menu: * __abs__: Emulating numeric types. * __and__: Emulating numeric types. * __builtin__ <1>: Complete Python programs. * __builtin__ <2>: exec statement. * __builtin__: Code blocks. * __div__: Emulating numeric types. * __divmod__: Emulating numeric types. * __eq__: Basic customization. * __float__: Emulating numeric types. * __ge__: Basic customization. * __gt__: Basic customization. * __hex__: Emulating numeric types. * __iand__: Emulating numeric types. * __idiv__: Emulating numeric types. * __ilshift__: Emulating numeric types. * __imod__: Emulating numeric types. * __imul__: Emulating numeric types. * __int__: Emulating numeric types. * __invert__: Emulating numeric types. * __ior__: Emulating numeric types. * __ipow__: Emulating numeric types. * __irshift__: Emulating numeric types. * __isub__: Emulating numeric types. * __ixor__: Emulating numeric types. * __le__: Basic customization. * __long__: Emulating numeric types. * __lshift__: Emulating numeric types. * __main__ <1>: Complete Python programs. * __main__: Code blocks. * __mod__: Emulating numeric types. * __mul__: Emulating numeric types. * __ne__: Basic customization. * __or__: Emulating numeric types. * __pos__: Emulating numeric types. * __pow__: Emulating numeric types. * __rand__: Emulating numeric types. * __rdiv__: Emulating numeric types. * __rdivmod__: Emulating numeric types. * __rlshift__: Emulating numeric types. * __rmod__: Emulating numeric types. * __rmul__: Emulating numeric types. * __ror__: Emulating numeric types. * __rpow__: Emulating numeric types. * __rrshift__: Emulating numeric types. * __rshift__: Emulating numeric types. * __rsub__: Emulating numeric types. * __rxor__: Emulating numeric types. * __sub__: Emulating numeric types. * __xor__: Emulating numeric types. * array: standard type hierarchy. * bsddb: standard type hierarchy. * dbm: standard type hierarchy. * gdbm: standard type hierarchy. * sys <1>: Complete Python programs. * sys <2>: try statement. * sys <3>: import statement. * sys: print statement.  File: python-ref.info, Node: Class-Exception-Object Index, Next: Function-Method-Variable Index, Prev: Module Index, Up: Top Class, Exception, and Object Index ********************************** * Menu: * AssertionError: Assert statements. * AttributeError: Attribute references. * built-in function <1>: Calls. * built-in function: standard type hierarchy. * built-in method <1>: Calls. * built-in method: standard type hierarchy. * callable <1>: Calls. * callable: standard type hierarchy. * class <1>: Class definitions. * class <2>: Calls. * class: standard type hierarchy. * class instance <1>: Calls. * class instance: standard type hierarchy. * code: standard type hierarchy. * complex: standard type hierarchy. * dictionary <1>: Assignment statements. * dictionary <2>: Subscriptions. * dictionary <3>: Dictionary displays. * dictionary <4>: Basic customization. * dictionary: standard type hierarchy. * Ellipsis@Ellipsis: standard type hierarchy. * file <1>: Expression input. * file: standard type hierarchy. * floating point: standard type hierarchy. * frame: standard type hierarchy. * function <1>: Function definitions. * function <2>: Calls. * function: standard type hierarchy. * immutable: standard type hierarchy. * immutable sequence: standard type hierarchy. * ImportError: import statement. * instance <1>: Calls. * instance: standard type hierarchy. * integer: standard type hierarchy. * list <1>: Assignment statements. * list <2>: Slicings. * list <3>: Subscriptions. * list <4>: Attribute references. * list <5>: List displays. * list: standard type hierarchy. * long integer: standard type hierarchy. * mapping <1>: Assignment statements. * mapping <2>: Subscriptions. * mapping: standard type hierarchy. * method <1>: Calls. * method: standard type hierarchy. * module <1>: Attribute references. * module: standard type hierarchy. * mutable <1>: Assignment statements. * mutable: standard type hierarchy. * mutable sequence: standard type hierarchy. * NameError: Identifiers Names. * None@None: standard type hierarchy. * NotImplemented@NotImplemented: standard type hierarchy. * numeric: standard type hierarchy. * plain integer: standard type hierarchy. * recursive: String conversions. * RuntimeError: print statement. * sequence <1>: for statement. * sequence <2>: Assignment statements. * sequence <3>: Comparisons. * sequence <4>: Slicings. * sequence <5>: Subscriptions. * sequence: standard type hierarchy. * slice: Emulating sequence and mapping types. * string <1>: Slicings. * string <2>: Subscriptions. * string: standard type hierarchy. * SyntaxError <1>: exec statement. * SyntaxError: import statement. * traceback <1>: try statement. * traceback <2>: raise statement. * traceback: standard type hierarchy. * tuple <1>: Expression lists. * tuple <2>: Slicings. * tuple <3>: Subscriptions. * tuple: standard type hierarchy. * TypeError: Unary arithmetic operations. * unicode: standard type hierarchy. * user-defined function <1>: Function definitions. * user-defined function <2>: Calls. * user-defined function: standard type hierarchy. * user-defined method: standard type hierarchy. * ValueError: Shifting operations. * ZeroDivisionError: Binary arithmetic operations.  File: python-ref.info, Node: Function-Method-Variable Index, Next: Miscellaneous Index, Prev: Class-Exception-Object Index, Up: Top Function, Method, and Variable Index ************************************ * Menu: * __add__: Emulating numeric types. * __call__: Emulating callable objects. * __cmp__: Basic customization. * __coerce__: Emulating numeric types. * __complex__: Emulating numeric types. * __contains__: Additional methods for emulation of sequence types. * __del__: Basic customization. * __delattr__: Customizing attribute access. * __delitem__: Emulating sequence and mapping types. * __delslice__: Additional methods for emulation of sequence types. * __getattr__: Customizing attribute access. * __getitem__: Emulating sequence and mapping types. * __getslice__: Additional methods for emulation of sequence types. * __hash__: Basic customization. * __iadd__: Emulating numeric types. * __import__: import statement. * __init__: Basic customization. * __len__: Emulating sequence and mapping types. * __lt__: Basic customization. * __neg__: Emulating numeric types. * __nonzero__: Basic customization. * __oct__: Emulating numeric types. * __radd__: Emulating numeric types. * __rcmp__: Basic customization. * __repr__: Basic customization. * __setattr__: Customizing attribute access. * __setitem__: Emulating sequence and mapping types. * __setslice__: Additional methods for emulation of sequence types. * __str__: Basic customization. * abs: Emulating numeric types. * chr: standard type hierarchy. * cmp: Basic customization. * compile: global statement. * complex: Emulating numeric types. * divmod: Emulating numeric types. * eval <1>: Expression input. * eval <2>: exec statement. * eval: global statement. * execfile: global statement. * float: Emulating numeric types. * globals: exec statement. * hash: Basic customization. * hex: Emulating numeric types. * id: Objects. * input: Expression input. * int: Emulating numeric types. * len <1>: Emulating sequence and mapping types. * len: standard type hierarchy. * locals: exec statement. * long: Emulating numeric types. * oct: Emulating numeric types. * open: standard type hierarchy. * ord: standard type hierarchy. * pow: Emulating numeric types. * range: for statement. * raw_input: Expression input. * repr <1>: Expression statements. * repr <2>: String conversions. * repr: Basic customization. * slice: standard type hierarchy. * str <1>: String conversions. * str: Basic customization. * type: Objects. * unichr: standard type hierarchy. * unicode: standard type hierarchy.