Skip to content

__future__.rst

Latest commit

 

History

History
117 lines (89 loc) · 6.15 KB

__future__.rst

File metadata and controls

117 lines (89 loc) · 6.15 KB
Raw

:mod:`__future__` --- Future statement definitions

.. module:: __future__
   :synopsis: Future statement definitions

Source code: :source:`Lib/__future__.py`

:mod:`__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 :ref:`future statements <future>` run under releases prior to 2.1 at least yield runtime exceptions (the import of :mod:`__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 programmatically via importing :mod:`__future__` and examining its contents.

Each statement in :file:`__future__.py` is of the form:

FeatureName = _Feature(OptionalRelease, MandatoryRelease,
                       CompilerFlag)

where, normally, OptionalRelease is less than MandatoryRelease, and both are 5-tuples of the same form as :data:`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
)

.. method:: _Feature.getOptionalRelease()

   *OptionalRelease* records the first release in which the feature was accepted.


.. method:: _Feature.getMandatoryRelease()

   In the case of a *MandatoryRelease* that has 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 or that it is not yet decided.


.. attribute:: _Feature.compiler_flag

   *CompilerFlag* is the (bitfield) flag that should be passed in the fourth
   argument to the built-in function :func:`compile` to enable the feature in
   dynamically compiled code.  This flag is stored in the :attr:`_Feature.compiler_flag`
   attribute on :class:`_Feature` instances.

No feature description will ever be deleted from :mod:`__future__`. Since its introduction in Python 2.1 the following features have found their way into the language using this mechanism:

feature optional in mandatory in effect
nested_scopes 2.1.0b1 2.2 PEP 227: Statically Nested Scopes
generators 2.2.0a1 2.3 PEP 255: Simple Generators
division 2.2.0a2 3.0 PEP 238: Changing the Division Operator
absolute_import 2.5.0a1 3.0 PEP 328: Imports: Multi-Line and Absolute/Relative
with_statement 2.5.0a1 2.6 PEP 343: The "with" Statement
print_function 2.6.0a2 3.0 PEP 3105: Make print a function
unicode_literals 2.6.0a2 3.0 PEP 3112: Bytes literals in Python 3000
generator_stop 3.5.0b1 3.7 PEP 479: StopIteration handling inside generators
annotations 3.7.0b1 TBD [1] PEP 563: Postponed evaluation of annotations
[1]from __future__ import annotations was previously scheduled to become mandatory in Python 3.10, but the Python Steering Council twice decided to delay the change (announcement for Python 3.10; announcement for Python 3.11). No final decision has been made yet. See also PEP 563 and PEP 649.
 
.. seealso::

   :ref:`future`
      How the compiler treats future imports.