5.2.1. Identifiers (Names)¶

An identifier occurring as an atom is a name. See sectionIdentifiers and keywordsfor lexical definition and sectionNaming and binding for documentation of naming andbinding.

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 aNameErrorexception.

Private name mangling: When an identifier that textually occurs in a classdefinition begins with two or more underscore characters and does not end in twoor more underscores, it is considered aprivate name of that class.Private names are transformed to a longer form before code is generated forthem. The transformation inserts the class name in front of the name, withleading underscores removed, and a single underscore inserted in front of theclass name. For example, the identifier__spam occurring in a class namedHam will be transformed to_Ham__spam. This transformation isindependent of the syntactical context in which the identifier is used. If thetransformed name is extremely long (longer than 255 characters), implementationdefined truncation may happen. If the class name consists only of underscores,no transformation is done.

5.2.2. Literals¶

Python supports string literals and various numeric literals:

literal ::=stringliteral |integer |longinteger             |floatnumber |imagnumber

Evaluation of a literal yields an object of the given type (string, integer,long integer, floating point number, complex number) with the given value. Thevalue may be approximated in the case of floating point and imaginary (complex)literals. See sectionLiterals for details.

All literals correspond to immutable data types, and hence the object’s identityis less important than its value. Multiple evaluations of literals with thesame value (either the same occurrence in the program text or a differentoccurrence) may obtain the same object or a different object with the samevalue.

5.2.3. Parenthesized forms¶

A parenthesized form is an optional expression list enclosed in parentheses:

parenth_form ::=  "(" [expression_list] ")"

A parenthesized expression list yields whatever that expression list yields: ifthe list contains at least one comma, it yields a tuple; otherwise, it yieldsthe single expression that makes up the expression list.

An empty pair of parentheses yields an empty tuple object. Since tuples areimmutable, the rules for literals apply (i.e., two occurrences of the emptytuple may or may not yield the same object).

Note that tuples are not formed by the parentheses, but rather by use of thecomma operator. The exception is the empty tuple, for which parenthesesarerequired — allowing unparenthesized “nothing” in expressions would causeambiguities and allow common typos to pass uncaught.

5.2.4. List displays¶

A list display is a possibly empty series of expressions enclosed in squarebrackets:

list_display ::=  "[" [expression_list |list_comprehension] "]"list_comprehension ::=expressionlist_forlist_for ::=  "for"target_list "in"old_expression_list [list_iter]old_expression_list ::=old_expression [(","old_expression)+ [","]]old_expression ::=or_test |old_lambda_formlist_iter ::=list_for |list_iflist_if ::=  "if"old_expression [list_iter]

A list display yields a new list object. Its contents are specified byproviding either a list of expressions or a list comprehension. When acomma-separated list of expressions is supplied, its elements are evaluated fromleft to right and placed into the list object in that order. When a listcomprehension is supplied, it consists of a single expression followed by atleast onefor clause and zero or morefor orifclauses. In this case, the elements of the new list are those that would beproduced by considering each of thefor orif clauses ablock, nesting from left to right, and evaluating the expression to produce alist element each time the innermost block is reached[1].

5.2.5. Displays for sets and dictionaries¶

For constructing a set or a dictionary Python provides special syntaxcalled “displays”, each of them in two flavors:

• either the container contents are listed explicitly, or
• they are computed via a set of looping and filtering instructions, called acomprehension.

Common syntax elements for comprehensions are:

comprehension ::=expressioncomp_forcomp_for ::=  "for"target_list "in"or_test [comp_iter]comp_iter ::=comp_for |comp_ifcomp_if ::=  "if"expression_nocond [comp_iter]

The comprehension consists of a single expression followed by at least onefor clause and zero or morefor orif clauses.In this case, the elements of the new container are those that would be producedby considering each of thefor orif clauses a block,nesting from left to right, and evaluating the expression to produce an elementeach time the innermost block is reached.

Note that the comprehension is executed in a separate scope, so names assignedto in the target list don’t “leak” in the enclosing scope.

5.2.6. Generator expressions¶

A generator expression is a compact generator notation in parentheses:

generator_expression ::=  "("expressioncomp_for ")"

A generator expression yields a new generator object. Its syntax is the same asfor comprehensions, except that it is enclosed in parentheses instead ofbrackets or curly braces.

