Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitba69585

Browse files
[3.11]gh-101100: Fix Sphinx nitpicks inlibrary/collections.abc.rst (GH-113116) (#113137)
gh-101100: Fix Sphinx nitpicks in `library/collections.abc.rst` (GH-113116)(cherry picked from commit006355b)Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
1 parent99c8d16 commitba69585

File tree

3 files changed

+43
-41
lines changed

3 files changed

+43
-41
lines changed

‎Doc/conf.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -231,10 +231,11 @@
231231
# be resolved, as the method is currently undocumented. For context, see
232232
# https://github.com/python/cpython/pull/103289.
233233
('py:meth','_SubParsersAction.add_parser'),
234-
# Attributes that definitely should be documented better,
234+
# Attributes/methods/etc. that definitely should be documented better,
235235
# but are deferred for now:
236236
('py:attr','__annotations__'),
237237
('py:attr','__wrapped__'),
238+
('py:meth','index'),# list.index, tuple.index, etc.
238239
]
239240

240241
# gh-106948: Copy standard C types declared in the "c:type" domain to the

‎Doc/library/collections.abc.rst

Lines changed: 41 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
This module provides:term:`abstract base classes <abstract base class>` that
2424
can be used to test whether a class provides a particular interface; for
25-
example, whether it is:term:`hashable` or whether it is a mapping.
25+
example, whether it is:term:`hashable` or whether it is a:term:`mapping`.
2626

2727
An:func:`issubclass` or:func:`isinstance` test for an interface works in one
2828
of three ways.
@@ -73,7 +73,7 @@ of the API:
7373
>>>isinstance(D(), Sequence)
7474
True
7575

76-
In this example, class:class:`D` does not need to define
76+
In this example, class:class:`!D` does not need to define
7777
``__contains__``, ``__iter__``, and ``__reversed__`` because the
7878
:ref:`in-operator<comparisons>`, the:term:`iteration <iterable>`
7979
logic, and the:func:`reversed` function automatically fall back to
@@ -182,14 +182,14 @@ ABC Inherits from Abstract Methods Mi
182182

183183
..rubric::Footnotes
184184

185-
.. [1]These ABCs override:meth:`object.__subclasshook__` to support
185+
.. [1]These ABCs override:meth:`~abc.ABCMeta.__subclasshook__` to support
186186
testing an interface by verifying the required methods are present
187187
and have not been set to:const:`None`. This only works for simple
188188
interfaces. More complex interfaces require registration or direct
189189
subclassing.
190190
191191
.. [2]Checking ``isinstance(obj, Iterable)`` detects classes that are
192-
registered as:class:`Iterable` or that have an:meth:`__iter__`
192+
registered as:class:`Iterable` or that have an:meth:`~container.__iter__`
193193
method, but it does not detect classes that iterate with the
194194
:meth:`~object.__getitem__` method. The only reliable way to determine
195195
whether an object is:term:`iterable` is to call ``iter(obj)``.
@@ -201,26 +201,27 @@ Collections Abstract Base Classes -- Detailed Descriptions
201201

202202
..class::Container
203203

204-
ABC for classes that provide the:meth:`__contains__` method.
204+
ABC for classes that provide the:meth:`~object.__contains__` method.
205205

206206
..class::Hashable
207207

208-
ABC for classes that provide the:meth:`__hash__` method.
208+
ABC for classes that provide the:meth:`~object.__hash__` method.
209209

210210
..class::Sized
211211

212-
ABC for classes that provide the:meth:`__len__` method.
212+
ABC for classes that provide the:meth:`~object.__len__` method.
213213

214214
..class::Callable
215215

216-
ABC for classes that provide the:meth:`__call__` method.
216+
ABC for classes that provide the:meth:`~object.__call__` method.
217217

218218
..class::Iterable
219219

220-
ABC for classes that provide the:meth:`__iter__` method.
220+
ABC for classes that provide the:meth:`~container.__iter__` method.
221221

