.. XXX: reference/datamodel and this have quite a few overlaps!

.. _bltin-types:

**************

Built-in Types

**************

The following sections describe the standard types that are built into the

interpreter.

.. index:: pair: built-in; types

The principal built-in types are numerics, sequences, mappings, classes,

instances and exceptions.

Some collection classes are mutable. The methods that add, subtract, or

rearrange their members in place, and don't return a specific item, never return

the collection instance itself but ``None``.

Some operations are supported by several object types; in particular,

practically all objects can be compared for equality, tested for truth

value, and converted to a string (with the :func:`repr` function or the

slightly different :func:`str` function). The latter function is implicitly

used when an object is written by the :func:`print` function.

.. _truth:

Truth Value Testing

===================

.. index::

pair: statement; if

pair: statement; while

pair: truth; value

pair: Boolean; operations

single: false

Any object can be tested for truth value, for use in an :keyword:`if` or

:keyword:`while` condition or as operand of the Boolean operations below.

.. index:: single: true

By default, an object is considered true unless its class defines either a

:meth:`~object.__bool__` method that returns ``False`` or a

:meth:`~object.__len__` method that

returns zero, when called with the object. [1]_ If one of the methods raises an

exception when called, the exception is propagated and the object does

not have a truth value (for example, :data:`NotImplemented`).

Here are most of the built-in objects considered false:

.. index::

single: None (Built-in object)

single: False (Built-in object)

* constants defined to be false: ``None`` and ``False``

* zero of any numeric type: ``0``, ``0.0``, ``0j``, ``Decimal(0)``,

``Fraction(0, 1)``

* empty sequences and collections: ``''``, ``()``, ``[]``, ``{}``, ``set()``,

``range(0)``

.. index::

pair: operator; or

pair: operator; and

single: False

single: True

Operations and built-in functions that have a Boolean result always return ``0``

or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated.

(Important exception: the Boolean operations ``or`` and ``and`` always return

one of their operands.)

.. _boolean:

Boolean Operations --- :keyword:`!and`, :keyword:`!or`, :keyword:`!not`

=======================================================================

.. index:: pair: Boolean; operations

These are the Boolean operations, ordered by ascending priority:

+-------------+---------------------------------+-------+

| Operation | Result | Notes |

+=============+=================================+=======+

| ``x or y`` | if *x* is true, then *x*, else | \(1) |

| | *y* | |

+-------------+---------------------------------+-------+

| ``x and y`` | if *x* is false, then *x*, else | \(2) |

| | *y* | |

+-------------+---------------------------------+-------+

| ``not x`` | if *x* is false, then ``True``, | \(3) |

| | else ``False`` | |

+-------------+---------------------------------+-------+

.. index::

pair: operator; and

pair: operator; or

pair: operator; not

Notes:

(1)

This is a short-circuit operator, so it only evaluates the second

argument if the first one is false.

(2)

This is a short-circuit operator, so it only evaluates the second

argument if the first one is true.

(3)

``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is

interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error.

.. _stdcomparisons:

Comparisons

===========

.. index::

pair: chaining; comparisons

pair: operator; comparison

pair: operator; ==

pair: operator; < (less)

pair: operator; <=

pair: operator; > (greater)

pair: operator; >=

pair: operator; !=

pair: operator; is

pair: operator; is not

There are eight comparison operations in Python. They all have the same

priority (which is higher than that of the Boolean operations). Comparisons can

be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and

y <= z``, except that *y* is evaluated only once (but in both cases *z* is not

evaluated at all when ``x < y`` is found to be false).

This table summarizes the comparison operations:

+------------+-------------------------+

| Operation | Meaning |

+============+=========================+

| ``<`` | strictly less than |

+------------+-------------------------+

| ``<=`` | less than or equal |

+------------+-------------------------+

| ``>`` | strictly greater than |

+------------+-------------------------+

| ``>=`` | greater than or equal |

+------------+-------------------------+

| ``==`` | equal |

+------------+-------------------------+

| ``!=`` | not equal |

+------------+-------------------------+

| ``is`` | object identity |

+------------+-------------------------+

| ``is not`` | negated object identity |

+------------+-------------------------+

.. index::

pair: object; numeric

pair: objects; comparing

Unless stated otherwise, objects of different types never compare equal.

The ``==`` operator is always defined but for some object types (for example,

class objects) is equivalent to :keyword:`is`. The ``<``, ``<=``, ``>`` and ``>=``

operators are only defined where they make sense; for example, they raise a