Variables used in the generator expression are evaluated lazily when the__next__() method is called for generator object (in the same fashion asnormal generators). However, the leftmostfor clause is immediatelyevaluated, so that an error produced by it can be seen before any other possibleerror in the code that handles the generator expression. Subsequentfor clauses cannot be evaluated immediately since they may depend onthe previousfor loop. For example:(x*yforxinrange(10)foryinbar(x)).

The parentheses can be omitted on calls with only one argument. See sectionCalls for the detail.

5.2.7. Dictionary displays¶

A dictionary display is a possibly empty series of key/datum pairs enclosed incurly braces:

dict_display ::=  "{" [key_datum_list |dict_comprehension] "}"key_datum_list ::=key_datum (","key_datum)* [","]key_datum ::=expression ":"expressiondict_comprehension ::=expression ":"expressioncomp_for

A dictionary display yields a new dictionary object.

If a comma-separated sequence of key/datum pairs is given, they are evaluatedfrom left to right to define the entries of the dictionary: each key object isused as a key into the dictionary to store the corresponding datum. This meansthat you can specify the same key multiple times in the key/datum list, and thefinal dictionary’s value for that key will be the last one given.

A dict comprehension, in contrast to list and set comprehensions, needs twoexpressions separated with a colon followed by the usual “for” and “if” clauses.When the comprehension is run, the resulting key and value elements are insertedin the new dictionary in the order they are produced.

Restrictions on the types of the key values are listed earlier in sectionThe standard type hierarchy. (To summarize, the key type should behashable, which excludesall mutable objects.) Clashes between duplicate keys are not detected; the lastdatum (textually rightmost in the display) stored for a given key valueprevails.

5.2.8. Set displays¶

A set display is denoted by curly braces and distinguishable from dictionarydisplays by the lack of colons separating keys and values:

set_display ::=  "{" (expression_list |comprehension) "}"

A set display yields a new mutable set object, the contents being specified byeither a sequence of expressions or a comprehension. When a comma-separatedlist of expressions is supplied, its elements are evaluated from left to rightand added to the set object. When a comprehension is supplied, the set isconstructed from the elements resulting from the comprehension.

An empty set cannot be constructed with{}; this literal constructs an emptydictionary.

5.2.9. String conversions¶

A string conversion is an expression list enclosed in reverse (a.k.a. backward)quotes:

string_conversion ::=  "`"expression_list "`"

A string conversion evaluates the contained expression list and converts theresulting object into a string according to rules specific to its type.

If the object is a string, a number,None, or a tuple, list or dictionarycontaining only objects whose type is one of these, the resulting string is avalid Python expression which can be passed to the built-in functioneval() to yield an expression with the same value (or an approximation, iffloating 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 referenceto themselves, directly or indirectly) use... to indicate a recursivereference, and the result cannot be passed toeval() to get an equal value(SyntaxError will be raised instead).

The built-in functionrepr() performs exactly the same conversion in itsargument as enclosing it in parentheses and reverse quotes does. The built-infunctionstr() performs a similar but more user-friendly conversion.

5.2.10. Yield expressions¶

yield_atom ::=  "("yield_expression ")"yield_expression ::=  "yield" [expression_list]

New in version 2.5.

Theyield expression is only used when defining a generator function,and can only be used in the body of a function definition. Using ayield expression in a function definition is sufficient to cause thatdefinition to create a generator function instead of a normal function.

When a generator function is called, it returns an iterator known as agenerator. That generator then controls the execution of a generator function.The execution starts when one of the generator’s methods is called. At thattime, the execution proceeds to the firstyield expression, where itis suspended again, returning the value ofexpression_list togenerator’s caller. By suspended we mean that all local state is retained,including the current bindings of local variables, the instruction pointer, andthe internal evaluation stack. When the execution is resumed by calling one ofthe generator’s methods, the function can proceed exactly as if theyield expression was just another external call. The value of theyield expression after resuming depends on the method which resumedthe execution.

All of this makes generator functions quite similar to coroutines; they yieldmultiple times, they have more than one entry point and their execution can besuspended. The only difference is that a generator function cannot controlwhere should the execution continue after it yields; the control is alwaystransferred to the generator’s caller.

