ReStructuredText | 64 lines | 44 code | 20 blank | 0 comment | 0 complexity | fdc5c426e3209dce441617e8311c6dcd MD5 | raw file
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 19 can be inspected programmatically via importing :mod:`__future__` and examining 20 its contents. 21 22Each statement in :file:`__future__.py` is of the form:: 23 24 FeatureName = _Feature(OptionalRelease, MandatoryRelease, 25 CompilerFlag) 26 27 28where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are 295-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 40In the case of a *MandatoryRelease* that has not yet occurred, 41*MandatoryRelease* predicts the release in which the feature will become part of 42the language. 43 44Else *MandatoryRelease* records when the feature became part of the language; in 45releases at or after that, modules no longer need a future statement to use the 46feature in question, but may continue to use such imports. 47 48*MandatoryRelease* may also be ``None``, meaning that a planned feature got 49dropped. 50 51Instances 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 55argument to the builtin function :func:`compile` to enable the feature in 56dynamically compiled code. This flag is stored in the :attr:`compiler_flag` 57attribute on :class:`_Feature` instances. 58 59No feature description will ever be deleted from :mod:`__future__`. 60 61.. seealso:: 62 63 :ref:`future` 64 How the compiler treats future imports.