Technical Documentation: python/cpython
βΉοΈ Provenance: Multi-Tier Ingestion Β· CodeWiki Reference
Doc README (`Doc/README.rst`)
Python Documentation README
text
This directory contains the reStructuredText (reST) sources to the Python
documentation. You don't need to build them yourself, `prebuilt versions are
available <https://docs.python.org/dev/download.html>`_.
Documentation on authoring Python documentation, including information about
both style and markup, is available in the "`Documenting Python
<https://devguide.python.org/documenting/>`_" chapter of the
developers guide.
Building the docs
=================
The documentation is built with several tools which are not included in this
tree but are maintained separately and are available from
`PyPI <https://pypi.org/>`_.
* `Sphinx <https://pypi.org/project/Sphinx/>`_
* `blurb <https://pypi.org/project/blurb/>`_
* `python-docs-theme <https://pypi.org/project/python-docs-theme/>`_
The easiest way to install these tools is to create a virtual environment and
install the tools into there.
Using make
----------
To get started on Unix, you can create a virtual environment and build
documentation with the commands::
make venv
make html
The virtual environment in the ``venv`` directory will contain all the tools
necessary to build the documentation downloaded and installed from PyPI.
If you'd like to create the virtual environment in a different location,
you can specify it using the ``VENVDIR`` variable.
You can also skip creating the virtual environment altogether, in which case
the ``Makefile`` will look for instances of ``sphinx-build`` and ``blurb``
installed on your process ``PATH`` (configurable with the ``SPHINXBUILD`` and
``BLURB`` variables).
On Windows, we try to emulate the ``Makefile`` as closely as possible with a
``make.bat`` file. If you need to specify the Python interpreter to use,
set the ``PYTHON`` environment variable.
Available make targets are:
* "clean", which removes all build files and the virtual environment.
* "clean-venv", which removes the virtual environment directory.
* "venv", which creates a virtual environment with all necessary tools
installed.
* "html", which builds standalone HTML files for offline viewing.
* "htmlview", which re-uses the "html" builder, but then opens the main page
in your default web browser.
* "htmllive", which re-uses the "html" builder, rebuilds the docs,
starts a local server, and automatically reloads the page in your browser
when you make changes to reST files (Unix only).
* "htmlhelp", which builds HTML files and a HTML Help project file usable to
convert them into a single Compiled HTML (.chm) file -- these are popular
under Microsoft Windows, but very handy on every platform.
To create the CHM file, you need to run the Microsoft HTML Help Workshop
over the generated project (.hhp) file. The ``make.bat`` script does this for
you on Windows.
* "latex", which builds LaTeX source files as input to ``pdflatex`` to produce
PDF documents.
* "text", which builds a plain text file for each source file.
* "epub", which builds an EPUB document, suitable to be viewed on e-book
readers.
* "linkcheck", which checks all external references to see whether they are
broken, redirected or malformed, and outputs this information to stdout as
well as a plain-text (.txt) file.
* "changes", which builds an overview over all versionadded/versionchanged/
deprecated items in the current version. This is meant as a help for the
writer of the "What's New" document.
* "coverage", which builds a coverage overview for standard library modules and
C API.
* "pydoc-topics", which builds a Python module containing a dictionary with
plain text documentation for the labels defined in
``tools/pyspecific.py`` -- pydoc needs these to show topic and keyword help.
* "check", which checks for frequent markup errors.
* "dist", (Unix only) which creates distributable archives of HTML, text,
PDF, and EPUB builds.
Without make
------------
First, install the tool dependencies from PyPI.
Then, from the ``Doc`` directory, run ::
sphinx-build -b<builder> . build/<builder>
where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
see the make targets above).
Deprecation header
==================
You can define the ``outdated`` variable in ``html_context`` to show a
red banner on each page redirecting to the "latest" version.
The link points to the same page on ``/3/``, sadly for the moment the
language is lost during the process.
Contributing
============
Bugs in the content should be reported to the
`Python bug tracker <https://github.com/python/cpython/issues>`_.
Bugs in the toolset should be reported to the tools themselves.
To help with the documentation, or report any problems, please leave a message
on `discuss.python.org <https://discuss.python.org/c/documentation>`_.
---
### Doc About (`Doc/about.rst`)
========================
About this documentation
========================
Python's documentation is generated from `reStructuredText`_ sources
using `Sphinx`_, a documentation generator originally created for Python
and now maintained as an independent project.
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Sphinx: https://www.sphinx-doc.org/
.. In the online version of this documentation, you can submit comments and suggest
changes directly on the documentation pages.
Development of the documentation and its toolchain is an entirely volunteer
effort, just like Python itself. If you want to contribute, please take a
look at the :ref:`reporting-bugs` page for information on how to do so. New
volunteers are always welcome!
Many thanks go to:
* Fred L. Drake, Jr., the creator of the original Python documentation toolset
and author of much of the content;
* the `Docutils <https://docutils.sourceforge.io/>`_ project for creating
reStructuredText and the Docutils suite;
* Fredrik Lundh for his Alternative Python Reference project from which Sphinx
got many good ideas.
Contributors to the Python documentation
----------------------------------------
Many people have contributed to the Python language, the Python standard
library, and the Python documentation. See the `CPython
GitHub repository <https://github.com/python/cpython/graphs/contributors>`__
for a partial list of contributors.
It is only with the input and contributions of the Python community
that Python has such wonderful documentation -- Thank You!
---
### Doc Bugs (`Doc/bugs.rst`)
.. _reporting-bugs:
*****************
Dealing with Bugs
*****************
Python is a mature programming language which has established a reputation for
stability. In order to maintain this reputation, the developers would like to
know of any deficiencies you find in Python.
It can be sometimes faster to fix bugs yourself and contribute patches to
Python as it streamlines the process and involves fewer people. Learn how to
:ref:`contribute <contributing-to-python>`.
.. _reporting-documentation-bugs:
Documentation bugs
==================
If you find a bug in this documentation or would like to propose an improvement,
please submit a bug report on the :ref:`issue tracker <using-the-tracker>`. If you
have a suggestion on how to fix it, include that as well.
.. only:: translation
If the bug or suggested improvement concerns the translation of this
documentation, submit the report to the
`translationβs repository <TRANSLATION_REPO_>`_ instead.
You can also open a discussion item on our
`Documentation Discourse forum <https://discuss.python.org/c/documentation/26>`_.
If you find a bug in the theme (HTML / CSS / JavaScript) of the
documentation, please submit a bug report on the `python-doc-theme issue
tracker <https://github.com/python/python-docs-theme>`_.
.. seealso::
`Documentation bugs`_
A list of documentation bugs that have been submitted to the Python issue tracker.
`Issue Tracking <https://devguide.python.org/tracker/>`_
Overview of the process involved in reporting an improvement on the tracker.
`Helping with Documentation <https://devguide.python.org/docquality/#helping-with-documentation>`_
Comprehensive guide for individuals that are interested in contributing to Python documentation.
`Documentation Translations <https://devguide.python.org/documentation/translations/translating/#translation-coordinators>`_
A list of GitHub pages for documentation translation and their coordination teams.
.. _using-the-tracker:
Using the Python issue tracker
==============================
Issue reports for Python itself should be submitted via the GitHub issues
tracker (https://github.com/python/cpython/issues).
The GitHub issues tracker offers a web form which allows pertinent information
to be entered and submitted to the developers.
The first step in filing a report is to determine whether the problem has
already been reported. The advantage in doing so, aside from saving the
developers' time, is that you learn what has been done to fix it; it may be that
the problem has already been fixed for the next release, or additional
information is needed (in which case you are welcome to provide it if you can!).
To do this, search the tracker using the search box at the top of the page.
If the problem you're reporting is not already in the list, log in to GitHub.
If you don't already have a GitHub account, create a new account using the
"Sign up" link.
It is not possible to submit a bug report anonymously.
Being now logged in, you can submit an issue.
Click on the "New issue" button in the top bar to report a new issue.
The submission form has two fields, "Title" and "Comment".
For the "Title" field, enter a *very* short description of the problem;
fewer than ten words is good.
In the "Comment" field, describe the problem in detail, including what you
expected to happen and what did happen. Be sure to include whether any
extension modules were involved, and what hardware and software platform you
were using (including version information as appropriate).
Each issue report will be reviewed by a developer who will determine what needs to
be done to correct the problem. You will receive an update each time an action is
taken on the issue.
.. seealso::
`How to Report Bugs Effectively <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
Article which goes into some detail about how to create a useful bug report.
This describes what kind of information is useful and why it is useful.
`Bug Writing Guidelines <https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html>`_
Information about writing a good bug report. Some of this is specific to the
Mozilla project, but describes general good practices.
.. _contributing-to-python:
Getting started contributing to Python yourself
===============================================
Beyond just reporting bugs that you find, you are also welcome to submit
patches to fix them. You can find more information on how to get started
patching Python in the `Python Developer's Guide`_. If you have questions,
the `core-mentorship mailing list`_ is a friendly place to get answers to
any and all questions pertaining to the process of fixing issues in Python.
.. _Documentation bugs: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocs
.. _Python Developer's Guide: https://devguide.python.org/
.. _core-mentorship mailing list: https://mail.python.org/mailman3/lists/core-mentorship.python.org/
---
### Doc Constraints (`Doc/constraints.txt`)
# We have upper bounds on our transitive dependencies here
# To avoid new releases unexpectedly breaking our build.
# This file can be updated on an ad-hoc basis,
# though it will probably have to be updated
# whenever Doc/requirements.txt is updated.
# Direct dependencies of Sphinx
babel<3
colorama<0.5
imagesize<2
Jinja2<4
packaging<25
Pygments<3
requests<3
snowballstemmer<3
sphinxcontrib-applehelp<3
sphinxcontrib-devhelp<3
sphinxcontrib-htmlhelp<3
sphinxcontrib-jsmath<2
sphinxcontrib-qthelp<3
sphinxcontrib-serializinghtml<3
# Direct dependencies of Jinja2 (Jinja is a dependency of Sphinx, see above)
MarkupSafe<3
---
### Doc Contents (`Doc/contents.rst`)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Python Documentation contents
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. toctree::
whatsnew/index.rst
tutorial/index.rst
using/index.rst
reference/index.rst
builtins/index.rst
library/index.rst
extending/index.rst
c-api/index.rst
installing/index.rst
howto/index.rst
faq/index.rst
deprecations/index.rst
glossary.rst
about.rst
bugs.rst
copyright.rst
license.rst
---
### Doc Copyright (`Doc/copyright.rst`)
*********
Copyright
*********
Python and this documentation is:
Copyright Β© 2001 Python Software Foundation. All rights reserved.
Copyright Β© 2000 BeOpen.com. All rights reserved.
Copyright Β© 1995-2000 Corporation for National Research Initiatives. All rights
reserved.
Copyright Β© 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
-------
See :ref:`history-and-license` for complete license and permissions information.
---
### Doc Glossary (`Doc/glossary.rst`)
.. _glossary:
********
Glossary
********
.. if you add new entries, keep the alphabetical sorting!
.. glossary::
``>>>``
The default Python prompt of the :term:`interactive` shell. Often
seen for code examples which can be executed interactively in the
interpreter.
``...``
Can refer to:
* The default Python prompt of the :term:`interactive` shell when entering the
code for an indented code block, when within a pair of matching left and
right delimiters (parentheses, square brackets, curly braces or triple
quotes), or after specifying a decorator.
.. index:: single: ...; ellipsis literal
* The three dots form of the :ref:`Ellipsis <bltin-ellipsis-object>` object.
abstract base class
Abstract base classes complement :term:`duck-typing` by
providing a way to define interfaces when other techniques like
:func:`hasattr` would be clumsy or subtly wrong (for example with
:ref:`magic methods <special-lookup>`). ABCs introduce virtual
subclasses, which are classes that don't inherit from a class but are
still recognized by :func:`isinstance` and :func:`issubclass`; see the
:mod:`abc` module documentation. Python comes with many built-in ABCs for
data structures (in the :mod:`collections.abc` module), numbers (in the
:mod:`numbers` module), streams (in the :mod:`io` module), import finders
and loaders (in the :mod:`importlib.abc` module). You can create your own
ABCs with the :mod:`abc` module.
annotate function
A callable that can be called to retrieve the :term:`annotations <annotation>` of
an object. Annotate functions are usually :term:`functions <function>`,
automatically generated as the :attr:`~object.__annotate__` attribute of functions,
classes, and modules. Annotate functions are a subset of
:term:`evaluate functions <evaluate function>`.
annotation
A label associated with a variable, a class
attribute or a function parameter or return value,
used by convention as a :term:`type hint`.
Annotations of local variables cannot be accessed at runtime, but
annotations of global variables, class attributes, and functions
can be retrieved by calling :func:`annotationlib.get_annotations`
on modules, classes, and functions, respectively.
See :term:`variable annotation`, :term:`function annotation`, :pep:`484`,
:pep:`526`, and :pep:`649`, which describe this functionality.
Also see :ref:`annotations-howto`
for best practices on working with annotations.
argument
A value passed to a :term:`function` (or :term:`method`) when calling the
function. There are two kinds of argument:
* :dfn:`keyword argument`: an argument preceded by an identifier (e.g.
``name=``) in a function call or passed as a value in a dictionary
preceded by ``**``. For example, ``3`` and ``5`` are both keyword
arguments in the following calls to :func:`complex`::
complex(real=3, imag=5)
complex(**{'real': 3, 'imag': 5})
* :dfn:`positional argument`: an argument that is not a keyword argument.
Positional arguments can appear at the beginning of an argument list
and/or be passed as elements of an :term:`iterable` preceded by ``*``.
For example, ``3`` and ``5`` are both positional arguments in the
following calls::
complex(3, 5)
complex(*(3, 5))
Arguments are assigned to the named local variables in a function body.
See the :ref:`calls` section for the rules governing this assignment.
Syntactically, any expression can be used to represent an argument; the
evaluated value is assigned to the local variable.
See also the :term:`parameter` glossary entry, the FAQ question on
:ref:`the difference between arguments and parameters
<faq-argument-vs-parameter>`, and :pep:`362`.
asynchronous context manager
An object which controls the environment seen in an
:keyword:`async with` statement by defining :meth:`~object.__aenter__` and
:meth:`~object.__aexit__` methods. Introduced by :pep:`492`.
asynchronous generator
Informally used to mean either an :term:`asynchronous generator
function` or an :term:`asynchronous generator iterator`, depending on
context. The formal terms :term:`asynchronous generator function` and
:term:`asynchronous generator iterator` are uncommon in practice;
"asynchronous generator" alone is almost always sufficient.
asynchronous generator function
A function which returns an :term:`asynchronous generator iterator`.
It looks like a coroutine function defined with :keyword:`async def`
except that it contains :keyword:`yield` expressions for producing a
series of values usable in an :keyword:`async for` loop. See :pep:`525`.
An asynchronous generator function may contain :keyword:`await`
expressions as well as :keyword:`async for`, and :keyword:`async with`
statements.
asynchronous generator iterator
An object created by an :term:`asynchronous generator function`.
This is an :term:`asynchronous iterator` which when called using the
:meth:`~object.__anext__` method returns an awaitable object which will execute
the body of the asynchronous generator function until the next
:keyword:`yield` expression.
Each :keyword:`yield` temporarily suspends processing, remembering the
execution state (including local variables and pending
try-statements). When the *asynchronous generator iterator* effectively
resumes with another awaitable returned by :meth:`~object.__anext__`, it
picks up where it left off. See :pep:`492` and :pep:`525`.
asynchronous iterable
An object, that can be used in an :keyword:`async for` statement.
Must return an :term:`asynchronous iterator` from its
:meth:`~object.__aiter__` method. Introduced by :pep:`492`.
asynchronous iterator
An object that implements the :meth:`~object.__aiter__` and :meth:`~object.__anext__`
methods. :meth:`~object.__anext__` must return an :term:`awaitable` object.
:keyword:`async for` resolves the awaitables returned by an asynchronous
iterator's :meth:`~object.__anext__` method until it raises a
:exc:`StopAsyncIteration` exception. Introduced by :pep:`492`.
atomic operation
An operation that appears to execute as a single, indivisible step: no
other thread can observe it half-done, and its effects become visible all
at once. Python does not guarantee that high-level statements are atomic
(for example, ``x += 1`` performs multiple bytecode operations and is not
atomic). Atomicity is only guaranteed where explicitly documented. See
also :term:`race condition` and :term:`data race`.
attached thread state
A :term:`thread state` that is active for the current OS thread.
When a :term:`thread state` is attached, the OS thread has
access to the full Python C API and can safely invoke the
bytecode interpreter.
Unless a function explicitly notes otherwise, attempting to call
the C API without an attached thread state will result in a fatal
error or undefined behavior. A thread state can be attached and detached
explicitly by the user through the C API, or implicitly by the runtime,
including during blocking C calls and by the bytecode interpreter in between
calls.
On most builds of Python, having an attached thread state implies that the
caller holds the :term:`GIL` for the current interpreter, so only
one OS thread can have an attached thread state at a given moment. In
:term:`free-threaded builds <free-threaded build>` of Python, threads can
concurrently hold an attached thread state, allowing for true parallelism of
the bytecode interpreter.
attribute
A value associated with an object which is usually referenced by name
using dotted expressions.
For example, if an object *o* has an attribute
*a* it would be referenced as *o.a*.
It is possible to give an object an attribute whose name is not an
identifier as defined by :ref:`identifiers`, for example using
:func:`setattr`, if the object allows it.
Such an attribute will not be accessible using a dotted expression,
and would instead need to be retrieved with :func:`getattr`.
awaitable
An object that can be used in an :keyword:`await` expression. Can be
a :term:`coroutine` or an object with an :meth:`~object.__await__` method.
See also :pep:`492`.
BDFL
Benevolent Dictator For Life, a.k.a. `Guido van Rossum
<https://gvanrossum.github.io/>`_, Python's creator.
binary file
A :term:`file object` able to read and write
:term:`bytes-like objects <bytes-like object>`.
Examples of binary files are files opened in binary mode (``'rb'``,
``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer <sys.stdin>`,
:data:`sys.stdout.buffer <sys.stdout>`, and instances of
:class:`io.BytesIO` and :class:`gzip.GzipFile`.
See also :term:`text file` for a file object able to read and write
:class:`str` objects.
borrowed reference
In Python's C API, a borrowed reference is a reference to an object,
where the code using the object does not own the reference.
It becomes a dangling
pointer if the object is destroyed. For example, a garbage collection can
remove the last :term:`strong reference` to the object and so destroy it.
Calling :c:func:`Py_INCREF` on the :term:`borrowed reference` is
recommended to convert it to a :term:`strong reference` in-place, except
when the object cannot be destroyed before the last usage of the borrowed
reference. The :c:func:`Py_NewRef` function can be used to create a new
:term:`strong reference`.
bytes-like object
An object that supports the :ref:`bufferobjects` and can
export a C-:term:`contiguous` buffer. This includes all :class:`bytes`,
:class:`bytearray`, and :class:`array.array` objects, as well as many
common :class:`memoryview` objects. Bytes-like objects can
be used for various operations that work with binary data; these include
compression, saving to a binary file, and sending over a socket.
Some operations need the binary data to be mutable. The documentation
often refers to these as "read-write bytes-like objects". Example
mutable buffer objects include :class:`bytearray` and a
:class:`memoryview` of a :class:`bytearray`.
Other operations require the binary data to be stored in
immutable objects ("read-only bytes-like objects"); examples
of these include :class:`bytes` and a :class:`memoryview`
of a :class:`bytes` object.
bytecode
Python source code is compiled into bytecode, the internal representation
of a Python program in the CPython interpreter. The bytecode is also
cached in ``.pyc`` files so that executing the same file is
faster the second time (recompilation from source to bytecode can be
avoided). This "intermediate language" is said to run on a
:term:`virtual machine` that executes the machine code corresponding to
each bytecode. Do note that bytecodes are not expected to work between
different Python virtual machines, nor to be stable between Python
releases.
A list of bytecode instructions can be found in the documentation for
:ref:`the dis module <bytecodes>`.
callable
A callable is an object that can be called, possibly with a set
of arguments (see :term:`argument`), with the following syntax::
callable(argument1, argument2, argumentN)
A :term:`function`, and by extension a :term:`method`, is a callable.
An instance of a class that implements the :meth:`~object.__call__`
method is also a callable.
callback
A subroutine function which is passed as an argument to be executed at
some point in the future.
class
A template for creating user-defined objects. Class definitions
normally contain method definitions which operate on instances of the
class.
class variable
A variable defined in a class and intended to be modified only at
class level (i.e., not in an instance of the class).
closure variable
A :term:`free variable` referenced from a :term:`nested scope` that is defined in an outer
scope rather than being resolved at runtime from the globals or builtin namespaces.
May be explicitly defined with the :keyword:`nonlocal` keyword to allow write access,
or implicitly defined if the variable is only being read.
For example, in the ``inner`` function in the following code, both ``x`` and ``print`` are
:term:`free variables <free variable>`, but only ``x`` is a *closure variable*::
def outer():
x = 0
def inner():
nonlocal x
x += 1
print(x)
return inner
Due to the :attr:`codeobject.co_freevars` attribute (which, despite its name, only
includes the names of closure variables rather than listing all referenced free
variables), the more general :term:`free variable` term is sometimes used even
when the intended meaning is to refer specifically to closure variables.
complex number
An extension of the familiar real number system in which all numbers are
expressed as a sum of a real part and an imaginary part. Imaginary
numbers are real multiples of the imaginary unit (the square root of
``-1``), often written ``i`` in mathematics or ``j`` in
engineering. Python has built-in support for complex numbers, which are
written with this latter notation; the imaginary part is written with a
``j`` suffix, e.g., ``3+1j``. To get access to complex equivalents of the
:mod:`math` module, use :mod:`cmath`. Use of complex numbers is a fairly
advanced mathematical feature. If you're not aware of a need for them,
it's almost certain you can safely ignore them.
concurrency
The ability of a computer program to perform multiple tasks at the same
time. Python provides libraries for writing programs that make use of
different forms of concurrency. :mod:`asyncio` is a library for dealing
with asynchronous tasks and coroutines. :mod:`threading` provides
access to operating system threads and :mod:`multiprocessing` to
operating system processes. Multi-core processors can execute threads and
processes on different CPU cores at the same time (see
:term:`parallelism`).
concurrent modification
When multiple threads modify shared data at the same time. Concurrent
modification without proper synchronization can cause
:term:`race conditions <race condition>`, and might also trigger a
:term:`data race <data race>`, data corruption, or both.
context
This term has different meanings depending on where and how it is used.
Some common meanings:
* The temporary state or environment established by a :term:`context
manager` via a :keyword:`with` statement.
* The collection of keyΒvalue bindings associated with a particular
:class:`contextvars.Context` object and accessed via
:class:`~contextvars.ContextVar` objects. Also see :term:`context
variable`.
* A :class:`contextvars.Context` object. Also see :term:`current
context`.
context management protocol
The :meth:`~object.__enter__` and :meth:`~object.__exit__` methods called
by the :keyword:`with` statement. See :pep:`343`.
context manager
An object which implements the :term:`context management protocol` and
controls the environment seen in a :keyword:`with` statement. See
:pep:`343`.
context variable
A variable whose value depends on which context is the :term:`current
context`. Values are accessed via :class:`contextvars.ContextVar`
objects. Context variables are primarily used to isolate state between
concurrent asynchronous tasks.
contiguous
.. index:: C-contiguous, Fortran contiguous
A buffer is considered contiguous exactly if it is either
*C-contiguous* or *Fortran contiguous*. Zero-dimensional buffers are
C and Fortran contiguous. In one-dimensional arrays, the items
must be laid out in memory next to each other, in order of
increasing indexes starting from zero. In multidimensional
C-contiguous arrays, the last index varies the fastest when
visiting items in order of memory address. However, in
Fortran contiguous arrays, the first index varies the fastest.
coroutine
Coroutines are a more generalized form of subroutines. Subroutines are
entered at one point and exited at another point. Coroutines can be
entered, exited, and resumed at many different points. They can be
implemented with the :keyword:`async def` statement. See also
:pep:`492`.
coroutine function
A function which returns a :term:`coroutine` object. A coroutine
function may be defined with the :keyword:`async def` statement,
and may contain :keyword:`await`, :keyword:`async for`, and
:keyword:`async with` keywords. These were introduced
by :pep:`492`.
CPython
The canonical implementation of the Python programming language, as
distributed on `python.org <https://www.python.org>`_. The term "CPython"
is used when necessary to distinguish this implementation from others
such as Jython or IronPython.
current context
The :term:`context` (:class:`contextvars.Context` object) that is
currently used by :class:`~contextvars.ContextVar` objects to access (get
or set) the values of :term:`context variables <context variable>`. Each
thread has its own current context. Frameworks for executing asynchronous
tasks (see :mod:`asyncio`) associate each task with a context which
becomes the current context whenever the task starts or resumes execution.
cyclic isolate
A subgroup of one or more objects that reference each other in a reference
cycle, but are not referenced by objects outside the group. The goal of
the :term:`cyclic garbage collector <garbage collection>` is to identify these groups and break the reference
cycles so that the memory can be reclaimed.
data race
A situation where multiple threads access the same memory location
concurrently, at least one of the accesses is a write, and the threads
do not use any synchronization to control their access. Data races
lead to :term:`non-deterministic` behavior and can cause data corruption.
Proper use of :term:`locks <lock>` and other :term:`synchronization primitives
<synchronization primitive>` prevents data races. Note that data races
can only happen in native code, but that :term:`native code` might be
exposed in a Python API. See also :term:`race condition` and
:term:`thread-safe`.
deadlock
A situation in which two or more tasks (threads, processes, or coroutines)
wait indefinitely for each other to release resources or complete actions,
preventing any from making progress. For example, if thread A holds lock
1 and waits for lock 2, while thread B holds lock 2 and waits for lock 1,
both threads will wait indefinitely. In Python this often arises from
acquiring multiple locks in conflicting orders or from circular
join/await dependencies. Deadlocks can be avoided by always acquiring
multiple :term:`locks <lock>` in a consistent order. See also
:term:`lock` and :term:`reentrant`.
decorator
A function returning another function, usually applied as a function
transformation using the ``@wrapper`` syntax. Common examples for
decorators are :deco:`classmethod` and :deco:`staticmethod`.
The decorator syntax is merely syntactic sugar, the following two
function definitions are semantically equivalent::
def f(arg):
...
f = staticmethod(f)
@staticmethod
def f(arg):
...
The same concept exists for classes, but is less commonly used there. See
the documentation for :ref:`function definitions <function>` and
:ref:`class definitions <class>` for more about decorators.
descriptor
Any object which defines the methods :meth:`~object.__get__`,
:meth:`~object.__set__`, or :meth:`~object.__delete__`.
When a class attribute is a descriptor, its special
binding behavior is triggered upon attribute lookup. Normally, using
*a.b* to get, set or delete an attribute looks up the object named *b* in
the class dictionary for *a*, but if *b* is a descriptor, the respective
descriptor method gets called. Understanding descriptors is a key to a
deep understanding of Python because they are the basis for many features
including functions, methods, properties, class methods, static methods,
and reference to super classes.
For more information about descriptors' methods, see :ref:`descriptors`
or the :ref:`Descriptor How To Guide <descriptorhowto>`.
dictionary
An associative array, where arbitrary keys are mapped to values. The
keys can be any object with :meth:`~object.__hash__` and
:meth:`~object.__eq__` methods.
Called a hash in Perl.
dictionary comprehension
A compact way to process all or part of the elements in an iterable and
return a dictionary with the results. ``results = {n: n ** 2 for n in
range(10)}`` generates a dictionary containing key ``n`` mapped to
value ``n ** 2``. See :ref:`comprehensions`.
dictionary view
The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
:meth:`dict.items` are called dictionary views. They provide a dynamic
view on the dictionaryβs entries, which means that when the dictionary
changes, the view reflects these changes. To force the
dictionary view to become a full list use ``list(dictview)``. See
:ref:`dict-views`.
docstring
A string literal which appears as the first expression in a class,
function or module. While ignored when the suite is executed, it is
recognized by the compiler and put into the :attr:`~definition.__doc__` attribute
of the enclosing class, function or module. Since it is available via
introspection, it is the canonical place for documentation of the
object.
duck-typing
A programming style which does not look at an object's type to determine
if it has the right interface; instead, the method or attribute is simply
called or used ("If it looks like a duck and quacks like a duck, it
must be a duck.") By emphasizing interfaces rather than specific types,
well-designed code improves its flexibility by allowing polymorphic
substitution. Duck-typing avoids tests using :func:`type` or
:func:`isinstance`. (Note, however, that duck-typing can be complemented
with :term:`abstract base classes <abstract base class>`.) Instead, it
typically employs :func:`hasattr` tests or :term:`EAFP` programming.
dunder
An informal short-hand for "double underscore", used when talking about a
:term:`special method`. For example, ``__init__`` is often pronounced
"dunder init".
EAFP
Easier to ask for forgiveness than permission. This common Python coding
style assumes the existence of valid keys or attributes and catches
exceptions if the assumption proves false. This clean and fast style is
characterized by the presence of many :keyword:`try` and :keyword:`except`
statements. The technique contrasts with the :term:`LBYL` style
common to many other languages such as C.
evaluate function
A function that can be called to evaluate a lazily evaluated attribute
of an object, such as the value of type aliases created with the :keyword:`type`
statement.
exhausted
An :term:`iterator` that has produced all of its values is said to be
:dfn:`exhausted`.
Further attempts to get the next value (for example, calls to
:func:`next`) raise :exc:`StopIteration`
(or :exc:`StopAsyncIteration` in the case of an :term:`asynchronous
iterator`).
expression
A piece of syntax which can be evaluated to some value. In other words,
an expression is an accumulation of expression elements like literals,
names, attribute access, operators or function calls which all return a
value. Not all language constructs
are expressions. There are also :term:`statement`\s which cannot be used
as expressions, such as :keyword:`while`. Assignments are also statements,
not expressions.
extension module
A module written in C or C++, using Python's C API to interact with the
core and with user code.
f-string
f-strings
String literals prefixed with ``f`` or ``F`` are commonly called
"f-strings" which is short for
:ref:`formatted string literals <f-strings>`. See also :pep:`498`.
file object
An object exposing a file-oriented API (with methods such as
:meth:`!read` or :meth:`!write`) to an underlying resource. Depending
on the way it was created, a file object can mediate access to a real
on-disk file or to another type of storage or communication device
(for example standard input/output, in-memory buffers, sockets, pipes,
etc.). File objects are also called :dfn:`file-like objects` or
:dfn:`streams`.
There are actually three categories of file objects: raw
:term:`binary files <binary file>`, buffered
:term:`binary files <binary file>` and :term:`text files <text file>`.
Their interfaces are defined in the :mod:`io` module. The canonical
way to create a file object is by using the :func:`open` function.
file-like object
A synonym for :term:`file object`.
filesystem encoding and error handler
Encoding and error handler used by Python to decode bytes from the
operating system and encode Unicode to the operating system.
The filesystem encoding must guarantee to successfully decode all bytes
below 128. If the file system encoding fails to provide this guarantee,
API functions can raise :exc:`UnicodeError`.
The :func:`sys.getfilesystemencoding` and
:func:`sys.getfilesystemencodeerrors` functions can be used to get the
filesystem encoding and error handler.
The :term:`filesystem encoding and error handler` are configured at
Python startup by the :c:func:`PyConfig_Read` function: see
:c:member:`~PyConfig.filesystem_encoding` and
:c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`.
See also the :term:`locale encoding`.
finder
An object that tries to find the :term:`loader` for a module that is
being imported.
There are two types of finder: :term:`meta path finders
<meta path finder>` for use with :data:`sys.meta_path`, and :term:`path
entry finders <path entry finder>` for use with :data:`sys.path_hooks`.
See :ref:`finders-and-loaders` and :mod:`importlib` for much more detail.
floor division
Mathematical division that rounds down to nearest integer. The floor
division operator is ``//``. For example, the expression ``11 // 4``
evaluates to ``2`` in contrast to the ``2.75`` returned by float true
division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75``
rounded *downward*. See :pep:`238`.
free threading
A threading model where multiple threads can run Python bytecode
simultaneously within the same interpreter. This is in contrast to
the :term:`global interpreter lock` which allows only one thread to
execute Python bytecode at a time. See :pep:`703`.
free-threaded build
A build of :term:`CPython` that supports :term:`free threading`,
configured using the :option:`--disable-gil` option before compilation.
See :ref:`freethreading-python-howto`.
free variable
Formally, as defined in the :ref:`language execution model <bind_names>`, a free
variable is any variable used in a namespace which is not a local variable in that
namespace. See :term:`closure variable` for an example.
Pragmatically, due to the name of the :attr:`codeobject.co_freevars` attribute,
the term is also sometimes used as a synonym for :term:`closure variable`.
function
A series of statements which returns some value to a caller. It can also
be passed zero or more :term:`arguments <argument>` which may be used in
the execution of the body. See also :term:`parameter`, :term:`method`,
and the :ref:`function` section.
function annotation
An :term:`annotation` of a function parameter or return value.
Function annotations are usually used for
:term:`type hints <type hint>`: for example, this function is expected to take two
:class:`int` arguments and is also expected to have an :class:`int`
return value::
def sum_two_numbers(a: int, b: int) -> int:
return a + b
Function annotation syntax is explained in section :ref:`function`.
See :term:`variable annotation` and :pep:`484`,
which describe this functionality.
Also see :ref:`annotations-howto`
for best practices on working with annotations.
__future__
A :ref:`future statement <future>`, ``from __future__ import <feature>``,
directs the compiler to compile the current module using syntax or
semantics that will become standard in a future release of Python.
The :mod:`__future__` module documents the possible values of
*feature*. By importing this module and evaluating its variables,
you can see when a new feature was first added to the language and
when it will (or did) become the default::
>>> import __future__
>>> __future__.division
_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
garbage collection
The process of freeing memory when it is not used anymore. Python
performs garbage collection via reference counting and a cyclic garbage
collector that is able to detect and break reference cycles. The
garbage collector can be controlled using the :mod:`gc` module.
.. index:: single: generator
generator
Informally used to mean either a :term:`generator function` or a
:term:`generator iterator`, depending on context. The formal terms
:term:`generator function` and :term:`generator iterator` are uncommon
in practice; "generator" alone is almost always sufficient.
.. index:: single: generator function
generator function
A function which returns a :term:`generator` object. It looks like a
normal function except that it contains :keyword:`yield` expressions
for producing a series of values usable in a :keyword:`for`\-loop or
that can be retrieved one at a time with the :func:`next` function.
See :ref:`yieldexpr`.
generator iterator
An object created by a :term:`generator function` or a
:term:`generator expression`.
Each :keyword:`yield` temporarily suspends processing, remembering the
execution state (including local variables and pending try-statements).
When the *generator iterator* resumes, it picks up where it left off
(in contrast to functions which start fresh on every invocation).
Generator iterators also implement the :meth:`~generator.send` method
to send a value into the suspended generator, and the
:meth:`~generator.throw` method to raise an exception at the point
where the generator was paused. See :ref:`generator-methods`.
.. index:: single: generator expression
generator expression
An :term:`expression` that returns an :term:`iterator`. It looks like a normal expression
followed by a :keyword:`!for` clause defining a loop variable, range,
and an optional :keyword:`!if` clause. The combined expression
generates values for an enclosing function::
>>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81
285
generic function
A function composed of multiple functions implementing the same operation
for different types. Which implementation should be used during a call is
determined by the dispatch algorithm.
See also the :term:`single dispatch` glossary entry, the
:deco:`functools.singledispatch` decorator, and :pep:`443`.
generic type
A :term:`type` that can be parameterized; typically a
:ref:`container class<sequence-types>` such as :class:`list` or
:class:`dict`. Used for :term:`type hints <type hint>` and
:term:`annotations <annotation>`.
For more details, see :ref:`generic alias types<types-genericalias>`,
:pep:`483`, :pep:`484`, :pep:`585`, and the :mod:`typing` module.
GIL
See :term:`global interpreter lock`.
global interpreter lock
The mechanism used by the :term:`CPython` interpreter to assure that
only one thread executes Python :term:`bytecode` at a time.
This simplifies the CPython implementation by making the object model
(including critical built-in types such as :class:`dict`) implicitly
safe against concurrent access. Locking the entire interpreter
makes it easier for the interpreter to be multi-threaded, at the
expense of much of the parallelism afforded by multi-processor
machines.
However, some extension modules, either standard or third-party,
are designed so as to release the GIL when doing computationally intensive
tasks such as compression or hashing. Also, the GIL is always released
when doing I/O.
As of Python 3.13, the GIL can be disabled using the :option:`--disable-gil`
build configuration. After building Python with this option, code must be
run with :option:`-X gil=0 <-X>` or after setting the :envvar:`PYTHON_GIL=0 <PYTHON_GIL>`
environment variable. This feature enables improved performance for
multi-threaded applications and makes it easier to use multi-core CPUs
efficiently. For more details, see :pep:`703`.
In prior versions of Python's C API, a function might declare that it
requires the GIL to be held in order to use it. This refers to having an
:term:`attached thread state`.
global state
Data that is accessible throughout a program, such as module-level
variables, class variables, or C static variables in :term:`extension modules
<extension module>`. In multi-threaded programs, global state shared
between threads typically requires synchronization to avoid
:term:`race conditions <race condition>` and
:term:`data races <data race>`.
hash-based pyc
A bytecode cache file that uses the hash rather than the last-modified
time of the corresponding source file to determine its validity. See
:ref:`pyc-invalidation`.
hashable
An object is *hashable* if it has a hash value which never changes during
its lifetime (it needs a :meth:`~object.__hash__` method), and can be
compared to other objects (it needs an :meth:`~object.__eq__` method).
Hashable objects which
compare equal must have the same hash value.
Hashability makes an object usable as a dictionary key and a set member,
because these data structures use the hash value internally.
Most of Python's immutable built-in objects are hashable; mutable
containers (such as lists or dictionaries) are not; immutable
containers (such as tuples and frozensets) are only hashable if
their elements are hashable. Objects which are
instances of user-defined classes are hashable by default. They all
compare unequal (except with themselves), and their hash value is derived
from their :func:`id`.
IDLE
An Integrated Development and Learning Environment for Python.
:ref:`idle` is a basic editor and interpreter environment
which ships with the standard distribution of Python.
immortal
*Immortal objects* are a CPython implementation detail introduced
in :pep:`683`.
If an object is immortal, its :term:`reference count` is never modified,
and therefore it is never deallocated while the interpreter is running.
For example, :const:`True` and :const:`None` are immortal in CPython.
Immortal objects can be identified via :func:`sys._is_immortal`, or
via :c:func:`PyUnstable_IsImmortal` in the C API.
immutable
An object with a fixed value. Immutable objects include numbers, strings and
tuples. Such an object cannot be altered. A new object has to
be created if a different value has to be stored. They play an important
role in places where a constant hash value is needed, for example as a key
in a dictionary. Immutable objects are inherently :term:`thread-safe`
because their state cannot be modified after creation, eliminating concerns
about improperly synchronized :term:`concurrent modification`.
import path
A list of locations (or :term:`path entries <path entry>`) that are
searched by the :term:`path based finder` for modules to import. During
import, this list of locations usually comes from :data:`sys.path`, but
for subpackages it may also come from the parent package's ``__path__``
attribute.
importing
The process by which Python code in one module is made available to
Python code in another module.
importer
An object that both finds and loads a module; both a
:term:`finder` and :term:`loader` object.
index
A numeric value that represents the position of an element in
a :term:`sequence`.
In Python, indexing starts at zero.
For example, ``things[0]`` names the *first* element of ``things``;
``things[1]`` names the second one.
In some contexts, Python allows negative indexes for counting from the
end of a sequence, and indexing using :term:`slices <slice>`.
See also :term:`subscript`.
interactive
Python has an interactive interpreter which means you can enter
statements and expressions at the interpreter prompt, immediately
execute them and see their results. Just launch ``python`` with no
arguments (possibly by selecting it from your computer's main
menu). It is a very powerful way to test out new ideas or inspect
modules and packages (remember ``help(x)``). For more on interactive
mode, see :ref:`tut-interac`.
interpreted
Python is an interpreted language, as opposed to a compiled one,
though the distinction can be blurry because of the presence of the
bytecode compiler. This means that source files can be run directly
without explicitly creating an executable which is then run.
Interpreted languages typically have a shorter development/debug cycle
than compiled ones, though their programs generally also run more
slowly. See also :term:`interactive`.
interpreter shutdown
When asked to shut down, the Python interpreter enters a special phase
where it gradually releases all allocated resources, such as modules
and various critical internal structures. It also makes several calls
to the :term:`garbage collector <garbage collection>`. This can trigger
the execution of code in user-defined destructors or weakref callbacks.
Code executed during the shutdown phase can encounter various
exceptions as the resources it relies on may not function anymore
(common examples are library modules or the warnings machinery).
The main reason for interpreter shutdown is that the ``__main__`` module
or the script being run has finished executing.
iterable
An object capable of returning its members one at a time. Examples of
iterables include all sequence types (such as :class:`list`, :class:`str`,
and :class:`tuple`) and some non-sequence types like :class:`dict`,
:term:`file objects <file object>`, and objects of any classes you define
with an :meth:`~object.__iter__` method or with a
:meth:`~object.__getitem__` method
that implements :term:`sequence` semantics.
Iterables can be
used in a :keyword:`for` loop and in many other places where a sequence is
needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed
as an argument to the built-in function :func:`iter`, it returns an
iterator for the object. This iterator is good for one pass over the set
of values. When using iterables, it is usually not necessary to call
:func:`iter` or deal with iterator objects yourself. The :keyword:`for`
statement does that automatically for you, creating a temporary unnamed
variable to hold the iterator for the duration of the loop. See also
:term:`iterator`, :term:`sequence`, and :term:`generator`.
iterator
An object representing a stream of data. Repeated calls to the iterator's
:meth:`~iterator.__next__` method (or passing it to the built-in function
:func:`next`) return successive items in the stream. When no more data
are available a :exc:`StopIteration` exception is raised instead. At this
point, the iterator object is :term:`exhausted` and any further calls to its
:meth:`!__next__` method just raise :exc:`StopIteration` again. Iterators
are required to have an :meth:`~iterator.__iter__` method that returns the iterator
object itself so every iterator is also iterable and may be used in most
places where other iterables are accepted. One notable exception is code
which attempts multiple iteration passes. A container object (such as a
:class:`list`) produces a fresh new iterator each time you pass it to the
:func:`iter` function or use it in a :keyword:`for` loop. Attempting this
with an iterator will just return the same exhausted iterator object used
in the previous iteration pass, making it appear like an empty container.
More information can be found in :ref:`typeiter`.
.. impl-detail::
CPython does not consistently apply the requirement that an iterator
define :meth:`~iterator.__iter__`.
And also please note that :term:`free-threaded <free threading>`
CPython does not guarantee :term:`thread-safe` behavior of iterator
operations.
key
A value that identifies an entry in a :term:`mapping`.
See also :term:`subscript`.
key function
A key function or collation function is a callable that returns a value
used for sorting or ordering. For example, :func:`locale.strxfrm` is
used to produce a sort key that is aware of locale specific sort
conventions.
A number of tools in Python accept key functions to control how elements
are ordered or grouped. They include :func:`min`, :func:`max`,
:func:`sorted`, :meth:`list.sort`, :func:`heapq.merge`,
:func:`heapq.nsmallest`, :func:`heapq.nlargest`, and
:func:`itertools.groupby`.
There are several ways to create a key function. For example. the
:meth:`str.casefold` method can serve as a key function for case insensitive
sorts. Alternatively, a key function can be built from a
:keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``. Also,
:func:`operator.attrgetter`, :func:`operator.itemgetter`, and
:func:`operator.methodcaller` are three key function constructors. See the :ref:`Sorting HOW TO
<sortinghowto>` for examples of how to create and use key functions.
keyword argument
See :term:`argument`.
lambda
An anonymous inline function consisting of a single :term:`expression`
which is evaluated when the function is called. The syntax to create
a lambda function is ``lambda [parameters]: expression``
LBYL
Look before you leap. This coding style explicitly tests for
pre-conditions before making calls or lookups. This style contrasts with
the :term:`EAFP` approach and is characterized by the presence of many
:keyword:`if` statements.
In a multi-threaded environment, the LBYL approach can risk introducing a
:term:`race condition` between "the looking" and "the leaping". For example,
the code, ``if key in mapping: return mapping[key]`` can fail if another
thread removes *key* from *mapping* after the test, but before the lookup.
This issue can be solved with :term:`locks <lock>` or by using the
:term:`EAFP` approach. See also :term:`thread-safe`.
lexical analyzer
Formal name for the *tokenizer*; see :term:`token`.
list
A built-in Python :term:`sequence`. Despite its name it is more akin
to an array in other languages than to a linked list since access to
elements is *O*\ (1). See :ref:`time-complexity`.
list comprehension
A compact way to process all or part of the elements in a sequence and
return a list with the results. ``result = ['{:#04x}'.format(x) for x in
range(256) if x % 2 == 0]`` generates a list of strings containing
even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if`
clause is optional. If omitted, all elements in ``range(256)`` are
processed.
lock
A :term:`synchronization primitive` that allows only one thread at a
time to access a shared resource. A thread must acquire a lock before
accessing the protected resource and release it afterward. If a thread
attempts to acquire a lock that is already held by another thread, it
will block until the lock becomes available. Python's :mod:`threading`
module provides :class:`~threading.Lock` (a basic lock) and
:class:`~threading.RLock` (a :term:`reentrant` lock). Locks are used
to prevent :term:`race conditions <race condition>` and ensure
:term:`thread-safe` access to shared data. Alternative design patterns
to locks exist such as queues, producer/consumer patterns, and
thread-local state. See also :term:`deadlock`, and :term:`reentrant`.
lock-free
An operation that does not acquire any :term:`lock` and uses atomic CPU
instructions to ensure correctness. Lock-free operations can execute
concurrently without blocking each other and cannot be blocked by
operations that hold locks. In :term:`free-threaded <free threading>`
Python, built-in types like :class:`dict` and :class:`list` provide
lock-free read operations, which means other threads may observe
intermediate states during multi-step modifications even when those
modifications hold the :term:`per-object lock`.
loader
An object that loads a module.
It must define the :meth:`!exec_module` and :meth:`!create_module` methods
to implement the :class:`~importlib.abc.Loader` interface.
A loader is typically returned by a :term:`finder`.
See also:
* :ref:`finders-and-loaders`
* :class:`importlib.abc.Loader`
* :pep:`302`
locale encoding
On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
:func:`locale.setlocale(locale.LC_CTYPE, new_locale) <locale.setlocale>`.
On Windows, it is the ANSI code page (ex: ``"cp1252"``).
On Android and VxWorks, Python uses ``"utf-8"`` as the locale encoding.
:func:`locale.getencoding` can be used to get the locale encoding.
See also the :term:`filesystem encoding and error handler`.
magic method
.. index:: pair: magic; method
An informal synonym for :term:`special method`.
mapping
A container object that supports arbitrary key lookups and implements the
methods specified in the :class:`collections.abc.Mapping` or
:class:`collections.abc.MutableMapping`
:ref:`abstract base classes <collections-abstract-base-classes>`. Examples
include :class:`dict`, :class:`collections.defaultdict`,
:class:`collections.OrderedDict` and :class:`collections.Counter`.
meta path finder
A :term:`finder` returned by a search of :data:`sys.meta_path`. Meta path
finders are related to, but different from :term:`path entry finders
<path entry finder>`.
See :class:`importlib.abc.MetaPathFinder` for the methods that meta path
finders implement.
metaclass
The class of a class. Class definitions create a class name, a class
dictionary, and a list of base classes. The metaclass is responsible for
taking those three arguments and creating the class. Most object oriented
programming languages provide a default implementation. What makes Python
special is that it is possible to create custom metaclasses. Most users
never need this tool, but when the need arises, metaclasses can provide
powerful, elegant solutions. They have been used for logging attribute
access, adding thread-safety, tracking object creation, implementing
singletons, and many other tasks.
More information can be found in :ref:`metaclasses`.
method
A function which is defined inside a class body. If called as an attribute
of an instance of that class, the method will get the instance object as
its first :term:`argument` (which is usually called ``self``).
See :term:`function` and :term:`nested scope`.
method resolution order
Method Resolution Order is the order in which base classes are searched
for a member during lookup. See :ref:`python_2.3_mro` for details of the
algorithm used by the Python interpreter since the 2.3 release.
module
An object that serves as an organizational unit of Python code. Modules
have a namespace containing arbitrary Python objects. Modules are loaded
into Python by the process of :term:`importing`.
See also :term:`package`.
module spec
A namespace containing the import-related information used to load a
module. An instance of :class:`importlib.machinery.ModuleSpec`.
See also :ref:`module-specs`.
MRO
See :term:`method resolution order`.
mutable
An :term:`object` with state that is allowed to change during the course
of the program. In multi-threaded programs, mutable objects that are
shared between threads require careful synchronization to avoid
:term:`race conditions <race condition>`. See also :term:`immutable`,
:term:`thread-safe`, and :term:`concurrent modification`.
named tuple
The term "named tuple" applies to any type or class that inherits from
tuple and whose indexable elements are also accessible using named
attributes. The type or class may have other features as well.
Several built-in types are named tuples, including the values returned
by :func:`time.localtime` and :func:`os.stat`. Another example is
:data:`sys.float_info`::
>>> sys.float_info[1] # indexed access
1024
>>> sys.float_info.max_exp # named field access
1024
>>> isinstance(sys.float_info, tuple) # kind of tuple
True
Some named tuples are built-in types (such as the above examples).
Alternatively, a named tuple can be created from a regular class
definition that inherits from :class:`tuple` and that defines named
fields. Such a class can be written by hand, or it can be created by
inheriting :class:`typing.NamedTuple`, or with the factory function
:func:`collections.namedtuple`. The latter techniques also add some
extra methods that may not be found in hand-written or built-in named
tuples.
namespace
The place where a variable is stored. Namespaces are implemented as
dictionaries. There are the local, global and built-in namespaces as well
as nested namespaces in objects (in methods). Namespaces support
modularity by preventing naming conflicts. For instance, the functions
:func:`builtins.open <.open>` and :func:`os.open` are distinguished by
their namespaces. Namespaces also aid readability and maintainability by
making it clear which module implements a function. For instance, writing
:func:`random.seed` or :func:`itertools.islice` makes it clear that those
functions are implemented by the :mod:`random` and :mod:`itertools`
modules, respectively.
namespace package
A :term:`package` which serves only as a container for subpackages.
Namespace packages may have no physical representation,
and specifically are not like a :term:`regular package` because they
have no ``__init__.py`` file.
Namespace packages allow several individually installable packages to have a common parent package.
Otherwise, it is recommended to use a :term:`regular package`.
For more information, see :pep:`420` and :ref:`reference-namespace-package`.
See also :term:`module`.
native code
Code that is compiled to machine instructions and runs directly on the
processor, as opposed to code that is interpreted or runs in a virtual
machine. In the context of Python, native code typically refers to
C, C++, Rust or Fortran code in :term:`extension modules <extension module>`
that can be called from Python. See also :term:`extension module`.
nested scope
The ability to refer to a variable in an enclosing definition. For
instance, a function defined inside another function can refer to
variables in the outer function. Note that nested scopes by default work
only for reference and not for assignment. Local variables both read and
write in the innermost scope. Likewise, global variables read and write
to the global namespace. The :keyword:`nonlocal` allows writing to outer
scopes.
new-style class
Old name for the flavor of classes now used for all class objects. In
earlier Python versions, only new-style classes could use Python's newer,
versatile features like :attr:`~object.__slots__`, descriptors,
properties, :meth:`~object.__getattribute__`, class methods, and static
methods.
non-deterministic
Behavior where the outcome of a program can vary between executions with
the same inputs. In multi-threaded programs, non-deterministic behavior
often results from :term:`race conditions <race condition>` where the
relative timing or interleaving of threads affects the result.
Proper synchronization using :term:`locks <lock>` and other
:term:`synchronization primitives <synchronization primitive>` helps
ensure deterministic behavior.
object
Any data with state (attributes or value) and defined behavior
(methods). Also the ultimate base class of any :term:`new-style
class`.
optimized scope
A scope where target local variable names are reliably known to the
compiler when the code is compiled, allowing optimization of read and
write access to these names. The local namespaces for functions,
generators, coroutines, comprehensions, and generator expressions are
optimized in this fashion. Note: most interpreter optimizations are
applied to all scopes, only those relying on a known set of local
and nonlocal variable names are restricted to optimized scopes.
optional module
An :term:`extension module` that is part of the :term:`standard library`,
but may be absent in some builds of :term:`CPython`,
usually due to missing third-party libraries or because the module
is not available for a given platform.
See :ref:`optional-module-requirements` for a list of optional modules
that require third-party libraries.
package
A Python :term:`module` which can contain submodules or recursively,
subpackages. Technically, a package is a Python module with a
``__path__`` attribute.
See also :term:`regular package` and :term:`namespace package`.
parallelism
Executing multiple operations at the same time (e.g. on multiple CPU
cores). In Python builds with the
:term:`global interpreter lock (GIL) <global interpreter lock>`, only one
thread runs Python bytecode at a time, so taking advantage of multiple
CPU cores typically involves multiple processes
(e.g. :mod:`multiprocessing`) or native extensions that release the GIL.
In :term:`free-threaded <free threading>` Python, multiple Python threads
can run Python code simultaneously on different cores.
parameter
A named entity in a :term:`function` (or method) definition that
specifies an :term:`argument` (or in some cases, arguments) that the
function can accept. There are five kinds of parameter:
* :dfn:`positional-or-keyword`: specifies an argument that can be passed
either :term:`positionally <argument>` or as a :term:`keyword argument
<argument>`. This is the default kind of parameter, for example *foo*
and *bar* in the following::
def func(foo, bar=None): ...
.. _positional-only_parameter:
* :dfn:`positional-only`: specifies an argument that can be supplied only
by position. Positional-only parameters can be defined by including a
``/`` character in the parameter list of the function definition after
them, for example *posonly1* and *posonly2* in the following::
def func(posonly1, posonly2, /, positional_or_keyword): ...
.. _keyword-only_parameter:
* :dfn:`keyword-only`: specifies an argument that can be supplied only
by keyword. Keyword-only parameters can be defined by including a
single var-positional parameter or bare ``*`` in the parameter list
of the function definition before them, for example *kw_only1* and
*kw_only2* in the following::
def func(arg, *, kw_only1, kw_only2): ...
* :dfn:`var-positional`: specifies that an arbitrary sequence of
positional arguments can be provided (in addition to any positional
arguments already accepted by other parameters). Such a parameter can
be defined by prepending the parameter name with ``*``, for example
*args* in the following::
def func(*args, **kwargs): ...
* :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments
can be provided (in addition to any keyword arguments already accepted
by other parameters). Such a parameter can be defined by prepending
the parameter name with ``**``, for example *kwargs* in the example
above.
Parameters can specify both optional and required arguments, as well as
default values for some optional arguments.
See also the :term:`argument` glossary entry, the FAQ question on
:ref:`the difference between arguments and parameters
<faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the
:ref:`function` section, and :pep:`362`.
per-object lock
A :term:`lock` associated with an individual object instance rather than
a global lock shared across all objects. In :term:`free-threaded
<free threading>` Python, built-in types like :class:`dict` and
:class:`list` use per-object locks to allow concurrent operations on
different objects while serializing operations on the same object.
Operations that hold the per-object lock prevent other locking operations
on the same object from proceeding, but do not block :term:`lock-free`
operations.
path entry
A single location on the :term:`import path` which the :term:`path
based finder` consults to find modules for importing.
path entry finder
A :term:`finder` returned by a callable on :data:`sys.path_hooks`
(i.e. a :term:`path entry hook`) which knows how to locate modules given
a :term:`path entry`.
See :class:`importlib.abc.PathEntryFinder` for the methods that path entry
finders implement.
path entry hook
A callable on the :data:`sys.path_hooks` list which returns a :term:`path
entry finder` if it knows how to find modules on a specific :term:`path
entry`.
path based finder
One of the default :term:`meta path finders <meta path finder>` which
searches an :term:`import path` for modules.
path-like object
An object representing a file system path. A path-like object is either
a :class:`str` or :class:`bytes` object representing a path, or an object
implementing the :class:`os.PathLike` protocol. An object that supports
the :class:`os.PathLike` protocol can be converted to a :class:`str` or
:class:`bytes` file system path by calling the :func:`os.fspath` function;
:func:`os.fsdecode` and :func:`os.fsencode` can be used to guarantee a
:class:`str` or :class:`bytes` result instead, respectively. Introduced
by :pep:`519`.
PEP
Python Enhancement Proposal. A PEP is a design document
providing information to the Python community, or describing a new
feature for Python or its processes or environment. PEPs should
provide a concise technical specification and a rationale for proposed
features.
PEPs are intended to be the primary mechanisms for proposing major new
features, for collecting community input on an issue, and for documenting
the design decisions that have gone into Python. The PEP author is
responsible for building consensus within the community and documenting
dissenting opinions.
See :pep:`1`.
portion
A set of files in a single directory (possibly stored in a zip file)
that contribute to a namespace package, as defined in :pep:`420`.
positional argument
See :term:`argument`.
provisional API
A provisional API is one which has been deliberately excluded from
the standard library's backwards compatibility guarantees. While major
changes to such interfaces are not expected, as long as they are marked
provisional, backwards incompatible changes (up to and including removal
of the interface) may occur if deemed necessary by core developers. Such
changes will not be made gratuitously -- they will occur only if serious
fundamental flaws are uncovered that were missed prior to the inclusion
of the API.
Even for provisional APIs, backwards incompatible changes are seen as
a "solution of last resort" - every attempt will still be made to find
a backwards compatible resolution to any identified problems.
This process allows the standard library to continue to evolve over
time, without locking in problematic design errors for extended periods
of time. See :pep:`411` for more details.
provisional package
See :term:`provisional API`.
Python 3000
Nickname for the Python 3.x release line (coined long ago when the
release of version 3 was something in the distant future.) This is also
abbreviated "Py3k".
Pythonic
An idea or piece of code which closely follows the most common idioms
of the Python language, rather than implementing code using concepts
common to other languages. For example, a common idiom in Python is
to loop over all elements of an iterable using a :keyword:`for`
statement. Many other languages don't have this type of construct, so
people unfamiliar with Python sometimes use a numerical counter instead::
for i in range(len(food)):
print(food[i])
As opposed to the cleaner, Pythonic method::
for piece in food:
print(piece)
qualified name
A dotted name showing the "path" from a module's global scope to a
class, function or method defined in that module, as defined in
:pep:`3155`. For top-level functions and classes, the qualified name
is the same as the object's name::
>>> class C:
... class D:
... def meth(self):
... pass
...
>>> C.__qualname__
'C'
>>> C.D.__qualname__
'C.D'
>>> C.D.meth.__qualname__
'C.D.meth'
When used to refer to modules, the *fully qualified name* means the
entire dotted path to the module, including any parent packages,
e.g. ``email.mime.text``::
>>> import email.mime.text
>>> email.mime.text.__name__
'email.mime.text'
race condition
A condition of a program where the behavior
depends on the relative timing or ordering of events, particularly in
multi-threaded programs. Race conditions can lead to
:term:`non-deterministic` behavior and bugs that are difficult to
reproduce. A :term:`data race` is a specific type of race condition
involving unsynchronized access to shared memory. The :term:`LBYL`
coding style is particularly susceptible to race conditions in
multi-threaded code. Using :term:`locks <lock>` and other
:term:`synchronization primitives <synchronization primitive>`
helps prevent race conditions.
reference count
The number of references to an object. When the reference count of an
object drops to zero, it is deallocated. Some objects are
:term:`immortal` and have reference counts that are never modified, and
therefore the objects are never deallocated. Reference counting is
generally not visible to Python code, but it is a key element of the
:term:`CPython` implementation. Programmers can call the
:func:`sys.getrefcount` function to return the
reference count for a particular object.
In :term:`CPython`, reference counts are not considered to be stable
or well-defined values; the number of references to an object, and how
that number is affected by Python code, may be different between
versions.
regular package
A traditional :term:`package`, such as a directory containing an
``__init__.py`` file.
See also :term:`namespace package`.
reentrant
A property of a function or :term:`lock` that allows it to be called or
acquired multiple times by the same thread without causing errors or a
:term:`deadlock`.
For functions, reentrancy means the function can be safely called again
before a previous invocation has completed, which is important when
functions may be called recursively or from signal handlers. Thread-unsafe
functions may be :term:`non-deterministic` if they're called reentrantly in a
multithreaded program.
For locks, Python's :class:`threading.RLock` (reentrant lock) is
reentrant, meaning a thread that already holds the lock can acquire it
again without blocking. In contrast, :class:`threading.Lock` is not
reentrant - attempting to acquire it twice from the same thread will cause
a deadlock.
See also :term:`lock` and :term:`deadlock`.
REPL
An acronym for the "readβevalβprint loop", another name for the
:term:`interactive` interpreter shell.
__slots__
A declaration inside a class that saves memory by pre-declaring space for
instance attributes and eliminating instance dictionaries. Though
popular, the technique is somewhat tricky to get right and is best
reserved for rare cases where there are large numbers of instances in a
memory-critical application.
sequence
An :term:`iterable` which supports efficient element access using integer
indices via the :meth:`~object.__getitem__` special method and defines a
:meth:`~object.__len__` method that returns the length of the sequence.
Some built-in sequence types are :class:`list`, :class:`str`,
:class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
supports :meth:`~object.__getitem__` and :meth:`!__len__`, but is considered a
mapping rather than a sequence because the lookups use arbitrary
:term:`hashable` keys rather than integers.
The :class:`collections.abc.Sequence` abstract base class
defines a much richer interface that goes beyond just
:meth:`~object.__getitem__` and :meth:`~object.__len__`, adding
:meth:`~sequence.count`, :meth:`~sequence.index`,
:meth:`~object.__contains__`, and :meth:`~object.__reversed__`.
Types that implement this expanded
interface can be registered explicitly using
:func:`~abc.ABCMeta.register`. For more documentation on sequence
methods generally, see
:ref:`Common Sequence Operations <typesseq-common>`.
set comprehension
A compact way to process all or part of the elements in an iterable and
return a set with the results. ``results = {c for c in 'abracadabra' if
c not in 'abc'}`` generates the set of strings ``{'r', 'd'}``. See
:ref:`comprehensions`.
single dispatch
A form of :term:`generic function` dispatch where the implementation is
chosen based on the type of a single argument.
slice
An object of type :class:`slice`, used to describe a portion of
a :term:`sequence`.
A slice object is created when using the :ref:`slicing <slicings>` form
of :ref:`subscript notation <subscriptions>`, with colons inside square
brackets, such as in ``variable_name[1:3:5]``.
soft deprecated
A soft deprecated API should not be used in new code,
but it is safe for already existing code to use it.
The API remains documented and tested, but will not be enhanced further.
Soft deprecation, unlike normal deprecation, does not plan on removing the API
and will not emit warnings.
See `PEP 387: Soft Deprecation
<https://peps.python.org/pep-0387/#soft-deprecation>`_.
special method
.. index:: pair: special; method
A method that is called implicitly by Python to execute a certain
operation on a type, such as addition. Such methods have names starting
and ending with double underscores. Special methods are documented in
:ref:`specialnames`.
standard library
The collection of :term:`packages <package>`, :term:`modules <module>`
and :term:`extension modules <extension module>` distributed as a part
of the official Python interpreter package. The exact membership of the
collection may vary based on platform, available system libraries, or
other criteria. Documentation can be found at :ref:`library-index`.
See also :data:`sys.stdlib_module_names` for a list of all possible
standard library module names.
statement
A statement is part of a suite (a "block" of code). A statement is either
an :term:`expression` or one of several constructs with a keyword, such
as :keyword:`if`, :keyword:`while` or :keyword:`for`.
static type checker
An external tool that reads Python code and analyzes it, looking for
issues such as incorrect types. See also :term:`type hints <type hint>`
and the :mod:`typing` module.
stdlib
An abbreviation of :term:`standard library`.
steal
In Python's C API, "*stealing*" an argument means that ownership of the
argument is transferred to the called function.
The caller must not use that reference after the call.
Generally, functions that "steal" an argument do so even if they fail.
See :ref:`api-refcountdetails` for a full explanation.
strong reference
In Python's C API, a strong reference is a reference to an object
which is owned by the code holding the reference. The strong
reference is taken by calling :c:func:`Py_INCREF` when the
reference is created and released with :c:func:`Py_DECREF`
when the reference is deleted.
The :c:func:`Py_NewRef` function can be used to create a strong reference
to an object. Usually, the :c:func:`Py_DECREF` function must be called on
the strong reference before exiting the scope of the strong reference, to
avoid leaking one reference.
See also :term:`borrowed reference`.
subscript
The expression in square brackets of a
:ref:`subscription expression <subscriptions>`, for example,
the ``3`` in ``items[3]``.
Usually used to select an element of a container.
Also called a :term:`key` when subscripting a :term:`mapping`,
or an :term:`index` when subscripting a :term:`sequence`.
synchronization primitive
A basic building block for coordinating (synchronizing) the execution of
multiple threads to ensure :term:`thread-safe` access to shared resources.
Python's :mod:`threading` module provides several synchronization primitives
including :class:`~threading.Lock`, :class:`~threading.RLock`,
:class:`~threading.Semaphore`, :class:`~threading.Condition`,
:class:`~threading.Event`, and :class:`~threading.Barrier`. Additionally,
the :mod:`queue` module provides multi-producer, multi-consumer queues
that are especially useful in multithreaded programs. These
primitives help prevent :term:`race conditions <race condition>` and
coordinate thread execution. See also :term:`lock`.
t-string
t-strings
String literals prefixed with ``t`` or ``T`` are commonly called
"t-strings" which is short for
:ref:`template string literals <t-strings>`.
text encoding
A string in Python is a sequence of Unicode code points (in range
``U+0000``--``U+10FFFF``). To store or transfer a string, it needs to be
serialized as a sequence of bytes.
Serializing a string into a sequence of bytes is known as "encoding", and
recreating the string from the sequence of bytes is known as "decoding".
There are a variety of different text serialization
:ref:`codecs <standard-encodings>`, which are collectively referred to as
"text encodings".
text file
A :term:`file object` able to read and write :class:`str` objects.
Often, a text file actually accesses a byte-oriented datastream
and handles the :term:`text encoding` automatically.
Examples of text files are files opened in text mode (``'r'`` or ``'w'``),
:data:`sys.stdin`, :data:`sys.stdout`, and instances of
:class:`io.StringIO`.
See also :term:`binary file` for a file object able to read and write
:term:`bytes-like objects <bytes-like object>`.
thread state
The information used by the :term:`CPython` runtime to run in an OS thread.
For example, this includes the current exception, if any, and the
state of the bytecode interpreter.
Each thread state is bound to a single OS thread, but threads may have
many thread states available. At most, one of them may be
:term:`attached <attached thread state>` at once.
An :term:`attached thread state` is required to call most
of Python's C API, unless a function explicitly documents otherwise.
The bytecode interpreter only runs under an attached thread state.
Each thread state belongs to a single interpreter, but each interpreter
may have many thread states, including multiple for the same OS thread.
Thread states from multiple interpreters may be bound to the same
thread, but only one can be :term:`attached <attached thread state>` in
that thread at any given moment.
See :ref:`Thread State and the Global Interpreter Lock <threads>` for more
information.
thread-safe
A module, function, or class that behaves correctly when used by multiple
threads concurrently. Thread-safe code uses appropriate
:term:`synchronization primitives <synchronization primitive>` like
:term:`locks <lock>` to protect shared mutable state, or is designed
to avoid shared mutable state entirely. In the
:term:`free-threaded <free threading>` build, built-in types like
:class:`dict`, :class:`list`, and :class:`set` use internal locking
to make many operations thread-safe, although thread safety is not
necessarily guaranteed. Code that is not thread-safe may experience
:term:`race conditions <race condition>` and :term:`data races <data race>`
when used in multi-threaded programs.
token
A small unit of source code, generated by the
:ref:`lexical analyzer <lexical>` (also called the *tokenizer*).
Names, numbers, strings, operators,
newlines and similar are represented by tokens.
The :mod:`tokenize` module exposes Python's lexical analyzer.
The :mod:`token` module contains information on the various types
of tokens.
triple-quoted string
A string which is bound by three instances of either a quotation mark
(") or an apostrophe ('). While they don't provide any functionality
not available with single-quoted strings, they are useful for a number
of reasons. They allow you to include unescaped single and double
quotes within a string and they can span multiple lines without the
use of the continuation character, making them especially useful when
writing docstrings.
type
The type of a Python object determines what kind of object it is; every
object has a type. An object's type is accessible as its
:attr:`~object.__class__` attribute or can be retrieved with
``type(obj)``.
type alias
A synonym for a type, created by assigning the type to an identifier.
Type aliases are useful for simplifying :term:`type hints <type hint>`.
For example::
def remove_gray_shades(
colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
pass
could be made more readable like this::
Color = tuple[int, int, int]
def remove_gray_shades(colors: list[Color]) -> list[Color]:
pass
See :mod:`typing` and :pep:`484`, which describe this functionality.
type hint
An :term:`annotation` that specifies the expected type for a variable, a class
attribute, or a function parameter or return value.
Type hints are optional and are not enforced by Python but
they are useful to :term:`static type checkers <static type checker>`.
They can also aid IDEs with code completion and refactoring.
Type hints of global variables, class attributes, and functions,
but not local variables, can be accessed using
:func:`typing.get_type_hints`.
See :mod:`typing` and :pep:`484`, which describe this functionality.
universal newlines
A manner of interpreting text streams in which all of the following are
recognized as ending a line: the Unix end-of-line convention ``'\n'``,
the Windows convention ``'\r\n'``, and the old Macintosh convention
``'\r'``. See :pep:`278` and :pep:`3116`, as well as
:func:`bytes.splitlines` for an additional use.
variable annotation
An :term:`annotation` of a variable or a class attribute.
When annotating a variable or a class attribute, assignment is optional::
class C:
field: 'annotation'
Variable annotations are usually used for
:term:`type hints <type hint>`: for example this variable is expected to take
:class:`int` values::
count: int = 0
Variable annotation syntax is explained in section :ref:`annassign`.
See :term:`function annotation`, :pep:`484`
and :pep:`526`, which describe this functionality.
Also see :ref:`annotations-howto`
for best practices on working with annotations.
virtual environment
A cooperatively isolated runtime environment that allows Python users
and applications to install and upgrade Python distribution packages
without interfering with the behaviour of other Python applications
running on the same system.
See also :mod:`venv`.
virtual machine
A computer defined entirely in software. Python's virtual machine
executes the :term:`bytecode` emitted by the bytecode compiler.
walrus operator
A light-hearted way to refer to the :ref:`assignment expression
<assignment-expressions>` operator ``:=`` because it looks a bit like a
walrus if you turn your head.
Zen of Python
Listing of Python design principles and philosophies that are helpful in
understanding and using the language. The listing can be found by typing
"``import this``" at the interactive prompt.
---
### Doc Improve Page Nojs (`Doc/improve-page-nojs.rst`)
:orphan:
****************************
Improve a documentation page
****************************
.. This is the no-javascript version of this page. The one most people
will see (with JavaScript enabled) is improve-page.rst. If you edit
this page, please also edit that one, and vice versa.
.. only:: html and not epub
We are always interested to hear ideas about improvements to the documentation.
.. only:: translation
If the bug or suggested improvement concerns the translation of this
documentation, open an issue or edit the page in
`translation's repository <TRANSLATION_REPO_>`_ instead.
You have a few ways to ask questions or suggest changes:
- You can start a discussion about the page on the Python discussion forum.
This link will start a topic in the Documentation category:
`New Documentation topic <https://discuss.python.org/new-topic?category=documentation>`_.
- You can open an issue on the Python GitHub issue tracker. This link will
create a new issue with the "docs" label:
`New docs issue <https://github.com/python/cpython/issues/new?template=documentation.yml>`_.
---
### Doc Improve Page (`Doc/improve-page.rst`)
:orphan:
****************************
Improve a documentation page
****************************
.. This is the JavaScript-enabled version of this page. Another version
(for those with JavaScript disabled) is improve-page-nojs.rst. If you
edit this page, please also edit that one, and vice versa.
.. only:: html and not epub
.. raw:: html
<script>
function applyReplacements(text, params) {
return text
.replace(/PAGETITLE/g, params.get('pagetitle'))
.replace(/PAGEURL/g, params.get('pageurl'))
.replace(/PAGESOURCE/g, params.get('pagesource'));
}
document.addEventListener('DOMContentLoaded', () => {
const params = new URLSearchParams(window.location.search);
const walker = document.createTreeWalker(
document.body,
NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
null
);
while (walker.nextNode()) {
const node = walker.currentNode;
if (node.nodeType === Node.TEXT_NODE) {
node.textContent = applyReplacements(node.textContent, params)
} else if (node.nodeName === 'A' && node.href) {
node.setAttribute('href', applyReplacements(node.getAttribute('href'), params));
}
}
});
</script>
We are always interested to hear ideas about improvements to the documentation.
You were reading "PAGETITLE" at `<PAGEURL>`_. The source for that page is on
`GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_.
.. only:: translation
If the bug or suggested improvement concerns the translation of this
documentation, open an issue or edit the page in
`translation's repository <TRANSLATION_REPO_>`_ instead.
You have a few ways to ask questions or suggest changes:
- You can start a discussion about the page on the Python discussion forum.
This link will start a pre-populated topic:
`Question about page "PAGETITLE" <https://discuss.python.org/new-topic?category=documentation&title=Question+about+page+%22PAGETITLE%22&body=About+the+page+at+PAGEURL%3A>`_.
- You can open an issue on the Python GitHub issue tracker. This link will
create a new pre-populated issue:
`Docs: problem with page "PAGETITLE" <https://github.com/python/cpython/issues/new?template=documentation.yml&title=Docs%3A+problem+with+page+%22PAGETITLE%22&description=The+page+at+PAGEURL+has+a+problem%3A>`_.
- You can `edit the page on GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_
to open a pull request and begin the contribution process.
---
### Doc Requirements (`Doc/requirements.txt`)
# Requirements to build the Python documentation
#
# Note that when updating this file, you will likely also have to update
# the Doc/constraints.txt file.
# The Sphinx version is pinned so that new versions that introduce new warnings
# won't suddenly cause build failures. Updating the version is fine as long
# as no warnings are raised by doing so.
# Keep this version in sync with ``Doc/conf.py``.
sphinx<9.0.0
pygments>=2.21
blurb
sphinx-linklint
sphinx-notfound-page~=1.0.0
sphinxext-opengraph~=0.13.0
sphinxext-rediraffe
# The theme used by the documentation is stored separately, so we need
# to install that as well.
python-docs-theme>=2023.3.1,!=2023.7
-c constraints.txt
---
### Doc Builtins Constants (`Doc/builtins/constants.rst`)
.. _built-in-consts:
Built-in Constants
==================
A small number of constants live in the built-in namespace. They are:
.. data:: False
The false value of the :class:`bool` type. Assignments to ``False``
are illegal and raise a :exc:`SyntaxError`.
.. data:: True
The true value of the :class:`bool` type. Assignments to ``True``
are illegal and raise a :exc:`SyntaxError`.
.. data:: None
An object frequently used to represent the absence of a value, as when
default arguments are not passed to a function. Assignments to ``None``
are illegal and raise a :exc:`SyntaxError`.
``None`` is the sole instance of the :class:`~types.NoneType` type.
.. data:: NotImplemented
A special value which should be returned by the binary special methods
(e.g. :meth:`~object.__eq__`, :meth:`~object.__lt__`, :meth:`~object.__add__`, :meth:`~object.__rsub__`,
etc.) to indicate that the operation is not implemented with respect to
the other type; may be returned by the in-place binary special methods
(e.g. :meth:`~object.__imul__`, :meth:`~object.__iand__`, etc.) for the same purpose.
It should not be evaluated in a boolean context.
:data:`!NotImplemented` is the sole instance of the :class:`types.NotImplementedType` type.
.. note::
When a binary (or in-place) method returns :data:`!NotImplemented` the
interpreter will try the reflected operation on the other type (or some
other fallback, depending on the operator). If all attempts return
:data:`!NotImplemented`, the interpreter will raise an appropriate exception.
Incorrectly returning :data:`!NotImplemented` will result in a misleading
error message or the :data:`!NotImplemented` value being returned to Python code.
See :ref:`implementing-the-arithmetic-operations` for examples.
.. caution::
:data:`!NotImplemented` and :exc:`!NotImplementedError` are not
interchangeable. This constant should only be used as described
above; see :exc:`NotImplementedError` for details on correct usage
of the exception.
.. versionchanged:: 3.9
Evaluating :data:`!NotImplemented` in a boolean context was deprecated.
.. versionchanged:: 3.14
Evaluating :data:`!NotImplemented` in a boolean context now raises a :exc:`TypeError`.
It previously evaluated to :const:`True` and emitted a :exc:`DeprecationWarning`
since Python 3.9.
.. index:: single: ...; ellipsis literal
.. data:: Ellipsis
The same as the ellipsis literal "``...``", an object frequently used to
indicate that something is omitted. Assignment to ``Ellipsis`` is possible, but
assignment to ``...`` raises a :exc:`SyntaxError`.
``Ellipsis`` is the sole instance of the :class:`types.EllipsisType` type.
.. data:: __debug__
This constant is true if Python was not started with an :option:`-O` option.
See also the :keyword:`assert` statement.
.. note::
The names :data:`None`, :data:`False`, :data:`True` and :data:`__debug__`
cannot be reassigned (assignments to them, even as an attribute name, raise
:exc:`SyntaxError`), so they can be considered "true" constants.
.. _site-consts:
Constants added by the :mod:`site` module
-----------------------------------------
The :mod:`site` module (which is imported automatically during startup, except
if the :option:`-S` command-line option is given) adds several constants to the
built-in namespace. They are useful for the interactive interpreter shell and
should not be used in programs.
.. data:: quit(code=None)
exit(code=None)
Objects that when printed, print a message like "Use quit() or Ctrl-D
(i.e. EOF) to exit", and when accessed directly in the interactive
interpreter or called as functions, raise :exc:`SystemExit` with the
specified exit code.
.. data:: help
:noindex:
Object that when printed, prints the message "Type help() for interactive
help, or help(object) for help about object.", and when accessed directly
in the interactive interpreter, invokes the built-in help system
(see :func:`help`).
.. data:: copyright
credits
Objects that when printed or called, print the text of copyright or
credits, respectively.
.. data:: license
Object that when printed, prints the message "Type license() to see the
full license text", and when called, displays the full license text in a
pager-like fashion (one screen at a time).
---
### Doc Builtins Exceptions (`Doc/builtins/exceptions.rst`)
.. _bltin-exceptions:
Built-in Exceptions
===================
.. index::
pair: statement; try
pair: statement; except
In Python, all exceptions must be instances of a class that derives from
:class:`BaseException`. In a :keyword:`try` statement with an :keyword:`except`
clause that mentions a particular class, that clause also handles any exception
classes derived from that class (but not exception classes from which *it* is
derived). Two exception classes that are not related via subclassing are never
equivalent, even if they have the same name.
.. index:: pair: statement; raise
The built-in exceptions listed in this chapter can be generated by the interpreter or
built-in functions. Except where mentioned, they have an "associated value"
indicating the detailed cause of the error. This may be a string or a tuple of
several items of information (e.g., an error code and a string explaining the
code). The associated value is usually passed as arguments to the exception
class's constructor.
User code can raise built-in exceptions. This can be used to test an exception
handler or to report an error condition "just like" the situation in which the
interpreter raises the same exception; but beware that there is nothing to
prevent user code from raising an inappropriate error.
The built-in exception classes can be subclassed to define new exceptions;
programmers are encouraged to derive new exceptions from the :exc:`Exception`
class or one of its subclasses, and not from :exc:`BaseException`. More
information on defining exceptions is available in the Python Tutorial under
:ref:`tut-userexceptions`.
Exception context
-----------------
.. index:: pair: exception; chaining
__cause__ (exception attribute)
__context__ (exception attribute)
__suppress_context__ (exception attribute)
Three attributes on exception objects provide information about the context in
which the exception was raised:
.. attribute:: BaseException.__context__
BaseException.__cause__
BaseException.__suppress_context__
When raising a new exception while another exception
is already being handled, the new exception's
:attr:`!__context__` attribute is automatically set to the handled
exception. An exception may be handled when an :keyword:`except` or
:keyword:`finally` clause, or a :keyword:`with` statement, is used.
This implicit exception context can be
supplemented with an explicit cause by using :keyword:`!from` with
:keyword:`raise`::
raise new_exc from original_exc
The expression following :keyword:`from<raise>` must be an exception or ``None``. It
will be set as :attr:`!__cause__` on the raised exception. Setting
:attr:`!__cause__` also implicitly sets the :attr:`!__suppress_context__`
attribute to ``True``, so that using ``raise new_exc from None``
effectively replaces the old exception with the new one for display
purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`), while
leaving the old exception available in :attr:`!__context__` for introspection
when debugging.
The default traceback display code shows these chained exceptions in
addition to the traceback for the exception itself. An explicitly chained
exception in :attr:`!__cause__` is always shown when present. An implicitly
chained exception in :attr:`!__context__` is shown only if :attr:`!__cause__`
is :const:`None` and :attr:`!__suppress_context__` is false.
In either case, the exception itself is always shown after any chained
exceptions so that the final line of the traceback always shows the last
exception that was raised.
Inheriting from built-in exceptions
-----------------------------------
User code can create subclasses that inherit from an exception type.
It's recommended to only subclass one exception type at a time to avoid
any possible conflicts between how the bases handle the ``args``
attribute, as well as due to possible memory layout incompatibilities.
.. impl-detail::
Most built-in exceptions are implemented in C for efficiency, see:
:source:`Objects/exceptions.c`. Some have custom memory layouts
which makes it impossible to create a subclass that inherits from
multiple exception types. The memory layout of a type is an implementation
detail and might change between Python versions, leading to new
conflicts in the future. Therefore, it's recommended to avoid
subclassing multiple exception types altogether.
Base classes
------------
The following exceptions are used mostly as base classes for other exceptions.
.. exception:: BaseException
The base class for all built-in exceptions. It is not meant to be directly
inherited by user-defined classes (for that, use :exc:`Exception`). If
:func:`str` is called on an instance of this class, the representation of
the argument(s) to the instance are returned, or the empty string when
there were no arguments.
.. attribute:: args
The tuple of arguments given to the exception constructor. Some built-in
exceptions (like :exc:`OSError`) expect a certain number of arguments and
assign a special meaning to the elements of this tuple, while others are
usually called only with a single string giving an error message.
.. method:: with_traceback(tb)
This method sets *tb* as the new traceback for the exception and returns
the exception object. It was more commonly used before the exception
chaining features of :pep:`3134` became available. The following example
shows how we can convert an instance of ``SomeException`` into an
instance of ``OtherException`` while preserving the traceback. Once
raised, the current frame is pushed onto the traceback of the
``OtherException``, as would have happened to the traceback of the
original ``SomeException`` had we allowed it to propagate to the caller. ::
try:
...
except SomeException:
tb = sys.exception().__traceback__
raise OtherException(...).with_traceback(tb)
.. attribute:: __traceback__
A writable field that holds the
:ref:`traceback object <traceback-objects>` associated with this
exception. See also: :ref:`raise`.
.. method:: add_note(note)
Add the string ``note`` to the exception's notes which appear in the standard
traceback after the exception string. A :exc:`TypeError` is raised if ``note``
is not a string.
.. versionadded:: 3.11
.. attribute:: __notes__
A list of the notes of this exception, which were added with :meth:`add_note`.
This attribute is created when :meth:`add_note` is called.
.. versionadded:: 3.11
.. exception:: Exception
All built-in, non-system-exiting exceptions are derived from this class. All
user-defined exceptions should also be derived from this class.
.. exception:: ArithmeticError
The base class for those built-in exceptions that are raised for various
arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`,
:exc:`FloatingPointError`.
.. exception:: BufferError
Raised when a :ref:`buffer <bufferobjects>` related operation cannot be
performed.
.. exception:: LookupError
The base class for the exceptions that are raised when a key or index used on
a mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. This
can be raised directly by :func:`codecs.lookup`.
Concrete exceptions
-------------------
The following exceptions are the exceptions that are usually raised.
.. exception:: AssertionError
.. index:: pair: statement; assert
Raised when an :keyword:`assert` statement fails.
.. exception:: AttributeError
Raised when an attribute reference (see :ref:`attribute-references`) or
assignment fails. (When an object does not support attribute references or
attribute assignments at all, :exc:`TypeError` is raised.)
The optional *name* and *obj* keyword-only arguments
set the corresponding attributes:
.. attribute:: name
The name of the attribute that was attempted to be accessed.
.. attribute:: obj
The object that was accessed for the named attribute.
When possible, :attr:`name` and :attr:`obj` are set automatically.
.. versionchanged:: 3.10
Added the :attr:`name` and :attr:`obj` attributes.
.. exception:: EOFError
Raised when the :func:`input` function hits an end-of-file condition (EOF)
without reading any data. (Note: the :meth:`io.TextIOBase.read` and
:meth:`io.IOBase.readline` methods return an empty string when they hit EOF.)
.. exception:: FloatingPointError
Not currently used.
.. exception:: GeneratorExit
Raised when a :term:`generator` or :term:`coroutine` is closed;
see :meth:`generator.close` and :meth:`coroutine.close`. It
directly inherits from :exc:`BaseException` instead of :exc:`Exception` since
it is technically not an error.
.. exception:: ImportError
Raised when the :keyword:`import` statement has troubles trying to
load a module. Also raised when the "from list" in ``from ... import``
has a name that cannot be found.
The optional *name* and *path* keyword-only arguments
set the corresponding attributes:
.. attribute:: name
The name of the module that was attempted to be imported.
.. attribute:: path
The path to any file which triggered the exception.
.. versionchanged:: 3.3
Added the :attr:`name` and :attr:`path` attributes.
.. exception:: ModuleNotFoundError
A subclass of :exc:`ImportError` which is raised by :keyword:`import`
when a module could not be located. It is also raised when ``None``
is found in :data:`sys.modules`.
.. versionadded:: 3.6
.. exception:: ImportCycleError
A subclass of :exc:`ImportError` which is raised when a lazy import fails
because it (directly or indirectly) tries to import itself.
.. versionadded:: 3.15
.. exception:: IndexError
Raised when a sequence subscript is out of range. (Slice indices are
silently truncated to fall in the allowed range; if an index is not an
integer, :exc:`TypeError` is raised.)
.. XXX xref to sequences
.. exception:: KeyError
Raised when a mapping (dictionary) key is not found in the set of existing keys.
.. XXX xref to mapping objects?
.. exception:: KeyboardInterrupt
Raised when the user hits the interrupt key (normally :kbd:`Control-C` or
:kbd:`Delete`). During execution, a check for interrupts is made
regularly. The exception inherits from :exc:`BaseException` so as to not be
accidentally caught by code that catches :exc:`Exception` and thus prevent
the interpreter from exiting.
.. note::
Catching a :exc:`KeyboardInterrupt` requires special consideration.
Because it can be raised at unpredictable points, it may, in some
circumstances, leave the running program in an inconsistent state. It is
generally best to allow :exc:`KeyboardInterrupt` to end the program as
quickly as possible or avoid raising it entirely. (See
:ref:`handlers-and-exceptions`.)
.. exception:: MemoryError
Raised when an operation runs out of memory but the situation may still be
rescued (by deleting some objects). The associated value is a string indicating
what kind of (internal) operation ran out of memory. Note that because of the
underlying memory management architecture (C's :c:func:`malloc` function), the
interpreter may not always be able to completely recover from this situation; it
nevertheless raises an exception so that a stack traceback can be printed, in
case a run-away program was the cause.
.. exception:: NameError
Raised when a local or global name is not found. This applies only to
unqualified names. The associated value is an error message that includes the
name that could not be found.
The optional *name* keyword-only argument sets the attribute:
.. attribute:: name
The name of the variable that was attempted to be accessed.
.. versionchanged:: 3.10
Added the :attr:`name` attribute.
.. exception:: NotImplementedError
This exception is derived from :exc:`RuntimeError`. In user defined base
classes, abstract methods should raise this exception when they require
derived classes to override the method, or while the class is being
developed to indicate that the real implementation still needs to be added.
.. note::
It should not be used to indicate that an operator or method is not
meant to be supported at all -- in that case either leave the operator /
method undefined or, if a subclass, set it to :data:`None`.
.. caution::
:exc:`!NotImplementedError` and :data:`!NotImplemented` are not
interchangeable. This exception should only be used as described
above; see :data:`NotImplemented` for details on correct usage of
the built-in constant.
.. exception:: OSError([arg])
OSError(errno, strerror[, filename[, winerror[, filename2]]])
.. index:: pair: module; errno
This exception is raised when a system function returns a system-related
error, including I/O failures such as "file not found" or "disk full"
(not for illegal argument types or other incidental errors).
The second form of the constructor sets the corresponding attributes,
described below. The attributes default to :const:`None` if not
specified. For backwards compatibility, if three arguments are passed,
the :attr:`~BaseException.args` attribute contains only a 2-tuple
of the first two constructor arguments.
The constructor often actually returns a subclass of :exc:`OSError`, as
described in `OS exceptions`_ below. The particular subclass depends on
the final :attr:`.errno` value. This behaviour only occurs when
constructing :exc:`OSError` directly or via an alias, and is not
inherited when subclassing.
.. attribute:: errno
A numeric error code from the C variable :c:data:`errno`.
.. attribute:: winerror
Under Windows, this gives you the native
Windows error code. The :attr:`.errno` attribute is then an approximate
translation, in POSIX terms, of that native error code.
Under Windows, if the *winerror* constructor argument is an integer,
the :attr:`.errno` attribute is determined from the Windows error code,
and the *errno* argument is ignored. On other platforms, the
*winerror* argument is ignored, and the :attr:`winerror` attribute
does not exist.
.. attribute:: strerror
The corresponding error message, as provided by
the operating system. It is formatted by the C
functions :c:func:`!perror` under POSIX, and :c:func:`!FormatMessage`
under Windows.
.. attribute:: filename
filename2
For exceptions that involve a file system path (such as :func:`open` or
:func:`os.unlink`), :attr:`filename` is the file name passed to the function.
For functions that involve two file system paths (such as
:func:`os.rename`), :attr:`filename2` corresponds to the second
file name passed to the function.
.. versionchanged:: 3.3
:exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`,
:exc:`socket.error`, :exc:`select.error` and
:exc:`!mmap.error` have been merged into :exc:`OSError`, and the
constructor may return a subclass.
.. versionchanged:: 3.4
The :attr:`filename` attribute is now the original file name passed to
the function, instead of the name encoded to or decoded from the
:term:`filesystem encoding and error handler`. Also, the *filename2*
constructor argument and attribute was added.
.. exception:: OverflowError
Raised when the result of an arithmetic operation is too large to be
represented. This cannot occur for integers (which would rather raise
:exc:`MemoryError` than give up). However, for historical reasons,
OverflowError is sometimes raised for integers that are outside a required
range. Because of the lack of standardization of floating-point exception
handling in C, most floating-point operations are not checked.
.. exception:: PythonFinalizationError
This exception is derived from :exc:`RuntimeError`. It is raised when
an operation is blocked during interpreter shutdown also known as
:term:`Python finalization <interpreter shutdown>`.
Examples of operations which can be blocked with a
:exc:`PythonFinalizationError` during the Python finalization:
* Creating a new Python thread.
* :meth:`Joining <threading.Thread.join>` a running daemon thread.
* :func:`os.fork`,
* acquiring a lock such as :class:`threading.Lock`, when it is known that
the operation would otherwise deadlock.
See also the :func:`sys.is_finalizing` function.
.. versionadded:: 3.13
Previously, a plain :exc:`RuntimeError` was raised.
.. versionchanged:: 3.14
:meth:`threading.Thread.join` can now raise this exception.
.. versionchanged:: 3.15
This exception may be raised when acquiring :meth:`threading.Lock`
or :meth:`threading.RLock`.
.. exception:: RecursionError
This exception is derived from :exc:`RuntimeError`. It is raised when the
interpreter detects that the maximum recursion depth (see
:func:`sys.getrecursionlimit`) is exceeded.
.. versionadded:: 3.5
Previously, a plain :exc:`RuntimeError` was raised.
.. exception:: ReferenceError
This exception is raised when a weak reference proxy, created by the
:func:`weakref.proxy` function, is used to access an attribute of the referent
after it has been garbage collected. For more information on weak references,
see the :mod:`weakref` module.
.. exception:: RuntimeError
Raised when an error is detected that doesn't fall in any of the other
categories. The associated value is a string indicating what precisely went
wrong.
.. exception:: StopIteration
Raised by built-in function :func:`next` and an :term:`iterator`\'s
:meth:`~iterator.__next__` method to signal that there are no further
items produced by the iterator.
.. attribute:: StopIteration.value
The exception object has a single attribute :attr:`!value`, which is
given as an argument when constructing the exception, and defaults
to :const:`None`.
When a :term:`generator` or :term:`coroutine` function
returns, a new :exc:`StopIteration` instance is
raised, and the value returned by the function is used as the
:attr:`value` parameter to the constructor of the exception.
If a generator code directly or indirectly raises :exc:`StopIteration`,
it is converted into a :exc:`RuntimeError` (retaining the
:exc:`StopIteration` as the new exception's cause).
.. versionchanged:: 3.3
Added ``value`` attribute and the ability for generator functions to
use it to return a value.
.. versionchanged:: 3.5
Introduced the RuntimeError transformation via
``from __future__ import generator_stop``, see :pep:`479`.
.. versionchanged:: 3.7
Enable :pep:`479` for all code by default: a :exc:`StopIteration`
error raised in a generator is transformed into a :exc:`RuntimeError`.
.. exception:: StopAsyncIteration
Must be raised by :meth:`~object.__anext__` method of an
:term:`asynchronous iterator` object to stop the iteration.
.. versionadded:: 3.5
.. exception:: SyntaxError(message, details)
Raised when the parser encounters a syntax error. This may occur in an
:keyword:`import` statement, in a call to the built-in functions
:func:`compile`, :func:`exec`,
or :func:`eval`, or when reading the initial script or standard input
(also interactively).
The :func:`str` of the exception instance returns only the error message.
Details is a tuple whose members are also available as separate attributes.
.. attribute:: filename
The name of the file the syntax error occurred in.
.. attribute:: lineno
Which line number in the file the error occurred in. This is
1-indexed: the first line in the file has a ``lineno`` of 1.
.. attribute:: offset
The column in the line where the error occurred. This is
1-indexed: the first character in the line has an ``offset`` of 1.
.. attribute:: text
The source code text involved in the error.
.. attribute:: end_lineno
Which line number in the file the error occurred ends in. This is
1-indexed: the first line in the file has a ``lineno`` of 1.
.. attribute:: end_offset
The column in the end line where the error occurred finishes. This is
1-indexed: the first character in the line has an ``offset`` of 1.
For errors in f-string fields, the message is prefixed by "f-string: "
and the offsets are offsets in a text constructed from the replacement
expression. For example, compiling f'Bad {a b} field' results in this
args attribute: ('f-string: ...', ('', 1, 2, '(a b)\n', 1, 5)).
.. versionchanged:: 3.10
Added the :attr:`end_lineno` and :attr:`end_offset` attributes.
.. exception:: IndentationError
Base class for syntax errors related to incorrect indentation. This is a
subclass of :exc:`SyntaxError`.
.. exception:: TabError
Raised when indentation contains an inconsistent use of tabs and spaces.
This is a subclass of :exc:`IndentationError`.
.. exception:: SystemError
Raised when the interpreter finds an internal error, but the situation does not
look so serious to cause it to abandon all hope. The associated value is a
string indicating what went wrong (in low-level terms). In :term:`CPython`,
this could be raised by incorrectly using Python's C API, such as returning
a ``NULL`` value without an exception set.
If you're confident that this exception wasn't your fault, or the fault of
a package you're using, you should report this to the author or maintainer
of your Python interpreter.
Be sure to report the version of the Python interpreter (``sys.version``; it is
also printed at the start of an interactive Python session), the exact error
message (the exception's associated value) and if possible the source of the
program that triggered the error.
.. exception:: SystemExit
This exception is raised by the :func:`sys.exit` function. It inherits from
:exc:`BaseException` instead of :exc:`Exception` so that it is not accidentally
caught by code that catches :exc:`Exception`. This allows the exception to
properly propagate up and cause the interpreter to exit. When it is not
handled, the Python interpreter exits; no stack traceback is printed. The
constructor accepts the same optional argument passed to :func:`sys.exit`.
If the value is an integer, it specifies the system exit status (passed to
C's :c:func:`!exit` function); if it is ``None``, the exit status is zero; if
it has another type (such as a string), the object's value is printed and
the exit status is one.
A call to :func:`sys.exit` is translated into an exception so that clean-up
handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be
executed, and so that a debugger can execute a script without running the risk
of losing control. The :func:`os._exit` function can be used if it is
absolutely positively necessary to exit immediately (for example, in the child
process after a call to :func:`os.fork`).
.. attribute:: code
The exit status or error message that is passed to the constructor.
(Defaults to ``None``.)
.. exception:: TypeError
Raised when an operation or function is applied to an object of inappropriate
type. The associated value is a string giving details about the type mismatch.
This exception may be raised by user code to indicate that an attempted
operation on an object is not supported, and is not meant to be. If an object
is meant to support a given operation but has not yet provided an
implementation, :exc:`NotImplementedError` is the proper exception to raise.
Passing arguments of the wrong type (e.g. passing a :class:`list` when an
:class:`int` is expected) should result in a :exc:`TypeError`, but passing
arguments with the wrong value (e.g. a number outside expected boundaries)
should result in a :exc:`ValueError`.
.. exception:: UnboundLocalError
Raised when a reference is made to a local variable in a function or method, but
no value has been bound to that variable. This is a subclass of
:exc:`NameError`.
.. exception:: UnicodeError
Raised when a Unicode-related encoding or decoding error occurs. It is a
subclass of :exc:`ValueError`.
:exc:`UnicodeError` has attributes that describe the encoding or decoding
error. For example, ``err.object[err.start:err.end]`` gives the particular
invalid input that the codec failed on.
.. attribute:: encoding
The name of the encoding that raised the error.
.. attribute:: reason
A string describing the specific codec error.
.. attribute:: object
The object the codec was attempting to encode or decode.
.. attribute:: start
The first index of invalid data in :attr:`object`.
This value should not be negative as it is interpreted as an
absolute offset but this constraint is not enforced at runtime.
.. attribute:: end
The index after the last invalid data in :attr:`object`.
This value should not be negative as it is interpreted as an
absolute offset but this constraint is not enforced at runtime.
.. exception:: UnicodeEncodeError
Raised when a Unicode-related error occurs during encoding. It is a subclass of
:exc:`UnicodeError`.
.. exception:: UnicodeDecodeError
Raised when a Unicode-related error occurs during decoding. It is a subclass of
:exc:`UnicodeError`.
.. exception:: UnicodeTranslateError
Raised when a Unicode-related error occurs during translating. It is a subclass
of :exc:`UnicodeError`.
.. exception:: ValueError
Raised when an operation or function receives an argument that has the
right type but an inappropriate value, and the situation is not described by a
more precise exception such as :exc:`IndexError`.
.. exception:: ZeroDivisionError
Raised when the second argument of a division or modulo operation is zero. The
associated value is a string indicating the type of the operands and the
operation.
The following exceptions are kept for compatibility with previous versions;
starting from Python 3.3, they are aliases of :exc:`OSError`.
.. exception:: EnvironmentError
.. exception:: IOError
.. exception:: WindowsError
Only available on Windows.
OS exceptions
^^^^^^^^^^^^^
The following exceptions are subclasses of :exc:`OSError`, they get raised
depending on the system error code.
.. exception:: BlockingIOError
Raised when an operation would block on an object (e.g. socket) set
for non-blocking operation.
Corresponds to :c:data:`errno` :py:const:`~errno.EAGAIN`, :py:const:`~errno.EALREADY`,
:py:const:`~errno.EWOULDBLOCK` and :py:const:`~errno.EINPROGRESS`.
In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have
one more attribute:
.. attribute:: characters_written
An integer containing the number of **bytes** written to the stream
before it blocked. This attribute is available when using the
buffered I/O classes from the :mod:`io` module.
.. exception:: ChildProcessError
Raised when an operation on a child process failed.
Corresponds to :c:data:`errno` :py:const:`~errno.ECHILD`.
.. exception:: ConnectionError
A base class for connection-related issues.
Subclasses are :exc:`BrokenPipeError`, :exc:`ConnectionAbortedError`,
:exc:`ConnectionRefusedError` and :exc:`ConnectionResetError`.
.. exception:: BrokenPipeError
A subclass of :exc:`ConnectionError`, raised when trying to write on a
pipe while the other end has been closed, or trying to write on a socket
which has been shutdown for writing.
Corresponds to :c:data:`errno` :py:const:`~errno.EPIPE` and :py:const:`~errno.ESHUTDOWN`.
.. exception:: ConnectionAbortedError
A subclass of :exc:`ConnectionError`, raised when a connection attempt
is aborted by the peer.
Corresponds to :c:data:`errno` :py:const:`~errno.ECONNABORTED`.
.. exception:: ConnectionRefusedError
A subclass of :exc:`ConnectionError`, raised when a connection attempt
is refused by the peer.
Corresponds to :c:data:`errno` :py:const:`~errno.ECONNREFUSED`.
.. exception:: ConnectionResetError
A subclass of :exc:`ConnectionError`, raised when a connection is
reset by the peer.
Corresponds to :c:data:`errno` :py:const:`~errno.ECONNRESET`.
.. exception:: FileExistsError
Raised when trying to create a file or directory which already exists.
Corresponds to :c:data:`errno` :py:const:`~errno.EEXIST`.
.. exception:: FileNotFoundError
Raised when a file or directory is requested but doesn't exist.
Corresponds to :c:data:`errno` :py:const:`~errno.ENOENT`.
.. exception:: InterruptedError
Raised when a system call is interrupted by an incoming signal.
Corresponds to :c:data:`errno` :py:const:`~errno.EINTR`.
.. versionchanged:: 3.5
Python now retries system calls when a syscall is interrupted by a
signal, except if the signal handler raises an exception (see :pep:`475`
for the rationale), instead of raising :exc:`InterruptedError`.
.. exception:: IsADirectoryError
Raised when a file operation (such as :func:`os.remove`) is requested
on a directory.
Corresponds to :c:data:`errno` :py:const:`~errno.EISDIR`.
.. exception:: NotADirectoryError
Raised when a directory operation (such as :func:`os.listdir`) is requested on
something which is not a directory. On most POSIX platforms, it may also be
raised if an operation attempts to open or traverse a non-directory file as if
it were a directory.
Corresponds to :c:data:`errno` :py:const:`~errno.ENOTDIR`.
.. exception:: PermissionError
Raised when trying to run an operation without the adequate access
rights - for example filesystem permissions.
Corresponds to :c:data:`errno` :py:const:`~errno.EACCES`,
:py:const:`~errno.EPERM`, and :py:const:`~errno.ENOTCAPABLE`.
.. versionchanged:: 3.11.1
WASI's :py:const:`~errno.ENOTCAPABLE` is now mapped to
:exc:`PermissionError`.
.. exception:: ProcessLookupError
Raised when a given process doesn't exist.
Corresponds to :c:data:`errno` :py:const:`~errno.ESRCH`.
.. exception:: TimeoutError
Raised when a system function timed out at the system level.
Corresponds to :c:data:`errno` :py:const:`~errno.ETIMEDOUT`.
.. versionadded:: 3.3
All the above :exc:`OSError` subclasses were added.
.. seealso::
:pep:`3151` - Reworking the OS and IO exception hierarchy
.. _warning-categories-as-exceptions:
Warnings
--------
The following exceptions are used as warning categories; see the
:ref:`warning-categories` documentation for more details.
.. exception:: Warning
Base class for warning categories.
.. exception:: UserWarning
Base class for warnings generated by user code.
.. exception:: DeprecationWarning
Base class for warnings about deprecated features when those warnings are
intended for other Python developers.
Ignored by the default warning filters, except in the ``__main__`` module
(:pep:`565`). Enabling the :ref:`Python Development Mode <devmode>` shows
this warning.
The deprecation policy is described in :pep:`387`.
.. exception:: PendingDeprecationWarning
Base class for warnings about features which are obsolete and
expected to be deprecated in the future, but are not deprecated
at the moment.
This class is rarely used as emitting a warning about a possible
upcoming deprecation is unusual, and :exc:`DeprecationWarning`
is preferred for already active deprecations.
Ignored by the default warning filters. Enabling the :ref:`Python
Development Mode <devmode>` shows this warning.
The deprecation policy is described in :pep:`387`.
.. exception:: SyntaxWarning
Base class for warnings about dubious syntax.
This warning is typically emitted when compiling Python source code, and usually won't be reported
when running already compiled code.
.. exception:: RuntimeWarning
Base class for warnings about dubious runtime behavior.
.. exception:: FutureWarning
Base class for warnings about deprecated features when those warnings are
intended for end users of applications that are written in Python.
.. exception:: ImportWarning
Base class for warnings about probable mistakes in module imports.
Ignored by the default warning filters. Enabling the :ref:`Python
Development Mode <devmode>` shows this warning.
.. exception:: UnicodeWarning
Base class for warnings related to Unicode.
.. exception:: EncodingWarning
Base class for warnings related to encodings.
See :ref:`io-encoding-warning` for details.
.. versionadded:: 3.10
.. exception:: BytesWarning
Base class for warnings related to :class:`bytes` and :class:`bytearray`.
.. exception:: ResourceWarning
Base class for warnings related to resource usage.
Ignored by the default warning filters. Enabling the :ref:`Python
Development Mode <devmode>` shows this warning.
.. versionadded:: 3.2
.. _lib-exception-groups:
Exception groups
----------------
The following are used when it is necessary to raise multiple unrelated
exceptions. They are part of the exception hierarchy so they can be
handled with :keyword:`except` like all other exceptions. In addition,
they are recognised by :keyword:`except*<except_star>`, which matches
their subgroups based on the types of the contained exceptions.
.. exception:: ExceptionGroup(msg, excs)
.. exception:: BaseExceptionGroup(msg, excs)
Both of these exception types wrap the exceptions in the sequence ``excs``.
The ``msg`` parameter must be a string. The difference between the two
classes is that :exc:`BaseExceptionGroup` extends :exc:`BaseException` and
it can wrap any exception, while :exc:`ExceptionGroup` extends :exc:`Exception`
and it can only wrap subclasses of :exc:`Exception`. This design is so that
``except Exception`` catches an :exc:`ExceptionGroup` but not
:exc:`BaseExceptionGroup`.
The :exc:`BaseExceptionGroup` constructor returns an :exc:`ExceptionGroup`
rather than a :exc:`BaseExceptionGroup` if all contained exceptions are
:exc:`Exception` instances, so it can be used to make the selection
automatic. The :exc:`ExceptionGroup` constructor, on the other hand,
raises a :exc:`TypeError` if any contained exception is not an
:exc:`Exception` subclass.
Exception groups are :ref:`generic <generics>` over the type of their
contained exceptions.
.. impl-detail::
The ``excs`` parameter may be any sequence, but lists and tuples are
specifically processed more efficiently here. For optimal performance,
pass a tuple as ``excs``.
.. attribute:: message
The ``msg`` argument to the constructor. This is a read-only attribute.
.. attribute:: exceptions
A tuple of the exceptions in the ``excs`` sequence given to the
constructor. This is a read-only attribute.
.. method:: subgroup(condition)
Returns an exception group that contains only the exceptions from the
current group that match *condition*, or ``None`` if the result is empty.
The condition can be an exception type or tuple of exception types, in which
case each exception is checked for a match using the same check that is used
in an ``except`` clause. The condition can also be a callable (other than
a type object) that accepts an exception as its single argument and returns
true for the exceptions that should be in the subgroup.
The nesting structure of the current exception is preserved in the result,
as are the values of its :attr:`message`,
:attr:`~BaseException.__traceback__`, :attr:`~BaseException.__cause__`,
:attr:`~BaseException.__context__` and
:attr:`~BaseException.__notes__` fields.
Empty nested groups are omitted from the result.
The condition is checked for all exceptions in the nested exception group,
including the top-level and any nested exception groups. If the condition is
true for such an exception group, it is included in the result in full.
.. versionadded:: 3.13
``condition`` can be any callable which is not a type object.
.. method:: split(condition)
Like :meth:`subgroup`, but returns the pair ``(match, rest)`` where ``match``
is ``subgroup(condition)`` and ``rest`` is the remaining non-matching
part.
.. method:: derive(excs)
Returns an exception group with the same :attr:`message`, but which
wraps the exceptions in ``excs``.
This method is used by :meth:`subgroup` and :meth:`split`, which
are used in various contexts to break up an exception group. A
subclass needs to override it in order to make :meth:`subgroup`
and :meth:`split` return instances of the subclass rather
than :exc:`ExceptionGroup`.
:meth:`subgroup` and :meth:`split` copy the
:attr:`~BaseException.__traceback__`,
:attr:`~BaseException.__cause__`, :attr:`~BaseException.__context__` and
:attr:`~BaseException.__notes__` fields from
the original exception group to the one returned by :meth:`derive`, so
these fields do not need to be updated by :meth:`derive`.
.. doctest::
>>> class MyGroup(ExceptionGroup):
... def derive(self, excs):
... return MyGroup(self.message, excs)
...
>>> e = MyGroup("eg", [ValueError(1), TypeError(2)])
>>> e.add_note("a note")
>>> e.__context__ = Exception("context")
>>> e.__cause__ = Exception("cause")
>>> try:
... raise e
... except Exception as e:
... exc = e
...
>>> match, rest = exc.split(ValueError)
>>> exc, exc.__context__, exc.__cause__, exc.__notes__
(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> match, match.__context__, match.__cause__, match.__notes__
(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), ['a note'])
>>> rest, rest.__context__, rest.__cause__, rest.__notes__
(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> exc.__traceback__ is match.__traceback__ is rest.__traceback__
True
Note that :exc:`BaseExceptionGroup` defines :meth:`~object.__new__`, so
subclasses that need a different constructor signature need to
override that rather than :meth:`~object.__init__`. For example, the following
defines an exception group subclass which accepts an exit_code and
constructs the group's message from it. ::
class Errors(ExceptionGroup):
def __new__(cls, errors, exit_code):
self = super().__new__(Errors, f"exit code: {exit_code}", errors)
self.exit_code = exit_code
return self
def derive(self, excs):
return Errors(excs, self.exit_code)
Like :exc:`ExceptionGroup`, any subclass of :exc:`BaseExceptionGroup` which
is also a subclass of :exc:`Exception` can only wrap instances of
:exc:`Exception`.
.. versionadded:: 3.11
Exception hierarchy
-------------------
The class hierarchy for built-in exceptions is:
.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
:language: text
---
### Doc Builtins Functions (`Doc/builtins/functions.rst`)
.. XXX document all delegations to __special__ methods
.. _built-in-funcs:
Built-in functions
==================
The Python interpreter has a number of functions and types built into it that
are always available. They are listed here in alphabetical order.
+---------------------------------------------------------------------------------------------------+
| Built-in Functions |
+=========================+=======================+=======================+=========================+
| | **A** | | **E** | | **L** | | **R** |
| | :func:`abs` | | :func:`enumerate` | | :func:`len` | | |func-range|_ |
| | :func:`aiter` | | :func:`eval` | | |func-list|_ | | :func:`repr` |
| | :func:`all` | | :func:`exec` | | :func:`locals` | | :func:`reversed` |
| | :func:`anext` | | | | | | :func:`round` |
| | :func:`any` | | **F** | | **M** | | |
| | :func:`ascii` | | :func:`filter` | | :func:`map` | | **S** |
| | | | :func:`float` | | :func:`max` | | |func-set|_ |
| | **B** | | :func:`format` | | |func-memoryview|_ | | :func:`setattr` |
| | :func:`bin` | | |func-frozendict|_ | | :func:`min` | | :func:`sentinel` |
| | :func:`bool` | | |func-frozenset|_ | | | | :func:`slice` |
| | :func:`breakpoint` | | | | **N** | | :func:`sorted` |
| | |func-bytearray|_ | | **G** | | :func:`next` | | :func:`staticmethod` |
| | |func-bytes|_ | | :func:`getattr` | | | | |func-str|_ |
| | | | :func:`globals` | | **O** | | :func:`sum` |
| | **C** | | | | :func:`object` | | :func:`super` |
| | :func:`callable` | | **H** | | :func:`oct` | | |
| | :func:`chr` | | :func:`hasattr` | | :func:`open` | | **T** |
| | :func:`classmethod` | | :func:`hash` | | :func:`ord` | | |func-tuple|_ |
| | :func:`compile` | | :func:`help` | | | | :func:`type` |
| | :func:`complex` | | :func:`hex` | | **P** | | |
| | | | | | :func:`pow` | | **V** |
| | **D** | | **I** | | :func:`print` | | :func:`vars` |
| | :func:`delattr` | | :func:`id` | | :func:`property` | | |
| | |func-dict|_ | | :func:`input` | | | | **Z** |
| | :func:`dir` | | :func:`int` | | | | :func:`zip` |
| | :func:`divmod` | | :func:`isinstance` | | | | |
| | | | :func:`issubclass` | | | | **_** |
| | | | :func:`iter` | | | | :func:`__import__` |
+-------------------------+-----------------------+-----------------------+-------------------------+
.. using :func:`dict` would create a link to another page, so local targets are
used, with replacement texts to make the output in the table consistent
.. |func-dict| replace:: ``dict()``
.. |func-frozendict| replace:: ``frozendict()``
.. |func-frozenset| replace:: ``frozenset()``
.. |func-memoryview| replace:: ``memoryview()``
.. |func-set| replace:: ``set()``
.. |func-list| replace:: ``list()``
.. |func-str| replace:: ``str()``
.. |func-tuple| replace:: ``tuple()``
.. |func-range| replace:: ``range()``
.. |func-bytearray| replace:: ``bytearray()``
.. |func-bytes| replace:: ``bytes()``
.. function:: abs(number, /)
Return the absolute value of a number. The argument may be an
integer, a floating-point number, or an object implementing
:meth:`~object.__abs__`.
If the argument is a complex number, its magnitude is returned.
.. function:: aiter(async_iterable, /)
aiter(callable, /, stop_value, *, stop_exception=StopAsyncIteration)
aiter(callable, /, *, stop_exception)
Return an :term:`asynchronous iterator` object.
The first argument is interpreted very differently
depending on the presence of the other arguments.
Without other arguments,
the single argument must be an :term:`asynchronous iterable`,
and the result is equivalent to calling ``x.__aiter__()``.
If *stop_value* or *stop_exception* is given,
then the first argument must be a callable object.
The asynchronous iterator created in this case
calls *callable* with no arguments and awaits the result
for each call to its :meth:`~object.__anext__` method;
if the awaited value is equal to *stop_value*,
or if the call raises an exception matching *stop_exception*,
:exc:`StopAsyncIteration` will be raised,
otherwise the value will be returned.
The callable is only called when the result of :meth:`~object.__anext__`
is awaited.
*stop_exception* is an exception class or a tuple of exception classes.
If *stop_value* is not specified,
the iteration stops only when the callable raises an exception.
If the callable raises :exc:`StopAsyncIteration`
which does not match *stop_exception*,
it is replaced with a :exc:`RuntimeError`,
as for asynchronous generators (see :pep:`525`).
For example, reading fixed-size chunks from an asynchronous stream
until the end of file is reached::
from functools import partial
async for chunk in aiter(partial(reader.read, 1024), b''):
process_chunk(chunk)
Or consuming an :class:`asyncio.Queue` until it is shut down::
from asyncio import QueueShutDown
async for item in aiter(queue.get, stop_exception=QueueShutDown):
process_item(item)
.. versionadded:: 3.10
.. versionchanged:: 3.16
Added the *stop_value* and *stop_exception* parameters.
.. function:: all(iterable, /)
Return ``True`` if all elements of the *iterable* are true (or if the iterable
is empty). Equivalent to::
def all(iterable):
for element in iterable:
if not element:
return False
return True
.. awaitablefunction:: anext(async_iterator, /)
anext(async_iterator, default, /)
When awaited, return the next item from the given :term:`asynchronous
iterator`, or *default* if given and the iterator is :term:`exhausted`.
This is the async variant of the :func:`next` builtin, and behaves
similarly.
This calls the :meth:`~object.__anext__` method of *async_iterator*,
returning an :term:`awaitable`. Awaiting this returns the next value of the
iterator. If *default* is given, it is returned if the iterator is exhausted,
otherwise :exc:`StopAsyncIteration` is raised.
.. versionadded:: 3.10
.. function:: any(iterable, /)
Return ``True`` if any element of the *iterable* is true. If the iterable
is empty, return ``False``. Equivalent to::
def any(iterable):
for element in iterable:
if element:
return True
return False
.. function:: ascii(object, /)
As :func:`repr`, return a string containing a printable representation of an
object, but escape the non-ASCII characters in the string returned by
:func:`repr` using ``\x``, ``\u``, or ``\U`` escapes. This generates a string
similar to that returned by :func:`repr` in Python 2.
.. function:: bin(integer, /)
Convert an integer number to a binary string prefixed with "0b". The result
is a valid Python expression. If *integer* is not a Python :class:`int` object, it
has to define an :meth:`~object.__index__` method that returns an integer. Some
examples:
>>> bin(3)
'0b11'
>>> bin(-10)
'-0b1010'
If the prefix "0b" is desired or not, you can use either of the following ways.
>>> format(14, '#b'), format(14, 'b')
('0b1110', '1110')
>>> f'{14:#b}', f'{14:b}'
('0b1110', '1110')
See also :func:`enum.bin` to represent negative values as twos-complement.
See also :func:`format` for more information.
.. class:: bool(object=False, /)
Return a Boolean value, i.e. one of ``True`` or ``False``. The argument
is converted using the standard :ref:`truth testing procedure <truth>`.
If the argument is false
or omitted, this returns ``False``; otherwise, it returns ``True``. The
:class:`bool` class is a subclass of :class:`int` (see :ref:`typesnumeric`).
It cannot be subclassed further. Its only instances are ``False`` and
``True`` (see :ref:`typebool`).
.. index:: pair: Boolean; type
.. versionchanged:: 3.7
The parameter is now positional-only.
.. function:: breakpoint(*args, **kws)
This function drops you into the debugger at the call site. Specifically,
it calls :func:`sys.breakpointhook`, passing ``args`` and ``kws`` straight
through. By default, ``sys.breakpointhook()`` calls
:func:`pdb.set_trace` expecting no arguments. In this case, it is
purely a convenience function so you don't have to explicitly import
:mod:`pdb` or type as much code to enter the debugger. However,
:func:`sys.breakpointhook` can be set to some other function and
:func:`breakpoint` will automatically call that, allowing you to drop into
the debugger of choice.
If :func:`sys.breakpointhook` is not accessible, this function will
raise :exc:`RuntimeError`.
By default, the behavior of :func:`breakpoint` can be changed with
the :envvar:`PYTHONBREAKPOINT` environment variable.
See :func:`sys.breakpointhook` for usage details.
Note that this is not guaranteed if :func:`sys.breakpointhook`
has been replaced.
.. audit-event:: builtins.breakpoint breakpointhook breakpoint
.. versionadded:: 3.7
.. _func-bytearray:
.. class:: bytearray(source=b'')
bytearray(source, encoding, errors='strict')
:noindex:
Return a new array of bytes. The :class:`bytearray` class is a mutable
sequence of integers in the range 0 <= x < 256. It has most of the usual
methods of mutable sequences, described in :ref:`typesseq-mutable`, as well
as most methods that the :class:`bytes` type has, see :ref:`bytes-methods`.
The optional *source* parameter can be used to initialize the array in a few
different ways:
* If it is a *string*, you must also give the *encoding* (and optionally,
*errors*) parameters; :func:`bytearray` then converts the string to
bytes using :meth:`str.encode`.
* If it is an *integer*, the array will have that size and will be
initialized with null bytes.
* If it is an object conforming to the :ref:`buffer interface <bufferobjects>`,
a read-only buffer of the object will be used to initialize the bytes array.
* If it is an *iterable*, it must be an iterable of integers in the range
``0 <= x < 256``, which are used as the initial contents of the array.
Without an argument, an array of size 0 is created.
See also :ref:`binaryseq` and :ref:`typebytearray`.
.. _func-bytes:
.. class:: bytes(source=b'')
bytes(source, encoding, errors='strict')
:noindex:
Return a new "bytes" object which is an immutable sequence of integers in
the range ``0 <= x < 256``. :class:`bytes` is an immutable version of
:class:`bytearray` -- it has the same non-mutating methods and the same
indexing and slicing behavior.
Accordingly, constructor arguments are interpreted as for :func:`bytearray`.
Bytes objects can also be created with literals, see :ref:`strings`.
See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`.
.. function:: callable(object, /)
Return :const:`True` if the *object* argument appears callable,
:const:`False` if not. If this returns ``True``, it is still possible that a
call fails, but if it is ``False``, calling *object* will never succeed.
Note that classes are callable (calling a class returns a new instance);
instances are callable if their class has a :meth:`~object.__call__` method.
.. versionadded:: 3.2
This function was first removed in Python 3.0 and then brought back
in Python 3.2.
.. function:: chr(codepoint, /)
Return the string representing a character with the specified Unicode code point.
For example, ``chr(97)`` returns the string ``'a'``, while
``chr(8364)`` returns the string ``'β¬'``. This is the inverse of :func:`ord`.
The valid range for the argument is from 0 through 1,114,111 (0x10FFFF in
base 16). :exc:`ValueError` will be raised if it is outside that range.
.. decorator:: classmethod
Transform a method into a class method.
A class method receives the class as an implicit first argument, just like an
instance method receives the instance. To declare a class method, use this
idiom::
class C:
@classmethod
def f(cls, arg1, arg2): ...
The ``@classmethod`` form is a function :term:`decorator` -- see
:ref:`function` for details.
A class method can be called either on the class (such as ``C.f()``) or on an instance (such
as ``C().f()``). The instance is ignored except for its class. If a class
method is called for a derived class, the derived class object is passed as the
implied first argument.
Class methods are different than C++ or Java static methods. If you want those,
see :func:`staticmethod` in this section.
For more information on class methods, see :ref:`types`.
.. versionchanged:: 3.9
Class methods can now wrap other :term:`descriptors <descriptor>` such as
:func:`property`.
.. versionchanged:: 3.10
Class methods now inherit the method attributes
(:attr:`~function.__module__`, :attr:`~function.__name__`,
:attr:`~function.__qualname__`, :attr:`~function.__doc__` and
:attr:`~function.__annotations__`) and have a new ``__wrapped__``
attribute.
.. deprecated-removed:: 3.11 3.13
Class methods can no longer wrap other :term:`descriptors <descriptor>` such as
:func:`property`.
.. function:: compile(source, filename, mode, flags=0, \
dont_inherit=False, optimize=-1, \
*, module=None)
Compile the *source* into a code or AST object. Code objects can be executed
by :func:`exec` or :func:`eval`. *source* can either be a normal string, a
byte string, or an AST object. Refer to the :mod:`ast` module documentation
for information on how to work with AST objects.
The *filename* argument should give the file from which the code was read;
pass some recognizable value if it wasn't read from a file (``'<string>'`` is
commonly used).
The *mode* argument specifies what kind of code must be compiled; it can be
``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
consists of a single expression, or ``'single'`` if it consists of a single
interactive statement (in the latter case, expression statements that
evaluate to something other than ``None`` will be printed).
The optional arguments *flags* and *dont_inherit* control which
:ref:`compiler options <ast-compiler-flags>` should be activated
and which :ref:`future features <future>` should be allowed. If neither
is present (or both are zero) the code is compiled with the same flags that
affect the code that is calling :func:`compile`. If the *flags*
argument is given and *dont_inherit* is not (or is zero) then the compiler
options and the future statements specified by the *flags* argument are used
in addition to those that would be used anyway. If *dont_inherit* is a
non-zero integer then the *flags* argument is it -- the flags (future
features and compiler options) in the surrounding code are ignored.
Compiler options and future statements are specified by bits which can be
bitwise ORed together to specify multiple options. The bitfield required to
specify a given future feature can be found as the
:attr:`~__future__._Feature.compiler_flag` attribute on the
:class:`~__future__._Feature` instance in the :mod:`__future__` module.
:ref:`Compiler flags <ast-compiler-flags>` can be found in :mod:`ast`
module, with ``PyCF_`` prefix.
The argument *optimize* specifies the optimization level of the compiler; the
default value of ``-1`` selects the optimization level of the interpreter as
given by :option:`-O` options. Explicit levels are ``0`` (no optimization;
``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
or ``2`` (docstrings are removed too).
The optional argument *module* specifies the module name.
It is needed to unambiguous :ref:`filter <warning-filter>` syntax warnings
by module name.
This function raises :exc:`SyntaxError` if the compiled source is invalid,
including a *source* containing a null character or that cannot be decoded;
:exc:`ValueError` if *mode* or *flags* is invalid,
or if a string *source* contains surrogate characters;
:exc:`MemoryError` or :exc:`RecursionError` if *source* is too complex
to parse or compile,
for example an expression with many thousands of nested operators;
and :exc:`OverflowError` if *source* is too large.
If you want to parse Python code into its AST representation, see
:func:`ast.parse`.
.. audit-event:: compile source,filename compile
Raises an :ref:`auditing event <auditing>` ``compile`` with arguments
``source`` and ``filename``. This event may also be raised by implicit
compilation.
.. note::
When compiling a string with multi-line code in ``'single'`` or
``'eval'`` mode, input must be terminated by at least one newline
character. This is to facilitate detection of incomplete and complete
statements in the :mod:`code` module.
.. warning::
It is possible to crash the Python interpreter with a
sufficiently large/complex string when compiling to an AST
object due to stack depth limitations in Python's AST compiler.
.. versionchanged:: 3.2
Allowed use of Windows and Mac newlines. Also, input in ``'exec'`` mode
does not have to end in a newline anymore. Added the *optimize* parameter.
.. versionchanged:: 3.5
Previously, :exc:`TypeError` was raised when null bytes were encountered
in *source*.
.. versionchanged:: 3.8
``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` can now be passed in flags to enable
support for top-level ``await``, ``async for``, and ``async with``.
.. versionchanged:: 3.12
:exc:`SyntaxError` is raised instead of :exc:`ValueError` when null bytes
are encountered in *source*.
.. versionchanged:: 3.15
Added the *module* parameter.
.. class:: complex(number=0, /)
complex(string, /)
complex(real=0, imag=0)
Convert a single string or number to a complex number, or create a
complex number from real and imaginary parts.
Examples:
.. doctest::
>>> complex('+1.23')
(1.23+0j)
>>> complex('-4.5j')
-4.5j
>>> complex('-1.23+4.5j')
(-1.23+4.5j)
>>> complex('\t( -1.23+4.5J )\n')
(-1.23+4.5j)
>>> complex('-Infinity+NaNj')
(-inf+nanj)
>>> complex(1.23)
(1.23+0j)
>>> complex(imag=-4.5)
-4.5j
>>> complex(-1.23, 4.5)
(-1.23+4.5j)
If the argument is a string, it must contain either a real part (in the
same format as for :func:`float`) or an imaginary part (in the same
format but with a ``'j'`` or ``'J'`` suffix), or both real and imaginary
parts (the sign of the imaginary part is mandatory in this case).
The string can optionally be surrounded by whitespaces and the round
parentheses ``'('`` and ``')'``, which are ignored.
The string must not contain whitespace between ``'+'``, ``'-'``, the
``'j'`` or ``'J'`` suffix, and the decimal number.
For example, ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises
:exc:`ValueError`.
More precisely, the input must conform to the :token:`~float:complexvalue`
production rule in the following grammar, after parentheses and leading and
trailing whitespace characters are removed:
.. productionlist:: float
complexvalue: `floatvalue` |
: `floatvalue` ("j" | "J") |
: `floatvalue` `sign` `absfloatvalue` ("j" | "J")
If the argument is a number, the constructor serves as a numeric
conversion like :class:`int` and :class:`float`.
For a general Python object ``x``, ``complex(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__`.
If two arguments are provided or keyword arguments are used, each argument
may be any numeric type (including complex).
If both arguments are real numbers, return a complex number with the real
component *real* and the imaginary component *imag*.
If both arguments are complex numbers, return a complex number with the real
component ``real.real-imag.imag`` and the imaginary component
``real.imag+imag.real``.
If one of arguments is a real number, only its real component is used in
the above expressions.
See also :meth:`complex.from_number` which only accepts a single numeric argument.
If all arguments are omitted, returns ``0j``.
The complex type is described in :ref:`typesnumeric`.
.. versionchanged:: 3.6
Grouping digits with underscores as in code literals is allowed.
.. versionchanged:: 3.8
Falls back to :meth:`~object.__index__` if :meth:`~object.__complex__` and
:meth:`~object.__float__` are not defined.
.. deprecated:: 3.14
Passing a complex number as the *real* or *imag* argument is now
deprecated; it should only be passed as a single positional argument.
.. function:: delattr(object, name, /)
This is a relative of :func:`setattr`. The arguments are an object and a
string. The string must be the name of one of the object's attributes. The
function deletes the named attribute, provided the object allows it. For
example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
*name* need not be a Python identifier (see :func:`setattr`).
.. _func-dict:
.. class:: dict(**kwargs)
dict(mapping, /, **kwargs)
dict(iterable, /, **kwargs)
:noindex:
Create a new dictionary. The :class:`dict` object is the dictionary class.
See also :ref:`typesmapping` for documentation about this class.
For other containers see the built-in :class:`frozendict`, :class:`list`,
:class:`set`, and :class:`tuple` classes, as well as the :mod:`collections` module.
.. function:: dir()
dir(object, /)
Without arguments, return the list of names in the current local scope. With an
argument, attempt to return a list of valid attributes for that object.
If the object has a method named :meth:`~object.__dir__`,
this method will be called and
must return the list of attributes. This allows objects that implement a custom
:func:`~object.__getattr__` or :func:`~object.__getattribute__` function
to customize the way
:func:`dir` reports their attributes.
If the object does not provide :meth:`~object.__dir__`,
the function tries its best to gather information from the object's
:attr:`~object.__dict__` attribute, if defined, and
from its type object. The resulting list is not necessarily complete and may
be inaccurate when the object has a custom :func:`~object.__getattr__`.
The default :func:`dir` mechanism behaves differently with different types of
objects, as it attempts to produce the most relevant, rather than complete,
information:
* If the object is a module object, the list contains the names of the module's
attributes.
* If the object is a type or class object, the list contains the names of its
attributes, and recursively of the attributes of its bases.
* Otherwise, the list contains the object's attributes' names, the names of its
class's attributes, and recursively of the attributes of its class's base
classes.
The resulting list is sorted alphabetically. For example:
>>> import struct
>>> dir() # show the names in the module namespace # doctest: +SKIP
['__builtins__', '__name__', 'struct']
>>> dir(struct) # show the names in the struct module # doctest: +SKIP
['Struct', '__all__', '__builtins__', '__doc__', '__file__',
'__initializing__', '__loader__', '__name__', '__package__',
'_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
'unpack', 'unpack_from']
>>> class Shape:
... def __dir__(self):
... return ['area', 'perimeter', 'location']
...
>>> s = Shape()
>>> dir(s)
['area', 'location', 'perimeter']
.. note::
Because :func:`dir` is supplied primarily as a convenience for use at an
interactive prompt, it tries to supply an interesting set of names more
than it tries to supply a rigorously or consistently defined set of names,
and its detailed behavior may change across releases. For example,
metaclass attributes are not in the result list when the argument is a
class.
.. function:: divmod(a, b, /)
Take two (non-complex) numbers as arguments and return a pair of numbers
consisting of their quotient and remainder when using integer division. With
mixed operand types, the rules for binary arithmetic operators apply. For
integers, the result is the same as ``(a // b, a % b)``. For floating-point
numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a /
b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very
close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0
<= abs(a % b) < abs(b)``.
.. function:: enumerate(iterable, start=0)
Return an enumerate object. *iterable* must be a sequence, an
:term:`iterator`, or some other object which supports iteration.
The :meth:`~iterator.__next__` method of the iterator returned by
:func:`enumerate` returns a tuple containing a count (from *start* which
defaults to 0) and the values obtained from iterating over *iterable*.
>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
>>> list(enumerate(seasons))
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
>>> list(enumerate(seasons, start=1))
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]
Equivalent to::
def enumerate(iterable, start=0):
n = start
for elem in iterable:
yield n, elem
n += 1
.. _func-eval:
.. function:: eval(source, /, globals=None, locals=None)
:param source:
A Python expression.
:type source: :class:`str` | :ref:`code object <code-objects>`
:param globals:
The global namespace (default: ``None``).
:type globals: :class:`dict` | :class:`frozendict` | ``None``
:param locals:
The local namespace (default: ``None``).
:type locals: :term:`mapping` | ``None``
:returns: The result of the evaluated expression.
:raises: Syntax errors are reported as exceptions.
.. warning::
This function executes arbitrary code. Calling it with
untrusted user-supplied input will lead to security vulnerabilities.
The *source* argument is parsed and evaluated as a Python expression
(technically speaking, an :ref:`expression list <exprlists>`)
using the *globals* and *locals* mappings as global and local namespace.
If the *globals* dictionary is present and does not contain a value for the
key ``__builtins__``, a
reference to the dictionary of the built-in module :mod:`builtins` is
inserted under that key before *source* is parsed.
Overriding ``__builtins__`` can be used to restrict or change the available
names, but this is **not** a security mechanism: the executed code can
still access all builtins.
If the *locals* mapping is omitted it defaults to the
*globals* dictionary. If both mappings are omitted, the source is
executed with the *globals* and *locals* in the environment where
:func:`eval` is called. Note, *eval()* will only have access to the
:term:`nested scopes <nested scope>` (non-locals) in the enclosing
environment if they are already referenced in the scope that is calling
:func:`eval` (e.g. via a :keyword:`nonlocal` statement).
Example:
>>> x = 1
>>> eval('x+1')
2
>>> eval("1, 2")
(1, 2)
This function can also be used to execute arbitrary code objects (such as
those created by :func:`compile`). In this case, pass a code object instead
of a string. If the code object has been compiled with ``'exec'`` as the
*mode* argument, :func:`eval`\'s return value will be ``None``.
Hints: dynamic execution of statements is supported by the :func:`exec`
function. The :func:`globals` and :func:`locals` functions
return the current global and local dictionary, respectively, which may be
useful to pass around for use by :func:`eval` or :func:`exec`.
If the given source is a string, then leading and trailing spaces and tabs
are stripped.
See :func:`ast.literal_eval` for a function to evaluate strings
with expressions containing only literals.
.. audit-event:: exec code_object eval
Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
as the argument. Code compilation events may also be raised.
.. versionchanged:: 3.13
The *globals* and *locals* arguments can now be passed as keywords.
.. versionchanged:: 3.13
The semantics of the default *locals* namespace have been adjusted as
described for the :func:`locals` builtin.
.. versionchanged:: 3.15
*globals* can now be a :class:`frozendict`.
.. index:: pair: built-in function; exec
.. function:: exec(source, /, globals=None, locals=None, *, closure=None)
.. warning::
This function executes arbitrary code. Calling it with
untrusted user-supplied input will lead to security vulnerabilities.
This function supports dynamic execution of Python code. *source* must be
either a string or a code object. If it is a string, the string is parsed as
a suite of Python statements which is then executed (unless a syntax error
occurs). [#]_ If it is a code object, it is simply executed. In all cases,
the code that's executed is expected to be valid as file input (see the
section :ref:`file-input` in the Reference Manual). Be aware that the
:keyword:`nonlocal`, :keyword:`yield`, and :keyword:`return`
statements may not be used outside of
function definitions even within the context of code passed to the
:func:`exec` function. The return value is ``None``.
In all cases, if the optional parts are omitted, the code is executed in the
current scope. If only *globals* is provided, it must be a dictionary
(and not a subclass of dictionary), which
will be used for both the global and the local variables. If *globals* and
*locals* are given, they are used for the global and local variables,
respectively. If provided, *locals* can be any mapping object. Remember
that at the module level, globals and locals are the same dictionary.
.. note::
When ``exec`` gets two separate objects as *globals* and *locals*, the
code will be executed as if it were embedded in a class definition. This
means functions and classes defined in the executed code will not be able
to access variables assigned at the top level (as the "top level"
variables are treated as class variables in a class definition).
If the *globals* dictionary does not contain a value for the key
``__builtins__``, a reference to the dictionary of the built-in module
:mod:`builtins` is inserted under that key.
Overriding ``__builtins__`` can be used to restrict or change the available
names, but this is **not** a security mechanism: the executed code can
still access all builtins.
The *closure* argument specifies a closure--a tuple of cellvars.
It's only valid when the *object* is a code object containing
:term:`free (closure) variables <closure variable>`.
The length of the tuple must exactly match the length of the code object's
:attr:`~codeobject.co_freevars` attribute.
.. audit-event:: exec code_object exec
Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
as the argument. Code compilation events may also be raised.
.. note::
The built-in functions :func:`globals` and :func:`locals` return the current
global and local namespace, respectively, which may be useful to pass around
for use as the second and third argument to :func:`exec`.
.. note::
The default *locals* act as described for function :func:`locals` below.
Pass an explicit *locals* dictionary if you need to see effects of the
code on *locals* after function :func:`exec` returns.
.. versionchanged:: 3.11
Added the *closure* parameter.
.. versionchanged:: 3.13
The *globals* and *locals* arguments can now be passed as keywords.
.. versionchanged:: 3.13
The semantics of the default *locals* namespace have been adjusted as
described for the :func:`locals` builtin.
.. versionchanged:: 3.15
*globals* can now be a :class:`frozendict`.
.. function:: filter(function, iterable, /)
Construct an iterator from those elements of *iterable* for which *function*
is true. *iterable* may be either a sequence, a container which
supports iteration, or an iterator. If *function* is ``None``, the identity
function is assumed, that is, all elements of *iterable* that are false are
removed.
Note that ``filter(function, iterable)`` is equivalent to the generator
expression ``(item for item in iterable if function(item))`` if function is
not ``None`` and ``(item for item in iterable if item)`` if function is
``None``.
See :func:`itertools.filterfalse` for the complementary function that returns
elements of *iterable* for which *function* is false.
.. class:: float(number=0.0, /)
float(string, /)
.. index::
single: NaN
single: Infinity
Return a floating-point number constructed from a number or a string.
Examples:
.. doctest::
>>> float('+1.23')
1.23
>>> float(' -12345\n')
-12345.0
>>> float('1e-003')
0.001
>>> float('+1E6')
1000000.0
>>> float('-Infinity')
-inf
If the argument is a string, it should contain a decimal number, optionally
preceded by a sign, and optionally embedded in whitespace. The optional
sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value
produced. The argument may also be a string representing a NaN
(not-a-number), or positive or negative infinity.
More precisely, the input must conform to the :token:`~float:floatvalue`
production rule in the following grammar, after leading and trailing
whitespace characters are removed:
.. productionlist:: float
sign: "+" | "-"
infinity: "Infinity" | "inf"
nan: "nan"
digit: <a Unicode decimal digit, i.e. characters in Unicode general category Nd>
digitpart: `digit` (["_"] `digit`)*
number: [`digitpart`] "." `digitpart` | `digitpart` ["."]
exponent: ("e" | "E") [`sign`] `digitpart`
floatnumber: `number` [`exponent`]
absfloatvalue: `floatnumber` | `infinity` | `nan`
floatvalue: [`sign`] `absfloatvalue`
Case is not significant, so, for example, "inf", "Inf", "INFINITY", and
"iNfINity" are all acceptable spellings for positive infinity.
Otherwise, 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(x)`` delegates to
``x.__float__()``. If :meth:`~object.__float__` is not defined then it falls back
to :meth:`~object.__index__`.
See also :meth:`float.from_number` which only accepts a numeric argument.
If no argument is given, ``0.0`` is returned.
The float type is described in :ref:`typesnumeric`.
.. versionchanged:: 3.6
Grouping digits with underscores as in code literals is allowed.
.. versionchanged:: 3.7
The parameter is now positional-only.
.. versionchanged:: 3.8
Falls back to :meth:`~object.__index__` if :meth:`~object.__float__` is not defined.
.. index::
single: __format__
single: string; format() (built-in function)
.. function:: format(value, format_spec="", /)
Convert a *value* to a "formatted" representation, as controlled by
*format_spec*. The interpretation of *format_spec* will depend on the type
of the *value* argument; however, there is a standard formatting syntax that
is used by most built-in types: :ref:`formatspec`.
The default *format_spec* is an empty string which usually gives the same
effect as calling :func:`str(value) <str>`.
A call to ``format(value, format_spec)`` is translated to
``type(value).__format__(value, format_spec)`` which bypasses the instance
dictionary when searching for the value's :meth:`~object.__format__` method.
A :exc:`TypeError` exception is raised if the method search reaches
:mod:`object` and the *format_spec* is non-empty, or if either the
*format_spec* or the return value are not strings.
.. versionchanged:: 3.4
``object().__format__(format_spec)`` raises :exc:`TypeError`
if *format_spec* is not an empty string.
.. _func-frozendict:
.. class:: frozendict(**kwargs)
frozendict(mapping, /, **kwargs)
frozendict(iterable, /, **kwargs)
:noindex:
Create a new frozen dictionary. The :class:`frozendict` object is a built-in class.
See also :ref:`typesmapping` for documentation about this class.
For other containers see the built-in :class:`dict`, :class:`list`, :class:`set`,
and :class:`tuple` classes, as well as the :mod:`collections` module.
.. versionadded:: 3.15
.. _func-frozenset:
.. class:: frozenset(iterable=(), /)
:noindex:
Return a new :class:`frozenset` object, optionally with elements taken from
*iterable*. :class:`frozenset` is a built-in class. See also
:ref:`types-set` for documentation about this class.
For other containers see the built-in :class:`set`, :class:`list`,
:class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
module.
.. function:: getattr(object, name, /)
getattr(object, name, default, /)
Return the value of the named attribute of *object*. *name* must be a string.
If the string is the name of one of the object's attributes, the result is the
value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
``x.foobar``. If the named attribute does not exist, *default* is returned if
provided, otherwise :exc:`AttributeError` is raised.
*name* need not be a Python identifier (see :func:`setattr`).
.. note::
Since :ref:`private name mangling <private-name-mangling>` happens at
compilation time, one must manually mangle a private attribute's
(attributes with two leading underscores) name in order to retrieve it with
:func:`getattr`.
.. function:: globals()
Return the dictionary implementing the current module namespace. For code within
functions, this is set when the function is defined and remains the same
regardless of where the function is called.
.. function:: hasattr(object, name, /)
The arguments are an object and a string. The result is ``True`` if the
string is the name of one of the object's attributes, ``False`` if not. (This
is implemented by calling ``getattr(object, name)`` and seeing whether it
raises an :exc:`AttributeError` or not.)
.. function:: hash(object, /)
Return the hash value of the object (if it has one). Hash values are
integers. They are used to quickly compare dictionary keys during a
dictionary lookup. Numeric values that compare equal have the same hash
value (even if they are of different types, as is the case for 1 and 1.0).
.. note::
For objects with custom :meth:`~object.__hash__` methods,
note that :func:`hash`
truncates the return value based on the bit width of the host machine.
.. function:: help()
help(request)
Invoke the built-in help system. (This function is intended for interactive
use.) If no argument is given, the interactive help system starts on the
interpreter console. If the argument is a string, then the string is looked up
as the name of a module, function, class, method, keyword, or documentation
topic, and a help page is printed on the console. If the argument is any other
kind of object, a help page on the object is generated.
Note that if a slash(/) appears in the parameter list of a function when
invoking :func:`help`, it means that the parameters prior to the slash are
positional-only. For more info, see
:ref:`the FAQ entry on positional-only parameters <faq-positional-only-arguments>`.
This function is added to the built-in namespace by the :mod:`site` module.
.. versionchanged:: 3.4
Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported
signatures for callables are now more comprehensive and consistent.
.. function:: hex(integer, /)
Convert an integer number to a lowercase hexadecimal string prefixed with
"0x". If *integer* is not a Python :class:`int` object, it has to define an
:meth:`~object.__index__` method that returns an integer. Some examples:
>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'
If you want to convert an integer number to an uppercase or lower hexadecimal
string with prefix or not, you can use either of the following ways:
>>> '%#x' % 255, '%x' % 255, '%X' % 255
('0xff', 'ff', 'FF')
>>> format(255, '#x'), format(255, 'x'), format(255, 'X')
('0xff', 'ff', 'FF')
>>> f'{255:#x}', f'{255:x}', f'{255:X}'
('0xff', 'ff', 'FF')
See also :func:`format` for more information.
See also :func:`int` for converting a hexadecimal string to an
integer using a base of 16.
.. note::
To obtain a hexadecimal string representation for a float, use the
:meth:`float.hex` method.
.. function:: id(object, /)
Return the "identity" of an object. This is an integer which
is guaranteed to be unique and constant for this object during its lifetime.
Two objects with non-overlapping lifetimes may have the same :func:`id`
value.
.. impl-detail:: This is the address of the object in memory.
.. audit-event:: builtins.id id id
.. function:: input()
input(prompt, /)
If the *prompt* argument is present, it is written to standard output without
a trailing newline. The function then reads a line from input, converts it
to a string (stripping a trailing newline), and returns that. When EOF is
read, :exc:`EOFError` is raised. Example::
>>> s = input('--> ') # doctest: +SKIP
--> Monty Python's Flying Circus
>>> s # doctest: +SKIP
"Monty Python's Flying Circus"
If the :mod:`readline` module was loaded, then :func:`input` will use it
to provide elaborate line editing and history features.
.. audit-event:: builtins.input prompt input
Raises an :ref:`auditing event <auditing>` ``builtins.input`` with
argument ``prompt`` before reading input
.. audit-event:: builtins.input/result result input
Raises an :ref:`auditing event <auditing>` ``builtins.input/result``
with the result after successfully reading input.
.. class:: int(number=0, /)
int(string, /, base=10)
Return an integer object constructed from a number or a string, or return
``0`` if no arguments are given.
Examples:
.. doctest::
>>> int(123.45)
123
>>> int('123')
123
>>> int(' -12_345\n')
-12345
>>> int('FACE', 16)
64206
>>> int('0xface', 0)
64206
>>> int('01110011', base=2)
115
If the argument defines :meth:`~object.__int__`,
``int(x)`` returns ``x.__int__()``. If the argument defines
:meth:`~object.__index__`, it returns ``x.__index__()``.
For floating-point numbers, this truncates towards zero.
If the argument is not a number or if *base* is given, then it must be a string,
:class:`bytes`, or :class:`bytearray` instance representing an integer
in radix *base*. Optionally, the string can be preceded by ``+`` or ``-``
(with no space in between), have leading zeros, be surrounded by whitespace,
and have single underscores interspersed between digits.
A base-n integer string contains digits, each representing a value from 0 to
n-1. The values 0--9 can be represented by any Unicode decimal digit. The
values 10--35 can be represented by ``a`` to ``z`` (or ``A`` to ``Z``). The
default *base* is 10. The allowed bases are 0 and 2--36. Base-2, -8, and -16
strings can be optionally prefixed with ``0b``/``0B``, ``0o``/``0O``, or
``0x``/``0X``, as with integer literals in code. For base 0, the string is
interpreted in a similar way to an :ref:`integer literal in code <integers>`,
in that the actual base is 2, 8, 10, or 16 as determined by the prefix. Base
0 also disallows leading zeros: ``int('010', 0)`` is not legal, while
``int('010')`` and ``int('010', 8)`` are.
The integer type is described in :ref:`typesnumeric`.
.. versionchanged:: 3.4
If *base* is not an instance of :class:`int` and the *base* object has a
:meth:`base.__index__ <object.__index__>` method, that method is called
to obtain an integer for the base. Previous versions used
:meth:`base.__int__ <object.__int__>` instead of :meth:`base.__index__
<object.__index__>`.
.. versionchanged:: 3.6
Grouping digits with underscores as in code literals is allowed.
.. versionchanged:: 3.7
The first parameter is now positional-only.
.. versionchanged:: 3.8
Falls back to :meth:`~object.__index__` if :meth:`~object.__int__` is not defined.
.. versionchanged:: 3.11
:class:`int` string inputs and string representations can be limited to
help avoid denial of service attacks. A :exc:`ValueError` is raised when
the limit is exceeded while converting a string to an :class:`int` or
when converting an :class:`int` into a string would exceed the limit.
See the :ref:`integer string conversion length limitation
<int_max_str_digits>` documentation.
.. versionchanged:: 3.14
:func:`int` no longer delegates to the :meth:`~object.__trunc__` method.
.. function:: isinstance(object, classinfo, /)
Return ``True`` if the *object* argument is an instance of the *classinfo*
argument, or of a (direct, indirect, or :term:`virtual <abstract base
class>`) subclass thereof. If *object* is not
an object of the given type, the function always returns ``False``.
If *classinfo* is a tuple of type objects (or recursively, other such
tuples) or a :ref:`types-union` of multiple types, return ``True`` if
*object* is an instance of any of the types.
If *classinfo* is not a type or tuple of types and such tuples,
a :exc:`TypeError` exception is raised. :exc:`TypeError` may not be
raised for an invalid type if an earlier check succeeds.
.. versionchanged:: 3.10
*classinfo* can be a :ref:`types-union`.
.. function:: issubclass(cls, classinfo, /)
Return ``True`` if *cls* is a subclass (direct, indirect, or :term:`virtual
<abstract base class>`) of *classinfo*. A
class is considered a subclass of itself. *classinfo* may be a tuple of class
objects (or recursively, other such tuples)
or a :ref:`types-union`, in which case return ``True`` if *cls* is a
subclass of any entry in *classinfo*. In any other case, a :exc:`TypeError`
exception is raised.
.. versionchanged:: 3.10
*classinfo* can be a :ref:`types-union`.
.. function:: iter(iterable, /)
iter(callable, /, stop_value, *, stop_exception=StopIteration)
iter(callable, /, *, stop_exception)
Return an :term:`iterator` object. The first argument is interpreted very
differently depending on the presence of the other arguments. Without other
arguments, the single argument must be a collection object which supports the
:term:`iterable` protocol (the :meth:`~object.__iter__` method),
or it must support
the sequence protocol (the :meth:`~object.__getitem__` method with integer arguments
starting at ``0``). If it does not support either of those protocols,
:exc:`TypeError` is raised.
If *stop_value* or *stop_exception* is given,
then the first argument must be a callable object. The iterator created in this case
will call *callable* with no arguments for each call to its
:meth:`~iterator.__next__` method; if the value returned is equal to
*stop_value*, or if the call raises an exception matching *stop_exception*,
:exc:`StopIteration` will be raised, otherwise the value will
be returned.
*stop_exception* is an exception class or a tuple of exception classes.
If *stop_value* is not specified,
the iteration stops only when the callable raises an exception.
If the callable raises :exc:`StopIteration`
which does not match *stop_exception*,
it is replaced with a :exc:`RuntimeError`,
as for generators (see :pep:`479`).
See also :ref:`typeiter`.
One useful application of the second form of :func:`iter` is to build a
block-reader. For example, reading fixed-width blocks from a binary
database file until the end of file is reached::
from functools import partial
with open('mydata.db', 'rb') as f:
for block in iter(partial(f.read, 64), b''):
process_block(block)
*stop_exception* is useful for callables
which report :term:`exhaustion <exhausted>` by raising an exception
instead of returning a special value.
For example, draining a queue::
import queue
for item in iter(input_queue.get_nowait, stop_exception=queue.Empty):
process_item(item)
.. versionchanged:: 3.16
Added the *stop_exception* parameter
and allowed passing *stop_value* by keyword.
.. function:: len(object, /)
Return the length (the number of items) of an object. The argument may be a
sequence (such as a string, bytes, tuple, list, or range) or a collection
(such as a dictionary, set, or frozen set).
.. impl-detail::
``len`` raises :exc:`OverflowError` on lengths larger than
:data:`sys.maxsize`, such as :class:`range(2 ** 100) <range>`.
.. _func-list:
.. class:: list(iterable=(), /)
:noindex:
Rather than being a function, :class:`list` is actually a mutable
sequence type, as documented in :ref:`typesseq-list` and :ref:`typesseq`.
.. function:: locals()
Return a mapping object representing the current local symbol table, with
variable names as the keys, and their currently bound references as the
values.
At module scope, as well as when using :func:`exec` or :func:`eval` with
a single namespace, this function returns the same namespace as
:func:`globals`.
At class scope, it returns the namespace that will be passed to the
metaclass constructor.
When using ``exec()`` or ``eval()`` with separate local and global
arguments, it returns the local namespace passed in to the function call.
In all of the above cases, each call to ``locals()`` in a given frame of
execution will return the *same* mapping object. Changes made through
the mapping object returned from ``locals()`` will be visible as assigned,
reassigned, or deleted local variables, and assigning, reassigning, or
deleting local variables will immediately affect the contents of the
returned mapping object.
In an :term:`optimized scope` (including functions, generators, and
coroutines), each call to ``locals()`` instead returns a fresh dictionary
containing the current bindings of the function's local variables and any
nonlocal cell references. In this case, name binding changes made via the
returned dict are *not* written back to the corresponding local variables
or nonlocal cell references, and assigning, reassigning, or deleting local
variables and nonlocal cell references does *not* affect the contents
of previously returned dictionaries.
Calling ``locals()`` as part of a comprehension in a function, generator, or
coroutine is equivalent to calling it in the containing scope, except that
the comprehension's initialised iteration variables will be included. In
other scopes, it behaves as if the comprehension were running as a nested
function.
Calling ``locals()`` as part of a generator expression is equivalent to
calling it in a nested generator function.
.. versionchanged:: 3.12
The behaviour of ``locals()`` in a comprehension has been updated as
described in :pep:`709`.
.. versionchanged:: 3.13
As part of :pep:`667`, the semantics of mutating the mapping objects
returned from this function are now defined. The behavior in
:term:`optimized scopes <optimized scope>` is now as described above.
Aside from being defined, the behaviour in other scopes remains
unchanged from previous versions.
.. function:: map(function, iterable, /, *iterables, strict=False)
Return an iterator that applies *function* to every item of *iterable*,
yielding the results. If additional *iterables* arguments are passed,
*function* must take that many arguments and is applied to the items from all
iterables in parallel. With multiple iterables, the iterator stops when the
shortest iterable is :term:`exhausted`. If *strict* is ``True`` and one of the
iterables is exhausted before the others, a :exc:`ValueError` is raised. For
cases where the function inputs are already arranged into argument tuples,
see :func:`itertools.starmap`.
.. versionchanged:: 3.14
Added the *strict* parameter.
.. function:: max(iterable, /, *, key=None)
max(iterable, /, *, default, key=None)
max(arg1, arg2, /, *args, key=None)
Return the largest item in an iterable or the largest of two or more
arguments.
If one positional argument is provided, it should be an :term:`iterable`.
The largest item in the iterable is returned. If two or more positional
arguments are provided, the largest of the positional arguments is
returned.
There are two optional keyword-only arguments. The *key* argument specifies
a one-argument ordering function like that used for :meth:`list.sort`. The
*default* argument specifies an object to return if the provided iterable is
empty. If the iterable is empty and *default* is not provided, a
:exc:`ValueError` is raised.
If multiple items are maximal, the function returns the first one
encountered. This is consistent with other sort-stability preserving tools
such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and
``heapq.nlargest(1, iterable, key=keyfunc)``.
.. versionchanged:: 3.4
Added the *default* keyword-only parameter.
.. versionchanged:: 3.8
The *key* can be ``None``.
.. _func-memoryview:
.. class:: memoryview(object)
:noindex:
Return a "memory view" object created from the given argument. See
:ref:`typememoryview` for more information.
.. function:: min(iterable, /, *, key=None)
min(iterable, /, *, default, key=None)
min(arg1, arg2, /, *args, key=None)
Return the smallest item in an iterable or the smallest of two or more
arguments.
If one positional argument is provided, it should be an :term:`iterable`.
The smallest item in the iterable is returned. If two or more positional
arguments are provided, the smallest of the positional arguments is
returned.
There are two optional keyword-only arguments. The *key* argument specifies
a one-argument ordering function like that used for :meth:`list.sort`. The
*default* argument specifies an object to return if the provided iterable is
empty. If the iterable is empty and *default* is not provided, a
:exc:`ValueError` is raised.
If multiple items are minimal, the function returns the first one
encountered. This is consistent with other sort-stability preserving tools
such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1,
iterable, key=keyfunc)``.
.. versionchanged:: 3.4
Added the *default* keyword-only parameter.
.. versionchanged:: 3.8
The *key* can be ``None``.
.. function:: next(iterator, /)
next(iterator, default, /)
Retrieve the next item from the :term:`iterator` by calling its
:meth:`~iterator.__next__` method. If *default* is given, it is returned
if the iterator is :term:`exhausted`, otherwise :exc:`StopIteration` is raised.
.. class:: object()
This is the ultimate base class of all other classes. It has methods
that are common to all instances of Python classes. When the constructor
is called, it returns a new featureless object. The constructor does not
accept any arguments.
.. note::
:class:`object` instances do *not* have :attr:`~object.__dict__`
attributes, so you can't assign arbitrary attributes to an instance of
:class:`object`.
.. function:: oct(integer, /)
Convert an integer number to an octal string prefixed with "0o". The result
is a valid Python expression. If *integer* is not a Python :class:`int` object, it
has to define an :meth:`~object.__index__` method that returns an integer. For
example:
>>> oct(8)
'0o10'
>>> oct(-56)
'-0o70'
If you want to convert an integer number to an octal string either with the prefix
"0o" or not, you can use either of the following ways.
>>> '%#o' % 10, '%o' % 10
('0o12', '12')
>>> format(10, '#o'), format(10, 'o')
('0o12', '12')
>>> f'{10:#o}', f'{10:o}'
('0o12', '12')
See also :func:`format` for more information.
.. index::
single: file object; open() built-in function
.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
Open *file* and return a corresponding :term:`file object`. If the file
cannot be opened, an :exc:`OSError` is raised. See
:ref:`tut-files` for more examples of how to use this function.
*file* is a :term:`path-like object` giving the pathname (absolute or
relative to the current working directory) of the file to be opened or an
integer file descriptor of the file to be wrapped. (If a file descriptor is
given, it is closed when the returned I/O object is closed unless *closefd*
is set to ``False``.)
*mode* is an optional string that specifies the mode in which the file is
opened. It defaults to ``'r'`` which means open for reading in text mode.
Other common values are ``'w'`` for writing (truncating the file if it
already exists), ``'x'`` for exclusive creation, and ``'a'`` for appending
(which on *some* Unix systems, means that *all* writes append to the end of
the file regardless of the current seek position). In text mode, if
*encoding* is not specified, UTF-8 is used by default; if
:ref:`Python UTF-8 Mode <utf8-mode>` is disabled,
:func:`locale.getencoding` is called to get the current locale encoding.
(For reading and writing raw bytes use binary mode and leave
*encoding* unspecified.) The available modes are:
.. _filemodes:
.. index::
pair: file; modes
========= ===============================================================
Character Meaning
========= ===============================================================
``'r'`` open for reading (default)
``'w'`` open for writing, truncating the file first
``'x'`` open for exclusive creation, failing if the file already exists
``'a'`` open for writing, appending to the end of file if it exists
``'b'`` binary mode
``'t'`` text mode (default)
``'+'`` open for updating (reading and writing)
========= ===============================================================
The default mode is ``'r'`` (open for reading text, a synonym of ``'rt'``).
Modes ``'w+'`` and ``'w+b'`` open and truncate the file. Modes ``'r+'``
and ``'r+b'`` open the file with no truncation.
As mentioned in the :ref:`io-overview`, Python distinguishes between binary
and text I/O. Files opened in binary mode (including ``'b'`` in the *mode*
argument) return contents as :class:`bytes` objects without any decoding. In
text mode (the default, or when ``'t'`` is included in the *mode* argument),
the contents of the file are returned as :class:`str`, the bytes having been
first decoded using the default encoding or using the specified
*encoding* if given.
.. note::
Python doesn't depend on the underlying operating system's notion of text
files; all the processing is done by Python itself, and is therefore
platform-independent.
*buffering* is an optional integer used to set the buffering policy. Pass 0
to switch buffering off (only allowed in binary mode), 1 to select line
buffering (only usable when writing in text mode), and an integer > 1 to indicate the size
in bytes of a fixed-size chunk buffer. Note that specifying a buffer size this
way applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened
with ``mode='r+'``) would have another buffering. To disable buffering in
``TextIOWrapper``, consider using the ``write_through`` flag for
:func:`io.TextIOWrapper.reconfigure`. When no *buffering* argument is
given, the default buffering policy works as follows:
* Binary files are buffered in fixed-size chunks; the size of the buffer
is ``max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)``
when the device block size is available.
On most systems, the buffer will typically be 128 kilobytes long.
* "Interactive" text files (files for which :meth:`~io.IOBase.isatty`
returns ``True``) use line buffering. Other text files use the policy
described above for binary files.
*encoding* is the name of the encoding used to decode or encode the file.
This should only be used in text mode. The default encoding is UTF-8;
if :ref:`Python UTF-8 Mode <utf8-mode>` is disabled, the default is
platform-dependent (whatever :func:`locale.getencoding` returns).
Any :term:`text encoding` supported by Python can be used, and
``encoding="locale"`` specifies the current locale encoding explicitly.
See the :mod:`codecs` module for the list of supported encodings.
*errors* is an optional string that specifies how encoding and decoding
errors are to be handledβthis cannot be used in binary mode.
A variety of standard error handlers are available,
though any error handling name that has been registered with
:func:`codecs.register_error` is also valid. The standard names
can be found in :ref:`error-handlers`.
.. index::
single: universal newlines; open() built-in function
.. _open-newline-parameter:
*newline* determines how to parse newline characters from the stream.
It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and
``'\r\n'``. It works as follows:
* When reading input from the stream, if *newline* is ``None``, universal
newlines mode is enabled. Lines in the input can end in ``'\n'``,
``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before
being returned to the caller. If it is ``''``, universal newlines mode is
enabled, but line endings are returned to the caller untranslated. If it
has any of the other legal values, input lines are only terminated by the
given string, and the line ending is returned to the caller untranslated.
* When writing output to the stream, if *newline* is ``None``, any ``'\n'``
characters written are translated to the system default line separator,
:data:`os.linesep`. If *newline* is ``''`` or ``'\n'``, no translation
takes place. If *newline* is any of the other legal values, any ``'\n'``
characters written are translated to the given string.
If *closefd* is ``False`` and a file descriptor rather than a filename was
given, the underlying file descriptor will be kept open when the file is
closed. If a filename is given *closefd* must be ``True`` (the default);
otherwise, an error will be raised.
A custom opener can be used by passing a callable as *opener*. The underlying
file descriptor for the file object is then obtained by calling *opener* with
(*file*, *flags*). *opener* must return an open file descriptor (passing
:mod:`os.open` as *opener* results in functionality similar to passing
``None``).
The newly created file is :ref:`non-inheritable <fd_inheritance>`.
The following example uses the :ref:`dir_fd <dir_fd>` parameter of the
:func:`os.open` function to open a file relative to a given directory::
>>> import os
>>> dir_fd = os.open('somedir', os.O_RDONLY)
>>> def opener(path, flags):
... return os.open(path, flags, dir_fd=dir_fd)
...
>>> with open('spamspam.txt', 'w', opener=opener) as f:
... print('This will be written to somedir/spamspam.txt', file=f)
...
>>> os.close(dir_fd) # don't leak a file descriptor
The type of :term:`file object` returned by the :func:`open` function
depends on the mode. When :func:`open` is used to open a file in a text
mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
:class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used
to open a file in a binary mode with buffering, the returned class is a
subclass of :class:`io.BufferedIOBase`. The exact class varies: in read
binary mode, it returns an :class:`io.BufferedReader`; in write binary and
append binary modes, it returns an :class:`io.BufferedWriter`, and in
read/write mode, it returns an :class:`io.BufferedRandom`. When buffering is
disabled, the raw stream, a subclass of :class:`io.RawIOBase`,
:class:`io.FileIO`, is returned.
.. index::
single: line-buffered I/O
single: unbuffered I/O
single: buffer size, I/O
single: I/O control; buffering
single: binary mode
single: text mode
pair: module; sys
See also the file handling modules, such as :mod:`fileinput`, :mod:`io`
(where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`,
and :mod:`shutil`.
.. audit-event:: open path,mode,flags open
The ``mode`` and ``flags`` arguments may have been modified or inferred from
the original call.
.. versionchanged:: 3.3
* The *opener* parameter was added.
* The ``'x'`` mode was added.
* :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
* :exc:`FileExistsError` is now raised if the file opened in exclusive
creation mode (``'x'``) already exists.
.. versionchanged:: 3.4
* The file is now non-inheritable.
.. versionchanged:: 3.5
* If the system call is interrupted and the signal handler does not raise an
exception, the function now retries the system call instead of raising an
:exc:`InterruptedError` exception (see :pep:`475` for the rationale).
* The ``'namereplace'`` error handler was added.
.. versionchanged:: 3.6
* Support added to accept objects implementing :class:`os.PathLike`.
* On Windows, opening a console buffer may return a subclass of
:class:`io.RawIOBase` other than :class:`io.FileIO`.
.. versionchanged:: 3.11
The ``'U'`` mode has been removed.
.. versionchanged:: 3.15
UTF-8 is now the default encoding, instead of the
platform-dependent locale encoding (:pep:`686`).
.. function:: ord(character, /)
Return the ordinal value of a character.
If the argument is a one-character string, return the Unicode code point
of that character. For example,
``ord('a')`` returns the integer ``97`` and ``ord('β¬')`` (Euro sign)
returns ``8364``. This is the inverse of :func:`chr`.
If the argument is a :class:`bytes` or :class:`bytearray` object of
length 1, return its single byte value.
For example, ``ord(b'a')`` returns the integer ``97``.
.. function:: pow(base, exp, mod=None)
Return *base* to the power *exp*; if *mod* is present, return *base* to the
power *exp*, modulo *mod* (computed more efficiently than
``pow(base, exp) % mod``). The two-argument form ``pow(base, exp)`` is
equivalent to using the power operator: ``base**exp``.
When arguments are builtin numeric types with mixed operand types, the
coercion rules for binary arithmetic operators apply. For :class:`int`
operands, the result has the same type as the operands (after coercion)
unless the second argument is negative; in that case, all arguments are
converted to float and a float result is delivered. For example, ``pow(10, 2)``
returns ``100``, but ``pow(10, -2)`` returns ``0.01``. For a negative base of
type :class:`int` or :class:`float` and a non-integral exponent, a complex
result is delivered. For example, ``pow(-9, 0.5)`` returns a value close
to ``3j``. Whereas, for a negative base of type :class:`int` or :class:`float`
with an integral exponent, a float result is delivered. For example,
``pow(-9, 2.0)`` returns ``81.0``.
For :class:`int` operands *base* and *exp*, if *mod* is present, *mod* must
also be of integer type and *mod* must be nonzero. If *mod* is present and
*exp* is negative, *base* must be relatively prime to *mod*. In that case,
``pow(inv_base, -exp, mod)`` is returned, where *inv_base* is an inverse to
*base* modulo *mod*.
Here's an example of computing an inverse for ``38`` modulo ``97``::
>>> pow(38, -1, mod=97)
23
>>> 23 * 38 % 97 == 1
True
.. versionchanged:: 3.8
For :class:`int` operands, the three-argument form of ``pow`` now allows
the second argument to be negative, permitting computation of modular
inverses.
.. versionchanged:: 3.8
Allow keyword arguments. Formerly, only positional arguments were
supported.
.. function:: print(*objects, sep=' ', end='\n', file=None, flush=False)
Print *objects* to the text stream *file*, separated by *sep* and followed
by *end*. *sep*, *end*, *file*, and *flush*, if present, must be given as keyword
arguments.
All non-keyword arguments are converted to strings like :func:`str` does and
written to the stream, separated by *sep* and followed by *end*. Both *sep*
and *end* must be strings; they can also be ``None``, which means to use the
default values. If no *objects* are given, :func:`print` will just write
*end*.
The *file* argument must be an object with a ``write(string)`` method; if it
is not present or ``None``, :data:`sys.stdout` will be used. Since printed
arguments are converted to text strings, :func:`print` cannot be used with
binary mode file objects. For these, use ``file.write(...)`` instead.
Output buffering is usually determined by *file*.
However, if *flush* is true, the stream is forcibly flushed.
.. versionchanged:: 3.3
Added the *flush* keyword argument.
.. class:: property(fget=None, fset=None, fdel=None, doc=None)
Return a property attribute.
*fget* is a function for getting an attribute value. *fset* is a function
for setting an attribute value. *fdel* is a function for deleting an attribute
value. And *doc* creates a docstring for the attribute.
A typical use is to define a managed attribute ``x``::
class C:
def __init__(self):
self._x = None
def getx(self):
return self._x
def setx(self, value):
self._x = value
def delx(self):
del self._x
x = property(getx, setx, delx, "I'm the 'x' property.")
If *c* is an instance of *C*, ``c.x`` will invoke the getter,
``c.x = value`` will invoke the setter, and ``del c.x`` the deleter.
If given, *doc* will be the docstring of the property attribute. Otherwise, the
property will copy *fget*'s docstring (if it exists). This makes it possible to
create read-only properties easily using :deco:`property` as a :term:`decorator`::
class Parrot:
def __init__(self):
self._voltage = 100000
@property
def voltage(self):
"""Get the current voltage."""
return self._voltage
The ``@property`` decorator turns the :meth:`!voltage` method into a "getter"
for a read-only attribute with the same name, and it sets the docstring for
*voltage* to "Get the current voltage."
.. decorator:: property.getter
.. decorator:: property.setter
.. decorator:: property.deleter
A property object has ``getter``, ``setter``,
and ``deleter`` methods usable as decorators that create a
copy of the property with the corresponding accessor function set to the
decorated function. This is best explained with an example:
.. testcode::
class C:
def __init__(self):
self._x = None
@property
def x(self):
"""I'm the 'x' property."""
return self._x
@x.setter
def x(self, value):
self._x = value
@x.deleter
def x(self):
del self._x
This code is exactly equivalent to the first example. Be sure to give the
additional functions the same name as the original property (``x`` in this
case.)
The returned property object also has the attributes ``fget``, ``fset``, and
``fdel`` corresponding to the constructor arguments.
.. versionchanged:: 3.5
The docstrings of property objects are now writeable.
.. attribute:: __name__
Attribute holding the name of the property. The name of the property
can be changed at runtime.
.. versionadded:: 3.13
.. _func-range:
.. class:: range(stop, /)
range(start, stop, step=1, /)
:noindex:
Rather than being a function, :class:`range` is actually an immutable
sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`.
.. function:: repr(object, /)
Return a string containing a printable representation of an object. For many
types, this function makes an attempt to return a string that would yield an
object with the same value when passed to :func:`eval`; otherwise, the
representation is a string enclosed in angle brackets that contains the name
of the type of the object together with additional information often
including the name and address of the object. A class can control what this
function returns for its instances
by defining a :meth:`~object.__repr__` method.
If :func:`sys.displayhook` is not accessible, this function will raise
:exc:`RuntimeError`.
This class has a custom representation that can be evaluated::
class Person:
def __init__(self, name, age):
self.name = name
self.age = age
def __repr__(self):
return f"Person({self.name!r}, {self.age!r})"
.. function:: reversed(object, /)
Return a reverse :term:`iterator`. The argument must be an object which has
a :meth:`~object.__reversed__` method or supports the sequence protocol (the
:meth:`~object.__len__` method and the :meth:`~object.__getitem__` method
with integer arguments starting at ``0``).
.. function:: round(number, ndigits=None)
Return *number* rounded to *ndigits* precision after the decimal
point. If *ndigits* is omitted or is ``None``, it returns the
nearest integer to its input.
For the built-in types supporting :func:`round`, values are rounded to the
closest multiple of 10 to the power minus *ndigits*; if two multiples are
equally close, rounding is done toward the even choice (so, for example,
both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is
``2``). Any integer value is valid for *ndigits* (positive, zero, or
negative). The return value is an integer if *ndigits* is omitted or
``None``.
Otherwise, the return value has the same type as *number*.
For a general Python object ``number``, ``round`` delegates to
``number.__round__``.
.. note::
The behavior of :func:`round` for floats can be surprising: for example,
``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``.
This is not a bug: it's a result of the fact that most decimal fractions
can't be represented exactly as a float. See :ref:`tut-fp-issues` for
more information.
.. _func-set:
.. class:: set(iterable=(), /)
:noindex:
Return a new :class:`set` object, optionally with elements taken from
*iterable*. :class:`set` is a built-in class. See also
:ref:`types-set` for documentation about this class.
For other containers see the built-in :class:`frozenset`, :class:`list`,
:class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
module.
.. function:: setattr(object, name, value, /)
This is the counterpart of :func:`getattr`. The arguments are an object, a
string, and an arbitrary value. The string may name an existing attribute or a
new attribute. The function assigns the value to the attribute, provided the
object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
``x.foobar = 123``.
*name* need not be a Python identifier as defined in :ref:`identifiers`
unless the object chooses to enforce that, for example in a custom
:meth:`~object.__getattribute__` or via :attr:`~object.__slots__`.
An attribute whose name is not an identifier will not be accessible using
the dot notation, but is accessible through :func:`getattr` etc..
.. note::
Since :ref:`private name mangling <private-name-mangling>` happens at
compilation time, one must manually mangle a private attribute's
(attributes with two leading underscores) name in order to set it with
:func:`setattr`.
.. class:: sentinel(name, /, *, repr=None)
Return a new unique sentinel object. *name* must be a :class:`str`, and is
used by default as the returned object's representation::
>>> MISSING = sentinel("MISSING")
>>> MISSING
MISSING
The optional *repr* argument can be used to specify a different representation::
>>> MISSING = sentinel("MISSING", repr="<MISSING>")
>>> MISSING
<MISSING>
Sentinel objects are truthy and compare equal only to themselves. They are
intended to be compared with the :keyword:`is` operator.
``sentinel`` does not support subclassing.
Shallow and deep copies of a sentinel object return the object itself.
Sentinels are conventionally assigned to a variable with a matching name.
Sentinels defined in this way can be used in :term:`type hints <type hint>`::
MISSING = sentinel("MISSING")
def next_value(default: int | MISSING = MISSING):
...
Sentinel objects support the :ref:`| <bitwise>` operator for use in type expressions.
:mod:`Pickling <pickle>` is supported for sentinel objects that are
placed in the global scope of a module under a name matching the sentinel's
name, and for sentinels placed in class scopes with a name matching the
:term:`qualified name` of the sentinel. Other sentinels, such as those
defined in a function scope, are not picklable. The identity of the sentinel is preserved
after pickling::
import pickle
PICKLABLE = sentinel("PICKLABLE")
assert pickle.loads(pickle.dumps(PICKLABLE)) is PICKLABLE
class Cls:
PICKLABLE = sentinel("Cls.PICKLABLE")
assert pickle.loads(pickle.dumps(Cls.PICKLABLE)) is Cls.PICKLABLE
Sentinel objects have the following attributes:
.. attribute:: __name__
The sentinel's name.
.. attribute:: __module__
The name of the module where the sentinel was created. This attribute is writable.
.. versionadded:: 3.15
.. class:: slice(stop, /)
slice(start, stop, step=None, /)
Return a :term:`slice` object representing the set of indices specified by
``range(start, stop, step)``. The *start* and *step* arguments default to
``None``.
Slice objects are also generated when :ref:`slicing syntax <slicings>`
is used. For example: ``a[start:stop:step]`` or ``a[start:stop, i]``.
See :func:`itertools.islice` for an alternate version that returns an
:term:`iterator`.
.. attribute:: slice.start
slice.stop
slice.step
These read-only attributes are set to the argument values
(or their default). They have no other explicit functionality;
however, they are used by NumPy and other third-party packages.
.. versionchanged:: 3.12
Slice objects are now :term:`hashable` (provided :attr:`~slice.start`,
:attr:`~slice.stop`, and :attr:`~slice.step` are hashable).
.. function:: sorted(iterable, /, *, key=None, reverse=False)
Return a new sorted list from the items in *iterable*.
Has two optional arguments which must be specified as keyword arguments.
*key* specifies a function of one argument that is used to extract a comparison
key from each element in *iterable* (for example, ``key=str.lower``). The
default value is ``None`` (compare the elements directly).
*reverse* is a boolean value. If set to ``True``, then the list elements are
sorted as if each comparison were reversed.
Use :func:`functools.cmp_to_key` to convert an old-style *cmp* function to a
*key* function.
The built-in :func:`sorted` function is guaranteed to be stable. A sort is
stable if it guarantees not to change the relative order of elements that
compare equal --- this is helpful for sorting in multiple passes (for
example, sort by department, then by salary grade).
The sort algorithm uses only ``<`` comparisons between items. While
defining an :meth:`~object.__lt__` method will suffice for sorting,
:PEP:`8` recommends that all six :ref:`rich comparisons
<comparisons>` be implemented. This will help avoid bugs when using
the same data with other ordering tools such as :func:`max` that rely
on a different underlying method. Implementing all six comparisons
also helps avoid confusion for mixed type comparisons which can call
the reflected :meth:`~object.__gt__` method.
For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
.. decorator:: staticmethod
Transform a method into a static method.
A static method does not receive an implicit first argument. To declare a static
method, use this idiom::
class C:
@staticmethod
def f(arg1, arg2, argN): ...
The ``@staticmethod`` form is a function :term:`decorator` -- see
:ref:`function` for details.
A static method can be called either on the class (such as ``C.f()``) or on
an instance (such as ``C().f()``).
Moreover, the static method :term:`descriptor` is also callable, so it can
be used in the class definition (such as ``f()``).
Static methods in Python are similar to those found in Java or C++. Also, see
:deco:`classmethod` for a variant that is useful for creating alternate class
constructors.
Like all decorators, it is also possible to call ``staticmethod`` as
a regular function and do something with its result. This is needed
in some cases where you need a reference to a function from a class
body and you want to avoid the automatic transformation to instance
method. For these cases, use this idiom::
def regular_function():
...
class C:
method = staticmethod(regular_function)
For more information on static methods, see :ref:`types`.
.. versionchanged:: 3.10
Static methods now inherit the method attributes
(:attr:`~function.__module__`, :attr:`~function.__name__`,
:attr:`~function.__qualname__`, :attr:`~function.__doc__` and
:attr:`~function.__annotations__`), have a new ``__wrapped__`` attribute,
and are now callable as regular functions.
.. index::
single: string; str() (built-in function)
.. _func-str:
.. class:: str(*, encoding='utf-8', errors='strict')
str(object)
str(object, encoding, errors='strict')
str(object, *, errors)
:noindex:
Return a :class:`str` version of *object*. See :func:`str` for details.
``str`` is the built-in string :term:`class`. For general information
about strings, see :ref:`textseq`.
.. function:: sum(iterable, /, start=0)
Sums *start* and the items of an *iterable* from left to right and returns the
total. The *iterable*'s items are normally numbers, and the start value is not
allowed to be a string.
For some use cases, there are good alternatives to :func:`sum`.
The preferred, fast way to concatenate a sequence of strings is by calling
``''.join(sequence)``. To add floating-point values with extended precision,
see :func:`math.fsum`\. To concatenate a series of iterables, consider using
:func:`itertools.chain`.
.. versionchanged:: 3.8
The *start* parameter can be specified as a keyword argument.
.. versionchanged:: 3.12 Summation of floats switched to an algorithm
that gives higher accuracy and better commutativity on most builds.
.. versionchanged:: 3.14
Added specialization for summation of complexes,
using same algorithm as for summation of floats.
.. class:: super()
super(type, object_or_type=None, /)
Return a proxy object that delegates method calls to a parent or sibling
class of *type*. This is useful for accessing inherited methods that have
been overridden in a class.
The *object_or_type* determines the :term:`method resolution order`
to be searched. The search starts from the class right after the
*type*.
For example, if :attr:`~type.__mro__` of *object_or_type* is
``D -> B -> C -> A -> object`` and the value of *type* is ``B``,
then :func:`super` searches ``C -> A -> object``.
The :attr:`~type.__mro__` attribute of the class corresponding to
*object_or_type* lists the method resolution search order used by both
:func:`getattr` and :func:`super`. The attribute is dynamic and can change
whenever the inheritance hierarchy is updated.
If the second argument is omitted, the super object returned is unbound. If
the second argument is an object, ``isinstance(obj, type)`` must be true. If
the second argument is a type, ``issubclass(type2, type)`` must be true (this
is useful for classmethods).
When called directly within an ordinary method of a class, both arguments may
be omitted ("zero-argument :func:`!super`"). In this case, *type* will be the
enclosing class, and *obj* will be the first argument of the immediately
enclosing function (typically ``self``). (This means that zero-argument
:func:`!super` will not work as expected within nested functions, including
generator expressions, which implicitly create nested functions.)
There are two typical use cases for *super*. In a class hierarchy with
single inheritance, *super* can be used to refer to parent classes without
naming them explicitly, thus making the code more maintainable. This use
closely parallels the use of *super* in other programming languages.
The second use case is to support cooperative multiple inheritance in a
dynamic execution environment. This use case is unique to Python and is
not found in statically compiled languages or languages that only support
single inheritance. This makes it possible to implement "diamond diagrams"
where multiple base classes implement the same method. Good design dictates
that such implementations have the same calling signature in every case (because the
order of calls is determined at runtime, because that order adapts
to changes in the class hierarchy, and because that order can include
sibling classes that are unknown prior to runtime).
For both use cases, a typical superclass call looks like this::
class C(B):
def method(self, arg):
super().method(arg) # This does the same thing as:
# super(C, self).method(arg)
In addition to method lookups, :func:`super` also works for attribute
lookups. One possible use case for this is calling :term:`descriptors <descriptor>`
in a parent or sibling class.
Note that :func:`super` is implemented as part of the binding process for
explicit dotted attribute lookups such as ``super().__getitem__(name)``.
It does so by implementing its own :meth:`~object.__getattribute__` method
for searching
classes in a predictable order that supports cooperative multiple inheritance.
Accordingly, :func:`super` is undefined for implicit lookups using statements or
operators such as ``super()[name]``.
Also note that, aside from the zero argument form, :func:`super` is not
limited to use inside methods. The two argument form specifies the
arguments exactly and makes the appropriate references. The zero
argument form only works inside a class definition, as the compiler fills
in the necessary details to correctly retrieve the class being defined,
as well as accessing the current instance for ordinary methods.
For practical suggestions on how to design cooperative classes using
:func:`super`, see `guide to using super()
<https://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_.
.. versionchanged:: 3.14
:class:`super` objects are now :mod:`pickleable <pickle>` and
:mod:`copyable <copy>`.
.. _func-tuple:
.. class:: tuple(iterable=(), /)
:noindex:
Rather than being a function, :class:`tuple` is actually an immutable
sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`.
.. class:: type(object, /)
type(name, bases, dict, /, **kwargs)
.. index:: pair: object; type
With one argument, return the type of an *object*. The return value is a
type object and generally the same object as returned by
:attr:`object.__class__`.
The :func:`isinstance` built-in function is recommended for testing the type
of an object, because it takes subclasses into account.
With three arguments, return a new type object. This is essentially a
dynamic form of the :keyword:`class` statement. The *name* string is
the class name and becomes the :attr:`~type.__name__` attribute.
The *bases* tuple contains the base classes and becomes the
:attr:`~type.__bases__` attribute; if empty, :class:`object`, the
ultimate base of all classes, is added. The *dict* dictionary contains
attribute and method definitions for the class body; it may be copied
or wrapped before becoming the :attr:`~type.__dict__` attribute.
The following two statements create identical :class:`!type` objects:
>>> class X:
... a = 1
...
>>> X = type('X', (), dict(a=1))
See also:
* :ref:`Documentation on attributes and methods on classes <class-attrs-and-methods>`.
* :ref:`bltin-type-objects`
Keyword arguments provided to the three argument form are passed to the
appropriate metaclass machinery (usually :meth:`~object.__init_subclass__`)
in the same way that keywords in a class
definition (besides *metaclass*) would.
Unlike a :keyword:`class` statement, the three argument form does not
call the metaclass ``__prepare__`` method (see :ref:`prepare`). Use
:func:`types.new_class` to dynamically create a class using the
appropriate metaclass.
See also :ref:`class-customization`.
.. versionchanged:: 3.6
Subclasses of :class:`!type` which don't override ``type.__new__`` may no
longer use the one-argument form to get the type of an object.
.. versionchanged:: 3.15
*dict* can now be a :class:`frozendict`.
.. function:: vars()
vars(object, /)
Return the :attr:`~object.__dict__` attribute for a module, class, instance,
or any other object with a :attr:`!__dict__` attribute.
Objects such as modules and instances have an updateable :attr:`~object.__dict__`
attribute; however, other objects may have write restrictions on their
:attr:`!__dict__` attributes (for example, classes use a
:class:`types.MappingProxyType` to prevent direct dictionary updates).
Without an argument, :func:`vars` acts like :func:`locals`.
A :exc:`TypeError` exception is raised if an object is specified but
it doesn't have a :attr:`~object.__dict__` attribute (for example, if
its class defines the :attr:`~object.__slots__` attribute).
.. versionchanged:: 3.13
The result of calling this function without an argument has been
updated as described for the :func:`locals` builtin.
.. function:: zip(*iterables, strict=False)
Iterate over several iterables in parallel, producing tuples with an item
from each one.
Example::
>>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):
... print(item)
...
(1, 'sugar')
(2, 'spice')
(3, 'everything nice')
More formally: :func:`zip` returns an iterator of tuples, where the *i*-th
tuple contains the *i*-th element from each of the argument iterables.
Another way to think of :func:`zip` is that it turns rows into columns, and
columns into rows. This is similar to `transposing a matrix
<https://en.wikipedia.org/wiki/Transpose>`_.
:func:`zip` is lazy: The elements won't be processed until the iterable is
iterated on, e.g. by a :keyword:`!for` loop or by wrapping in a
:class:`list`.
One thing to consider is that the iterables passed to :func:`zip` could have
different lengths; sometimes by design, and sometimes because of a bug in
the code that prepared these iterables. Python offers three different
approaches to dealing with this issue:
* By default, :func:`zip` stops when the shortest iterable is :term:`exhausted`.
It will ignore the remaining items in the longer iterables, cutting off
the result to the length of the shortest iterable::
>>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))
[(0, 'fee'), (1, 'fi'), (2, 'fo')]
* :func:`zip` is often used in cases where the iterables are assumed to be
of equal length. In such cases, it's recommended to use the ``strict=True``
option. Its output is the same as regular :func:`zip`::
>>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))
[('a', 1), ('b', 2), ('c', 3)]
Unlike the default behavior, it raises a :exc:`ValueError` if one iterable
is :term:`exhausted` before the others:
>>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True): # doctest: +SKIP
... print(item)
...
(0, 'fee')
(1, 'fi')
(2, 'fo')
Traceback (most recent call last):
...
ValueError: zip() argument 2 is longer than argument 1
..
This doctest is disabled because doctest does not support capturing
output and exceptions in the same code unit.
https://github.com/python/cpython/issues/65382
Without the ``strict=True`` argument, any bug that results in iterables of
different lengths will be silenced, possibly manifesting as a hard-to-find
bug in another part of the program.
* Shorter iterables can be padded with a constant value to make all the
iterables have the same length. This is done by
:func:`itertools.zip_longest`.
Edge cases: With a single iterable argument, :func:`zip` returns an
iterator of 1-tuples. With no arguments, it returns an empty iterator.
Tips and tricks:
* The left-to-right evaluation order of the iterables is guaranteed. This
makes possible an idiom for clustering a data series into n-length groups
using ``zip(*[iter(s)]*n, strict=True)``. This repeats the *same* iterator
``n`` times so that each output tuple has the result of ``n`` calls to the
iterator. This has the effect of dividing the input into n-length chunks.
* :func:`zip` in conjunction with the ``*`` operator can be used to unzip a
list::
>>> x = [1, 2, 3]
>>> y = [4, 5, 6]
>>> list(zip(x, y))
[(1, 4), (2, 5), (3, 6)]
>>> x2, y2 = zip(*zip(x, y))
>>> x == list(x2) and y == list(y2)
True
.. versionchanged:: 3.10
Added the ``strict`` argument.
.. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0)
.. index::
pair: statement; import
pair: module; builtins
.. note::
This is an advanced function that is not needed in everyday Python
programming, unlike :func:`importlib.import_module`.
This function is invoked by the :keyword:`import` statement. It can be
replaced (by importing the :mod:`builtins` module and assigning to
``builtins.__import__``) in order to change semantics of the
:keyword:`!import` statement, but doing so is **strongly** discouraged as it
is usually simpler to use import hooks (see :pep:`302`) to attain the same
goals and does not cause issues with code which assumes the default import
implementation is in use. Direct use of :func:`__import__` is also
discouraged in favor of :func:`importlib.import_module`.
The function imports the module *name*, potentially using the given *globals*
and *locals* to determine how to interpret the name in a package context.
The *fromlist* gives the names of objects or submodules that should be
imported from the module given by *name*. The standard implementation does
not use its *locals* argument at all and uses its *globals* only to
determine the package context of the :keyword:`import` statement.
*level* specifies whether to use absolute or relative imports. ``0`` (the
default) means only perform absolute imports. Positive values for
*level* indicate the number of parent directories to search relative to the
directory of the module calling :func:`__import__` (see :pep:`328` for the
details).
When the *name* variable is of the form ``package.module``, normally, the
top-level package (the name up till the first dot) is returned, *not* the
module named by *name*. However, when a non-empty *fromlist* argument is
given, the module named by *name* is returned.
For example, the statement ``import spam`` results in bytecode resembling the
following code::
spam = __import__('spam', globals(), locals(), [], 0)
The statement ``import spam.ham`` results in this call::
spam = __import__('spam.ham', globals(), locals(), [], 0)
Note how :func:`__import__` returns the toplevel module here because this is
the object that is bound to a name by the :keyword:`import` statement.
On the other hand, the statement ``from spam.ham import eggs, sausage as
saus`` results in ::
_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
eggs = _temp.eggs
saus = _temp.sausage
Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
object, the names to import are retrieved and assigned to their respective
names.
If you simply want to import a module (potentially within a package) by name,
use :func:`importlib.import_module`.
.. versionchanged:: 3.3
Negative values for *level* are no longer supported (which also changes
the default value to 0).
.. versionchanged:: 3.9
When the command line options :option:`-E` or :option:`-I` are being used,
the environment variable :envvar:`PYTHONCASEOK` is now ignored.
.. rubric:: Footnotes
.. [#] Note that the parser only accepts the Unix-style end of line convention.
If you are reading the code from a file, make sure to use newline conversion
mode to convert Windows or Mac-style newlines.
---
### Doc Builtins Index (`Doc/builtins/index.rst`)
.. _builtins-index:
##############################
Python built-ins reference
##############################
Python comes with a number of built-in functions and classes.
The built-in classes include data types that would normally be considered part
of the "core" of a language, such as numbers and lists. For these types, the
Python language core defines the form of literals and places some constraints
on their semantics, but does not fully define the semantics.
The built-ins also include functions and exceptions --- objects that can
be used by all Python code without the need of an :keyword:`import` statement.
Some of these are defined by the core language, but many are not essential for
the core semantics and are only described here.
.. seealso::
In addition to the built-ins, Python provides an extensive importable
standard library, see :ref:`library-index`.
.. We don't use :numbered: option for the TOC below as it enforces
numbered sections for the entire builtin docs. If desired,
:numbered: can be enabled on a per-page basis.
.. toctree::
:maxdepth: 2
stdtypes.rst
constants.rst
functions.rst
exceptions.rst
threadsafety.rst
time-complexity.rst
---
### Doc Builtins Stdtypes (`Doc/builtins/stdtypes.rst`)
.. 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 be 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.
.. _iterator-types:
.. _typeiter:
Iteration-related 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.
Iterables
---------
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.
.. _stdtypes-iterators:
Iterators
---------
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:`generators <generator>` -- or more precisely,
:term:`generator functions <generator function>` and
:term:`generator iterators <generator iterator>` -- provide a convenient way
to implement the iterator protocol.
A function that contains one or more :ref:`yield expressions <yieldexpr>`
is a :term:`generator function`.
For example::
>>> def count_to_three():
... yield 0
... yield 1
... yield 2
... yield 3
Generator functions behave as regular
:ref:`user-defined functions <user-defined-funcs>`
(for example, they have the same attributes), except that calling a generator
function returns a :ref:`generator iterator <generator-methods>`::
>>> count_to_three()
<generator object count_to_three at 0x7f33a2305000>
Iterating a generator iterator executes code of the underlying
generator function, producing each :keyword:`yield`\ed value in turn::
>>> for number in count_to_three():
... print(number)
0
1
2
3
>>> list(count_to_three())
[0, 1, 2, 3]
One common use for generator functions is implementing the
:meth:`~object.__iter__` method of custom iterable objects.
For example::
>>> class CardDeck:
... def __iter__(self):
... yield 'three of clubs'
... yield 'ace of hearts'
>>> list(CardDeck())
['three of clubs', 'ace of hearts']
.. index:: pair: object; generator
.. _generator-methods:
Generator iterators
^^^^^^^^^^^^^^^^^^^
Generator iterators implement the
:ref:`iterator protocol <stdtypes-iterators>`.
Iterating them drives execution of the underlying generator function.
.. index:: pair: exception; StopIteration
.. method:: generator.__next__()
Starts the execution of a generator function or resumes it at the
:ref:`yield expression <yieldexpr>` where the function is currently suspended.
When a generator function is resumed with a :meth:`~generator.__next__`
method, the current yield expression always evaluates to :const:`None`.
The execution then continues to the next yield expression, where the
generator is suspended again, and the value of the expression after the
:keyword:`yield` keyword is returned to :meth:`~generator.__next__`'s
caller.
If the generator exits without yielding another value,
:meth:`~generator.__next__` raises a :exc:`StopIteration` exception,
signalling that iteration has completed.
This method is normally called implicitly, for example by a :keyword:`for`
loop, or by the built-in :func:`next` function.
Generator iterators have a few more methods than generic iterators, which
can be used to control the execution of the underlying generator function:
.. method:: generator.send(value)
"Sends" a value into the generator function: the *value* argument becomes
the result of the current yield expression.
Otherwise, this method behaves like :meth:`~generator.__next__`: it resumes
the underlying function and either returns the next yielded value or raises
:exc:`StopIteration`.
When :meth:`send` is called to start the generator, it must be called
with :const:`None` as the argument, because there is no current yield
expression that could receive the value.
.. method:: generator.throw(value)
generator.throw(type[, value[, traceback]])
Raises an exception at the point where the generator is currently suspended.
Otherwise, this method behaves like :meth:`~generator.__next__`: it resumes
the underlying function and either returns the next yielded value or raises
:exc:`StopIteration`.
If the generator function does not catch the passed-in exception, or
raises a different exception, then that exception propagates to the caller.
When :meth:`throw` is called to start the generator, the generator
immediately exits (that is, subsequent calls to :meth:`~generator.__next__`
will raise :exc:`StopIteration`) and the thrown exception is propagated to
:meth:`throw`'s caller.
In typical use, this is called with a single argument, an exception instance,
similar to the way the :keyword:`raise` keyword is used.
For backwards compatibility, however, the second signature is
supported, following a convention from older versions of Python.
The *type* argument should be an exception class, and *value*
should be an exception instance. If the *value* is not provided, the
*type* constructor is called to get an instance. If *traceback*
is provided, it is set on the exception, otherwise any existing
:attr:`~BaseException.__traceback__` attribute stored in *value* may
be cleared.
.. versionchanged:: 3.12
The second signature \(type\[, value\[, traceback\]\]\) is deprecated and
may be removed in a future version of Python.
.. index:: pair: exception; GeneratorExit
.. method:: generator.close()
Raises a :exc:`GeneratorExit` exception at the point where the generator
function is currently suspended (equivalent to calling ``throw(GeneratorExit)``).
If the generator function has already exited (due to an exception or
normal return), or raises :exc:`GeneratorExit` (by not catching the
exception), :meth:`close` returns :const:`None`.
If the generator yields a value, a :exc:`RuntimeError` is raised.
If the generator raises any other exception, it is propagated to the caller.
If a generator returns a value upon being closed, that value is returned
by :meth:`close`.
When a generator iterator is garbage collected before it has exited,
:meth:`~generator.close` is called automatically.
.. versionchanged:: 3.13
If a generator returns a value upon being closed, the value is returned
by :meth:`close`.
Previously, it returned ``None``.
Calling any of the generator methods (:meth:`~generator.__next__`,
:meth:`~generator.send`, :meth:`~generator.throw`, :meth:`~generator.close`)
while one of these methods is already executing
raises a :exc:`ValueError` exception.
.. index:: pair: object; asynchronous-generator
.. _asynchronous-generator-methods:
Asynchronous generator iterators
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This subsection describes the methods of an asynchronous generator iterator,
which are used to control the execution of an asynchronous generator function.
.. index:: pair: exception; StopAsyncIteration
.. method:: agen.__anext__()
:async:
Returns an :term:`awaitable` which when run starts to execute the
asynchronous generator function or resumes it at the
:ref:`yield expression <yieldexpr>` where the function is currently suspended.
When an asynchronous generator function is resumed with an
:meth:`~agen.__anext__` method, the current yield expression always
evaluates to :const:`None` in the returned awaitable, which when run will
continue to the next yield expression.
The value of the expression after the :keyword:`yield` keyword is the value
of the :exc:`StopIteration` exception raised by the completing coroutine.
If the asynchronous generator exits without yielding another value, the
awaitable instead raises a :exc:`StopAsyncIteration` exception,
signalling that the asynchronous iteration has completed.
This method is normally called implicitly by an :keyword:`async for` loop,
or by the built-in :func:`anext` function.
Asynchronous generator-iterators have a few more methods than generic
asynchronous iterators, which can be used to control the execution of
the underlying generator function:
.. method:: agen.asend(value)
:async:
Returns an awaitable which, when run, "sends" a value into the underlying
asynchronous generator function: the *value* argument becomes
the result of the current yield expression.
Otherwise, this method behaves like :meth:`~agen.__anext__`: when the
returned awaitable runs, it resumes the underlying function and either
returns the next yielded value as the value of the raised
:exc:`StopIteration`, or raises :exc:`StopAsyncIteration`.
When :meth:`asend` is called to start the asynchronous
generator, it must be called with :const:`None` as the argument,
because there is no yield expression that could receive the value.
.. method:: agen.athrow(value)
agen.athrow(type[, value[, traceback]])
:async:
Returns an awaitable that, when run, raises an exception at the point where
the underlying asynchronous generator function is currently suspended.
Otherwise, this method behaves like :meth:`~agen.__anext__`: when the
returned awaitable runs, it resumes the underlying function (with an
exception raised) and either returns the next yielded value as the value of
the raised :exc:`StopIteration`, or raises :exc:`StopAsyncIteration`.
If the underlying function does not catch the passed-in exception, or
raises a different exception, then when the awaitable is run, that
exception propagates to the caller of the awaitable.
When :meth:`~agen.athrow` is called to start the generator, the generator
exits when the awaitable runs (that is, subsequent results from
:meth:`~agen.__anext__` will raise :exc:`StopAsyncIteration` when run)
and the thrown exception is propagated to the awaitable's caller.
In typical use, this is called with a single argument, an exception instance,
similar to the way the :keyword:`raise` keyword is used.
For backwards compatibility, however, the second signature is
supported.
An exception instance is created from three arguments in the same way as in
:meth:`generator.throw`.
.. versionchanged:: 3.12
The second signature \(type\[, value\[, traceback\]\]\) is deprecated and
may be removed in a future version of Python.
.. index:: pair: exception; GeneratorExit
.. method:: agen.aclose()
:async:
Returns an awaitable that when run will throw a :exc:`GeneratorExit` into
the underlying asynchronous generator function at the point where it is
currently suspended (equivalent to calling ``athrow(GeneratorExit)``).
If the asynchronous generator function then exits gracefully, is already
closed, or raises :exc:`GeneratorExit` (by not catching the exception),
then the returned awaitable will raise a :exc:`StopIteration` exception.
Any further awaitables returned by subsequent calls to the asynchronous
generator will raise a :exc:`StopAsyncIteration` exception.
If the asynchronous generator yields a value, a :exc:`RuntimeError` is
raised by the awaitable.
If the asynchronous generator raises any other exception, that exception
is propagated to the caller of the awaitable.
If the asynchronous generator has already exited due to an exception or
normal exit, then further calls to :meth:`aclose` will return an awaitable
that does nothing.
.. _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]_
See :ref:`time-complexity` for the costs of the various sequence
operations.
.. index::
triple: operations on; sequence; types
pair: built-in function; len
pair: built-in function; min
pair: built-in function; max
pair: concatenation; operation
pair: repetition; operation
pair: subscript; operation
pair: slice; operation
pair: operator; in
pair: operator; not in
+--------------------------+--------------------------------+----------+
| Operation | Result | Notes |
+==========================+================================+==========+
| ``x in s`` | ``True`` if an item of *s* is | \(1) |
| | equal to *x*, else ``False`` | |
+--------------------------+--------------------------------+----------+
| ``x not in s`` | ``False`` if an item of *s* is | \(1) |
| | equal to *x*, else ``True`` | |
+--------------------------+--------------------------------+----------+
| ``s + t`` | the concatenation of *s* and | (6)(7) |
| | *t* | |
+--------------------------+--------------------------------+----------+
| ``s * n`` or | equivalent to adding *s* to | (2)(7) |
| ``n * s`` | itself *n* times | |
+--------------------------+--------------------------------+----------+
| ``s[i]`` | *i*\ th item of *s*, origin 0 | (3)(8) |
+--------------------------+--------------------------------+----------+
| ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) |
+--------------------------+--------------------------------+----------+
| ``s[i:j:k]`` | slice of *s* from *i* to *j* | (3)(5) |
| | with step *k* | |
+--------------------------+--------------------------------+----------+
| ``len(s)`` | length of *s* | |
+--------------------------+--------------------------------+----------+
| ``min(s)`` | smallest item of *s* | |
+--------------------------+--------------------------------+----------+
| ``max(s)`` | largest item of *s* | |
+--------------------------+--------------------------------+----------+
Sequences of the same type also support comparisons. In particular, tuples
and lists are compared lexicographically by comparing corresponding elements.
This means that to compare equal, every element must compare equal and the
two sequences must be of the same type and have the same length. (For full
details see :ref:`comparisons` in the language reference.)
.. index::
single: loop; over mutable sequence
single: mutable sequence; loop over
Forward and reversed iterators over mutable sequences access values using an
index. That index will continue to march forward (or backward) even if the
underlying sequence is mutated. The iterator terminates only when an
:exc:`IndexError` or a :exc:`StopIteration` is encountered (or when the index
drops below zero).
Notes:
(1)
While the ``in`` and ``not in`` operations are used only for simple
containment testing in the general case, some specialised sequences
(such as :class:`str`, :class:`bytes` and :class:`bytearray`) also use
them for subsequence testing::
>>> "gg" in "eggs"
True
(2)
Values of *n* less than ``0`` are treated as ``0`` (which yields an empty
sequence of the same type as *s*). Note that items in the sequence *s*
are not copied; they are referenced multiple times. This often haunts
new Python programmers; consider::
>>> lists = [[]] * 3
>>> lists
[[], [], []]
>>> lists[0].append(3)
>>> lists
[[3], [3], [3]]
What has happened is that ``[[]]`` is a one-element list containing an empty
list, so all three elements of ``[[]] * 3`` are references to this single empty
list. 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 entry
:ref:`faq-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`` is
still ``0``.
(4)
The slice of *s* from *i* to *j* is defined as the sequence of items with
index *k* such that ``i <= k < j``.
* If *i* is omitted or ``None``, use ``0``.
* If *j* is omitted or ``None``, use ``len(s)``.
* If *i* or *j* is less than ``-len(s)``, use ``0``.
* If *i* or *j* is greater than ``len(s)``, use ``len(s)``.
* If *i* is greater than or equal to *j*, the slice is empty.
(5)
The slice of *s* from *i* to *j* with step *k* is defined as the sequence of
items 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 when
*j* 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`` if
they 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``.
.. _typesseq-repeated-concatenation:
(6)
Concatenating immutable sequences always results in a new object. This
means that building up a sequence by repeated concatenation will have a
quadratic runtime cost in the total sequence length. To get a linear
runtime cost, you must switch to one of the alternatives below:
* if concatenating :class:`str` objects, you can build a list and use
:meth:`str.join` at the end or else write to an :class:`io.StringIO`
instance and retrieve its value when complete
* if concatenating :class:`bytes` objects, you can similarly use
:meth:`bytes.join` or :class:`io.BytesIO`, or you can do in-place
concatenation with a :class:`bytearray` object. :class:`bytearray`
objects are mutable and have an efficient overallocation mechanism
* if concatenating :class:`tuple` objects, extend a :class:`list` instead
* for other types, investigate the relevant class documentation
(7)
Some sequence types (such as :class:`range`) only support item sequences
that follow specific patterns, and hence don't support sequence
concatenation or repetition.
(8)
An :exc:`IndexError` is raised if *i* is outside the sequence range.
.. rubric:: Sequence Methods
Sequence types also support the following methods:
.. method:: list.count(value, /)
range.count(value, /)
tuple.count(value, /)
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.count(value, /)
Return the total number of occurrences of *value* in *sequence*.
.. method:: list.index(value[, start[, stop]])
range.index(value[, start[, stop]])
tuple.index(value[, start[, stop]])
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.index(value[, start[, stop]])
Return the index of the first occurrence of *value* in *sequence*.
Raises :exc:`ValueError` if *value* is not found in *sequence*.
The *start* or *stop* arguments allow for efficient searching
of subsections of the sequence, beginning at *start* and ending at *stop*.
This is roughly equivalent to ``start + sequence[start:stop].index(value)``,
only without copying any data.
.. caution::
Not all sequence types support passing the *start* and *stop* arguments.
.. _typesseq-immutable:
Immutable Sequence Types
------------------------
.. index::
triple: immutable; sequence; types
pair: object; tuple
pair: built-in function; hash
The only operation that immutable sequence types generally implement that is
not also implemented by mutable sequence types is support for the :func:`hash`
built-in.
This support allows immutable sequences, such as :class:`tuple` instances, to
be used as :class:`dict` keys and stored in :class:`set` and :class:`frozenset`
instances.
Attempting to hash an immutable sequence that contains unhashable values will
result in :exc:`TypeError`.
.. _typesseq-mutable:
Mutable Sequence Types
----------------------
.. index::
triple: mutable; sequence; types
pair: object; list
pair: object; bytearray
The operations in the following table are defined on mutable sequence types.
The :class:`collections.abc.MutableSequence` ABC is provided to make it
easier to correctly implement these operations on custom sequence types.
In the table *s* is an instance of a mutable sequence type, *t* is any
iterable object and *x* is an arbitrary object that meets any type
and value restrictions imposed by *s* (for example, :class:`bytearray` only
accepts integers that meet the value restriction ``0 <= x <= 255``).
.. index::
triple: operations on; sequence; types
triple: operations on; list; type
pair: subscript; assignment
pair: slice; assignment
pair: statement; del
+------------------------------+--------------------------------+---------------------+
| Operation | Result | Notes |
+==============================+================================+=====================+
| ``s[i] = x`` | item *i* of *s* is replaced by | |
| | *x* | |
+------------------------------+--------------------------------+---------------------+
| ``del s[i]`` | removes item *i* of *s* | |
+------------------------------+--------------------------------+---------------------+
| ``s[i:j] = t`` | slice of *s* from *i* to *j* | |
| | is replaced by the contents of | |
| | the iterable *t* | |
+------------------------------+--------------------------------+---------------------+
| ``del s[i:j]`` | removes the elements of | |
| | ``s[i:j]`` from the list | |
| | (same as ``s[i:j] = []``) | |
+------------------------------+--------------------------------+---------------------+
| ``s[i:j:k] = t`` | the elements of ``s[i:j:k]`` | \(1) |
| | are replaced by those of *t* | |
+------------------------------+--------------------------------+---------------------+
| ``del s[i:j:k]`` | removes the elements of | |
| | ``s[i:j:k]`` from the list | |
+------------------------------+--------------------------------+---------------------+
| ``s += t`` | extends *s* with the | |
| | contents of *t* (for the | |
| | most part the same as | |
| | ``s[len(s):len(s)] = t``) | |
+------------------------------+--------------------------------+---------------------+
| ``s *= n`` | updates *s* with its contents | \(2) |
| | repeated *n* times | |
+------------------------------+--------------------------------+---------------------+
Notes:
(1)
If *k* is not equal to ``1``, *t* must have the same length as the slice it is replacing.
(2)
The value *n* is an integer, or an object implementing
:meth:`~object.__index__`. Zero and negative values of *n* clear
the sequence. Items in the sequence are not copied; they are referenced
multiple times, as explained for ``s * n`` under :ref:`typesseq-common`.
.. rubric:: Mutable Sequence Methods
Mutable sequence types also support the following methods:
.. method:: bytearray.append(value, /)
list.append(value, /)
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.append(value, /)
Append *value* to the end of the sequence.
This is equivalent to writing ``seq[len(seq):len(seq)] = [value]``.
.. method:: bytearray.clear()
list.clear()
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.clear()
.. versionadded:: 3.3
Remove all items from *sequence*.
This is equivalent to writing ``del sequence[:]``.
.. method:: bytearray.copy()
list.copy()
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.copy()
.. versionadded:: 3.3
Create a shallow copy of *sequence*.
This is equivalent to writing ``sequence[:]``.
.. hint:: The :meth:`!copy` method is not part of the
:class:`~collections.abc.MutableSequence` :class:`~abc.ABC`,
but most concrete mutable sequence types provide it.
.. method:: bytearray.extend(iterable, /)
list.extend(iterable, /)
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.extend(iterable, /)
Extend *sequence* with the contents of *iterable*.
For the most part, this is the same as writing
``seq[len(seq):len(seq)] = iterable``.
.. method:: bytearray.insert(index, value, /)
list.insert(index, value, /)
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.insert(index, value, /)
Insert *value* into *sequence* at the given *index*.
This is equivalent to writing ``sequence[index:index] = [value]``.
.. method:: bytearray.pop(index=-1, /)
list.pop(index=-1, /)
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.pop(index=-1, /)
Retrieve the item at *index* and also remove it from *sequence*.
By default, the last item in *sequence* is removed and returned.
.. method:: bytearray.remove(value, /)
list.remove(value, /)
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.remove(value, /)
Remove the first item from *sequence* where ``sequence[i] == value``.
Raises :exc:`ValueError` if *value* is not found in *sequence*.
.. method:: bytearray.reverse()
list.reverse()
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.reverse()
Reverse the items of *sequence* in place.
This method maintains economy of space when reversing a large sequence.
To remind users that it operates by side-effect, it returns ``None``.
.. _typesseq-list:
Lists
-----
.. index:: pair: object; list
Lists are mutable sequences, typically used to store collections of
homogeneous items (where the precise degree of similarity will vary by
application).
.. 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 same
order as *iterable*'s items. *iterable* may be either a sequence, a
container that supports iteration, or an iterator object. If *iterable*
is already a list, a copy is made and returned, similar to ``iterable[:]``.
For example, ``list('abc')`` returns ``['a', 'b', 'c']`` and
``list( (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 :func:`sorted`
built-in.
Lists are :ref:`generic <generics>` over the types of their items.
Lists implement all of the :ref:`common <typesseq-common>` and
:ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the
following additional method:
.. method:: list.sort(*, key=None, reverse=False)
This method sorts the list in place, using only ``<`` comparisons
between items. Exceptions are not suppressed - if any comparison operations
fail, the entire sort operation will fail (and the list will likely be left
in a partially modified state).
:meth:`sort` accepts two arguments that can only be passed by keyword
(:ref:`keyword-only arguments <keyword-only_parameter>`):
*key* specifies a function of one argument that is used to extract a
comparison key from each list element (for example, ``key=str.lower``).
The key corresponding to each item in the list is calculated once and
then used for the entire sorting process. The default value of ``None``
means that list items are sorted directly without calculating a separate
key value.
The :func:`functools.cmp_to_key` utility is available to convert a 2.x
style *cmp* function to a *key* function.
*reverse* is a boolean value. If set to ``True``, then the list elements
are sorted as if each comparison were reversed.
This method modifies the sequence in place for economy of space when
sorting a large sequence. To remind users that it operates by side
effect, it does not return the sorted sequence (use :func:`sorted` to
explicitly request a new sorted list instance).
The :meth:`sort` method is guaranteed to be stable. A sort is stable if it
guarantees not to change the relative order of elements that compare equal
--- this is helpful for sorting in multiple passes (for example, sort by
department, then by salary grade).
For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
.. impl-detail::
While a list is being sorted, the effect of attempting to mutate, or even
inspect, the list is undefined. The C implementation of Python makes the
list appear empty for the duration, and raises :exc:`ValueError` if it can
detect that the list has been mutated during a sort.
.. seealso::
For detailed information on thread-safety guarantees for :class:`list`
objects, see :ref:`thread-safety-list`.
.. _typesseq-tuple:
Tuples
------
.. index:: pair: object; tuple
Tuples are immutable sequences, typically used to store collections of
heterogeneous data (such as the 2-tuples produced by the :func:`enumerate`
built-in). Tuples are also used for cases where an immutable sequence of
homogeneous data is needed (such as allowing storage in a :class:`set` or
:class:`dict` 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 :func:`tuple` built-in: ``tuple()`` or ``tuple(iterable)``
The constructor builds a tuple whose items are the same and in the same
order as *iterable*'s items. *iterable* may be either a sequence, a
container that supports iteration, or an iterator object. If *iterable*
is already a tuple, it is returned unchanged. For example,
``tuple('abc')`` returns ``('a', 'b', 'c')`` and
``tuple( [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, or
when they are needed to avoid syntactic ambiguity. For example,
``f(a, b, c)`` is a function call with three arguments, while
``f((a, b, c))`` is a function call with a 3-tuple as the sole argument.
Tuples implement all of the :ref:`common <typesseq-common>` sequence
operations.
Tuples are :ref:`generic <generics>` over the types of their contents.
For more information, refer to
:ref:`the typing documentation on annotating tuples <annotating-tuples>`.
For heterogeneous collections of data where access by name is clearer than
access by index, :func:`collections.namedtuple` may be a more appropriate
choice than a simple tuple object.
.. _typesseq-range:
Ranges
------
.. index:: pair: object; range
The :class:`range` type represents an immutable sequence of numbers and is
commonly used for looping a specific number of times in :keyword:`for`
loops.
.. class:: range(stop, /)
range(start, stop, step=1, /)
The arguments to the range constructor must be integers (either built-in
:class:`int` or any object that implements the :meth:`~object.__index__` special
method). If the *step* argument is omitted, it defaults to ``1``.
If the *start* argument is omitted, it defaults to ``0``.
If *step* is zero, :exc:`ValueError` is raised.
For a positive *step*, the contents of a range ``r`` are determined by the
formula ``r[i] = start + step*i`` where ``i >= 0`` and
``r[i] < stop``.
For a negative *step*, the contents of the range are still determined by
the formula ``r[i] = start + step*i``, but the constraints are ``i >= 0``
and ``r[i] > stop``.
A range object will be empty if ``r[0]`` does not meet the value
constraint. Ranges do support negative indices, but these are interpreted
as indexing from the end of the sequence determined by the positive
indices.
Ranges containing absolute values larger than :data:`sys.maxsize` are
permitted but some features (such as :func:`len`) may raise
:exc:`OverflowError`.
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 :ref:`common <typesseq-common>` sequence operations
except concatenation and repetition (due to the fact that range objects can
only represent sequences that follow a strict pattern and repetition and
concatenation will usually violate that pattern).
.. attribute:: start
The value of the *start* parameter (or ``0`` if the parameter was
not supplied)
.. attribute:: stop
The value of the *stop* parameter
.. attribute:: step
The value of the *step* parameter (or ``1`` if the parameter was
not supplied)
The advantage of the :class:`range` type over a regular :class:`list` or
:class:`tuple` is that a :class:`range` object will always take the same
(small) amount of memory, no matter the size of the range it represents (as it
only stores the ``start``, ``stop`` and ``step`` values, calculating individual
items and subranges as needed).
Range objects implement the :class:`collections.abc.Sequence` ABC, and provide
features such as containment tests, element index lookup, slicing and
support for negative indices (see :ref:`typesseq`):
>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18
Testing range objects for equality with ``==`` and ``!=`` compares
them as sequences. That is, two range objects are considered equal if
they represent the same sequence of values. (Note that two range
objects that compare equal might have different :attr:`~range.start`,
:attr:`~range.stop` and :attr:`~range.step` attributes, for example
``range(0) == range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
.. versionchanged:: 3.2
Implement the Sequence ABC.
Support slicing and negative indices.
Test :class:`int` objects for membership in constant time instead of
iterating through all items.
.. versionchanged:: 3.3
Define '==' and '!=' to compare range objects based on the
sequence of values they define (instead of comparing based on
object identity).
Added the :attr:`~range.start`, :attr:`~range.stop` and :attr:`~range.step`
attributes.
.. seealso::
* The `linspace recipe <https://code.activestate.com/recipes/579000-equally-spaced-numbers-linspace/>`_
shows how to implement a lazy version of range suitable for floating-point
applications.
.. index::
single: string; text sequence type
single: str (built-in class); (see also string)
pair: object; string
.. _text-methods-summary:
Text and Binary Sequence Type Methods Summary
=============================================
The following table summarizes the text and binary sequence types methods by
category.
+--------------------------+-------------------------------------------+---------------------------------------------------+
| Category | :class:`str` methods | :class:`bytes` and :class:`bytearray` methods |
+==========================+===========================================+===================================================+
| Formatting | :meth:`str.format` | |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.format_map` | |
| +-------------------------------------------+---------------------------------------------------+
| | :ref:`f-strings` | |
| +-------------------------------------------+---------------------------------------------------+
| | :ref:`old-string-formatting` | :ref:`bytes-formatting` |
+--------------------------+------------------+------------------------+--------------------+------------------------------+
| Searching and Replacing | :meth:`str.find` | :meth:`str.rfind` | :meth:`bytes.find` | :meth:`bytes.rfind` |
| +------------------+------------------------+--------------------+------------------------------+
| | :meth:`str.index`| :meth:`str.rindex` | :meth:`bytes.index`| :meth:`bytes.rindex` |
| +------------------+------------------------+--------------------+------------------------------+
| | :meth:`str.startswith` | :meth:`bytes.startswith` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.endswith` | :meth:`bytes.endswith` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.count` | :meth:`bytes.count` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.replace` | :meth:`bytes.replace` |
+--------------------------+-------------------+-----------------------+---------------------+-----------------------------+
| Splitting and Joining | :meth:`str.split` | :meth:`str.rsplit` | :meth:`bytes.split` | :meth:`bytes.rsplit` |
| +-------------------+-----------------------+---------------------+-----------------------------+
| | :meth:`str.splitlines` | :meth:`bytes.splitlines` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.partition` | :meth:`bytes.partition` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.rpartition` | :meth:`bytes.rpartition` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.join` | :meth:`bytes.join` |
+--------------------------+-------------------------------------------+---------------------------------------------------+
| String Classification | :meth:`str.isalpha` | :meth:`bytes.isalpha` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.isdecimal` | |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.isdigit` | :meth:`bytes.isdigit` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.isnumeric` | |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.isalnum` | :meth:`bytes.isalnum` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.isidentifier` | |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.islower` | :meth:`bytes.islower` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.isupper` | :meth:`bytes.isupper` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.istitle` | :meth:`bytes.istitle` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.isspace` | :meth:`bytes.isspace` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.isprintable` | |
+--------------------------+-------------------------------------------+---------------------------------------------------+
| Case Manipulation | :meth:`str.lower` | :meth:`bytes.lower` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.upper` | :meth:`bytes.upper` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.casefold` | |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.capitalize` | :meth:`bytes.capitalize` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.title` | :meth:`bytes.title` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.swapcase` | :meth:`bytes.swapcase` |
+--------------------------+-------------------+-----------------------+---------------------+-----------------------------+
| Padding and Stripping | :meth:`str.ljust` | :meth:`str.rjust` | :meth:`bytes.ljust` | :meth:`bytes.rjust` |
| +-------------------+-----------------------+---------------------+-----------------------------+
| | :meth:`str.center` | :meth:`bytes.center` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.expandtabs` | :meth:`bytes.expandtabs` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.strip` | :meth:`bytes.strip` |
| +--------------------+----------------------+----------------------+----------------------------+
| | :meth:`str.lstrip` | :meth:`str.rstrip` | :meth:`bytes.lstrip` | :meth:`bytes.rstrip` |
| +--------------------+----------------------+----------------------+----------------------------+
| | :meth:`str.removeprefix` | :meth:`bytes.removeprefix` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.removesuffix` | :meth:`bytes.removesuffix` |
+--------------------------+-------------------------------------------+---------------------------------------------------+
| Translation and Encoding | :meth:`str.translate` | :meth:`bytes.translate` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.maketrans` | :meth:`bytes.maketrans` |
| +-------------------------------------------+---------------------------------------------------+
| | :meth:`str.encode` | |
| +-------------------------------------------+---------------------------------------------------+
| | | :meth:`bytes.decode` |
+--------------------------+-------------------------------------------+---------------------------------------------------+
.. _textseq:
Text Sequence Type --- :class:`str`
===================================
Textual data in Python is handled with :class:`str` objects, or :dfn:`strings`.
Strings are immutable
:ref:`sequences <typesseq>` of Unicode code points. String literals are
written in a variety of ways:
* Single quotes: ``'allows embedded "double" quotes'``
* Double quotes: ``"allows embedded 'single' quotes"``
* Triple quoted: ``'''Three single quotes'''``, ``"""Three double quotes"""``
Triple quoted strings may span multiple lines - all associated whitespace will
be included in the string literal.
String literals that are part of a single expression and have only whitespace
between them will be implicitly converted to a single string literal. That
is, ``("spam " "eggs") == "spam eggs"``.
See :ref:`strings` for more about the various forms of string literal,
including supported :ref:`escape sequences <escape-sequences>`, and the ``r`` ("raw") prefix that
disables most escape sequence processing.
Strings may also be created from other objects using the :class:`str`
constructor.
Since there is no separate "character" type, indexing a string produces
strings of length 1. That is, for a non-empty string *s*, ``s[0] == s[0:1]``.
.. index::
pair: object; io.StringIO
There is also no mutable string type, but :meth:`str.join` or
:class:`io.StringIO` can be used to efficiently construct strings from
multiple fragments.
.. versionchanged:: 3.3
For backwards compatibility with the Python 2 series, the ``u`` prefix is
once again permitted on string literals. It has no effect on the meaning
of string literals and cannot be combined with the ``r`` prefix.
.. index::
single: string; str (built-in class)
.. class:: str(*, encoding='utf-8', errors='strict')
str(object)
str(object, encoding, errors='strict')
str(object, *, errors)
Return a :ref:`string <textseq>` version of *object*. If *object* is not
provided, returns the empty string. Otherwise, the behavior of ``str()``
depends on whether *encoding* or *errors* is given, as follows.
If neither *encoding* nor *errors* is given, ``str(object)`` returns
:meth:`type(object).__str__(object) <object.__str__>`,
which is the "informal" or nicely
printable string representation of *object*. For string objects, this is
the string itself. If *object* does not have a :meth:`~object.__str__`
method, then :func:`str` falls back to returning
:func:`repr(object) <repr>`.
.. index::
single: buffer protocol; str (built-in class)
single: bytes; str (built-in class)
If at least one of *encoding* or *errors* is given, *object* should be a
:term:`bytes-like object` (e.g. :class:`bytes` or :class:`bytearray`). In
this case, if *object* is a :class:`bytes` (or :class:`bytearray`) object,
then ``str(bytes, encoding, errors)`` is equivalent to
:meth:`bytes.decode(encoding, errors) <bytes.decode>`. Otherwise, the bytes
object underlying the buffer object is obtained before calling
:meth:`bytes.decode`. See :ref:`binaryseq` and
:ref:`bufferobjects` for information on buffer objects.
Passing a :class:`bytes` object to :func:`str` without the *encoding*
or *errors* arguments falls under the first case of returning the informal
string representation (see also the :option:`-b` command-line option to
Python). For example::
>>> str(b'Zoot!')
"b'Zoot!'"
For more information on the ``str`` class and its methods, see
:ref:`textseq` and the :ref:`string-methods` section below. To output
formatted strings, see the :ref:`f-strings` and :ref:`formatstrings`
sections. In addition, see the :ref:`stringservices` section.
.. index::
pair: string; methods
.. _string-methods:
String Methods
--------------
.. index::
pair: module; re
Strings implement all of the :ref:`common <typesseq-common>` sequence
operations, along with the additional methods described below.
Strings also support two styles of string formatting, one providing a large
degree of flexibility and customization (see :meth:`str.format`,
:ref:`formatstrings` and :ref:`string-formatting`) and the other based on C
``printf`` style formatting that handles a narrower range of types and is
slightly harder to use correctly, but is often faster for the cases it can
handle (:ref:`old-string-formatting`).
The :ref:`textservices` section of the standard library covers a number of
other modules that provide various text related utilities (including regular
expression support in the :mod:`re` module).
.. method:: str.capitalize()
Return a copy of the string with its first character capitalized and the
rest lowercased.
.. versionchanged:: 3.8
The first character is now put into titlecase rather than uppercase.
This means that characters like digraphs will only have their first
letter capitalized, instead of the full character.
.. method:: str.casefold()
Return a casefolded copy of the string. Casefolded strings may be used for
caseless matching.
Casefolding is similar to lowercasing but more aggressive because it is
intended to remove all case distinctions in a string. For example, the German
lowercase letter ``'Γ'`` is equivalent to ``"ss"``. Since it is already
lowercase, :meth:`lower` would do nothing to ``'Γ'``; :meth:`casefold`
converts it to ``"ss"``.
For example:
.. doctest::
>>> 'straΓe'.lower()
'straΓe'
>>> 'straΓe'.casefold()
'strasse'
The casefolding algorithm is `described in section 3.13.3 'Default Case
Folding' of the Unicode Standard
<https://www.unicode.org/versions/Unicode18.0.0/core-spec/chapter-3/#G53253>`__.
.. versionadded:: 3.3
.. method:: str.center(width, fillchar=' ', /)
Return centered in a string of length *width*. Padding is done using the
specified *fillchar* (default is an ASCII space). The original string is
returned if *width* is less than or equal to ``len(s)``. For example::
>>> 'Python'.center(10)
' Python '
>>> 'Python'.center(10, '-')
'--Python--'
>>> 'Python'.center(4)
'Python'
.. method:: str.count(sub[, start[, end]])
Return the number of non-overlapping occurrences of substring *sub* in the
range [*start*, *end*]. Optional arguments *start* and *end* are
interpreted as in slice notation.
If *sub* is empty, returns the number of empty strings between characters
which is the length of the string plus one. For example::
>>> 'spam, spam, spam'.count('spam')
3
>>> 'spam, spam, spam'.count('spam', 5)
2
>>> 'spam, spam, spam'.count('spam', 5, 10)
1
>>> 'spam, spam, spam'.count('eggs')
0
>>> 'spam, spam, spam'.count('')
17
.. method:: str.encode(encoding="utf-8", errors="strict")
Return the string encoded to :class:`bytes`.
*encoding* defaults to ``'utf-8'``;
see :ref:`standard-encodings` for possible values.
*errors* controls how encoding errors are handled.
If ``'strict'`` (the default), a :exc:`UnicodeError` exception is raised.
Other possible values are ``'ignore'``,
``'replace'``, ``'xmlcharrefreplace'``, ``'backslashreplace'`` and any
other name registered via :func:`codecs.register_error`.
See :ref:`error-handlers` for details.
For performance reasons, the value of *errors* is not checked for validity
unless an encoding error actually occurs,
:ref:`devmode` is enabled
or a :ref:`debug build <debug-build>` is used.
For example::
>>> encoded_str_to_bytes = 'Python'.encode()
>>> type(encoded_str_to_bytes)
<class 'bytes'>
>>> encoded_str_to_bytes
b'Python'
.. versionchanged:: 3.1
Added support for keyword arguments.
.. versionchanged:: 3.9
The value of the *errors* argument is now checked in :ref:`devmode` and
in :ref:`debug mode <debug-build>`.
.. method:: str.endswith(suffix[, start[, end]])
Return ``True`` if the string ends with the specified *suffix*, otherwise return
``False``. *suffix* can also be a tuple of suffixes to look for. With optional
*start*, test beginning at that position. With optional *end*, stop comparing
at that position. Using *start* and *end* is equivalent to
``str[start:end].endswith(suffix)``. For example::
>>> 'Python'.endswith('on')
True
>>> 'a tuple of suffixes'.endswith(('at', 'in'))
False
>>> 'a tuple of suffixes'.endswith(('at', 'es'))
True
>>> 'Python is amazing'.endswith('is', 0, 9)
True
See also :meth:`startswith` and :meth:`removesuffix`.
.. method:: str.expandtabs(tabsize=8)
Return a copy of the string where all tab characters are replaced by one or
more spaces, depending on the current column and the given tab size. Tab
positions occur every *tabsize* characters (default is 8, giving tab
positions at columns 0, 8, 16 and so on). To expand the string, the current
column is set to zero and the string is examined character by character. If
the character is a tab (``\t``), one or more space characters are inserted
in 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 to
zero. Any other character is copied unchanged and the current column is
incremented by one regardless of how the character is represented when
printed. For example::
>>> '01\t012\t0123\t01234'.expandtabs()
'01 012 0123 01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01 012 0123 01234'
>>> print('01\t012\n0123\t01234'.expandtabs(4))
01 012
0123 01234
.. method:: str.find(sub[, start[, end]])
Return the lowest index in the string where substring *sub* is found within
the slice ``s[start:end]``. Optional arguments *start* and *end* are
interpreted as in slice notation. Return ``-1`` if *sub* is not found.
For example::
>>> 'spam, spam, spam'.find('sp')
0
>>> 'spam, spam, spam'.find('sp', 5)
6
See also :meth:`rfind` and :meth:`index`.
.. note::
The :meth:`~str.find` method should be used only if you need to know the
position of *sub*. To check if *sub* is a substring or not, use the
:keyword:`in` operator::
>>> 'Py' in 'Python'
True
.. method:: str.format(*args, **kwargs)
Perform a string formatting operation. The string on which this method is
called can contain literal text or replacement fields delimited by braces
``{}``. Each replacement field contains either the numeric index of a
positional argument, or the name of a keyword argument. Returns a copy of
the string where each replacement field is replaced with the string value of
the corresponding argument. For example:
.. doctest::
>>> "The sum of 1 + 2 is {0}".format(1+2)
'The sum of 1 + 2 is 3'
>>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
'The sum of 1 + 2 is 3'
>>> "{1} expects the {0} Inquisition!".format("Spanish", "Nobody")
'Nobody expects the Spanish Inquisition!'
See :ref:`formatstrings` for a description of the various formatting options
that can be specified in format strings.
.. note::
When formatting a number (:class:`int`, :class:`float`, :class:`complex`,
:class:`decimal.Decimal` and subclasses) with the ``n`` type
(ex: ``'{:n}'.format(1234)``), the function temporarily sets the
``LC_CTYPE`` locale to the ``LC_NUMERIC`` locale to decode
``decimal_point`` and ``thousands_sep`` fields of :c:func:`localeconv` if
they are non-ASCII or longer than 1 byte, and the ``LC_NUMERIC`` locale is
different than the ``LC_CTYPE`` locale. This temporary change affects
other threads.
.. versionchanged:: 3.7
When formatting a number with the ``n`` type, the function sets
temporarily the ``LC_CTYPE`` locale to the ``LC_NUMERIC`` locale in some
cases.
.. method:: str.format_map(mapping, /)
Similar to ``str.format(**mapping)``, except that ``mapping`` is
used directly and not copied to a :class:`dict`. This is useful
if 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'
.. versionadded:: 3.2
.. method:: str.index(sub[, start[, end]])
Like :meth:`~str.find`, but raise :exc:`ValueError` when the substring is
not found. For example:
.. doctest::
>>> 'spam, spam, spam'.index('spam')
0
>>> 'spam, spam, spam'.index('eggs')
Traceback (most recent call last):
File "<python-input-0>", line 1, in <module>
'spam, spam, spam'.index('eggs')
~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found
See also :meth:`rindex`.
.. method:: str.isalnum()
Return ``True`` if all characters in the string are alphanumeric and there is at
least one character, ``False`` otherwise. A character ``c`` is alphanumeric if one
of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``,
``c.isdigit()``, or ``c.isnumeric()``. For example:
.. doctest::
>>> 'abc123'.isalnum()
True
>>> 'abc123!@#'.isalnum()
False
>>> ''.isalnum()
False
>>> ' '.isalnum()
False
.. method:: str.isalpha()
Return ``True`` if all characters in the string are alphabetic and there is at least
one character, ``False`` otherwise. Alphabetic characters are those characters defined
in the Unicode character database as "Letter", i.e., those with general category
property being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is different
from the `Alphabetic property defined in section 4.10 'Letters, Alphabetic, and
Ideographic' of the Unicode Standard
<https://www.unicode.org/versions/Unicode18.0.0/core-spec/chapter-4/#G91002>`__.
For example:
.. doctest::
>>> 'Letters and spaces'.isalpha()
False
>>> 'LettersOnly'.isalpha()
True
>>> 'Β΅'.isalpha() # non-ASCII characters can be considered alphabetical too
True
See :ref:`unicode-properties`.
.. method:: 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. For example:
.. doctest::
>>> 'ASCII characters'.isascii()
True
>>> 'Β΅'.isascii()
False
.. versionadded:: 3.7
.. method:: str.isdecimal()
Return ``True`` if all characters in the string are decimal
characters and there is at least one character, ``False``
otherwise. Decimal characters are those that can be used to form
numbers in base 10, such as U+0660, ARABIC-INDIC DIGIT
ZERO. Formally a decimal character is a character in the Unicode
General Category "Nd". For example:
.. doctest::
>>> '0123456789'.isdecimal()
True
>>> 'Ω Ω‘Ω’Ω£Ω€Ω₯Ω¦Ω§Ω¨Ω©'.isdecimal() # Arabic-Indic digits zero to nine
True
>>> 'alphabetic'.isdecimal()
False
.. method:: str.isdigit()
Return ``True`` if all characters in the string are digits and there is at least one
character, ``False`` otherwise. Digits include decimal characters and digits that need
special handling, such as the compatibility superscript digits.
This covers digits which cannot be used to form numbers in base 10,
like the `Kharosthi numbers <https://en.wikipedia.org/wiki/Kharosthi#Numerals>`__.
Formally, a digit is a character that has the
property value Numeric_Type=Digit or Numeric_Type=Decimal.
For example:
.. doctest::
>>> '0123456789'.isdigit()
True
>>> 'Ω Ω‘Ω’Ω£Ω€Ω₯Ω¦Ω§Ω¨Ω©'.isdigit() # Arabic-Indic digits zero to nine
True
>>> 'β
'.isdigit() # Vulgar fraction one fifth
False
>>> 'Β²'.isdecimal(), 'Β²'.isdigit(), 'Β²'.isnumeric()
(False, True, True)
See also :meth:`isdecimal` and :meth:`isnumeric`.
.. method:: str.isidentifier()
Return ``True`` if the string is a valid identifier according to the language
definition, section :ref:`identifiers`.
:func:`keyword.iskeyword` can be used to test whether string ``s`` is a reserved
identifier, such as :keyword:`def` and :keyword:`class`.
Example:
::
>>> from keyword import iskeyword
>>> 'hello'.isidentifier(), iskeyword('hello')
(True, False)
>>> 'def'.isidentifier(), iskeyword('def')
(True, True)
.. method:: str.islower()
Return ``True`` if all cased characters [4]_ in the string are lowercase and
there is at least one cased character, ``False`` otherwise.
.. method:: str.isnumeric()
Return ``True`` if all characters in the string are numeric
characters, and there is at least one character, ``False``
otherwise. Numeric characters include digit characters, and all characters
that have the Unicode numeric value property, e.g. U+2155,
VULGAR FRACTION ONE FIFTH. Formally, numeric characters are those with the property
value Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric.
For example:
.. doctest::
>>> '0123456789'.isnumeric()
True
>>> 'Ω Ω‘Ω’Ω£Ω€Ω₯Ω¦Ω§Ω¨Ω©'.isnumeric() # Arabic-Indic digits zero to nine
True
>>> 'β
'.isnumeric() # Vulgar fraction one fifth
True
>>> 'Β²'.isdecimal(), 'Β²'.isdigit(), 'Β²'.isnumeric()
(False, True, True)
See also :meth:`isdecimal` and :meth:`isdigit`.
.. method:: str.isprintable()
Return ``True`` if all characters in the string are printable, ``False`` if it
contains at least one non-printable character.
Here "printable" means the character is suitable for :func:`repr` to use in
its output; "non-printable" means that :func:`repr` on built-in types will
hex-escape the character. It has no bearing on the handling of strings
written to :data:`sys.stdout` or :data:`sys.stderr`.
The printable characters are those which in the Unicode character database
(see :mod:`unicodedata`) have a general category in group Letter, Mark,
Number, Punctuation, or Symbol (L, M, N, P, or S); plus the ASCII space 0x20.
Nonprintable characters are those in group Separator or Other (Z or C),
except the ASCII space.
For example:
.. doctest::
>>> ''.isprintable(), ' '.isprintable()
(True, True)
>>> '\t'.isprintable(), '\n'.isprintable()
(False, False)
See also :meth:`isspace`.
.. method:: str.isspace()
Return ``True`` if there are only whitespace characters in the string and there is
at least one character, ``False`` otherwise.
For example:
.. doctest::
>>> ''.isspace()
False
>>> ' '.isspace()
True
>>> '\t\n'.isspace() # TAB and BREAK LINE
True
>>> '\u3000'.isspace() # IDEOGRAPHIC SPACE
True
A character is *whitespace* if in the Unicode character database
(see :mod:`unicodedata`), either its general category is ``Zs``
("Separator, space"), or its bidirectional class is one of ``WS``,
``B``, or ``S``.
See also :meth:`isprintable`.
.. method:: str.istitle()
Return ``True`` if the string is a titlecased string and there is at least one
character, for example uppercase characters may only follow uncased characters
and lowercase characters only cased ones. Return ``False`` otherwise.
For example:
.. doctest::
>>> 'Spam, Spam, Spam'.istitle()
True
>>> 'spam, spam, spam'.istitle()
False
>>> 'SPAM, SPAM, SPAM'.istitle()
False
See also :meth:`title`.
.. method:: str.isupper()
Return ``True`` if all cased characters [4]_ in the string are uppercase and
there is at least one cased character, ``False`` otherwise.
>>> 'BANANA'.isupper()
True
>>> 'banana'.isupper()
False
>>> 'baNana'.isupper()
False
>>> ' '.isupper()
False
.. _meth-str-join:
.. method:: str.join(iterable, /)
Return a string which is the concatenation of the strings in *iterable*.
A :exc:`TypeError` will be raised if there are any non-string values in
*iterable*, including :class:`bytes` objects. The separator between
elements is the string providing this method. For example:
.. doctest::
>>> ', '.join(['spam', 'spam', 'spam'])
'spam, spam, spam'
>>> '-'.join('Python')
'P-y-t-h-o-n'
See also :meth:`split`.
.. method:: str.ljust(width, fillchar=' ', /)
Return the string left justified in a string of length *width*. Padding is
done using the specified *fillchar* (default is an ASCII space). The
original string is returned if *width* is less than or equal to ``len(s)``.
For example:
.. doctest::
>>> 'Python'.ljust(10)
'Python '
>>> 'Python'.ljust(10, '.')
'Python....'
>>> 'Monty Python'.ljust(10, '.')
'Monty Python'
See also :meth:`rjust`.
.. method:: str.lower()
Return a copy of the string with all the cased characters [4]_ converted to
lowercase. For example:
.. doctest::
>>> 'Lower Method Example'.lower()
'lower method example'
The lowercasing algorithm used is `described in section 3.13.2 'Default Case
Conversion' of the Unicode Standard
<https://www.unicode.org/versions/Unicode18.0.0/core-spec/chapter-3/#G34078>`__.
.. method:: str.lstrip(chars=None, /)
Return a copy of the string with leading 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, that is
characters for which :meth:`str.isspace` is true. The *chars*
argument is not a prefix; rather, all combinations of its values are stripped::
>>> ' spacious '.lstrip()
'spacious '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'
See :meth:`str.removeprefix` for a method that will remove a single prefix
string rather than all of a set of characters. For example::
>>> 'Arthur: three!'.lstrip('Arthur: ')
'ee!'
>>> 'Arthur: three!'.removeprefix('Arthur: ')
'three!'
.. staticmethod:: str.maketrans(dict, /)
str.maketrans(from, to, remove='', /)
This static method returns a translation table usable for :meth:`str.translate`.
If there is only one argument, it must be a dictionary mapping Unicode
ordinals (integers) or characters (strings of length 1) to Unicode ordinals,
strings (of arbitrary lengths) or ``None``. Character keys will then be
converted to ordinals.
If there are two arguments, they must be strings of equal length, and in the
resulting dictionary, each character in *from* will be mapped to the character at
the same position in *to*. If there is a third argument, it must be a string,
whose characters will be mapped to ``None`` in the result.
.. versionchanged:: 3.15
*dict* can now be a :class:`frozendict`.
.. method:: str.partition(sep, /)
Split the string at the first occurrence of *sep*, and return a 3-tuple
containing the part before the separator, the separator itself, and the part
after the separator. If the separator is not found, return a 3-tuple containing
the string itself, followed by two empty strings.
For example:
.. doctest::
>>> 'Monty Python'.partition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".partition(' ')
('Monty', ' ', "Python's Flying Circus")
>>> 'Monty Python'.partition('-')
('Monty Python', '', '')
See also :meth:`rpartition`.
.. method:: str.removeprefix(prefix, /)
If the string starts with the *prefix* string, return
``string[len(prefix):]``. Otherwise, return a copy of the original
string:
.. doctest::
>>> 'TestHook'.removeprefix('Test')
'Hook'
>>> 'BaseTestCase'.removeprefix('Test')
'BaseTestCase'
.. versionadded:: 3.9
See also :meth:`removesuffix` and :meth:`startswith`.
.. method:: 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 the
original string:
.. doctest::
>>> 'MiscTests'.removesuffix('Tests')
'Misc'
>>> 'TmpDirMixin'.removesuffix('Tests')
'TmpDirMixin'
.. versionadded:: 3.9
See also :meth:`removeprefix` and :meth:`endswith`.
.. method:: str.replace(old, new, /, count=-1)
Return a copy of the string with all occurrences of substring *old* replaced by
*new*. If *count* is given, only the first *count* occurrences are replaced.
If *count* is not specified or ``-1``, then all occurrences are replaced.
For example:
.. doctest::
>>> 'spam, spam, spam'.replace('spam', 'eggs')
'eggs, eggs, eggs'
>>> 'spam, spam, spam'.replace('spam', 'eggs', 1)
'eggs, spam, spam'
.. versionchanged:: 3.13
*count* is now supported as a keyword argument.
.. method:: str.rfind(sub[, start[, end]])
Return the highest index in the string where substring *sub* is found, such
that *sub* is contained within ``s[start:end]``. Optional arguments *start*
and *end* are interpreted as in slice notation. Return ``-1`` on failure.
For example:
.. doctest::
>>> 'spam, spam, spam'.rfind('sp')
12
>>> 'spam, spam, spam'.rfind('sp', 0, 10)
6
See also :meth:`find` and :meth:`rindex`.
.. method:: str.rindex(sub[, start[, end]])
Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not
found.
For example:
.. doctest::
>>> 'spam, spam, spam'.rindex('spam')
12
>>> 'spam, spam, spam'.rindex('eggs')
Traceback (most recent call last):
File "<stdin-0>", line 1, in <module>
'spam, spam, spam'.rindex('eggs')
~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found
See also :meth:`index` and :meth:`find`.
.. method:: str.rjust(width, fillchar=' ', /)
Return the string right justified in a string of length *width*. Padding is
done using the specified *fillchar* (default is an ASCII space). The
original string is returned if *width* is less than or equal to ``len(s)``.
For example:
.. doctest::
>>> 'Python'.rjust(10)
' Python'
>>> 'Python'.rjust(10, '.')
'....Python'
>>> 'Monty Python'.rjust(10, '.')
'Monty Python'
See also :meth:`ljust` and :meth:`zfill`.
.. method:: str.rpartition(sep, /)
Split the string at the last occurrence of *sep*, and return a 3-tuple
containing the part before the separator, the separator itself, and the part
after the separator. If the separator is not found, return a 3-tuple containing
two empty strings, followed by the string itself.
For example:
.. doctest::
>>> 'Monty Python'.rpartition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".rpartition(' ')
("Monty Python's Flying", ' ', 'Circus')
>>> 'Monty Python'.rpartition('-')
('', '', 'Monty Python')
See also :meth:`partition`.
.. method:: 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 *rightmost*
ones. If *sep* is not specified or ``None``, any
:meth:`whitespace <str.isspace>` string is a
separator. Except for splitting from the right, :meth:`rsplit` behaves like
:meth:`split` which is described in detail below.
.. method:: str.rstrip(chars=None, /)
Return a copy of the string with 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, that is
characters for which :meth:`str.isspace` is true. The *chars*
argument is not a suffix; rather, all combinations of its values are stripped.
For example:
.. doctest::
>>> ' spacious '.rstrip()
' spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'
See :meth:`removesuffix` for a method that will remove a single suffix
string rather than all of a set of characters. For example::
>>> 'Monty Python'.rstrip(' Python')
'M'
>>> 'Monty Python'.removesuffix(' Python')
'Monty'
See also :meth:`strip`.
.. method:: str.split(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 (thus,
the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not
specified 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 are
deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns
``['1', '', '2']``). The *sep* argument may consist of multiple characters
as a single delimiter (to split with multiple delimiters, use
:func:`re.split`). Splitting an empty string with a specified separator
returns ``['']``.
For example:
.. doctest::
>>> '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 is
applied: runs of consecutive :meth:`whitespace <str.isspace>` are regarded
as a single separator,
and the result will contain no empty strings at the start or end if the
string has leading or trailing whitespace. Consequently, splitting an empty
string or a string consisting of just whitespace with a ``None`` separator
returns ``[]``.
For example:
.. doctest::
>>> '1 2 3'.split()
['1', '2', '3']
>>> '1 2 3'.split(maxsplit=1)
['1', '2 3']
>>> ' 1 2 3 '.split()
['1', '2', '3']
If *sep* is not specified or is ``None`` and *maxsplit* is ``0``, only
leading runs of consecutive whitespace are considered.
For example:
.. doctest::
>>> "".split(None, 0)
[]
>>> " ".split(None, 0)
[]
>>> " foo ".split(maxsplit=0)
['foo ']
See also :meth:`join` and :meth:`rsplit`.
.. index::
single: universal newlines; str.splitlines method
.. method:: str.splitlines(keepends=False)
Return a list of the lines in the string, breaking at line boundaries. Line
breaks are not included in the resulting list unless *keepends* is given and
true.
This method splits on the following line boundaries. In particular, the
boundaries are a superset of :term:`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 |
+-----------------------+-----------------------------+
.. versionchanged:: 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 :meth:`~str.split` when a delimiter string *sep* is given, this
method returns an empty list for the empty string, and a terminal line
break 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', '']
.. method:: 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 comparing
string at that position.
For example:
.. doctest::
>>> 'Python'.startswith('Py')
True
>>> 'a tuple of prefixes'.startswith(('at', 'a'))
True
>>> 'Python is amazing'.startswith('is', 7)
True
See also :meth:`endswith` and :meth:`removeprefix`.
.. method:: str.strip(chars=None, /)
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,
that is characters for which :meth:`str.isspace` is true. The *chars* argument
is not a prefix or suffix; rather, all combinations of its values are stripped.
For example:
.. doctest::
>>> ' spacious '.strip()
'spacious'
>>> 'www.example.com'.strip('cmowz.')
'example'
The outermost leading and trailing *chars* argument values are stripped
from the string. Characters are removed from the leading end until
reaching a string character that is not contained in the set of
characters in *chars*. A similar action takes place on the trailing end.
For example:
.. doctest::
>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'
See also :meth:`rstrip`.
.. method:: str.swapcase()
Return a copy of the string with uppercase characters converted to lowercase and
vice versa. For example:
.. doctest::
>>> 'Hello World'.swapcase()
'hELLO wORLD'
Note that it is not necessarily true that ``s.swapcase().swapcase() == s``.
For example:
.. doctest::
>>> 'straΓe'.swapcase().swapcase()
'strasse'
See also :meth:`str.lower` and :meth:`str.upper`.
.. method:: str.title()
Return a titlecased version of the string where words start with an uppercase
character and the remaining characters are lowercase.
For example::
>>> 'Hello world'.title()
'Hello World'
The algorithm uses a simple language-independent definition of a word as
groups of consecutive letters. The definition works in many contexts but
it means that apostrophes in contractions and possessives form word
boundaries, 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 :func:`string.capwords` function does not have this problem, as it
splits words on spaces only.
Alternatively, a workaround for apostrophes can be constructed using regular
expressions::
>>> 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."
See also :meth:`istitle`.
.. method:: str.translate(table, /)
Return a copy of the string in which each character has been mapped through
the given translation table. The table must be an object that implements
indexing via :meth:`~object.__getitem__`, typically a :term:`mapping` or
:term:`sequence`. When indexed by a Unicode ordinal (an integer), the
table object can do any of the following: return a Unicode ordinal or a
string, to map the character to one or more other characters; return
``None``, to delete the character from the return string; or raise a
:exc:`LookupError` exception, to map the character to itself.
You can use :meth:`str.maketrans` to create a translation map from
character-to-character mappings in different formats.
The following example uses a mapping to replace ``'a'`` with ``'X'``,
``'b'`` with ``'Y'``, and delete ``'c'``:
.. doctest::
>>> 'abc123'.translate({ord('a'): 'X', ord('b'): 'Y', ord('c'): None})
'XY123'
See also the :mod:`codecs` module for a more flexible approach to custom
character mappings.
.. method:: str.upper()
Return a copy of the string with all the cased characters [4]_ converted to
uppercase. Note that ``s.upper().isupper()`` might be ``False`` if ``s``
contains uncased characters or if the Unicode category of the resulting
character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter,
titlecase).
The uppercasing algorithm used is `described in section 3.13.2 'Default Case
Conversion' of the Unicode Standard
<https://www.unicode.org/versions/Unicode18.0.0/core-spec/chapter-3/#G34078>`__.
.. method:: str.zfill(width, /)
Return a copy of the string left filled with ASCII ``'0'`` digits to
make a string of length *width*. A leading sign prefix (``'+'``/``'-'``)
is handled by inserting the padding *after* the sign character rather
than before. The original string is returned if *width* is less than
or equal to ``len(s)``.
For example:
.. doctest::
>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'
See also :meth:`rjust`.
.. index::
single: ! formatted string literal
single: formatted string literals
single: ! f-string
single: f-strings
single: fstring
single: interpolated string literal
single: string; formatted literal
single: string; interpolated literal
single: {} (curly brackets); in formatted string literal
single: ! (exclamation mark); in formatted string literal
single: : (colon); in formatted string literal
single: = (equals); for help in debugging using string literals
.. _stdtypes-fstrings:
Formatted String Literals (f-strings)
-------------------------------------
.. versionadded:: 3.6
.. versionchanged:: 3.7
The :keyword:`await` and :keyword:`async for` can be used in expressions
within f-strings.
.. versionchanged:: 3.8
Added the debug specifier (``=``)
.. versionchanged:: 3.12
Many restrictions on expressions within f-strings have been removed.
Notably, nested strings, comments, and backslashes are now permitted.
An :dfn:`f-string` (formally a :dfn:`formatted string literal`) is
a string literal that is prefixed with ``f`` or ``F``.
This type of string literal allows embedding the results of arbitrary Python
expressions within *replacement fields*, which are delimited by curly
brackets (``{}``).
Each replacement field must contain an expression, optionally followed by:
* a *debug specifier* -- an equal sign (``=``);
* a *conversion specifier* -- ``!s``, ``!r`` or ``!a``; and/or
* a *format specifier* prefixed with a colon (``:``).
See the :ref:`Lexical Analysis section on f-strings <f-strings>` for details
on the syntax of these fields.
Debug specifier
^^^^^^^^^^^^^^^
.. versionadded:: 3.8
If a debug specifier -- an equal sign (``=``) -- appears after the replacement
field expression, the resulting f-string will contain the expression's source,
the equal sign, and the value of the expression.
This is often useful for debugging::
>>> number = 14.3
>>> f'{number=}'
'number=14.3'
Whitespace before, inside and after the expression, as well as whitespace
after the equal sign, is significant --- it is retained in the result::
>>> f'{ number - 4 = }'
' number - 4 = 10.3'
Conversion specifier
^^^^^^^^^^^^^^^^^^^^
By default, the value of a replacement field expression is converted to
a string using :func:`str`::
>>> from fractions import Fraction
>>> one_third = Fraction(1, 3)
>>> f'{one_third}'
'1/3'
When a debug specifier but no format specifier is used, the default conversion
instead uses :func:`repr`::
>>> f'{one_third = }'
'one_third = Fraction(1, 3)'
The conversion can be specified explicitly using one of these specifiers:
* ``!s`` for :func:`str`
* ``!r`` for :func:`repr`
* ``!a`` for :func:`ascii`
For example::
>>> str(one_third)
'1/3'
>>> repr(one_third)
'Fraction(1, 3)'
>>> f'{one_third!s} is {one_third!r}'
'1/3 is Fraction(1, 3)'
>>> string = "Β‘koΔka πΈ!"
>>> ascii(string)
"'\\xa1ko\\u010dka \\U0001f638!'"
>>> f'{string = !a}'
"string = '\\xa1ko\\u010dka \\U0001f638!'"
Format specifier
^^^^^^^^^^^^^^^^
After the expression has been evaluated, and possibly converted using an
explicit conversion specifier, it is formatted using the :func:`format` function.
If the replacement field includes a *format specifier* introduced by a colon
(``:``), the specifier is passed to :func:`!format` as the second argument.
The result of :func:`!format` is then used as the final value for the
replacement field. For example::
>>> from fractions import Fraction
>>> one_third = Fraction(1, 3)
>>> f'{one_third:.6f}'
'0.333333'
>>> f'{one_third:_^+10}'
'___+1/3___'
>>> f'{one_third!r:_^20}'
'___Fraction(1, 3)___'
>>> f'{one_third = :~>10}~'
'one_third = ~~~~~~~1/3~'
.. _stdtypes-tstrings:
Template String Literals (t-strings)
------------------------------------
A :dfn:`t-string` (formally a :dfn:`template string literal`) is
a string literal that is prefixed with ``t`` or ``T``.
These strings follow the same syntax and evaluation rules as
:ref:`formatted string literals <stdtypes-fstrings>`,
with the following differences:
* Rather than evaluating to a ``str`` object, template string literals evaluate
to a :class:`string.templatelib.Template` object.
* The :func:`format` protocol is not used.
Instead, the format specifier and conversions (if any) are passed to
a new :class:`~string.templatelib.Interpolation` object that is created
for each evaluated expression.
It is up to code that processes the resulting :class:`~string.templatelib.Template`
object to decide how to handle format specifiers and conversions.
* Format specifiers containing nested replacement fields are evaluated eagerly,
prior to being passed to the :class:`~string.templatelib.Interpolation` object.
For instance, an interpolation of the form ``{amount:.{precision}f}`` will
evaluate the inner expression ``{precision}`` to determine the value of the
``format_spec`` attribute.
If ``precision`` were to be ``2``, the resulting format specifier
would be ``'.2f'``.
* When the equals sign ``'='`` is provided in an interpolation expression,
the text of the expression is appended to the literal string that precedes
the relevant interpolation.
This includes the equals sign and any surrounding whitespace.
The :class:`!Interpolation` instance for the expression will be created as
normal, except that :attr:`~string.templatelib.Interpolation.conversion` will
be set to '``r``' (:func:`repr`) by default.
If an explicit conversion or format specifier is provided,
this will override the default behaviour.
.. _old-string-formatting:
``printf``-style String Formatting
----------------------------------
.. index::
single: formatting, string (%)
single: interpolation, string (%)
single: string; formatting, printf
single: string; interpolation, printf
single: printf-style formatting
single: sprintf-style formatting
single: % (percent); printf-style formatting
.. note::
The formatting operations described here exhibit a variety of quirks that
lead to a number of common errors (such as failing to display tuples and
dictionaries correctly).
Using :ref:`formatted string literals <f-strings>`, the :meth:`str.format`
interface, or :class:`string.Template` may help avoid these errors.
Each of these alternatives provides their own trade-offs and benefits of
simplicity, flexibility, and/or extensibility.
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), ``%`` conversion
specifications in *format* are replaced with zero or more elements of *values*.
The effect is similar to using the :c:func:`sprintf` function in the C language.
For example:
.. doctest::
>>> print('%s has %d quote types.' % ('Python', 2))
Python has 2 quote types.
If *format* requires a single argument, *values* may be a single non-tuple
object. [5]_ Otherwise, *values* must be a tuple with exactly the number of
items specified by the format string, or a single mapping object (for example, a
dictionary).
.. index::
single: () (parentheses); in printf-style formatting
single: * (asterisk); in printf-style formatting
single: . (dot); in printf-style formatting
A conversion specifier contains two or more characters and has the following
components, which must occur in this order:
#. The ``'%'`` character, which marks the start of the specifier.
#. Mapping key (optional), consisting of a parenthesised sequence of characters
(for example, ``(somename)``).
#. Conversion flags (optional), which affect the result of some conversion
types.
#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the
actual width is read from the next element of the tuple in *values*, and the
object to convert comes after the minimum field width and optional precision.
#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If
specified as ``'*'`` (an asterisk), the actual precision is read from the next
element of the tuple in *values*, and the value to convert comes after the
precision.
#. Length modifier (optional).
#. Conversion type.
When the right argument is a dictionary (or other mapping type), then the
formats in the string *must* include a parenthesised mapping key into that
dictionary inserted immediately after the ``'%'`` character. The mapping key
selects 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 a
sequential parameter list).
The conversion flag characters are:
.. index::
single: # (hash); in printf-style formatting
single: - (minus); in printf-style formatting
single: + (plus); in printf-style formatting
single: space; in printf-style formatting
+---------+---------------------------------------------------------------------+
| Flag | Meaning |
+=========+=====================================================================+
| ``'#'`` | The value conversion will use the "alternate form" (where defined |
| | below). |
+---------+---------------------------------------------------------------------+
| ``'0'`` | The conversion will be zero padded for numeric values. |
+---------+---------------------------------------------------------------------+
| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` |
| | conversion if both are given). |
+---------+---------------------------------------------------------------------+
| ``' '`` | (a space) A blank should be left before a positive number (or empty |
| | string) produced by a signed conversion. |
+---------+---------------------------------------------------------------------+
| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion |
| | (overrides a "space" flag). |
+---------+---------------------------------------------------------------------+
A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it
is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``.
The conversion types are:
+------------+-----------------------------------------------------+-------+
| Conversion | Meaning | Notes |
+============+=====================================================+=======+
| ``'d'`` | Signed integer decimal. | |
+------------+-----------------------------------------------------+-------+
| ``'i'`` | Signed integer decimal. | |
+------------+-----------------------------------------------------+-------+
| ``'o'`` | Signed octal value. | \(1) |
+------------+-----------------------------------------------------+-------+
| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(6) |
+------------+-----------------------------------------------------+-------+
| ``'x'`` | Signed hexadecimal (lowercase). | \(2) |
+------------+-----------------------------------------------------+-------+
| ``'X'`` | Signed hexadecimal (uppercase). | \(2) |
+------------+-----------------------------------------------------+-------+
| ``'e'`` | Floating-point exponential format (lowercase). | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'E'`` | Floating-point exponential format (uppercase). | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'f'`` | Floating-point decimal format. | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'F'`` | Floating-point decimal format. | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'g'`` | Floating-point format. Uses lowercase exponential | \(4) |
| | format if exponent is less than -4 or not less than | |
| | precision, decimal format otherwise. | |
+------------+-----------------------------------------------------+-------+
| ``'G'`` | Floating-point format. Uses uppercase exponential | \(4) |
| | format if exponent is less than -4 or not less than | |
| | precision, decimal format otherwise. | |
+------------+-----------------------------------------------------+-------+
| ``'c'`` | Single character (accepts integer or single | |
| | character string). | |
+------------+-----------------------------------------------------+-------+
| ``'r'`` | String (converts any Python object using | \(5) |
| | :func:`repr`). | |
+------------+-----------------------------------------------------+-------+
| ``'s'`` | String (converts any Python object using | \(5) |
| | :func:`str`). | |
+------------+-----------------------------------------------------+-------+
| ``'a'`` | String (converts any Python object using | \(5) |
| | :func:`ascii`). | |
+------------+-----------------------------------------------------+-------+
| ``'%'`` | No argument is converted, results in a ``'%'`` | |
| | character in the result. | |
+------------+-----------------------------------------------------+-------+
For floating-point formats, the result should be correctly rounded to a given
precision ``p`` of digits after the decimal point. The rounding mode matches
that of the :func:`round` builtin.
Notes:
(1)
The alternate form causes a leading octal specifier (``'0o'``) to be
inserted before the first digit.
(2)
The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether
the ``'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 if
no digits follow it.
The precision determines the number of digits after the decimal point and
defaults to 6.
(4)
The alternate form causes the result to always contain a decimal point, and
trailing zeroes are not removed as they would otherwise be.
The precision determines the number of significant digits before and after the
decimal 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 assume
that ``'\0'`` is the end of the string.
.. XXX Examples?
.. versionchanged:: 3.1
``%f`` conversions for numbers whose absolute value is over 1e50 are no
longer replaced by ``%g`` conversions.
.. index::
single: buffer protocol; binary sequence types
.. _binaryseq:
Binary Sequence Types --- :class:`bytes`, :class:`bytearray`, :class:`memoryview`
=================================================================================
.. index::
pair: object; bytes
pair: object; bytearray
pair: object; memoryview
pair: module; array
The core built-in types for manipulating binary data are :class:`bytes` and
:class:`bytearray`. They are supported by :class:`memoryview` which uses
the :ref:`buffer protocol ` to access the memory of other
binary objects without needing to make a copy.
The :mod:`array` module supports efficient storage of basic data types like
32-bit integers and IEEE754 double-precision floating values.
.. _typebytes:
Bytes Objects
-------------
.. index:: pair: object; bytes
Bytes objects are immutable sequences of single bytes. Since many major
binary protocols are based on the ASCII text encoding, bytes objects offer
several methods that are only valid when working with ASCII compatible
data and are closely related to string objects in a variety of other ways.
.. class:: bytes(source=b'')
bytes(source, encoding, errors='strict')
Firstly, the syntax for bytes literals is largely the same as that for string
literals, 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 the
declared source code encoding). Any binary values over 127 must be entered
into bytes literals using the appropriate escape sequence.
As with string literals, bytes literals may also use a ``r`` prefix to disable
processing of escape sequences. See :ref:`strings` for more about the various
forms of bytes literal, including supported escape sequences.
While bytes literals and representations are based on ASCII text, bytes
objects actually behave like immutable sequences of integers, with each
value in the sequence restricted such that ``0 <= x < 256`` (attempts to
violate this restriction will trigger :exc:`ValueError`). This is done
deliberately to emphasise that while many binary formats include ASCII based
elements and can be usefully manipulated with some text-oriented algorithms,
this is not generally the case for arbitrary binary data (blindly applying
text processing algorithms to binary data formats that are not ASCII
compatible will usually lead to data corruption).
In addition to the literal forms, bytes objects can be created in a number of
other 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 :ref:`bytes <func-bytes>` built-in.
Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
numbers 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 :class:`bytes` class method returns a bytes object, decoding the
given string object. The string must contain two hexadecimal digits per
byte, with ASCII whitespace being ignored.
>>> bytes.fromhex('2Ef0 F1f2 ')
b'.\xf0\xf1\xf2'
.. versionchanged:: 3.7
:meth:`bytes.fromhex` now skips all ASCII whitespace in the string,
not just spaces.
.. versionchanged:: 3.14
:meth:`bytes.fromhex` now accepts ASCII :class:`bytes` and
:term:`bytes-like objects ` as input.
A reverse conversion function exists to transform a bytes object into its
hexadecimal representation.
.. method:: hex(*, bytes_per_sep=1)
hex(sep, bytes_per_sep=1)
Return a string object containing two hexadecimal digits for each
byte in the instance.
>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'
If you want to make the hex string easier to read, you can specify a
single 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'
.. versionadded:: 3.5
.. versionchanged:: 3.8
:meth:`bytes.hex` now supports optional *sep* and *bytes_per_sep*
parameters to insert separators between bytes in the hex output.
Since bytes objects are sequences of integers (akin to a tuple), for a bytes
object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be a bytes
object of length 1. (This contrasts with text strings, where both indexing
and 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 can
always convert a bytes object into a list of integers using ``list(b)``.
.. _typebytearray:
Bytearray Objects
-----------------
.. index:: pair: object; bytearray
:class:`bytearray` objects are a mutable counterpart to :class:`bytes`
objects.
.. class:: bytearray(source=b'')
bytearray(source, encoding, errors='strict')
There is no dedicated literal syntax for bytearray objects, instead
they 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 the
:ref:`mutable <typesseq-mutable>` sequence operations in addition to the
common bytes and bytearray operations described in :ref:`bytes-methods`.
Also see the :ref:`bytearray <func-bytearray>` built-in.
Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
numbers 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 :class:`bytearray` class method returns a bytearray object, decoding
the given string object. The string must contain two hexadecimal digits
per byte, with ASCII whitespace being ignored.
>>> bytearray.fromhex('2Ef0 F1f2 ')
bytearray(b'.\xf0\xf1\xf2')
.. versionchanged:: 3.7
:meth:`bytearray.fromhex` now skips all ASCII whitespace in the string,
not just spaces.
.. versionchanged:: 3.14
:meth:`bytearray.fromhex` now accepts ASCII :class:`bytes` and
:term:`bytes-like objects ` as input.
A reverse conversion function exists to transform a bytearray object into its
hexadecimal representation.
.. method:: hex(*, bytes_per_sep=1)
hex(sep, bytes_per_sep=1)
Return a string object containing two hexadecimal digits for each
byte in the instance.
>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'
.. versionadded:: 3.5
.. versionchanged:: 3.8
Similar to :meth:`bytes.hex`, :meth:`bytearray.hex` now supports
optional *sep* and *bytes_per_sep* parameters to insert separators
between bytes in the hex output.
.. method:: resize(size, /)
Resize the :class:`bytearray` to contain *size* bytes. *size* must be
greater than or equal to 0.
If the :class:`bytearray` needs to shrink, bytes beyond *size* are truncated.
If the :class:`bytearray` needs to grow, all new bytes, those beyond *size*,
will be set to null bytes.
This is equivalent to:
>>> def resize(ba, size):
... if len(ba) > size:
... del ba[size:]
... else:
... ba += b'\0' * (size - len(ba))
Examples:
>>> shrink = bytearray(b'abc')
>>> shrink.resize(1)
>>> (shrink, len(shrink))
(bytearray(b'a'), 1)
>>> grow = bytearray(b'abc')
>>> grow.resize(5)
>>> (grow, len(grow))
(bytearray(b'abc\x00\x00'), 5)
.. versionadded:: 3.14
.. method:: take_bytes(n=None, /)
Remove the first *n* bytes from the bytearray and return them as an immutable
:class:`bytes`.
By default (if *n* is ``None``), return all bytes and clear the bytearray.
If *n* is negative, index from the end and take the first :func:`len`
plus *n* bytes. If *n* is out of bounds, raise :exc:`IndexError`.
Taking less than the full length will leave remaining bytes in the
:class:`bytearray`, which requires a copy. If the remaining bytes should be
discarded, use :func:`~bytearray.resize` or :keyword:`del` to truncate
then :func:`~bytearray.take_bytes` without a size.
.. impl-detail::
Taking all bytes is a zero-copy operation.
.. versionadded:: 3.15
See the :ref:`What's New <whatsnew315-bytearray-take-bytes>` entry for
common code patterns which can be optimized with
:meth:`bytearray.take_bytes`.
Since bytearray objects are sequences of integers (akin to a list), for a
bytearray object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be
a bytearray object of length 1. (This contrasts with text strings, where
both 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 into
a list of integers using ``list(b)``.
.. seealso::
For detailed information on thread-safety guarantees for :class:`bytearray`
objects, see :ref:`thread-safety-bytearray`.
.. _bytes-methods:
Bytes and Bytearray Operations
------------------------------
.. index:: pair: bytes; methods
pair: bytearray; methods
Both bytes and bytearray objects support the :ref:`common <typesseq-common>`
sequence operations. They interoperate not just with operands of the same
type, but with any :term:`bytes-like object`. Due to this flexibility, they can be
freely mixed in operations without causing errors. However, the return type
of the result may depend on the order of operands.
.. note::
The methods on bytes and bytearray objects don't accept strings as their
arguments, just as the methods on strings don't accept bytes as their
arguments. For example, you have to write::
a = "abc"
b = a.replace("a", "f")
and::
a = b"abc"
b = a.replace(b"a", b"f")
Some bytes and bytearray operations assume the use of ASCII compatible
binary formats, and hence should be avoided when working with arbitrary
binary data. These restrictions are covered below.
.. note::
Using these ASCII based operations to manipulate binary data that is not
stored in an ASCII based format may lead to data corruption.
The following methods on bytes and bytearray objects can be used with
arbitrary binary data.
.. method:: bytes.count(sub[, start[, end]])
bytearray.count(sub[, start[, end]])
Return the number of non-overlapping occurrences of subsequence *sub* in
the range [*start*, *end*]. Optional arguments *start* and *end* are
interpreted as in slice notation.
The subsequence to search for may be any :term:`bytes-like object` or an
integer in the range 0 to 255.
If *sub* is empty, returns the number of empty slices between characters
which is the length of the bytes object plus one.
.. versionchanged:: 3.3
Also accept an integer in the range 0 to 255 as the subsequence.
.. method:: bytes.removeprefix(prefix, /)
bytearray.removeprefix(prefix, /)
If the binary data starts with the *prefix* string, return
``bytes[len(prefix):]``. Otherwise, return a copy of the original
binary data::
>>> b'TestHook'.removeprefix(b'Test')
b'Hook'
>>> b'BaseTestCase'.removeprefix(b'Test')
b'BaseTestCase'
The *prefix* may be any :term:`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.
.. versionadded:: 3.9
.. method:: bytes.removesuffix(suffix, /)
bytearray.removesuffix(suffix, /)
If the binary data ends with the *suffix* string and that *suffix* is
not empty, return ``bytes[:-len(suffix)]``. Otherwise, return a copy of
the original binary data::
>>> b'MiscTests'.removesuffix(b'Tests')
b'Misc'
>>> b'TmpDirMixin'.removesuffix(b'Tests')
b'TmpDirMixin'
The *suffix* may be any :term:`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.
.. versionadded:: 3.9
.. method:: bytes.decode(encoding="utf-8", errors="strict")
bytearray.decode(encoding="utf-8", errors="strict")
Return the bytes decoded to a :class:`str`.
*encoding* defaults to ``'utf-8'``;
see :ref:`standard-encodings` for possible values.
*errors* controls how decoding errors are handled.
If ``'strict'`` (the default), a :exc:`UnicodeError` exception is raised.
Other possible values are ``'ignore'``, ``'replace'``,
and any other name registered via :func:`codecs.register_error`.
See :ref:`error-handlers` for details.
For performance reasons, the value of *errors* is not checked for validity
unless a decoding error actually occurs,
:ref:`devmode` is enabled or a :ref:`debug build <debug-build>` is used.
.. note::
Passing the *encoding* argument to :class:`str` allows decoding any
:term:`bytes-like object` directly, without needing to make a temporary
:class:`!bytes` or :class:`!bytearray` object.
.. versionchanged:: 3.1
Added support for keyword arguments.
.. versionchanged:: 3.9
The value of the *errors* argument is now checked in :ref:`devmode` and
in :ref:`debug mode <debug-build>`.
.. method:: 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 to
look for. With optional *start*, test beginning at that position. With
optional *end*, stop comparing at that position.
The suffix(es) to search for may be any :term:`bytes-like object`.
.. method:: 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]``. Optional
arguments *start* and *end* are interpreted as in slice notation. Return
``-1`` if *sub* is not found.
The subsequence to search for may be any :term:`bytes-like object` or an
integer in the range 0 to 255.
.. note::
The :meth:`~bytes.find` method should be used only if you need to know the
position of *sub*. To check if *sub* is a substring or not, use the
:keyword:`in` operator::
>>> b'Py' in b'Python'
True
.. versionchanged:: 3.3
Also accept an integer in the range 0 to 255 as the subsequence.
.. method:: bytes.index(sub[, start[, end]])
bytearray.index(sub[, start[, end]])
Like :meth:`~bytes.find`, but raise :exc:`ValueError` when the
subsequence is not found.
The subsequence to search for may be any :term:`bytes-like object` or an
integer in the range 0 to 255.
.. versionchanged:: 3.3
Also accept an integer in the range 0 to 255 as the subsequence.
.. method:: bytes.join(iterable, /)
bytearray.join(iterable, /)
Return a bytes or bytearray object which is the concatenation of the
binary data sequences in *iterable*. A :exc:`TypeError` will be raised
if there are any values in *iterable* that are not :term:`bytes-like
objects `, including :class:`str` objects. The
separator between elements is the contents of the bytes or
bytearray object providing this method.
.. staticmethod:: bytes.maketrans(from, to, /)
bytearray.maketrans(from, to, /)
This static method returns a translation table usable for
:meth:`bytes.translate` that will map each character in *from* into the
character at the same position in *to*; *from* and *to* must both be
:term:`bytes-like objects ` and have the same length.
.. versionadded:: 3.1
.. method:: bytes.partition(sep, /)
bytearray.partition(sep, /)
Split the sequence at the first occurrence of *sep*, and return a 3-tuple
containing the part before the separator, the separator itself or its
bytearray copy, and the part after the separator.
If the separator is not found, return a 3-tuple
containing a copy of the original sequence, followed by two empty bytes or
bytearray objects.
The separator to search for may be any :term:`bytes-like object`.
.. method:: bytes.replace(old, new, /, count=-1)
bytearray.replace(old, new, /, count=-1)
Return a copy of the sequence with all occurrences of subsequence *old*
replaced by *new*. If *count* is given, only the first *count* occurrences
are replaced. If *count* is not specified or ``-1``, then all occurrences
are replaced.
The subsequence to search for and its replacement may be any
:term:`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.
.. versionchanged:: 3.15
*count* is now supported as a keyword argument.
.. method:: bytes.rfind(sub[, start[, end]])
bytearray.rfind(sub[, start[, end]])
Return the highest index in the sequence where the subsequence *sub* is
found, such that *sub* is contained within ``s[start:end]``. Optional
arguments *start* and *end* are interpreted as in slice notation. Return
``-1`` on failure.
The subsequence to search for may be any :term:`bytes-like object` or an
integer in the range 0 to 255.
.. versionchanged:: 3.3
Also accept an integer in the range 0 to 255 as the subsequence.
.. method:: bytes.rindex(sub[, start[, end]])
bytearray.rindex(sub[, start[, end]])
Like :meth:`~bytes.rfind` but raises :exc:`ValueError` when the
subsequence *sub* is not found.
The subsequence to search for may be any :term:`bytes-like object` or an
integer in the range 0 to 255.
.. versionchanged:: 3.3
Also accept an integer in the range 0 to 255 as the subsequence.
.. method:: bytes.rpartition(sep, /)
bytearray.rpartition(sep, /)
Split the sequence at the last occurrence of *sep*, and return a 3-tuple
containing the part before the separator, the separator itself or its
bytearray copy, and the part after the separator.
If the separator is not found, return a 3-tuple
containing two empty bytes or bytearray objects, followed by a copy of the
original sequence.
The separator to search for may be any :term:`bytes-like object`.
.. method:: 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 to
look for. With optional *start*, test beginning at that position. With
optional *end*, stop comparing at that position.
The prefix(es) to search for may be any :term:`bytes-like object`.
.. method:: bytes.translate(table, /, delete=b'')
bytearray.translate(table, /, delete=b'')
Return a copy of the bytes or bytearray object where all bytes occurring in
the optional argument *delete* are removed, and the remaining bytes have
been mapped through the given translation table, which must be a bytes
object of length 256.
You can use the :func:`bytes.maketrans` method to create a translation
table.
Set the *table* argument to ``None`` for translations that only delete
characters::
>>> b'read this short text'.translate(None, b'aeiou')
b'rd ths shrt txt'
.. versionchanged:: 3.6
*delete* is now supported as a keyword argument.
The following methods on bytes and bytearray objects have default behaviours
that assume the use of ASCII compatible binary formats, but can still be used
with arbitrary binary data by passing appropriate arguments. Note that all of
the bytearray methods in this section do *not* operate in place, and instead
produce new objects.
.. method:: bytes.center(width, fillbyte=b' ', /)
bytearray.center(width, fillbyte=b' ', /)
Return a copy of the object centered in a sequence of length *width*.
Padding is done using the specified *fillbyte* (default is an ASCII
space). For :class:`bytes` objects, the original sequence is returned if
*width* 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.
.. method:: bytes.ljust(width, fillbyte=b' ', /)
bytearray.ljust(width, fillbyte=b' ', /)
Return a copy of the object left justified in a sequence of length *width*.
Padding is done using the specified *fillbyte* (default is an ASCII
space). For :class:`bytes` objects, the original sequence is returned if
*width* 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.
.. method:: bytes.lstrip(bytes=None, /)
bytearray.lstrip(bytes=None, /)
Return a copy of the sequence with specified leading bytes removed. The
*bytes* argument is a binary sequence specifying the set of byte values to
be removed. If omitted or ``None``, the *bytes* argument defaults
to removing :meth:`ASCII whitespace `.
The *bytes* 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 any
:term:`bytes-like object`. See :meth:`~bytes.removeprefix` for a method
that will remove a single prefix string rather than all of a set of
characters. 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.
.. method:: bytes.rjust(width, fillbyte=b' ', /)
bytearray.rjust(width, fillbyte=b' ', /)
Return a copy of the object right justified in a sequence of length *width*.
Padding is done using the specified *fillbyte* (default is an ASCII
space). For :class:`bytes` objects, the original sequence is returned if
*width* 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.
.. method:: bytes.rsplit(sep=None, maxsplit=-1)
bytearray.rsplit(sep=None, maxsplit=-1)
Split the binary sequence into subsequences of the same type, using *sep*
as the delimiter string. If *maxsplit* is given, at most *maxsplit* splits
are done, the *rightmost* ones. If *sep* is not specified or ``None``,
any subsequence consisting solely of
:meth:`ASCII whitespace ` is a separator.
Except for splitting from the right, :meth:`rsplit` behaves like
:meth:`split` which is described in detail below.
.. method:: bytes.rstrip(bytes=None, /)
bytearray.rstrip(bytes=None, /)
Return a copy of the sequence with specified trailing bytes removed. The
*bytes* argument is a binary sequence specifying the set of byte values to
be removed. If omitted or ``None``, the *bytes* argument defaults to
removing :meth:`ASCII whitespace `.
The *bytes* 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 any
:term:`bytes-like object`. See :meth:`~bytes.removesuffix` for a method
that will remove a single suffix string rather than all of a set of
characters. 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.
.. method:: bytes.split(sep=None, maxsplit=-1)
bytearray.split(sep=None, maxsplit=-1)
Split the binary sequence into subsequences of the same type, using *sep*
as the delimiter string. If *maxsplit* is given and non-negative, at most
*maxsplit* splits are done (thus, the list will have at most ``maxsplit+1``
elements). If *maxsplit* is not specified or is ``-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 are
deemed to delimit empty subsequences (for example, ``b'1,,2'.split(b',')``
returns ``[b'1', b'', b'2']``). The *sep* argument may consist of a
multibyte sequence as a single delimiter. Splitting an empty sequence with
a specified separator returns ``[b'']`` or ``[bytearray(b'')]`` depending
on the type of object being split. The *sep* argument may be any
:term:`bytes-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 algorithm
is applied: runs of consecutive :meth:`ASCII whitespace `
are regarded as a single
separator, and the result will contain no empty strings at the start or
end if the sequence has leading or trailing whitespace. Consequently,
splitting an empty sequence or a sequence consisting solely of ASCII
whitespace 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']
.. method:: bytes.strip(bytes=None, /)
bytearray.strip(bytes=None, /)
Return a copy of the sequence with specified leading and trailing bytes
removed. The *bytes* argument is a binary sequence specifying the set of
byte values to be removed. If omitted or ``None``, the *bytes*
argument defaults to removing :meth:`ASCII whitespace `.
The *bytes* argument is
not a prefix or suffix; rather, all combinations of its values are
stripped::
>>> b' spacious '.strip()
b'spacious'
>>> b'www.example.com'.strip(b'cmowz.')
b'example'
The binary sequence of byte values to remove may be any
:term:`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.
The following methods on bytes and bytearray objects assume the use of ASCII
compatible binary formats and should not be applied to arbitrary binary data.
Note that all of the bytearray methods in this section do *not* operate in
place, and instead produce new objects.
.. method:: bytes.capitalize()
bytearray.capitalize()
Return a copy of the sequence with each byte interpreted as an ASCII
character, and the first byte capitalized and the rest lowercased.
Non-ASCII byte values are passed through unchanged.
.. note::
The bytearray version of this method does *not* operate in place - it
always produces a new object, even if no changes were made.
.. method:: bytes.expandtabs(tabsize=8)
bytearray.expandtabs(tabsize=8)
Return a copy of the sequence where all ASCII tab characters are replaced
by one or more ASCII spaces, depending on the current column and the given
tab size. Tab positions occur every *tabsize* bytes (default is 8,
giving tab positions at columns 0, 8, 16 and so on). To expand the
sequence, the current column is set to zero and the sequence is examined
byte by byte. If the byte is an ASCII tab character (``b'\t'``), one or
more space characters are inserted in the result until the current column
is equal to the next tab position. (The tab character itself is not
copied.) If the current byte is an ASCII newline (``b'\n'``) or
carriage return (``b'\r'``), it is copied and the current column is reset
to zero. Any other byte value is copied unchanged and the current column
is incremented by one regardless of how the byte value is represented when
printed::
>>> b'01\t012\t0123\t01234'.expandtabs()
b'01 012 0123 01234'
>>> b'01\t012\t0123\t01234'.expandtabs(4)
b'01 012 0123 01234'
.. note::
The bytearray version of this method does *not* operate in place - it
always produces a new object, even if no changes were made.
.. method:: bytes.isalnum()
bytearray.isalnum()
Return ``True`` if all bytes in the sequence are alphabetical ASCII characters
or ASCII decimal digits and the sequence is not empty, ``False`` otherwise.
Alphabetic ASCII characters are those byte values in the sequence
``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``. ASCII decimal
digits are those byte values in the sequence ``b'0123456789'``.
For example::
>>> b'ABCabc1'.isalnum()
True
>>> b'ABC abc1'.isalnum()
False
.. method:: bytes.isalpha()
bytearray.isalpha()
Return ``True`` if all bytes in the sequence are alphabetic ASCII characters
and the sequence is not empty, ``False`` otherwise. Alphabetic ASCII
characters are those byte values in the sequence
``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``.
For example::
>>> b'ABCabc'.isalpha()
True
>>> b'ABCabc1'.isalpha()
False
.. method:: bytes.isascii()
bytearray.isascii()
Return ``True`` if the sequence is empty or all bytes in the sequence are ASCII,
``False`` otherwise.
ASCII bytes are in the range 0-0x7F.
.. versionadded:: 3.7
.. method:: bytes.isdigit()
bytearray.isdigit()
Return ``True`` if all bytes in the sequence are ASCII decimal digits
and the sequence is not empty, ``False`` otherwise. ASCII decimal digits are
those byte values in the sequence ``b'0123456789'``.
For example::
>>> b'1234'.isdigit()
True
>>> b'1.23'.isdigit()
False
.. method:: bytes.islower()
bytearray.islower()
Return ``True`` if there is at least one lowercase ASCII character
in the sequence and no uppercase ASCII characters, ``False`` otherwise.
For example::
>>> b'hello world'.islower()
True
>>> b'Hello world'.islower()
False
Lowercase ASCII characters are those byte values in the sequence
``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters
are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.
.. method:: bytes.isspace()
bytearray.isspace()
Return ``True`` if all bytes in the sequence are ASCII whitespace and the
sequence is not empty, ``False`` otherwise. ASCII whitespace characters are
those byte values in the sequence ``b' \t\n\r\x0b\f'`` (space, tab, newline,
carriage return, vertical tab, form feed).
.. method:: bytes.istitle()
bytearray.istitle()
Return ``True`` if the sequence is ASCII titlecase and the sequence is not
empty, ``False`` otherwise. See :meth:`bytes.title` for more details on the
definition of "titlecase".
For example::
>>> b'Hello World'.istitle()
True
>>> b'Hello world'.istitle()
False
.. method:: bytes.isupper()
bytearray.isupper()
Return ``True`` if there is at least one uppercase alphabetic ASCII character
in the sequence and no lowercase ASCII characters, ``False`` otherwise.
For example::
>>> b'HELLO WORLD'.isupper()
True
>>> b'Hello world'.isupper()
False
Lowercase ASCII characters are those byte values in the sequence
``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters
are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.
.. method:: bytes.lower()
bytearray.lower()
Return a copy of the sequence with all the uppercase ASCII characters
converted to their corresponding lowercase counterpart.
For example::
>>> b'Hello World'.lower()
b'hello world'
Lowercase ASCII characters are those byte values in the sequence
``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters
are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.
.. note::
The bytearray version of this method does *not* operate in place - it
always produces a new object, even if no changes were made.
.. index::
single: universal newlines; bytes.splitlines method
single: universal newlines; bytearray.splitlines method
.. method:: bytes.splitlines(keepends=False)
bytearray.splitlines(keepends=False)
Return a list of the lines in the binary sequence, breaking at ASCII
line boundaries. This method uses the :term:`universal newlines` approach
to splitting lines. Line breaks are not included in the resulting list
unless *keepends* is given and true.
For example::
>>> b'ab c\n\nde fg\rkl\r\n'.splitlines()
[b'ab c', b'', b'de fg', b'kl']
>>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
[b'ab c\n', b'\n', b'de fg\r', b'kl\r\n']
Unlike :meth:`~bytes.split` when a delimiter string *sep* is given, this
method returns an empty list for the empty string, and a terminal line
break does not result in an extra line::
>>> b"".split(b'\n'), b"Two lines\n".split(b'\n')
([b''], [b'Two lines', b''])
>>> b"".splitlines(), b"One line\n".splitlines()
([], [b'One line'])
.. method:: bytes.swapcase()
bytearray.swapcase()
Return a copy of the sequence with all the lowercase ASCII characters
converted to their corresponding uppercase counterpart and vice-versa.
For example::
>>> b'Hello World'.swapcase()
b'hELLO wORLD'
Lowercase ASCII characters are those byte values in the sequence
``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters
are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.
Unlike :func:`str.swapcase`, it is always the case that
``bin.swapcase().swapcase() == bin`` for the binary versions. Case
conversions are symmetrical in ASCII, even though that is not generally
true for arbitrary Unicode code points.
.. note::
The bytearray version of this method does *not* operate in place - it
always produces a new object, even if no changes were made.
.. method:: bytes.title()
bytearray.title()
Return a titlecased version of the binary sequence where words start with
an uppercase ASCII character and the remaining characters are lowercase.
Uncased byte values are left unmodified.
For example::
>>> b'Hello world'.title()
b'Hello World'
Lowercase ASCII characters are those byte values in the sequence
``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters
are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.
All other byte values are uncased.
The algorithm uses a simple language-independent definition of a word as
groups of consecutive letters. The definition works in many contexts but
it means that apostrophes in contractions and possessives form word
boundaries, which may not be the desired result::
>>> b"they're bill's friends from the UK".title()
b"They'Re Bill'S Friends From The Uk"
A workaround for apostrophes can be constructed using regular expressions::
>>> import re
>>> def titlecase(s):
... return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?",
... lambda mo: mo.group(0)[0:1].upper() +
... mo.group(0)[1:].lower(),
... s)
...
>>> titlecase(b"they're bill's friends.")
b"They're Bill's Friends."
.. note::
The bytearray version of this method does *not* operate in place - it
always produces a new object, even if no changes were made.
.. method:: bytes.upper()
bytearray.upper()
Return a copy of the sequence with all the lowercase ASCII characters
converted to their corresponding uppercase counterpart.
For example::
>>> b'Hello World'.upper()
b'HELLO WORLD'
Lowercase ASCII characters are those byte values in the sequence
``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters
are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.
.. note::
The bytearray version of this method does *not* operate in place - it
always produces a new object, even if no changes were made.
.. method:: bytes.zfill(width, /)
bytearray.zfill(width, /)
Return a copy of the sequence left filled with ASCII ``b'0'`` digits to
make a sequence of length *width*. A leading sign prefix (``b'+'``/
``b'-'``) is handled by inserting the padding *after* the sign character
rather than before. For :class:`bytes` objects, the original sequence is
returned if *width* is less than or equal to ``len(seq)``.
For example::
>>> b"42".zfill(5)
b'00042'
>>> b"-42".zfill(5)
b'-0042'
.. 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-formatting:
``printf``-style Bytes Formatting
----------------------------------
.. index::
single: formatting; bytes (%)
single: formatting; bytearray (%)
single: interpolation; bytes (%)
single: interpolation; bytearray (%)
single: bytes; formatting
single: bytearray; formatting
single: bytes; interpolation
single: bytearray; interpolation
single: printf-style formatting
single: sprintf-style formatting
single: % (percent); printf-style formatting
.. note::
The formatting operations described here exhibit a variety of quirks that
lead to a number of common errors (such as failing to display tuples and
dictionaries correctly). If the value being printed may be a tuple or
dictionary, wrap it in a tuple.
Bytes objects (``bytes``/``bytearray``) have one unique built-in operation:
the ``%`` operator (modulo).
This is also known as the bytes *formatting* or *interpolation* operator.
Given ``format % values`` (where *format* is a bytes object), ``%`` conversion
specifications in *format* are replaced with zero or more elements of *values*.
The effect is similar to using the :c:func:`sprintf` function in the C language.
If *format* requires a single argument, *values* may be a single non-tuple
object. [5]_ Otherwise, *values* must be a tuple with exactly the number of
items specified by the format bytes object, or a single mapping object (for
example, a dictionary).
.. index::
single: () (parentheses); in printf-style formatting
single: * (asterisk); in printf-style formatting
single: . (dot); in printf-style formatting
A conversion specifier contains two or more characters and has the following
components, which must occur in this order:
#. The ``'%'`` character, which marks the start of the specifier.
#. Mapping key (optional), consisting of a parenthesised sequence of characters
(for example, ``(somename)``).
#. Conversion flags (optional), which affect the result of some conversion
types.
#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the
actual width is read from the next element of the tuple in *values*, and the
object to convert comes after the minimum field width and optional precision.
#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If
specified as ``'*'`` (an asterisk), the actual precision is read from the next
element of the tuple in *values*, and the value to convert comes after the
precision.
#. Length modifier (optional).
#. Conversion type.
When the right argument is a dictionary (or other mapping type), then the
formats in the bytes object *must* include a parenthesised mapping key into that
dictionary inserted immediately after the ``'%'`` character. The mapping key
selects the value to be formatted from the mapping. For example:
>>> print(b'%(language)s has %(number)03d quote types.' %
... {b'language': b"Python", b"number": 2})
b'Python has 002 quote types.'
In this case no ``*`` specifiers may occur in a format (since they require a
sequential parameter list).
The conversion flag characters are:
.. index::
single: # (hash); in printf-style formatting
single: - (minus); in printf-style formatting
single: + (plus); in printf-style formatting
single: space; in printf-style formatting
+---------+---------------------------------------------------------------------+
| Flag | Meaning |
+=========+=====================================================================+
| ``'#'`` | The value conversion will use the "alternate form" (where defined |
| | below). |
+---------+---------------------------------------------------------------------+
| ``'0'`` | The conversion will be zero padded for numeric values. |
+---------+---------------------------------------------------------------------+
| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` |
| | conversion if both are given). |
+---------+---------------------------------------------------------------------+
| ``' '`` | (a space) A blank should be left before a positive number (or empty |
| | string) produced by a signed conversion. |
+---------+---------------------------------------------------------------------+
| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion |
| | (overrides a "space" flag). |
+---------+---------------------------------------------------------------------+
A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it
is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``.
The conversion types are:
+------------+-----------------------------------------------------+-------+
| Conversion | Meaning | Notes |
+============+=====================================================+=======+
| ``'d'`` | Signed integer decimal. | |
+------------+-----------------------------------------------------+-------+
| ``'i'`` | Signed integer decimal. | |
+------------+-----------------------------------------------------+-------+
| ``'o'`` | Signed octal value. | \(1) |
+------------+-----------------------------------------------------+-------+
| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(8) |
+------------+-----------------------------------------------------+-------+
| ``'x'`` | Signed hexadecimal (lowercase). | \(2) |
+------------+-----------------------------------------------------+-------+
| ``'X'`` | Signed hexadecimal (uppercase). | \(2) |
+------------+-----------------------------------------------------+-------+
| ``'e'`` | Floating-point exponential format (lowercase). | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'E'`` | Floating-point exponential format (uppercase). | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'f'`` | Floating-point decimal format. | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'F'`` | Floating-point decimal format. | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'g'`` | Floating-point format. Uses lowercase exponential | \(4) |
| | format if exponent is less than -4 or not less than | |
| | precision, decimal format otherwise. | |
+------------+-----------------------------------------------------+-------+
| ``'G'`` | Floating-point format. Uses uppercase exponential | \(4) |
| | format if exponent is less than -4 or not less than | |
| | precision, decimal format otherwise. | |
+------------+-----------------------------------------------------+-------+
| ``'c'`` | Single byte (accepts integer or single | |
| | byte objects). | |
+------------+-----------------------------------------------------+-------+
| ``'b'`` | Bytes (any object that follows the | \(5) |
| | :ref:`buffer protocol ` or has | |
| | :meth:`~object.__bytes__`). | |
+------------+-----------------------------------------------------+-------+
| ``'s'`` | ``'s'`` is an alias for ``'b'`` and should only | \(6) |
| | be used for Python2/3 code bases. | |
+------------+-----------------------------------------------------+-------+
| ``'a'`` | Bytes (converts any Python object using | \(5) |
| | ``repr(obj).encode('ascii', 'backslashreplace')``). | |
+------------+-----------------------------------------------------+-------+
| ``'r'`` | ``'r'`` is an alias for ``'a'`` and should only | \(7) |
| | be used for Python2/3 code bases. | |
+------------+-----------------------------------------------------+-------+
| ``'%'`` | No argument is converted, results in a ``'%'`` | |
| | character in the result. | |
+------------+-----------------------------------------------------+-------+
Notes:
(1)
The alternate form causes a leading octal specifier (``'0o'``) to be
inserted before the first digit.
(2)
The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether
the ``'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 if
no digits follow it.
The precision determines the number of digits after the decimal point and
defaults to 6.
(4)
The alternate form causes the result to always contain a decimal point, and
trailing zeroes are not removed as they would otherwise be.
The precision determines the number of significant digits before and after the
decimal point and defaults to 6.
(5)
If precision is ``N``, the output is truncated to ``N`` characters.
(6)
``b'%s'`` is deprecated, but will not be removed during the 3.x series.
(7)
``b'%r'`` is deprecated, but will not be removed during the 3.x series.
(8)
See :pep:`237`.
.. note::
The bytearray version of this method does *not* operate in place - it
always produces a new object, even if no changes were made.
.. seealso::
:pep:`461` - Adding % formatting to bytes and bytearray
.. versionadded:: 3.5
.. _typememoryview:
Memory Views
------------
:class:`memoryview` objects allow Python code to access the internal data
of an object that supports the :ref:`buffer protocol ` without
copying.
.. class:: memoryview(object)
Create a :class:`memoryview` that references *object*. *object* must
support the buffer protocol. Built-in objects that support the buffer
protocol include :class:`bytes` and :class:`bytearray`.
A :class:`memoryview` has the notion of an *element*, which is the
atomic memory unit handled by the originating *object*. For many simple
types such as :class:`bytes` and :class:`bytearray`, an element is a single
byte, but other types such as :class:`array.array` may have bigger elements.
:class:`!memoryview`\s are :ref:`generic <generics>` over the type of their
underlying data.
``len(view)`` is equal to the length of :meth:`~memoryview.tolist`, which
is the nested list representation of the view. If ``view.ndim == 1``,
this is equal to the number of elements in the view.
.. versionchanged:: 3.12
If ``view.ndim == 0``, ``len(view)`` now raises :exc:`TypeError` instead of returning 1.
The :class:`~memoryview.itemsize` attribute will give you the number of
bytes in a single element.
A :class:`memoryview` supports slicing and indexing to expose its data.
One-dimensional slicing will result in a subview::
>>> v = memoryview(b'abcefg')
>>> v[1]
98
>>> v[-1]
103
>>> v[1:4]
<memory at 0x7f3ddc9f4350>
>>> bytes(v[1:4])
b'bce'
If :class:`~memoryview.format` is one of the native format specifiers
from the :mod:`struct` module, indexing with an integer or a tuple of
integers is also supported and returns a single *element* with
the correct type. One-dimensional memoryviews can be indexed
with an integer or a one-integer tuple. Multi-dimensional memoryviews
can be indexed with tuples of exactly *ndim* integers where *ndim* is
the number of dimensions. Zero-dimensional memoryviews can be indexed
with the empty tuple.
Here is an example with a non-byte format::
>>> import array
>>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444])
>>> m = memoryview(a)
>>> m[0]
-11111111
>>> m[-1]
44444444
>>> m[::2].tolist()
[-11111111, -33333333]
If the underlying object is writable, the memoryview supports
one-dimensional slice assignment. Resizing is not allowed::
>>> data = bytearray(b'abcefg')
>>> v = memoryview(data)
>>> v.readonly
False
>>> v[0] = ord(b'z')
>>> data
bytearray(b'zbcefg')
>>> v[1:4] = b'123'
>>> data
bytearray(b'z123fg')
>>> v[2:3] = b'spam'
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: memoryview assignment: lvalue and rvalue have different structures
>>> v[2:6] = b'spam'
>>> data
bytearray(b'z1spam')
One-dimensional memoryviews of :term:`hashable` (read-only) types with formats
'B', 'b' or 'c' are also hashable. The hash is defined as
``hash(m) == hash(m.tobytes())``::
>>> v = memoryview(b'abcefg')
>>> hash(v) == hash(b'abcefg')
True
>>> hash(v[2:4]) == hash(b'ce')
True
>>> hash(v[::-2]) == hash(b'abcefg'[::-2])
True
.. versionchanged:: 3.3
One-dimensional memoryviews can now be sliced.
One-dimensional memoryviews with formats 'B', 'b' or 'c' are now :term:`hashable`.
.. versionchanged:: 3.4
memoryview is now registered automatically with
:class:`collections.abc.Sequence`
.. versionchanged:: 3.5
memoryviews can now be indexed with a tuple of integers.
.. versionchanged:: 3.14
memoryview is now a :term:`generic type`.
:class:`memoryview` has several methods:
.. method:: __eq__(exporter)
A memoryview and a :pep:`3118` exporter are equal if their shapes are
equivalent and if all corresponding values are equal when the operands'
respective format codes are interpreted using :mod:`struct` syntax.
For the subset of :mod:`struct` format strings currently supported by
:meth:`tolist`, ``v`` and ``w`` are equal if ``v.tolist() == w.tolist()``::
>>> import array
>>> a = array.array('I', [1, 2, 3, 4, 5])
>>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0])
>>> c = array.array('b', [5, 3, 1])
>>> x = memoryview(a)
>>> y = memoryview(b)
>>> x == a == y == b
True
>>> x.tolist() == a.tolist() == y.tolist() == b.tolist()
True
>>> z = y[::-2]
>>> z == c
True
>>> z.tolist() == c.tolist()
True
If either format string is not supported by the :mod:`struct` module,
then the objects will always compare as unequal (even if the format
strings and buffer contents are identical)::
>>> from ctypes import BigEndianStructure, c_long
>>> class BEPoint(BigEndianStructure):
... _fields_ = [("x", c_long), ("y", c_long)]
...
>>> point = BEPoint(100, 200)
>>> a = memoryview(point)
>>> b = memoryview(point)
>>> a == point
False
>>> a == b
False
Note that, as with floating-point numbers, ``v is w`` does *not* imply
``v == w`` for memoryview objects.
.. versionchanged:: 3.3
Previous versions compared the raw memory disregarding the item format
and the logical array structure.
.. method:: tobytes(order='C')
Return the data in the buffer as a bytestring. This is equivalent to
calling the :class:`bytes` constructor on the memoryview. ::
>>> m = memoryview(b"abc")
>>> m.tobytes()
b'abc'
>>> bytes(m)
b'abc'
For non-contiguous arrays the result is equal to the flattened list
representation with all elements converted to bytes. :meth:`tobytes`
supports all format strings, including those that are not in
:mod:`struct` module syntax.
.. versionadded:: 3.8
*order* can be {'C', 'F', 'A'}. When *order* is 'C' or 'F', the data
of the original array is converted to C or Fortran order. For contiguous
views, 'A' returns an exact copy of the physical memory. In particular,
in-memory Fortran order is preserved. For non-contiguous views, the
data is converted to C first. *order=None* is the same as *order='C'*.
.. method:: hex(*, bytes_per_sep=1)
hex(sep, bytes_per_sep=1)
Return a string object containing two hexadecimal digits for each
byte in the buffer. ::
>>> m = memoryview(b"abc")
>>> m.hex()
'616263'
.. versionadded:: 3.5
.. versionchanged:: 3.8
Similar to :meth:`bytes.hex`, :meth:`memoryview.hex` now supports
optional *sep* and *bytes_per_sep* parameters to insert separators
between bytes in the hex output.
.. method:: tolist()
Return the data in the buffer as a list of elements. ::
>>> memoryview(b'abc').tolist()
[97, 98, 99]
>>> import array
>>> a = array.array('d', [1.1, 2.2, 3.3])
>>> m = memoryview(a)
>>> m.tolist()
[1.1, 2.2, 3.3]
.. versionchanged:: 3.3
:meth:`tolist` now supports all single character native formats in
:mod:`struct` module syntax as well as multi-dimensional
representations.
.. method:: toreadonly()
Return a readonly version of the memoryview object. The original
memoryview object is unchanged. ::
>>> m = memoryview(bytearray(b'abc'))
>>> mm = m.toreadonly()
>>> mm.tolist()
[97, 98, 99]
>>> mm[0] = 42
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> m[0] = 43
>>> mm.tolist()
[43, 98, 99]
.. versionadded:: 3.8
.. method:: release()
Release the underlying buffer exposed by the memoryview object. Many
objects take special actions when a view is held on them (for example,
a :class:`bytearray` would temporarily forbid resizing); therefore,
calling release() is handy to remove these restrictions (and free any
dangling resources) as soon as possible.
After this method has been called, any further operation on the view
raises a :class:`ValueError` (except :meth:`release` itself which can
be called multiple times)::
>>> m = memoryview(b'abc')
>>> m.release()
>>> m[0]
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object
The context management protocol can be used for a similar effect,
using the ``with`` statement::
>>> with memoryview(b'abc') as m:
... m[0]
...
97
>>> m[0]
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object
.. versionadded:: 3.2
.. method:: cast(format, /)
cast(format, shape, /, *, order='C')
Cast a memoryview to a new format or shape. *shape* defaults to
``[byte_length//new_itemsize]``, which means that the result view
will be one-dimensional. The return value is a new memoryview, but
the buffer itself is not copied. Supported casts are
1D -> C-:term:`contiguous`, C-contiguous -> 1D, and
F-contiguous -> 1D.
With a multidimensional *shape*, *order* selects the memory layout of
the result: ``'C'`` for C-contiguous (row-major, the default) or ``'F'``
for Fortran-contiguous (column-major). The buffer is still not copied,
so ``order='F'`` gives a zero-copy view over a buffer holding
column-major data.
The destination format is restricted to a single element native format in
:mod:`struct` syntax. One of the formats must be a byte format
('B', 'b' or 'c'). The byte length of the result must be the same
as the original length.
Note that all byte lengths may depend on the operating system.
Cast 1D/long to 1D/unsigned bytes::
>>> import array
>>> a = array.array('l', [1,2,3])
>>> x = memoryview(a)
>>> x.format
'l'
>>> x.itemsize
8
>>> len(x)
3
>>> x.nbytes
24
>>> y = x.cast('B')
>>> y.format
'B'
>>> y.itemsize
1
>>> len(y)
24
>>> y.nbytes
24
Cast 1D/unsigned bytes to 1D/char::
>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
...
TypeError: memoryview: invalid type for format 'B'
>>> y = x.cast('c')
>>> y[0] = b'a'
>>> b
bytearray(b'ayz')
Cast 1D/bytes to 3D/ints to 1D/signed char::
>>> import struct
>>> buf = struct.pack("i"*12, *list(range(12)))
>>> x = memoryview(buf)
>>> y = x.cast('i', shape=[2,2,3])
>>> y.tolist()
[[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
>>> y.format
'i'
>>> y.itemsize
4
>>> len(y)
2
>>> y.nbytes
48
>>> z = y.cast('b')
>>> z.format
'b'
>>> z.itemsize
1
>>> len(z)
48
>>> z.nbytes
48
Cast 1D/unsigned long to 2D/unsigned long::
>>> buf = struct.pack("L"*6, *list(range(6)))
>>> x = memoryview(buf)
>>> y = x.cast('L', shape=[2,3])
>>> len(y)
2
>>> y.nbytes
48
>>> y.tolist()
[[0, 1, 2], [3, 4, 5]]
.. versionadded:: 3.3
.. versionchanged:: 3.5
The source format is no longer restricted when casting to a byte view.
.. versionchanged:: 3.16
Casting a multi-dimensional F-contiguous view to a one-dimensional
view is now supported.
.. method:: count(value, /)
Count the number of occurrences of *value*.
.. versionadded:: 3.14
.. method:: index(value, start=0, stop=sys.maxsize, /)
Return the index of the first occurrence of *value* (at or after
index *start* and before index *stop*).
Raises a :exc:`ValueError` if *value* cannot be found.
.. versionadded:: 3.14
There are also several readonly attributes available:
.. attribute:: obj
The underlying object of the memoryview::
>>> b = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True
.. versionadded:: 3.3
.. attribute:: nbytes
``nbytes == product(shape) * itemsize == len(m.tobytes())``. This is
the amount of space in bytes that the array would use in a contiguous
representation. It is not necessarily equal to ``len(m)``::
>>> import array
>>> a = array.array('i', [1,2,3,4,5])
>>> m = memoryview(a)
>>> len(m)
5
>>> m.nbytes
20
>>> y = m[::2]
>>> len(y)
3
>>> y.nbytes
12
>>> len(y.tobytes())
12
Multi-dimensional arrays::
>>> import struct
>>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)])
>>> x = memoryview(buf)
>>> y = x.cast('d', shape=[3,4])
>>> y.tolist()
[[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]]
>>> len(y)
3
>>> y.nbytes
96
Interpret a flat buffer as a Fortran-contiguous (column-major) array::
>>> buf = bytes(range(6))
>>> y = memoryview(buf).cast('B', shape=[3, 2], order='F')
>>> y.f_contiguous
True
>>> y.tolist()
[[0, 3], [1, 4], [2, 5]]
.. versionadded:: 3.3
.. versionchanged:: 3.16
Added the *order* parameter.
.. attribute:: readonly
A bool indicating whether the memory is read only.
.. attribute:: format
A string containing the format (in :mod:`struct` module style) for each
element in the view. A memoryview can be created from exporters with
arbitrary format strings, but some methods (e.g. :meth:`tolist`) are
restricted to native single element formats.
.. versionchanged:: 3.3
format ``'B'`` is now handled according to the struct module syntax.
This means that ``memoryview(b'abc')[0] == b'abc'[0] == 97``.
.. attribute:: itemsize
The size in bytes of each element of the memoryview::
>>> import array, struct
>>> m = memoryview(array.array('H', [32000, 32001, 32002]))
>>> m.itemsize
2
>>> m[0]
32000
>>> struct.calcsize('H') == m.itemsize
True
.. attribute:: ndim
An integer indicating how many dimensions of a multi-dimensional array the
memory represents.
.. attribute:: shape
A tuple of integers the length of :attr:`ndim` giving the shape of the
memory as an N-dimensional array.
.. versionchanged:: 3.3
An empty tuple instead of ``None`` when ndim = 0.
.. attribute:: strides
A tuple of integers the length of :attr:`ndim` giving the size in bytes to
access each element for each dimension of the array.
.. versionchanged:: 3.3
An empty tuple instead of ``None`` when ndim = 0.
.. attribute:: suboffsets
Used internally for PIL-style arrays. The value is informational only.
.. attribute:: c_contiguous
A bool indicating whether the memory is C-:term:`contiguous`.
.. versionadded:: 3.3
.. attribute:: f_contiguous
A bool indicating whether the memory is Fortran :term:`contiguous`.
.. versionadded:: 3.3
.. attribute:: contiguous
A bool indicating whether the memory is :term:`contiguous`.
.. versionadded:: 3.3
For information on the thread safety of :class:`memoryview` objects in
the :term:`free-threaded build`, see :ref:`thread-safety-memoryview`.
.. _types-set:
Set Types --- :class:`set`, :class:`frozenset`
==============================================
.. index:: pair: object; set
A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects.
Common uses include membership testing, removing duplicates from a sequence, and
computing mathematical operations such as intersection, union, difference, and
symmetric difference.
(For other containers see the built-in :class:`dict`, :class:`list`,
and :class:`tuple` classes, and the :mod:`collections` module.)
See :ref:`time-complexity` for the costs of the various set operations.
Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
set``. Being an unordered collection, sets do not record element position or
order of insertion. Accordingly, sets do not support indexing, slicing, or
other sequence-like behavior.
There are currently two built-in set types, :class:`set` and :class:`frozenset`.
The :class:`set` type is mutable --- the contents can be changed using methods
like :meth:`~set.add` and :meth:`~set.remove`.
Since it is mutable, it has no hash value and cannot be used as
either a dictionary key or as an element of another set.
The :class:`frozenset` type is immutable and :term:`hashable` ---
its contents cannot be altered after it is created;
it can therefore be used as a dictionary key or as an element of another set.
Non-empty sets (not frozensets) can be created by placing a comma-separated list
of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the
:class:`set` constructor.
The constructors for both classes work the same:
.. class:: set(iterable=(), /)
frozenset(iterable=(), /)
Return a new set or frozenset object whose elements are taken from
*iterable*. The elements of a set must be :term:`hashable`. To
represent sets of sets, the inner sets must be :class:`frozenset`
objects. If *iterable* is not specified, a new empty set is
returned.
Sets can be created by several means:
* Use a comma-separated list of elements within braces: ``{'jack', 'sjoerd'}``
* Use a set comprehension: ``{c for c in 'abracadabra' if c not in 'abc'}``
* Use the type constructor: ``set()``, ``set('foobar')``, ``set(['a', 'b', 'foo'])``
Instances of :class:`set` and :class:`frozenset` provide the following
operations:
.. describe:: len(s)
Return the number of elements in set *s* (cardinality of *s*).
.. describe:: x in s
Test *x* for membership in *s*.
.. describe:: x not in s
Test *x* for non-membership in *s*.
.. method:: frozenset.isdisjoint(other, /)
set.isdisjoint(other, /)
Return ``True`` if the set has no elements in common with *other*. Sets are
disjoint if and only if their intersection is the empty set.
.. method:: frozenset.issubset(other, /)
set.issubset(other, /)
.. describe:: set <= other
Test whether every element in the set is in *other*.
.. describe:: set < other
Test whether the set is a proper subset of *other*, that is,
``set <= other and set != other``.
.. method:: frozenset.issuperset(other, /)
set.issuperset(other, /)
.. describe:: set >= other
Test whether every element in *other* is in the set.
.. describe:: set > other
Test whether the set is a proper superset of *other*, that is, ``set >=
other and set != other``.
.. method:: frozenset.union(*others)
set.union(*others)
.. describe:: set | other | ...
Return a new set with elements from the set and all others.
.. method:: frozenset.intersection(*others)
set.intersection(*others)
.. describe:: set & other & ...
Return a new set with elements common to the set and all others.
.. method:: frozenset.difference(*others)
set.difference(*others)
.. describe:: set - other - ...
Return a new set with elements in the set that are not in the others.
.. method:: frozenset.symmetric_difference(other, /)
set.symmetric_difference(other, /)
.. describe:: set ^ other
Return a new set with elements in either the set or *other* but not both.
.. method:: frozenset.copy()
set.copy()
Return a shallow copy of the set.
Note, the non-operator versions of :meth:`~frozenset.union`,
:meth:`~frozenset.intersection`, :meth:`~frozenset.difference`, :meth:`~frozenset.symmetric_difference`, :meth:`~frozenset.issubset`, and
:meth:`~frozenset.issuperset` methods will accept any iterable as an argument. In
contrast, their operator based counterparts require their arguments to be
sets. This precludes error-prone constructions like ``set('abc') & 'cbs'``
in favor of the more readable ``set('abc').intersection('cbs')``.
Both :class:`set` and :class:`frozenset` support set to set comparisons. Two
sets are equal if and only if every element of each set is contained in the
other (each is a subset of the other). A set is less than another set if and
only if the first set is a proper subset of the second set (is a subset, but
is not equal). A set is greater than another set if and only if the first set
is a proper superset of the second set (is a superset, but is not equal).
Instances of :class:`set` are compared to instances of :class:`frozenset`
based on their members. For example, ``set('abc') == frozenset('abc')``
returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``.
The subset and equality comparisons do not generalize to a total ordering
function. For example, any two nonempty disjoint sets are not equal and are not
subsets of each other, so *all* of the following return ``False``: ``ab``.
Since sets only define partial ordering (subset relationships), the output of
the :meth:`list.sort` method is undefined for lists of sets.
Set elements, like dictionary keys, must be :term:`hashable`.
Binary operations that mix :class:`set` instances with :class:`frozenset`
return the type of the first operand. For example: ``frozenset('ab') |
set('bc')`` returns an instance of :class:`frozenset`.
The following table lists operations available for :class:`set` that do not
apply to immutable instances of :class:`frozenset`:
.. method:: set.update(*others)
.. describe:: set |= other | ...
Update the set, adding elements from all others.
.. method:: set.intersection_update(*others)
.. describe:: set &= other & ...
Update the set, keeping only elements found in it and all others.
.. method:: set.difference_update(*others)
.. describe:: set -= other | ...
Update the set, removing elements found in others.
.. method:: set.symmetric_difference_update(other, /)
.. describe:: set ^= other
Update the set, keeping only elements found in either set, but not in both.
.. method:: set.add(elem, /)
Add element *elem* to the set.
.. method:: set.remove(elem, /)
Remove element *elem* from the set. Raises :exc:`KeyError` if *elem* is
not contained in the set.
.. method:: set.discard(elem, /)
Remove element *elem* from the set if it is present.
.. method:: set.pop()
Remove and return an arbitrary element from the set. Raises
:exc:`KeyError` if the set is empty.
.. method:: set.clear()
Remove all elements from the set.
Note, the non-operator versions of the :meth:`~set.update`,
:meth:`~set.intersection_update`, :meth:`~set.difference_update`, and
:meth:`~set.symmetric_difference_update` methods will accept any iterable as an
argument.
Note, the *elem* argument to the :meth:`~object.__contains__`,
:meth:`~set.remove`, and
:meth:`~set.discard` methods may be a set. To support searching for an equivalent
frozenset, a temporary one is created from *elem*.
Sets and frozensets are :ref:`generic <generics>` over the type of their elements.
.. seealso::
For detailed information on thread-safety guarantees for :class:`set`
objects, see :ref:`thread-safety-set`.
.. _typesmapping:
Mapping types --- :class:`!dict`, :class:`!frozendict`
======================================================
.. index::
pair: object; mapping
pair: object; dictionary
triple: operations on; mapping; types
triple: operations on; dictionary; type
pair: statement; del
pair: built-in function; len
A :term:`mapping` object maps :term:`hashable` values to arbitrary objects.
There are currently two standard mapping types, the :dfn:`dictionary` and
:class:`frozendict`.
(For other containers see the built-in
:class:`list`, :class:`set`, and :class:`tuple` classes, and the
:mod:`collections` module.)
See :ref:`time-complexity` for the costs of the various dictionary
operations.
A dictionary's keys are *almost* arbitrary values. Values that are not
:term:`hashable`, that is, values containing lists, dictionaries or other
mutable types (that are compared by value rather than by object identity) may
not be used as keys.
Values that compare equal (such as ``1``, ``1.0``, and ``True``)
can be used interchangeably to index the same dictionary entry.
.. class:: dict(**kwargs)
dict(mapping, /, **kwargs)
dict(iterable, /, **kwargs)
Return a new dictionary initialized from an optional positional argument
and a possibly empty set of keyword arguments.
Dictionaries can be created by several means:
* Use a comma-separated list of ``key: value`` pairs within braces:
``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 'jack', 4127: 'sjoerd'}``
* Use a dict comprehension: ``{}``, ``{x: x ** 2 for x in range(10)}``
* Use the type constructor: ``dict()``,
``dict([('foo', 100), ('bar', 200)])``, ``dict(foo=100, bar=200)``
If no positional argument is given, an empty dictionary is created.
If a positional argument is given and it defines a ``keys()`` method, a
dictionary is created by calling :meth:`~object.__getitem__` on the argument with
each returned key from the method. Otherwise, the positional argument must be an
:term:`iterable` object. Each item in the iterable must itself be an iterable
with exactly two elements. The first element of each item becomes a key in the
new dictionary, and the second element the corresponding value. If a key occurs
more than once, the last value for that key becomes the corresponding value in
the new dictionary.
If keyword arguments are given, the keyword arguments and their values are
added to the dictionary created from the positional argument. If a key
being added is already present, the value from the keyword argument
replaces the value from the positional argument.
Dictionaries compare equal if and only if they have the same ``(key,
value)`` pairs (regardless of ordering). Order comparisons ('<', '<=', '>=', '>') raise
:exc:`TypeError`. To illustrate dictionary creation and equality,
the following examples all return a dictionary equal to
``{"one": 1, "two": 2, "three": 3}``::
>>> a = dict(one=1, two=2, three=3)
>>> b = {'one': 1, 'two': 2, 'three': 3}
>>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
>>> d = dict([('two', 2), ('one', 1), ('three', 3)])
>>> e = dict({'three': 3, 'one': 1, 'two': 2})
>>> f = dict({'one': 1, 'three': 3}, two=2)
>>> a == b == c == d == e == f
True
Providing keyword arguments as in the first example only works for keys that
are valid Python identifiers. Otherwise, any valid keys can be used.
Dictionaries preserve insertion order. Note that updating a key does not
affect the order. Keys added after deletion are inserted at the end. ::
>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(d)
['one', 'two', 'three', 'four']
>>> list(d.values())
[1, 2, 3, 4]
>>> d["one"] = 42
>>> d
{'one': 42, 'two': 2, 'three': 3, 'four': 4}
>>> del d["two"]
>>> d["two"] = None
>>> d
{'one': 42, 'three': 3, 'four': 4, 'two': None}
.. versionchanged:: 3.7
Dictionary order is guaranteed to be insertion order. This behavior was
an implementation detail of CPython from 3.6.
Dictionaries are :ref:`generic <generics>` over two types, signifying
(respectively) the types of the dictionary's keys and values.
These are the operations that dictionaries support (and therefore, custom
mapping types should support too):
.. describe:: list(d)
Return a list of all the keys used in the dictionary *d*.
.. describe:: len(d)
Return the number of items in the dictionary *d*.
.. describe:: d[key]
Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is
not in the map.
.. index:: __missing__()
If a subclass of dict defines a method :meth:`~object.__missing__` and *key*
is not present, the ``d[key]`` operation calls that method with the key *key*
as argument. The ``d[key]`` operation then returns or raises whatever is
returned or raised by the ``__missing__(key)`` call.
No other operations or methods invoke :meth:`~object.__missing__`. If
:meth:`~object.__missing__` is not defined, :exc:`KeyError` is raised.
:meth:`~object.__missing__` must be a method; it cannot be an instance variable::
>>> class Counter(dict):
... def __missing__(self, key):
... return 0
...
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1
The example above shows part of the implementation of
:class:`collections.Counter`.
A different :meth:`!__missing__` method is used
by :class:`collections.defaultdict`.
.. describe:: d[key] = value
Set ``d[key]`` to *value*.
.. describe:: del d[key]
Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the
map.
.. describe:: key in d
Return ``True`` if *d* has a key *key*, else ``False``.
.. describe:: key not in d
Equivalent to ``not key in d``.
.. describe:: iter(d)
Return an iterator over the keys of the dictionary. This is a shortcut
for ``iter(d.keys())``.
.. method:: clear()
Remove all items from the dictionary.
.. method:: copy()
Return a shallow copy of the dictionary.
.. classmethod:: fromkeys(iterable, value=None, /)
Create a new dictionary with keys from *iterable* and values set to *value*.
:meth:`fromkeys` is a class method that returns a new dictionary. *value*
defaults to ``None``. All of the values refer to just a single instance,
so it generally doesn't make sense for *value* to be a mutable object
such as an empty list. To get distinct values, use a :ref:`dict
comprehension <dict>` instead.
.. method:: get(key, default=None, /)
Return the value for *key* if *key* is in the dictionary, else *default*.
If *default* is not given, it defaults to ``None``, so that this method
never raises a :exc:`KeyError`.
.. method:: items()
Return a new view of the dictionary's items (``(key, value)`` pairs).
See the :ref:`documentation of view objects <dict-views>`.
.. method:: keys()
Return a new view of the dictionary's keys. See the :ref:`documentation
of view objects <dict-views>`.
.. method:: pop(key, /)
pop(key, default, /)
If *key* is in the dictionary, remove it and return its value, else return
*default*. If *default* is not given and *key* is not in the dictionary,
a :exc:`KeyError` is raised.
.. method:: popitem()
Remove and return a ``(key, value)`` pair from the dictionary.
Pairs are returned in :abbr:`LIFO (last-in, first-out)` order.
:meth:`popitem` is useful to destructively iterate over a dictionary, as
often used in set algorithms. If the dictionary is empty, calling
:meth:`popitem` raises a :exc:`KeyError`.
.. versionchanged:: 3.7
LIFO order is now guaranteed. In prior versions, :meth:`popitem` would
return an arbitrary key/value pair.
.. describe:: reversed(d)
Return a reverse iterator over the keys of the dictionary. This is a
shortcut for ``reversed(d.keys())``.
.. versionadded:: 3.8
.. method:: setdefault(key, default=None, /)
If *key* is in the dictionary, return its value. If not, insert *key*
with a value of *default* and return *default*. *default* defaults to
``None``.
.. method:: update(**kwargs)
update(mapping, /, **kwargs)
update(iterable, /, **kwargs)
Update the dictionary with the key/value pairs from *mapping* or *iterable* and *kwargs*, overwriting
existing keys. Return ``None``.
:meth:`update` accepts either another object with a ``keys()`` method (in
which case :meth:`~object.__getitem__` is called with every key returned from
the method) or an iterable of key/value pairs (as tuples or other iterables
of length two). If keyword arguments are specified, the dictionary is then
updated with those key/value pairs: ``d.update(red=1, blue=2)``.
.. method:: values()
Return a new view of the dictionary's values. See the
:ref:`documentation of view objects <dict-views>`.
An equality comparison between one ``dict.values()`` view and another
will always return ``False``. This also applies when comparing
``dict.values()`` to itself::
>>> d = {'a': 1}
>>> d.values() == d.values()
False
.. describe:: d | other
Create a new dictionary with the merged keys and values of *d* and
*other*, which must both be dictionaries. The values of *other* take
priority when *d* and *other* share keys.
.. versionadded:: 3.9
.. describe:: d |= other
Update the dictionary *d* with keys and values from *other*, which may be
either a :term:`mapping` or an :term:`iterable` of key/value pairs. The
values of *other* take priority when *d* and *other* share keys.
.. versionadded:: 3.9
Dictionaries and dictionary views are reversible. ::
>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(reversed(d))
['four', 'three', 'two', 'one']
>>> list(reversed(d.values()))
[4, 3, 2, 1]
>>> list(reversed(d.items()))
[('four', 4), ('three', 3), ('two', 2), ('one', 1)]
.. versionchanged:: 3.8
Dictionaries are now reversible.
.. seealso::
:class:`frozendict` and :class:`types.MappingProxyType` can be used to
create a read-only view of a :class:`dict`.
.. seealso::
For detailed information on thread-safety guarantees for :class:`dict`
objects, see :ref:`thread-safety-dict`.
.. _dict-views:
Dictionary view objects
-----------------------
The objects returned by :meth:`dict.keys`, :meth:`dict.values` and
:meth:`dict.items` are *view objects*. They provide a dynamic view on the
dictionary's entries, which means that when the dictionary changes, the view
reflects these changes.
Dictionary views can be iterated over to yield their respective data, and
support membership tests:
.. describe:: len(dictview)
Return the number of entries in the dictionary.
.. describe:: iter(dictview)
Return an iterator over the keys, values or items (represented as tuples of
``(key, value)``) in the dictionary.
Keys and values are iterated over in insertion order.
This allows the creation of ``(value, key)`` pairs
using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to
create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``.
Iterating views while adding or deleting entries in the dictionary may raise
a :exc:`RuntimeError` or fail to iterate over all entries.
.. versionchanged:: 3.7
Dictionary order is guaranteed to be insertion order.
.. describe:: x in dictview
Return ``True`` if *x* is in the underlying dictionary's keys, values or
items (in the latter case, *x* should be a ``(key, value)`` tuple).
.. describe:: reversed(dictview)
Return a reverse iterator over the keys, values or items of the dictionary.
The view will be iterated in reverse order of the insertion.
.. versionchanged:: 3.8
Dictionary views are now reversible.
.. describe:: dictview.mapping
Return a :class:`types.MappingProxyType` that wraps the original
dictionary to which the view refers.
.. versionadded:: 3.10
Keys views are set-like since their entries are unique and :term:`hashable`.
Items views also have set-like operations since the (key, value) pairs
are unique and the keys are hashable.
If all values in an items view are hashable as well,
then the items view can interoperate with other sets.
(Values views are not treated as set-like
since the entries are generally not unique.) For set-like views, all of the
operations defined for the abstract base class :class:`collections.abc.Set` are
available (for example, ``==``, ``<``, or ``^``). While using set operators,
set-like views accept any iterable as the other operand,
unlike sets which only accept sets as the input.
An example of dictionary view usage::
>>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
>>> keys = dishes.keys()
>>> values = dishes.values()
>>> # iteration
>>> n = 0
>>> for val in values:
... n += val
...
>>> print(n)
504
>>> # keys and values are iterated over in the same order (insertion order)
>>> list(keys)
['eggs', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]
>>> # view objects are dynamic and reflect dict changes
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['bacon', 'spam']
>>> # set operations
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
>>> keys ^ {'sausage', 'juice'} == {'juice', 'sausage', 'bacon', 'spam'}
True
>>> keys | ['juice', 'juice', 'juice'] == {'bacon', 'spam', 'juice'}
True
>>> # get back a read-only proxy for the original dictionary
>>> values.mapping
mappingproxy({'bacon': 1, 'spam': 500})
>>> values.mapping['spam']
500
Frozen dictionaries
-------------------
.. class:: frozendict(**kwargs)
frozendict(mapping, /, **kwargs)
frozendict(iterable, /, **kwargs)
Return a new frozen dictionary initialized from an optional positional
argument and a possibly empty set of keyword arguments.
A :class:`!frozendict` has a similar API to the :class:`dict` API, with the
following differences:
* :class:`!dict` has more methods than :class:`!frozendict`:
* :meth:`!__delitem__`
* :meth:`!__setitem__`
* :meth:`~dict.clear`
* :meth:`~dict.pop`
* :meth:`~dict.popitem`
* :meth:`~dict.setdefault`
* :meth:`~dict.update`
* A :class:`!frozendict` can be hashed with ``hash(frozendict)`` if all keys and
values can be hashed.
* ``frozendict |= other`` does not modify the :class:`!frozendict` in-place but
creates a new frozen dictionary.
:class:`!frozendict` is not a :class:`!dict` subclass but inherits directly
from ``object``.
Like dictionaries, frozendicts are :ref:`generic <generics>` over two types,
signifying (respectively) the types of the frozendict's keys and values.
.. classmethod:: fromkeys(iterable, value=None, /)
Similar to :meth:`dict.fromkeys`, but call again the type constructor
with an initialized :class:`frozendict` if the type is a
:class:`frozendict` subclass or if the constructor returned a
:class:`frozendict`.
.. versionadded:: 3.15
.. _typecontextmanager:
Context Manager Types
=====================
.. index::
single: context manager
single: context management protocol
single: protocol; context management
Python's :keyword:`with` statement supports the concept of a runtime context
defined by a context manager. This is implemented using a pair of methods
that allow user-defined classes to define a runtime context that is entered
before the statement body is executed and exited when the statement ends:
.. method:: contextmanager.__enter__()
Enter the runtime context and return either this object or another object
related to the runtime context. The value returned by this method is bound to
the identifier in the :keyword:`!as` clause of :keyword:`with` statements using
this context manager.
An example of a context manager that returns itself is a :term:`file object`.
File objects return themselves from __enter__() to allow :func:`open` to be
used as the context expression in a :keyword:`with` statement.
An example of a context manager that returns a related object is the one
returned by :func:`decimal.localcontext`. These managers set the active
decimal context to a copy of the original decimal context and then return the
copy. This allows changes to be made to the current decimal context in the body
of the :keyword:`with` statement without affecting code outside the
:keyword:`!with` statement.
.. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb)
Exit the runtime context and return a Boolean flag indicating if any exception
that occurred should be suppressed. If an exception occurred while executing the
body of the :keyword:`with` statement, the arguments contain the exception type,
value and traceback information. Otherwise, all three arguments are ``None``.
Returning a true value from this method will cause the :keyword:`with` statement
to suppress the exception and continue execution with the statement immediately
following the :keyword:`!with` statement. Otherwise the exception continues
propagating after this method has finished executing.
If this method raises an exception while handling an earlier exception from the
:keyword:`with` block, the new exception is raised, and the original exception
is stored in its :attr:`~BaseException.__context__` attribute.
The exception passed in should never be reraised explicitly - instead, this
method should return a false value to indicate that the method completed
successfully and does not want to suppress the raised exception. This allows
context management code to easily detect whether or not an :meth:`~object.__exit__`
method has actually failed.
Python defines several context managers to support easy thread synchronisation,
prompt closure of files or other objects, and simpler manipulation of the active
decimal arithmetic context. The specific types are not treated specially beyond
their implementation of the context management protocol. See the
:mod:`contextlib` module for some examples.
Python's :term:`generator`\s and the :class:`contextlib.contextmanager` decorator
provide a convenient way to implement these protocols. If a generator function is
decorated with the :class:`contextlib.contextmanager` decorator, it will return a
context manager implementing the necessary :meth:`~contextmanager.__enter__` and
:meth:`~contextmanager.__exit__` methods, rather than the iterator produced by an
undecorated generator function.
Note that there is no specific slot for any of these methods in the type
structure for Python objects in the Python/C API. Extension types wanting to
define these methods must provide them as a normal Python accessible method.
Compared to the overhead of setting up the runtime context, the overhead of a
single class dictionary lookup is negligible.
Type Annotation Types --- :ref:`Generic Alias <types-genericalias>`, :ref:`Union <types-union>`
===============================================================================================
.. index::
single: annotation; type annotation; type hint
The core built-in types for :term:`type annotations <annotation>` are
:ref:`Generic Alias <types-genericalias>` and :ref:`Union <types-union>`.
.. _types-genericalias:
Generic Alias Type
------------------
.. index::
pair: object; GenericAlias
pair: Generic; Alias
``GenericAlias`` objects are generally created by
:ref:`subscripting <subscriptions>` a class. They are most often used with
:ref:`container classes <sequence-types>`, such as :class:`list` or
:class:`dict`. For example, ``list[int]`` is a ``GenericAlias`` object created
by subscripting the ``list`` class with the argument :class:`int`.
``GenericAlias`` objects are intended primarily for use with
:term:`type annotations <annotation>`.
.. note::
It is generally only possible to subscript a class if the class implements
the special method :meth:`~object.__class_getitem__`.
A ``GenericAlias`` object acts as a proxy for a :term:`generic type`,
implementing *parameterized generics*.
For a container class, the
argument(s) supplied to a :ref:`subscription <subscriptions>` of the class may
indicate the type(s) of the elements an object contains. For example,
``set[bytes]`` can be used in type annotations to signify a :class:`set` in
which all the elements are of type :class:`bytes`.
For a class which defines :meth:`~object.__class_getitem__` but is not a
container, the argument(s) supplied to a subscription of the class will often
indicate the return type(s) of one or more methods defined on an object. For
example, :mod:`regular expressions <re>` can be used on both the :class:`str` data
type and the :class:`bytes` data type:
* If ``x = re.search('foo', 'foo')``, ``x`` will be a
:ref:`re.Match <match-objects>` object where the return values of
``x.group(0)`` and ``x[0]`` will both be of type :class:`str`. We can
represent this kind of object in type annotations with the ``GenericAlias``
``re.Match[str]``.
* If ``y = re.search(b'bar', b'bar')``, (note the ``b`` for :class:`bytes`),
``y`` will also be an instance of ``re.Match``, but the return
values of ``y.group(0)`` and ``y[0]`` will both be of type
:class:`bytes`. In type annotations, we would represent this
variety of :ref:`re.Match <match-objects>` objects with ``re.Match[bytes]``.
``GenericAlias`` objects are instances of the class
:class:`types.GenericAlias`, which can also be used to create ``GenericAlias``
objects directly. Specializations of user-defined :ref:`generic classes <generic-classes>`
may not be instances of :class:`types.GenericAlias`, but they provide similar functionality.
.. describe:: T[X, Y, ...]
Creates a ``GenericAlias`` representing a type ``T`` parameterized by types
*X*, *Y*, and more depending on the ``T`` used.
For example, a function expecting a :class:`list` containing
:class:`float` elements::
def average(values: list[float]) -> float:
return sum(values) / len(values)
Another example for :term:`mapping` objects, using a :class:`dict`, which
is a generic type expecting two type parameters representing the key type
and the value type. In this example, the function expects a ``dict`` with
keys of type :class:`str` and values of type :class:`int`::
def send_post_request(url: str, body: dict[str, int]) -> None:
...
The builtin functions :func:`isinstance` and :func:`issubclass` do not accept
``GenericAlias`` types for their second argument::
>>> isinstance([1, 2], list[str])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot be a parameterized generic
The Python runtime does not enforce :term:`type annotations <annotation>`.
This extends to generic types and their type parameters. When creating
a container object from a ``GenericAlias``, the elements in the container are not checked
against their type. For example, the following code is discouraged, but will
run without errors::
>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]
Furthermore, parameterized generics erase type parameters during object
creation::
>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>
>>> l = t()
>>> type(l)
<class 'list'>
Instances of ``GenericAlias`` are not classes at runtime, even though they behave like classes (they can be instantiated and subclassed)::
>>> import inspect
>>> inspect.isclass(list[int])
False
This is true for :ref:`user-defined generics ` also.
Calling :func:`repr` or :func:`str` on a generic shows the parameterized type::
>>> repr(list[int])
'list[int]'
>>> str(list[int])
'list[int]'
The :meth:`~object.__getitem__` method of generic containers will raise an
exception to disallow mistakes like ``dict[str][str]``::
>>> dict[str][str]
Traceback (most recent call last):
...
TypeError: dict[str] is not a generic class
However, such expressions are valid when :ref:`type variables <generics>` are
used. The index must have as many elements as there are type variable items
in the ``GenericAlias`` object's :attr:`~genericalias.__args__`. ::
>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]
Standard Generic Classes
^^^^^^^^^^^^^^^^^^^^^^^^
The following standard library classes support parameterized generics. This
list is non-exhaustive.
* :class:`tuple`
* :class:`list`
* :class:`dict`
* :class:`set`
* :class:`frozendict`
* :class:`frozenset`
* :class:`type`
* :class:`asyncio.Future`
* :class:`asyncio.Task`
* :class:`collections.deque`
* :class:`collections.defaultdict`
* :class:`collections.OrderedDict`
* :class:`collections.Counter`
* :class:`collections.ChainMap`
* :class:`collections.abc.Awaitable`
* :class:`collections.abc.Coroutine`
* :class:`collections.abc.AsyncIterable`
* :class:`collections.abc.AsyncIterator`
* :class:`collections.abc.AsyncGenerator`
* :class:`collections.abc.Iterable`
* :class:`collections.abc.Iterator`
* :class:`collections.abc.Generator`
* :class:`collections.abc.Reversible`
* :class:`collections.abc.Container`
* :class:`collections.abc.Collection`
* :class:`collections.abc.Callable`
* :class:`collections.abc.Set`
* :class:`collections.abc.MutableSet`
* :class:`collections.abc.Mapping`
* :class:`collections.abc.MutableMapping`
* :class:`collections.abc.Sequence`
* :class:`collections.abc.MutableSequence`
* :class:`collections.abc.ByteString`
* :class:`collections.abc.MappingView`
* :class:`collections.abc.KeysView`
* :class:`collections.abc.ItemsView`
* :class:`collections.abc.ValuesView`
* :class:`contextlib.AbstractContextManager`
* :class:`contextlib.AbstractAsyncContextManager`
* :class:`dataclasses.Field`
* :class:`functools.cached_property`
* :class:`functools.partialmethod`
* :class:`os.PathLike`
* :class:`queue.LifoQueue`
* :class:`queue.Queue`
* :class:`queue.PriorityQueue`
* :class:`queue.SimpleQueue`
* :ref:`re.Pattern <re-objects>`
* :ref:`re.Match <match-objects>`
* :class:`shelve.BsdDbShelf`
* :class:`shelve.DbfilenameShelf`
* :class:`shelve.Shelf`
* :class:`types.MappingProxyType`
* :class:`weakref.WeakKeyDictionary`
* :class:`weakref.WeakMethod`
* :class:`weakref.WeakSet`
* :class:`weakref.WeakValueDictionary`
Special Attributes of ``GenericAlias`` objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All parameterized generics implement special read-only attributes.
.. attribute:: genericalias.__origin__
This attribute points at the non-parameterized generic class::
>>> list[int].__origin__
<class 'list'>
.. attribute:: genericalias.__args__
This attribute is a :class:`tuple` (possibly of length 1) of generic
types passed to the original :meth:`~object.__class_getitem__` of the
generic class::
>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])
.. attribute:: genericalias.__parameters__
This attribute is a lazily computed tuple (possibly empty) of unique type
variables found in ``__args__``::
>>> from typing import TypeVar
>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)
.. note::
A ``GenericAlias`` object with :class:`typing.ParamSpec` parameters may not
have correct ``__parameters__`` after substitution because
:class:`typing.ParamSpec` is intended primarily for static type checking.
.. attribute:: genericalias.__unpacked__
A boolean that is true if the alias has been unpacked using the
``*`` operator (see :data:`~typing.TypeVarTuple`).
.. versionadded:: 3.11
.. seealso::
:pep:`484` - Type Hints
Introducing Python's framework for type annotations.
:pep:`585` - Type Hinting Generics In Standard Collections
Introducing the ability to natively parameterize standard-library
classes, provided they implement the special class method
:meth:`~object.__class_getitem__`.
:ref:`Generics`, :ref:`user-defined generics ` and :class:`typing.Generic`
Documentation on how to implement generic classes that can be
parameterized at runtime and understood by static type-checkers.
.. versionadded:: 3.9
.. _types-union:
Union Type
----------
.. index::
pair: object; Union
pair: union; type
A union object holds the value of the ``|`` (bitwise or) operation on
multiple :ref:`type objects `. These types are intended
primarily for :term:`type annotations <annotation>`. The union type expression
enables cleaner type hinting syntax compared to subscripting :class:`typing.Union`.
.. describe:: X | Y | ...
Defines a union object which holds types *X*, *Y*, and so forth. ``X | Y``
means either X or Y. It is equivalent to ``typing.Union[X, Y]``.
For example, the following function expects an argument of type
:class:`int` or :class:`float`::
def square(number: int | float) -> int | float:
return number ** 2
.. note::
The ``|`` operator cannot be used at runtime to define unions where one or
more members is a forward reference. For example, ``int | "Foo"``, where
``"Foo"`` is a reference to a class not yet defined, will fail at
runtime. For unions which include forward references, present the
whole expression as a string, e.g. ``"int | Foo"``.
.. describe:: union_object == other
Union objects can be tested for equality with other union objects. Details:
* Unions of unions are flattened::
(int | str) | float == int | str | float
* Redundant types are removed::
int | str | int == int | str
* When comparing unions, the order is ignored::
int | str == str | int
* It creates instances of :class:`typing.Union`::
int | str == typing.Union[int, str]
type(int | str) is typing.Union
* Optional types can be spelled as a union with ``None``::
str | None == typing.Optional[str]
.. describe:: isinstance(obj, union_object)
.. describe:: issubclass(obj, union_object)
Calls to :func:`isinstance` and :func:`issubclass` are also supported with a
union object::
>>> isinstance("", int | str)
True
However, :ref:`parameterized generics <types-genericalias>` in
union objects cannot be checked::
>>> isinstance(1, int | list[int]) # short-circuit evaluation
True
>>> isinstance([1], int | list[int])
Traceback (most recent call last):
...
TypeError: isinstance() argument 2 cannot be a parameterized generic
The user-exposed type for the union object can be accessed from
:class:`typing.Union` and used for :func:`isinstance` checks::
>>> import typing
>>> isinstance(int | str, typing.Union)
True
>>> typing.Union()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: cannot create 'typing.Union' instances
.. note::
The :meth:`!__or__` method for type objects was added to support the syntax
``X | Y``. If a metaclass implements :meth:`!__or__`, the Union may
override it:
.. doctest::
>>> class M(type):
... def __or__(self, other):
... return "Hello"
...
>>> class C(metaclass=M):
... pass
...
>>> C | int
'Hello'
>>> int | C
int | C
.. seealso::
:pep:`604` -- PEP proposing the ``X | Y`` syntax and the Union type.
.. versionadded:: 3.10
.. versionchanged:: 3.14
Union objects are now instances of :class:`typing.Union`. Previously, they were instances
of :class:`types.UnionType`, which remains an alias for :class:`typing.Union`.
.. _typesother:
Other Built-in Types
====================
The interpreter supports several other kinds of objects. Most of these support
only one or two operations.
.. _typesmodules:
Modules
-------
The only special operation on a module is attribute access: ``m.name``, where
*m* is a module and *name* accesses a name defined in *m*'s symbol table.
Module attributes can be assigned to. (Note that the :keyword:`import`
statement is not, strictly speaking, an operation on a module object; ``import
foo`` does not require a module object named *foo* to exist, rather it requires
an (external) *definition* for a module named *foo* somewhere.)
A special attribute of every module is :attr:`~object.__dict__`. This is the
dictionary containing the module's symbol table. Modifying this dictionary will
actually change the module's symbol table, but direct assignment to the
:attr:`~object.__dict__` attribute is not possible (you can write
``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write
``m.__dict__ = {}``). Modifying :attr:`~object.__dict__` directly is
not recommended.
Modules built into the interpreter are written like this: ``<module 'sys'
(built-in)>``. If loaded from a file, they are written as ``<module 'os' from
'/usr/local/lib/pythonX.Y/os.pyc'>``.
.. _typesobjects:
Classes and Class Instances
---------------------------
See :ref:`objects` and :ref:`class` for these.
.. _typesfunctions:
Functions
---------
Function objects are created by function definitions. The only operation on a
function object is to call it: ``func(argument-list)``.
There are really two flavors of function objects: built-in functions and
user-defined functions. Both support the same operation (to call the function),
but the implementation is different, hence the different object types.
See :ref:`function` for more information.
.. _typesmethods:
Methods
-------
.. index:: pair: object; method
Methods are functions that are called using the attribute notation.
There are two flavors: :ref:`built-in methods `
(such as :meth:`~list.append` on lists)
and :ref:`class instance methods `.
Built-in methods are described with the types that support them.
If you access a method (a function defined in a class namespace) through an
instance, you get a special object: a :dfn:`bound method` (also called
:ref:`instance method `) object. When called, it will add
the ``self`` argument
to the argument list. Bound methods have two special read-only attributes:
:attr:`m.__self__ <method.__self__>` is the object on which the method
operates, and :attr:`m.__func__ <method.__func__>` is
the function implementing the method. Calling ``m(arg-1, arg-2, ..., arg-n)``
is completely equivalent to calling ``m.__func__(m.__self__, arg-1, arg-2, ...,
arg-n)``.
Like :ref:`function objects `, bound method objects support
getting arbitrary
attributes. However, since method attributes are actually stored on the
underlying function object (:attr:`method.__func__`), setting method attributes on
bound methods is disallowed. Attempting to set an attribute on a method
results in an :exc:`AttributeError` being raised. In order to set a method
attribute, you need to explicitly set it on the underlying function object:
.. doctest::
>>> class C:
... def method(self):
... pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method' # can't set on the method
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'
See :ref:`instance-methods` for more information.
.. index:: object; code, code object
.. _bltin-code-objects:
Code Objects
------------
.. index::
pair: built-in function; compile
single: __code__ (function object attribute)
Code objects are used by the implementation to represent "pseudo-compiled"
executable Python code such as a function body. They differ from function
objects because they don't contain a reference to their global execution
environment. Code objects are returned by the built-in :func:`compile` function
and can be extracted from function objects through their
:attr:`~function.__code__` attribute. See also the :mod:`code` module.
Accessing :attr:`~function.__code__` raises an :ref