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 ::=  "(" [starred_expression] ")"

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” into the enclosing scope.

6.2.5. List displays¶

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

list_display ::=  "[" [starred_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 ::=  "{" (starred_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 ":"expression | "**"or_exprdict_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 double asterisk** denotesdictionary unpacking.Its operand must be amapping. Each mapping item is addedto the new dictionary. Later values replace values already set byearlier key/datum pairs and earlier dictionary unpackings.

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 the 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 details.

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 the 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 the generator’scaller. By suspended, we mean that all local state is retained, including thecurrent bindings of local variables, the instruction pointer, the internalevaluation stack, and the state of any exception handling. When the executionis resumed by calling one of thegenerator’s methods, the function can proceed exactly as if the yield expressionwere 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 the execution should continue after it yields; the control is alwaystransferred to the generator’s caller.

Yield expressions are allowed anywhere in atry construct. If thegenerator 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. This production can be customized byoverriding the__getattr__() method. If this attribute is not available,the exceptionAttributeError is raised. Otherwise, the type and value ofthe object produced is determined by the object. Multiple evaluations of thesame attribute 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 (lists ordictionaries for example). User-defined objects can support subscription bydefining 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 is indexed (using thesame__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 [","starred_and_keywords]                            [","keywords_arguments]                          |starred_and_keywords [","keywords_arguments]                          |keywords_argumentspositional_arguments ::=  ["*"]expression ("," ["*"]expression)*starred_and_keywords ::=  ("*"expression |keyword_item)                          ("," "*"expression | ","keyword_item)*keywords_arguments ::=  (keyword_item | "**"expression)                          (","keyword_item | "," "**"expression)*keyword_item ::=identifier "="expression

An optional trailing comma may be present after the positional and keyword argumentsbut does 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 aniterable. Elements from these iterables aretreated as if they were additional positional arguments. For the callf(x1,x2,*y,x3,x4), ify evaluates to a sequencey1, …,yM,this is equivalent to a call with M+4 positional argumentsx1,x2,y1, …,yM,x3,x4.

A consequence of this is that although the*expression syntax may appearafter explicit keyword arguments, it is processedbefore thekeyword arguments (and any**expression arguments – 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<module>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 amapping, the contents of which are treated asadditional keyword arguments. If a keyword is already present(as an explicit keyword argument, or from another unpacking),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.

New in version 3.5.

New in version 3.5.

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.

6.10.1. Value comparisons¶

The operators<,>,==,>=,<=, and!= compare thevalues of two objects. The objects do not need to have the same type.

ChapterObjects, values and types states that objects have a value (in addition to typeand identity). The value of an object is a rather abstract notion in Python:For example, there is no canonical access method for an object’s value. Also,there is no requirement that the value of an object should be constructed in aparticular way, e.g. comprised of all its data attributes. Comparison operatorsimplement a particular notion of what the value of an object is. One can thinkof them as defining the value of an object indirectly, by means of theircomparison implementation.

Because all types are (direct or indirect) subtypes ofobject, theyinherit the default comparison behavior fromobject. Types cancustomize their comparison behavior by implementingrich comparison methods like__lt__(), described inBasic customization.

The default behavior for equality comparison (== and!=) is based onthe identity of the objects. Hence, equality comparison of instances with thesame identity results in equality, and equality comparison of instances withdifferent identities results in inequality. A motivation for this defaultbehavior is the desire that all objects should be reflexive (i.e.xisyimpliesx==y).

A default order comparison (<,>,<=, and>=) is not provided;an attempt raisesTypeError. A motivation for this default behavior isthe lack of a similar invariant as for equality.

The behavior of the default equality comparison, that instances with differentidentities are always unequal, may be in contrast to what types will need thathave a sensible definition of object value and value-based equality. Suchtypes will need to customize their comparison behavior, and in fact, a numberof built-in types have done that.

The following list describes the comparison behavior of the most importantbuilt-in types.

• Numbers of built-in numeric types (Numeric Types — int, float, complex) and of the standardlibrary typesfractions.Fraction anddecimal.Decimal can becompared within and across their types, with the restriction that complexnumbers do not support order comparison. Within the limits of the typesinvolved, they compare mathematically (algorithmically) correct without lossof precision.

  The not-a-number valuesfloat('NaN') andDecimal('NaN')are special. They are identical to themselves (xisx is true) butare not equal to themselves (x==x is false). Additionally,comparing any number to a not-a-number valuewill returnFalse. For example, both3<float('NaN') andfloat('NaN')<3 will returnFalse.

• Binary sequences (instances ofbytes orbytearray) can becompared within and across their types. They compare lexicographically usingthe numeric values of their elements.

• Strings (instances ofstr) compare lexicographically using thenumerical Unicode code points (the result of the built-in functionord()) of their characters.[3]

  Strings and binary sequences cannot be directly compared.

• Sequences (instances oftuple,list, orrange) canbe compared only within each of their types, with the restriction that rangesdo not support order comparison. Equality comparison across these typesresults in unequality, and ordering comparison across these types raisesTypeError.

  Sequences compare lexicographically using comparison of correspondingelements, whereby reflexivity of the elements is enforced.

  In enforcing reflexivity of elements, the comparison of collections assumesthat for a collection elementx,x==x is always true. Based onthat assumption, element identity is compared first, and element comparisonis performed only for distinct elements. This approach yields the sameresult as a strict element comparison would, if the compared elements arereflexive. For non-reflexive elements, the result is different than forstrict element comparison, and may be surprising: The non-reflexivenot-a-number values for example result in the following comparison behaviorwhen used in a list:

  >>>nan=float('NaN')>>>nanisnanTrue>>>nan==nanFalse                 <-- the defined non-reflexive behavior of NaN>>>[nan]==[nan]True                  <-- list enforces reflexivity and tests identity first

  Lexicographical comparison between built-in collections works as follows:

  • For two collections to compare equal, they must be of the same type, havethe same length, and each pair of corresponding elements must compareequal (for example,[1,2]==(1,2) is false because the type is not thesame).
  • Collections that support order comparison are ordered the same as theirfirst unequal elements (for example,[1,2,x]<=[1,2,y] has the samevalue asx<=y). If a corresponding element does not exist, theshorter collection is ordered first (for example,[1,2]<[1,2,3] istrue).

• Mappings (instances ofdict) compare equal if and only if they haveequal(key, value) pairs. Equality comparison of the keys and valuesenforces reflexivity.

  Order comparisons (<,>,<=, and>=) raiseTypeError.

• Sets (instances ofset orfrozenset) can be compared withinand across their types.

  They define ordercomparison operators to mean subset and superset tests. Those relations donot define total orderings (for example, the two sets{1,2} and{2,3}are not equal, nor subsets of one another, nor supersets of oneanother). Accordingly, sets are not appropriate arguments for functionswhich depend on total ordering (for example,min(),max(), andsorted() produce undefined results given a list of sets as inputs).

  Comparison of sets enforces reflexivity of its elements.

• Most other built-in types have no comparison methods implemented, so theyinherit the default comparison behavior.

User-defined classes that customize their comparison behavior should followsome consistency rules, if possible:

• Equality comparison should be reflexive.In other words, identical objects should compare equal:

  xisy impliesx==y

• Comparison should be symmetric.In other words, the following expressions should have the same result:

  x==y andy==x

  x!=y andy!=x

  x<y andy>x

  x<=y andy>=x

• Comparison should be transitive.The following (non-exhaustive) examples illustrate that:

  x>yandy>z impliesx>z

  x<yandy<=z impliesx<z

• Inverse comparison should result in the boolean negation.In other words, the following expressions should have the same result:

  x==y andnotx!=y

  x<y andnotx>=y (for total ordering)

  x>y andnotx<=y (for total ordering)

  The last two expressions apply to totally ordered collections (e.g. tosequences, but not to sets or mappings). See also thetotal_ordering() decorator.

• Thehash() result should be consistent with equality.Objects that are equal should either have the same hash value,or be marked as unhashable.

Python does not enforce these consistency rules. In fact, the not-a-numbervalues are an example for not following these rules.

6.10.2. Membership test operations¶

The operatorsin andnotin test for membership.xins evaluates toTrue ifx is a member ofs, andFalse otherwise.xnotins returns the negation ofxins. All built-in sequences andset types support this as well as dictionary, for whichin testswhether the dictionary has a given key. For container types such as list, tuple,set, frozenset, dict, or collections.deque, the expressionxiny is equivalenttoany(xiseorx==eforeiny).

For the string and bytes types,xiny isTrue if and only ifx is asubstring ofy. An equivalent test isy.find(x)!=-1. Empty strings arealways considered to be a substring of any other string, so""in"abc" willreturnTrue.

For user-defined classes which define the__contains__() method,xiny returnsTrue ify.__contains__(x) returns a true value, andFalse otherwise.

For user-defined classes which do not define__contains__() but do define__iter__(),xiny isTrue if some valuez withx==z isproduced while iterating overy. If an exception is raised during theiteration, it is as ifin raised that exception.

Lastly, the old-style iteration protocol is tried: if a class defines__getitem__(),xiny isTrue if and only if there is a non-negativeinteger indexi such thatx==y[i], and all lower integer indices do notraiseIndexError exception. (If any other exception is raised, it is asifin raised that exception).

The operatornotin is defined to have the inverse true value ofin.

6.10.3. Identity comparisons¶

The operatorsis andisnot test for object identity:xisy is true if and only ifx andy are the same object. Object identityis determined using theid() function.xisnoty yields the inversetruth value.[4]

New in version 3.5:Iterable unpacking in expression lists, originally proposed byPEP 448.