6.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, with leading underscoresremoved and a single underscore inserted, in front of the name. For example,the identifier__spam occurring in a class namedHam will be transformedto_Ham__spam. This transformation is independent of the syntacticalcontext in which the identifier is used. If the transformed name is extremelylong (longer than 255 characters), implementation defined truncation may happen.If the class name consists only of underscores, no transformation is done.

6.2.2. Literals¶

Python supports string and bytes literals and various numeric literals:

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

Evaluation of a literal yields an object of the given type (string, bytes,integer, floating point number, complex number) with the given value. The valuemay 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.

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

6.2.4. Displays for lists, sets and dictionaries¶

For constructing a list, 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.

6.2.5. List displays¶

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

list_display ::=  "[" [expression_list |comprehension] "]"

A list display yields a new list object, the contents being specified by eithera list of expressions or a comprehension. When a comma-separated list ofexpressions is supplied, its elements are evaluated from left to right andplaced into the list object in that order. When a comprehension is supplied,the list is constructed from the elements resulting from the comprehension.

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

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

6.2.8. 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 samefashion as normal generators). However, the leftmostfor clause isimmediately evaluated, so that an error produced by it can be seen before anyother possible error in the code that handles the generator expression.Subsequentfor clauses cannot be evaluated immediately since theymay depend on the 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.

6.2.9. Yield expressions¶

yield_atom ::=  "("yield_expression ")"yield_expression ::=  "yield" [expression_list | "from"expression]

The yield expression is only used when defining agenerator function andthus can only be used in the body of a function definition. Using a yieldexpression in a function’s body causes that function to be a generator.

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 first yield expression, where it issuspended again, returning the value ofexpression_list to generator’scaller. By suspended, we mean that all local state is retained, including thecurrent bindings of local variables, the instruction pointer, and the internalevaluation stack. When the execution is resumed by calling one of thegenerator’s methods, the function can proceed exactly as if the yield expressionwas just another external call. The value of the yield expression afterresuming depends on the method which resumed the execution. If__next__() is used (typically via either afor orthenext() builtin) then the result isNone. Otherwise, ifsend() is used, then the result will be the value passed in tothat method.

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.

yield expressions are allowed in thetry clause of atry...finally construct. If the generator is not resumed before it isfinalized (by reaching a zero reference count or by being garbage collected),the generator-iterator’sclose() method will be called,allowing any pendingfinally clauses to execute.

Whenyieldfrom<expr> is used, it treats the supplied expression asa subiterator. All values produced by that subiterator are passed directlyto the caller of the current generator’s methods. Any values passed in withsend() and any exceptions passed in withthrow() are passed to the underlying iterator if it has theappropriate methods. If this is not the case, thensend()will raiseAttributeError orTypeError, whilethrow() will just raise the passed in exception immediately.

When the underlying iterator is complete, thevalueattribute of the raisedStopIteration instance becomes the value ofthe yield expression. It can be either set explicitly when raisingStopIteration, or automatically when the sub-iterator is a generator(by returning a value from the sub-generator).

Changed in version 3.3:Addedyieldfrom<expr> to delegate control flow to a subiterator

The parentheses may be omitted when the yield expression is the sole expressionon the right hand side of an assignment statement.

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

6.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, which most objects do. This object is then asked to produce theattribute whose name is the identifier (which can be customized by overridingthe__getattr__() method). If this attribute is not available, theexceptionAttributeError is raised. Otherwise, the type and value of theobject produced is determined by the object. Multiple evaluations of the sameattribute reference may yield different objects.

6.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 that supports subscription, e.g. a listor dictionary. User-defined objects can support subscription by defining a__getitem__() method.

For built-in objects, there are two types of objects that support subscription:

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 an integeror a slice (as discussed in the following section).

The formal syntax makes no special provision for negative indices insequences; however, built-in sequences all provide a__getitem__()method that interprets negative indices by adding the length of the sequenceto the index (so thatx[-1] selects the last item ofx). Theresulting value must be a nonnegative integer less than the number of items inthe sequence, and the subscription selects the item whose index is that value(counting from zero). Since the support for negative indices and slicingoccurs in the object’s__getitem__() method, subclasses overridingthis method will need to explicitly add that support.

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

6.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 ::=primary "["slice_list "]"slice_list ::=slice_item (","slice_item)* [","]slice_item ::=expression |proper_sliceproper_slice ::=  [lower_bound] ":" [upper_bound] [ ":" [stride] ]lower_bound ::=expressionupper_bound ::=expressionstride ::=expression

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

The semantics for a slicing are as follows. The primary must evaluate to amapping object, and it is indexed (using the same__getitem__() method asnormal subscription) with a key that is constructed from the slice list, asfollows. If the slice list contains at least one comma, the key is a tuplecontaining the conversion of the slice items; otherwise, the conversion of thelone slice item is the key. The conversion of a slice item that is anexpression is that expression. The conversion of a proper slice is a sliceobject (see sectionThe standard type hierarchy) whosestart,stop andstep attributes are the values of theexpressions given as lower bound, upper bound and stride, respectively,substitutingNone for missing expressions.

6.3.4. Calls¶

A call calls a callable object (e.g., afunction) with a possibly emptyseries ofarguments:

call ::=primary "(" [argument_list [","] |comprehension] ")"argument_list ::=positional_arguments [","keyword_arguments]                            ["," "*"expression] [","keyword_arguments]                            ["," "**"expression]                          |keyword_arguments ["," "*"expression]                            [","keyword_arguments] ["," "**"expression]                          | "*"expression [","keyword_arguments] ["," "**"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 all objects having a__call__() method are callable). Allargument expressions are evaluated before the call is attempted. Please referto sectionFunction definitions for the syntax of formalparameter 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,this is 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):...print(a,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.

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.

def <lambda>(arguments):    return expression