Bitwise Operations on Integer Types¶

Bitwise operations only make sense for integers. The result of bitwiseoperations is calculated as though carried out in two’s complement with aninfinite number of sign bits.

The priorities of the binary bitwise operations are all lower than the numericoperations and higher than the comparisons; the unary operation~ has thesame priority as the other unary numeric operations (+ and-).

This table lists the bitwise operations sorted in ascending priority:

Notes:

1. Negative shift counts are illegal and cause aValueError to be raised.

2. A left shift byn bits is equivalent to multiplication bypow(2,n).

3. A right shift byn bits is equivalent to floor division bypow(2,n).

4. Performing these calculations with at least one extra sign extension bit ina finite two’s complement representation (a working bit-width of1+max(x.bit_length(),y.bit_length()) or more) is sufficient to get thesame result as if there were an infinite number of sign bits.

Additional Methods on Integer Types¶

The int type implements thenumbers.Integralabstract baseclass. In addition, it provides a few more methods:

int.bit_length()¶

Return the number of bits necessary to represent an integer in binary,excluding the sign and leading zeros:

>>>n=-37>>>bin(n)'-0b100101'>>>n.bit_length()6

More precisely, ifx is nonzero, thenx.bit_length() is theunique positive integerk such that2**(k-1)<=abs(x)<2**k.Equivalently, whenabs(x) is small enough to have a correctlyrounded logarithm, thenk=1+int(log(abs(x),2)).Ifx is zero, thenx.bit_length() returns0.

Equivalent to:

defbit_length(self):s=bin(self)# binary representation:  bin(-37) --> '-0b100101's=s.lstrip('-0b')# remove leading zeros and minus signreturnlen(s)# len('100101') --> 6

Added in version 3.1.

int.bit_count()¶

Return the number of ones in the binary representation of the absolutevalue of the integer. This is also known as the population count.Example:

>>>n=19>>>bin(n)'0b10011'>>>n.bit_count()3>>>(-n).bit_count()3

Equivalent to:

defbit_count(self):returnbin(self).count("1")

Added in version 3.10.

int.to_bytes(length=1,byteorder='big',*,signed=False)¶

Return an array of bytes representing an integer.