>>>defecho(value=None):...print"Execution starts when 'next()' is called for the first time."...try:...whileTrue:...try:...value=(yieldvalue)...exceptException,e:...value=e...finally:...print"Don't forget to clean up when 'close()' is called."...>>>generator=echo(1)>>>printgenerator.next()Execution starts when 'next()' is called for the first time.1>>>printgenerator.next()None>>>printgenerator.send(2)2>>>generator.throw(TypeError,"spam")TypeError('spam',)>>>generator.close()Don't forget to clean up when 'close()' is called.

5.3.1. Attribute references¶

An attribute reference is a primary followed by a period and a name:

attributeref ::=primary "."identifier

The primary must evaluate to an object of a type that supports attributereferences, e.g., a module, list, or an instance. This object is then asked toproduce the attribute whose name is the identifier. If this attribute is notavailable, the exceptionAttributeError is raised. Otherwise, the typeand value of the object produced is determined by the object. Multipleevaluations of the same attribute reference may yield different objects.

5.3.2. Subscriptions¶

A subscription selects an item of a sequence (string, tuple or list) or mapping(dictionary) object:

subscription ::=primary "["expression_list "]"

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 objectwhose value is one of the keys of the mapping, and the subscription selects thevalue in the mapping that corresponds to that key. (The expression list is atuple except if it has exactly one item.)

If the primary is a sequence, the expression (list) must evaluate to a plaininteger. If this value is negative, the length of the sequence is added to it(so that, e.g.,x[-1] selects the last item ofx.) The resulting valuemust be a nonnegative integer less than the number of items in the sequence, andthe subscription selects the item whose index is that value (counting fromzero).

A string’s items are characters. A character is not a separate data type but astring of exactly one character.

5.3.3. Slicings¶

A slicing selects a range of items in a sequence object (e.g., a string, tupleor list). Slicings may be used as expressions or as targets in assignment ordel statements. The syntax for a slicing:

slicing ::=simple_slicing |extended_slicingsimple_slicing ::=primary "["short_slice "]"extended_slicing ::=primary "["slice_list "]"slice_list ::=slice_item (","slice_item)* [","]slice_item ::=expression |proper_slice |ellipsisproper_slice ::=short_slice |long_sliceshort_slice ::=  [lower_bound] ":" [upper_bound]long_slice ::=short_slice ":" [stride]lower_bound ::=expressionupper_bound ::=expressionstride ::=expressionellipsis ::=  "..."

There is ambiguity in the formal syntax here: anything that looks like anexpression list also looks like a slice list, so any subscription can beinterpreted as a slicing. Rather than further complicating the syntax, this isdisambiguated by defining that in this case the interpretation as a subscriptiontakes priority over the interpretation as a slicing (this is the case if theslice list contains no proper slice nor ellipses). Similarly, when the slicelist has exactly one short slice and no trailing comma, the interpretation as asimple slicing takes priority over that as an extended slicing.

The semantics for a simple slicing are as follows. The primary must evaluate toa sequence object. The lower and upper bound expressions, if present, mustevaluate to plain integers; defaults are zero and thesys.maxint,respectively. If either bound is negative, the sequence’s length is added toit. The slicing now selects all items with indexk such thati<=k<jwherei andj are the specified lower and upper bounds. This may be anempty sequence. It is not an error ifi orj lie outside the range of validindexes (such items don’t exist so they aren’t selected).

The semantics for an extended slicing are as follows. The primary must evaluateto a mapping object, and it is indexed with a key that is constructed from theslice list, as follows. If the slice list contains at least one comma, the keyis a tuple containing the conversion of the slice items; otherwise, theconversion of the lone slice item is the key. The conversion of a slice itemthat is an expression is that expression. The conversion of an ellipsis sliceitem is the built-inEllipsis object. The conversion of a proper slice is aslice object (see sectionThe standard type hierarchy) whosestart,stop andstep attributes are the values of the expressions given as lower bound,upper bound and stride, respectively, substitutingNone for missingexpressions.

5.3.4. Calls¶

A call calls a callable object (e.g., a function) with a possibly empty seriesof arguments:

call ::=primary "(" [argument_list [","]                          |expressiongenexpr_for] ")"argument_list ::=positional_arguments [","keyword_arguments]                            ["," "*"expression] [","keyword_arguments]                            ["," "**"expression]                          |keyword_arguments ["," "*"expression]                            ["," "**"expression]                          | "*"expression ["," "*"expression] ["," "**"expression]                          | "**"expressionpositional_arguments ::=expression (","expression)*keyword_arguments ::=keyword_item (","keyword_item)*keyword_item ::=identifier "="expression

