Note

Historically (until release 2.2), Python’s built-in types have differed fromuser-defined types because it was not possible to use the built-in types as thebasis for object-oriented inheritance. This limitation no longerexists.

5.1.Truth Value Testing¶

Any object can be tested for truth value, for use in anif orwhile condition or as operand of the Boolean operations below. Thefollowing values are considered false:

• None

• False

• zero of any numeric type, for example,0,0L,0.0,0j.

• any empty sequence, for example,'',(),[].

• any empty mapping, for example,{}.

• instances of user-defined classes, if the class defines a__nonzero__()or__len__() method, when that method returns the integer zero orbool valueFalse.1

All other values are considered true — so objects of many types are alwaystrue.

Operations and built-in functions that have a Boolean result always return0orFalse for false and1 orTrue for true, unless otherwise stated.(Important exception: the Boolean operationsor andand always returnone of their operands.)

5.2.Boolean Operations —and,or,not¶

These are the Boolean operations, ordered by ascending priority:

Notes:

1. This is a short-circuit operator, so it only evaluates the secondargument if the first one is false.

2. This is a short-circuit operator, so it only evaluates the secondargument if the first one is true.

3. not has a lower priority than non-Boolean operators, sonota==b isinterpreted asnot(a==b), anda==notb is a syntax error.

5.3.Comparisons¶

Comparison operations are supported by all objects. They all have the samepriority (which is higher than that of the Boolean operations). Comparisons canbe chained arbitrarily; for example,x<y<=z is equivalent tox<yandy<=z, except thaty is evaluated only once (but in both casesz is notevaluated at all whenx<y is found to be false).

This table summarizes the comparison operations:

Notes:

1. != can also be written<>, but this is an obsolete usagekept for backwards compatibility only. New code should always use!=.

Objects of different types, except different numeric types and different stringtypes, never compare equal; such objects are ordered consistently butarbitrarily (so that sorting a heterogeneous array yields a consistent result).Furthermore, some types (for example, file objects) support only a degeneratenotion of comparison where any two objects of that type are unequal. Again,such objects are ordered arbitrarily but consistently. The<,<=,>and>= operators will raise aTypeError exception when any operand isa complex number.

Non-identical instances of a class normally compare as non-equal unless theclass defines the__eq__() method or the__cmp__() method.

Instances of a class cannot be ordered with respect to other instances of thesame class, or other types of object, unless the class defines either enough ofthe rich comparison methods (__lt__(),__le__(),__gt__(), and__ge__()) or the__cmp__() method.

Two more operations with the same syntactic priority,in andnotin, aresupported only by sequence types (below).

5.4.Numeric Types —int,float,long,complex¶

There are four distinct numeric types:plain integers,longintegers,floating point numbers, andcomplex numbers. Inaddition, Booleans are a subtype of plain integers. Plain integers (also justcalledintegers) are implemented usinglong in C, which givesthem at least 32 bits of precision (sys.maxint is always set to the maximumplain integer value for the current platform, the minimum value is-sys.maxint-1). Long integers have unlimited precision. Floating pointnumbers are usually implemented usingdouble in C; information aboutthe precision and internal representation of floating point numbers for themachine on which your program is running is available insys.float_info. Complex numbers have a real and imaginary part, whichare each a floating point number. To extract these parts from a complex numberz, usez.real andz.imag. (The standard library includes additionalnumeric types,fractions that hold rationals, anddecimal thathold floating-point numbers with user-definable precision.)

Numbers are created by numeric literals or as the result of built-in functionsand operators. Unadorned integer literals (including binary, hex, and octalnumbers) yield plain integers unless the value they denote is too large to berepresented as a plain integer, in which case they yield a long integer.Integer literals with an'L' or'l' suffix yield long integers ('L'is preferred because1l looks too much like eleven!). Numeric literalscontaining a decimal point or an exponent sign yield floating point numbers.Appending'j' or'J' to a numeric literal yields an imaginary number(a complex number with a zero real part) which you can add to an integer orfloat to get a complex number with real and imaginary parts.

Python fully supports mixed arithmetic: when a binary arithmetic operator hasoperands of different numeric types, the operand with the “narrower” type iswidened to that of the other, where plain integer is narrower than long integeris narrower than floating point is narrower than complex. Comparisons betweennumbers of mixed type use the same rule.2 The constructorsint(),long(),float(), andcomplex() can be used to produce numbersof a specific type.

All built-in numeric types support the following operations. SeeThe power operator and later sections for the operators’ priorities.

Notes:

1. For (plain or long) integer division, the result is an integer. The result isalways rounded towards minus infinity: 1/2 is 0, (-1)/2 is -1, 1/(-2) is -1, and(-1)/(-2) is 0. Note that the result is a long integer if either operand is along integer, regardless of the numeric value.

2. Conversion from floats usingint() orlong() truncates towardzero like the related function,math.trunc(). Use the functionmath.floor() to round downward andmath.ceil() to roundupward.

3. SeeBuilt-in Functions for a full description.

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

5. Also referred to as integer division. The resultant value is a whole integer,though the result’s type is not necessarily int.

