Byte Array Objects
------------------
-.. index:: object: bytearray
+.. index:: pair: object; bytearray
.. c:type:: PyByteArrayObject
These functions raise :exc:`TypeError` when expecting a bytes parameter and
called with a non-bytes parameter.
-.. index:: object: bytes
+.. index:: pair: object; bytes
.. c:type:: PyBytesObject
Capsules
--------
-.. index:: object: Capsule
+.. index:: pair: object; Capsule
Refer to :ref:`using-capsules` for more information on using these objects.
Complex Number Objects
----------------------
-.. index:: object: complex number
+.. index:: pair: object; complex number
Python's complex number objects are implemented as two distinct types when
viewed from the C API: one is the Python object exposed to Python programs, and
Numeric Objects
===============
-.. index:: object: numeric
+.. index:: pair: object; numeric
.. toctree::
Sequence Objects
================
-.. index:: object: sequence
+.. index:: pair: object; sequence
Generic operations on sequence objects were discussed in the previous chapter;
this section deals with the specific kinds of sequence objects that are
Container Objects
=================
-.. index:: object: mapping
+.. index:: pair: object; mapping
.. toctree::
Dictionary Objects
------------------
-.. index:: object: dictionary
+.. index:: pair: object; dictionary
.. c:type:: PyDictObject
File Objects
------------
-.. index:: object: file
+.. index:: pair: object; file
These APIs are a minimal emulation of the Python 2 C API for built-in file
objects, which used to rely on the buffered I/O (:c:expr:`FILE*`) support
Floating Point Objects
----------------------
-.. index:: object: floating point
+.. index:: pair: object; floating point
.. c:type:: PyFloatObject
Function Objects
----------------
-.. index:: object: function
+.. index:: pair: object; function
There are a few functions specific to Python functions.
Objects, Types and Reference Counts
===================================
-.. index:: object: type
+.. index:: pair: object; type
Most Python/C API functions have one or more arguments as well as a return value
of type :c:expr:`PyObject*`. This type is a pointer to an opaque data type
List Objects
------------
-.. index:: object: list
+.. index:: pair: object; list
.. c:type:: PyListObject
Integer Objects
---------------
-.. index:: object: long integer
- object: integer
+.. index:: pair: object; long integer
+ pair: object; integer
All integers are implemented as "long" integer objects of arbitrary size.
.. _memoryview-objects:
.. index::
- object: memoryview
+ pair: object; memoryview
MemoryView objects
------------------
Instance Method Objects
-----------------------
-.. index:: object: instancemethod
+.. index:: pair: object; instancemethod
An instance method is a wrapper for a :c:data:`PyCFunction` and the new way
to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
Method Objects
--------------
-.. index:: object: method
+.. index:: pair: object; method
Methods are bound function objects. Methods are always bound to an instance of
a user-defined class. Unbound methods (methods bound to a class object) are
Module Objects
--------------
-.. index:: object: module
+.. index:: pair: object; module
.. c:var:: PyTypeObject PyModule_Type
The ``None`` Object
-------------------
-.. index:: object: None
+.. index:: pair: object; None
Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the
Python/C API. Since ``None`` is a singleton, testing for object identity (using
.. index::
- object: set
- object: frozenset
+ pair: object; set
+ pair: object; frozenset
This section details the public API for :class:`set` and :class:`frozenset`
objects. Any functionality not listed below is best accessed using either
Tuple Objects
-------------
-.. index:: object: tuple
+.. index:: pair: object; tuple
.. c:type:: PyTupleObject
Type Objects
------------
-.. index:: object: type
+.. index:: pair: object; type
.. c:type:: PyTypeObject
.. class:: type(object)
type(name, bases, dict, **kwds)
- .. index:: object: type
+ .. 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
.. include:: ../includes/wasm-notavail.rst
-.. index:: object: socket
+.. index:: pair: object; socket
The Python interface is a straightforward transliteration of the Unix system
call and library interface for sockets to Python's object-oriented style: the
================================================================
.. index::
- object: numeric
- object: Boolean
- object: integer
- object: floating point
- object: complex number
+ 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
Common Sequence Operations
--------------------------
-.. index:: object: sequence
+.. 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
.. index::
triple: immutable; sequence; types
- object: tuple
+ pair: object; tuple
builtin: hash
The only operation that immutable sequence types generally implement that is
.. index::
triple: mutable; sequence; types
- object: list
- object: bytearray
+ 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
Lists
-----
-.. index:: object: list
+.. 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
Tuples
------
-.. index:: object: tuple
+.. 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`
Ranges
------
-.. index:: object: range
+.. 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`
.. index::
single: string; text sequence type
single: str (built-in class); (see also string)
- object: string
+ pair: object; string
.. _textseq:
strings of length 1. That is, for a non-empty string *s*, ``s[0] == s[0:1]``.
.. index::
- object: io.StringIO
+ 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
=================================================================================
.. index::
- object: bytes
- object: bytearray
- object: memoryview
+ 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
Bytes Objects
-------------
-.. index:: object: bytes
+.. 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
Bytearray Objects
-----------------
-.. index:: object: bytearray
+.. index:: pair: object; bytearray
:class:`bytearray` objects are a mutable counterpart to :class:`bytes`
objects.
Set Types --- :class:`set`, :class:`frozenset`
==============================================
-.. index:: object: set
+.. 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
===============================
.. index::
- object: mapping
- object: dictionary
+ pair: object; mapping
+ pair: object; dictionary
triple: operations on; mapping; types
triple: operations on; dictionary; type
statement: del
------------------
.. index::
- object: GenericAlias
+ pair: object; GenericAlias
pair: Generic; Alias
``GenericAlias`` objects are generally created by
----------
.. index::
- object: Union
+ pair: object; Union
pair: union; type
A union object holds the value of the ``|`` (bitwise or) operation on
Methods
-------
-.. index:: object: method
+.. index:: pair: object; method
Methods are functions that are called using the attribute notation. There are
two flavors: built-in methods (such as :meth:`append` on lists) and class
object <traceback-objects>` which typically encapsulates the call
stack at the point where the exception last occurred.
- .. index:: object: traceback
+ .. index:: pair: object; traceback
If no exception is being handled anywhere on the stack, this function
return a tuple containing three ``None`` values.
stack traces under program control, such as in a "wrapper" around the
interpreter.
-.. index:: object: traceback
+.. index:: pair: object; traceback
The module uses traceback objects --- these are objects of type :class:`types.TracebackType`,
which are assigned to the ``__traceback__`` field of :class:`BaseException` instances.
pair: keyword; else
pair: target; list
pair: loop; statement
- object: sequence
+ pair: object; sequence
single: : (colon); compound statement
The :keyword:`for` statement is used to iterate over the elements of a sequence
.. index::
pair: module; sys
- object: traceback
+ pair: object; traceback
Before an :keyword:`!except` clause's suite is executed,
the exception is stored in the :mod:`sys` module, where it can be accessed
pair: function; definition
pair: function; name
pair: name; binding
- object: user-defined function
- object: function
+ pair: object; user-defined function
+ pair: object; function
pair: function; name
pair: name; binding
single: () (parentheses); function definition
=================
.. index::
- object: class
+ pair: object; class
statement: class
pair: class; definition
pair: class; name
are not intended for general use. Their definition may change in the future.
None
- .. index:: object: None
+ .. index:: pair: object; None
This type has a single value. There is a single object with this value. This
object is accessed through the built-in name ``None``. It is used to signify the
don't explicitly return anything. Its truth value is false.
NotImplemented
- .. index:: object: NotImplemented
+ .. index:: pair: object; NotImplemented
This type has a single value. There is a single object with this value. This
object is accessed through the built-in name ``NotImplemented``. Numeric methods
Ellipsis
.. index::
- object: Ellipsis
+ pair: object; Ellipsis
single: ...; ellipsis literal
This type has a single value. There is a single object with this value. This
``Ellipsis``. Its truth value is true.
:class:`numbers.Number`
- .. index:: object: numeric
+ .. index:: pair: object; numeric
These are created by numeric literals and returned as results by arithmetic
operators and arithmetic built-in functions. Numeric objects are immutable;
numbers:
:class:`numbers.Integral`
- .. index:: object: integer
+ .. index:: pair: object; integer
These represent elements from the mathematical set of integers (positive and
negative).
Booleans (:class:`bool`)
.. index::
- object: Boolean
+ pair: object; Boolean
single: False
single: True
:class:`numbers.Real` (:class:`float`)
.. index::
- object: floating point
+ pair: object; floating point
pair: floating point; number
pair: C; language
pair: Java; language
:class:`numbers.Complex` (:class:`complex`)
.. index::
- object: complex
+ pair: object; complex
pair: complex; number
These represent complex numbers as a pair of machine-level double precision
Sequences
.. index::
builtin: len
- object: sequence
+ pair: object; sequence
single: index operation
single: item selection
single: subscription
Immutable sequences
.. index::
- object: immutable sequence
- object: immutable
+ pair: object; immutable sequence
+ pair: object; immutable
An object of an immutable sequence type cannot change once it is created. (If
the object contains references to other objects, these other objects may be
Tuples
.. index::
- object: tuple
+ pair: object; tuple
pair: singleton; tuple
pair: empty; tuple
Mutable sequences
.. index::
- object: mutable sequence
- object: mutable
+ pair: object; mutable sequence
+ pair: object; mutable
pair: assignment; statement
single: subscription
single: slicing
There are currently two intrinsic mutable sequence types:
Lists
- .. index:: object: list
+ .. index:: pair: object; list
The items of a list are arbitrary Python objects. Lists are formed by
placing a comma-separated list of expressions in square brackets. (Note
Set types
.. index::
builtin: len
- object: set type
+ pair: object; set type
These represent unordered, finite sets of unique, immutable objects. As such,
they cannot be indexed by any subscript. However, they can be iterated over, and
There are currently two intrinsic set types:
Sets
- .. index:: object: set
+ .. index:: pair: object; set
These represent a mutable set. They are created by the built-in :func:`set`
constructor and can be modified afterwards by several methods, such as
:meth:`~set.add`.
Frozen sets
- .. index:: object: frozenset
+ .. index:: pair: object; frozenset
These represent an immutable set. They are created by the built-in
:func:`frozenset` constructor. As a frozenset is immutable and
.. index::
builtin: len
single: subscription
- object: mapping
+ pair: object; mapping
These represent finite sets of objects indexed by arbitrary index sets. The
subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
There is currently a single intrinsic mapping type:
Dictionaries
- .. index:: object: dictionary
+ .. index:: pair: object; dictionary
These represent finite sets of objects indexed by nearly arbitrary values. The
only types of values not acceptable as keys are values containing lists or
Callable types
.. index::
- object: callable
+ pair: object; callable
pair: function; call
single: invocation
pair: function; argument
User-defined functions
.. index::
pair: user-defined; function
- object: function
- object: user-defined function
+ pair: object; function
+ pair: object; user-defined function
A user-defined function object is created by a function definition (see
section :ref:`function`). It should be called with an argument list
Instance methods
.. index::
- object: method
- object: user-defined method
+ pair: object; method
+ pair: object; user-defined method
pair: user-defined; method
An instance method object combines a class, a class instance and any
Built-in functions
.. index::
- object: built-in function
- object: function
+ pair: object; built-in function
+ pair: object; function
pair: C; language
A built-in function object is a wrapper around a C function. Examples of
Built-in methods
.. index::
- object: built-in method
- object: method
+ pair: object; built-in method
+ pair: object; method
pair: built-in; method
This is really a different disguise of a built-in function, this time containing
Modules
.. index::
statement: import
- object: module
+ pair: object; module
Modules are a basic organizational unit of Python code, and are created by
the :ref:`import system <importsystem>` as invoked either by the
.. XXX: Could we add that MRO doc as an appendix to the language ref?
.. index::
- object: class
- object: class instance
- object: instance
+ pair: object; class
+ pair: object; class instance
+ pair: object; instance
pair: class object; call
single: container
- object: dictionary
+ pair: object; dictionary
pair: class; attribute
When a class attribute reference (for class :class:`C`, say) would yield a
Class instances
.. index::
- object: class instance
- object: instance
+ pair: object; class instance
+ pair: object; instance
pair: class; instance
pair: class instance; attribute
dictionary directly.
.. index::
- object: numeric
- object: sequence
- object: mapping
+ pair: object; numeric
+ pair: object; sequence
+ pair: object; mapping
Class instances can pretend to be numbers, sequences, or mappings if they have
methods with certain special names. See section :ref:`specialnames`.
required stack size; :attr:`co_flags` is an integer encoding a number
of flags for the interpreter.
- .. index:: object: generator
+ .. index:: pair: object; generator
The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
the function uses the ``*arguments`` syntax to accept an arbitrary number of
.. _frame-objects:
Frame objects
- .. index:: object: frame
+ .. index:: pair: object; frame
Frame objects represent execution frames. They may occur in traceback objects
(see below), and are also passed to registered trace functions.
Traceback objects
.. index::
- object: traceback
+ pair: object; traceback
pair: stack; trace
pair: exception; handler
pair: execution; stack
.. method:: object.__hash__(self)
.. index::
- object: dictionary
+ pair: object; dictionary
builtin: hash
Called by built-in function :func:`hash` and for operations on members of
.. versionadded:: 3.4
-.. index:: object: slice
+.. index:: pair: object; slice
.. note::
pair: list; display
pair: list; comprehensions
pair: empty; list
- object: list
+ pair: object; list
single: [] (square brackets); list expression
single: , (comma); expression list
.. index::
pair: set; display
pair: set; comprehensions
- object: set
+ pair: object; set
single: {} (curly brackets); set expression
single: , (comma); expression list
pair: dictionary; display
pair: dictionary; comprehensions
key, datum, key/datum pair
- object: dictionary
+ pair: object; dictionary
single: {} (curly brackets); dictionary expression
single: : (colon); in dictionary expressions
single: , (comma); in dictionary displays
.. index::
pair: generator; expression
- object: generator
+ pair: object; generator
single: () (parentheses); generator expression
A generator expression is a compact generator notation in parentheses:
The proposal that expanded on :pep:`492` by adding generator capabilities to
coroutine functions.
-.. index:: object: generator
+.. index:: pair: object; generator
.. _generator-methods:
Generator-iterator methods
The expression ``yield from <expr>`` is a syntax error when used in an
asynchronous generator function.
-.. index:: object: asynchronous-generator
+.. index:: pair: object; asynchronous-generator
.. _asynchronous-generator-methods:
Asynchronous generator-iterator methods
.. index::
exception: AttributeError
- object: module
- object: list
+ pair: object; module
+ pair: object; list
The primary must evaluate to an object of a type that supports attribute
references, which most objects do. This object is then asked to produce the
single: [] (square brackets); subscription
.. index::
- object: sequence
- object: mapping
- object: string
- object: tuple
- object: list
- object: dictionary
+ pair: object; sequence
+ pair: object; mapping
+ pair: object; string
+ pair: object; tuple
+ pair: object; list
+ pair: object; dictionary
pair: sequence; item
The subscription of an instance of a :ref:`container class <sequence-types>`
single: , (comma); slicing
.. index::
- object: sequence
- object: string
- object: tuple
- object: list
+ pair: object; sequence
+ pair: object; string
+ pair: object; tuple
+ pair: object; list
A slicing selects a range of items in a sequence object (e.g., a string, tuple
or list). Slicings may be used as expressions or as targets in assignment or
.. index::
- object: callable
+ pair: object; callable
single: call
single: argument; call semantics
single: () (parentheses); call
.. index::
pair: function; call
triple: user-defined; function; call
- object: user-defined function
- object: function
+ pair: object; user-defined function
+ pair: object; function
The code block for the function is executed, passing it the argument list. The
first thing the code block will do is bind the formal parameters to the
pair: built-in function; call
pair: method; call
pair: built-in method; call
- object: built-in method
- object: built-in function
- object: method
- object: function
+ pair: object; built-in method
+ pair: object; built-in function
+ pair: object; method
+ pair: object; function
The result is up to the interpreter; see :ref:`built-in-funcs` for the
descriptions of built-in functions and methods.
a class object:
.. index::
- object: class
+ pair: object; class
pair: class object; call
A new instance of that class is returned.
a class instance method:
.. index::
- object: class instance
- object: instance
+ pair: object; class instance
+ pair: object; instance
pair: class instance; call
The corresponding user-defined function is called, with an argument list that is
pair: operator; in
pair: operator; not in
pair: membership; test
- object: sequence
+ pair: object; sequence
The operator :keyword:`not in` is defined to have the inverse truth value of
:keyword:`in`.
starred_expression: `expression` | (`starred_item` ",")* [`starred_item`]
starred_item: `assignment_expression` | "*" `or_expr`
-.. index:: object: tuple
+.. index:: pair: object; tuple
Except when part of a list or set display, an expression list
containing at least one comma yields a tuple. The length of
.. index::
builtin: repr
- object: None
+ pair: object; None
pair: string; conversion
single: output
pair: standard; output
pair: assignment; statement
pair: binding; name
pair: rebinding; name
- object: mutable
+ pair: object; mutable
pair: attribute; assignment
Assignment statements are used to (re)bind names to values and to modify
.. index::
pair: subscription; assignment
- object: mutable
+ pair: object; mutable
* If the target is a subscription: The primary expression in the reference is
evaluated. It should yield either a mutable sequence object (such as a list)
evaluated.
.. index::
- object: sequence
- object: list
+ pair: object; sequence
+ pair: object; list
If the primary is a mutable sequence object (such as a list), the subscript
must yield an integer. If it is negative, the sequence's length is added to
raised (assignment to a subscripted sequence cannot add new items to a list).
.. index::
- object: mapping
- object: dictionary
+ pair: object; mapping
+ pair: object; dictionary
If the primary is a mapping object (such as a dictionary), the subscript must
have a type compatible with the mapping's key type, and the mapping is then
The :dfn:`type` of the exception is the exception instance's class, the
:dfn:`value` is the instance itself.
-.. index:: object: traceback
+.. index:: pair: object; traceback
A traceback object is normally created automatically when an exception is raised
and attached to it as the :attr:`__traceback__` attribute, which is writable.
pairindextypes.pop('module', None)
pairindextypes.pop('keyword', None)
pairindextypes.pop('operator', None)
- # pairindextypes.pop('object', None)
+ pairindextypes.pop('object', None)
# pairindextypes.pop('exception', None)
# pairindextypes.pop('statement', None)
# pairindextypes.pop('builtin', None)
However, in the following discussion, we'll use the term method exclusively to
mean methods of class instance objects, unless explicitly stated otherwise.)
-.. index:: object: method
+.. index:: pair: object; method
Valid method names of an instance object depend on its class. By definition,
all attributes of a class that are function objects define corresponding
.. index::
builtin: open
- object: file
+ pair: object; file
:func:`open` returns a :term:`file object`, and is most commonly used with
two positional arguments and one keyword argument:
projects / thirdparty / Python / cpython.git / commitdiff