>>>(1024).to_bytes(2,byteorder='big')b'\x04\x00'>>>(1024).to_bytes(10,byteorder='big')b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00'>>>(-1024).to_bytes(10,byteorder='big',signed=True)b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00'>>>x=1000>>>x.to_bytes((x.bit_length()+7)//8,byteorder='little')b'\xe8\x03'

The integer is represented usinglength bytes, and defaults to 1. AnOverflowError is raised if the integer is not representable withthe given number of bytes.

Thebyteorder argument determines the byte order used to represent theinteger, and defaults to"big". Ifbyteorder is"big", the most significant byte is at the beginning of the bytearray. Ifbyteorder is"little", the most significant byte is atthe end of the byte array.

Thesigned argument determines whether two’s complement is used torepresent the integer. Ifsigned isFalse and a negative integer isgiven, anOverflowError is raised. The default value forsignedisFalse.

The default values can be used to conveniently turn an integer into asingle byte object:

>>>(65).to_bytes()b'A'

However, when using the default arguments, don’t tryto convert a value greater than 255 or you’ll get anOverflowError.

Equivalent to:

defto_bytes(n,length=1,byteorder='big',signed=False):ifbyteorder=='little':order=range(length)elifbyteorder=='big':order=reversed(range(length))else:raiseValueError("byteorder must be either 'little' or 'big'")returnbytes((n>>i*8)&0xffforiinorder)

Added in version 3.2.

Changed in version 3.11:Added default argument values forlength andbyteorder.

classmethodint.from_bytes(bytes,byteorder='big',*,signed=False)¶

Return the integer represented by the given array of bytes.

>>>int.from_bytes(b'\x00\x10',byteorder='big')16>>>int.from_bytes(b'\x00\x10',byteorder='little')4096>>>int.from_bytes(b'\xfc\x00',byteorder='big',signed=True)-1024>>>int.from_bytes(b'\xfc\x00',byteorder='big',signed=False)64512>>>int.from_bytes([255,0,0],byteorder='big')16711680

The argumentbytes must either be abytes-like object or aniterable producing bytes.

Thebyteorder argument determines the byte order used to represent theinteger, and defaults to"big". Ifbyteorder is"big", the most significant byte is at the beginning of the bytearray. Ifbyteorder is"little", the most significant byte is atthe end of the byte array. To request the native byte order of the hostsystem, usesys.byteorder as the byte order value.

Thesigned argument indicates whether two’s complement is used torepresent the integer.

Equivalent to:

deffrom_bytes(bytes,byteorder='big',signed=False):ifbyteorder=='little':little_ordered=list(bytes)elifbyteorder=='big':little_ordered=list(reversed(bytes))else:raiseValueError("byteorder must be either 'little' or 'big'")n=sum(b<<i*8fori,binenumerate(little_ordered))ifsignedandlittle_orderedand(little_ordered[-1]&0x80):n-=1<<8*len(little_ordered)returnn

Added in version 3.2.

Changed in version 3.11:Added default argument value forbyteorder.

int.as_integer_ratio()¶

Return a pair of integers whose ratio is equal to the originalinteger and has a positive denominator. The integer ratio of integers(whole numbers) is always the integer as the numerator and1 as thedenominator.

Added in version 3.8.

int.is_integer()¶

ReturnsTrue. Exists for duck type compatibility withfloat.is_integer().

Added in version 3.12.

Additional Methods on Float¶

The float type implements thenumbers.Realabstract baseclass. float also has the following additional methods.

float.as_integer_ratio()¶

Return a pair of integers whose ratio is exactly equal to theoriginal float. The ratio is in lowest terms and has a positive denominator. RaisesOverflowError on infinities and aValueError onNaNs.

float.is_integer()¶

ReturnTrue if the float instance is finite with integralvalue, andFalse otherwise:

>>>(-2.0).is_integer()True>>>(3.2).is_integer()False

Two methods support conversion toand from hexadecimal strings. Since Python’s floats are storedinternally as binary numbers, converting a float to or from adecimal string usually involves a small rounding error. Incontrast, hexadecimal strings allow exact representation andspecification of floating-point numbers. This can be useful whendebugging, and in numerical work.

float.hex()¶

Return a representation of a floating-point number as a hexadecimalstring. For finite floating-point numbers, this representationwill always include a leading0x and a trailingp andexponent.

classmethodfloat.fromhex(s)¶

Class method to return the float represented by a hexadecimalstrings. The strings may have leading and trailingwhitespace.

Note thatfloat.hex() is an instance method, whilefloat.fromhex() is a class method.

A hexadecimal string takes the form:

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

where the optionalsign may by either+ or-,integerandfraction are strings of hexadecimal digits, andexponentis a decimal integer with an optional leading sign. Case is notsignificant, and there must be at least one hexadecimal digit ineither the integer or the fraction. This syntax is similar to thesyntax specified in section 6.4.4.2 of the C99 standard, and also tothe syntax used in Java 1.5 onwards. In particular, the output offloat.hex() is usable as a hexadecimal floating-point literal inC or Java code, and hexadecimal strings produced by C’s%a formatcharacter or Java’sDouble.toHexString are accepted byfloat.fromhex().

Note that the exponent is written in decimal rather than hexadecimal,and that it gives the power of 2 by which to multiply the coefficient.For example, the hexadecimal string0x3.a7p10 represents thefloating-point number(3+10./16+7./16**2)*2.0**10, or3740.0:

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

Applying the reverse conversion to3740.0 gives a differenthexadecimal string representing the same number:

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

Hashing of numeric types¶

For numbersx andy, possibly of different types, it’s a requirementthathash(x)==hash(y) wheneverx==y (see the__hash__()method documentation for more details). For ease of implementation andefficiency across a variety of numeric types (includingint,float,decimal.Decimal andfractions.Fraction)Python’s hash for numeric types is based on a single mathematical functionthat’s defined for any rational number, and hence applies to all instances ofint andfractions.Fraction, and all finite instances offloat anddecimal.Decimal. Essentially, this function isgiven by reduction moduloP for a fixed primeP. The value ofP ismade available to Python as themodulus attribute ofsys.hash_info.

Here are the rules in detail:

• Ifx=m/n is a nonnegative rational number andn is not divisiblebyP, definehash(x) asm*invmod(n,P)%P, whereinvmod(n,P) gives the inverse ofn moduloP.

• Ifx=m/n is a nonnegative rational number andn isdivisible byP (butm is not) thenn has no inversemoduloP and the rule above doesn’t apply; in this case definehash(x) to be the constant valuesys.hash_info.inf.

• Ifx=m/n is a negative rational number definehash(x)as-hash(-x). If the resulting hash is-1, replace it with-2.

• The particular valuessys.hash_info.inf and-sys.hash_info.infare used as hash values for positiveinfinity or negative infinity (respectively).

• For acomplex numberz, the hash values of the realand imaginary parts are combined by computinghash(z.real)+sys.hash_info.imag*hash(z.imag), reduced modulo2**sys.hash_info.width so that it lies inrange(-2**(sys.hash_info.width-1),2**(sys.hash_info.width-1)). Again, if the result is-1, it’s replaced with-2.

To clarify the above rules, here’s some example Python code,equivalent to the built-in hash, for computing the hash of a rationalnumber,float, orcomplex:

importsys,mathdefhash_fraction(m,n):"""Compute the hash of a rational number m / n.    Assumes m and n are integers, with n positive.    Equivalent to hash(fractions.Fraction(m, n)).    """P=sys.hash_info.modulus# Remove common factors of P.  (Unnecessary if m and n already coprime.)whilem%P==n%P==0:m,n=m//P,n//Pifn%P==0:hash_value=sys.hash_info.infelse:# Fermat's Little Theorem: pow(n, P-1, P) is 1, so# pow(n, P-2, P) gives the inverse of n modulo P.hash_value=(abs(m)%P)*pow(n,P-2,P)%Pifm<0:hash_value=-hash_valueifhash_value==-1:hash_value=-2returnhash_valuedefhash_float(x):"""Compute the hash of a float x."""ifmath.isnan(x):returnobject.__hash__(x)elifmath.isinf(x):returnsys.hash_info.infifx>0else-sys.hash_info.infelse:returnhash_fraction(*x.as_integer_ratio())defhash_complex(z):"""Compute the hash of a complex number z."""hash_value=hash_float(z.real)+sys.hash_info.imag*hash_float(z.imag)# do a signed reduction modulo 2**sys.hash_info.widthM=2**(sys.hash_info.width-1)hash_value=(hash_value&(M-1))-(hash_value&M)ifhash_value==-1:hash_value=-2returnhash_value

Generator Types¶

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.More information about generators can be found inthe documentation forthe yield expression.

Common Sequence Operations¶

The operations in the following table are supported by most sequence types,both mutable and immutable. Thecollections.abc.Sequence ABC isprovided to make it easier to correctly implement these operations oncustom sequence types.

This table lists the sequence operations sorted in ascending priority. In thetable,s andt are sequences of the same type,n,i,j andk areintegers andx is an arbitrary object that meets any type and valuerestrictions imposed bys.

Thein andnotin operations have the same priorities as thecomparison operations. The+ (concatenation) and* (repetition)operations have the same priority as the corresponding numeric operations.[3]

Sequences of the same type also support comparisons. In particular, tuplesand lists are compared lexicographically by comparing corresponding elements.This means that to compare equal, every element must compare equal and thetwo sequences must be of the same type and have the same length. (For fulldetails seeComparisons in the language reference.)

Forward and reversed iterators over mutable sequences access values using anindex. That index will continue to march forward (or backward) even if theunderlying sequence is mutated. The iterator terminates only when anIndexError or aStopIteration is encountered (or when the indexdrops below zero).

Notes:

1. While thein andnotin operations are used only for simplecontainment testing in the general case, some specialised sequences(such asstr,bytes andbytearray) also usethem for subsequence testing:

   >>>"gg"in"eggs"True

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 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). 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. Concatenating immutable sequences always results in a new object. Thismeans that building up a sequence by repeated concatenation will have aquadratic runtime cost in the total sequence length. To get a linearruntime cost, you must switch to one of the alternatives below:

   • if concatenatingstr objects, you can build a list and usestr.join() at the end or else write to anio.StringIOinstance and retrieve its value when complete

   • if concatenatingbytes objects, you can similarly usebytes.join() orio.BytesIO, or you can do in-placeconcatenation with abytearray object.bytearrayobjects are mutable and have an efficient overallocation mechanism

   • if concatenatingtuple objects, extend alist instead

   • for other types, investigate the relevant class documentation

7. Some sequence types (such asrange) only support item sequencesthat follow specific patterns, and hence don’t support sequenceconcatenation or repetition.

8. index raisesValueError whenx is not found ins.Not all implementations support passing the additional argumentsi andj.These arguments allow efficient searching of subsections of the sequence. Passingthe extra arguments is roughly equivalent to usings[i:j].index(x), onlywithout copying any data and with the returned index being relative tothe start of the sequence rather than the start of the slice.

Immutable Sequence Types¶

The only operation that immutable sequence types generally implement that isnot also implemented by mutable sequence types is support for thehash()built-in.

This support allows immutable sequences, such astuple instances, tobe used asdict keys and stored inset andfrozensetinstances.

Attempting to hash an immutable sequence that contains unhashable values willresult inTypeError.

Mutable Sequence Types¶

The operations in the following table are defined on mutable sequence types.Thecollections.abc.MutableSequence ABC is provided to make iteasier to correctly implement these operations on custom sequence types.

In the tables is an instance of a mutable sequence type,t is anyiterable object andx is an arbitrary object that meets any typeand value restrictions imposed bys (for example,bytearray onlyaccepts integers that meet the value restriction0<=x<=255).

Notes:

1. Ifk is not equal to1,t must have the same length as the slice it is replacing.

2. The optional argumenti defaults to-1, so that by default the lastitem is removed and returned.

3. remove() raisesValueError whenx is not found ins.

4. Thereverse() method modifies the sequence in place for economy ofspace when reversing a large sequence. To remind users that it operates byside effect, it does not return the reversed sequence.

5. clear() andcopy() are included for consistency with theinterfaces of mutable containers that don’t support slicing operations(such asdict andset).copy() is not part of thecollections.abc.MutableSequence ABC, but most concretemutable sequence classes provide it.

   Added in version 3.3:clear() andcopy() methods.