6. float also accepts the strings “nan” and “inf” with an optional prefix “+”or “-” for Not a Number (NaN) and positive or negative infinity.

   New in version 2.6.

7. Python definespow(0,0) and0**0 to be1, as is common forprogramming languages.

Allnumbers.Real types (int,long, andfloat) also include the following operations:

[sign]['0x']integer['.'fraction]['p'exponent]

>>>float.fromhex('0x3.a7p10')3740.0

>>>float.hex(3740.0)'0x1.d380000000000p+11'

5.5.Iterator Types¶

Python supports a concept of iteration over containers. This is implementedusing two distinct methods; these are used to allow user-defined classes tosupport iteration. Sequences, described below in more detail, always supportthe iteration methods.

One method needs to be defined for container objects to provide iterationsupport:

container.__iter__()¶

Return an iterator object. The object is required to support the iteratorprotocol described below. If a container supports different types ofiteration, additional methods can be provided to specifically requestiterators for those iteration types. (An example of an object supportingmultiple forms of iteration would be a tree structure which supports bothbreadth-first and depth-first traversal.) This method corresponds to thetp_iter slot of the type structure for Python objects in the Python/CAPI.

The iterator objects themselves are required to support the following twomethods, which together form theiterator protocol:

iterator.__iter__()¶

Return the iterator object itself. This is required to allow both containersand iterators to be used with thefor andin statements.This method corresponds to thetp_iter slot of the type structure forPython objects in the Python/C API.

iterator.next()¶

Return the next item from the container. If there are no further items, raisetheStopIteration exception. This method corresponds to thetp_iternext slot of the type structure for Python objects in thePython/C API.

Python defines several iterator objects to support iteration over general andspecific sequence types, dictionaries, and other more specialized forms. Thespecific types are not important beyond their implementation of the iteratorprotocol.

The intention of the protocol is that once an iterator’snext() methodraisesStopIteration, it will continue to do so on subsequent calls.Implementations that do not obey this property are deemed broken. (Thisconstraint was added in Python 2.3; in Python 2.2, various iterators are brokenaccording to this rule.)

5.6.Sequence Types —str,unicode,list,tuple,bytearray,buffer,xrange¶

There are seven sequence types: strings, Unicode strings, lists, tuples,bytearrays, buffers, and xrange objects.

For other containers see the built indict andset classes,and thecollections module.

String literals are written in single or double quotes:'xyzzy',"frobozz". SeeString literals for more about string literals.Unicode strings are much like strings, but are specified in the syntaxusing a preceding'u' character:u'abc',u"def". In additionto the functionality described here, there are also string-specificmethods described in theString Methods section. Lists areconstructed with square brackets, separating items with commas:[a,b,c].Tuples are constructed by the comma operator (not within squarebrackets), with or without enclosing parentheses, but an empty tuplemust have the enclosing parentheses, such asa,b,c or(). Asingle item tuple must have a trailing comma, such as(d,).

Bytearray objects are created with the built-in functionbytearray().

Buffer objects are not directly supported by Python syntax, but can be createdby calling the built-in functionbuffer(). They don’t supportconcatenation or repetition.

Objects of type xrange are similar to buffers in that there is no specific syntax tocreate them, but they are created using thexrange() function. They don’tsupport slicing, concatenation or repetition, and usingin,notin,min() ormax() on them is inefficient.

Most sequence types support the following operations. Thein andnotinoperations have the same priorities as the comparison operations. The+ and* operations have the same priority as the corresponding numeric operations.3 Additional methods are provided forMutable Sequence Types.

This table lists the sequence operations sorted in ascending priority.In the table,s andt are sequences of the same type;n,i andj are integers:

Sequence types also support comparisons. In particular, tuples and listsare compared lexicographically by comparing correspondingelements. This means that to compare equal, every element must compareequal and the two sequences must be of the same type and have the samelength. (For full details seeComparisons in the languagereference.)

Notes:

1. Whens is a string or Unicode string object thein andnotinoperations act like a substring test. In Python versions before 2.3,x had tobe a string of length 1. In Python 2.3 and beyond,x may be a string of anylength.

2. Values ofn less than0 are treated as0 (which yields an emptysequence of the same type ass). Note that items in the sequencesare not copied; they are referenced multiple times. This often hauntsnew Python programmers; consider:

   >>>lists=[[]]*3>>>lists[[], [], []]>>>lists[0].append(3)>>>lists[[3], [3], [3]]

   What has happened is that[[]] is a one-element list containing an emptylist, so all three elements of[[]]*3 are references to this single emptylist. Modifying any of the elements oflists modifies this single list.You can create a list of different lists this way:

   >>>lists=[[]foriinrange(3)]>>>lists[0].append(3)>>>lists[1].append(5)>>>lists[2].append(7)>>>lists[[3], [5], [7]]

   Further explanation is available in the FAQ entryHow do I create a multidimensional list?.

3. Ifi orj is negative, the index is relative to the end of sequences:len(s)+i orlen(s)+j is substituted. But note that-0 is still0.