222222
Checking ``isinstance(obj, Iterable)`` detects classes that are registered
223-
as:class:`Iterable` or that have an:meth:`__iter__` method, but it does
223+
as:class:`Iterable` or that have an:meth:`~container.__iter__` method,
224+
but it does
224225
not detect classes that iterate with the:meth:`~object.__getitem__` method.
225226
The only reliable way to determine whether an object is:term:`iterable`
226227
is to call ``iter(obj)``.
@@ -239,17 +240,17 @@ Collections Abstract Base Classes -- Detailed Descriptions
239240

240241
..class::Reversible
241242

242-
ABC for iterable classes that also provide the:meth:`__reversed__`
243+
ABC for iterable classes that also provide the:meth:`~object.__reversed__`
243244
method.
244245

245246
..versionadded::3.6
246247

247248
..class::Generator
248249

249-
ABC for generator classes that implement the protocol defined in
250-
:pep:`342` that extends iterators with the:meth:`~generator.send`,
250+
ABC for:term:`generator` classes that implement the protocol defined in
251+
:pep:`342` that extends:term:`iterators <iterator>` with the
252+
:meth:`~generator.send`,
251253
:meth:`~generator.throw` and:meth:`~generator.close` methods.
252-
See also the definition of:term:`generator`.
253254

254255
..versionadded::3.5
255256

@@ -260,7 +261,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
260261
ABCs for read-only and mutable:term:`sequences <sequence>`.
261262

262263
Implementation note: Some of the mixin methods, such as
263-
:meth:`__iter__`,:meth:`__reversed__` and:meth:`index`, make
264+
:meth:`~container.__iter__`,:meth:`~object.__reversed__` and:meth:`index`, make
264265
repeated calls to the underlying:meth:`~object.__getitem__` method.
265266
Consequently, if:meth:`~object.__getitem__` is implemented with constant
266267
access speed, the mixin methods will have linear performance;
@@ -275,7 +276,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
275276
..class::Set
276277
MutableSet
277278

278-
ABCs for read-only and mutable sets.
279+
ABCs for read-only and mutable:ref:`sets<types-set>`.
279280

280281
..class::Mapping
281282
MutableMapping
@@ -292,42 +293,42 @@ Collections Abstract Base Classes -- Detailed Descriptions
292293
..class::Awaitable
293294

294295
ABC for:term:`awaitable` objects, which can be used in:keyword:`await`
295-
expressions. Custom implementations must provide the:meth:`__await__`
296-
method.
296+
expressions. Custom implementations must provide the
297+
:meth:`~object.__await__`method.
297298

298299
:term:`Coroutine <coroutine>` objects and instances of the
299300
:class:`~collections.abc.Coroutine` ABC are all instances of this ABC.
300301

301302
..note::
302-
In CPython, generator-based coroutines (generatorsdecorated with
303-
:func:`types.coroutine`) are
304-
*awaitables*, even though they do not have an:meth:`__await__` method.
303+
In CPython, generator-based coroutines (:term:`generators<generator>`
304+
decorated with:func:`@types.coroutine <types.coroutine>`) are
305+
*awaitables*, even though they do not have an:meth:`~object.__await__` method.
305306
Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``.
306307
Use:func:`inspect.isawaitable` to detect them.
307308

308309
..versionadded::3.5
309310

310311
..class::Coroutine
311312

312-
ABC for coroutine compatible classes. These implement the
313+
ABC for:term:`coroutine` compatible classes. These implement the
313314
following methods, defined in:ref:`coroutine-objects`:
314315
:meth:`~coroutine.send`,:meth:`~coroutine.throw`, and
315316
:meth:`~coroutine.close`. Custom implementations must also implement
316-
:meth:`__await__`. All:class:`Coroutine` instances are also instances of
317-
:class:`Awaitable`. See also the definitionof:term:`coroutine`.
317+
:meth:`~object.__await__`. All:class:`Coroutine` instances are also
318+
instancesof:class:`Awaitable`.
318319

