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

Author: AA-Turner

Doc/library/importlib.resources.abc.rst

@@ -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
@@ -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`.
@@ -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`).
@@ -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.

Doc/library/importlib.rst

@@ -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
@@ -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
@@ -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
@@ -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.
 
@@ -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
@@ -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`).
@@ -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.

Doc/library/numbers.rst

@@ -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)``.

Doc/library/os.rst

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

Doc/library/selectors.rst

@@ -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.
 
@@ -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.
@@ -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.
@@ -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.
 

Doc/tools/extensions/pyspecific.py

@@ -103,19 +103,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 documenting Opcodes
 
 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', '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}