4. The slice ofs fromi toj is defined as the sequence of items with indexk such thati<=k<j. Ifi orj is greater thanlen(s), uselen(s). Ifi is omitted orNone, use0. Ifj is omitted orNone, uselen(s). Ifi is greater than or equal toj, the slice isempty.

5. The slice ofs fromi toj with stepk is defined as the sequence ofitems with indexx=i+n*k such that0<=n<(j-i)/k. In other words,the indices arei,i+k,i+2*k,i+3*k and so on, stopping whenj is reached (but never includingj). Whenk is positive,i andj are reduced tolen(s) if they are greater.Whenk is negative,i andj are reduced tolen(s)-1 ifthey are greater. Ifi orj are omitted orNone, they become“end” values (which end depends on the sign ofk). Note,k cannot be zero.Ifk isNone, it is treated like1.

6. CPython implementation detail: Ifs andt are both strings, some Python implementations such asCPython can usually perform an in-place optimization for assignments ofthe forms=s+t ors+=t. When applicable, this optimizationmakes quadratic run-time much less likely. This optimization is bothversion and implementation dependent. For performance sensitive code, itis preferable to use thestr.join() method which assures consistentlinear concatenation performance across versions and implementations.

   Changed in version 2.4:Formerly, string concatenation never occurred in-place.

>>>print'%(language)s has%(number)03d quote types.'% \...{"language":"Python","number":2}Python has 002 quote types.

5.7.Set Types —set,frozenset¶

Aset object is an unordered collection of distincthashable objects.Common uses include membership testing, removing duplicates from a sequence, andcomputing mathematical operations such as intersection, union, difference, andsymmetric difference.(For other containers see the built indict,list,andtuple classes, and thecollections module.)

Like other collections, sets supportxinset,len(set), andforxinset. Being an unordered collection, sets do not record element position ororder of insertion. Accordingly, sets do not support indexing, slicing, orother sequence-like behavior.

There are currently two built-in set types,set andfrozenset.Theset type is mutable — the contents can be changed using methodslikeadd() andremove(). Since it is mutable, it has nohash value and cannot be used as either a dictionary key or as an element ofanother set. Thefrozenset type is immutable andhashable —its contents cannot be altered after it is created; it can therefore be used asa dictionary key or as an element of another set.

As of Python 2.7, non-empty sets (not frozensets) can be created by placing acomma-separated list of elements within braces, for example:{'jack','sjoerd'}, in addition to theset constructor.

The constructors for both classes work the same:

classset([iterable])¶

classfrozenset([iterable])¶

Return a new set or frozenset object whose elements are taken fromiterable. The elements of a set must behashable. Torepresent sets of sets, the inner sets must befrozensetobjects. Ifiterable is not specified, a new empty set isreturned.

Instances ofset andfrozenset provide the followingoperations:

len(s)

Return the number of elements in sets (cardinality ofs).

x in s

Testx for membership ins.

x not in s

Testx for non-membership ins.

isdisjoint(other)¶

ReturnTrue if the set has no elements in common withother. Sets aredisjoint if and only if their intersection is the empty set.

New in version 2.6.

issubset(other)¶

set <= other

Test whether every element in the set is inother.

set < other

Test whether the set is a proper subset ofother, that is,set<=otherandset!=other.

issuperset(other)¶

set >= other

Test whether every element inother is in the set.

set > other

Test whether the set is a proper superset ofother, that is,set>=otherandset!=other.

union(*others)¶

set | other | ...

Return a new set with elements from the set and all others.

Changed in version 2.6:Accepts multiple input iterables.

intersection(*others)¶

set & other & ...

Return a new set with elements common to the set and all others.

Changed in version 2.6:Accepts multiple input iterables.

difference(*others)¶

set - other - ...

Return a new set with elements in the set that are not in the others.

Changed in version 2.6:Accepts multiple input iterables.

symmetric_difference(other)¶

set ^ other

Return a new set with elements in either the set orother but not both.

copy()¶

Return a shallow copy of the set.

Note, the non-operator versions ofunion(),intersection(),difference(), andsymmetric_difference(),issubset(), andissuperset() methods will accept any iterable as an argument. Incontrast, their operator based counterparts require their arguments to besets. This precludes error-prone constructions likeset('abc')&'cbs'in favor of the more readableset('abc').intersection('cbs').

Bothset andfrozenset support set to set comparisons. Twosets are equal if and only if every element of each set is contained in theother (each is a subset of the other). A set is less than another set if andonly if the first set is a proper subset of the second set (is a subset, butis not equal). A set is greater than another set if and only if the first setis a proper superset of the second set (is a superset, but is not equal).

Instances ofset are compared to instances offrozensetbased on their members. For example,set('abc')==frozenset('abc')returnsTrue and so doesset('abc')inset([frozenset('abc')]).

The subset and equality comparisons do not generalize to a total orderingfunction. For example, any two non-empty disjoint sets are not equal and are notsubsets of each other, soall of the following returnFalse:a<b,a==b, ora>b. Accordingly, sets do not implement the__cmp__()method.