319320
..note::
320-
In CPython, generator-based coroutines (generatorsdecorated with
321-
:func:`types.coroutine`) are
322-
*awaitables*, even though they do not have an:meth:`__await__` method.
321+
In CPython, generator-based coroutines (:term:`generators<generator>`
322+
decorated with:func:`@types.coroutine <types.coroutine>`) are
323+
*awaitables*, even though they do not have an:meth:`~object.__await__` method.
323324
Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``.
324325
Use:func:`inspect.isawaitable` to detect them.
325326

326327
..versionadded::3.5
327328

328329
..class::AsyncIterable
329330

330-
ABC for classes that provide ``__aiter__`` method. See also the
331+
ABC for classes that providean``__aiter__`` method. See also the
331332
definition of:term:`asynchronous iterable`.
332333

333334
..versionadded::3.5
@@ -341,7 +342,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
341342

342343
..class::AsyncGenerator
343344

344-
ABC for asynchronous generator classes that implement the protocol
345+
ABC for:term:`asynchronous generator` classes that implement the protocol
345346
defined in:pep:`525` and:pep:`492`.
346347

347348
..versionadded::3.6
@@ -359,9 +360,9 @@ particular functionality, for example::
359360
Several of the ABCs are also useful as mixins that make it easier to develop
360361
classes supporting container APIs. For example, to write a class supporting
361362
the full:class:`Set` API, it is only necessary to supply the three underlying
362-
abstract methods::meth:`__contains__`,:meth:`__iter__`, and:meth:`__len__`.
363-
The ABC supplies the remaining methods such as:meth:`__and__` and
364-
:meth:`isdisjoint`::
363+
abstract methods::meth:`~object.__contains__`,:meth:`~container.__iter__`, and
364+
:meth:`~object.__len__`.The ABC supplies the remaining methods such as
365+
:meth:`!__and__` and:meth:`~frozenset.isdisjoint`::
365366

366367
class ListBasedSet(collections.abc.Set):
367368
''' Alternate set implementation favoring space over speed
@@ -389,23 +390,24 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
389390

390391
(1)
391392
Since some set operations create new sets, the default mixin methods need
392-
a way to create new instances from an iterable. The class constructor is
393+
a way to create new instances from an:term:`iterable`. The class constructor is
393394
assumed to have a signature in the form ``ClassName(iterable)``.
394-
That assumption is factored-out to an internal classmethod called
395-
:meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
395+
That assumption is factored-out to an internal:class:`classmethod` called
396+
:meth:`!_from_iterable` which calls ``cls(iterable)`` to produce a new set.
396397
If the:class:`Set` mixin is being used in a class with a different
397-
constructor signature, you will need to override:meth:`_from_iterable`
398+
constructor signature, you will need to override:meth:`!_from_iterable`
398399
with a classmethod or regular method that can construct new instances from
399400
an iterable argument.
400401

401402
(2)
402403
To override the comparisons (presumably for speed, as the
403-
semantics are fixed), redefine:meth:`__le__` and:meth:`__ge__`,
404+
semantics are fixed), redefine:meth:`~object.__le__` and
405+
:meth:`~object.__ge__`,
404406
then the other operations will automatically follow suit.
405407

406408
(3)
407-
The:class:`Set` mixin provides a:meth:`_hash` method to compute a hash value
408-
for the set; however,:meth:`__hash__` is not defined because not all sets
409+
The:class:`Set` mixin provides a:meth:`!_hash` method to compute a hash value
410+
for the set; however,:meth:`~object.__hash__` is not defined because not all sets
409411
are:term:`hashable` or immutable. To add set hashability using mixins,
410412
inherit from both:meth:`Set` and:meth:`Hashable`, then define
411413
``__hash__ = Set._hash``.

‎Doc/tools/.nitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,6 @@ Doc/library/bdb.rst
3535
Doc/library/bisect.rst
3636
Doc/library/calendar.rst
3737
Doc/library/cmd.rst
38-
Doc/library/collections.abc.rst
3938
Doc/library/collections.rst
4039
Doc/library/concurrent.futures.rst
4140
Doc/library/configparser.rst

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp