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,0.0,0j.

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

• any empty mapping, for example,{}.

• instances of user-defined classes, if the class defines a__bool__() 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¶

There are eight comparison operations in Python. 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:

Objects of different types, except different numeric types, never compare equal.Furthermore, some types (for example, file objects) support only a degeneratenotion of comparison where any two objects of that type are unequal. The<,<=,> and>= operators will raise aTypeError exception whenany operand is a complex number, the objects are of different types that cannotbe compared, or other cases where there is no defined ordering.

Non-identical instances of a class normally compare as non-equal unless theclass defines the__eq__() 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 enough of themethods__lt__(),__le__(),__gt__(), and__ge__() (ingeneral,__lt__() and__eq__() are sufficient, if you want theconventional meanings of the comparison operators).

The behavior of theis andisnot operators cannot becustomized; also they can be applied to any two objects and never raise anexception.

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

Numeric Types —int,float,complex¶

There are three distinct numeric types:integers,floatingpoint numbers, andcomplex numbers. In addition, Booleans are asubtype of integers. Integers have unlimited precision. Floating pointnumbers are implemented usingdouble in C—all bets on theirprecision are off unless you happen to know the machine you are workingwith. Complex numbers have a real and imaginary part, which are eachimplemented usingdouble in C. To extract these parts from acomplex numberz, usez.real andz.imag. (The standard libraryincludes additional numeric types,fractions that hold rationals,anddecimal that hold floating-point numbers with user-definableprecision.)

Numbers are created by numeric literals or as the result of built-in functionsand operators. Unadorned integer literals (including hex, octal and binarynumbers) yield integers. Numeric literals containing a decimal point or anexponent sign yield floating point numbers. Appending'j' or'J' to anumeric literal yields an imaginary number (a complex number with a zero realpart) which you can add to an integer or float to get a complex number with realand 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 integer is narrower than floating point,which is narrower than complex. Comparisons between numbers of mixed type usethe same rule.[2] The constructorsint(),float(), andcomplex() can be used to produce numbers of a specific type.

All numeric types (except complex) support the following operations, sorted byascending priority (operations in the same box have the same priority; allnumeric operations have a higher priority than comparison operations):

Notes:

1. Also referred to as integer division. The resultant value is a wholeinteger, though the result’s type is not necessarily int. The result isalways rounded towards minus infinity:1//2 is0,(-1)//2 is-1,1//(-2) is-1, and(-1)//(-2) is0.

2. Not for complex numbers. Instead convert to floats usingabs() ifappropriate.

3. Conversion from floating point to integer may round or truncateas in C; see functionsfloor() andceil() in themath modulefor well-defined conversions.

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

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

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

For additional numeric operations see themath andcmathmodules.

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

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

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

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.

Once an iterator’s__next__() method raisesStopIteration, it mustcontinue to do so on subsequent calls. Implementations that do not obey thisproperty are deemed broken.

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__() and__next__() methods.

Sequence Types —str,bytes,bytearray,list,tuple,range¶

There are six sequence types: strings, byte sequences (bytes objects),byte arrays (bytearray objects), lists, tuples, and range objects. Forother containers see the built indict andset classes, andthecollections module.

Strings contain Unicode characters. Their literals are written in single ordouble quotes:'xyzzy',"frobozz". SeeString and Bytes literals for more aboutstring literals. In addition to the functionality described here, there arealso string-specific methods described in theString Methods section.

Bytes and bytearray objects contain single bytes – the former is immutablewhile the latter is a mutable sequence. Bytes objects can be constructed theconstructor,bytes(), and from literals; use ab prefix with normalstring syntax:b'xyzzy'. To construct byte arrays, use thebytearray() function.

Lists are constructed 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 tuple must havethe enclosing parentheses, such asa,b,c or(). A single item tuplemust have a trailing comma, such as(d,).

Objects of type range are created using therange() 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 lists arecompared lexicographically by comparing corresponding elements. This means thatto compare equal, every element must compare equal and the two sequences must beof the same type and have the same length. (For full details seeComparisons in the language reference.)

Notes:

1. Whens is a string object, thein andnotin operations act like asubstring test.

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

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.

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

a="abc"b=a.replace("a","f")

a=b"abc"b=a.replace(b"a",b"f")

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

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 the set and all others.

intersection(other,...)¶

set & other & ...

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

difference(other,...)¶

set - other - ...

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

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.

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.

intersection_update(other,...)¶

set &= other & ...

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

difference_update(other,...)¶

set -= other | ...

Update the set, removing elements found in others.

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 orfrom a set of keyword arguments. If no arguments are given, return a newempty dictionary. If the positional argumentarg is a mapping object,return a dictionary mapping the same keys to the same values as does themapping object. Otherwise the positional argument must be a sequence, acontainer that supports iteration, or an iterator object. The elements ofthe argument must each also be of one of those kinds, and each must in turncontain exactly two objects. The first is used as a key in the newdictionary, and the second as the key’s value. If a given key is seen morethan once, the last value associated with it is retained in the newdictionary.

If keyword arguments are given, the keywords themselves with their associatedvalues are added as items to the dictionary. If a key is specified both inthe positional argument and as a keyword argument, the value associated withthe keyword 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 Python identifiers; theothers work with any valid keys.

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 ifkey isnot in the map.

If a subclass of dict defines a method__missing__(), if the keykeyis 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 if the key is notpresent. 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. Foran 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.

key not in d

Equivalent tonotkeyind.

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.

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.

items()¶

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

keys()¶

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

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.

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

values()¶

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

>>>dishes={'eggs':2,'sausage':1,'bacon':1,'spam':500}>>>keys=dishes.keys()>>>values=dishes.values()>>># 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'}

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.

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__ import with_statement # This isn't required in Python 2.6with open("hello.txt") as f:    for line in f:        print(line)

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

f=open("hello.txt")try:forlineinf:print(line)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.

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:print(line)), the__next__() method is called repeatedly. This method returns the nextinput line, or raisesStopIteration when EOF is hit when the file is openfor reading (behavior is undefined when the file is open for writing). In orderto make afor loop the most efficient way of looping over the linesof a file (a very common operation), the__next__() method uses a hiddenread-ahead buffer. As a consequence of using a read-ahead buffer, combining__next__() with other file methods (likereadline()) does not workright. However, usingseek() to reposition the file to an absoluteposition will flush the read-ahead buffer.

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.

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

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. Due to buffering, the string may not actuallyshow up in the file until theflush() orclose() method iscalled.

The meaning of the return value is not defined for every file-like object.Some (mostly low-level) file-like objects may return the number of bytesactually written, others returnNone.

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

file.errors¶

The Unicode error handler used along with the encoding.

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.

memoryview Types¶

memoryviews allow Python code to access the internal data of an objectthat supports the buffer protocol without copying. Memory can be interpreted assimple bytes or complex data structures.

classmemoryview(obj)¶

Create amemoryview that referencesobj.obj must support thebuffer protocol. Builtin objects that support the buffer protocol includebytes andbytearray.

len(view) returns the total number of bytes in the memoryview,view.

Amemoryview supports slicing to expose its data. Taking a singleindex will return a single byte. Full slicing will result in a subview:

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

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

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

Notice how the size of the memoryview object can not be changed.

memoryview has two methods:

tobytes()¶

Return the data in the buffer as a bytestring.

tolist()¶

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

>>>memoryview(b'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 a 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.

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

class C:    def method(self):        passc = C()c.method.__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.

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