6. The valuen is an integer, or an object implementing__index__(). Zero and negative values ofn clearthe sequence. Items in the sequence are not copied; they are referencedmultiple times, as explained fors*n underCommon Sequence Operations.

Lists¶

Lists are mutable sequences, typically used to store collections ofhomogeneous items (where the precise degree of similarity will vary byapplication).

classlist([iterable])¶

Lists may be constructed in several ways:

• Using a pair of square brackets to denote the empty list:[]

• Using square brackets, separating items with commas:[a],[a,b,c]

• Using a list comprehension:[xforxiniterable]

• Using the type constructor:list() orlist(iterable)

The constructor builds a list whose items are the same and in the sameorder asiterable’s items.iterable may be either a sequence, acontainer that supports iteration, or an iterator object. Ifiterableis already a list, a copy is made and returned, similar toiterable[:].For example,list('abc') returns['a','b','c'] andlist((1,2,3)) returns[1,2,3].If no argument is given, the constructor creates a new empty list,[].

Many other operations also produce lists, including thesorted()built-in.

Lists implement all of thecommon andmutable sequence operations. Lists also provide thefollowing additional method:

sort(*,key=None,reverse=False)¶

This method sorts the list in place, using only< comparisonsbetween items. Exceptions are not suppressed - if any comparison operationsfail, the entire sort operation will fail (and the list will likely be leftin a partially modified state).

sort() accepts two arguments that can only be passed by keyword(keyword-only arguments):

key specifies a function of one argument that is used to extract acomparison key from each list element (for example,key=str.lower).The key corresponding to each item in the list is calculated once andthen used for the entire sorting process. The default value ofNonemeans that list items are sorted directly without calculating a separatekey value.

Thefunctools.cmp_to_key() utility is available to convert a 2.xstylecmp function to akey function.

reverse is a boolean value. If set toTrue, then the list elementsare sorted as if each comparison were reversed.

This method modifies the sequence in place for economy of space whensorting a large sequence. To remind users that it operates by sideeffect, it does not return the sorted sequence (usesorted() toexplicitly request a new sorted list instance).

Thesort() method is guaranteed to be stable. A sort is stable if itguarantees not to change the relative order of elements that compare equal— this is helpful for sorting in multiple passes (for example, sort bydepartment, then by salary grade).

For sorting examples and a brief sorting tutorial, seeSorting Techniques.

CPython implementation detail: While a list is being sorted, the effect of attempting to mutate, or eveninspect, the list is undefined. The C implementation of Python makes thelist appear empty for the duration, and raisesValueError if it candetect that the list has been mutated during a sort.

Tuples¶

Tuples are immutable sequences, typically used to store collections ofheterogeneous data (such as the 2-tuples produced by theenumerate()built-in). Tuples are also used for cases where an immutable sequence ofhomogeneous data is needed (such as allowing storage in aset ordict instance).

classtuple([iterable])¶

Tuples may be constructed in a number of ways:

• Using a pair of parentheses to denote the empty tuple:()

• Using a trailing comma for a singleton tuple:a, or(a,)

• Separating items with commas:a,b,c or(a,b,c)

• Using thetuple() built-in:tuple() ortuple(iterable)

The constructor builds a tuple whose items are the same and in the sameorder asiterable’s items.iterable may be either a sequence, acontainer that supports iteration, or an iterator object. Ifiterableis already a tuple, it is returned unchanged. For example,tuple('abc') returns('a','b','c') andtuple([1,2,3]) returns(1,2,3).If no argument is given, the constructor creates a new empty tuple,().

Note that it is actually the comma which makes a tuple, not the parentheses.The parentheses are optional, except in the empty tuple case, orwhen they are needed to avoid syntactic ambiguity. For example,f(a,b,c) is a function call with three arguments, whilef((a,b,c)) is a function call with a 3-tuple as the sole argument.

Tuples implement all of thecommon sequenceoperations.

For heterogeneous collections of data where access by name is clearer thanaccess by index,collections.namedtuple() may be a more appropriatechoice than a simple tuple object.

Ranges¶

Therange type represents an immutable sequence of numbers and iscommonly used for looping a specific number of times inforloops.

classrange(stop)¶

classrange(start,stop[,step])

The arguments to the range constructor must be integers (either built-inint or any object that implements the__index__() specialmethod). If thestep argument is omitted, it defaults to1.If thestart argument is omitted, it defaults to0.Ifstep is zero,ValueError is raised.

For a positivestep, the contents of a ranger are determined by theformular[i]=start+step*i wherei>=0 andr[i]<stop.

For a negativestep, the contents of the range are still determined bythe formular[i]=start+step*i, but the constraints arei>=0andr[i]>stop.

A range object will be empty ifr[0] does not meet the valueconstraint. Ranges do support negative indices, but these are interpretedas indexing from the end of the sequence determined by the positiveindices.

Ranges containing absolute values larger thansys.maxsize arepermitted but some features (such aslen()) may raiseOverflowError.

Range examples:

>>>list(range(10))[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]>>>list(range(1,11))[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]>>>list(range(0,30,5))[0, 5, 10, 15, 20, 25]>>>list(range(0,10,3))[0, 3, 6, 9]>>>list(range(0,-10,-1))[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]>>>list(range(0))[]>>>list(range(1,0))[]

Ranges implement all of thecommon sequence operationsexcept concatenation and repetition (due to the fact that range objects canonly represent sequences that follow a strict pattern and repetition andconcatenation will usually violate that pattern).

start¶

The value of thestart parameter (or0 if the parameter wasnot supplied)

stop¶

The value of thestop parameter

step¶

The value of thestep parameter (or1 if the parameter wasnot supplied)

The advantage of therange type over a regularlist ortuple is that arange object will always take the same(small) amount of memory, no matter the size of the range it represents (as itonly stores thestart,stop andstep values, calculating individualitems and subranges as needed).

Range objects implement thecollections.abc.Sequence ABC, and providefeatures such as containment tests, element index lookup, slicing andsupport for negative indices (seeSequence Types — list, tuple, range):

>>>r=range(0,20,2)>>>rrange(0, 20, 2)>>>11inrFalse>>>10inrTrue>>>r.index(10)5>>>r[5]10>>>r[:5]range(0, 10, 2)>>>r[-1]18

Testing range objects for equality with== and!= comparesthem as sequences. That is, two range objects are considered equal ifthey represent the same sequence of values. (Note that two rangeobjects that compare equal might have differentstart,stop andstep attributes, for examplerange(0)==range(2,1,3) orrange(0,3,2)==range(0,4,2).)

String Methods¶

Strings implement all of thecommon sequenceoperations, along with the additional methods described below.

Strings also support two styles of string formatting, one providing a largedegree of flexibility and customization (seestr.format(),Format String Syntax andCustom String Formatting) and the other based on Cprintf style formatting that handles a narrower range of types and isslightly harder to use correctly, but is often faster for the cases it canhandle (printf-style String Formatting).

TheText Processing Services section of the standard library covers a number ofother modules that provide various text related utilities (including regularexpression support in there module).

str.capitalize()¶

Return a copy of the string with its first character capitalized and therest lowercased.

Changed in version 3.8:The first character is now put into titlecase rather than uppercase.This means that characters like digraphs will only have their firstletter capitalized, instead of the full character.

str.casefold()¶

