1148 lines
40 KiB
TeX
1148 lines
40 KiB
TeX
% Format this file with latex.
|
|
|
|
\documentstyle[myformat]{report}
|
|
|
|
\title{\bf
|
|
Python Reference Manual \\
|
|
{\em Incomplete Draft}
|
|
}
|
|
|
|
\author{
|
|
Guido van Rossum \\
|
|
Dept. CST, CWI, Kruislaan 413 \\
|
|
1098 SJ Amsterdam, The Netherlands \\
|
|
E-mail: {\tt guido@cwi.nl}
|
|
}
|
|
|
|
\begin{document}
|
|
|
|
\pagenumbering{roman}
|
|
|
|
\maketitle
|
|
|
|
\begin{abstract}
|
|
|
|
\noindent
|
|
Python is a simple, yet powerful programming language that bridges the
|
|
gap between C and shell programming, and is thus ideally suited for
|
|
``throw-away programming''
|
|
and rapid prototyping. Its syntax is put
|
|
together from constructs borrowed from a variety of other languages;
|
|
most prominent are influences from ABC, C, Modula-3 and Icon.
|
|
|
|
The Python interpreter is easily extended with new functions and data
|
|
types implemented in C. Python is also suitable as an extension
|
|
language for highly customizable C applications such as editors or
|
|
window managers.
|
|
|
|
Python is available for various operating systems, amongst which
|
|
several flavors of {\UNIX}, Amoeba, the Apple Macintosh O.S.,
|
|
and MS-DOS.
|
|
|
|
This reference manual describes the syntax and ``core semantics'' of
|
|
the language. It is terse, but exact and complete. The semantics of
|
|
non-essential built-in object types and of the built-in functions and
|
|
modules are described in the {\em Python Library Reference}. For an
|
|
informal introduction to the language, see the {\em Python Tutorial}.
|
|
|
|
\end{abstract}
|
|
|
|
\pagebreak
|
|
|
|
\tableofcontents
|
|
|
|
\pagebreak
|
|
|
|
\pagenumbering{arabic}
|
|
|
|
\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 in fact be 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 be able to find it 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
|
|
particular quirks of it are sometimes worth mentioning, especially
|
|
where it differs from the ``ideal'' specification.
|
|
|
|
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:
|
|
|
|
\begin{verbatim}
|
|
name: lcletter (lcletter | "_")*
|
|
lcletter: "a"..."z"
|
|
\end{verbatim}
|
|
|
|
The first line says that a \verb\name\ is a \verb\lcletter\ followed by
|
|
a sequence of zero or more \verb\lcletter\s and underscores. A
|
|
\verb\lcletter\ in turn is any of the single characters `a' through `z'.
|
|
(This rule is actually adhered to for the names defined in syntax and
|
|
grammar rules in this document.)
|
|
|
|
Each rule begins with a name (which is the name defined by the rule)
|
|
followed by a colon. Each rule is wholly contained on one line. 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 question mark (\verb\?\) zero or
|
|
one (in other words, the preceding item is optional). These three
|
|
operators bind as tight as possible; parentheses are used for
|
|
grouping. Literal strings are enclosed in double quotes. White space
|
|
is only meaningful to separate tokens.
|
|
|
|
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.
|
|
|
|
Although 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.
|
|
|
|
\chapter{Lexical analysis}
|
|
|
|
A Python program is read by a {\em parser}. Input to the parser is a
|
|
stream of {\em tokens}, generated by the {\em lexical analyzer}. This
|
|
chapter describes how the lexical analyzer breaks a file into tokens.
|
|
|
|
\section{Line structure}
|
|
|
|
A Python program is divided in a number of logical lines. Statements
|
|
do not straddle logical line boundaries except where explicitly
|
|
indicated by the syntax (i.e., for compound statements). To this
|
|
purpose, the end of a logical line is represented by the token
|
|
NEWLINE.
|
|
|
|
\subsection{Comments}
|
|
|
|
A comment starts with a hash character (\verb\#\) that is not part of
|
|
a string literal, and ends at the end of the physical line. Comments
|
|
are ignored by the syntax.
|
|
|
|
\subsection{Line joining}
|
|
|
|
Two or more physical lines may be joined into logical lines using
|
|
backslash characters (\verb/\/), as follows: When physical line ends
|
|
in a backslash that is not part of a string literal or comment, it is
|
|
joined with the following forming a single logical line, deleting the
|
|
backslash and the following end-of-line character.
|
|
|
|
\subsection{Blank lines}
|
|
|
|
A logical line that contains only spaces, tabs, and possibly a
|
|
comment, is ignored (i.e., no NEWLINE token is generated), except that
|
|
during interactive input of statements, an entirely blank logical line
|
|
terminates a multi-line statement.
|
|
|
|
\subsection{Indentation}
|
|
|
|
Spaces and tabs at the beginning of a logical line are used to compute
|
|
the indentation level of the line, which in turn is used to determine
|
|
the grouping of statements.
|
|
|
|
First, each tab is replaced by one to eight spaces such that the total
|
|
number of spaces up to that point is a multiple of eight. The total
|
|
number of spaces preceding the first non-blank character then
|
|
determines the line's indentation. Indentation cannot be split over
|
|
multiple physical lines using backslashes.
|
|
|
|
The indentation levels of consecutive lines are used to generate
|
|
INDENT and DEDENT tokens, using a stack, as follows.
|
|
|
|
Before the first line of the file is read, a single zero is pushed on
|
|
the stack; this will never be popped off again. The numbers pushed on
|
|
the stack will always be strictly increasing from bottom to top. At
|
|
the beginning of each logical line, the line's indentation level is
|
|
compared to the top of the stack. If it is equal, nothing happens.
|
|
If it larger, it is pushed on the stack, and one INDENT token is
|
|
generated. If it is smaller, it {\em must} be one of the numbers
|
|
occurring on the stack; all numbers on the stack that are larger are
|
|
popped off, and for each number popped off a DEDENT token is
|
|
generated. At the end of the file, a DEDENT token is generated for
|
|
each number remaining on the stack that is larger than zero.
|
|
|
|
\section{Other tokens}
|
|
|
|
Besides NEWLINE, INDENT and DEDENT, the following categories of tokens
|
|
exist: identifiers, keywords, literals, operators, and delimiters.
|
|
Spaces and tabs are not tokens, but serve to delimit tokens. Where
|
|
ambiguity exists, a token comprises the longest possible string that
|
|
forms a legal token, when read from left to right.
|
|
|
|
\section{Identifiers}
|
|
|
|
Identifiers are described by the following regular expressions:
|
|
|
|
\begin{verbatim}
|
|
identifier: (letter|"_") (letter|digit|"_")*
|
|
letter: lowercase | uppercase
|
|
lowercase: "a"..."z"
|
|
uppercase: "A"..."Z"
|
|
digit: "0"..."9"
|
|
\end{verbatim}
|
|
|
|
Identifiers are unlimited in length. Case is significant.
|
|
|
|
\section{Keywords}
|
|
|
|
The following identifiers are used as reserved words, or {\em
|
|
keywords} of the language, and may not be used as ordinary
|
|
identifiers. They must be spelled exactly as written here:
|
|
|
|
\begin{verbatim}
|
|
and del for in print
|
|
break elif from is raise
|
|
class else global not return
|
|
continue except if or try
|
|
def finally import pass while
|
|
\end{verbatim}
|
|
|
|
% # This Python program sorts and formats the above table
|
|
% import string
|
|
% l = []
|
|
% try:
|
|
% while 1:
|
|
% l = l + string.split(raw_input())
|
|
% except EOFError:
|
|
% pass
|
|
% l.sort()
|
|
% for i in range((len(l)+4)/5):
|
|
% for j in range(i, len(l), 5):
|
|
% print string.ljust(l[j], 10),
|
|
% print
|
|
|
|
\section{Literals}
|
|
|
|
\subsection{String literals}
|
|
|
|
String literals are described by the following regular expressions:
|
|
|
|
\begin{verbatim}
|
|
stringliteral: "'" stringitem* "'"
|
|
stringitem: stringchar | escapeseq
|
|
stringchar: <any ASCII character except newline or "\" or "'">
|
|
escapeseq: "'" <any ASCII character except newline>
|
|
\end{verbatim}
|
|
|
|
String literals cannot span physical line boundaries. Escape
|
|
sequences in strings are actually interpreted according to rules
|
|
simular to those used by Standard C. The recognized escape sequences
|
|
are:
|
|
|
|
\begin{center}
|
|
\begin{tabular}{|l|l|}
|
|
\hline
|
|
\verb/\\/ & Backslash (\verb/\/) \\
|
|
\verb/\'/ & Single quote (\verb/'/) \\
|
|
\verb/\a/ & ASCII Bell (BEL) \\
|
|
\verb/\b/ & ASCII Backspace (BS) \\
|
|
\verb/\E/ & ASCII Escape (ESC) \\
|
|
\verb/\f/ & ASCII Formfeed (FF) \\
|
|
\verb/\n/ & ASCII Linefeed (LF) \\
|
|
\verb/\r/ & ASCII Carriage Return (CR) \\
|
|
\verb/\t/ & ASCII Horizontal Tab (TAB) \\
|
|
\verb/\v/ & ASCII Vertical Tab (VT) \\
|
|
\verb/\/{\em ooo} & ASCII character with octal value {\em ooo} \\
|
|
\verb/\x/{em xx...} & ASCII character with hex value {\em xx...} \\
|
|
\hline
|
|
\end{tabular}
|
|
\end{center}
|
|
|
|
For compatibility with in Standard C, up to three octal digits are
|
|
accepted, but an unlimited number of hex digits is taken to be part of
|
|
the hex escape (and then the lower 8 bits of the resulting hex number
|
|
are used...).
|
|
|
|
All unrecognized escape sequences are left in the string {\em
|
|
unchanged}, i.e., the backslash is left in the string. (This rule is
|
|
useful when debugging: if an escape sequence is mistyped, the
|
|
resulting output is more easily recognized as broken. It also helps a
|
|
great deal for string literals used as regular expressions or
|
|
otherwise passed to other modules that do their own escape handling --
|
|
but you may end up quadrupling backslashes that must appear literally.)
|
|
|
|
\subsection{Numeric literals}
|
|
|
|
There are three types of numeric literals: integers, long integers,
|
|
and floating point numbers.
|
|
|
|
Integers and long integers are described by the following regular expressions:
|
|
|
|
\begin{verbatim}
|
|
longinteger: integer ("l"|"L")
|
|
integer: decimalinteger | octinteger | hexinteger
|
|
decimalinteger: nonzerodigit digit* | "0"
|
|
octinteger: "0" octdigit+
|
|
hexinteger: "0" ("x"|"X") hexdigit+
|
|
|
|
nonzerodigit: "1"..."9"
|
|
octdigit: "0"..."7"
|
|
hexdigit: digit|"a"..."f"|"A"..."F"
|
|
\end{verbatim}
|
|
|
|
Floating point numbers are described by the following regular expressions:
|
|
|
|
\begin{verbatim}
|
|
floatnumber: [intpart] fraction [exponent] | intpart ["."] exponent
|
|
intpart: digit+
|
|
fraction: "." digit+
|
|
exponent: ("e"|"E") ["+"|"-"] digit+
|
|
\end{verbatim}
|
|
|
|
\section{Operators}
|
|
|
|
The following tokens are operators:
|
|
|
|
\begin{verbatim}
|
|
+ - * / %
|
|
<< >> & | ^ ~
|
|
< == > <= <> != >=
|
|
\end{verbatim}
|
|
|
|
The comparison operators \verb\<>\ and \verb\!=\ are alternate
|
|
spellings of the same operator.
|
|
|
|
\section{Delimiters}
|
|
|
|
The following tokens serve as delimiters or otherwise have a special
|
|
meaning:
|
|
|
|
\begin{verbatim}
|
|
( ) [ ] { }
|
|
; , : . ` =
|
|
\end{verbatim}
|
|
|
|
The following printing ASCII characters are currently not used;
|
|
their occurrence is an unconditional error:
|
|
|
|
\begin{verbatim}
|
|
! @ $ " ?
|
|
\end{verbatim}
|
|
|
|
\chapter{Execution model}
|
|
|
|
(XXX This chapter should explain the general model of the execution of
|
|
Python code and the evaluation of expressions. It should introduce
|
|
objects, values, code blocks, scopes, name spaces, name binding,
|
|
types, sequences, numbers, mappings, exceptions, and other technical
|
|
terms needed to make the following chapters concise and exact.)
|
|
|
|
\section{Objects, values and types}
|
|
|
|
I won't try to define rigorously here what an object is, but I'll give
|
|
some properties of objects that are important to know about.
|
|
|
|
Every object has an identity, a type and a value. An object's {\em
|
|
identity} never changes once it has been created; think of it as the
|
|
object's (permanent) address. An object's {\em type} determines the
|
|
operations that an object supports (e.g., can its length be taken?)
|
|
and also defines the ``meaning'' of the object's value; it also never
|
|
changes. The {\em value} of some objects can change; whether an
|
|
object's value can change is a property of its type.
|
|
|
|
Objects are never explicitly destroyed; however, when they become
|
|
unreachable they may be garbage-collected. An implementation,
|
|
however, is allowed to delay garbage collection or omit it altogether
|
|
-- it is a matter of implementation quality how garbage collection is
|
|
implemented. (Implementation note: the current implementation uses a
|
|
reference-counting scheme which collects most objects as soon as they
|
|
become onreachable, but does not detect garbage containing circular
|
|
references.)
|
|
|
|
(Some objects contain references to ``external'' resources such as
|
|
open files. It is understood that these resources are freed when the
|
|
object is garbage-collected, but since garbage collection is not
|
|
guaranteed such objects also provide an explicit way to release the
|
|
external resource (e.g., a \verb\close\ method) and programs are
|
|
recommended to use this.)
|
|
|
|
Some objects contain references to other objects. These references
|
|
are part of the object's value; in most cases, when such a
|
|
``container'' object is compared to another (of the same type), the
|
|
comparison takes the {\em values} of the referenced objects into
|
|
account (not their identities).
|
|
|
|
Except for their identity, types affect almost any aspect of objects.
|
|
Even object identities are affected in some sense: for immutable
|
|
types, operations that compute new values may actually return a
|
|
reference to an existing object with the same type and value, while
|
|
for mutable objects this is not allowed. E.g., after
|
|
|
|
\begin{verbatim}
|
|
a = 1; b = 1; c = []; d = []
|
|
\end{verbatim}
|
|
|
|
\verb\a\ and \verb\b\ may or may not refer to the same object, but
|
|
\verb\c\ and \verb\d\ are guaranteed to refer to two different, unique,
|
|
newly created lists.
|
|
|
|
\section{Execution frames, name spaces, and scopes}
|
|
|
|
XXX
|
|
|
|
\chapter{Expressions and conditions}
|
|
|
|
From now on, extended BNF notation will be used to describe syntax,
|
|
not lexical analysis.
|
|
|
|
This chapter explains the meaning of the elements of expressions and
|
|
conditions. Conditions are a superset of expressions, and a condition
|
|
may be used where an expression is required by enclosing it in
|
|
parentheses. The only place where an unparenthesized condition is not
|
|
allowed is on the right-hand side of the assignment operator, because
|
|
this operator is the same token (\verb\=\) as used for compasisons.
|
|
|
|
The comma plays a somewhat special role in Python's syntax. It is an
|
|
operator with a lower precedence than all others, but occasionally
|
|
serves other purposes as well (e.g., it has special semantics in print
|
|
statements). When a comma is accepted by the syntax, one of the
|
|
syntactic categories \verb\expression_list\ or \verb\condition_list\
|
|
is always used.
|
|
|
|
When (one alternative of) a syntax rule has the form
|
|
|
|
\begin{verbatim}
|
|
name: othername
|
|
\end{verbatim}
|
|
|
|
and no semantics are given, the semantics of this form of \verb\name\
|
|
are the same as for \verb\othername\.
|
|
|
|
\section{Arithmetic conversions}
|
|
|
|
When a description of an arithmetic operator below uses the phrase
|
|
``the numeric arguments are converted to a common type'',
|
|
this both means that if either argument is not a number, a
|
|
{\tt TypeError} exception is raised, and that otherwise
|
|
the following conversions are applied:
|
|
|
|
\begin{itemize}
|
|
\item First, if either argument is a floating point number,
|
|
the other is converted to floating point;
|
|
\item else, if either argument is a long integer,
|
|
the other is converted to long integer;
|
|
\item otherwise, both must be short integers and no conversion
|
|
is necessary.
|
|
\end{itemize}
|
|
|
|
(Note: ``short integers'' in Python are at least 32 bits in size;
|
|
``long integers'' are arbitrary precision integers.)
|
|
|
|
\section{Atoms}
|
|
|
|
Atoms are the most basic elements of expressions.
|
|
Forms enclosed in reverse quotes or various types of parentheses
|
|
or braces are also categorized syntactically as atoms.
|
|
Syntax rules for atoms:
|
|
|
|
\begin{verbatim}
|
|
atom: identifier | literal | parenth_form | string_conversion
|
|
literal: stringliteral | integer | longinteger | floatnumber
|
|
parenth_form: enclosure | list_display | dict_display
|
|
enclosure: "(" [condition_list] ")"
|
|
list_display: "[" [condition_list] "]"
|
|
dict_display: "{" [key_datum ("," key_datum)* [","] "}"
|
|
key_datum: condition ":" condition
|
|
string_conversion:"`" condition_list "`"
|
|
\end{verbatim}
|
|
|
|
\subsection{Identifiers (Names)}
|
|
|
|
An identifier occurring as an atom is a reference to a local, global
|
|
or built-in name binding. If a name can be assigned to anywhere in a code
|
|
block, it refers to a local name throughout that code block.
|
|
Otherwise, it refers to a global name if one exists, else to a
|
|
built-in name.
|
|
|
|
When the name is bound to an object, evaluation of the atom
|
|
yields that object.
|
|
When it is not bound, a {\tt NameError} exception
|
|
is raised, with the identifier as string parameter.
|
|
|
|
\subsection{Literals}
|
|
|
|
Evaluation of a literal yields an object of the given type
|
|
(string, integer, long integer, floating point number)
|
|
with the given value.
|
|
The value may be approximated in the case of floating point literals.
|
|
|
|
All literals correspond to immutable data types, and hence the object's
|
|
identity is less important than its value.
|
|
Multiple evaluations of the same literal (either the same occurrence
|
|
in the program text or a different occurrence) may
|
|
obtain the same object or a different object with the same value.
|
|
|
|
(In the original implementation, all literals in the same code block
|
|
with the same type and value yield the same object.)
|
|
|
|
\subsection{Enclosures}
|
|
|
|
An empty enclosure yields an empty tuple object.
|
|
|
|
An enclosed condition list yields whatever that condition list yields.
|
|
|
|
(Note that, except for empty tuples, tuples are not formed by
|
|
enclosure in parentheses, but rather by use of the comma operator.)
|
|
|
|
\subsection{List displays}
|
|
|
|
A list display yields a new list object.
|
|
|
|
If it has no condition list, the list object has no items.
|
|
Otherwise, the elements of the condition list are evaluated
|
|
from left to right and inserted in the list object in that order.
|
|
|
|
\subsection{Dictionary displays}
|
|
|
|
A dictionary display yields a new dictionary object.
|
|
|
|
The key/datum pairs are evaluated from left to right to
|
|
define the entries of the dictionary:
|
|
each key object is used as a key into the dictionary to store
|
|
the corresponding datum pair.
|
|
|
|
Keys must be strings, otherwise a {\tt TypeError} exception is raised.
|
|
Clashes between keys are not detected; the last datum (textually
|
|
rightmost in the display) stored for a given key value prevails.
|
|
|
|
\subsection{String conversions}
|
|
|
|
A string conversion evaluates the contained condition list and converts the
|
|
resulting object into a string according to rules specific to its type.
|
|
|
|
If the object is a string, a number, \verb\None\, or a tuple, list or
|
|
dictionary containing only objects whose type is in this list,
|
|
the resulting
|
|
string is a valid Python expression which can be passed to the
|
|
built-in function \verb\eval()\ to yield an expression with the
|
|
same value (or an approximation, if floating point numbers are
|
|
involved).
|
|
|
|
(In particular, converting a string adds quotes around it and converts
|
|
``funny'' characters to escape sequences that are safe to print.)
|
|
|
|
It is illegal to attempt to convert recursive objects (e.g.,
|
|
lists or dictionaries that -- directly or indirectly -- contain a reference
|
|
to themselves.)
|
|
|
|
\section{Primaries}
|
|
|
|
Primaries represent the most tightly bound operations of the language.
|
|
Their syntax is:
|
|
|
|
\begin{verbatim}
|
|
primary: atom | attributeref | call | subscription | slicing
|
|
attributeref: primary "." identifier
|
|
call: primary "(" [condition_list] ")"
|
|
subscription: primary "[" condition "]"
|
|
slicing: primary "[" [condition] ":" [condition] "]"
|
|
\end{verbatim}
|
|
|
|
\subsection{Attribute references}
|
|
|
|
\subsection{Calls}
|
|
|
|
\subsection{Subscriptions}
|
|
|
|
\subsection{Slicings}
|
|
|
|
\section{Factors}
|
|
|
|
Factors represent the unary numeric operators.
|
|
Their syntax is:
|
|
|
|
\begin{verbatim}
|
|
factor: primary | "-" factor | "+" factor | "~" factor
|
|
\end{verbatim}
|
|
|
|
The unary \verb\-\ operator yields the negative of its numeric argument.
|
|
|
|
The unary \verb\+\ operator yields its numeric argument unchanged.
|
|
|
|
The unary \verb\~\ operator yields the bit-wise negation of its
|
|
integral numerical argument.
|
|
|
|
In all three cases, if the argument does not have the proper type,
|
|
a {\tt TypeError} exception is raised.
|
|
|
|
\section{Terms}
|
|
|
|
Terms represent the most tightly binding binary operators:
|
|
|
|
\begin{verbatim}
|
|
term: factor | term "*" factor | term "/" factor | term "%" factor
|
|
\end{verbatim}
|
|
|
|
The \verb\*\ operator yields the product of its arguments.
|
|
The arguments must either both be numbers, or one argument must be
|
|
a (short) integer and the other must be a string.
|
|
In the former case, the numbers are converted to a common type
|
|
and then multiplied together.
|
|
In the latter case, string repetition is performed; a negative
|
|
repetition factor yields the empty string.
|
|
|
|
The \verb|"/"| operator yields the quotient of its arguments.
|
|
The numeric arguments are first converted to a common type.
|
|
(Short or long) integer division yields an integer of the same type,
|
|
truncating towards zero.
|
|
Division by zero raises a {\tt RuntimeError} exception.
|
|
|
|
The \verb|"%"| operator yields the remainder from the division
|
|
of the first argument by the second.
|
|
The numeric arguments are first converted to a common type.
|
|
The outcome of $x \% y$ is defined as $x - y*trunc(x/y)$.
|
|
A zero right argument raises a {\tt RuntimeError} exception.
|
|
The arguments may be floating point numbers, e.g.,
|
|
$3.14 \% 0.7$ equals $0.34$.
|
|
|
|
\section{Arithmetic expressions}
|
|
|
|
\begin{verbatim}
|
|
arith_expr: term | arith_expr "+" term | arith_expr "-" term
|
|
\end{verbatim}
|
|
|
|
The \verb|"+"| operator yields the sum of its arguments.
|
|
The arguments must either both be numbers, or both strings.
|
|
In the former case, the numbers are converted to a common type
|
|
and then added together.
|
|
In the latter case, the strings are concatenated directly,
|
|
without inserting a space.
|
|
|
|
The \verb|"-"| operator yields the difference of its arguments.
|
|
The numeric arguments are first converted to a common type.
|
|
|
|
\section{Shift expressions}
|
|
|
|
\begin{verbatim}
|
|
shift_expr: arith_expr | shift_expr "<<" arith_expr | shift_expr ">>" arith_expr
|
|
\end{verbatim}
|
|
|
|
These operators accept short integers as arguments only.
|
|
They shift their left argument to the left or right by the number of bits
|
|
given by the right argument. Shifts are ``logical"", e.g., bits shifted
|
|
out on one end are lost, and bits shifted in are zero;
|
|
negative numbers are shifted as if they were unsigned in C.
|
|
Negative shift counts and shift counts greater than {\em or equal to}
|
|
the word size yield undefined results.
|
|
|
|
\section{Bitwise AND expressions}
|
|
|
|
\begin{verbatim}
|
|
and_expr: shift_expr | and_expr "&" shift_expr
|
|
\end{verbatim}
|
|
|
|
This operator yields the bitwise AND of its arguments,
|
|
which must be short integers.
|
|
|
|
\section{Bitwise XOR expressions}
|
|
|
|
\begin{verbatim}
|
|
xor_expr: and_expr | xor_expr "^" and_expr
|
|
\end{verbatim}
|
|
|
|
This operator yields the bitwise exclusive OR of its arguments,
|
|
which must be short integers.
|
|
|
|
\section{Bitwise OR expressions}
|
|
|
|
\begin{verbatim}
|
|
or_expr: xor_expr | or_expr "|" xor_expr
|
|
\end{verbatim}
|
|
|
|
This operator yields the bitwise OR of its arguments,
|
|
which must be short integers.
|
|
|
|
\section{Expressions and expression lists}
|
|
|
|
\begin{verbatim}
|
|
expression: or_expression
|
|
expr_list: expression ("," expression)* [","]
|
|
\end{verbatim}
|
|
|
|
An expression list containing at least one comma yields a new tuple.
|
|
The length of the tuple is the number of expressions in the list.
|
|
The expressions are evaluated from left to right.
|
|
|
|
The trailing comma is required only to create a single tuple;
|
|
it is optional in all other cases (a single expression without
|
|
a trailing comma doesn't create a tuple, but rather yields the
|
|
value of that expression).
|
|
|
|
To create an empty tuple, use an empty pair of parentheses: \verb\()\.
|
|
|
|
\section{Comparisons}
|
|
|
|
\begin{verbatim}
|
|
comparison: expression (comp_operator expression)*
|
|
comp_operator: "<"|">"|"=="|">="|"<="|"<>"|"!="|"is" ["not"]|["not"] "in"
|
|
\end{verbatim}
|
|
|
|
Comparisons yield integer value: 1 for true, 0 for false.
|
|
|
|
Comparisons can be chained arbitrarily,
|
|
e.g., $x < y <= z$ is equivalent to
|
|
$x < y$ {\tt and} $y <= z$, except that $y$ is evaluated only once
|
|
(but in both cases $z$ is not evaluated at all when $x < y$ is
|
|
found to be false).
|
|
|
|
Formally, $e_0 op_1 e_1 op_2 e_2 ...e_{n-1} op_n e_n$ is equivalent to
|
|
$e_0 op_1 e_1$ {\tt and} $e_1 op_2 e_2$ {\tt and} ... {\tt and}
|
|
$e_{n-1} op_n e_n$, except that each expression is evaluated at most once.
|
|
|
|
Note that $e_0 op_1 e_1 op_2 e_2$ does not imply any kind of comparison
|
|
between $e_0$ and $e_2$, e.g., $x < y > z$ is perfectly legal.
|
|
|
|
The forms \verb\<>\ and \verb\!=\ are equivalent.
|
|
|
|
The operators {\tt "<", ">", "==", ">=", "<="}, and {\tt "<>"} compare
|
|
the values of two objects. The objects needn't have the same type.
|
|
If both are numbers, they are compared to a common type.
|
|
Otherwise, objects of different types {\em always} compare unequal,
|
|
and are ordered consistently but arbitrarily, except that
|
|
the value \verb\None\ compares smaller than the values of any other type.
|
|
|
|
(This unusual
|
|
definition of comparison is done to simplify the definition of
|
|
operations like sorting and the \verb\in\ and \verb\not in\ operators.)
|
|
|
|
Comparison of objects of the same type depends on the type:
|
|
|
|
\begin{itemize}
|
|
\item Numbers are compared arithmetically.
|
|
\item Strings are compared lexicographically using the numeric
|
|
equivalents (the result of the built-in function ord())
|
|
of their characters.
|
|
\item Tuples and lists are compared lexicographically
|
|
using comparison of corresponding items.
|
|
\item Dictionaries compare unequal unless they are the same object;
|
|
the choice whether one dictionary object is considered smaller
|
|
or larger than another one is made arbitrarily but
|
|
consistently within one execution of a program.
|
|
\item The latter rule is also used for most other built-in types.
|
|
\end{itemize}
|
|
|
|
The operators \verb\in\ and \verb\not in\ test for sequence membership:
|
|
if $y$ is a sequence, $x {\tt in} y$ is true if and only if there exists
|
|
an index $i$ such that $x = y_i$.
|
|
$x {\tt not in} y$ yields the inverse truth value.
|
|
The exception {\tt TypeError} is raised when $y$ is not a sequence,
|
|
or when $y$ is a string and $x$ is not a string of length one.
|
|
|
|
The operators \verb\is\ and \verb\is not\ compare object identity:
|
|
$x {\tt is} y$ is true if and only if $x$ and $y$ are the same object.
|
|
$x {\tt is not} y$ yields the inverse truth value.
|
|
|
|
\section{Boolean operators}
|
|
|
|
\begin{verbatim}
|
|
condition: or_test
|
|
or_test: and_test | or_test "or" and_test
|
|
and_test: not_test | and_test "and" not_test
|
|
not_test: comparison | "not" not_test
|
|
\end{verbatim}
|
|
|
|
In the context of Boolean operators, and also when conditions are
|
|
used by control flow statements, the following values are interpreted
|
|
as false: None, numeric zero of all types, empty sequences (strings,
|
|
tuples and lists), and empty mappings (dictionaries).
|
|
All other values are interpreted as true.
|
|
|
|
The operator \verb\not\ yields 1 if its argument is false, 0 otherwise.
|
|
|
|
The condition $x {\tt and} y$ first evaluates $x$; if $x$ is false,
|
|
$x$ is returned; otherwise, $y$ is evaluated and returned.
|
|
|
|
The condition $x {\tt or} y$ first evaluates $x$; if $x$ is true,
|
|
$x$ is returned; otherwise, $y$ is evaluated and returned.
|
|
|
|
(Note that \verb\and\ and \verb\or\ do not restrict the value and type
|
|
they return to 0 and 1, but rather return the last evaluated argument.
|
|
This is sometimes useful, e.g., if $s$ is a string, which should be
|
|
replaced by a default value if it is empty, $s {\tt or} 'foo'$
|
|
returns the desired value. Because \verb\not\ has to invent a value
|
|
anyway, it does not bother to return a value of the same type as its
|
|
argument, so \verb\not 'foo'\ yields $0$, not $''$.)
|
|
|
|
\chapter{Simple statements}
|
|
|
|
Simple statements are comprised within a single logical line.
|
|
Several simple statements may occor on a single line separated
|
|
by semicolons. The syntax for simple statements is:
|
|
|
|
\begin{verbatim}
|
|
stmt_list: simple_stmt (";" simple_stmt)* [";"]
|
|
simple_stmt: expression_stmt
|
|
| assignment
|
|
| pass_stmt
|
|
| del_stmt
|
|
| print_stmt
|
|
| return_stmt
|
|
| raise_stmt
|
|
| break_stmt
|
|
| continue_stmt
|
|
| import_stmt
|
|
| global_stmt
|
|
\end{verbatim}
|
|
|
|
\section{Expression statements}
|
|
|
|
\begin{verbatim}
|
|
expression_stmt: expression_list
|
|
\end{verbatim}
|
|
|
|
An expression statement evaluates the expression list (which may
|
|
be a single expression).
|
|
If the value is not \verb\None\, it is converted to a string
|
|
using the rules for string conversions, and the resulting string
|
|
is written to standard output on a line by itself.
|
|
|
|
(The exception for \verb\None\ is made so that procedure calls,
|
|
which are syntactically equivalent to expressions,
|
|
do not cause any output.)
|
|
|
|
\section{Assignments}
|
|
|
|
\begin{verbatim}
|
|
assignment: target_list ("=" target_list)* "=" expression_list
|
|
target_list: target ("," target)* [","]
|
|
target: identifier | "(" target_list ")" | "[" target_list "]"
|
|
| attributeref | subscription | slicing
|
|
\end{verbatim}
|
|
|
|
(See the section on primaries for the definition of the last
|
|
three symbols.)
|
|
|
|
An assignment evaluates the expression list (remember that this can
|
|
be a single expression or a comma-separated list,
|
|
the latter yielding a tuple)
|
|
and assigns the single resulting object to each of the target lists,
|
|
from left to right.
|
|
|
|
Assignment is defined recursively depending on the type of the
|
|
target. Where assignment is to part of a mutable object
|
|
(through an attribute reference, subscription or slicing),
|
|
the mutable object must ultimately perform the
|
|
assignment and decide about its validity, raising an exception
|
|
if the assignment is unacceptable. The rules observed by
|
|
various types and the exceptions raised are given with the
|
|
definition of the object types (some of which are defined
|
|
in the library reference).
|
|
|
|
Assignment of an object to a target list is recursively
|
|
defined as follows.
|
|
|
|
\begin{itemize}
|
|
\item
|
|
If the target list contains no commas (except in nested constructs):
|
|
the object is assigned to the single target contained in the list.
|
|
|
|
\item
|
|
If the target list contains commas (that are not in nested constructs):
|
|
the object must be a tuple with as many items
|
|
as the list contains targets, and the items are assigned, from left
|
|
to right, to the corresponding targets.
|
|
|
|
\end{itemize}
|
|
|
|
Assignment of an object to a (non-list)
|
|
target is recursively defined as follows.
|
|
|
|
\begin{itemize}
|
|
|
|
\item
|
|
If the target is an identifier (name):
|
|
the object is bound to that name
|
|
in the current local scope. Any previous binding of the same name
|
|
is undone.
|
|
|
|
\item
|
|
If the target is a target list enclosed in parentheses:
|
|
the object is assigned to that target list.
|
|
|
|
\item
|
|
If the target is a target list enclosed in square brackets:
|
|
the object must be a list with as many items
|
|
as the target list contains targets,
|
|
and the list's items are assigned, from left to right,
|
|
to the corresponding targets.
|
|
|
|
\item
|
|
If the target is an attribute reference:
|
|
The primary expression in the reference is evaluated.
|
|
It should yield an object with assignable attributes;
|
|
if this is not the case, a {\tt TypeError} exception is raised.
|
|
That object is then asked to assign the assigned object
|
|
to the given attribute; if it cannot perform the assignment,
|
|
it raises an exception.
|
|
|
|
\item
|
|
If the target is a subscription:
|
|
The primary expression in the reference is evaluated.
|
|
It should yield either a mutable sequence object or a mapping
|
|
(dictionary) object.
|
|
Next, the subscript expression is evaluated.
|
|
|
|
If the primary is a sequence object, the subscript must yield a
|
|
nonnegative integer smaller than the sequence's length,
|
|
and the sequence is asked to assign the assigned object
|
|
to its item with that index.
|
|
|
|
If the primary is a mapping object, the subscript must have a
|
|
type compatible with the mapping's key type,
|
|
and the mapping is then asked to to create a key/datum pair
|
|
which maps the subscript to the assigned object.
|
|
|
|
Various exceptions can be raised.
|
|
|
|
\item
|
|
If the target is a slicing:
|
|
The primary expression in the reference is evaluated.
|
|
It should yield a mutable sequence object (currently only lists).
|
|
The assigned object should be a sequence object of the same type.
|
|
Next, the lower and upper bound expressions are evaluated,
|
|
insofar they are present; defaults are zero and the sequence's length.
|
|
The bounds should evaluate to (small) integers.
|
|
If either bound is negative, the sequence's length is added to it (once).
|
|
The resulting bounds are clipped to lie between zero
|
|
and the sequence's length, inclusive.
|
|
(XXX Shouldn't this description be with expressions?)
|
|
Finally, the sequence object is asked to replace the items
|
|
indicated by the slice with the items of the assigned sequence.
|
|
This may change the sequence's length, if it allows it.
|
|
|
|
\end{itemize}
|
|
|
|
(In the original implementation, the syntax for targets is taken
|
|
to be the same as for expressions, and invalid syntax is rejected
|
|
during the code generation phase, causing less detailed error
|
|
messages.)
|
|
|
|
\section{The {\tt pass} statement}
|
|
|
|
\begin{verbatim}
|
|
pass_stmt: "pass"
|
|
\end{verbatim}
|
|
|
|
{\tt pass} is a null operation -- when it is executed,
|
|
nothing happens.
|
|
|
|
\section{The {\tt del} statement}
|
|
|
|
\begin{verbatim}
|
|
del_stmt: "del" target_list
|
|
\end{verbatim}
|
|
|
|
Deletion is recursively defined similar to assignment.
|
|
|
|
(XXX Rather that spelling it out in full details,
|
|
here are some hints.)
|
|
|
|
Deletion of a target list recursively deletes each target,
|
|
from left to right.
|
|
|
|
Deletion of a name removes the binding of that name (which must exist)
|
|
from the local scope.
|
|
|
|
Deletion of attribute references, subscriptions and slicings
|
|
is passed to the primary object involved; deletion of a slicing
|
|
is in general equivalent to assignment of an empty slice of the
|
|
right type (but even this is determined by the sliced object).
|
|
|
|
\section{The {\tt print} statement}
|
|
|
|
\begin{verbatim}
|
|
print_stmt: "print" [ condition ("," condition)* [","] ]
|
|
\end{verbatim}
|
|
|
|
{\tt print} evaluates each condition in turn and writes the resulting
|
|
object to standard output (see below).
|
|
If an object is not a string, it is first converted to
|
|
a string using the rules for string conversions.
|
|
The (resulting or original) string is then written.
|
|
A space is written before each object is (converted and) written,
|
|
unless the output system believes it is positioned at the beginning
|
|
of a line. This is the case: (1) when no characters have been written
|
|
to standard output; or (2) when the last character written to
|
|
standard output is \verb/\n/;
|
|
or (3) when the last I/O operation
|
|
on standard output was not a \verb\print\ statement.
|
|
|
|
Finally,
|
|
a \verb/\n/ character is written at the end,
|
|
unless the \verb\print\ statement ends with a comma.
|
|
This is the only action if the statement contains just the keyword
|
|
\verb\print\.
|
|
|
|
Standard output is defined as the file object named \verb\stdout\
|
|
in the built-in module \verb\sys\. If no such object exists,
|
|
or if it is not a writable file, a {\tt RuntimeError} exception is raised.
|
|
(The original implementation attempts to write to the system's original
|
|
standard output instead, but this is not safe, and should be fixed.)
|
|
|
|
\section{The {\tt return} statement}
|
|
|
|
\begin{verbatim}
|
|
return_stmt: "return" [condition_list]
|
|
\end{verbatim}
|
|
|
|
\verb\return\ may only occur syntactically nested in a function
|
|
definition, not within a nested class definition.
|
|
|
|
If a condition list is present, it is evaluated, else \verb\None\
|
|
is substituted.
|
|
|
|
\verb\return\ leaves the current function call with the condition
|
|
list (or \verb\None\) as return value.
|
|
|
|
When \verb\return\ passes control out of a \verb\try\ statement
|
|
with a \verb\finally\ clause, that finally clause is executed
|
|
before really leaving the function.
|
|
(XXX This should be made more exact, a la Modula-3.)
|
|
|
|
\section{The {\tt raise} statement}
|
|
|
|
\begin{verbatim}
|
|
raise_stmt: "raise" condition ["," condition]
|
|
\end{verbatim}
|
|
|
|
\verb\raise\ evaluates its first condition, which must yield
|
|
a string object. If there is a second condition, this is evaluated,
|
|
else \verb\None\ is substituted.
|
|
|
|
It then raises the exception identified by the first object,
|
|
with the second one (or \verb\None\) as its parameter.
|
|
|
|
\section{The {\tt break} statement}
|
|
|
|
\begin{verbatim}
|
|
break_stmt: "break"
|
|
\end{verbatim}
|
|
|
|
\verb\break\ may only occur syntactically nested in a \verb\for\
|
|
or \verb\while\ loop, not nested in a function or class definition.
|
|
|
|
It terminates the neares enclosing loop, skipping the optional
|
|
\verb\else\ clause if the loop has one.
|
|
|
|
If a \verb\for\ loop is terminated by \verb\break\, the loop control
|
|
target (list) keeps its current value.
|
|
|
|
When \verb\break\ passes control out of a \verb\try\ statement
|
|
with a \verb\finally\ clause, that finally clause is executed
|
|
before really leaving the loop.
|
|
|
|
\section{The {\tt continue} statement}
|
|
|
|
\begin{verbatim}
|
|
continue_stmt: "continue"
|
|
\end{verbatim}
|
|
|
|
\verb\continue\ may only occur syntactically nested in a \verb\for\
|
|
or \verb\while\ loop, not nested in a function or class definition,
|
|
and {\em not nested in a \verb\try\ statement with a \verb\finally\
|
|
clause}.
|
|
|
|
It continues with the next cycle of the nearest enclosing loop.
|
|
|
|
\section{The {\tt import} statement}
|
|
|
|
\begin{verbatim}
|
|
import_stmt: "import" identifier ("," identifier)*
|
|
| "from" identifier "import" identifier ("," identifier)*
|
|
| "from" identifier "import" "*"
|
|
\end{verbatim}
|
|
|
|
(XXX To be done.)
|
|
|
|
\section{The {\tt global} statement}
|
|
|
|
\begin{verbatim}
|
|
global_stmt: "global" identifier ("," identifier)*
|
|
\end{verbatim}
|
|
|
|
(XXX To be done.)
|
|
|
|
\chapter{Compound statements}
|
|
|
|
(XXX The semantic definitions of this chapter are still to be done.)
|
|
|
|
\begin{verbatim}
|
|
statement: stmt_list NEWLINE | compound_stmt
|
|
compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | funcdef | classdef
|
|
suite: statement | NEWLINE INDENT statement+ DEDENT
|
|
\end{verbatim}
|
|
|
|
\section{The {\tt if} statement}
|
|
|
|
\begin{verbatim}
|
|
if_stmt: "if" condition ":" suite
|
|
("elif" condition ":" suite)*
|
|
["else" ":" suite]
|
|
\end{verbatim}
|
|
|
|
\section{The {\tt while} statement}
|
|
|
|
\begin{verbatim}
|
|
while_stmt: "while" condition ":" suite ["else" ":" suite]
|
|
\end{verbatim}
|
|
|
|
\section{The {\tt for} statement}
|
|
|
|
\begin{verbatim}
|
|
for_stmt: "for" target_list "in" condition_list ":" suite
|
|
["else" ":" suite]
|
|
\end{verbatim}
|
|
|
|
\section{The {\tt try} statement}
|
|
|
|
\begin{verbatim}
|
|
try_stmt: "try" ":" suite
|
|
("except" condition ["," condition] ":" suite)*
|
|
["finally" ":" suite]
|
|
\end{verbatim}
|
|
|
|
\section{Function definitions}
|
|
|
|
\begin{verbatim}
|
|
funcdef: "def" identifier "(" [parameter_list] ")" ":" suite
|
|
parameter_list: parameter ("," parameter)*
|
|
parameter: identifier | "(" parameter_list ")"
|
|
\end{verbatim}
|
|
|
|
\section{Class definitions}
|
|
|
|
\begin{verbatim}
|
|
classdef: "class" identifier [inheritance] ":" suite
|
|
inheritance: "(" expression ("," expression)* ")"
|
|
\end{verbatim}
|
|
|
|
XXX Syntax for scripts, modules
|
|
XXX Syntax for interactive input, eval, exec, input
|
|
XXX New definition of expressions (as conditions)
|
|
|
|
\end{document}
|