Home | History | Annotate | Download | only in library 
      1 :mod:`__future__` --- Future statement definitions
      2 ==================================================
      3 
      4 .. module:: __future__
      5    :synopsis: Future statement definitions
      6 
      7 **Source code:** :source:`Lib/__future__.py`
      8 
      9 --------------
     10 
     11 :mod:`__future__` is a real module, and serves three purposes:
     12 
     13 * To avoid confusing existing tools that analyze import statements and expect to
     14   find the modules they're importing.
     15 
     16 * To ensure that :ref:`future statements <future>` run under releases prior to
     17   2.1 at least yield runtime exceptions (the import of :mod:`__future__` will
     18   fail, because there was no module of that name prior to 2.1).
     19 
     20 * To document when incompatible changes were introduced, and when they will be
     21   --- or were --- made mandatory.  This is a form of executable documentation, and
     22   can be inspected programmatically via importing :mod:`__future__` and examining
     23   its contents.
     24 
     25 Each statement in :file:`__future__.py` is of the form::
     26 
     27    FeatureName = _Feature(OptionalRelease, MandatoryRelease,
     28                           CompilerFlag)
     29 
     30 
     31 where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
     32 5-tuples of the same form as ``sys.version_info``::
     33 
     34    (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
     35     PY_MINOR_VERSION, # the 1; an int
     36     PY_MICRO_VERSION, # the 0; an int
     37     PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
     38     PY_RELEASE_SERIAL # the 3; an int
     39    )
     40 
     41 *OptionalRelease* records the first release in which the feature was accepted.
     42 
     43 In the case of a *MandatoryRelease* that has not yet occurred,
     44 *MandatoryRelease* predicts the release in which the feature will become part of
     45 the language.
     46 
     47 Else *MandatoryRelease* records when the feature became part of the language; in
     48 releases at or after that, modules no longer need a future statement to use the
     49 feature in question, but may continue to use such imports.
     50 
     51 *MandatoryRelease* may also be ``None``, meaning that a planned feature got
     52 dropped.
     53 
     54 Instances of class :class:`_Feature` have two corresponding methods,
     55 :meth:`getOptionalRelease` and :meth:`getMandatoryRelease`.
     56 
     57 *CompilerFlag* is the (bitfield) flag that should be passed in the fourth
     58 argument to the built-in function :func:`compile` to enable the feature in
     59 dynamically compiled code.  This flag is stored in the :attr:`compiler_flag`
     60 attribute on :class:`_Feature` instances.
     61 
     62 No feature description will ever be deleted from :mod:`__future__`. Since its
     63 introduction in Python 2.1 the following features have found their way into the
     64 language using this mechanism:
     65 
     66 +------------------+-------------+--------------+---------------------------------------------+
     67 | feature          | optional in | mandatory in | effect                                      |
     68 +==================+=============+==============+=============================================+
     69 | nested_scopes    | 2.1.0b1     | 2.2          | :pep:`227`:                                 |
     70 |                  |             |              | *Statically Nested Scopes*                  |
     71 +------------------+-------------+--------------+---------------------------------------------+
     72 | generators       | 2.2.0a1     | 2.3          | :pep:`255`:                                 |
     73 |                  |             |              | *Simple Generators*                         |
     74 +------------------+-------------+--------------+---------------------------------------------+
     75 | division         | 2.2.0a2     | 3.0          | :pep:`238`:                                 |
     76 |                  |             |              | *Changing the Division Operator*            |
     77 +------------------+-------------+--------------+---------------------------------------------+
     78 | absolute_import  | 2.5.0a1     | 3.0          | :pep:`328`:                                 |
     79 |                  |             |              | *Imports: Multi-Line and Absolute/Relative* |
     80 +------------------+-------------+--------------+---------------------------------------------+
     81 | with_statement   | 2.5.0a1     | 2.6          | :pep:`343`:                                 |
     82 |                  |             |              | *The "with" Statement*                      |
     83 +------------------+-------------+--------------+---------------------------------------------+
     84 | print_function   | 2.6.0a2     | 3.0          | :pep:`3105`:                                |
     85 |                  |             |              | *Make print a function*                     |
     86 +------------------+-------------+--------------+---------------------------------------------+
     87 | unicode_literals | 2.6.0a2     | 3.0          | :pep:`3112`:                                |
     88 |                  |             |              | *Bytes literals in Python 3000*             |
     89 +------------------+-------------+--------------+---------------------------------------------+
     90 
     91 .. seealso::
     92 
     93    :ref:`future`
     94       How the compiler treats future imports.
     95