greg/cpython
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

GH-121970: Replace custom abstract method directive with the `:abstract:` option (#129311)

Browse Source
This commit is contained in:
Adam Turner
2025-02-22 01:53:57 +00:00
committed by GitHub
parent 8e96adf453
commit 30e892473e
6 changed files with 66 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
Doc/library/importlib.resources.abc.rst
View File

@@ -46,7 +46,8 @@
.. deprecated:: 3.12 .. deprecated:: 3.12
Use :class:`importlib.resources.abc.TraversableResources` instead. 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 Returns an opened, :term:`file-like object` for binary reading
of the *resource*. of the *resource*.
@@ -54,19 +55,22 @@
If the resource cannot be found, :exc:`FileNotFoundError` is If the resource cannot be found, :exc:`FileNotFoundError` is
raised. raised.
.. abstractmethod:: resource_path(resource) .. method:: resource_path(resource)
:abstractmethod:
Returns the file system path to the *resource*. Returns the file system path to the *resource*.
If the resource does not concretely exist on the file system, If the resource does not concretely exist on the file system,
raise :exc:`FileNotFoundError`. raise :exc:`FileNotFoundError`.
.. abstractmethod:: is_resource(name) .. method:: is_resource(name)
:abstractmethod:
Returns ``True`` if the named *name* is considered a resource. Returns ``True`` if the named *name* is considered a resource.
:exc:`FileNotFoundError` is raised if *name* does not exist. :exc:`FileNotFoundError` is raised if *name* does not exist.
.. abstractmethod:: contents() .. method:: contents()
:abstractmethod:
Returns an :term:`iterable` of strings over the contents of Returns an :term:`iterable` of strings over the contents of
the package. Do note that it is not required that all names the package. Do note that it is not required that all names
@@ -97,19 +101,23 @@
Abstract. The base name of this object without any parent references. Abstract. The base name of this object without any parent references.
.. abstractmethod:: iterdir() .. method:: iterdir()
:abstractmethod:
Yield Traversable objects in self. Yield Traversable objects in self.
.. abstractmethod:: is_dir() .. method:: is_dir()
:abstractmethod:
Return ``True`` if self is a directory. Return ``True`` if self is a directory.
.. abstractmethod:: is_file() .. method:: is_file()
:abstractmethod:
Return ``True`` if self is a file. Return ``True`` if self is a file.
.. abstractmethod:: joinpath(*pathsegments) .. method:: joinpath(*pathsegments)
:abstractmethod:
Traverse directories according to *pathsegments* and return Traverse directories according to *pathsegments* and return
the result as :class:`!Traversable`. the result as :class:`!Traversable`.
@@ -134,12 +142,14 @@
may contain forward slashes as path separators. may contain forward slashes as path separators.
Previously, only a single *child* argument was accepted. Previously, only a single *child* argument was accepted.
.. abstractmethod:: __truediv__(child) .. method:: __truediv__(child)
:abstractmethod:
Return Traversable child in self. Return Traversable child in self.
Equivalent to ``joinpath(child)``. 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 *mode* may be 'r' or 'rb' to open as text or binary. Return a handle
suitable for reading (same as :attr:`pathlib.Path.open`). suitable for reading (same as :attr:`pathlib.Path.open`).
@@ -168,7 +178,8 @@
Loaders that wish to support resource reading are expected to Loaders that wish to support resource reading are expected to
implement this interface. implement this interface.
.. abstractmethod:: files() .. method:: files()
:abstractmethod:
Returns a :class:`importlib.resources.abc.Traversable` object for the loaded Returns a :class:`importlib.resources.abc.Traversable` object for the loaded
package. package.

48
Doc/library/importlib.rst
View File

@@ -390,7 +390,8 @@ ABC hierarchy::
This ABC is deprecated in favour of supporting resource loading This ABC is deprecated in favour of supporting resource loading
through :class:`importlib.resources.abc.TraversableResources`. 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*. An abstract method to return the bytes for the data located at *path*.
Loaders that have a file-like storage back-end Loaders that have a file-like storage back-end
@@ -427,7 +428,8 @@ ABC hierarchy::
.. versionchanged:: 3.4 .. versionchanged:: 3.4
No longer abstract and a concrete implementation is provided. 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 An abstract method to return the source of a module. It is returned as
a text string using :term:`universal newlines`, translating all a text string using :term:`universal newlines`, translating all
@@ -484,7 +486,8 @@ ABC hierarchy::
when implemented, helps a module to be executed as a script. The ABC when implemented, helps a module to be executed as a script. The ABC
represents an optional :pep:`302` protocol. 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 An abstract method that is to return the value of
:attr:`~module.__file__` for the specified module. If no path is :attr:`~module.__file__` for the specified module. If no path is
@@ -524,11 +527,13 @@ ABC hierarchy::
.. deprecated-removed:: 3.4 3.15 .. deprecated-removed:: 3.4 3.15
Use :meth:`Loader.exec_module` instead. Use :meth:`Loader.exec_module` instead.
.. abstractmethod:: get_filename(fullname) .. method:: get_filename(fullname)
:abstractmethod:
Returns :attr:`path`. Returns :attr:`path`.
.. abstractmethod:: get_data(path) .. method:: get_data(path)
:abstractmethod:
Reads *path* as a binary file and returns the bytes from it. Reads *path* as a binary file and returns the bytes from it.
@@ -664,7 +669,8 @@ ABC hierarchy::
.. deprecated-removed:: 3.12 3.14 .. deprecated-removed:: 3.12 3.14
Use :class:`importlib.resources.abc.TraversableResources` instead. 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 Returns an opened, :term:`file-like object` for binary reading
of the *resource*. of the *resource*.
@@ -672,19 +678,22 @@ ABC hierarchy::
If the resource cannot be found, :exc:`FileNotFoundError` is If the resource cannot be found, :exc:`FileNotFoundError` is
raised. raised.
.. abstractmethod:: resource_path(resource) .. method:: resource_path(resource)
:abstractmethod:
Returns the file system path to the *resource*. Returns the file system path to the *resource*.
If the resource does not concretely exist on the file system, If the resource does not concretely exist on the file system,
raise :exc:`FileNotFoundError`. raise :exc:`FileNotFoundError`.
.. abstractmethod:: is_resource(name) .. method:: is_resource(name)
:abstractmethod:
Returns ``True`` if the named *name* is considered a resource. Returns ``True`` if the named *name* is considered a resource.
:exc:`FileNotFoundError` is raised if *name* does not exist. :exc:`FileNotFoundError` is raised if *name* does not exist.
.. abstractmethod:: contents() .. method:: contents()
:abstractmethod:
Returns an :term:`iterable` of strings over the contents of Returns an :term:`iterable` of strings over the contents of
the package. Do note that it is not required that all names the package. Do note that it is not required that all names
@@ -720,27 +729,33 @@ ABC hierarchy::
Abstract. The base name of this object without any parent references. Abstract. The base name of this object without any parent references.
.. abstractmethod:: iterdir() .. method:: iterdir()
:abstractmethod:
Yield ``Traversable`` objects in ``self``. Yield ``Traversable`` objects in ``self``.
.. abstractmethod:: is_dir() .. method:: is_dir()
:abstractmethod:
Return ``True`` if ``self`` is a directory. Return ``True`` if ``self`` is a directory.
.. abstractmethod:: is_file() .. method:: is_file()
:abstractmethod:
Return ``True`` if ``self`` is a file. Return ``True`` if ``self`` is a file.
.. abstractmethod:: joinpath(child) .. method:: joinpath(child)
:abstractmethod:
Return Traversable child in ``self``. Return Traversable child in ``self``.
.. abstractmethod:: __truediv__(child) .. method:: __truediv__(child)
:abstractmethod:
Return ``Traversable`` child in ``self``. 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 *mode* may be 'r' or 'rb' to open as text or binary. Return a handle
suitable for reading (same as :attr:`pathlib.Path.open`). suitable for reading (same as :attr:`pathlib.Path.open`).
@@ -774,7 +789,8 @@ ABC hierarchy::
.. deprecated-removed:: 3.12 3.14 .. deprecated-removed:: 3.12 3.14
Use :class:`importlib.resources.abc.TraversableResources` instead. Use :class:`importlib.resources.abc.TraversableResources` instead.
.. abstractmethod:: files() .. method:: files()
:abstractmethod:
Returns a :class:`importlib.resources.abc.Traversable` object for the loaded Returns a :class:`importlib.resources.abc.Traversable` object for the loaded
package. package.

3
Doc/library/numbers.rst
View File

@@ -38,7 +38,8 @@ The numeric tower
Abstract. Retrieves the imaginary component of this number. Abstract. Retrieves the imaginary component of this number.
.. abstractmethod:: conjugate() .. method:: conjugate()
:abstractmethod:
Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate() Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate()
== (1-3j)``. == (1-3j)``.

3
Doc/library/os.rst
View File

@@ -321,7 +321,8 @@ process and user.
.. versionadded:: 3.6 .. versionadded:: 3.6
.. abstractmethod:: __fspath__() .. method:: __fspath__()
:abstractmethod:
Return the file system path representation of the object. Return the file system path representation of the object.

12
Doc/library/selectors.rst
View File

@@ -103,7 +103,8 @@ constants below:
:class:`BaseSelector` and its concrete implementations support the :class:`BaseSelector` and its concrete implementations support the
:term:`context manager` protocol. :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. Register a file object for selection, monitoring it for I/O events.
@@ -116,7 +117,8 @@ constants below:
:exc:`ValueError` in case of invalid event mask or file descriptor, or :exc:`ValueError` in case of invalid event mask or file descriptor, or
:exc:`KeyError` if the file object is already registered. :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 Unregister a file object from selection, removing it from monitoring. A
file object shall be unregistered prior to being closed. file object shall be unregistered prior to being closed.
@@ -140,7 +142,8 @@ constants below:
:exc:`ValueError` in case of invalid event mask or file descriptor, or :exc:`ValueError` in case of invalid event mask or file descriptor, or
:exc:`KeyError` if the file object is not registered. :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 Wait until some registered file objects become ready, or the timeout
expires. expires.
@@ -183,7 +186,8 @@ constants below:
This returns the :class:`SelectorKey` instance associated to this file This returns the :class:`SelectorKey` instance associated to this file
object, or raises :exc:`KeyError` if the file object is not registered. 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. Return a mapping of file objects to selector keys.

14
Doc/tools/extensions/pyspecific.py
View File

@@ -103,19 +103,6 @@ class PyAwaitableMethod(PyAwaitableMixin, PyMethod):
return PyMethod.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 documenting Opcodes # Support for documenting Opcodes
opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s*\((.*)\))?') opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s*\((.*)\))?')
@@ -201,6 +188,5 @@ def setup(app):
app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod) app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod)
app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction) app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction)
app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod) app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
app.add_directive_to_domain('py', 'abstractmethod', PyAbstractMethod)
app.connect('env-check-consistency', patch_pairindextypes) app.connect('env-check-consistency', patch_pairindextypes)
return {'version': '1.0', 'parallel_read_safe': True} return {'version': '1.0', 'parallel_read_safe': True}