Return a casefolded copy of the string. Casefolded strings may be used forcaseless matching.

Casefolding is similar to lowercasing but more aggressive because it isintended to remove all case distinctions in a string. For example, the Germanlowercase letter'ß' is equivalent to"ss". Since it is alreadylowercase,lower() would do nothing to'ß';casefold()converts it to"ss".

The casefolding algorithm isdescribed in section 3.13 ‘Default Case Folding’ of the Unicode Standard.

Added in version 3.3.

str.center(width[,fillchar])¶

Return centered in a string of lengthwidth. Padding is done using thespecifiedfillchar (default is an ASCII space). The original string isreturned ifwidth is less than or equal tolen(s).

str.count(sub[,start[,end]])¶

Return the number of non-overlapping occurrences of substringsub in therange [start,end]. Optional argumentsstart andend areinterpreted as in slice notation.

Ifsub is empty, returns the number of empty strings between characterswhich is the length of the string plus one.

str.encode(encoding='utf-8',errors='strict')¶

Return the string encoded tobytes.

encoding defaults to'utf-8';seeStandard Encodings for possible values.

errors controls how encoding errors are handled.If'strict' (the default), aUnicodeError exception is raised.Other possible values are'ignore','replace','xmlcharrefreplace','backslashreplace' and anyother name registered viacodecs.register_error().SeeError Handlers for details.

For performance reasons, the value oferrors is not checked for validityunless an encoding error actually occurs,Python Development Mode is enabledor adebug build is used.

Changed in version 3.1:Added support for keyword arguments.

Changed in version 3.9:The value of theerrors argument is now checked inPython Development Mode andindebug mode.

str.endswith(suffix[,start[,end]])¶

ReturnTrue if the string ends with the specifiedsuffix, otherwise returnFalse.suffix can also be a tuple of suffixes to look for. With optionalstart, test beginning at that position. With optionalend, stop comparingat that position.

str.expandtabs(tabsize=8)¶

Return a copy of the string where all tab characters are replaced by one ormore spaces, depending on the current column and the given tab size. Tabpositions occur everytabsize characters (default is 8, giving tabpositions at columns 0, 8, 16 and so on). To expand the string, the currentcolumn is set to zero and the string is examined character by character. Ifthe character is a tab (\t), one or more space characters are insertedin the result until the current column is equal to the next tab position.(The tab character itself is not copied.) If the character is a newline(\n) or return (\r), it is copied and the current column is reset tozero. Any other character is copied unchanged and the current column isincremented by one regardless of how the character is represented whenprinted.

>>>'01\t012\t0123\t01234'.expandtabs()'01      012     0123    01234'>>>'01\t012\t0123\t01234'.expandtabs(4)'01  012 0123    01234'

str.find(sub[,start[,end]])¶

Return the lowest index in the string where substringsub is found withinthe slices[start:end]. Optional argumentsstart andend areinterpreted as in slice notation. Return-1 ifsub is not found.

Note

Thefind() method should be used only if you need to know theposition ofsub. To check ifsub is a substring or not, use thein operator:

>>>'Py'in'Python'True

str.format(*args,**kwargs)¶

Perform a string formatting operation. The string on which this method iscalled can contain literal text or replacement fields delimited by braces{}. Each replacement field contains either the numeric index of apositional argument, or the name of a keyword argument. Returns a copy ofthe string where each replacement field is replaced with the string value ofthe corresponding argument.

>>>"The sum of 1 + 2 is{0}".format(1+2)'The sum of 1 + 2 is 3'

SeeFormat String Syntax for a description of the various formatting optionsthat can be specified in format strings.

Note

When formatting a number (int,float,complex,decimal.Decimal and subclasses) with then type(ex:'{:n}'.format(1234)), the function temporarily sets theLC_CTYPE locale to theLC_NUMERIC locale to decodedecimal_point andthousands_sep fields oflocaleconv() ifthey are non-ASCII or longer than 1 byte, and theLC_NUMERIC locale isdifferent than theLC_CTYPE locale. This temporary change affectsother threads.

Changed in version 3.7:When formatting a number with then type, the function setstemporarily theLC_CTYPE locale to theLC_NUMERIC locale in somecases.

str.format_map(mapping,/)¶

Similar tostr.format(**mapping), except thatmapping isused directly and not copied to adict. This is usefulif for examplemapping is a dict subclass:

>>>classDefault(dict):...def__missing__(self,key):...returnkey...>>>'{name} was born in{country}'.format_map(Default(name='Guido'))'Guido was born in country'

Added in version 3.2.

str.index(sub[,start[,end]])¶

Likefind(), but raiseValueError when the substring isnot found.

str.isalnum()¶

ReturnTrue if all characters in the string are alphanumeric and there is atleast one character,False otherwise. A characterc is alphanumeric if oneof the following returnsTrue:c.isalpha(),c.isdecimal(),c.isdigit(), orc.isnumeric().

str.isalpha()¶

ReturnTrue if all characters in the string are alphabetic and there is at leastone character,False otherwise. Alphabetic characters are those characters definedin the Unicode character database as “Letter”, i.e., those with general categoryproperty being one of “Lm”, “Lt”, “Lu”, “Ll”, or “Lo”. Note that this is differentfrom theAlphabetic property defined in the section 4.10 ‘Letters, Alphabetic, andIdeographic’ of the Unicode Standard.

str.isascii()¶

ReturnTrue if the string is empty or all characters in the string are ASCII,False otherwise.ASCII characters have code points in the range U+0000-U+007F.

Added in version 3.7.

str.isdecimal()¶

ReturnTrue if all characters in the string are decimalcharacters and there is at least one character,Falseotherwise. Decimal characters are those that can be used to formnumbers in base 10, e.g. U+0660, ARABIC-INDIC DIGITZERO. Formally a decimal character is a character in the UnicodeGeneral Category “Nd”.

str.isdigit()¶

ReturnTrue if all characters in the string are digits and there is at least onecharacter,False otherwise. Digits include decimal characters and digits that needspecial handling, such as the compatibility superscript digits.This covers digits which cannot be used to form numbers in base 10,like the Kharosthi numbers. Formally, a digit is a character that has theproperty value Numeric_Type=Digit or Numeric_Type=Decimal.

str.isidentifier()¶

ReturnTrue if the string is a valid identifier according to the languagedefinition, sectionIdentifiers and keywords.

keyword.iskeyword() can be used to test whether strings is a reservedidentifier, such asdef andclass.

Example:

>>>fromkeywordimportiskeyword>>>'hello'.isidentifier(),iskeyword('hello')(True, False)>>>'def'.isidentifier(),iskeyword('def')(True, True)

str.islower()¶

ReturnTrue if all cased characters[4] in the string are lowercase andthere is at least one cased character,False otherwise.

str.isnumeric()¶

ReturnTrue if all characters in the string are numericcharacters, and there is at least one character,Falseotherwise. Numeric characters include digit characters, and all charactersthat have the Unicode numeric value property, e.g. U+2155,VULGAR FRACTION ONE FIFTH. Formally, numeric characters are those with the propertyvalue Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric.

str.isprintable()¶

ReturnTrue if all characters in the string are printable,False if itcontains at least one non-printable character.

Here “printable” means the character is suitable forrepr() to use inits output; “non-printable” means thatrepr() on built-in types willhex-escape the character. It has no bearing on the handling of stringswritten tosys.stdout orsys.stderr.