:exc:`TypeError` exception when one of the arguments is a complex number.

.. index::

single: __eq__() (instance method)

single: __ne__() (instance method)

single: __lt__() (instance method)

single: __le__() (instance method)

single: __gt__() (instance method)

single: __ge__() (instance method)

Non-identical instances of a class normally compare as non-equal unless the

class defines the :meth:`~object.__eq__` method.

Instances of a class cannot be ordered with respect to other instances of the

same class, or other types of object, unless the class defines enough of the

methods :meth:`~object.__lt__`, :meth:`~object.__le__`, :meth:`~object.__gt__`, and

:meth:`~object.__ge__` (in general, :meth:`~object.__lt__` and

:meth:`~object.__eq__` are sufficient, if you want the conventional meanings of the

comparison operators).

The behavior of the :keyword:`is` and :keyword:`is not` operators cannot be

customized; also they can be applied to any two objects and never raise an

exception.

.. index::

pair: operator; in

pair: operator; not in

Two more operations with the same syntactic priority, :keyword:`in` and

:keyword:`not in`, are supported by types that are :term:`iterable` or

implement the :meth:`~object.__contains__` method.

.. _typesnumeric:

Numeric Types --- :class:`int`, :class:`float`, :class:`complex`

================================================================

.. index::

pair: object; numeric

pair: object; Boolean

pair: object; integer

pair: object; floating-point

pair: object; complex number

pair: C; language

There are three distinct numeric types: :dfn:`integers`, :dfn:`floating-point

numbers`, and :dfn:`complex numbers`. In addition, Booleans are a

subtype of integers. Integers have unlimited precision. Floating-point

numbers are usually implemented using :c:expr:`double` in C; information

about the precision and internal representation of floating-point

numbers for the machine on which your program is running is available

in :data:`sys.float_info`. Complex numbers have a real and imaginary

part, which are each a floating-point number. To extract these parts

from a complex number *z*, use ``z.real`` and ``z.imag``. (The standard

library includes the additional numeric types :mod:`fractions.Fraction`, for

rationals, and :mod:`decimal.Decimal`, for floating-point numbers with

user-definable precision.)

.. index::

pair: numeric; literals

pair: integer; literals

pair: floating-point; literals

pair: complex number; literals

pair: hexadecimal; literals

pair: octal; literals

pair: binary; literals

Numbers are created by numeric literals or as the result of built-in functions

and operators. Unadorned integer literals (including hex, octal and binary

numbers) yield integers. Numeric literals containing a decimal point or an

exponent sign yield floating-point numbers. Appending ``'j'`` or ``'J'`` to a

numeric literal yields an imaginary number (a complex number with a zero real

part) which you can add to an integer or float to get a complex number with real

and imaginary parts.

The constructors :func:`int`, :func:`float`, and

:func:`complex` can be used to produce numbers of a specific type.

.. index::

single: arithmetic

pair: built-in function; int

pair: built-in function; float

pair: built-in function; complex

single: operator; + (plus)

single: + (plus); unary operator

single: + (plus); binary operator

single: operator; - (minus)

single: - (minus); unary operator

single: - (minus); binary operator

pair: operator; * (asterisk)

pair: operator; / (slash)

pair: operator; //

pair: operator; % (percent)

pair: operator; **

.. _stdtypes-mixed-arithmetic:

Python fully supports mixed arithmetic: when a binary arithmetic operator has

operands of different built-in numeric types, the operand with the "narrower"

type is widened to that of the other:

* If both arguments are complex numbers, no conversion is performed;

* if either argument is a complex or a floating-point number, the other is

converted to a floating-point number;

* otherwise, both must be integers and no conversion is necessary.

Arithmetic with complex and real operands is defined by the usual mathematical

formula, for example::

x + complex(u, v) = complex(x + u, v)

x * complex(u, v) = complex(x * u, x * v)

A comparison between numbers of different types behaves as though the exact

values of those numbers were being compared. [2]_

All numeric types (except complex) support the following operations (for priorities of

the operations, see :ref:`operator-summary`):

+---------------------+---------------------------------+---------+--------------------+

| Operation | Result | Notes | Full documentation |

+=====================+=================================+=========+====================+

| ``x + y`` | sum of *x* and *y* | | |

+---------------------+---------------------------------+---------+--------------------+

| ``x - y`` | difference of *x* and *y* | | |

+---------------------+---------------------------------+---------+--------------------+

| ``x * y`` | product of *x* and *y* | | |