Since sets only define partial ordering (subset relationships), the output ofthelist.sort() method is undefined for lists of sets.

Set elements, like dictionary keys, must behashable.

Binary operations that mixset instances withfrozensetreturn the type of the first operand. For example:frozenset('ab')|set('bc') returns an instance offrozenset.

The following table lists operations available forset that do notapply to immutable instances offrozenset:

update(*others)¶

set |= other | ...

Update the set, adding elements from all others.

Changed in version 2.6:Accepts multiple input iterables.

intersection_update(*others)¶

set &= other & ...

Update the set, keeping only elements found in it and all others.

Changed in version 2.6:Accepts multiple input iterables.

difference_update(*others)¶

set -= other | ...

Update the set, removing elements found in others.

Changed in version 2.6:Accepts multiple input iterables.

symmetric_difference_update(other)¶

set ^= other

Update the set, keeping only elements found in either set, but not in both.

add(elem)¶

Add elementelem to the set.

remove(elem)¶

Remove elementelem from the set. RaisesKeyError ifelem isnot contained in the set.

discard(elem)¶

Remove elementelem from the set if it is present.

pop()¶

Remove and return an arbitrary element from the set. RaisesKeyError if the set is empty.

clear()¶

Remove all elements from the set.

Note, the non-operator versions of theupdate(),intersection_update(),difference_update(), andsymmetric_difference_update() methods will accept any iterable as anargument.

Note, theelem argument to the__contains__(),remove(), anddiscard() methods may be a set. To support searching for an equivalentfrozenset, a temporary one is created fromelem.

5.8.Mapping Types —dict¶

Amapping object mapshashable values to arbitrary objects.Mappings are mutable objects. There is currently only one standard mappingtype, thedictionary. (For other containers see the built inlist,set, andtuple classes, and thecollections module.)

A dictionary’s keys arealmost arbitrary values. Values that are nothashable, that is, values containing lists, dictionaries or othermutable types (that are compared by value rather than by object identity) maynot be used as keys. Numeric types used for keys obey the normal rules fornumeric comparison: if two numbers compare equal (such as1 and1.0)then they can be used interchangeably to index the same dictionary entry. (Notehowever, that since computers store floating-point numbers as approximations itis usually unwise to use them as dictionary keys.)

Dictionaries can be created by placing a comma-separated list ofkey:valuepairs within braces, for example:{'jack':4098,'sjoerd':4127} or{4098:'jack',4127:'sjoerd'}, or by thedict constructor.

classdict(**kwarg)¶

classdict(mapping,**kwarg)

classdict(iterable,**kwarg)

Return a new dictionary initialized from an optional positional argumentand a possibly empty set of keyword arguments.

If no positional argument is given, an empty dictionary is created.If a positional argument is given and it is a mapping object, a dictionaryis created with the same key-value pairs as the mapping object. Otherwise,the positional argument must be aniterable object. Each item inthe iterable must itself be an iterable with exactly two objects. Thefirst object of each item becomes a key in the new dictionary, and thesecond object the corresponding value. If a key occurs more than once, thelast value for that key becomes the corresponding value in the newdictionary.

If keyword arguments are given, the keyword arguments and their values areadded to the dictionary created from the positional argument. If a keybeing added is already present, the value from the keyword argumentreplaces the value from the positional argument.

To illustrate, the following examples all return a dictionary equal to{"one":1,"two":2,"three":3}:

>>>a=dict(one=1,two=2,three=3)>>>b={'one':1,'two':2,'three':3}>>>c=dict(zip(['one','two','three'],[1,2,3]))>>>d=dict([('two',2),('one',1),('three',3)])>>>e=dict({'three':3,'one':1,'two':2})>>>a==b==c==d==eTrue

Providing keyword arguments as in the first example only works for keys thatare valid Python identifiers. Otherwise, any valid keys can be used.

New in version 2.2.

Changed in version 2.3:Support for building a dictionary from keyword arguments added.

These are the operations that dictionaries support (and therefore, custommapping types should support too):

len(d)

Return the number of items in the dictionaryd.

d[key]

Return the item ofd with keykey. Raises aKeyError ifkeyis not in the map.

If a subclass of dict defines a method__missing__() andkeyis not present, thed[key] operation calls that method with the keykeyas argument. Thed[key] operation then returns or raises whatever isreturned or raised by the__missing__(key) call.No other operations or methods invoke__missing__(). If__missing__() is not defined,KeyError is raised.__missing__() must be a method; it cannot be an instance variable:

>>>classCounter(dict):...def__missing__(self,key):...return0>>>c=Counter()>>>c['red']0>>>c['red']+=1>>>c['red']1

The example above shows part of the implementation ofcollections.Counter. A different__missing__ method is usedbycollections.defaultdict.

New in version 2.5:Recognition of __missing__ methods of dict subclasses.

d[key] = value

Setd[key] tovalue.

del d[key]

Removed[key] fromd. Raises aKeyError ifkey is not in themap.

key in d

ReturnTrue ifd has a keykey, elseFalse.

New in version 2.2.

key not in d