The printable characters are those which in the Unicode character database(seeunicodedata) have a general category in group Letter, Mark,Number, Punctuation, or Symbol (L, M, N, P, or S); plus the ASCII space 0x20.Nonprintable characters are those in group Separator or Other (Z or C),except the ASCII space.

str.isspace()¶

ReturnTrue if there are only whitespace characters in the string and there isat least one character,False otherwise.

A character iswhitespace if in the Unicode character database(seeunicodedata), either its general category isZs(“Separator, space”), or its bidirectional class is one ofWS,B, orS.

str.istitle()¶

ReturnTrue if the string is a titlecased string and there is at least onecharacter, for example uppercase characters may only follow uncased charactersand lowercase characters only cased ones. ReturnFalse otherwise.

str.isupper()¶

ReturnTrue if all cased characters[4] in the string are uppercase andthere is at least one cased character,False otherwise.

>>>'BANANA'.isupper()True>>>'banana'.isupper()False>>>'baNana'.isupper()False>>>' '.isupper()False

str.join(iterable)¶

Return a string which is the concatenation of the strings initerable.ATypeError will be raised if there are any non-string values initerable, includingbytes objects. The separator betweenelements is the string providing this method.

str.ljust(width[,fillchar])¶

Return the string left justified in a string of lengthwidth. Padding isdone using the specifiedfillchar (default is an ASCII space). Theoriginal string is returned ifwidth is less than or equal tolen(s).

str.lower()¶

Return a copy of the string with all the cased characters[4] converted tolowercase.

The lowercasing algorithm used isdescribed in section 3.13 ‘Default Case Folding’ of the Unicode Standard.

str.lstrip([chars])¶

Return a copy of the string with leading characters removed. Thecharsargument is a string specifying the set of characters to be removed. If omittedorNone, thechars argument defaults to removing whitespace. Thecharsargument is not a prefix; rather, all combinations of its values are stripped:

>>>'   spacious   '.lstrip()'spacious   '>>>'www.example.com'.lstrip('cmowz.')'example.com'

Seestr.removeprefix() for a method that will remove a single prefixstring rather than all of a set of characters. For example:

>>>'Arthur: three!'.lstrip('Arthur: ')'ee!'>>>'Arthur: three!'.removeprefix('Arthur: ')'three!'

staticstr.maketrans(x[,y[,z]])¶

This static method returns a translation table usable forstr.translate().

If there is only one argument, it must be a dictionary mapping Unicodeordinals (integers) or characters (strings of length 1) to Unicode ordinals,strings (of arbitrary lengths) orNone. Character keys will then beconverted to ordinals.

If there are two arguments, they must be strings of equal length, and in theresulting dictionary, each character in x will be mapped to the character atthe same position in y. If there is a third argument, it must be a string,whose characters will be mapped toNone in the result.

str.partition(sep)¶

Split the string at the first occurrence ofsep, and return a 3-tuplecontaining the part before the separator, the separator itself, and the partafter the separator. If the separator is not found, return a 3-tuple containingthe string itself, followed by two empty strings.

str.removeprefix(prefix,/)¶

If the string starts with theprefix string, returnstring[len(prefix):]. Otherwise, return a copy of the originalstring:

>>>'TestHook'.removeprefix('Test')'Hook'>>>'BaseTestCase'.removeprefix('Test')'BaseTestCase'

Added in version 3.9.

str.removesuffix(suffix,/)¶

If the string ends with thesuffix string and thatsuffix is not empty,returnstring[:-len(suffix)]. Otherwise, return a copy of theoriginal string:

>>>'MiscTests'.removesuffix('Tests')'Misc'>>>'TmpDirMixin'.removesuffix('Tests')'TmpDirMixin'

Added in version 3.9.

str.replace(old,new,count=-1)¶

Return a copy of the string with all occurrences of substringold replaced bynew. Ifcount is given, only the firstcount occurrences are replaced.Ifcount is not specified or-1, then all occurrences are replaced.

Changed in version 3.13:count is now supported as a keyword argument.

str.rfind(sub[,start[,end]])¶

Return the highest index in the string where substringsub is found, suchthatsub is contained withins[start:end]. Optional argumentsstartandend are interpreted as in slice notation. Return-1 on failure.

str.rindex(sub[,start[,end]])¶

Likerfind() but raisesValueError when the substringsub is notfound.

str.rjust(width[,fillchar])¶

Return the string right justified in a string of lengthwidth. Padding isdone using the specifiedfillchar (default is an ASCII space). Theoriginal string is returned ifwidth is less than or equal tolen(s).

str.rpartition(sep)¶

Split the string at the last occurrence ofsep, and return a 3-tuplecontaining the part before the separator, the separator itself, and the partafter the separator. If the separator is not found, return a 3-tuple containingtwo empty strings, followed by the string itself.

str.rsplit(sep=None,maxsplit=-1)¶

Return a list of the words in the string, usingsep as the delimiter string.Ifmaxsplit is given, at mostmaxsplit splits are done, therightmostones. Ifsep is not specified orNone, any whitespace string is aseparator. Except for splitting from the right,rsplit() behaves likesplit() which is described in detail below.

str.rstrip([chars])¶

Return a copy of the string with trailing characters removed. Thecharsargument is a string specifying the set of characters to be removed. If omittedorNone, thechars argument defaults to removing whitespace. Thecharsargument is not a suffix; rather, all combinations of its values are stripped:

>>>'   spacious   '.rstrip()'   spacious'>>>'mississippi'.rstrip('ipz')'mississ'

Seestr.removesuffix() for a method that will remove a single suffixstring rather than all of a set of characters. For example:

>>>'Monty Python'.rstrip(' Python')'M'>>>'Monty Python'.removesuffix(' Python')'Monty'

str.split(sep=None,maxsplit=-1)¶

Return a list of the words in the string, usingsep as the delimiterstring. Ifmaxsplit is given, at mostmaxsplit splits are done (thus,the list will have at mostmaxsplit+1 elements). Ifmaxsplit is notspecified or-1, then there is no limit on the number of splits(all possible splits are made).

Ifsep is given, consecutive delimiters are not grouped together and aredeemed to delimit empty strings (for example,'1,,2'.split(',') returns['1','','2']). Thesep argument may consist of multiple charactersas a single delimiter (to split with multiple delimiters, usere.split()). Splitting an empty string with a specified separatorreturns[''].

For example:

>>>'1,2,3'.split(',')['1', '2', '3']>>>'1,2,3'.split(',',maxsplit=1)['1', '2,3']>>>'1,2,,3,'.split(',')['1', '2', '', '3', '']>>>'1<>2<>3<4'.split('<>')['1', '2', '3<4']

Ifsep is not specified or isNone, a different splitting algorithm isapplied: runs of consecutive whitespace are regarded as a single separator,and the result will contain no empty strings at the start or end if thestring has leading or trailing whitespace. Consequently, splitting an emptystring or a string consisting of just whitespace with aNone separatorreturns[].

For example:

>>>'1 2 3'.split()['1', '2', '3']>>>'1 2 3'.split(maxsplit=1)['1', '2 3']>>>'   1   2   3   '.split()['1', '2', '3']

Ifsep is not specified or isNone andmaxsplit is0, onlyleading runs of consecutive whitespace are considered.

