diff options
Diffstat (limited to 'Doc/ref/ref5.tex')
| -rw-r--r-- | Doc/ref/ref5.tex | 1325 |
1 files changed, 0 insertions, 1325 deletions
diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex deleted file mode 100644 index 73015aa5ca..0000000000 --- a/Doc/ref/ref5.tex +++ /dev/null @@ -1,1325 +0,0 @@ -\chapter{Expressions\label{expressions}} -\index{expression} - -This chapter explains the meaning of the elements of expressions in -Python. - -\strong{Syntax Notes:} In this and the following chapters, extended -BNF\index{BNF} notation will be used to describe syntax, not lexical -analysis. When (one alternative of) a syntax rule has the form - -\begin{productionlist}[*] - \production{name}{\token{othername}} -\end{productionlist} - -and no semantics are given, the semantics of this form of \code{name} -are the same as for \code{othername}. -\index{syntax} - - -\section{Arithmetic conversions\label{conversions}} -\indexii{arithmetic}{conversion} - -When a description of an arithmetic operator below uses the phrase -``the numeric arguments are converted to a common type,'' the -arguments are coerced using the coercion rules listed at -~\ref{coercion-rules}. If both arguments are standard numeric types, -the following coercions are applied: - -\begin{itemize} -\item If either argument is a complex number, the other is converted - to complex; -\item otherwise, if either argument is a floating point number, - the other is converted to floating point; -\item otherwise, if either argument is a long integer, - the other is converted to long integer; -\item otherwise, both must be plain integers and no conversion - is necessary. -\end{itemize} - -Some additional rules apply for certain operators (e.g., a string left -argument to the `\%' operator). Extensions can define their own -coercions. - - -\section{Atoms\label{atoms}} -\index{atom} - -Atoms are the most basic elements of expressions. The simplest atoms -are identifiers or literals. Forms enclosed in -reverse quotes or in parentheses, brackets or braces are also -categorized syntactically as atoms. The syntax for atoms is: - -\begin{productionlist} - \production{atom} - {\token{identifier} | \token{literal} | \token{enclosure}} - \production{enclosure} - {\token{parenth_form} | \token{list_display}} - \productioncont{| \token{generator_expression} | \token{dict_display}} - \productioncont{| \token{string_conversion} | \token{yield_atom}} -\end{productionlist} - - -\subsection{Identifiers (Names)\label{atom-identifiers}} -\index{name} -\index{identifier} - -An identifier occurring as an atom is a name. See -section \ref{identifiers} for lexical definition and -section~\ref{naming} for documentation of naming and binding. - -When the name is bound to an object, evaluation of the atom yields -that object. When a name is not bound, an attempt to evaluate it -raises a \exception{NameError} exception. -\exindex{NameError} - -\strong{Private name mangling:} -\indexii{name}{mangling}% -\indexii{private}{names}% -When an identifier that textually occurs in a class definition begins -with two or more underscore characters and does not end in two or more -underscores, it is considered a \dfn{private name} of that class. -Private names are transformed to a longer form before code is -generated for them. The transformation inserts the class name in -front of the name, with leading underscores removed, and a single -underscore inserted in front of the class name. For example, the -identifier \code{__spam} occurring in a class named \code{Ham} will be -transformed to \code{_Ham__spam}. This transformation is independent -of the syntactical context in which the identifier is used. If the -transformed name is extremely long (longer than 255 characters), -implementation defined truncation may happen. If the class name -consists only of underscores, no transformation is done. - - -\subsection{Literals\label{atom-literals}} -\index{literal} - -Python supports string literals and various numeric literals: - -\begin{productionlist} - \production{literal} - {\token{stringliteral} | \token{integer} | \token{longinteger}} - \productioncont{| \token{floatnumber} | \token{imagnumber}} -\end{productionlist} - -Evaluation of a literal yields an object of the given type (string, -integer, long integer, floating point number, complex number) with the -given value. The value may be approximated in the case of floating -point and imaginary (complex) literals. See section \ref{literals} -for details. - -All literals correspond to immutable data types, and hence the -object's identity is less important than its value. Multiple -evaluations of literals with the same value (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. -\indexiii{immutable}{data}{type} -\indexii{immutable}{object} - - -\subsection{Parenthesized forms\label{parenthesized}} -\index{parenthesized form} - -A parenthesized form is an optional expression list enclosed in -parentheses: - -\begin{productionlist} - \production{parenth_form} - {"(" [\token{expression_list}] ")"} -\end{productionlist} - -A parenthesized expression list yields whatever that expression list -yields: if the list contains at least one comma, it yields a tuple; -otherwise, it yields the single expression that makes up the -expression list. - -An empty pair of parentheses yields an empty tuple object. Since -tuples are immutable, the rules for literals apply (i.e., two -occurrences of the empty tuple may or may not yield the same object). -\indexii{empty}{tuple} - -Note that tuples are not formed by the parentheses, but rather by use -of the comma operator. The exception is the empty tuple, for which -parentheses \emph{are} required --- allowing unparenthesized ``nothing'' -in expressions would cause ambiguities and allow common typos to -pass uncaught. -\index{comma} -\indexii{tuple}{display} - - -\subsection{List displays\label{lists}} -\indexii{list}{display} -\indexii{list}{comprehensions} - -A list display is a possibly empty series of expressions enclosed in -square brackets: - -\begin{productionlist} - \production{list_display} - {"[" [\token{expression_list} | \token{list_comprehension}] "]"} - \production{list_comprehension} - {\token{expression} \token{list_for}} - \production{list_for} - {"for" \token{target_list} "in" \token{old_expression_list} - [\token{list_iter}]} - \production{old_expression_list} - {\token{old_expression} - [("," \token{old_expression})+ [","]]} - \production{list_iter} - {\token{list_for} | \token{list_if}} - \production{list_if} - {"if" \token{old_expression} [\token{list_iter}]} -\end{productionlist} - -A list display yields a new list object. Its contents are specified -by providing either a list of expressions or a list comprehension. -\indexii{list}{comprehensions} -When a comma-separated list of expressions is supplied, its elements are -evaluated from left to right and placed into the list object in that -order. When a list comprehension is supplied, it consists of a -single expression followed by at least one \keyword{for} clause and zero or -more \keyword{for} or \keyword{if} clauses. In this -case, the elements of the new list are those that would be produced -by considering each of the \keyword{for} or \keyword{if} clauses a block, -nesting from -left to right, and evaluating the expression to produce a list element -each time the innermost block is reached\footnote{In Python 2.3, a -list comprehension "leaks" the control variables of each -\samp{for} it contains into the containing scope. However, this -behavior is deprecated, and relying on it will not work once this -bug is fixed in a future release}. -\obindex{list} -\indexii{empty}{list} - - -\subsection{Generator expressions\label{genexpr}} -\indexii{generator}{expression} - -A generator expression is a compact generator notation in parentheses: - -\begin{productionlist} - \production{generator_expression} - {"(" \token{expression} \token{genexpr_for} ")"} - \production{genexpr_for} - {"for" \token{target_list} "in" \token{or_test} - [\token{genexpr_iter}]} - \production{genexpr_iter} - {\token{genexpr_for} | \token{genexpr_if}} - \production{genexpr_if} - {"if" \token{old_expression} [\token{genexpr_iter}]} -\end{productionlist} - -A generator expression yields a new generator object. -\obindex{generator} -It consists of a single expression followed by at least one -\keyword{for} clause and zero or more \keyword{for} or \keyword{if} -clauses. The iterating values of the new generator are those that -would be produced by considering each of the \keyword{for} or -\keyword{if} clauses a block, nesting from left to right, and -evaluating the expression to yield a value that is reached the -innermost block for each iteration. - -Variables used in the generator expression are evaluated lazily -when the \method{next()} method is called for generator object -(in the same fashion as normal generators). However, the leftmost -\keyword{for} clause is immediately evaluated so that error produced -by it can be seen before any other possible error in the code that -handles the generator expression. -Subsequent \keyword{for} clauses cannot be evaluated immediately since -they may depend on the previous \keyword{for} loop. -For example: \samp{(x*y for x in range(10) for y in bar(x))}. - -The parentheses can be omitted on calls with only one argument. -See section \ref{calls} for the detail. - - -\subsection{Dictionary displays\label{dict}} -\indexii{dictionary}{display} - -A dictionary display is a possibly empty series of key/datum pairs -enclosed in curly braces: -\index{key} -\index{datum} -\index{key/datum pair} - -\begin{productionlist} - \production{dict_display} - {"\{" [\token{key_datum_list}] "\}"} - \production{key_datum_list} - {\token{key_datum} ("," \token{key_datum})* [","]} - \production{key_datum} - {\token{expression} ":" \token{expression}} -\end{productionlist} - -A dictionary display yields a new dictionary object. -\obindex{dictionary} - -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. - -Restrictions on the types of the key values are listed earlier in -section \ref{types}. (To summarize, the key type should be hashable, -which excludes all mutable objects.) Clashes between duplicate keys -are not detected; the last datum (textually rightmost in the display) -stored for a given key value prevails. -\indexii{immutable}{object} - - -\subsection{String conversions\label{string-conversions}} -\indexii{string}{conversion} -\indexii{reverse}{quotes} -\indexii{backward}{quotes} -\index{back-quotes} - -A string conversion is an expression list enclosed in reverse (a.k.a. -backward) quotes: - -\begin{productionlist} - \production{string_conversion} - {"`" \token{expression_list} "`"} -\end{productionlist} - -A string conversion evaluates the contained expression list and -converts the resulting object into a string according to rules -specific to its type. - -If the object is a string, a number, \code{None}, or a tuple, list or -dictionary containing only objects whose type is one of these, the -resulting string is a valid Python expression which can be passed to -the built-in function \function{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.) - -Recursive objects (for example, lists or dictionaries that contain a -reference to themselves, directly or indirectly) use \samp{...} to -indicate a recursive reference, and the result cannot be passed to -\function{eval()} to get an equal value (\exception{SyntaxError} will -be raised instead). -\obindex{recursive} - -The built-in function \function{repr()} performs exactly the same -conversion in its argument as enclosing it in parentheses and reverse -quotes does. The built-in function \function{str()} performs a -similar but more user-friendly conversion. -\bifuncindex{repr} -\bifuncindex{str} - - -\subsection{Yield expressions\label{yieldexpr}} -\kwindex{yield} -\indexii{yield}{expression} -\indexii{generator}{function} - -\begin{productionlist} - \production{yield_atom} - {"(" \token{yield_expression} ")"} - \production{yield_expression} - {"yield" [\token{expression_list}]} -\end{productionlist} - -\versionadded{2.5} - -The \keyword{yield} expression is only used when defining a generator -function, and can only be used in the body of a function definition. -Using a \keyword{yield} expression in a function definition is -sufficient to cause that definition to create a generator function -instead of a normal function. - -When a generator function is called, it returns an iterator known as a -generator. That generator then controls the execution of a generator -function. The execution starts when one of the generator's methods is -called. At that time, the execution proceeds to the first -\keyword{yield} expression, where it is suspended again, returning the -value of \grammartoken{expression_list} to generator's caller. By -suspended we mean that all local state is retained, including the -current bindings of local variables, the instruction pointer, and the -internal evaluation stack. When the execution is resumed by calling -one of the generator's methods, the function can proceed exactly as -if the \keyword{yield} expression was just another external call. -The value of the \keyword{yield} expression after resuming depends on -the method which resumed the execution. - -\index{coroutine} - -All of this makes generator functions quite similar to coroutines; they -yield multiple times, they have more than one entry point and their -execution can be suspended. The only difference is that a generator -function cannot control where should the execution continue after it -yields; the control is always transfered to the generator's caller. - -\obindex{generator} - -The following generator's methods can be used to control the execution -of a generator function: - -\exindex{StopIteration} - -\begin{methoddesc}[generator]{next}{} - Starts the execution of a generator function or resumes it at the - last executed \keyword{yield} expression. When a generator function - is resumed with a \method{next()} method, the current \keyword{yield} - expression always evaluates to \constant{None}. The execution then - continues to the next \keyword{yield} expression, where the generator - is suspended again, and the value of the - \grammartoken{expression_list} is returned to \method{next()}'s - caller. If the generator exits without yielding another value, a - \exception{StopIteration} exception is raised. -\end{methoddesc} - -\begin{methoddesc}[generator]{send}{value} - Resumes the execution and ``sends'' a value into the generator - function. The \code{value} argument becomes the result of the - current \keyword{yield} expression. The \method{send()} method - returns the next value yielded by the generator, or raises - \exception{StopIteration} if the generator exits without yielding - another value. - When \method{send()} is called to start the generator, it must be - called with \constant{None} as the argument, because there is no - \keyword{yield} expression that could receieve the value. -\end{methoddesc} - -\begin{methoddesc}[generator]{throw} - {type\optional{, value\optional{, traceback}}} - Raises an exception of type \code{type} at the point where generator - was paused, and returns the next value yielded by the generator - function. If the generator exits without yielding another value, a - \exception{StopIteration} exception is raised. If the generator - function does not catch the passed-in exception, or raises a - different exception, then that exception propagates to the caller. -\end{methoddesc} - -\exindex{GeneratorExit} - -\begin{methoddesc}[generator]{close}{} - Raises a \exception{GeneratorExit} at the point where the generator - function was paused. If the generator function then raises - \exception{StopIteration} (by exiting normally, or due to already - being closed) or \exception{GeneratorExit} (by not catching the - exception), close returns to its caller. If the generator yields a - value, a \exception{RuntimeError} is raised. If the generator raises - any other exception, it is propagated to the caller. \method{close} - does nothing if the generator has already exited due to an exception - or normal exit. -\end{methoddesc} - -Here is a simple example that demonstrates the behavior of generators -and generator functions: - -\begin{verbatim} ->>> def echo(value=None): -... print "Execution starts when 'next()' is called for the first time." -... try: -... while True: -... try: -... value = (yield value) -... except GeneratorExit: -... # never catch GeneratorExit -... raise -... except Exception, e: -... value = e -... finally: -... print "Don't forget to clean up when 'close()' is called." -... ->>> generator = echo(1) ->>> print generator.next() -Execution starts when 'next()' is called for the first time. -1 ->>> print generator.next() -None ->>> print generator.send(2) -2 ->>> generator.throw(TypeError, "spam") -TypeError('spam',) ->>> generator.close() -Don't forget to clean up when 'close()' is called. -\end{verbatim} - -\begin{seealso} - \seepep{0342}{Coroutines via Enhanced Generators} - {The proposal to enhance the API and syntax of generators, - making them usable as simple coroutines.} -\end{seealso} - - -\section{Primaries\label{primaries}} -\index{primary} - -Primaries represent the most tightly bound operations of the language. -Their syntax is: - -\begin{productionlist} - \production{primary} - {\token{atom} | \token{attributeref} - | \token{subscription} | \token{slicing} | \token{call}} -\end{productionlist} - - -\subsection{Attribute references\label{attribute-references}} -\indexii{attribute}{reference} - -An attribute reference is a primary followed by a period and a name: - -\begin{productionlist} - \production{attributeref} - {\token{primary} "." \token{identifier}} -\end{productionlist} - -The primary must evaluate to an object of a type that supports -attribute references, e.g., a module, list, or an instance. This -object is then asked to produce the attribute whose name is the -identifier. If this attribute is not available, the exception -\exception{AttributeError}\exindex{AttributeError} is raised. -Otherwise, the type and value of the object produced is determined by -the object. Multiple evaluations of the same attribute reference may -yield different objects. -\obindex{module} -\obindex{list} - - -\subsection{Subscriptions\label{subscriptions}} -\index{subscription} - -A subscription selects an item of a sequence (string, tuple or list) -or mapping (dictionary) object: -\obindex{sequence} -\obindex{mapping} -\obindex{string} -\obindex{tuple} -\obindex{list} -\obindex{dictionary} -\indexii{sequence}{item} - -\begin{productionlist} - \production{subscription} - {\token{primary} "[" \token{expression_list} "]"} -\end{productionlist} - -The primary must evaluate to an object of a sequence or mapping type. - -If the primary is a mapping, the expression list must evaluate to an -object whose value is one of the keys of the mapping, and the -subscription selects the value in the mapping that corresponds to that -key. (The expression list is a tuple except if it has exactly one -item.) - -If the primary is a sequence, the expression (list) must evaluate to a -plain integer. If this value is negative, the length of the sequence -is added to it (so that, e.g., \code{x[-1]} selects the last item of -\code{x}.) The resulting value must be a nonnegative integer less -than the number of items in the sequence, and the subscription selects -the item whose index is that value (counting from zero). - -A string's items are characters. A character is not a separate data -type but a string of exactly one character. -\index{character} -\indexii{string}{item} - - -\subsection{Slicings\label{slicings}} -\index{slicing} -\index{slice} - -A slicing selects a range of items in a sequence object (e.g., a -string, tuple or list). Slicings may be used as expressions or as -targets in assignment or \keyword{del} statements. The syntax for a -slicing: -\obindex{sequence} -\obindex{string} -\obindex{tuple} -\obindex{list} - -\begin{productionlist} - \production{slicing} - {\token{simple_slicing} | \token{extended_slicing}} - \production{simple_slicing} - {\token{primary} "[" \token{short_slice} "]"} - \production{extended_slicing} - {\token{primary} "[" \token{slice_list} "]" } - \production{slice_list} - {\token{slice_item} ("," \token{slice_item})* [","]} - \production{slice_item} - {\token{expression} | \token{proper_slice} | \token{ellipsis}} - \production{proper_slice} - {\token{short_slice} | \token{long_slice}} - \production{short_slice} - {[\token{lower_bound}] ":" [\token{upper_bound}]} - \production{long_slice} - {\token{short_slice} ":" [\token{stride}]} - \production{lower_bound} - {\token{expression}} - \production{upper_bound} - {\token{expression}} - \production{stride} - {\token{expression}} - \production{ellipsis} - {"..."} -\end{productionlist} - -There is ambiguity in the formal syntax here: anything that looks like -an expression list also looks like a slice list, so any subscription -can be interpreted as a slicing. Rather than further complicating the -syntax, this is disambiguated by defining that in this case the -interpretation as a subscription takes priority over the -interpretation as a slicing (this is the case if the slice list -contains no proper slice nor ellipses). Similarly, when the slice -list has exactly one short slice and no trailing comma, the -interpretation as a simple slicing takes priority over that as an -extended slicing.\indexii{extended}{slicing} - -The semantics for a simple slicing are as follows. The primary must -evaluate to a sequence object. The lower and upper bound expressions, -if present, must evaluate to plain integers; defaults are zero and the -\code{sys.maxint}, respectively. If either bound is negative, the -sequence's length is added to it. The slicing now selects all items -with index \var{k} such that -\code{\var{i} <= \var{k} < \var{j}} where \var{i} -and \var{j} are the specified lower and upper bounds. This may be an -empty sequence. It is not an error if \var{i} or \var{j} lie outside the -range of valid indexes (such items don't exist so they aren't -selected). - -The semantics for an extended slicing are as follows. The primary -must evaluate to a mapping object, and it is indexed with a key that -is constructed from the slice list, as follows. If the slice list -contains at least one comma, the key is a tuple containing the -conversion of the slice items; otherwise, the conversion of the lone -slice item is the key. The conversion of a slice item that is an -expression is that expression. The conversion of an ellipsis slice -item is the built-in \code{Ellipsis} object. The conversion of a -proper slice is a slice object (see section \ref{types}) whose -\member{start}, \member{stop} and \member{step} attributes are the -values of the expressions given as lower bound, upper bound and -stride, respectively, substituting \code{None} for missing -expressions. -\withsubitem{(slice object attribute)}{\ttindex{start} - \ttindex{stop}\ttindex{step}} - - -\subsection{Calls\label{calls}} -\index{call} - -A call calls a callable object (e.g., a function) with a possibly empty -series of arguments: -\obindex{callable} - -\begin{productionlist} - \production{call} - {\token{primary} "(" [\token{argument_list} [","]} - \productioncont{ | \token{expression} \token{genexpr_for}] ")"} - \production{argument_list} - {\token{positional_arguments} ["," \token{keyword_arguments}]} - \productioncont{ ["," "*" \token{expression}]} - \productioncont{ ["," "**" \token{expression}]} - \productioncont{| \token{keyword_arguments} ["," "*" \token{expression}]} - \productioncont{ ["," "**" \token{expression}]} - \productioncont{| "*" \token{expression} ["," "**" \token{expression}]} - \productioncont{| "**" \token{expression}} - \production{positional_arguments} - {\token{expression} ("," \token{expression})*} - \production{keyword_arguments} - {\token{keyword_item} ("," \token{keyword_item})*} - \production{keyword_item} - {\token{identifier} "=" \token{expression}} -\end{productionlist} - -A trailing comma may be present after the positional and keyword -arguments but does not affect the semantics. - -The primary must evaluate to a callable object (user-defined -functions, built-in functions, methods of built-in objects, class -objects, methods of class instances, and certain class instances -themselves are callable; extensions may define additional callable -object types). All argument expressions are evaluated before the call -is attempted. Please refer to section \ref{function} for the syntax -of formal parameter lists. - -If keyword arguments are present, they are first converted to -positional arguments, as follows. First, a list of unfilled slots is -created for the formal parameters. If there are N positional -arguments, they are placed in the first N slots. Next, for each -keyword argument, the identifier is used to determine the -corresponding slot (if the identifier is the same as the first formal -parameter name, the first slot is used, and so on). If the slot is -already filled, a \exception{TypeError} exception is raised. -Otherwise, the value of the argument is placed in the slot, filling it -(even if the expression is \code{None}, it fills the slot). When all -arguments have been processed, the slots that are still unfilled are -filled with the corresponding default value from the function -definition. (Default values are calculated, once, when the function -is defined; thus, a mutable object such as a list or dictionary used -as default value will be shared by all calls that don't specify an -argument value for the corresponding slot; this should usually be -avoided.) If there are any unfilled slots for which no default value -is specified, a \exception{TypeError} exception is raised. Otherwise, -the list of filled slots is used as the argument list for the call. - -If there are more positional arguments than there are formal parameter -slots, a \exception{TypeError} exception is raised, unless a formal -parameter using the syntax \samp{*identifier} is present; in this -case, that formal parameter receives a tuple containing the excess -positional arguments (or an empty tuple if there were no excess -positional arguments). - -If any keyword argument does not correspond to a formal parameter -name, a \exception{TypeError} exception is raised, unless a formal -parameter using the syntax \samp{**identifier} is present; in this -case, that formal parameter receives a dictionary containing the -excess keyword arguments (using the keywords as keys and the argument -values as corresponding values), or a (new) empty dictionary if there -were no excess keyword arguments. - -If the syntax \samp{*expression} appears in the function call, -\samp{expression} must evaluate to a sequence. Elements from this -sequence are treated as if they were additional positional arguments; -if there are postional arguments \var{x1},...,\var{xN} , and -\samp{expression} evaluates to a sequence \var{y1},...,\var{yM}, this -is equivalent to a call with M+N positional arguments -\var{x1},...,\var{xN},\var{y1},...,\var{yM}. - -A consequence of this is that although the \samp{*expression} syntax -appears \emph{after} any keyword arguments, it is processed -\emph{before} the keyword arguments (and the -\samp{**expression} argument, if any -- see below). So: - -\begin{verbatim} ->>> def f(a, b): -... print a, b -... ->>> f(b=1, *(2,)) -2 1 ->>> f(a=1, *(2,)) -Traceback (most recent call last): - File "<stdin>", line 1, in ? -TypeError: f() got multiple values for keyword argument 'a' ->>> f(1, *(2,)) -1 2 -\end{verbatim} - -It is unusual for both keyword arguments and the -\samp{*expression} syntax to be used in the same call, so in practice -this confusion does not arise. - -If the syntax \samp{**expression} appears in the function call, -\samp{expression} must evaluate to a mapping, the -contents of which are treated as additional keyword arguments. In the -case of a keyword appearing in both \samp{expression} and as an -explicit keyword argument, a \exception{TypeError} exception is -raised. - -Formal parameters using the syntax \samp{*identifier} or -\samp{**identifier} cannot be used as positional argument slots or -as keyword argument names. Formal parameters using the syntax -\samp{(sublist)} cannot be used as keyword argument names; the -outermost sublist corresponds to a single unnamed argument slot, and -the argument value is assigned to the sublist using the usual tuple -assignment rules after all other parameter processing is done. - -A call always returns some value, possibly \code{None}, unless it -raises an exception. How this value is computed depends on the type -of the callable object. - -If it is--- - -\begin{description} - -\item[a user-defined function:] The code block for the function is -executed, passing it the argument list. The first thing the code -block will do is bind the formal parameters to the arguments; this is -described in section \ref{function}. When the code block executes a -\keyword{return} statement, this specifies the return value of the -function call. -\indexii{function}{call} -\indexiii{user-defined}{function}{call} -\obindex{user-defined function} -\obindex{function} - -\item[a built-in function or method:] The result is up to the -interpreter; see the \citetitle[../lib/built-in-funcs.html]{Python -Library Reference} for the descriptions of built-in functions and -methods. -\indexii{function}{call} -\indexii{built-in function}{call} -\indexii{method}{call} -\indexii{built-in method}{call} -\obindex{built-in method} -\obindex{built-in function} -\obindex{method} -\obindex{function} - -\item[a class object:] A new instance of that class is returned. -\obindex{class} -\indexii{class object}{call} - -\item[a class instance method:] The corresponding user-defined -function is called, with an argument list that is one longer than the -argument list of the call: the instance becomes the first argument. -\obindex{class instance} -\obindex{instance} -\indexii{class instance}{call} - -\item[a class instance:] The class must define a \method{__call__()} -method; the effect is then the same as if that method was called. -\indexii{instance}{call} -\withsubitem{(object method)}{\ttindex{__call__()}} - -\end{description} - - -\section{The power operator\label{power}} - -The power operator binds more tightly than unary operators on its -left; it binds less tightly than unary operators on its right. The -syntax is: - -\begin{productionlist} - \production{power} - {\token{primary} ["**" \token{u_expr}]} -\end{productionlist} - -Thus, in an unparenthesized sequence of power and unary operators, the -operators are evaluated from right to left (this does not constrain -the evaluation order for the operands). - -The power operator has the same semantics as the built-in -\function{pow()} function, when called with two arguments: it yields -its left argument raised to the power of its right argument. The -numeric arguments are first converted to a common type. The result -type is that of the arguments after coercion. - -With mixed operand types, the coercion rules for binary arithmetic -operators apply. For int and long int operands, the result has the -same type as the operands (after coercion) unless the second argument -is negative; in that case, all arguments are converted to float and a -float result is delivered. For example, \code{10**2} returns \code{100}, -but \code{10**-2} returns \code{0.01}. (This last feature was added in -Python 2.2. In Python 2.1 and before, if both arguments were of integer -types and the second argument was negative, an exception was raised). - -Raising \code{0.0} to a negative power results in a -\exception{ZeroDivisionError}. Raising a negative number to a -fractional power results in a \exception{ValueError}. - - -\section{Unary arithmetic operations \label{unary}} -\indexiii{unary}{arithmetic}{operation} -\indexiii{unary}{bit-wise}{operation} - -All unary arithmetic (and bit-wise) operations have the same priority: - -\begin{productionlist} - \production{u_expr} - {\token{power} | "-" \token{u_expr} - | "+" \token{u_expr} | "{\~}" \token{u_expr}} -\end{productionlist} - -The unary \code{-} (minus) operator yields the negation of its -numeric argument. -\index{negation} -\index{minus} - -The unary \code{+} (plus) operator yields its numeric argument -unchanged. -\index{plus} - -The unary \code{\~} (invert) operator yields the bit-wise inversion -of its plain or long integer argument. The bit-wise inversion of -\code{x} is defined as \code{-(x+1)}. It only applies to integral -numbers. -\index{inversion} - -In all three cases, if the argument does not have the proper type, -a \exception{TypeError} exception is raised. -\exindex{TypeError} - - -\section{Binary arithmetic operations\label{binary}} -\indexiii{binary}{arithmetic}{operation} - -The binary arithmetic operations have the conventional priority -levels. Note that some of these operations also apply to certain -non-numeric types. Apart from the power operator, there are only two -levels, one for multiplicative operators and one for additive -operators: - -\begin{productionlist} - \production{m_expr} - {\token{u_expr} | \token{m_expr} "*" \token{u_expr} - | \token{m_expr} "//" \token{u_expr} - | \token{m_expr} "/" \token{u_expr}} - \productioncont{| \token{m_expr} "\%" \token{u_expr}} - \production{a_expr} - {\token{m_expr} | \token{a_expr} "+" \token{m_expr} - | \token{a_expr} "-" \token{m_expr}} -\end{productionlist} - -The \code{*} (multiplication) operator yields the product of its -arguments. The arguments must either both be numbers, or one argument -must be an integer (plain or long) and the other must be a sequence. -In the former case, the numbers are converted to a common type and -then multiplied together. In the latter case, sequence repetition is -performed; a negative repetition factor yields an empty sequence. -\index{multiplication} - -The \code{/} (division) and \code{//} (floor division) operators yield -the quotient of their arguments. The numeric arguments are first -converted to a common type. Plain or long integer division yields an -integer of the same type; the result is that of mathematical division -with the `floor' function applied to the result. Division by zero -raises the -\exception{ZeroDivisionError} exception. -\exindex{ZeroDivisionError} -\index{division} - -The \code{\%} (modulo) operator yields the remainder from the -division of the first argument by the second. The numeric arguments -are first converted to a common type. A zero right argument raises -the \exception{ZeroDivisionError} exception. The arguments may be floating -point numbers, e.g., \code{3.14\%0.7} equals \code{0.34} (since -\code{3.14} equals \code{4*0.7 + 0.34}.) The modulo operator always -yields a result with the same sign as its second operand (or zero); -the absolute value of the result is strictly smaller than the absolute -value of the second operand\footnote{ - While \code{abs(x\%y) < abs(y)} is true mathematically, for - floats it may not be true numerically due to roundoff. For - example, and assuming a platform on which a Python float is an - IEEE 754 double-precision number, in order that \code{-1e-100 \% 1e100} - have the same sign as \code{1e100}, the computed result is - \code{-1e-100 + 1e100}, which is numerically exactly equal - to \code{1e100}. Function \function{fmod()} in the \module{math} - module returns a result whose sign matches the sign of the - first argument instead, and so returns \code{-1e-100} in this case. - Which approach is more appropriate depends on the application. -}. -\index{modulo} - -The integer division and modulo operators are connected by the -following identity: \code{x == (x/y)*y + (x\%y)}. Integer division and -modulo are also connected with the built-in function \function{divmod()}: -\code{divmod(x, y) == (x/y, x\%y)}. These identities don't hold for -floating point numbers; there similar identities hold -approximately where \code{x/y} is replaced by \code{floor(x/y)} or -\code{floor(x/y) - 1}\footnote{ - If x is very close to an exact integer multiple of y, it's - possible for \code{floor(x/y)} to be one larger than - \code{(x-x\%y)/y} due to rounding. In such cases, Python returns - the latter result, in order to preserve that \code{divmod(x,y)[0] - * y + x \%{} y} be very close to \code{x}. -}. - -In addition to performing the modulo operation on numbers, the \code{\%} -operator is also overloaded by string and unicode objects to perform -string formatting (also known as interpolation). The syntax for string -formatting is described in the -\citetitle[../lib/typesseq-strings.html]{Python Library Reference}, -section ``Sequence Types''. - -\deprecated{2.3}{The floor division operator, the modulo operator, -and the \function{divmod()} function are no longer defined for complex -numbers. Instead, convert to a floating point number using the -\function{abs()} function if appropriate.} - -The \code{+} (addition) operator yields the sum of its arguments. -The arguments must either both be numbers or both sequences of the -same type. In the former case, the numbers are converted to a common -type and then added together. In the latter case, the sequences are -concatenated. -\index{addition} - -The \code{-} (subtraction) operator yields the difference of its -arguments. The numeric arguments are first converted to a common -type. -\index{subtraction} - - -\section{Shifting operations\label{shifting}} -\indexii{shifting}{operation} - -The shifting operations have lower priority than the arithmetic -operations: - -\begin{productionlist} - \production{shift_expr} - {\token{a_expr} - | \token{shift_expr} ( "<<" | ">>" ) \token{a_expr}} -\end{productionlist} - -These operators accept plain or long integers as arguments. The -arguments are converted to a common type. They shift the first -argument to the left or right by the number of bits given by the -second argument. - -A right shift by \var{n} bits is defined as division by -\code{pow(2,\var{n})}. A left shift by \var{n} bits is defined as -multiplication with \code{pow(2,\var{n})}; for plain integers there is -no overflow check so in that case the operation drops bits and flips -the sign if the result is not less than \code{pow(2,31)} in absolute -value. Negative shift counts raise a \exception{ValueError} -exception. -\exindex{ValueError} - - -\section{Binary bit-wise operations\label{bitwise}} -\indexiii{binary}{bit-wise}{operation} - -Each of the three bitwise operations has a different priority level: - -\begin{productionlist} - \production{and_expr} - {\token{shift_expr} | \token{and_expr} "\&" \token{shift_expr}} - \production{xor_expr} - {\token{and_expr} | \token{xor_expr} "\textasciicircum" \token{and_expr}} - \production{or_expr} - {\token{xor_expr} | \token{or_expr} "|" \token{xor_expr}} -\end{productionlist} - -The \code{\&} operator yields the bitwise AND of its arguments, which -must be plain or long integers. The arguments are converted to a -common type. -\indexii{bit-wise}{and} - -The \code{\^} operator yields the bitwise XOR (exclusive OR) of its -arguments, which must be plain or long integers. The arguments are -converted to a common type. -\indexii{bit-wise}{xor} -\indexii{exclusive}{or} - -The \code{|} operator yields the bitwise (inclusive) OR of its -arguments, which must be plain or long integers. The arguments are -converted to a common type. -\indexii{bit-wise}{or} -\indexii{inclusive}{or} - - -\section{Comparisons\label{comparisons}} -\index{comparison} - -Unlike C, all comparison operations in Python have the same priority, -which is lower than that of any arithmetic, shifting or bitwise -operation. Also unlike C, expressions like \code{a < b < c} have the -interpretation that is conventional in mathematics: -\indexii{C}{language} - -\begin{productionlist} - \production{comparison} - {\token{or_expr} ( \token{comp_operator} \token{or_expr} )*} - \production{comp_operator} - {"<" | ">" | "==" | ">=" | "<=" | "<>" | "!="} - \productioncont{| "is" ["not"] | ["not"] "in"} -\end{productionlist} - -Comparisons yield boolean values: \code{True} or \code{False}. - -Comparisons can be chained arbitrarily, e.g., \code{x < y <= z} is -equivalent to \code{x < y and y <= z}, except that \code{y} is -evaluated only once (but in both cases \code{z} is not evaluated at all -when \code{x < y} is found to be false). -\indexii{chaining}{comparisons} - -Formally, if \var{a}, \var{b}, \var{c}, \ldots, \var{y}, \var{z} are -expressions and \var{opa}, \var{opb}, \ldots, \var{opy} are comparison -operators, then \var{a opa b opb c} \ldots \var{y opy z} is equivalent -to \var{a opa b} \keyword{and} \var{b opb c} \keyword{and} \ldots -\var{y opy z}, except that each expression is evaluated at most once. - -Note that \var{a opa b opb c} doesn't imply any kind of comparison -between \var{a} and \var{c}, so that, e.g., \code{x < y > z} is -perfectly legal (though perhaps not pretty). - -The forms \code{<>} and \code{!=} are equivalent; for consistency with -C, \code{!=} is preferred; where \code{!=} is mentioned below -\code{<>} is also accepted. The \code{<>} spelling is considered -obsolescent. - -The operators \code{<}, \code{>}, \code{==}, \code{>=}, \code{<=}, and -\code{!=} compare -the values of two objects. The objects need not have the same type. -If both are numbers, they are converted to a common type. Otherwise, -objects of different types \emph{always} compare unequal, and are -ordered consistently but arbitrarily. You can control comparison -behavior of objects of non-builtin types by defining a \code{__cmp__} -method or rich comparison methods like \code{__gt__}, described in -section~\ref{specialnames}. - -(This unusual definition of comparison was used to simplify the -definition of operations like sorting and the \keyword{in} and -\keyword{not in} operators. In the future, the comparison rules for -objects of different types are likely to change.) - -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 \function{ord()}) of their -characters. Unicode and 8-bit strings are fully interoperable in this -behavior. - -\item -Tuples and lists are compared lexicographically using comparison of -corresponding elements. This means that to compare equal, each -element must compare equal and the two sequences must be of the same -type and have the same length. - -If not equal, the sequences are ordered the same as their first -differing elements. For example, \code{cmp([1,2,x], [1,2,y])} returns -the same as \code{cmp(x,y)}. If the corresponding element does not -exist, the shorter sequence is ordered first (for example, -\code{[1,2] < [1,2,3]}). - -\item -Mappings (dictionaries) compare equal if and only if their sorted -(key, value) lists compare equal.\footnote{The implementation computes - this efficiently, without constructing lists or sorting.} -Outcomes other than equality are resolved consistently, but are not -otherwise defined.\footnote{Earlier versions of Python used - lexicographic comparison of the sorted (key, value) lists, but this - was very expensive for the common case of comparing for equality. An - even earlier version of Python compared dictionaries by identity only, - but this caused surprises because people expected to be able to test - a dictionary for emptiness by comparing it to \code{\{\}}.} - -\item -Most other objects of builtin types compare unequal unless they are -the same object; -the choice whether one object is considered smaller or larger than -another one is made arbitrarily but consistently within one -execution of a program. - -\end{itemize} - -The operators \keyword{in} and \keyword{not in} test for set -membership. \code{\var{x} in \var{s}} evaluates to true if \var{x} -is a member of the set \var{s}, and false otherwise. \code{\var{x} -not in \var{s}} returns the negation of \code{\var{x} in \var{s}}. -The set membership test has traditionally been bound to sequences; an -object is a member of a set if the set is a sequence and contains an -element equal to that object. However, it is possible for an object -to support membership tests without being a sequence. In particular, -dictionaries support membership testing as a nicer way of spelling -\code{\var{key} in \var{dict}}; other mapping types may follow suit. - -For the list and tuple types, \code{\var{x} in \var{y}} is true if and -only if there exists an index \var{i} such that -\code{\var{x} == \var{y}[\var{i}]} is true. - -For the Unicode and string types, \code{\var{x} in \var{y}} is true if -and only if \var{x} is a substring of \var{y}. An equivalent test is -\code{y.find(x) != -1}. Note, \var{x} and \var{y} need not be the -same type; consequently, \code{u'ab' in 'abc'} will return \code{True}. -Empty strings are always considered to be a substring of any other string, -so \code{"" in "abc"} will return \code{True}. -\versionchanged[Previously, \var{x} was required to be a string of -length \code{1}]{2.3} - -For user-defined classes which define the \method{__contains__()} method, -\code{\var{x} in \var{y}} is true if and only if -\code{\var{y}.__contains__(\var{x})} is true. - -For user-defined classes which do not define \method{__contains__()} and -do define \method{__getitem__()}, \code{\var{x} in \var{y}} is true if -and only if there is a non-negative integer index \var{i} such that -\code{\var{x} == \var{y}[\var{i}]}, and all lower integer indices -do not raise \exception{IndexError} exception. (If any other exception -is raised, it is as if \keyword{in} raised that exception). - -The operator \keyword{not in} is defined to have the inverse true value -of \keyword{in}. -\opindex{in} -\opindex{not in} -\indexii{membership}{test} -\obindex{sequence} - -The operators \keyword{is} and \keyword{is not} test for object identity: -\code{\var{x} is \var{y}} is true if and only if \var{x} and \var{y} -are the same object. \code{\var{x} is not \var{y}} yields the inverse -truth value. -\opindex{is} -\opindex{is not} -\indexii{identity}{test} - - -\section{Boolean operations\label{Booleans}} -\indexii{Conditional}{expression} -\indexii{Boolean}{operation} - -Boolean operations have the lowest priority of all Python operations: - -\begin{productionlist} - \production{expression} - {\token{conditional_expression} | \token{lambda_form}} - \production{old_expression} - {\token{or_test} | \token{old_lambda_form}} - \production{conditional_expression} - {\token{or_test} ["if" \token{or_test} "else" \token{expression}]} - \production{or_test} - {\token{and_test} | \token{or_test} "or" \token{and_test}} - \production{and_test} - {\token{not_test} | \token{and_test} "and" \token{not_test}} - \production{not_test} - {\token{comparison} | "not" \token{not_test}} -\end{productionlist} - -In the context of Boolean operations, and also when expressions are -used by control flow statements, the following values are interpreted -as false: \code{False}, \code{None}, numeric zero of all types, and empty -strings and containers (including strings, tuples, lists, dictionaries, -sets and frozensets). All other values are interpreted as true. - -The operator \keyword{not} yields \code{True} if its argument is false, -\code{False} otherwise. -\opindex{not} - -The expression \code{\var{x} if \var{C} else \var{y}} first evaluates -\var{C} (\emph{not} \var{x}); if \var{C} is true, \var{x} is evaluated and -its value is returned; otherwise, \var{y} is evaluated and its value is -returned. \versionadded{2.5} - -The expression \code{\var{x} and \var{y}} first evaluates \var{x}; if -\var{x} is false, its value is returned; otherwise, \var{y} is -evaluated and the resulting value is returned. -\opindex{and} - -The expression \code{\var{x} or \var{y}} first evaluates \var{x}; if -\var{x} is true, its value is returned; otherwise, \var{y} is -evaluated and the resulting value is returned. -\opindex{or} - -(Note that neither \keyword{and} nor \keyword{or} restrict the value -and type they return to \code{False} and \code{True}, but rather return the -last evaluated argument. -This is sometimes useful, e.g., if \code{s} is a string that should be -replaced by a default value if it is empty, the expression -\code{s or 'foo'} yields the desired value. Because \keyword{not} has to -invent a value anyway, it does not bother to return a value of the -same type as its argument, so e.g., \code{not 'foo'} yields \code{False}, -not \code{''}.) - -\section{Lambdas\label{lambdas}} -\indexii{lambda}{expression} -\indexii{lambda}{form} -\indexii{anonymous}{function} - -\begin{productionlist} - \production{lambda_form} - {"lambda" [\token{parameter_list}]: \token{expression}} - \production{old_lambda_form} - {"lambda" [\token{parameter_list}]: \token{old_expression}} -\end{productionlist} - -Lambda forms (lambda expressions) have the same syntactic position as -expressions. They are a shorthand to create anonymous functions; the -expression \code{lambda \var{arguments}: \var{expression}} -yields a function object. The unnamed object behaves like a function -object defined with - -\begin{verbatim} -def name(arguments): - return expression -\end{verbatim} - -See section \ref{function} for the syntax of parameter lists. Note -that functions created with lambda forms cannot contain statements. -\label{lambda} - -\section{Expression lists\label{exprlists}} -\indexii{expression}{list} - -\begin{productionlist} - \production{expression_list} - {\token{expression} ( "," \token{expression} )* [","]} -\end{productionlist} - -An expression list containing at least one comma yields a -tuple. The length of the tuple is the number of expressions in the -list. The expressions are evaluated from left to right. -\obindex{tuple} - -The trailing comma is required only to create a single tuple (a.k.a. a -\emph{singleton}); 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: -\code{()}.) -\indexii{trailing}{comma} - -\section{Evaluation order\label{evalorder}} -\indexii{evaluation}{order} - -Python evaluates expressions from left to right. Notice that while -evaluating an assignment, the right-hand side is evaluated before -the left-hand side. - -In the following lines, expressions will be evaluated in the -arithmetic order of their suffixes: - -\begin{verbatim} -expr1, expr2, expr3, expr4 -(expr1, expr2, expr3, expr4) -{expr1: expr2, expr3: expr4} -expr1 + expr2 * (expr3 - expr4) -func(expr1, expr2, *expr3, **expr4) -expr3, expr4 = expr1, expr2 -\end{verbatim} - -\section{Summary\label{summary}} - -The following table summarizes the operator -precedences\indexii{operator}{precedence} in Python, from lowest -precedence (least binding) to highest precedence (most binding). -Operators in the same box have the same precedence. Unless the syntax -is explicitly given, operators are binary. Operators in the same box -group left to right (except for comparisons, including tests, which all -have the same precedence and chain from left to right --- see section -\ref{comparisons} -- and exponentiation, which groups from right to left). - -\begin{tableii}{c|l}{textrm}{Operator}{Description} - \lineii{\keyword{lambda}} {Lambda expression} - \hline - \lineii{\keyword{or}} {Boolean OR} - \hline - \lineii{\keyword{and}} {Boolean AND} - \hline - \lineii{\keyword{not} \var{x}} {Boolean NOT} - \hline - \lineii{\keyword{in}, \keyword{not} \keyword{in}}{Membership tests} - \lineii{\keyword{is}, \keyword{is not}}{Identity tests} - \lineii{\code{<}, \code{<=}, \code{>}, \code{>=}, - \code{<>}, \code{!=}, \code{==}} - {Comparisons} - \hline - \lineii{\code{|}} {Bitwise OR} - \hline - \lineii{\code{\^}} {Bitwise XOR} - \hline - \lineii{\code{\&}} {Bitwise AND} - \hline - \lineii{\code{<<}, \code{>>}} {Shifts} - \hline - \lineii{\code{+}, \code{-}}{Addition and subtraction} - \hline - \lineii{\code{*}, \code{/}, \code{\%}} - {Multiplication, division, remainder} - \hline - \lineii{\code{+\var{x}}, \code{-\var{x}}} {Positive, negative} - \lineii{\code{\~\var{x}}} {Bitwise not} - \hline - \lineii{\code{**}} {Exponentiation} - \hline - \lineii{\code{\var{x}.\var{attribute}}} {Attribute reference} - \lineii{\code{\var{x}[\var{index}]}} {Subscription} - \lineii{\code{\var{x}[\var{index}:\var{index}]}} {Slicing} - \lineii{\code{\var{f}(\var{arguments}...)}} {Function call} - \hline - \lineii{\code{(\var{expressions}\ldots)}} {Binding or tuple display} - \lineii{\code{[\var{expressions}\ldots]}} {List display} - \lineii{\code{\{\var{key}:\var{datum}\ldots\}}}{Dictionary display} - \lineii{\code{`\var{expressions}\ldots`}} {String conversion} -\end{tableii} |