/Doc/library/__future__.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 64 lines · 44 code · 20 blank · 0 comment · 0 complexity · fdc5c426e3209dce441617e8311c6dcd MD5 · raw file

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