For example:

>>>"".split(None,0)[]>>>"   ".split(None,0)[]>>>"   foo   ".split(maxsplit=0)['foo   ']

str.splitlines(keepends=False)¶

Return a list of the lines in the string, breaking at line boundaries. Linebreaks are not included in the resulting list unlesskeepends is given andtrue.

This method splits on the following line boundaries. In particular, theboundaries are a superset ofuniversal newlines.

Representation	Description
\n	Line Feed
\r	Carriage Return
\r\n	Carriage Return + Line Feed
\v or\x0b	Line Tabulation
\f or\x0c	Form Feed
\x1c	File Separator
\x1d	Group Separator
\x1e	Record Separator
\x85	Next Line (C1 Control Code)
\u2028	Line Separator
\u2029	Paragraph Separator

Changed in version 3.2:\v and\f added to list of line boundaries.

For example:

>>>'ab c\n\nde fg\rkl\r\n'.splitlines()['ab c', '', 'de fg', 'kl']>>>'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)['ab c\n', '\n', 'de fg\r', 'kl\r\n']

Unlikesplit() when a delimiter stringsep is given, thismethod returns an empty list for the empty string, and a terminal linebreak does not result in an extra line:

>>>"".splitlines()[]>>>"One line\n".splitlines()['One line']

For comparison,split('\n') gives:

>>>''.split('\n')['']>>>'Two lines\n'.split('\n')['Two lines', '']

str.startswith(prefix[,start[,end]])¶

ReturnTrue if string starts with theprefix, otherwise returnFalse.prefix can also be a tuple of prefixes to look for. With optionalstart,test string beginning at that position. With optionalend, stop comparingstring at that position.

str.strip([chars])¶

Return a copy of the string with the leading and trailing characters removed.Thechars argument is a string specifying the set of characters to be removed.If omitted orNone, thechars argument defaults to removing whitespace.Thechars argument is not a prefix or suffix; rather, all combinations of itsvalues are stripped:

>>>'   spacious   '.strip()'spacious'>>>'www.example.com'.strip('cmowz.')'example'

The outermost leading and trailingchars argument values are strippedfrom the string. Characters are removed from the leading end untilreaching a string character that is not contained in the set ofcharacters inchars. A similar action takes place on the trailing end.For example:

>>>comment_string='#....... Section 3.2.1 Issue #32 .......'>>>comment_string.strip('.#! ')'Section 3.2.1 Issue #32'

str.swapcase()¶

Return a copy of the string with uppercase characters converted to lowercase andvice versa. Note that it is not necessarily true thats.swapcase().swapcase()==s.

str.title()¶

Return a titlecased version of the string where words start with an uppercasecharacter and the remaining characters are lowercase.

For example:

>>>'Hello world'.title()'Hello World'

The algorithm uses a simple language-independent definition of a word asgroups of consecutive letters. The definition works in many contexts butit means that apostrophes in contractions and possessives form wordboundaries, which may not be the desired result:

>>>"they're bill's friends from the UK".title()"They'Re Bill'S Friends From The Uk"

Thestring.capwords() function does not have this problem, as itsplits words on spaces only.

Alternatively, a workaround for apostrophes can be constructed using regularexpressions:

>>>importre>>>deftitlecase(s):...returnre.sub(r"[A-Za-z]+('[A-Za-z]+)?",...lambdamo:mo.group(0).capitalize(),...s)...>>>titlecase("they're bill's friends.")"They're Bill's Friends."

str.translate(table)¶

Return a copy of the string in which each character has been mapped throughthe given translation table. The table must be an object that implementsindexing via__getitem__(), typically amapping orsequence. When indexed by a Unicode ordinal (an integer), thetable object can do any of the following: return a Unicode ordinal or astring, to map the character to one or more other characters; returnNone, to delete the character from the return string; or raise aLookupError exception, to map the character to itself.

You can usestr.maketrans() to create a translation map fromcharacter-to-character mappings in different formats.

See also thecodecs module for a more flexible approach to customcharacter mappings.

str.upper()¶

Return a copy of the string with all the cased characters[4] converted touppercase. Note thats.upper().isupper() might beFalse ifscontains uncased characters or if the Unicode category of the resultingcharacter(s) is not “Lu” (Letter, uppercase), but e.g. “Lt” (Letter,titlecase).

The uppercasing algorithm used isdescribed in section 3.13 ‘Default Case Folding’ of the Unicode Standard.

str.zfill(width)¶

Return a copy of the string left filled with ASCII'0' digits tomake a string of lengthwidth. A leading sign prefix ('+'/'-')is handled by inserting the paddingafter the sign character ratherthan before. The original string is returned ifwidth is less thanor equal tolen(s).

For example:

>>>"42".zfill(5)'00042'>>>"-42".zfill(5)'-0042'

Formatted String Literals (f-strings)¶

Anf-string (formally aformatted string literal) isa string literal that is prefixed withf orF.This type of string literal allows embedding arbitrary Python expressionswithinreplacement fields, which are delimited by curly brackets ({}).These expressions are evaluated at runtime, similarly tostr.format(),and are converted into regularstr objects.For example:

>>>who='nobody'>>>nationality='Spanish'>>>f'{who.title()} expects the{nationality} Inquisition!''Nobody expects the Spanish Inquisition!'

It is also possible to use a multi line f-string:

>>>f'''This is a string...on two lines''''This is a string\non two lines'

A single opening curly bracket,'{', marks areplacement field thatcan contain any Python expression:

>>>nationality='Spanish'>>>f'The{nationality} Inquisition!''The Spanish Inquisition!'

To include a literal{ or}, use a double bracket:

>>>x=42>>>f'{{x}} is{x}''{x} is 42'

Functions can also be used, andformat specifiers:

>>>frommathimportsqrt>>>f'√2\N{ALMOST EQUAL TO}{sqrt(2):.5f}''√2 ≈ 1.41421'

Any non-string expression is converted usingstr(), by default:

>>>fromfractionsimportFraction>>>f'{Fraction(1,3)}''1/3'

To use an explicit conversion, use the! (exclamation mark) operator,followed by any of the valid formats, which are:

For example:

>>>fromfractionsimportFraction>>>f'{Fraction(1,3)!s}''1/3'>>>f'{Fraction(1,3)!r}''Fraction(1, 3)'>>>question='¿Dónde está el Presidente?'>>>print(f'{question!a}')'\xbfD\xf3nde est\xe1 el Presidente?'

While debugging it may be helpful to see both the expression and its value,by using the equals sign (=) after the expression.This preserves spaces within the brackets, and can be used with a converter.By default, the debugging operator uses therepr() (!r) conversion.For example:

>>>fromfractionsimportFraction>>>calculation=Fraction(1,3)>>>f'{calculation=}''calculation=Fraction(1, 3)'>>>f'{calculation= }''calculation = Fraction(1, 3)'>>>f'{calculation= !s}''calculation = 1/3'

Once the output has been evaluated, it can be formatted using aformat specifier following a colon (':').After the expression has been evaluated, and possibly converted to a string,the__format__() method of the result is called with the format specifier,or the empty string if no format specifier is given.The formatted result is then used as the final value for the replacement field.For example:

>>>fromfractionsimportFraction>>>f'{Fraction(1,7):.6f}''0.142857'>>>f'{Fraction(1,7):_^+10}''___+1/7___'

