Initial revision

Doc/ref/ref1.tex

+\chapter{Introduction}
+
+This reference manual describes the Python programming language.
+It is not intended as a tutorial.
+
+While I am trying to be as precise as possible, I chose to use English
+rather than formal specifications for everything except syntax and
+lexical analysis.  This should make the document better understandable
+to the average reader, but will leave room for ambiguities.
+Consequently, if you were coming from Mars and tried to re-implement
+Python from this document alone, you might have to guess things and in
+fact you would probably end up implementing quite a different language.
+On the other hand, if you are using
+Python and wonder what the precise rules about a particular area of
+the language are, you should definitely be able to find them here.
+
+It is dangerous to add too many implementation details to a language
+reference document --- the implementation may change, and other
+implementations of the same language may work differently.  On the
+other hand, there is currently only one Python implementation, and
+its particular quirks are sometimes worth being mentioned, especially
+where the implementation imposes additional limitations.  Therefore,
+you'll find short ``implementation notes'' sprinkled throughout the
+text.
+
+Every Python implementation comes with a number of built-in and
+standard modules.  These are not documented here, but in the separate
+{\em Python Library Reference} document.  A few built-in modules are
+mentioned when they interact in a significant way with the language
+definition.
+
+\section{Notation}
+
+The descriptions of lexical analysis and syntax use a modified BNF
+grammar notation.  This uses the following style of definition:
+\index{BNF}
+\index{grammar}
+\index{syntax}
+\index{notation}
+
+\begin{verbatim}
+name:           lc_letter (lc_letter | "_")*
+lc_letter:      "a"..."z"
+\end{verbatim}
+
+The first line says that a \verb\name\ is an \verb\lc_letter\ followed by
+a sequence of zero or more \verb\lc_letter\s and underscores.  An
+\verb\lc_letter\ in turn is any of the single characters `a' through `z'.
+(This rule is actually adhered to for the names defined in lexical and
+grammar rules in this document.)
+
+Each rule begins with a name (which is the name defined by the rule)
+and a colon.  A vertical bar (\verb\|\) is used to separate
+alternatives; it is the least binding operator in this notation.  A
+star (\verb\*\) means zero or more repetitions of the preceding item;
+likewise, a plus (\verb\+\) means one or more repetitions, and a
+phrase enclosed in square brackets (\verb\[ ]\) means zero or one
+occurrences (in other words, the enclosed phrase is optional).  The
+\verb\*\ and \verb\+\ operators bind as tightly as possible;
+parentheses are used for grouping.  Literal strings are enclosed in
+double quotes.  White space is only meaningful to separate tokens.
+Rules are normally contained on a single line; rules with many
+alternatives may be formatted alternatively with each line after the
+first beginning with a vertical bar.
+
+In lexical definitions (as the example above), two more conventions
+are used: Two literal characters separated by three dots mean a choice
+of any single character in the given (inclusive) range of ASCII
+characters.  A phrase between angular brackets (\verb\<...>\) gives an
+informal description of the symbol defined; e.g. this could be used
+to describe the notion of `control character' if needed.
+\index{lexical definitions}
+\index{ASCII}
+
+Even though the notation used is almost the same, there is a big
+difference between the meaning of lexical and syntactic definitions:
+a lexical definition operates on the individual characters of the
+input source, while a syntax definition operates on the stream of
+tokens generated by the lexical analysis.  All uses of BNF in the next
+chapter (``Lexical Analysis'') are lexical definitions; uses in
+subsequent chapters are syntactic definitions.

Doc/ref/ref4.tex

+\chapter{Execution model}
+\index{execution model}
+
+\section{Code blocks, execution frames, and name spaces} \label{execframes}
+\index{code block}
+\indexii{execution}{frame}
+\index{name space}
+
+A {\em code block} is a piece of Python program text that can be
+executed as a unit, such as a module, a class definition or a function
+body.  Some code blocks (like modules) are executed only once, others
+(like function bodies) may be executed many times.  Code block may
+textually contain other code blocks.  Code blocks may invoke other
+code blocks (that may or may not be textually contained in them) as
+part of their execution, e.g. by invoking (calling) a function.
+\index{code block}
+\indexii{code}{block}
+
+The following are code blocks:  A module is a code block.  A function
+body is a code block.  A class definition is a code block.  Each
+command typed interactively is a separate code block; a script file is
+a code block.  The string argument passed to the built-in functions
+\verb\eval\ and \verb\exec\ are code blocks.  And finally, the
+expression read and evaluated by the built-in function \verb\input\ is
+a code block.
+
+A code block is executed in an execution frame.  An {\em execution
+frame} contains some administrative information (used for debugging),
+determines where and how execution continues after the code block's
+execution has completed, and (perhaps most importantly) defines two
+name spaces, the local and the global name space, that affect
+execution of the code block.
+\indexii{execution}{frame}
+
+A {\em name space} is a mapping from names (identifiers) to objects.
+A particular name space may be referenced by more than one execution
+frame, and from other places as well.  Adding a name to a name space
+is called {\em binding} a name (to an object); changing the mapping of
+a name is called {\em rebinding}; removing a name is {\em unbinding}.
+Name spaces are functionally equivalent to dictionaries.
+\index{name space}
+\indexii{binding}{name}
+\indexii{rebinding}{name}
+\indexii{unbinding}{name}
+
+The {\em local name space} of an execution frame determines the default
+place where names are defined and searched.  The {\em global name
+space} determines the place where names listed in \verb\global\
+statements are defined and searched, and where names that are not
+explicitly bound in the current code block are searched.
+\indexii{local}{name space}
+\indexii{global}{name space}
+\stindex{global}
+
+Whether a name is local or global in a code block is determined by
+static inspection of the source text for the code block: in the
+absence of \verb\global\ statements, a name that is bound anywhere in
+the code block is local in the entire code block; all other names are
+considered global.  The \verb\global\ statement forces global
+interpretation of selected names throughout the code block.  The
+following constructs bind names: formal parameters, \verb\import\
+statements, class and function definitions (these bind the class or
+function name), and targets that are identifiers if occurring in an
+assignment, \verb\for\ loop header, or \verb\except\ clause header.
+(A target occurring in a \verb\del\ statement does not bind a name.)
+
+When a global name is not found in the global name space, it is
+searched in the list of ``built-in'' names (which is actually the
+global name space of the module \verb\builtin\).  When a name is not
+found at all, the \verb\NameError\ exception is raised.
+
+The following table lists the meaning of the local and global name
+space for various types of code blocks.  The name space for a
+particular module is automatically created when the module is first
+referenced.
+
+\begin{center}
+\begin{tabular}{|l|l|l|l|}
+\hline
+Code block type & Global name space & Local name space & Notes \\
+\hline
+Module & n.s. for this module & same as global & \\
+Script & n.s. for \verb\__main__\ & same as global & \\
+Interactive command & n.s. for \verb\__main__\ & same as global & \\
+Class definition & global n.s. of containing block & new n.s. & \\
+Function body & global n.s. of containing block & new n.s. & \\
+String passed to \verb\exec\ or \verb\eval\
+	& global n.s. of caller & local n.s. of caller & (1) \\
+File read by \verb\execfile\
+	& global n.s. of caller & local n.s. of caller & (1) \\
+Expression read by \verb\input\
+	& global n.s. of caller & local n.s. of caller & \\
+\hline
+\end{tabular}
+\end{center}
+
+Notes:
+
+\begin{description}
+
+\item[n.s.] means {\em name space}
+
+\item[(1)] The global and local name space for these functions can be
+overridden with optional extra arguments.
+
+\end{description}
+
+\section{Exceptions}
+
+Exceptions are a means of breaking out of the normal flow of control
+of a code block in order to handle errors or other exceptional
+conditions.  An exception is {\em raised} at the point where the error
+is detected; it may be {\em handled} by the surrounding code block or
+by any code block that directly or indirectly invoked the code block
+where the error occurred.
+\index{exception}
+\index{raise an exception}
+\index{handle an exception}
+\index{exception handler}
+\index{errors}
+\index{error handling}
+
+The Python interpreter raises an exception when it detects an run-time
+error (such as division by zero).  A Python program can also
+explicitly raise an exception with the \verb\raise\ statement.
+Exception handlers are specified with the \verb\try...except\
+statement.
+
+Python uses the ``termination'' model of error handling: an exception
+handler can find out what happened and continue execution at an outer
+level, but it cannot repair the cause of the error and retry the
+failing operation (except by re-entering the the offending piece of
+code from the top).
+
+When an exception is not handled at all, the interpreter terminates
+execution of the program, or returns to its interactive main loop.
+
+Exceptions are identified by string objects.  Two different string
+objects with the same value identify different exceptions.
+
+When an exception is raised, an object (maybe \verb\None\) is passed
+as the exception's ``parameter''; this object does not affect the
+selection of an exception handler, but is passed to the selected
+exception handler as additional information.
+
+See also the description of the \verb\try\ and \verb\raise\
+statements.

Doc/ref1.tex

+\chapter{Introduction}
+
+This reference manual describes the Python programming language.
+It is not intended as a tutorial.
+
+While I am trying to be as precise as possible, I chose to use English
+rather than formal specifications for everything except syntax and
+lexical analysis.  This should make the document better understandable
+to the average reader, but will leave room for ambiguities.
+Consequently, if you were coming from Mars and tried to re-implement
+Python from this document alone, you might have to guess things and in
+fact you would probably end up implementing quite a different language.
+On the other hand, if you are using
+Python and wonder what the precise rules about a particular area of
+the language are, you should definitely be able to find them here.
+
+It is dangerous to add too many implementation details to a language
+reference document --- the implementation may change, and other
+implementations of the same language may work differently.  On the
+other hand, there is currently only one Python implementation, and
+its particular quirks are sometimes worth being mentioned, especially
+where the implementation imposes additional limitations.  Therefore,
+you'll find short ``implementation notes'' sprinkled throughout the
+text.
+
+Every Python implementation comes with a number of built-in and
+standard modules.  These are not documented here, but in the separate
+{\em Python Library Reference} document.  A few built-in modules are
+mentioned when they interact in a significant way with the language
+definition.
+
+\section{Notation}
+
+The descriptions of lexical analysis and syntax use a modified BNF
+grammar notation.  This uses the following style of definition:
+\index{BNF}
+\index{grammar}
+\index{syntax}
+\index{notation}
+
+\begin{verbatim}
+name:           lc_letter (lc_letter | "_")*
+lc_letter:      "a"..."z"
+\end{verbatim}
+
+The first line says that a \verb\name\ is an \verb\lc_letter\ followed by
+a sequence of zero or more \verb\lc_letter\s and underscores.  An
+\verb\lc_letter\ in turn is any of the single characters `a' through `z'.
+(This rule is actually adhered to for the names defined in lexical and
+grammar rules in this document.)
+
+Each rule begins with a name (which is the name defined by the rule)
+and a colon.  A vertical bar (\verb\|\) is used to separate
+alternatives; it is the least binding operator in this notation.  A
+star (\verb\*\) means zero or more repetitions of the preceding item;
+likewise, a plus (\verb\+\) means one or more repetitions, and a
+phrase enclosed in square brackets (\verb\[ ]\) means zero or one
+occurrences (in other words, the enclosed phrase is optional).  The
+\verb\*\ and \verb\+\ operators bind as tightly as possible;
+parentheses are used for grouping.  Literal strings are enclosed in
+double quotes.  White space is only meaningful to separate tokens.
+Rules are normally contained on a single line; rules with many
+alternatives may be formatted alternatively with each line after the
+first beginning with a vertical bar.
+
+In lexical definitions (as the example above), two more conventions
+are used: Two literal characters separated by three dots mean a choice
+of any single character in the given (inclusive) range of ASCII
+characters.  A phrase between angular brackets (\verb\<...>\) gives an
+informal description of the symbol defined; e.g. this could be used
+to describe the notion of `control character' if needed.
+\index{lexical definitions}
+\index{ASCII}
+
+Even though the notation used is almost the same, there is a big
+difference between the meaning of lexical and syntactic definitions:
+a lexical definition operates on the individual characters of the
+input source, while a syntax definition operates on the stream of
+tokens generated by the lexical analysis.  All uses of BNF in the next
+chapter (``Lexical Analysis'') are lexical definitions; uses in
+subsequent chapters are syntactic definitions.

Doc/ref4.tex

+\chapter{Execution model}
+\index{execution model}
+
+\section{Code blocks, execution frames, and name spaces} \label{execframes}
+\index{code block}
+\indexii{execution}{frame}
+\index{name space}
+
+A {\em code block} is a piece of Python program text that can be
+executed as a unit, such as a module, a class definition or a function
+body.  Some code blocks (like modules) are executed only once, others
+(like function bodies) may be executed many times.  Code block may
+textually contain other code blocks.  Code blocks may invoke other
+code blocks (that may or may not be textually contained in them) as
+part of their execution, e.g. by invoking (calling) a function.
+\index{code block}
+\indexii{code}{block}
+
+The following are code blocks:  A module is a code block.  A function
+body is a code block.  A class definition is a code block.  Each
+command typed interactively is a separate code block; a script file is
+a code block.  The string argument passed to the built-in functions
+\verb\eval\ and \verb\exec\ are code blocks.  And finally, the
+expression read and evaluated by the built-in function \verb\input\ is
+a code block.
+
+A code block is executed in an execution frame.  An {\em execution
+frame} contains some administrative information (used for debugging),
+determines where and how execution continues after the code block's
+execution has completed, and (perhaps most importantly) defines two
+name spaces, the local and the global name space, that affect
+execution of the code block.
+\indexii{execution}{frame}
+
+A {\em name space} is a mapping from names (identifiers) to objects.
+A particular name space may be referenced by more than one execution
+frame, and from other places as well.  Adding a name to a name space
+is called {\em binding} a name (to an object); changing the mapping of
+a name is called {\em rebinding}; removing a name is {\em unbinding}.
+Name spaces are functionally equivalent to dictionaries.
+\index{name space}
+\indexii{binding}{name}
+\indexii{rebinding}{name}
+\indexii{unbinding}{name}
+
+The {\em local name space} of an execution frame determines the default
+place where names are defined and searched.  The {\em global name
+space} determines the place where names listed in \verb\global\
+statements are defined and searched, and where names that are not
+explicitly bound in the current code block are searched.
+\indexii{local}{name space}
+\indexii{global}{name space}
+\stindex{global}
+
+Whether a name is local or global in a code block is determined by
+static inspection of the source text for the code block: in the
+absence of \verb\global\ statements, a name that is bound anywhere in
+the code block is local in the entire code block; all other names are
+considered global.  The \verb\global\ statement forces global
+interpretation of selected names throughout the code block.  The
+following constructs bind names: formal parameters, \verb\import\
+statements, class and function definitions (these bind the class or
+function name), and targets that are identifiers if occurring in an
+assignment, \verb\for\ loop header, or \verb\except\ clause header.
+(A target occurring in a \verb\del\ statement does not bind a name.)
+
+When a global name is not found in the global name space, it is
+searched in the list of ``built-in'' names (which is actually the
+global name space of the module \verb\builtin\).  When a name is not
+found at all, the \verb\NameError\ exception is raised.
+
+The following table lists the meaning of the local and global name
+space for various types of code blocks.  The name space for a
+particular module is automatically created when the module is first
+referenced.
+
+\begin{center}
+\begin{tabular}{|l|l|l|l|}
+\hline
+Code block type & Global name space & Local name space & Notes \\
+\hline
+Module & n.s. for this module & same as global & \\
+Script & n.s. for \verb\__main__\ & same as global & \\
+Interactive command & n.s. for \verb\__main__\ & same as global & \\
+Class definition & global n.s. of containing block & new n.s. & \\
+Function body & global n.s. of containing block & new n.s. & \\
+String passed to \verb\exec\ or \verb\eval\
+	& global n.s. of caller & local n.s. of caller & (1) \\
+File read by \verb\execfile\
+	& global n.s. of caller & local n.s. of caller & (1) \\
+Expression read by \verb\input\
+	& global n.s. of caller & local n.s. of caller & \\
+\hline
+\end{tabular}
+\end{center}
+
+Notes:
+
+\begin{description}
+
+\item[n.s.] means {\em name space}
+
+\item[(1)] The global and local name space for these functions can be
+overridden with optional extra arguments.
+
+\end{description}
+
+\section{Exceptions}
+
+Exceptions are a means of breaking out of the normal flow of control
+of a code block in order to handle errors or other exceptional
+conditions.  An exception is {\em raised} at the point where the error
+is detected; it may be {\em handled} by the surrounding code block or
+by any code block that directly or indirectly invoked the code block
+where the error occurred.
+\index{exception}
+\index{raise an exception}
+\index{handle an exception}
+\index{exception handler}
+\index{errors}
+\index{error handling}
+
+The Python interpreter raises an exception when it detects an run-time
+error (such as division by zero).  A Python program can also
+explicitly raise an exception with the \verb\raise\ statement.
+Exception handlers are specified with the \verb\try...except\
+statement.
+
+Python uses the ``termination'' model of error handling: an exception
+handler can find out what happened and continue execution at an outer
+level, but it cannot repair the cause of the error and retry the
+failing operation (except by re-entering the the offending piece of
+code from the top).
+
+When an exception is not handled at all, the interpreter terminates
+execution of the program, or returns to its interactive main loop.
+
+Exceptions are identified by string objects.  Two different string
+objects with the same value identify different exceptions.
+
+When an exception is raised, an object (maybe \verb\None\) is passed
+as the exception's ``parameter''; this object does not affect the
+selection of an exception handler, but is passed to the selected
+exception handler as additional information.
+
+See also the description of the \verb\try\ and \verb\raise\
+statements.