+---------------------+---------------------------------+---------+--------------------+

| ``x / y`` | quotient of *x* and *y* | | |

+---------------------+---------------------------------+---------+--------------------+

| ``x // y`` | floored quotient of *x* and | \(1)\(2)| |

| | *y* | | |

+---------------------+---------------------------------+---------+--------------------+

| ``x % y`` | remainder of ``x / y`` | \(2) | |

+---------------------+---------------------------------+---------+--------------------+

| ``-x`` | *x* negated | | |

+---------------------+---------------------------------+---------+--------------------+

| ``+x`` | *x* unchanged | | |

+---------------------+---------------------------------+---------+--------------------+

| ``abs(x)`` | absolute value or magnitude of | | :func:`abs` |

| | *x* | | |

+---------------------+---------------------------------+---------+--------------------+

| ``int(x)`` | *x* converted to integer | \(3)\(6)| :func:`int` |

+---------------------+---------------------------------+---------+--------------------+

| ``float(x)`` | *x* converted to floating point | \(4)\(6)| :func:`float` |

+---------------------+---------------------------------+---------+--------------------+

| ``complex(re, im)`` | a complex number with real part | \(6) | :func:`complex` |

| | *re*, imaginary part *im*. | | |

| | *im* defaults to zero. | | |

+---------------------+---------------------------------+---------+--------------------+

| ``c.conjugate()`` | conjugate of the complex number | | |

| | *c* | | |

+---------------------+---------------------------------+---------+--------------------+

| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | \(2) | :func:`divmod` |

+---------------------+---------------------------------+---------+--------------------+

| ``pow(x, y)`` | *x* to the power *y* | \(5) | :func:`pow` |

+---------------------+---------------------------------+---------+--------------------+

| ``x ** y`` | *x* to the power *y* | \(5) | |

+---------------------+---------------------------------+---------+--------------------+

.. index::

triple: operations on; numeric; types

single: conjugate() (complex number method)

Notes:

(1)

Also referred to as integer division. For operands of type :class:`int`,

the result has type :class:`int`. For operands of type :class:`float`,

the result has type :class:`float`. In general, the result is a whole

integer, though the result's type is not necessarily :class:`int`. The result is

always rounded towards minus infinity: ``1//2`` is ``0``, ``(-1)//2`` is

``-1``, ``1//(-2)`` is ``-1``, and ``(-1)//(-2)`` is ``0``.

(2)

Not for complex numbers. Instead convert to floats using :func:`abs` if

appropriate.

(3)

.. index::

pair: module; math

single: floor() (in module math)

single: ceil() (in module math)

single: trunc() (in module math)

pair: numeric; conversions

Conversion from :class:`float` to :class:`int` truncates, discarding the

fractional part. See functions :func:`math.floor` and :func:`math.ceil` for

alternative conversions.

(4)

float also accepts the strings "nan" and "inf" with an optional prefix "+"

or "-" for Not a Number (NaN) and positive or negative infinity.

(5)

Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for

programming languages.

(6)

The numeric literals accepted include the digits ``0`` to ``9`` or any

Unicode equivalent (code points with the ``Nd`` property).

See `the Unicode Standard <https://unicode.org/Public/UNIDATA/extracted/DerivedNumericType.txt>`_

for a complete list of code points with the ``Nd`` property.

All :class:`numbers.Real` types (:class:`int` and :class:`float`) also include

the following operations:

+--------------------+---------------------------------------------+

| Operation | Result |

+====================+=============================================+

| :func:`math.trunc(\| *x* truncated to :class:`~numbers.Integral` |

| x) <math.trunc>` | |

+--------------------+---------------------------------------------+

| :func:`round(x[, | *x* rounded to *n* digits, |

| n]) <round>` | rounding half to even. If *n* is |

| | omitted, it defaults to 0. |

+--------------------+---------------------------------------------+

| :func:`math.floor(\| the greatest :class:`~numbers.Integral` |

| x) <math.floor>` | <= *x* |

+--------------------+---------------------------------------------+

| :func:`math.ceil(x)| the least :class:`~numbers.Integral` >= *x* |

| <math.ceil>` | |

+--------------------+---------------------------------------------+

For additional numeric operations see the :mod:`math` and :mod:`cmath`

modules.

.. XXXJH exceptions: overflow (when? what operations?) zerodivision

.. _bitstring-ops:

Bitwise Operations on Integer Types

-----------------------------------

.. index::

triple: operations on; integer; types