Equivalent tonotkeyind.

New in version 2.2.

iter(d)

Return an iterator over the keys of the dictionary. This is a shortcutforiterkeys().

clear()¶

Remove all items from the dictionary.

copy()¶

Return a shallow copy of the dictionary.

fromkeys(seq[,value])¶

Create a new dictionary with keys fromseq and values set tovalue.

fromkeys() is a class method that returns a new dictionary.valuedefaults toNone.

New in version 2.3.

get(key[,default])¶

Return the value forkey ifkey is in the dictionary, elsedefault.Ifdefault is not given, it defaults toNone, so that this methodnever raises aKeyError.

has_key(key)¶

Test for the presence ofkey in the dictionary.has_key() isdeprecated in favor ofkeyind.

items()¶

Return a copy of the dictionary’s list of(key,value) pairs.

CPython implementation detail: Keys and values are listed in an arbitrary order which is non-random,varies across Python implementations, and depends on the dictionary’shistory of insertions and deletions.

Ifitems(),keys(),values(),iteritems(),iterkeys(), anditervalues() are called with no interveningmodifications to the dictionary, the lists will directly correspond. Thisallows the creation of(value,key) pairs usingzip():pairs=zip(d.values(),d.keys()). The same relationship holds for theiterkeys() anditervalues() methods:pairs=zip(d.itervalues(),d.iterkeys()) provides the same value forpairs. Another way to create the same list ispairs=[(v,k)for(k,v)ind.iteritems()].

iteritems()¶

Return an iterator over the dictionary’s(key,value) pairs. See thenote fordict.items().

Usingiteritems() while adding or deleting entries in the dictionarymay raise aRuntimeError or fail to iterate over all entries.

New in version 2.2.

iterkeys()¶

Return an iterator over the dictionary’s keys. See the note fordict.items().

Usingiterkeys() while adding or deleting entries in the dictionarymay raise aRuntimeError or fail to iterate over all entries.

New in version 2.2.

itervalues()¶

Return an iterator over the dictionary’s values. See the note fordict.items().

Usingitervalues() while adding or deleting entries in thedictionary may raise aRuntimeError or fail to iterate over allentries.

New in version 2.2.

keys()¶

Return a copy of the dictionary’s list of keys. See the note fordict.items().

pop(key[,default])¶

Ifkey is in the dictionary, remove it and return its value, else returndefault. Ifdefault is not given andkey is not in the dictionary,aKeyError is raised.

New in version 2.3.

popitem()¶

Remove and return an arbitrary(key,value) pair from the dictionary.

popitem() is useful to destructively iterate over a dictionary, asoften used in set algorithms. If the dictionary is empty, callingpopitem() raises aKeyError.

setdefault(key[,default])¶

Ifkey is in the dictionary, return its value. If not, insertkeywith a value ofdefault and returndefault.default defaults toNone.

update([other])¶

Update the dictionary with the key/value pairs fromother, overwritingexisting keys. ReturnNone.

update() accepts either another dictionary object or an iterable ofkey/value pairs (as tuples or other iterables of length two). If keywordarguments are specified, the dictionary is then updated with thosekey/value pairs:d.update(red=1,blue=2).

Changed in version 2.4:Allowed the argument to be an iterable of key/value pairs and allowedkeyword arguments.

values()¶

Return a copy of the dictionary’s list of values. See the note fordict.items().

viewitems()¶

Return a new view of the dictionary’s items ((key,value) pairs). Seebelow for documentation of view objects.

New in version 2.7.

viewkeys()¶

Return a new view of the dictionary’s keys. See below for documentation ofview objects.

New in version 2.7.

viewvalues()¶

Return a new view of the dictionary’s values. See below for documentation ofview objects.

New in version 2.7.

Dictionaries compare equal if and only if they have the same(key,value) pairs.

>>>dishes={'eggs':2,'sausage':1,'bacon':1,'spam':500}>>>keys=dishes.viewkeys()>>>values=dishes.viewvalues()>>># iteration>>>n=0>>>forvalinvalues:...n+=val>>>print(n)504>>># keys and values are iterated over in the same order>>>list(keys)['eggs', 'bacon', 'sausage', 'spam']>>>list(values)[2, 1, 1, 500]>>># view objects are dynamic and reflect dict changes>>>deldishes['eggs']>>>deldishes['sausage']>>>list(keys)['spam', 'bacon']>>># set operations>>>keys&{'eggs','bacon','salad'}{'bacon'}

5.9.File Objects¶

File objects are implemented using C’sstdio package and can becreated with the built-inopen() function. Fileobjects are also returned by some other built-in functions and methods,such asos.popen() andos.fdopen() and themakefile()method of socket objects. Temporary files can be created using thetempfile module, and high-level file operations such as copying,moving, and deleting files and directories can be achieved with theshutil module.

When a file operation fails for an I/O-related reason, the exceptionIOError is raised. This includes situations where the operation is notdefined for some reason, likeseek() on a tty device or writing a fileopened for reading.

Files have the following methods:

file.close()¶

