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`,
- :data:`sys.stdout.buffer`, and instances of :class:`io.BytesIO` and
- :class:`gzip.GzipFile`.
+ ``'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.
:ref:`class definitions <class>` for more about decorators.
descriptor
- Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or
- :meth:`__delete__`. When a class attribute is a descriptor, its special
+ 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
dictionary
An associative array, where arbitrary keys are mapped to values. The
- keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
+ keys can be any object with :meth:`~object.__hash__` and
+ :meth:`~object.__eq__` methods.
Called a hash in Perl.
dictionary comprehension
file object
An object exposing a file-oriented API (with methods such as
- :meth:`read()` or :meth:`write()`) to an underlying resource. Depending
+ :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,
hashable
An object is *hashable* if it has a hash value which never changes during
- its lifetime (it needs a :meth:`__hash__` method), and can be compared to
- other objects (it needs an :meth:`__eq__` method). Hashable objects which
+ 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,
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:`__iter__` method or with a :meth:`~object.__getitem__` method
+ with an :meth:`~iterator.__iter__` method or with a
+ :meth:`~object.__getitem__` method
that implements :term:`sequence` semantics.
Iterables can be
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 ``for``
+ :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`.
: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:`__iter__` method that returns the iterator
+ :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
.. impl-detail::
CPython does not consistently apply the requirement that an iterator
- define :meth:`__iter__`.
+ define :meth:`~iterator.__iter__`.
key function
A key function or collation function is a callable that returns a value
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:`__getattribute__`, class methods, and static methods.
+ properties, :meth:`~object.__getattribute__`, class methods, and static
+ methods.
object
Any data with state (attributes or value) and defined behavior
finders implement.
path entry hook
- A callable on the :data:`sys.path_hook` list which returns a :term:`path
+ 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`.
sequence
An :term:`iterable` which supports efficient element access using integer
indices via the :meth:`~object.__getitem__` special method and defines a
- :meth:`__len__` method that returns the length of the sequence.
+ :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
+ supports :meth:`~object.__getitem__` and :meth:`!__len__`, but is considered a
mapping rather than a sequence because the lookups use arbitrary
:term:`immutable` 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:`__len__`, adding :meth:`count`,
- :meth:`index`, :meth:`__contains__`, and
- :meth:`__reversed__`. Types that implement this expanded
+ :meth:`~object.__getitem__` and :meth:`~object.__len__`, adding
+ :meth:`count`, :meth:`index`, :meth:`~object.__contains__`, and
+ :meth:`~object.__reversed__`. Types that implement this expanded
interface can be registered explicitly using
:func:`~abc.ABCMeta.register`.
.. 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:`__len__` method that
+:meth:`~object.__bool__` method that returns ``False`` or a
+:meth:`~object.__len__` method that
returns zero, when called with the object. [1]_ Here are most of the built-in
objects considered false:
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:`__contains__` method.
+implement the :meth:`~object.__contains__` method.
.. _typesnumeric:
: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:`modulus` attribute of
+made available to Python as the :attr:`~sys.hash_info.modulus` attribute of
:data:`sys.hash_info`.
.. impl-detail::
---------------
Python's :term:`generator`\s provide a convenient way to implement the iterator
-protocol. If a container object's :meth:`__iter__` method is implemented as a
+protocol. If a container object's :meth:`~iterator.__iter__` method is implemented as a
generator, it will automatically return an iterator object (technically, a
-generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__`
+generator object) supplying the :meth:`!__iter__` and :meth:`~generator.__next__`
methods.
More information about generators can be found in :ref:`the documentation for
the yield expression <yieldexpr>`.
+------------+-----------------------------------------------------+-------+
| ``'b'`` | Bytes (any object that follows the | \(5) |
| | :ref:`buffer protocol <bufferobjects>` or has | |
-| | :meth:`__bytes__`). | |
+| | :meth:`~object.__bytes__`). | |
+------------+-----------------------------------------------------+-------+
| ``'s'`` | ``'s'`` is an alias for ``'b'`` and should only | \(6) |
| | be used for Python2/3 code bases. | |
:meth:`symmetric_difference_update` methods will accept any iterable as an
argument.
- Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and
+ Note, the *elem* argument to the :meth:`~object.__contains__`,
+ :meth:`remove`, and
:meth:`discard` methods may be a set. To support searching for an equivalent
frozenset, a temporary one is created from *elem*.
TypeError: cannot create 'types.UnionType' 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::
+ 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):
>>> C | int
'Hello'
>>> int | C
- int | __main__.C
+ int | C
.. seealso::
projects / thirdparty / Python / cpython.git / commitdiff