pair: bitwise; operations

pair: shifting; operations

pair: masking; operations

pair: operator; | (vertical bar)

pair: operator; ^ (caret)

pair: operator; & (ampersand)

pair: operator; <<

pair: operator; >>

pair: operator; ~ (tilde)

Bitwise operations only make sense for integers. The result of bitwise

operations is calculated as though carried out in two's complement with an

infinite number of sign bits.

The priorities of the binary bitwise operations are all lower than the numeric

operations and higher than the comparisons; the unary operation ``~`` has the

same priority as the other unary numeric operations (``+`` and ``-``).

This table lists the bitwise operations sorted in ascending priority:

+------------+--------------------------------+----------+

| Operation | Result | Notes |

+============+================================+==========+

| ``x | y`` | bitwise :dfn:`or` of *x* and | \(4) |

| | *y* | |

+------------+--------------------------------+----------+

| ``x ^ y`` | bitwise :dfn:`exclusive or` of | \(4) |

| | *x* and *y* | |

+------------+--------------------------------+----------+

| ``x & y`` | bitwise :dfn:`and` of *x* and | \(4) |

| | *y* | |

+------------+--------------------------------+----------+

| ``x << n`` | *x* shifted left by *n* bits | (1)(2) |

+------------+--------------------------------+----------+

| ``x >> n`` | *x* shifted right by *n* bits | (1)(3) |

+------------+--------------------------------+----------+

| ``~x`` | the bits of *x* inverted | |

+------------+--------------------------------+----------+

Notes:

(1)

Negative shift counts are illegal and cause a :exc:`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 in

a finite two's complement representation (a working bit-width of

``1 + max(x.bit_length(), y.bit_length())`` or more) is sufficient to get the

same result as if there were an infinite number of sign bits.

Additional Methods on Integer Types

-----------------------------------

The int type implements the :class:`numbers.Integral` :term:`abstract base

class`. In addition, it provides a few more methods:

.. method:: 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 the

unique positive integer ``k`` such that ``2**(k-1) <= abs(x) < 2**k``.

Equivalently, when ``abs(x)`` is small enough to have a correctly

rounded 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

.. versionadded:: 3.1

.. method:: int.bit_count()

Return the number of ones in the binary representation of the absolute

value 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")

.. versionadded:: 3.10

.. method:: 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. An

:exc:`OverflowError` is raised if the integer is not representable with

the given number of bytes.

The *byteorder* argument determines the byte order used to represent the

integer, and defaults to ``"big"``. If *byteorder* is

``"big"``, the most significant byte is at the beginning of the byte

array. If *byteorder* is ``"little"``, the most significant byte is at

the end of the byte array.

The *signed* argument determines whether two's complement is used to

represent the integer. If *signed* is ``False`` and a negative integer is

given, an :exc:`OverflowError` is raised. The default value for *signed*

is ``False``.

The default values can be used to conveniently turn an integer into a

single byte object::

>>> (65).to_bytes()

b'A'

However, when using the default arguments, don't try

to convert a value greater than 255 or you'll get an :exc:`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)

.. versionadded:: 3.2

.. versionchanged:: 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 :term:`bytes-like object` or an

iterable producing bytes.

The *byteorder* argument determines the byte order used to represent the

integer, and defaults to ``"big"``. If *byteorder* is

``"big"``, the most significant byte is at the beginning of the byte

array. If *byteorder* is ``"little"``, the most significant byte is at

the end of the byte array. To request the native byte order of the host

system, use :data:`sys.byteorder` as the byte order value.

The *signed* argument indicates whether two's complement is used to

represent 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

.. versionadded:: 3.2

.. versionchanged:: 3.11

Added default argument value for ``byteorder``.

.. method:: int.as_integer_ratio()

Return a pair of integers whose ratio is equal to the original

integer and has a positive denominator. The integer ratio of integers

(whole numbers) is always the integer as the numerator and ``1`` as the

denominator.

.. versionadded:: 3.8

.. method:: int.is_integer()

Returns ``True``. Exists for duck type compatibility with :meth:`float.is_integer`.

.. versionadded:: 3.12

Additional Methods on Float

---------------------------

The float type implements the :class:`numbers.Real` :term:`abstract base

class`. float also has the following additional methods.

.. classmethod:: float.from_number(x)

Class method to return a floating-point number constructed from a number *x*.

If the argument is an integer or a floating-point number, a

floating-point number with the same value (within Python's floating-point

precision) is returned. If the argument is outside the range of a Python