A trailing comma may be present after the positional and keyword arguments butdoes not affect the semantics.

The primary must evaluate to a callable object (user-defined functions, built-infunctions, methods of built-in objects, class objects, methods of classinstances, and certain class instances themselves are callable; extensions maydefine additional callable object types). All argument expressions areevaluated before the call is attempted. Please refer to sectionFunction definitionsfor the syntax of formal parameter lists.

If keyword arguments are present, they are first converted to positionalarguments, as follows. First, a list of unfilled slots is created for theformal parameters. If there are N positional arguments, they are placed in thefirst N slots. Next, for each keyword argument, the identifier is used todetermine the corresponding slot (if the identifier is the same as the firstformal parameter name, the first slot is used, and so on). If the slot isalready filled, aTypeError exception is raised. Otherwise, the value ofthe argument is placed in the slot, filling it (even if the expression isNone, it fills the slot). When all arguments have been processed, the slotsthat are still unfilled are filled with the corresponding default value from thefunction definition. (Default values are calculated, once, when the function isdefined; thus, a mutable object such as a list or dictionary used as defaultvalue will be shared by all calls that don’t specify an argument value for thecorresponding slot; this should usually be avoided.) If there are any unfilledslots for which no default value is specified, aTypeError exception israised. Otherwise, the list of filled slots is used as the argument list forthe call.

If there are more positional arguments than there are formal parameter slots, aTypeError exception is raised, unless a formal parameter using the syntax*identifier is present; in this case, that formal parameter receives a tuplecontaining the excess positional arguments (or an empty tuple if there were noexcess positional arguments).

If any keyword argument does not correspond to a formal parameter name, aTypeError exception is raised, unless a formal parameter using the syntax**identifier is present; in this case, that formal parameter receives adictionary containing the excess keyword arguments (using the keywords as keysand the argument values as corresponding values), or a (new) empty dictionary ifthere were no excess keyword arguments.

If the syntax*expression appears in the function call,expression mustevaluate to an iterable. Elements from this iterable are treated as if theywere additional positional arguments; if there are positional argumentsx1, ...,xN, andexpression evaluates to a sequencey1, ...,yM, thisis equivalent to a call with M+N positional argumentsx1, ...,xN,y1,...,yM.

A consequence of this is that although the*expression syntax may appearafter some keyword arguments, it is processedbefore the keyword arguments(and the**expression argument, if any – see below). So:

>>>deff(a,b):...printa,b...>>>f(b=1,*(2,))2 1>>>f(a=1,*(2,))Traceback (most recent call last):  File"<stdin>", line1, in?TypeError:f() got multiple values for keyword argument 'a'>>>f(1,*(2,))1 2

It is unusual for both keyword arguments and the*expression syntax to beused in the same call, so in practice this confusion does not arise.

If the syntax**expression appears in the function call,expression mustevaluate to a mapping, the contents of which are treated as additional keywordarguments. In the case of a keyword appearing in bothexpression and as anexplicit keyword argument, aTypeError exception is raised.

Formal parameters using the syntax*identifier or**identifier cannot beused as positional argument slots or as keyword argument names. Formalparameters using the syntax(sublist) cannot be used as keyword argumentnames; the outermost sublist corresponds to a single unnamed argument slot, andthe argument value is assigned to the sublist using the usual tuple assignmentrules after all other parameter processing is done.

A call always returns some value, possiblyNone, unless it raises anexception. How this value is computed depends on the type of the callableobject.

If it is—

a user-defined function:

The code block for the function is executed, passing it the argument list. Thefirst thing the code block will do is bind the formal parameters to thearguments; this is described in sectionFunction definitions. When the code blockexecutes areturn statement, this specifies the return value of thefunction call.

a built-in function or method:

The result is up to the interpreter; seeBuilt-in Functions for thedescriptions of built-in functions and methods.

a class object:

A new instance of that class is returned.

a class instance method:

The corresponding user-defined function is called, with an argument list that isone longer than the argument list of the call: the instance becomes the firstargument.

a class instance:

The class must define a__call__() method; the effect is then the same asif that method was called.

Note

In the current implementation, the right-hand operand is requiredto be at mostsys.maxsize. If the right-hand operand is larger thansys.maxsize anOverflowError exception is raised.