Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 1 | \section{\module{__future__} --- |
| 2 | Future statement definitions} |
| 3 | |
| 4 | \declaremodule[future]{standard}{__future__} |
| 5 | \modulesynopsis{Future statement definitions} |
| 6 | |
| 7 | \module{__future__} is a real module, and serves three purposes: |
| 8 | |
| 9 | \begin{itemize} |
| 10 | |
| 11 | \item To avoid confusing existing tools that analyze import statements |
| 12 | and expect to find the modules they're importing. |
| 13 | |
| 14 | \item To ensure that future_statements run under releases prior to 2.1 |
| 15 | at least yield runtime exceptions (the import of |
| 16 | \module{__future__} will fail, because there was no module of |
| 17 | that name prior to 2.1). |
| 18 | |
| 19 | \item To document when incompatible changes were introduced, and when they |
| 20 | will be --- or were --- made mandatory. This is a form of executable |
| 21 | documentation, and can be inspected programatically via importing |
| 22 | \module{__future__} and examining its contents. |
| 23 | |
| 24 | \end{itemize} |
| 25 | |
Raymond Hettinger | 02771c1 | 2003-08-05 11:40:21 +0000 | [diff] [blame] | 26 | Each statement in \file{__future__.py} is of the form: |
Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 27 | |
Fred Drake | 74530ff | 2003-09-05 15:50:20 +0000 | [diff] [blame] | 28 | \begin{alltt} |
| 29 | FeatureName = "_Feature(" \var{OptionalRelease} "," \var{MandatoryRelease} "," |
| 30 | \var{CompilerFlag} ")" |
| 31 | \end{alltt} |
Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 32 | |
Fred Drake | 74530ff | 2003-09-05 15:50:20 +0000 | [diff] [blame] | 33 | where, normally, \var{OptionalRelease} is less than |
| 34 | \var{MandatoryRelease}, and both are 5-tuples of the same form as |
| 35 | \code{sys.version_info}: |
Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 36 | |
| 37 | \begin{verbatim} |
| 38 | (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int |
| 39 | PY_MINOR_VERSION, # the 1; an int |
| 40 | PY_MICRO_VERSION, # the 0; an int |
| 41 | PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string |
| 42 | PY_RELEASE_SERIAL # the 3; an int |
| 43 | ) |
| 44 | \end{verbatim} |
| 45 | |
Fred Drake | 74530ff | 2003-09-05 15:50:20 +0000 | [diff] [blame] | 46 | \var{OptionalRelease} records the first release in which the feature |
| 47 | was accepted. |
Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 48 | |
Fred Drake | 74530ff | 2003-09-05 15:50:20 +0000 | [diff] [blame] | 49 | In the case of a \var{MandatoryRelease} that has not yet occurred, |
| 50 | \var{MandatoryRelease} predicts the release in which the feature will |
| 51 | become part of the language. |
Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 52 | |
Fred Drake | 74530ff | 2003-09-05 15:50:20 +0000 | [diff] [blame] | 53 | Else \var{MandatoryRelease} records when the feature became part of |
| 54 | the language; in releases at or after that, modules no longer need a |
Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 55 | future statement to use the feature in question, but may continue to |
Fred Drake | 74530ff | 2003-09-05 15:50:20 +0000 | [diff] [blame] | 56 | use such imports. |
Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 57 | |
Fred Drake | 74530ff | 2003-09-05 15:50:20 +0000 | [diff] [blame] | 58 | \var{MandatoryRelease} may also be \code{None}, meaning that a planned |
Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 59 | feature got dropped. |
| 60 | |
| 61 | Instances of class \class{_Feature} have two corresponding methods, |
| 62 | \method{getOptionalRelease()} and \method{getMandatoryRelease()}. |
| 63 | |
Fred Drake | 74530ff | 2003-09-05 15:50:20 +0000 | [diff] [blame] | 64 | \var{CompilerFlag} is the (bitfield) flag that should be passed in the |
Jeremy Hylton | e41195f | 2003-05-21 21:45:01 +0000 | [diff] [blame] | 65 | fourth argument to the builtin function \function{compile()} to enable |
| 66 | the feature in dynamically compiled code. This flag is stored in the |
| 67 | \member{compiler_flag} attribute on \class{_Future} instances. |
| 68 | |
| 69 | No feature description will ever be deleted from \module{__future__}. |