Close the file. A closed file cannot be read or written any more. Any operationwhich requires that the file be open will raise aValueError after thefile has been closed. Callingclose() more than once is allowed.

As of Python 2.5, you can avoid having to call this method explicitly if you usethewith statement. For example, the following code willautomatically closef when thewith block is exited:

from__future__importwith_statement# This isn't required in Python 2.6withopen("hello.txt")asf:forlineinf:printline,

In older versions of Python, you would have needed to do this to get the sameeffect:

f=open("hello.txt")try:forlineinf:printline,finally:f.close()

Note

Not all “file-like” types in Python support use as a context manager for thewith statement. If your code is intended to work with any file-likeobject, you can use the functioncontextlib.closing() instead of usingthe object directly.

file.flush()¶

Flush the internal buffer, likestdio’sfflush(). This may be ano-op on some file-like objects.

Note

flush() does not necessarily write the file’s data to disk. Useflush() followed byos.fsync() to ensure this behavior.

file.fileno()¶

Return the integer “file descriptor” that is used by the underlyingimplementation to request I/O operations from the operating system. This can beuseful for other, lower level interfaces that use file descriptors, such as thefcntl module oros.read() and friends.

Note

File-like objects which do not have a real file descriptor shouldnot providethis method!

file.isatty()¶

ReturnTrue if the file is connected to a tty(-like) device, elseFalse.

Note

If a file-like object is not associated with a real file, this method shouldnot be implemented.

file.next()¶

A file object is its own iterator, for exampleiter(f) returnsf (unlessf is closed). When a file is used as an iterator, typically in afor loop (for example,forlineinf:printline.strip()), thenext() method is called repeatedly. This method returns the next inputline, or raisesStopIteration when EOF is hit when the file is open forreading (behavior is undefined when the file is open for writing). In order tomake afor loop the most efficient way of looping over the lines of afile (a very common operation), thenext() method uses a hidden read-aheadbuffer. As a consequence of using a read-ahead buffer, combiningnext()with other file methods (likereadline()) does not work right. However,usingseek() to reposition the file to an absolute position will flush theread-ahead buffer.

New in version 2.3.

file.read([size])¶

Read at mostsize bytes from the file (less if the read hits EOF beforeobtainingsize bytes). If thesize argument is negative or omitted, readall data until EOF is reached. The bytes are returned as a string object. Anempty string is returned when EOF is encountered immediately. (For certainfiles, like ttys, it makes sense to continue reading after an EOF is hit.) Notethat this method may call the underlying C functionfread() more thanonce in an effort to acquire as close tosize bytes as possible. Also notethat when in non-blocking mode, less data than was requested may bereturned, even if nosize parameter was given.

Note

This function is simply a wrapper for the underlyingfread() C function, and will behave the same in corner cases,such as whether the EOF value is cached.

file.readline([size])¶

Read one entire line from the file. A trailing newline character is kept inthe string (but may be absent when a file ends with an incomplete line).6If thesize argument is present and non-negative, it is a maximum bytecount (including the trailing newline) and an incomplete line may bereturned. Whensize is not 0, an empty string is returnedonly when EOFis encountered immediately.

Note

Unlikestdio’sfgets(), the returned string contains null characters('\0') if they occurred in the input.

file.readlines([sizehint])¶

Read until EOF usingreadline() and return a list containing the linesthus read. If the optionalsizehint argument is present, instead ofreading up to EOF, whole lines totalling approximatelysizehint bytes(possibly after rounding up to an internal buffer size) are read. Objectsimplementing a file-like interface may choose to ignoresizehint if itcannot be implemented, or cannot be implemented efficiently.

file.xreadlines()¶

This method returns the same thing asiter(f).

New in version 2.1.

Deprecated since version 2.3:Useforlineinfile instead.

file.seek(offset[,whence])¶

Set the file’s current position, likestdio’sfseek(). Thewhenceargument is optional and defaults toos.SEEK_SET or0 (absolute filepositioning); other values areos.SEEK_CUR or1 (seek relative to thecurrent position) andos.SEEK_END or2 (seek relative to the file’send). There is no return value.

For example,f.seek(2,os.SEEK_CUR) advances the position by two andf.seek(-3,os.SEEK_END) sets the position to the third to last.

Note that if the file is opened for appending(mode'a' or'a+'), anyseek() operations will be undone at thenext write. If the file is only opened for writing in append mode (mode'a'), this method is essentially a no-op, but it remains useful for filesopened in append mode with reading enabled (mode'a+'). If the file isopened in text mode (without'b'), only offsets returned bytell() arelegal. Use of other offsets causes undefined behavior.

Note that not all file objects are seekable.

Changed in version 2.6:Passing float values as offset has been deprecated.

file.tell()¶

Return the file’s current position, likestdio’sftell().

Note

On Windows,tell() can return illegal values (after anfgets())when reading files with Unix-style line-endings. Use binary mode ('rb') tocircumvent this problem.

file.truncate([size])¶