printf-style String Formatting¶

String objects have one unique built-in operation: the% operator (modulo).This is also known as the stringformatting orinterpolation operator.Givenformat%values (whereformat is a string),% conversionspecifications informat are replaced with zero or more elements ofvalues.The effect is similar to using thesprintf() function in the C language.For example:

>>>print('%s has%d quote types.'%('Python',2))Python has 2 quote types.

Ifformat requires a single argument,values may be a single non-tupleobject.[5] Otherwise,values must be a tuple with exactly the number ofitems specified by the format string, or a single mapping object (for example, adictionary).

A conversion specifier contains two or more characters and has the followingcomponents, which must occur in this order:

1. The'%' character, which marks the start of the specifier.

2. Mapping key (optional), consisting of a parenthesised sequence of characters(for example,(somename)).

3. Conversion flags (optional), which affect the result of some conversiontypes.

4. Minimum field width (optional). If specified as an'*' (asterisk), theactual width is read from the next element of the tuple invalues, and theobject to convert comes after the minimum field width and optional precision.

5. Precision (optional), given as a'.' (dot) followed by the precision. Ifspecified as'*' (an asterisk), the actual precision is read from the nextelement of the tuple invalues, and the value to convert comes after theprecision.

6. Length modifier (optional).

7. Conversion type.

When the right argument is a dictionary (or other mapping type), then theformats in the stringmust include a parenthesised mapping key into thatdictionary inserted immediately after the'%' character. The mapping keyselects the value to be formatted from the mapping. For example:

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

In this case no* specifiers may occur in a format (since they require asequential parameter list).

The conversion flag characters are:

A length modifier (h,l, orL) may be present, but is ignored as itis not necessary for Python – so e.g.%ld is identical to%d.

The conversion types are:

Notes:

1. The alternate form causes a leading octal specifier ('0o') to beinserted before the first digit.

2. The alternate form causes a leading'0x' or'0X' (depending on whetherthe'x' or'X' format was used) to be inserted before the first digit.

3. The alternate form causes the result to always contain a decimal point, even ifno digits follow it.

   The precision determines the number of digits after the decimal point anddefaults to 6.

4. The alternate form causes the result to always contain a decimal point, andtrailing zeroes are not removed as they would otherwise be.

   The precision determines the number of significant digits before and after thedecimal point and defaults to 6.

5. If precision isN, the output is truncated toN characters.

6. SeePEP 237.

Since Python strings have an explicit length,%s conversions do not assumethat'\0' is the end of the string.

Bytes Objects¶

Bytes objects are immutable sequences of single bytes. Since many majorbinary protocols are based on the ASCII text encoding, bytes objects offerseveral methods that are only valid when working with ASCII compatibledata and are closely related to string objects in a variety of other ways.

classbytes([source[,encoding[,errors]]])¶

Firstly, the syntax for bytes literals is largely the same as that for stringliterals, except that ab prefix is added:

• Single quotes:b'stillallowsembedded"double"quotes'

• Double quotes:b"stillallowsembedded'single'quotes"

• Triple quoted:b'''3singlequotes''',b"""3doublequotes"""

Only ASCII characters are permitted in bytes literals (regardless of thedeclared source code encoding). Any binary values over 127 must be enteredinto bytes literals using the appropriate escape sequence.

As with string literals, bytes literals may also use ar prefix to disableprocessing of escape sequences. SeeString and Bytes literals for more about the variousforms of bytes literal, including supported escape sequences.

While bytes literals and representations are based on ASCII text, bytesobjects actually behave like immutable sequences of integers, with eachvalue in the sequence restricted such that0<=x<256 (attempts toviolate this restriction will triggerValueError). This is donedeliberately to emphasise that while many binary formats include ASCII basedelements and can be usefully manipulated with some text-oriented algorithms,this is not generally the case for arbitrary binary data (blindly applyingtext processing algorithms to binary data formats that are not ASCIIcompatible will usually lead to data corruption).

In addition to the literal forms, bytes objects can be created in a number ofother ways:

• A zero-filled bytes object of a specified length:bytes(10)

• From an iterable of integers:bytes(range(20))

• Copying existing binary data via the buffer protocol:bytes(obj)

Also see thebytes built-in.

Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimalnumbers are a commonly used format for describing binary data. Accordingly,the bytes type has an additional class method to read data in that format:

classmethodfromhex(string)¶

Thisbytes class method returns a bytes object, decoding thegiven string object. The string must contain two hexadecimal digits perbyte, with ASCII whitespace being ignored.

>>>bytes.fromhex('2Ef0 F1f2  ')b'.\xf0\xf1\xf2'

Changed in version 3.7:bytes.fromhex() now skips all ASCII whitespace in the string,not just spaces.

A reverse conversion function exists to transform a bytes object into itshexadecimal representation.

hex([sep[,bytes_per_sep]])¶

Return a string object containing two hexadecimal digits for eachbyte in the instance.

>>>b'\xf0\xf1\xf2'.hex()'f0f1f2'

If you want to make the hex string easier to read, you can specify asingle character separatorsep parameter to include in the output.By default, this separator will be included between each byte.A second optionalbytes_per_sep parameter controls the spacing.Positive values calculate the separator position from the right,negative values from the left.

>>>value=b'\xf0\xf1\xf2'>>>value.hex('-')'f0-f1-f2'>>>value.hex('_',2)'f0_f1f2'>>>b'UUDDLRLRAB'.hex(' ',-4)'55554444 4c524c52 4142'

Added in version 3.5.

Changed in version 3.8:bytes.hex() now supports optionalsep andbytes_per_sepparameters to insert separators between bytes in the hex output.

Since bytes objects are sequences of integers (akin to a tuple), for a bytesobjectb,b[0] will be an integer, whileb[0:1] will be a bytesobject of length 1. (This contrasts with text strings, where both indexingand slicing will produce a string of length 1)

The representation of bytes objects uses the literal format (b'...')since it is often more useful than e.g.bytes([46,46,46]). You canalways convert a bytes object into a list of integers usinglist(b).

Bytearray Objects¶

bytearray objects are a mutable counterpart tobytesobjects.

classbytearray([source[,encoding[,errors]]])¶

There is no dedicated literal syntax for bytearray objects, insteadthey are always created by calling the constructor:

• Creating an empty instance:bytearray()

• Creating a zero-filled instance with a given length:bytearray(10)

• From an iterable of integers:bytearray(range(20))

• Copying existing binary data via the buffer protocol:bytearray(b'Hi!')

As bytearray objects are mutable, they support themutable sequence operations in addition to thecommon bytes and bytearray operations described inBytes and Bytearray Operations.

Also see thebytearray built-in.

Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimalnumbers are a commonly used format for describing binary data. Accordingly,the bytearray type has an additional class method to read data in that format:

classmethodfromhex(string)¶

Thisbytearray class method returns bytearray object, decodingthe given string object. The string must contain two hexadecimal digitsper byte, with ASCII whitespace being ignored.

>>>bytearray.fromhex('2Ef0 F1f2  ')bytearray(b'.\xf0\xf1\xf2')

Changed in version 3.7:bytearray.fromhex() now skips all ASCII whitespace in the string,not just spaces.

A reverse conversion function exists to transform a bytearray object into itshexadecimal representation.

