Skip to content

[3.12] GH-121970: Replace custom abstract method directive with the :abstract: option (GH-129311) #130440

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

Merged
merged 1 commit into from
Feb 22, 2025
Merged

[3.12] GH-121970: Replace custom abstract method directive with the :abstract: option (GH-129311) #130440

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
33 changes: 22 additions & 11 deletions Doc/library/importlib.resources.abc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,27 +46,31 @@
.. deprecated:: 3.12
Use :class:`importlib.resources.abc.TraversableResources` instead.

.. abstractmethod:: open_resource(resource)
.. method:: open_resource(resource)
:abstractmethod:

Returns an opened, :term:`file-like object` for binary reading
of the *resource*.

If the resource cannot be found, :exc:`FileNotFoundError` is
raised.

.. abstractmethod:: resource_path(resource)
.. method:: resource_path(resource)
:abstractmethod:

Returns the file system path to the *resource*.

If the resource does not concretely exist on the file system,
raise :exc:`FileNotFoundError`.

.. abstractmethod:: is_resource(name)
.. method:: is_resource(name)
:abstractmethod:

Returns ``True`` if the named *name* is considered a resource.
:exc:`FileNotFoundError` is raised if *name* does not exist.

.. abstractmethod:: contents()
.. method:: contents()
:abstractmethod:

Returns an :term:`iterable` of strings over the contents of
the package. Do note that it is not required that all names
Expand Down Expand Up @@ -97,19 +101,23 @@

Abstract. The base name of this object without any parent references.

.. abstractmethod:: iterdir()
.. method:: iterdir()
:abstractmethod:

Yield Traversable objects in self.

.. abstractmethod:: is_dir()
.. method:: is_dir()
:abstractmethod:

Return ``True`` if self is a directory.

.. abstractmethod:: is_file()
.. method:: is_file()
:abstractmethod:

Return ``True`` if self is a file.

.. abstractmethod:: joinpath(*pathsegments)
.. method:: joinpath(*pathsegments)
:abstractmethod:

Traverse directories according to *pathsegments* and return
the result as :class:`!Traversable`.
Expand All @@ -134,12 +142,14 @@
may contain forward slashes as path separators.
Previously, only a single *child* argument was accepted.

.. abstractmethod:: __truediv__(child)
.. method:: __truediv__(child)
:abstractmethod:

Return Traversable child in self.
Equivalent to ``joinpath(child)``.

.. abstractmethod:: open(mode='r', *args, **kwargs)
.. method:: open(mode='r', *args, **kwargs)
:abstractmethod:

*mode* may be 'r' or 'rb' to open as text or binary. Return a handle
suitable for reading (same as :attr:`pathlib.Path.open`).
Expand Down Expand Up @@ -168,7 +178,8 @@
Loaders that wish to support resource reading are expected to
implement this interface.

.. abstractmethod:: files()
.. method:: files()
:abstractmethod:

Returns a :class:`importlib.resources.abc.Traversable` object for the loaded
package.
48 changes: 32 additions & 16 deletions Doc/library/importlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -390,7 +390,8 @@ ABC hierarchy::
This ABC is deprecated in favour of supporting resource loading
through :class:`importlib.resources.abc.TraversableResources`.

.. abstractmethod:: get_data(path)
.. method:: get_data(path)
:abstractmethod:

An abstract method to return the bytes for the data located at *path*.
Loaders that have a file-like storage back-end
Expand Down Expand Up @@ -427,7 +428,8 @@ ABC hierarchy::
.. versionchanged:: 3.4
No longer abstract and a concrete implementation is provided.

.. abstractmethod:: get_source(fullname)
.. method:: get_source(fullname)
:abstractmethod:

An abstract method to return the source of a module. It is returned as
a text string using :term:`universal newlines`, translating all
Expand Down Expand Up @@ -484,7 +486,8 @@ ABC hierarchy::
when implemented, helps a module to be executed as a script. The ABC
represents an optional :pep:`302` protocol.

.. abstractmethod:: get_filename(fullname)
.. method:: get_filename(fullname)
:abstractmethod:

An abstract method that is to return the value of
:attr:`~module.__file__` for the specified module. If no path is
Expand Down Expand Up @@ -524,11 +527,13 @@ ABC hierarchy::
.. deprecated-removed:: 3.4 3.15
Use :meth:`Loader.exec_module` instead.

.. abstractmethod:: get_filename(fullname)
.. method:: get_filename(fullname)
:abstractmethod:

Returns :attr:`path`.

.. abstractmethod:: get_data(path)
.. method:: get_data(path)
:abstractmethod:

Reads *path* as a binary file and returns the bytes from it.

Expand Down Expand Up @@ -664,27 +669,31 @@ ABC hierarchy::
.. deprecated-removed:: 3.12 3.14
Use :class:`importlib.resources.abc.TraversableResources` instead.

.. abstractmethod:: open_resource(resource)
.. method:: open_resource(resource)
:abstractmethod:

Returns an opened, :term:`file-like object` for binary reading
of the *resource*.

