Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

gh-101100: Fix most Sphinx nitpicks in the glossary and stdtypes.rst #112757

Merged
merged 2 commits into from
Dec 6, 2023
Merged

gh-101100: Fix most Sphinx nitpicks in the glossary and stdtypes.rst #112757

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8cfbdc2
Fix most Sphinx nitpicks in the glossary and `stdtypes.rst`
AlexWaygood Dec 5, 2023
54606d6
fix doctest that is now run in CI
AlexWaygood Dec 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 26 additions & 21 deletions Doc/glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,9 +151,9 @@
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.
Expand Down Expand Up @@ -304,8 +304,9 @@
: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
Expand All @@ -319,7 +320,8 @@

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
Expand Down Expand Up @@ -383,7 +385,7 @@

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It can refer to io.BaseIO.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure there's anything we could specifically link to for either method. io.IOBase does not have read() or write() as abstract methods, so neither IOBase.read nor IOBase.write is explicitly documented currently.

https://docs.python.org/3/library/io.html#io.IOBase

Here's all the IOBase docs say on read and write:

Even though IOBase does not declare read() or write() because their signatures will vary, implementations and clients should consider those methods part of the interface. Also, implementations may raise a ValueError (or UnsupportedOperation) when operations they do not support are called.

Specific subclasses of IOBase implement versions of read and write that either only work with raw binary streams or only work with text streams

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, and there is a reason to not declare them there. But there are many other references to read and write. It would be nice to have the general interface of them be documented somewhere. It is a different issue.

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,
Expand Down Expand Up @@ -559,8 +561,9 @@

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,
Expand Down Expand Up @@ -646,7 +649,8 @@
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
Expand All @@ -655,7 +659,7 @@
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`.
Expand All @@ -666,8 +670,8 @@
: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
Expand All @@ -681,7 +685,7 @@
.. 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
Expand Down Expand Up @@ -875,7 +879,8 @@
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
Expand Down Expand Up @@ -955,7 +960,7 @@
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`.

Expand Down Expand Up @@ -1089,18 +1094,18 @@
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

Check warning on line 1104 in Doc/glossary.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:meth reference target not found: count

Check warning on line 1104 in Doc/glossary.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:meth reference target not found: index
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`.

Expand Down
26 changes: 15 additions & 11 deletions Doc/library/stdtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,8 @@ Any object can be tested for truth value, for use in an :keyword:`if` or
.. 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:

Expand Down Expand Up @@ -197,7 +198,7 @@ exception.

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:

Expand Down Expand Up @@ -717,7 +718,7 @@ 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:`modulus` attribute of
made available to Python as the :attr:`~sys.hash_info.modulus` attribute of
:data:`sys.hash_info`.

.. impl-detail::
Expand Down Expand Up @@ -906,9 +907,9 @@ Generator Types
---------------

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>`.
Expand Down Expand Up @@ -3672,7 +3673,7 @@ The conversion types are:
+------------+-----------------------------------------------------+-------+
| ``'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. | |
Expand Down Expand Up @@ -4410,7 +4411,8 @@ The constructors for both classes work the same:
: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*.

Expand Down Expand Up @@ -5236,9 +5238,11 @@ instantiated from the type::
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
Comment on lines +5241 to +5242
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I considered linking to https://docs.python.org/3/reference/datamodel.html#object.__or__, but the data model only discusses implementing __or__ in the context of emulating numeric types, and that's pretty distinct to the purpose of type.__or__

override it:

.. doctest::

>>> class M(type):
... def __or__(self, other):
Expand All @@ -5250,7 +5254,7 @@ instantiated from the type::
>>> C | int
'Hello'
>>> int | C
int | __main__.C
int | C

.. seealso::

Expand Down
Loading