.. _glossary:

Glossary

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

* :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::

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

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*::

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

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.

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

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

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

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