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 | |
| 7 | |
| 8 | :mod:`__future__` is a real module, and serves three purposes: |
| 9 | |
| 10 | * To avoid confusing existing tools that analyze import statements and expect to |
| 11 | find the modules they're importing. |
| 12 | |
| 13 | * To ensure that future_statements run under releases prior to 2.1 at least |
| 14 | yield runtime exceptions (the import of :mod:`__future__` will fail, because |
| 15 | there was no module of that name prior to 2.1). |
| 16 | |
| 17 | * To document when incompatible changes were introduced, and when they will be |
| 18 | --- or were --- made mandatory. This is a form of executable documentation, and |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 19 | can be inspected programmatically via importing :mod:`__future__` and examining |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | its contents. |
| 21 | |
| 22 | Each statement in :file:`__future__.py` is of the form:: |
| 23 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 24 | FeatureName = _Feature(OptionalRelease, MandatoryRelease, |
| 25 | CompilerFlag) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
| 27 | |
| 28 | where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are |
| 29 | 5-tuples of the same form as ``sys.version_info``:: |
| 30 | |
| 31 | (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int |
| 32 | PY_MINOR_VERSION, # the 1; an int |
| 33 | PY_MICRO_VERSION, # the 0; an int |
| 34 | PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string |
| 35 | PY_RELEASE_SERIAL # the 3; an int |
| 36 | ) |
| 37 | |
| 38 | *OptionalRelease* records the first release in which the feature was accepted. |
| 39 | |
| 40 | In the case of a *MandatoryRelease* that has not yet occurred, |
| 41 | *MandatoryRelease* predicts the release in which the feature will become part of |
| 42 | the language. |
| 43 | |
| 44 | Else *MandatoryRelease* records when the feature became part of the language; in |
| 45 | releases at or after that, modules no longer need a future statement to use the |
| 46 | feature in question, but may continue to use such imports. |
| 47 | |
| 48 | *MandatoryRelease* may also be ``None``, meaning that a planned feature got |
| 49 | dropped. |
| 50 | |
| 51 | Instances of class :class:`_Feature` have two corresponding methods, |
| 52 | :meth:`getOptionalRelease` and :meth:`getMandatoryRelease`. |
| 53 | |
| 54 | *CompilerFlag* is the (bitfield) flag that should be passed in the fourth |
| 55 | argument to the builtin function :func:`compile` to enable the feature in |
| 56 | dynamically compiled code. This flag is stored in the :attr:`compiler_flag` |
| 57 | attribute on :class:`_Feature` instances. |
| 58 | |
| 59 | No feature description will ever be deleted from :mod:`__future__`. |
| 60 | |
Georg Brandl | ff2ad0e | 2009-04-27 16:51:45 +0000 | [diff] [blame] | 61 | .. seealso:: |
| 62 | |
| 63 | :ref:`future` |
| 64 | How the compiler treats future imports. |