From 116aa62bf54a39697e25f21d6cf6799f7faa1349 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 15 Aug 2007 14:28:22 +0000 Subject: Move the 3k reST doc tree in place. --- Doc/library/__future__.rst | 61 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 Doc/library/__future__.rst (limited to 'Doc/library/__future__.rst') diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst new file mode 100644 index 0000000000..6bf2830c29 --- /dev/null +++ b/Doc/library/__future__.rst @@ -0,0 +1,61 @@ + +:mod:`__future__` --- Future statement definitions +================================================== + +.. module:: __future__ + :synopsis: Future statement definitions + + +: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 future_statements 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 programatically 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 ``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 + ) + +*OptionalRelease* records the first release in which the feature was accepted. + +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. + +Instances of class :class:`_Feature` have two corresponding methods, +:meth:`getOptionalRelease` and :meth:`getMandatoryRelease`. + +*CompilerFlag* is the (bitfield) flag that should be passed in the fourth +argument to the builtin function :func:`compile` to enable the feature in +dynamically compiled code. This flag is stored in the :attr:`compiler_flag` +attribute on :class:`_Feature` instances. + +No feature description will ever be deleted from :mod:`__future__`. + -- cgit v1.2.1