Truncate the file’s size. If the optionalsize argument is present, the fileis truncated to (at most) that size. The size defaults to the current position.The current file position is not changed. Note that if a specified size exceedsthe file’s current size, the result is platform-dependent: possibilitiesinclude that the file may remain unchanged, increase to the specified size as ifzero-filled, or increase to the specified size with undefined new content.Availability: Windows, many Unix variants.

file.write(str)¶

Write a string to the file. There is no return value. Due to buffering, thestring may not actually show up in the file until theflush() orclose() method is called.

file.writelines(sequence)¶

Write a sequence of strings to the file. The sequence can be any iterableobject producing strings, typically a list of strings. There is no return value.(The name is intended to matchreadlines();writelines() does notadd line separators.)

Files support the iterator protocol. Each iteration returns the same result asreadline(), and iteration ends when thereadline() method returnsan empty string.

File objects also offer a number of other interesting attributes. These are notrequired for file-like objects, but should be implemented if they make sense forthe particular object.

file.closed¶

bool indicating the current state of the file object. This is a read-onlyattribute; theclose() method changes the value. It may not be availableon all file-like objects.

file.encoding¶

The encoding that this file uses. When Unicode strings are written to a file,they will be converted to byte strings using this encoding. In addition, whenthe file is connected to a terminal, the attribute gives the encoding that theterminal is likely to use (that information might be incorrect if the user hasmisconfigured the terminal). The attribute is read-only and may not be presenton all file-like objects. It may also beNone, in which case the file usesthe system default encoding for converting Unicode strings.

New in version 2.3.

file.errors¶

The Unicode error handler used along with the encoding.

New in version 2.6.

file.mode¶

The I/O mode for the file. If the file was created using theopen()built-in function, this will be the value of themode parameter. This is aread-only attribute and may not be present on all file-like objects.

file.name¶

If the file object was created usingopen(), the name of the file.Otherwise, some string that indicates the source of the file object, of theform<...>. This is a read-only attribute and may not be present on allfile-like objects.

file.newlines¶

If Python was built withuniversal newlines enabled (the default) thisread-only attribute exists, and for files opened in universal newline readmode it keeps track of the types of newlines encountered while reading thefile. The values it can take are'\r','\n','\r\n',None(unknown, no newlines read yet) or a tuple containing all the newline typesseen, to indicate that multiple newline conventions were encountered. Forfiles not opened in universal newlines read mode the value of this attributewill beNone.

file.softspace¶

Boolean that indicates whether a space character needs to be printed beforeanother value when using theprint statement. Classes that are tryingto simulate a file object should also have a writablesoftspaceattribute, which should be initialized to zero. This will be automatic for mostclasses implemented in Python (care may be needed for objects that overrideattribute access); types implemented in C will have to provide a writablesoftspace attribute.

Note

This attribute is not used to control theprint statement, but toallow the implementation ofprint to keep track of its internalstate.

5.10.memoryview type¶

memoryview objects allow Python code to access the internal dataof an object that supports the buffer protocol without copying. Memoryis generally interpreted as simple bytes.

classmemoryview(obj)¶

Create amemoryview that referencesobj.obj must support thebuffer protocol. Built-in objects that support the buffer protocol includestr andbytearray (but notunicode).

Amemoryview has the notion of anelement, which is theatomic memory unit handled by the originating objectobj. For manysimple types such asstr andbytearray, an elementis a single byte, but other third-party types may expose larger elements.

len(view) returns the total number of elements in the memoryview,view. Theitemsize attribute will give you thenumber of bytes in a single element.

Amemoryview supports slicing to expose its data. Taking a singleindex will return a single element as astr object. Fullslicing will result in a subview:

>>>v=memoryview('abcefg')>>>v[1]'b'>>>v[-1]'g'>>>v[1:4]<memory at 0x77ab28>>>>v[1:4].tobytes()'bce'

If the object the memoryview is over supports changing its data, thememoryview supports slice assignment:

>>>data=bytearray('abcefg')>>>v=memoryview(data)>>>v.readonlyFalse>>>v[0]='z'>>>databytearray(b'zbcefg')>>>v[1:4]='123'>>>databytearray(b'z123fg')>>>v[2]='spam'Traceback (most recent call last):  File"<stdin>", line1, in<module>ValueError:cannot modify size of memoryview object

Notice how the size of the memoryview object cannot be changed.

memoryview has two methods:

tobytes()¶

Return the data in the buffer as a bytestring (an object of classstr).

>>>m=memoryview("abc")>>>m.tobytes()'abc'

tolist()¶

Return the data in the buffer as a list of integers.

>>>memoryview("abc").tolist()[97, 98, 99]

There are also several readonly attributes available:

format¶

A string containing the format (instruct module style) for eachelement in the view. This defaults to'B', a simple bytestring.

itemsize¶

The size in bytes of each element of the memoryview.

shape¶

A tuple of integers the length ofndim giving the shape of thememory as an N-dimensional array.

ndim¶

An integer indicating how many dimensions of a multi-dimensional array thememory represents.

strides¶

A tuple of integers the length ofndim giving the size in bytes toaccess each element for each dimension of the array.

readonly¶

A bool indicating whether the memory is read only.

