Built-in Types (2024)

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 a ValueError to be raised.

2. A left shift by n bits is equivalent to multiplication by pow(2, n).

3. A right shift by n bits is equivalent to floor division by pow(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 the numbers.Integral abstract 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, if x is nonzero, then x.bit_length() is theunique positive integer k such that 2**(k-1) <= abs(x) < 2**k.Equivalently, when abs(x) is small enough to have a correctlyrounded logarithm, then k = 1 + int(log(abs(x), 2)).If x is zero, then x.bit_length() returns 0.

Equivalent to:

def bit_length(self): s = bin(self) # binary representation: bin(-37) --> '-0b100101' s = s.lstrip('-0b') # remove leading zeros and minus sign return len(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:

def bit_count(self): return bin(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 using length bytes, and defaults to 1. AnOverflowError is raised if the integer is not representable withthe given number of bytes.

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

The signed argument determines whether two’s complement is used torepresent the integer. If signed is False and a negative integer isgiven, an OverflowError is raised. The default value for signedis False.

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

Equivalent to:

def to_bytes(n, length=1, byteorder='big', signed=False): if byteorder == 'little': order = range(length) elif byteorder == 'big': order = reversed(range(length)) else: raise ValueError("byteorder must be either 'little' or 'big'") return bytes((n >> i*8) & 0xff for i in order)

Added in version 3.2.

Changed in version 3.11: Added default argument values for length and byteorder.

classmethod int.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 argument bytes must either be a bytes-like object or aniterable producing bytes.

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

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

Equivalent to:

def from_bytes(bytes, byteorder='big', signed=False): if byteorder == 'little': little_ordered = list(bytes) elif byteorder == 'big': little_ordered = list(reversed(bytes)) else: raise ValueError("byteorder must be either 'little' or 'big'") n = sum(b << i*8 for i, b in enumerate(little_ordered)) if signed and little_ordered and (little_ordered[-1] & 0x80): n -= 1 << 8*len(little_ordered) return n

Added in version 3.2.

Changed in version 3.11: Added default argument value for byteorder.

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 and 1 as thedenominator.

Added in version 3.8.

int.is_integer()¶

Returns True. Exists for duck type compatibility with float.is_integer().

Added in version 3.12.

Additional Methods on Float¶

The float type implements the numbers.Real abstract 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 a ValueError onNaNs.

float.is_integer()¶

Return True if the float instance is finite with integralvalue, and False 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 leading 0x and a trailing p andexponent.

classmethod float.fromhex(s)¶

Class method to return the float represented by a hexadecimalstring s. The string s may have leading and trailingwhitespace.

Note that float.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 optional sign may by either + or -, integerand fraction are strings of hexadecimal digits, and exponentis 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’s Double.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 string 0x3.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 to 3740.0 gives a differenthexadecimal string representing the same number:

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

Hashing of numeric types¶

For numbers x and y, possibly of different types, it’s a requirementthat hash(x) == hash(y) whenever x == y (see the __hash__()method documentation for more details). For ease of implementation andefficiency across a variety of numeric types (including int,float, decimal.Decimal and fractions.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 and fractions.Fraction, and all finite instances offloat and decimal.Decimal. Essentially, this function isgiven by reduction modulo P for a fixed prime P. The value of P ismade available to Python as the modulus attribute ofsys.hash_info.

CPython implementation detail: Currently, the prime used is P = 2**31 - 1 on machines with 32-bit Clongs and P = 2**61 - 1 on machines with 64-bit C longs.

Here are the rules in detail:

• If x = m / n is a nonnegative rational number and n is not divisibleby P, define hash(x) as m * invmod(n, P) % P, where invmod(n,P) gives the inverse of n modulo P.

• If x = m / n is a nonnegative rational number and n isdivisible by P (but m is not) then n has no inversemodulo P and the rule above doesn’t apply; in this case definehash(x) to be the constant value sys.hash_info.inf.

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

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

• For a complex number z, the hash values of the realand imaginary parts are combined by computing hash(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, or complex:

import sys, mathdef hash_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.) while m % P == n % P == 0: m, n = m // P, n // P if n % P == 0: hash_value = sys.hash_info.inf else: # 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) % P if m < 0: hash_value = -hash_value if hash_value == -1: hash_value = -2 return hash_valuedef hash_float(x): """Compute the hash of a float x.""" if math.isnan(x): return object.__hash__(x) elif math.isinf(x): return sys.hash_info.inf if x > 0 else -sys.hash_info.inf else: return hash_fraction(*x.as_integer_ratio())def hash_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.width M = 2**(sys.hash_info.width - 1) hash_value = (hash_value & (M - 1)) - (hash_value & M) if hash_value == -1: hash_value = -2 return hash_value

Generator Types¶

Python’s generators 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 in the documentation forthe yield expression.

Common Sequence Operations¶

The operations in the following table are supported by most sequence types,both mutable and immutable. The collections.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 and t are sequences of the same type, n, i, j and k areintegers and x is an arbitrary object that meets any type and valuerestrictions imposed by s.

The in and not in 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 see Comparisons 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 a StopIteration is encountered (or when the indexdrops below zero).

Notes:

1. While the in and not in operations are used only for simplecontainment testing in the general case, some specialised sequences(such as str, bytes and bytearray) also usethem for subsequence testing:

   >>> "gg" in "eggs"True

2. Values of n less than 0 are treated as 0 (which yields an emptysequence of the same type as s). Note that items in the sequence sare 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 of lists modifies this single list.You can create a list of different lists this way:

   >>> lists = [[] for i in range(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. If i or j is negative, the index is relative to the end of sequence s:len(s) + i or len(s) + j is substituted. But note that -0 isstill 0.

4. The slice of s from i to j is defined as the sequence of items with indexk such that i <= k < j. If i or j is greater than len(s), uselen(s). If i is omitted or None, use 0. If j is omitted orNone, use len(s). If i is greater than or equal to j, the slice isempty.

5. The slice of s from i to j with step k is defined as the sequence ofitems with index x = i + n*k such that 0 <= n < (j-i)/k. In other words,the indices are i, i+k, i+2*k, i+3*k and so on, stopping whenj is reached (but never including j). When k is positive,i and j are reduced to len(s) if they are greater.When k is negative, i and j are reduced to len(s) - 1 ifthey are greater. If i or j are omitted or None, they become“end” values (which end depends on the sign of k). Note, k cannot be zero.If k is None, it is treated like 1.

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 concatenating str objects, you can build a list and usestr.join() at the end or else write to an io.StringIOinstance and retrieve its value when complete

   • if concatenating bytes objects, you can similarly usebytes.join() or io.BytesIO, or you can do in-placeconcatenation with a bytearray object. bytearrayobjects are mutable and have an efficient overallocation mechanism

   • if concatenating tuple objects, extend a list instead

   • for other types, investigate the relevant class documentation

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

8. index raises ValueError when x is not found in s.Not all implementations support passing the additional arguments i and j.These arguments allow efficient searching of subsections of the sequence. Passingthe extra arguments is roughly equivalent to using s[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 the hash()built-in.

This support allows immutable sequences, such as tuple instances, tobe used as dict keys and stored in set and frozensetinstances.

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

Mutable Sequence Types¶

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

In the table s is an instance of a mutable sequence type, t is anyiterable object and x is an arbitrary object that meets any typeand value restrictions imposed by s (for example, bytearray onlyaccepts integers that meet the value restriction 0 <= x <= 255).

Notes:

1. If k is not equal to 1, t must have the same length as the slice it is replacing.

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

3. remove() raises ValueError when x is not found in s.

4. The reverse() 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() and copy() are included for consistency with theinterfaces of mutable containers that don’t support slicing operations(such as dict and set). copy() is not part of thecollections.abc.MutableSequence ABC, but most concretemutable sequence classes provide it.

   Added in version 3.3: clear() and copy() methods.

6. The value n is an integer, or an object implementing__index__(). Zero and negative values of n clearthe sequence. Items in the sequence are not copied; they are referencedmultiple times, as explained for s * n under Common Sequence Operations.

Lists¶

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

class list([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: [x for x in iterable]

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

The constructor builds a list whose items are the same and in the sameorder as iterable’s items. iterable may be either a sequence, acontainer that supports iteration, or an iterator object. If iterableis already a list, a copy is made and returned, similar to iterable[:].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 the sorted()built-in.

Lists implement all of the common 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 of Nonemeans that list items are sorted directly without calculating a separatekey value.

The functools.cmp_to_key() utility is available to convert a 2.xstyle cmp function to a key function.

reverse is a boolean value. If set to True, 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 (use sorted() toexplicitly request a new sorted list instance).

The sort() 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, see Sorting 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 raises ValueError 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 the enumerate()built-in). Tuples are also used for cases where an immutable sequence ofhom*ogeneous data is needed (such as allowing storage in a set ordict instance).

class tuple([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 the tuple() built-in: tuple() or tuple(iterable)

The constructor builds a tuple whose items are the same and in the sameorder as iterable’s items. iterable may be either a sequence, acontainer that supports iteration, or an iterator object. If iterableis 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 the common 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¶

The range type represents an immutable sequence of numbers and iscommonly used for looping a specific number of times in forloops.

class range(stop)¶

class range(start, stop[, step])

The arguments to the range constructor must be integers (either built-inint or any object that implements the __index__() specialmethod). If the step argument is omitted, it defaults to 1.If the start argument is omitted, it defaults to 0.If step is zero, ValueError is raised.

For a positive step, the contents of a range r are determined by theformula r[i] = start + step*i where i >= 0 andr[i] < stop.

For a negative step, the contents of the range are still determined bythe formula r[i] = start + step*i, but the constraints are i >= 0and r[i] > stop.

A range object will be empty if r[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 than sys.maxsize arepermitted but some features (such as len()) 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 the common 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 the start parameter (or 0 if the parameter wasnot supplied)

stop¶

The value of the stop parameter

step¶

The value of the step parameter (or 1 if the parameter wasnot supplied)

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

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

>>> r = range(0, 20, 2)>>> rrange(0, 20, 2)>>> 11 in rFalse>>> 10 in rTrue>>> 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 different start,stop and step attributes, for examplerange(0) == range(2, 1, 3) or range(0, 3, 2) == range(0, 4, 2).)

Changed in version 3.2: Implement the Sequence ABC.Support slicing and negative indices.Test int objects for membership in constant time instead ofiterating through all items.

String Methods¶

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

Strings also support two styles of string formatting, one providing a largedegree of flexibility and customization (see str.format(),Format String Syntax and Custom 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).

The Text Processing Services section of the standard library covers a number ofother modules that provide various text related utilities (including regularexpression support in the re 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 length width. Padding is done using thespecified fillchar (default is an ASCII space). The original string isreturned if width is less than or equal to len(s).

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

Return the number of non-overlapping occurrences of substring sub in therange [start, end]. Optional arguments start and end areinterpreted as in slice notation.

If sub 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 to bytes.

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

errors controls how encoding errors are handled.If 'strict' (the default), a UnicodeError exception is raised.Other possible values are 'ignore','replace', 'xmlcharrefreplace', 'backslashreplace' and anyother name registered via codecs.register_error().See Error Handlers for details.

For performance reasons, the value of errors is not checked for validityunless an encoding error actually occurs,Python Development Mode is enabledor a debug build is used.

Changed in version 3.1: Added support for keyword arguments.

Changed in version 3.9: The value of the errors argument is now checked in Python Development Mode andin debug mode.

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

Return True if the string ends with the specified suffix, otherwise returnFalse. suffix can also be a tuple of suffixes to look for. With optionalstart, test beginning at that position. With optional end, 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 every tabsize 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 substring sub is found withinthe slice s[start:end]. Optional arguments start and end areinterpreted as in slice notation. Return -1 if sub is not found.

Note

The find() method should be used only if you need to know theposition of sub. To check if sub 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'

See Format 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 the n type(ex: '{:n}'.format(1234)), the function temporarily sets theLC_CTYPE locale to the LC_NUMERIC locale to decodedecimal_point and thousands_sep fields of localeconv() ifthey are non-ASCII or longer than 1 byte, and the LC_NUMERIC locale isdifferent than the LC_CTYPE locale. This temporary change affectsother threads.

Changed in version 3.7: When formatting a number with the n type, the function setstemporarily the LC_CTYPE locale to the LC_NUMERIC locale in somecases.

str.format_map(mapping)¶

Similar to str.format(**mapping), except that mapping isused directly and not copied to a dict. This is usefulif for example mapping is a dict subclass:

>>> class Default(dict):...  def __missing__(self, key):...  return key...>>> '{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]])¶

Like find(), but raise ValueError when the substring isnot found.

str.isalnum()¶

Return True if all characters in the string are alphanumeric and there is atleast one character, False otherwise. A character c is alphanumeric if oneof the following returns True: c.isalpha(), c.isdecimal(),c.isdigit(), or c.isnumeric().

str.isalpha()¶

Return True 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 the Alphabetic property defined in the section 4.10 ‘Letters, Alphabetic, andIdeographic’ of the Unicode Standard.

str.isascii()¶

Return True 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()¶

Return True 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()¶

Return True 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()¶

Return True if the string is a valid identifier according to the languagedefinition, section Identifiers and keywords.

keyword.iskeyword() can be used to test whether string s is a reservedidentifier, such as def and class.

Example:

>>> from keyword import iskeyword>>> 'hello'.isidentifier(), iskeyword('hello')(True, False)>>> 'def'.isidentifier(), iskeyword('def')(True, True)

str.islower()¶

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

str.isnumeric()¶

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

See Also

What is the numeric form of the number name given below? “One hundred four thousand, one hundred three”A. 1, 414B. 14, 103C. 104, 103D. 104, 113When to Spell Out Numbers in Writing: Guide and Examples | ScribendiNumeric Numbers: What are Numeric numbers?Numerical Expression: Definition, Simplification & Examples

str.isprintable()¶

Return True if all characters in the string are printable or the string isempty, False otherwise. Nonprintable characters are those characters definedin the Unicode character database as “Other” or “Separator”, excepting theASCII space (0x20) which is considered printable. (Note that printablecharacters in this context are those which should not be escaped whenrepr() is invoked on a string. It has no bearing on the handling ofstrings written to sys.stdout or sys.stderr.)

str.isspace()¶

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

A character is whitespace if in the Unicode character database(see unicodedata), either its general category is Zs(“Separator, space”), or its bidirectional class is one of WS,B, or S.

str.istitle()¶

Return True 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. Return False otherwise.

str.isupper()¶

Return True 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 in iterable.A TypeError will be raised if there are any non-string values initerable, including bytes objects. The separator betweenelements is the string providing this method.

str.ljust(width[, fillchar])¶

Return the string left justified in a string of length width. Padding isdone using the specified fillchar (default is an ASCII space). Theoriginal string is returned if width is less than or equal to len(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. The charsargument is a string specifying the set of characters to be removed. If omittedor None, the chars argument defaults to removing whitespace. The charsargument is not a prefix; rather, all combinations of its values are stripped:

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

See str.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!'

static str.maketrans(x[, y[, z]])¶

This static method returns a translation table usable for str.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) or None. 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 to None in the result.

str.partition(sep)¶

Split the string at the first occurrence of sep, 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 the prefix 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 the suffix string and that suffix is not empty,return string[:-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])¶

Return a copy of the string with all occurrences of substring old replaced bynew. If the optional argument count is given, only the first countoccurrences are replaced.

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

Return the highest index in the string where substring sub is found, suchthat sub is contained within s[start:end]. Optional arguments startand end are interpreted as in slice notation. Return -1 on failure.

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

Like rfind() but raises ValueError when the substring sub is notfound.

str.rjust(width[, fillchar])¶

Return the string right justified in a string of length width. Padding isdone using the specified fillchar (default is an ASCII space). Theoriginal string is returned if width is less than or equal to len(s).

str.rpartition(sep)¶

Split the string at the last occurrence of sep, 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, using sep as the delimiter string.If maxsplit is given, at most maxsplit splits are done, the rightmostones. If sep is not specified or None, 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. The charsargument is a string specifying the set of characters to be removed. If omittedor None, the chars argument defaults to removing whitespace. The charsargument is not a suffix; rather, all combinations of its values are stripped:

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

See str.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, using sep as the delimiterstring. If maxsplit is given, at most maxsplit splits are done (thus,the list will have at most maxsplit+1 elements). If maxsplit is notspecified or -1, then there is no limit on the number of splits(all possible splits are made).

If sep is given, consecutive delimiters are not grouped together and aredeemed to delimit empty strings (for example, '1,,2'.split(',') returns['1', '', '2']). The sep 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']

If sep is not specified or is None, 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 a None 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']

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 unless keepends is given andtrue.

This method splits on the following line boundaries. In particular, theboundaries are a superset of universal 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']

Unlike split() when a delimiter string sep 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]])¶

Return True if string starts with the prefix, otherwise return False.prefix can also be a tuple of prefixes to look for. With optional start,test string beginning at that position. With optional end, stop comparingstring at that position.

str.strip([chars])¶

Return a copy of the string with the leading and trailing characters removed.The chars argument is a string specifying the set of characters to be removed.If omitted or None, the chars argument defaults to removing whitespace.The chars 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 trailing chars 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 in chars. 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"

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

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

>>> import re>>> def titlecase(s):...  return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",...  lambda mo: 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 a mapping 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 use str.maketrans() to create a translation map fromcharacter-to-character mappings in different formats.

See also the codecs 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 that s.upper().isupper() might be False if scontains 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 length width. A leading sign prefix ('+'/'-')is handled by inserting the padding after the sign character ratherthan before. The original string is returned if width is less thanor equal to len(s).

For example:

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

printf-style String Formatting¶

String objects have one unique built-in operation: the % operator (modulo).This is also known as the string formatting or interpolation operator.Given format % values (where format is a string), % conversionspecifications in format are replaced with zero or more elements of values.The effect is similar to using the sprintf() in the C language.

If format 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 in values, 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 in values, 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 string must 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, or L) 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 is N, the output is truncated to N characters.

6. See PEP 237.

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

Changed in version 3.1: %f conversions for numbers whose absolute value is over 1e50 are nolonger replaced by %g conversions.

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.

class bytes([source[, encoding[, errors]]])¶

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

• Single quotes: b'still allows embedded "double" quotes'

• Double quotes: b"still allows embedded 'single' quotes"

• Triple quoted: b'''3 single quotes''', b"""3 double quotes"""

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 a r prefix to disableprocessing of escape sequences. See String 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 that 0 <= x < 256 (attempts toviolate this restriction will trigger ValueError). 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 the bytes 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:

classmethod fromhex(string)¶

This bytes 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 separator sep parameter to include in the output.By default, this separator will be included between each byte.A second optional bytes_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 optional sep and bytes_per_sepparameters to insert separators between bytes in the hex output.

Since bytes objects are sequences of integers (akin to a tuple), for a bytesobject b, b[0] will be an integer, while b[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 using list(b).

Bytearray Objects¶

bytearray objects are a mutable counterpart to bytesobjects.

class bytearray([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 in Bytes and Bytearray Operations.

Also see the bytearray 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:

classmethod fromhex(string)¶

This bytearray 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 to bytes.hex(), bytearray.hex() now supportsoptional sep and bytes_per_sep parameters to insert separatorsbetween bytes in the hex output.

Since bytearray objects are sequences of integers (akin to a list), for abytearray object b, b[0] will be an integer, while b[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 using list(b).

Bytes and Bytearray Operations¶

Both bytes and bytearray objects support the commonsequence operations. They interoperate not just with operands of the sametype, but with any bytes-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 subsequence sub inthe range [start, end]. Optional arguments start and end areinterpreted as in slice notation.

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

If sub 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 the prefix 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'

The prefix may be any bytes-like object.

Note

The bytearray version of this method does not 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 the suffix string and that suffix isnot empty, return bytes[:-len(suffix)]. Otherwise, return a copy ofthe original binary data:

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

The suffix may be any bytes-like object.

Note

The bytearray version of this method does not 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 a str.

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

errors controls how decoding errors are handled.If 'strict' (the default), a UnicodeError exception is raised.Other possible values are 'ignore', 'replace',and any other name registered via codecs.register_error().See Error Handlers for details.

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

Note

Passing the encoding argument to str allows decoding anybytes-like object directly, without needing to make a temporarybytes or bytearray object.

Changed in version 3.1: Added support for keyword arguments.

Changed in version 3.9: The value of the errors argument is now checked in Python Development Mode andin debug mode.

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

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

Return True if the binary data ends with the specified suffix,otherwise return False. suffix can also be a tuple of suffixes tolook for. With optional start, test beginning at that position. Withoptional end, stop comparing at that position.

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

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

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

Return the lowest index in the data where the subsequence sub is found,such that sub is contained in the slice s[start:end]. Optionalarguments start and end are interpreted as in slice notation. Return-1 if sub is not found.

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

Note

The find() method should be used only if you need to know theposition of sub. To check if sub is a substring or not, use thein operator:

>>> b'Py' in b'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]])¶

Like find(), but raise ValueError when thesubsequence is not found.

The subsequence to search for may be any bytes-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 in iterable. A TypeError will be raisedif there are any values in iterable that are not bytes-likeobjects, including str objects. Theseparator between elements is the contents of the bytes orbytearray object providing this method.

static bytes.maketrans(from, to)¶

static bytearray.maketrans(from, to)¶

This static method returns a translation table usable forbytes.translate() that will map each character in from into thecharacter at the same position in to; from and to 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 of sep, 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 any bytes-like object.

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

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

Return a copy of the sequence with all occurrences of subsequence oldreplaced by new. If the optional argument count is given, only thefirst count occurrences are replaced.

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

Note

The bytearray version of this method does not 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 subsequence sub isfound, such that sub is contained within s[start:end]. Optionalarguments start and end are interpreted as in slice notation. Return-1 on failure.

The subsequence to search for may be any bytes-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]])¶

Like rfind() but raises ValueError when thesubsequence sub is not found.

The subsequence to search for may be any bytes-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.rpartition(sep)¶

bytearray.rpartition(sep)¶

Split the sequence at the last occurrence of sep, 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 two empty bytes or bytearray objects, followed by a copy of theoriginal sequence.

The separator to search for may be any bytes-like object.

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

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

Return True if the binary data starts with the specified prefix,otherwise return False. prefix can also be a tuple of prefixes tolook for. With optional start, test beginning at that position. Withoptional end, stop comparing at that position.

The prefix(es) to search for may be any bytes-like object.

bytes.translate(table, /, delete=b'')¶

bytearray.translate(table, /, delete=b'')¶

Return a copy of the bytes or bytearray object where all bytes occurring inthe optional argument delete are removed, and the remaining bytes havebeen mapped through the given translation table, which must be a bytesobject of length 256.

You can use the bytes.maketrans() method to create a translationtable.

Set the table argument to None for translations that only deletecharacters:

>>> b'read this short text'.translate(None, b'aeiou')b'rd ths shrt txt'

Changed in version 3.6: delete is now supported as a keyword argument.

The following methods on bytes and bytearray objects have default behavioursthat assume the use of ASCII compatible binary formats, but can still be usedwith arbitrary binary data by passing appropriate arguments. Note that all ofthe bytearray methods in this section do not operate in place, and insteadproduce new objects.

bytes.center(width[, fillbyte])¶

bytearray.center(width[, fillbyte])¶

Return a copy of the object centered in a sequence of length width.Padding is done using the specified fillbyte (default is an ASCIIspace). For bytes objects, the original sequence is returned ifwidth is less than or equal to len(s).

Note

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

bytes.ljust(width[, fillbyte])¶

bytearray.ljust(width[, fillbyte])¶

Return a copy of the object left justified in a sequence of length width.Padding is done using the specified fillbyte (default is an ASCIIspace). For bytes objects, the original sequence is returned ifwidth is less than or equal to len(s).

Note

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

bytes.lstrip([chars])¶

bytearray.lstrip([chars])¶

Return a copy of the sequence with specified leading bytes removed. Thechars argument is a binary sequence specifying the set of byte values tobe removed - the name refers to the fact this method is usually used withASCII characters. If omitted or None, the chars argument defaultsto removing ASCII whitespace. The chars argument is not a prefix;rather, all combinations of its values are stripped:

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

The binary sequence of byte values to remove may be anybytes-like object. See removeprefix() for a methodthat will remove a single prefix string rather than all of a set ofcharacters. For example:

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

Note

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

bytes.rjust(width[, fillbyte])¶

bytearray.rjust(width[, fillbyte])¶

Return a copy of the object right justified in a sequence of length width.Padding is done using the specified fillbyte (default is an ASCIIspace). For bytes objects, the original sequence is returned ifwidth is less than or equal to len(s).

Note

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

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

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

Split the binary sequence into subsequences of the same type, using sepas the delimiter string. If maxsplit is given, at most maxsplit splitsare done, the rightmost ones. If sep is not specified or None,any subsequence consisting solely of ASCII whitespace is a separator.Except for splitting from the right, rsplit() behaves likesplit() which is described in detail below.

bytes.rstrip([chars])¶

bytearray.rstrip([chars])¶

Return a copy of the sequence with specified trailing bytes removed. Thechars argument is a binary sequence specifying the set of byte values tobe removed - the name refers to the fact this method is usually used withASCII characters. If omitted or None, the chars argument defaults toremoving ASCII whitespace. The chars argument is not a suffix; rather,all combinations of its values are stripped:

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

The binary sequence of byte values to remove may be anybytes-like object. See removesuffix() for a methodthat will remove a single suffix string rather than all of a set ofcharacters. For example:

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

Note

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

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

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

Split the binary sequence into subsequences of the same type, using sepas the delimiter string. If maxsplit is given and non-negative, at mostmaxsplit splits are done (thus, the list will have at most maxsplit+1elements). If maxsplit is not specified or is -1, then there is nolimit on the number of splits (all possible splits are made).

If sep is given, consecutive delimiters are not grouped together and aredeemed to delimit empty subsequences (for example, b'1,,2'.split(b',')returns [b'1', b'', b'2']). The sep argument may consist of amultibyte sequence as a single delimiter. Splitting an empty sequence witha specified separator returns [b''] or [bytearray(b'')] dependingon the type of object being split. The sep argument may be anybytes-like object.

For example:

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

If sep is not specified or is None, a different splitting algorithmis applied: runs of consecutive ASCII whitespace are regarded as a singleseparator, and the result will contain no empty strings at the start orend if the sequence has leading or trailing whitespace. Consequently,splitting an empty sequence or a sequence consisting solely of ASCIIwhitespace without a specified separator returns [].

For example:

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