float, an :exc:`OverflowError` will be raised.

For a general Python object ``x``, ``float.from_number(x)`` delegates to

``x.__float__()``.

If :meth:`~object.__float__` is not defined then it falls back

to :meth:`~object.__index__`.

.. versionadded:: 3.14

.. method:: float.as_integer_ratio()

Return a pair of integers whose ratio is exactly equal to the

original float. The ratio is in lowest terms and has a positive denominator. Raises

:exc:`OverflowError` on infinities and a :exc:`ValueError` on

NaNs.

.. method:: float.is_integer()

Return ``True`` if the float instance is finite with integral

value, and ``False`` otherwise::

>>> (-2.0).is_integer()

True

>>> (3.2).is_integer()

False

Two methods support conversion to

and from hexadecimal strings. Since Python's floats are stored

internally as binary numbers, converting a float to or from a

*decimal* string usually involves a small rounding error. In

contrast, hexadecimal strings allow exact representation and

specification of floating-point numbers. This can be useful when

debugging, and in numerical work.

.. method:: float.hex()

Return a representation of a floating-point number as a hexadecimal

string. For finite floating-point numbers, this representation

will always include a leading ``0x`` and a trailing ``p`` and

exponent.

.. classmethod:: float.fromhex(s)

Class method to return the float represented by a hexadecimal

string *s*. The string *s* may have leading and trailing

whitespace.

Note that :meth:`float.hex` is an instance method, while

:meth:`float.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 ``-``, ``integer``

and ``fraction`` are strings of hexadecimal digits, and ``exponent``

is a decimal integer with an optional leading sign. Case is not

significant, and there must be at least one hexadecimal digit in

either the integer or the fraction. This syntax is similar to the

syntax specified in section 6.4.4.2 of the C99 standard, and also to

the syntax used in Java 1.5 onwards. In particular, the output of

:meth:`float.hex` is usable as a hexadecimal floating-point literal in

C or Java code, and hexadecimal strings produced by C's ``%a`` format

character or Java's ``Double.toHexString`` are accepted by

:meth:`float.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 the

floating-point number ``(3 + 10./16 + 7./16**2) * 2.0**10``, or

``3740.0``::

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

3740.0

Applying the reverse conversion to ``3740.0`` gives a different

hexadecimal string representing the same number::

>>> float.hex(3740.0)

'0x1.d380000000000p+11'

Additional Methods on Complex

-----------------------------

The :class:`!complex` type implements the :class:`numbers.Complex`

:term:`abstract base class`.

:class:`!complex` also has the following additional methods.

.. classmethod:: complex.from_number(x)

Class method to convert a number to a complex number.

For a general Python object ``x``, ``complex.from_number(x)`` delegates to

``x.__complex__()``. If :meth:`~object.__complex__` is not defined then it falls back

to :meth:`~object.__float__`. If :meth:`!__float__` is not defined then it falls back

to :meth:`~object.__index__`.

.. versionadded:: 3.14

.. _numeric-hash:

Hashing of numeric types

------------------------

For numbers ``x`` and ``y``, possibly of different types, it's a requirement

that ``hash(x) == hash(y)`` whenever ``x == y`` (see the :meth:`~object.__hash__`

method documentation for more details). For ease of implementation and

efficiency across a variety of numeric types (including :class:`int`,

:class:`float`, :class:`decimal.Decimal` and :class:`fractions.Fraction`)

Python's hash for numeric types is based on a single mathematical function

that's defined for any rational number, and hence applies to all instances of

:class:`int` and :class:`fractions.Fraction`, and all finite instances of

:class:`float` and :class:`decimal.Decimal`. Essentially, this function is

given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is

made available to Python as the :attr:`~sys.hash_info.modulus` attribute of

:data:`sys.hash_info`.

.. impl-detail::

Currently, the prime used is ``P = 2**31 - 1`` on machines with 32-bit C

longs 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 divisible

by ``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`` is

divisible by ``P`` (but ``m`` is not) then ``n`` has no inverse

modulo ``P`` and the rule above doesn't apply; in this case define