5.11.Context Manager Types¶

Python’swith statement supports the concept of a runtime contextdefined by a context manager. This is implemented using two separate methodsthat allow user-defined classes to define a runtime context that is enteredbefore the statement body is executed and exited when the statement ends.

Thecontext management protocol consists of a pair of methods that needto be provided for a context manager object to define a runtime context:

contextmanager.__enter__()¶

Enter the runtime context and return either this object or another objectrelated to the runtime context. The value returned by this method is bound tothe identifier in theas clause ofwith statements usingthis context manager.

An example of a context manager that returns itself is a file object. Fileobjects return themselves from __enter__() to allowopen() to be used asthe context expression in awith statement.

An example of a context manager that returns a related object is the onereturned bydecimal.localcontext(). These managers set the activedecimal context to a copy of the original decimal context and then return thecopy. This allows changes to be made to the current decimal context in the bodyof thewith statement without affecting code outside thewith statement.

contextmanager.__exit__(exc_type,exc_val,exc_tb)¶

Exit the runtime context and return a Boolean flag indicating if any exceptionthat occurred should be suppressed. If an exception occurred while executing thebody of thewith statement, the arguments contain the exception type,value and traceback information. Otherwise, all three arguments areNone.

Returning a true value from this method will cause thewith statementto suppress the exception and continue execution with the statement immediatelyfollowing thewith statement. Otherwise the exception continuespropagating after this method has finished executing. Exceptions that occurduring execution of this method will replace any exception that occurred in thebody of thewith statement.

The exception passed in should never be reraised explicitly - instead, thismethod should return a false value to indicate that the method completedsuccessfully and does not want to suppress the raised exception. This allowscontext management code (such ascontextlib.nested) to easily detect whetheror not an__exit__() method has actually failed.

Python defines several context managers to support easy thread synchronisation,prompt closure of files or other objects, and simpler manipulation of the activedecimal arithmetic context. The specific types are not treated specially beyondtheir implementation of the context management protocol. See thecontextlib module for some examples.

Python’sgenerators and thecontextlib.contextmanagerdecoratorprovide a convenient way to implement these protocols. If a generator function isdecorated with thecontextlib.contextmanager decorator, it will return acontext manager implementing the necessary__enter__() and__exit__() methods, rather than the iterator produced by an undecoratedgenerator function.

Note that there is no specific slot for any of these methods in the typestructure for Python objects in the Python/C API. Extension types wanting todefine these methods must provide them as a normal Python accessible method.Compared to the overhead of setting up the runtime context, the overhead of asingle class dictionary lookup is negligible.

5.12.Other Built-in Types¶

The interpreter supports several other kinds of objects. Most of these supportonly one or two operations.

>>>classC:...defmethod(self):...pass...>>>c=C()>>>c.method.whoami='my name is method'# can't set on the methodTraceback (most recent call last):  File"<stdin>", line1, in<module>AttributeError:'instancemethod' object has no attribute 'whoami'>>>c.method.im_func.whoami='my name is method'>>>c.method.whoami'my name is method'

5.13.Special Attributes¶

The implementation adds a few special read-only attributes to several objecttypes, where they are relevant. Some of these are not reported by thedir() built-in function.

object.__dict__¶

A dictionary or other mapping object used to store an object’s (writable)attributes.

object.__methods__¶

Deprecated since version 2.2:Use the built-in functiondir() to get a list of an object’s attributes.This attribute is no longer available.

object.__members__¶

Deprecated since version 2.2:Use the built-in functiondir() to get a list of an object’s attributes.This attribute is no longer available.

instance.__class__¶

The class to which a class instance belongs.

class.__bases__¶

The tuple of base classes of a class object.

definition.__name__¶

The name of the class, type, function, method, descriptor, orgenerator instance.

The following attributes are only supported bynew-style classes.

class.__mro__¶

This attribute is a tuple of classes that are considered when looking forbase classes during method resolution.

class.mro()¶

This method can be overridden by a metaclass to customize the methodresolution order for its instances. It is called at class instantiation, andits result is stored in__mro__.

class.__subclasses__()¶

Each new-style class keeps a list of weak references to its immediatesubclasses. This method returns a list of all those references still alive.Example:

>>>int.__subclasses__()[<type 'bool'>]

Footnotes

1

Additional information on these special methods may be found in the PythonReference Manual (Basic customization).

2

As a consequence, the list[1,2] is considered equal to[1.0,2.0], andsimilarly for tuples.

3

They must have since the parser can’t tell the type of the operands.

4(1,2,3,4)

Cased characters are those with general category property being one of“Lu” (Letter, uppercase), “Ll” (Letter, lowercase), or “Lt” (Letter, titlecase).

5

To format only a tuple you should therefore provide a singleton tuple whose onlyelement is the tuple to be formatted.

6

The advantage of leaving the newline on is that returning an empty string isthen an unambiguous EOF indication. It is also possible (in cases where itmight matter, for example, if you want to make an exact copy of a file whilescanning its lines) to tell whether the last line of a file ended in a newlineor not (yes this happens!).