If the resource cannot be found, :exc:`FileNotFoundError` is
raised.

.. abstractmethod:: resource_path(resource)
.. method:: resource_path(resource)
:abstractmethod:

Returns the file system path to the *resource*.

If the resource does not concretely exist on the file system,
raise :exc:`FileNotFoundError`.

.. abstractmethod:: is_resource(name)
.. method:: is_resource(name)
:abstractmethod:

Returns ``True`` if the named *name* is considered a resource.
:exc:`FileNotFoundError` is raised if *name* does not exist.

.. abstractmethod:: contents()
.. method:: contents()
:abstractmethod:

Returns an :term:`iterable` of strings over the contents of
the package. Do note that it is not required that all names
Expand Down Expand Up @@ -720,27 +729,33 @@ ABC hierarchy::

Abstract. The base name of this object without any parent references.

.. abstractmethod:: iterdir()
.. method:: iterdir()
:abstractmethod:

Yield ``Traversable`` objects in ``self``.

.. abstractmethod:: is_dir()
.. method:: is_dir()
:abstractmethod:

Return ``True`` if ``self`` is a directory.

.. abstractmethod:: is_file()
.. method:: is_file()
:abstractmethod:

Return ``True`` if ``self`` is a file.

.. abstractmethod:: joinpath(child)
.. method:: joinpath(child)
:abstractmethod:

Return Traversable child in ``self``.

.. abstractmethod:: __truediv__(child)
.. method:: __truediv__(child)
:abstractmethod:

Return ``Traversable`` child in ``self``.

.. abstractmethod:: open(mode='r', *args, **kwargs)
.. method:: open(mode='r', *args, **kwargs)
:abstractmethod:

*mode* may be 'r' or 'rb' to open as text or binary. Return a handle
suitable for reading (same as :attr:`pathlib.Path.open`).
Expand Down Expand Up @@ -774,7 +789,8 @@ ABC hierarchy::
.. deprecated-removed:: 3.12 3.14
Use :class:`importlib.resources.abc.TraversableResources` instead.

.. abstractmethod:: files()
.. method:: files()
:abstractmethod:

Returns a :class:`importlib.resources.abc.Traversable` object for the loaded
package.
Expand Down
3 changes: 2 additions & 1 deletion Doc/library/numbers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ The numeric tower

Abstract. Retrieves the imaginary component of this number.

.. abstractmethod:: conjugate()
.. method:: conjugate()
:abstractmethod:

Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate()
== (1-3j)``.
Expand Down
3 changes: 2 additions & 1 deletion Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,8 @@ process and user.

.. versionadded:: 3.6

.. abstractmethod:: __fspath__()
.. method:: __fspath__()
:abstractmethod:

Return the file system path representation of the object.

Expand Down
12 changes: 8 additions & 4 deletions Doc/library/selectors.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,8 @@ constants below:
:class:`BaseSelector` and its concrete implementations support the
:term:`context manager` protocol.

.. abstractmethod:: register(fileobj, events, data=None)
.. method:: register(fileobj, events, data=None)
:abstractmethod:

Register a file object for selection, monitoring it for I/O events.

Expand All @@ -116,7 +117,8 @@ constants below:
:exc:`ValueError` in case of invalid event mask or file descriptor, or
:exc:`KeyError` if the file object is already registered.

.. abstractmethod:: unregister(fileobj)
.. method:: unregister(fileobj)
:abstractmethod:

Unregister a file object from selection, removing it from monitoring. A
file object shall be unregistered prior to being closed.
Expand All @@ -140,7 +142,8 @@ constants below:
:exc:`ValueError` in case of invalid event mask or file descriptor, or
:exc:`KeyError` if the file object is not registered.

.. abstractmethod:: select(timeout=None)
.. method:: select(timeout=None)
:abstractmethod:

Wait until some registered file objects become ready, or the timeout
expires.
Expand Down Expand Up @@ -183,7 +186,8 @@ constants below:
This returns the :class:`SelectorKey` instance associated to this file
object, or raises :exc:`KeyError` if the file object is not registered.

.. abstractmethod:: get_map()
.. method:: get_map()
:abstractmethod:

Return a mapping of file objects to selector keys.

Expand Down
14 changes: 0 additions & 14 deletions Doc/tools/extensions/pyspecific.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,19 +109,6 @@ def run(self):
return PyMethod.run(self)


class PyAbstractMethod(PyMethod):

def handle_signature(self, sig, signode):
ret = super(PyAbstractMethod, self).handle_signature(sig, signode)
signode.insert(0, addnodes.desc_annotation('abstractmethod ',
'abstractmethod '))
return ret

def run(self):
self.name = 'py:method'
return PyMethod.run(self)


# Support for building "topic help" for pydoc

pydoc_topic_labels = [
Expand Down Expand Up @@ -273,6 +260,5 @@ def setup(app):
app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod)
app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction)
app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
app.add_directive_to_domain('py', 'abstractmethod', PyAbstractMethod)
app.connect('env-check-consistency', patch_pairindextypes)
return {'version': '1.0', 'parallel_read_safe': True}
Loading