Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`__future__` --- Future statement definitions |
| 2 | ================================================== |
| 3 | |
| 4 | .. module:: __future__ |
| 5 | :synopsis: Future statement definitions |
| 6 | |
Raymond Hettinger | 3029aff | 2011-02-10 08:09:36 +0000 | [diff] [blame] | 7 | **Source code:** :source:`Lib/__future__.py` |
| 8 | |
| 9 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 225f169 | 2009-09-14 14:49:30 +0000 | [diff] [blame] | 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). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 22 | can be inspected programmatically via importing :mod:`__future__` and examining |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | its contents. |
| 24 | |
| 25 | Each statement in :file:`__future__.py` is of the form:: |
| 26 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 27 | FeatureName = _Feature(OptionalRelease, MandatoryRelease, |
| 28 | CompilerFlag) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | |
| 30 | |
| 31 | where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are |
Éric Araujo | 10f3d7a | 2011-04-27 16:22:32 +0200 | [diff] [blame] | 32 | 5-tuples of the same form as :data:`sys.version_info`:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 58 | argument to the built-in function :func:`compile` to enable the feature in |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 59 | dynamically compiled code. This flag is stored in the :attr:`compiler_flag` |
| 60 | attribute on :class:`_Feature` instances. |
| 61 | |
Georg Brandl | 225f169 | 2009-09-14 14:49:30 +0000 | [diff] [blame] | 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 | +------------------+-------------+--------------+---------------------------------------------+ |
Petri Lehtinen | 079bfc9 | 2012-05-19 18:34:06 +0300 | [diff] [blame] | 78 | | absolute_import | 2.5.0a1 | 3.0 | :pep:`328`: | |
Georg Brandl | 225f169 | 2009-09-14 14:49:30 +0000 | [diff] [blame] | 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 | +------------------+-------------+--------------+---------------------------------------------+ |
Georg Brandl | 277b6f9 | 2009-09-15 19:55:15 +0000 | [diff] [blame] | 90 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |
Georg Brandl | ff2ad0e | 2009-04-27 16:51:45 +0000 | [diff] [blame] | 92 | .. seealso:: |
| 93 | |
| 94 | :ref:`future` |
| 95 | How the compiler treats future imports. |