Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libfuture.tex @ 32527:0da660e05e69 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"#if WITH_THREAD" is incorrect; must be #ifdef instead; WITH_THREAD isn't always set to an integer value when it's defined.
author Tim Peters <tim.peters@gmail.com>
date Wed, 07 Jul 2004 20:42:07 +0000
parents 562089a8678f
children fdf1be9cfedf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
1 \section{\module{__future__} ---
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
2 Future statement definitions}
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
3
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
4 \declaremodule[future]{standard}{__future__}
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
5 \modulesynopsis{Future statement definitions}
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
6
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
7 \module{__future__} is a real module, and serves three purposes:
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
8
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
9 \begin{itemize}
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
10
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
11 \item To avoid confusing existing tools that analyze import statements
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
12 and expect to find the modules they're importing.
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
13
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
14 \item To ensure that future_statements run under releases prior to 2.1
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
15 at least yield runtime exceptions (the import of
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
16 \module{__future__} will fail, because there was no module of
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
17 that name prior to 2.1).
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
18
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
19 \item To document when incompatible changes were introduced, and when they
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
20 will be --- or were --- made mandatory. This is a form of executable
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
21 documentation, and can be inspected programatically via importing
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
22 \module{__future__} and examining its contents.
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
23
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
24 \end{itemize}
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
25
30067
9bd5c052b308 SF patch #782810: typo in libfuture.tex
Raymond Hettinger <python@rcn.com>
parents: 29285
diff changeset
26 Each statement in \file{__future__.py} is of the form:
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
27
30337
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
28 \begin{alltt}
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
29 FeatureName = "_Feature(" \var{OptionalRelease} "," \var{MandatoryRelease} ","
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
30 \var{CompilerFlag} ")"
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
31 \end{alltt}
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
32
30337
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
33 where, normally, \var{OptionalRelease} is less than
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
34 \var{MandatoryRelease}, and both are 5-tuples of the same form as
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
35 \code{sys.version_info}:
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
36
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
37 \begin{verbatim}
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
38 (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
39 PY_MINOR_VERSION, # the 1; an int
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
40 PY_MICRO_VERSION, # the 0; an int
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
41 PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
42 PY_RELEASE_SERIAL # the 3; an int
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
43 )
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
44 \end{verbatim}
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
45
30337
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
46 \var{OptionalRelease} records the first release in which the feature
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
47 was accepted.
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
48
30337
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
49 In the case of a \var{MandatoryRelease} that has not yet occurred,
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
50 \var{MandatoryRelease} predicts the release in which the feature will
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
51 become part of the language.
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
52
30337
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
53 Else \var{MandatoryRelease} records when the feature became part of
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
54 the language; in releases at or after that, modules no longer need a
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
55 future statement to use the feature in question, but may continue to
30337
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
56 use such imports.
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
57
30337
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
58 \var{MandatoryRelease} may also be \code{None}, meaning that a planned
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
59 feature got dropped.
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
60
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
61 Instances of class \class{_Feature} have two corresponding methods,
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
62 \method{getOptionalRelease()} and \method{getMandatoryRelease()}.
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
63
30337
562089a8678f markup updates
Fred Drake <fdrake@acm.org>
parents: 30067
diff changeset
64 \var{CompilerFlag} is the (bitfield) flag that should be passed in the
29285
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
65 fourth argument to the builtin function \function{compile()} to enable
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
66 the feature in dynamically compiled code. This flag is stored in the
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
67 \member{compiler_flag} attribute on \class{_Future} instances.
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
68
949f41829f36 Rename lib__future__.tex to libfuture.tex and add link in lib.tex.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
diff changeset
69 No feature description will ever be deleted from \module{__future__}.