``hash(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.inf``

are used as hash values for positive

infinity or negative infinity (respectively).

- For a :class:`complex` number ``z``, the hash values of the real

and imaginary parts are combined by computing ``hash(z.real) +

sys.hash_info.imag * hash(z.imag)``, reduced modulo

``2**sys.hash_info.width`` so that it lies in

``range(-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 rational

number, :class:`float`, or :class:`complex`::

import sys, math

def 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_value

def 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

.. _bltin-boolean-values:

.. _typebool:

Boolean Type - :class:`bool`

============================

Booleans represent truth values. The :class:`bool` type has exactly two

constant instances: ``True`` and ``False``.

.. index::

single: False

single: True

pair: Boolean; values

The built-in function :func:`bool` converts any value to a boolean, if the

value can be interpreted as a truth value (see section :ref:`truth` above).

For logical operations, use the :ref:`boolean operators <boolean>` ``and``,

``or`` and ``not``.

When applying the bitwise operators ``&``, ``|``, ``^`` to two booleans, they

return a bool equivalent to the logical operations "and", "or", "xor". However,

the logical operators ``and``, ``or`` and ``!=`` should be preferred

over ``&``, ``|`` and ``^``.

.. deprecated:: 3.12

The use of the bitwise inversion operator ``~`` is deprecated and will

raise an error in Python 3.16.

:class:`bool` is a subclass of :class:`int` (see :ref:`typesnumeric`). In

many numeric contexts, ``False`` and ``True`` behave like the integers 0 and 1, respectively.

However, relying on this is discouraged; explicitly convert using :func:`int`

instead.

.. _typeiter:

Iterator Types

==============

.. index::

single: iterator protocol

single: protocol; iterator

single: sequence; iteration

single: container; iteration over

Python supports a concept of iteration over containers. This is implemented

using two distinct methods; these are used to allow user-defined classes to

support iteration. Sequences, described below in more detail, always support

the iteration methods.

One method needs to be defined for container objects to provide :term:`iterable`

support:

.. XXX duplicated in reference/datamodel!

.. method:: container.__iter__()

Return an :term:`iterator` object. The object is required to support the

iterator protocol described below. If a container supports different types

of iteration, additional methods can be provided to specifically request

iterators for those iteration types. (An example of an object supporting

multiple forms of iteration would be a tree structure which supports both

breadth-first and depth-first traversal.) This method corresponds to the

:c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python

objects in the Python/C API.

The iterator objects themselves are required to support the following two

methods, which together form the :dfn:`iterator protocol`:

.. method:: iterator.__iter__()

Return the :term:`iterator` object itself. This is required to allow both

containers and iterators to be used with the :keyword:`for` and

:keyword:`in` statements. This method corresponds to the

:c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python

objects in the Python/C API.

.. method:: iterator.__next__()

Return the next item from the :term:`iterator`. If there are no further

items, raise the :exc:`StopIteration` exception. This method corresponds to

the :c:member:`~PyTypeObject.tp_iternext` slot of the type structure for

Python objects in the Python/C API.

Python defines several iterator objects to support iteration over general and

specific sequence types, dictionaries, and other more specialized forms. The

specific types are not important beyond their implementation of the iterator

protocol.

Once an iterator's :meth:`~iterator.__next__` method raises

:exc:`StopIteration`, it must continue to do so on subsequent calls.

Implementations that do not obey this property are deemed broken.

.. _generator-types:

Generator Types

---------------

Python's :term:`generator`\s provide a convenient way to implement the iterator

protocol. If a container object's :meth:`~object.__iter__` method is implemented as a

generator, it will automatically return an iterator object (technically, a

generator object) supplying the :meth:`~iterator.__iter__` and :meth:`~generator.__next__`

methods.

More information about generators can be found in :ref:`the documentation for

the yield expression <yieldexpr>`.

.. _typesseq:

Sequence Types --- :class:`list`, :class:`tuple`, :class:`range`

================================================================

There are three basic sequence types: lists, tuples, and range objects.

Additional sequence types tailored for processing of

:ref:`binary data <binaryseq>` and :ref:`text strings <textseq>` are

described in dedicated sections.

.. _typesseq-common:

Common Sequence Operations

--------------------------

.. index:: pair: object; sequence

The operations in the following table are supported by most sequence types,

both mutable and immutable. The :class:`collections.abc.Sequence` ABC is

provided to make it easier to correctly implement these operations on

custom sequence types.

This table lists the sequence operations sorted in ascending priority. In the

table, *s* and *t* are sequences of the same type, *n*, *i*, *j* and *k* are

integers and *x* is an arbitrary object that meets any type and value

restrictions imposed by *s*.

The ``in`` and ``not in`` operations have the same priorities as the

comparison operations. The ``+`` (concatenation) and ``*`` (repetition)

operations have the same priority as the corresponding numeric operations. [3]_