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

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_exprlist_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 reached1.

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]

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 theexpressions given as lower bound, upper bound and stride, respectively,substitutingNone for missing expressions.

5.3.4.Calls¶

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

call ::=primary "(" [argument_list [","]                          |expressiongenexpr_for] ")"argument_list ::=positional_arguments [","keyword_arguments]                            ["," "*"expression] [","keyword_arguments]                            ["," "**"expression]                          |keyword_arguments ["," "*"expression]                            ["," "**"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 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 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, 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<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 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.

Deprecated since version 2.3:The floor division operator, the modulo operator, and thedivmod()function are no longer defined for complex numbers. Instead, convert to afloating point number using theabs() function if appropriate.

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.

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

Types can customize their comparison behavior by implementinga__cmp__() method orrich 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).

The default order comparison (<,>,<=, and>=) gives aconsistent but arbitrary order.

(This unusual definition of comparison was used to simplify the definition ofoperations like sorting and thein andnotin operators.In the future, the comparison rules for objects of different types are likely tochange.)

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, long, 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.

• Strings (instances ofstr orunicode)compare lexicographically using the numeric equivalents (theresult of the built-in functionord()) of their characters.4When comparing an 8-bit string and a Unicode string, the 8-bit stringis converted to Unicode. If the conversion fails, the stringsare considered unequal.

• Instances oftuple orlist can be compared onlywithin each of their types. Equality comparison across these typesresults in unequality, and ordering comparison across these typesgives an arbitrary order.

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

  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 are ordered the same as theirfirst unequal elements (for example,cmp([1,2,x],[1,2,y]) returns thesame ascmp(x,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.

  Outcomes other than equality are resolvedconsistently, but are not otherwise defined.5

• Most other objects of built-in types compare unequal unless they are the sameobject; the choice whether one object is considered smaller or larger thananother one is made arbitrarily but consistently within one execution of aprogram.

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.

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

5.9.3.Identity comparisons¶

The operatorsis andisnot test for object identity:xisy is true if and only ifx andy are the same object.xisnotyyields the inverse truth value.6

New in version 2.5.