hex([sep[,bytes_per_sep]])¶

Return a string object containing two hexadecimal digits for eachbyte in the instance.

>>>bytearray(b'\xf0\xf1\xf2').hex()'f0f1f2'

Added in version 3.5.

Changed in version 3.8:Similar tobytes.hex(),bytearray.hex() now supportsoptionalsep andbytes_per_sep parameters to insert separatorsbetween bytes in the hex output.

Since bytearray objects are sequences of integers (akin to a list), for abytearray objectb,b[0] will be an integer, whileb[0:1] will bea bytearray object of length 1. (This contrasts with text strings, whereboth indexing and slicing will produce a string of length 1)

The representation of bytearray objects uses the bytes literal format(bytearray(b'...')) since it is often more useful than e.g.bytearray([46,46,46]). You can always convert a bytearray object intoa list of integers usinglist(b).

Bytes and Bytearray Operations¶

Both bytes and bytearray objects support thecommonsequence operations. They interoperate not just with operands of the sametype, but with anybytes-like object. Due to this flexibility, they can befreely mixed in operations without causing errors. However, the return typeof the result may depend on the order of operands.

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

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

Some bytes and bytearray operations assume the use of ASCII compatiblebinary formats, and hence should be avoided when working with arbitrarybinary data. These restrictions are covered below.

The following methods on bytes and bytearray objects can be used witharbitrary binary data.

bytes.count(sub[,start[,end]])¶

bytearray.count(sub[,start[,end]])¶

Return the number of non-overlapping occurrences of subsequencesub inthe range [start,end]. Optional argumentsstart andend areinterpreted as in slice notation.

The subsequence to search for may be anybytes-like object or aninteger in the range 0 to 255.

Ifsub is empty, returns the number of empty slices between characterswhich is the length of the bytes object plus one.

Changed in version 3.3:Also accept an integer in the range 0 to 255 as the subsequence.

bytes.removeprefix(prefix,/)¶

bytearray.removeprefix(prefix,/)¶

If the binary data starts with theprefix string, returnbytes[len(prefix):]. Otherwise, return a copy of the originalbinary data:

>>>b'TestHook'.removeprefix(b'Test')b'Hook'>>>b'BaseTestCase'.removeprefix(b'Test')b'BaseTestCase'

Theprefix may be anybytes-like object.

Note

The bytearray version of this method doesnot operate in place -it always produces a new object, even if no changes were made.

Added in version 3.9.

bytes.removesuffix(suffix,/)¶

bytearray.removesuffix(suffix,/)¶

If the binary data ends with thesuffix string and thatsuffix isnot empty, returnbytes[:-len(suffix)]. Otherwise, return a copy ofthe original binary data:

>>>b'MiscTests'.removesuffix(b'Tests')b'Misc'>>>b'TmpDirMixin'.removesuffix(b'Tests')b'TmpDirMixin'

Thesuffix may be anybytes-like object.

Note

The bytearray version of this method doesnot operate in place -it always produces a new object, even if no changes were made.

Added in version 3.9.

bytes.decode(encoding='utf-8',errors='strict')¶

bytearray.decode(encoding='utf-8',errors='strict')¶

Return the bytes decoded to astr.

encoding defaults to'utf-8';seeStandard Encodings for possible values.

errors controls how decoding errors are handled.If'strict' (the default), aUnicodeError exception is raised.Other possible values are'ignore','replace',and any other name registered viacodecs.register_error().SeeError Handlers for details.

For performance reasons, the value oferrors is not checked for validityunless a decoding error actually occurs,Python Development Mode is enabled or adebug build is used.

Note

Passing theencoding argument tostr allows decoding anybytes-like object directly, without needing to make a temporarybytes orbytearray object.

Changed in version 3.1:Added support for keyword arguments.

Changed in version 3.9:The value of theerrors argument is now checked inPython Development Mode andindebug mode.

bytes.endswith(suffix[,start[,end]])¶

bytearray.endswith(suffix[,start[,end]])¶

ReturnTrue if the binary data ends with the specifiedsuffix,otherwise returnFalse.suffix can also be a tuple of suffixes tolook for. With optionalstart, test beginning at that position. Withoptionalend, stop comparing at that position.

The suffix(es) to search for may be anybytes-like object.

bytes.find(sub[,start[,end]])¶

bytearray.find(sub[,start[,end]])¶

Return the lowest index in the data where the subsequencesub is found,such thatsub is contained in the slices[start:end]. Optionalargumentsstart andend are interpreted as in slice notation. Return-1 ifsub is not found.

The subsequence to search for may be anybytes-like object or aninteger in the range 0 to 255.

Note

Thefind() method should be used only if you need to know theposition ofsub. To check ifsub is a substring or not, use thein operator:

>>>b'Py'inb'Python'True

Changed in version 3.3:Also accept an integer in the range 0 to 255 as the subsequence.

bytes.index(sub[,start[,end]])¶

bytearray.index(sub[,start[,end]])¶

Likefind(), but raiseValueError when thesubsequence is not found.

The subsequence to search for may be anybytes-like object or aninteger in the range 0 to 255.

Changed in version 3.3:Also accept an integer in the range 0 to 255 as the subsequence.

bytes.join(iterable)¶

bytearray.join(iterable)¶

Return a bytes or bytearray object which is the concatenation of thebinary data sequences initerable. ATypeError will be raisedif there are any values initerable that are notbytes-likeobjects, includingstr objects. Theseparator between elements is the contents of the bytes orbytearray object providing this method.

staticbytes.maketrans(from,to)¶

staticbytearray.maketrans(from,to)¶

This static method returns a translation table usable forbytes.translate() that will map each character infrom into thecharacter at the same position into;from andto must both bebytes-like objects and have the same length.

Added in version 3.1.

bytes.partition(sep)¶

bytearray.partition(sep)¶

Split the sequence at the first occurrence ofsep, and return a 3-tuplecontaining the part before the separator, the separator itself or itsbytearray copy, and the part after the separator.If the separator is not found, return a 3-tuplecontaining a copy of the original sequence, followed by two empty bytes orbytearray objects.

The separator to search for may be anybytes-like object.

bytes.replace(old,new[,count])¶

bytearray.replace(old,new[,count])¶

Return a copy of the sequence with all occurrences of subsequenceoldreplaced bynew. If the optional argumentcount is given, only thefirstcount occurrences are replaced.

The subsequence to search for and its replacement may be anybytes-like object.

Note

The bytearray version of this method doesnot operate in place - italways produces a new object, even if no changes were made.

bytes.rfind(sub[,start[,end]])¶

bytearray.rfind(sub[,start[,end]])¶

Return the highest index in the sequence where the subsequencesub isfound, such thatsub is contained withins[start:end]. Optionalargumentsstart andend are interpreted as in slice notation. Return-1 on failure.

The subsequence to search for may be anybytes-like object or aninteger in the range 0 to 255.

Changed in version 3.3:Also accept an integer in the range 0 to 255 as the subsequence.

bytes.rindex(sub[,start[,end]])¶

bytearray.rindex(sub[,start[,end]])¶

Likerfind() but raisesValueError when thesubsequencesub is not found.

The subsequence to search for may be anybytes-like object or aninteger in the range 0 to 255.

Changed in version 3.3:Also accept an integer in the range 0 to 255 as the subsequence.