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.

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

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 isFalse.
2. This is a short-circuit operator, so it only evaluates the secondargument if the first one isTrue.
3. not has a lower priority than non-Boolean operators, sonota==b isinterpreted asnot(a==b), anda==notb is a syntax error.

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.

Instances of a class normally compare as non-equal unless the class defines the__cmp__() method. Refer toBasic customization) for information on theuse of this method to effect object comparisons.

Implementation note: Objects of different types except numbers are orderedby their type names; objects of the same types that don’t support propercomparison are ordered by their address.

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

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 implemented usingdouble in C. All bets on their precisionare off unless you happen to know the machine you are working with.

Complex numbers have a real and imaginary part, which are each implemented usingdouble in C. To extract these parts from a complex numberz, usez.real andz.imag.

Numbers are created by numeric literals or as the result of built-in functionsand operators. Unadorned integer literals (including hex and octal numbers)yield plain integers unless the value they denote is too large to be representedas a plain integer, in which case they yield a long integer. Integer literalswith an'L' or'l' suffix yield long integers ('L' is preferredbecause1l looks too much like eleven!). Numeric literals containing adecimal point or an exponent sign yield floating point numbers. Appending'j' or'J' to a numeric literal yields a complex number with a zero realpart. A complex numeric literal is the sum of a real and an imaginary part.

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 builtin 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 floating point to (long or plain) integer may round ortruncate as in C; see functionsmath.floor() andmath.ceil() forwell-defined conversions.

   Deprecated since version 2.6:Instead, convert floats to long explicitly withtrunc().

3. SeeBuilt-in Functions for a full description.

4. Complex floor division operator, modulo operator, anddivmod().

   Deprecated since version 2.3:Instead convert to float usingabs() 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'

Iterator Types¶

New in version 2.2.

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

Python’sgenerators provide a convenient way to implement the iteratorprotocol. If a container object’s__iter__() method is implemented as agenerator, it will automatically return an iterator object (technically, agenerator object) supplying the__iter__() andnext() methods.

Sequence Types —str,unicode,list,tuple,buffer,xrange¶

There are six sequence types: strings, Unicode strings, lists, tuples, buffers,and xrange objects.(For other containers see the built indict,list,set, andtuple classes, and thecollectionsmodule.)

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

Buffer objects are not directly supported by Python syntax, but can be createdby calling the builtin 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(operations in the same box have the same priority). In the table,s andtare 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 also that the copies are shallow;nested structures are not copied. This often haunts new 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 (pointers 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]]

3. Ifi orj is negative, the index is relative to the end of the string: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). Ifi orj is greater thanlen(s), uselen(s). 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. Ifs andt are both strings, some Python implementations such as CPython canusually perform an in-place optimization for assignments of the forms=s+tors+=t. When applicable, this optimization makes quadratic run-time muchless likely. This optimization is both version and implementation dependent.For performance sensitive code, it is preferable to use thestr.join()method which assures consistent linear concatenation performance across versionsand implementations.

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

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

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

New in version 2.4.

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 builtin set types,set andfrozenset.Theset type is mutable — the contents can be changed using methodslikeadd() andremove(). Since it is mutable, it has no hash valueand cannot be used as either a dictionary key or as an element of another set.Thefrozenset type is immutable andhashable — its contents cannot bealtered after it is created; it can therefore be used as a dictionary key or asan element of another set.

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 be hashable. To represent sets ofsets, the inner sets must befrozenset objects. Ifiterable isnot specified, a new empty set is returned.

Instances ofset andfrozenset provide the followingoperations:

len(s)

Return the cardinality of sets.

x in s

Testx for membership ins.

x not in s

Testx for non-membership ins.

isdisjoint(other)¶

Return True 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 true 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 true superset ofother, that is,set>=otherandset!=other.

union(other,...)¶

set | other | ...

Return a new set with elements from both sets.

Changed in version 2.6:Accepts multiple input iterables.

intersection(other,...)¶

set & other & ...

Return a new set with elements common to both sets.

Changed in version 2.6:Accepts multiple input iterables.

difference(other,...)¶

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 new set with a shallow copy ofs.

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 complete orderingfunction. For example, any two 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(other,...)¶

set |= other | ...

Update the set, adding elements fromother.

Changed in version 2.6:Accepts multiple input iterables.

intersection_update(other,...)¶

set &= other & ...

Update the set, keeping only elements found in it andother.

Changed in version 2.6:Accepts multiple input iterables.

difference_update(other,...)¶

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, theelem set is temporarily mutated during the search and thenrestored. During the search, theelem set should not be read or mutatedsince it does not have a meaningful value.

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([arg])¶

Return a new dictionary initialized from an optional positional argument or froma set of keyword arguments. If no arguments are given, return a new emptydictionary. If the positional argumentarg is a mapping object, return adictionary mapping the same keys to the same values as does the mapping object.Otherwise the positional argument must be a sequence, a container that supportsiteration, or an iterator object. The elements of the argument must each alsobe of one of those kinds, and each must in turn contain exactly two objects.The first is used as a key in the new dictionary, and the second as the key’svalue. If a given key is seen more than once, the last value associated with itis retained in the new dictionary.

If keyword arguments are given, the keywords themselves with their associatedvalues are added as items to the dictionary. If a key is specified both in thepositional argument and as a keyword argument, the value associated with thekeyword is retained in the dictionary. For example, these all return adictionary equal to{"one":2,"two":3}:

• dict(one=2,two=3)
• dict({'one':2,'two':3})
• dict(zip(('one','two'),(2,3)))
• dict([['two',3],['one',2]])

The first example only works for keys that are valid Pythonidentifiers; the others work with any valid keys.

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.

New in version 2.5:If a subclass of dict defines a method__missing__(), if the keykey is not present, thed[key] operation calls that method withthe keykey as argument. Thed[key] operation then returns orraises whatever is returned or raised by the__missing__(key) callif the key is not present. No other operations or methods invoke__missing__(). If__missing__() is not defined,KeyError is raised.__missing__() must be a method; itcannot be an instance variable. For an example, seecollections.defaultdict.

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.

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

dict.has_key(key) is equivalent tokeyind, but deprecated.

items()¶

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

Note

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 intervening modifications to thedictionary, the lists will directly correspond. This allows thecreation 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().

New in version 2.2.

iterkeys()¶

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

New in version 2.2.

itervalues()¶

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

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 a tuple or other iterable of length two). If keywordarguments are specified, the dictionary is then is 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().

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:printlinefinally: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.

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), 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 in thestring (but may be absent when a file ends with an incomplete line).[6] Ifthesize argument is present and non-negative, it is a maximum byte count(including the trailing newline) and an incomplete line may be returned. Anempty string is returnedonly when EOF is 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 asfile.readline(), 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 with the--with-universal-newlines option toconfigure (the default) this read-only attribute exists, and forfiles opened in universal newline read mode it keeps track of the types ofnewlines encountered while reading the file. The values it can take are'\r','\n','\r\n',None (unknown, no newlines read yet) or atuple containing all the newline types seen, to indicate that multiple newlineconventions were encountered. For files not opened in universal newline readmode the value of this attribute will 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.

Context Manager Types¶

New in version 2.5.

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.contextfactorydecoratorprovide a convenient way to implement these protocols. If a generator function isdecorated with thecontextlib.contextfactory 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.

Other Built-in Types¶

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

classC:defmethod(self):passc=C()c.method.im_func.whoami='my name is c'

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. If there are no base classes, thiswill be an empty tuple.

class.__name__¶

The name of the class or type.

Footnotes