diff --git a/Doc/library/importlib.resources.abc.rst b/Doc/library/importlib.resources.abc.rst index 4085bdf6598d98..7a77466bcbaf27 100644 --- a/Doc/library/importlib.resources.abc.rst +++ b/Doc/library/importlib.resources.abc.rst @@ -46,7 +46,8 @@ .. 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*. @@ -54,19 +55,22 @@ 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. diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index b935fc0e42a4bd..3830dc1a64b536 100644 --- a/Doc/library/importlib.rst +++ b/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:: 3.4 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,7 +669,8 @@ 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*. @@ -672,19 +678,22 @@ ABC hierarchy:: 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. diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst index d0ae79c7a3df76..681d0b76f2a14b 100644 --- a/Doc/library/numbers.rst +++ b/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)``. diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 2445b008eb5a75..156d1458e8637f 100644 --- a/Doc/library/os.rst +++ b/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. diff --git a/Doc/library/selectors.rst b/Doc/library/selectors.rst index de8c3ef0ea2275..ee556f1f3cecae 100644 --- a/Doc/library/selectors.rst +++ b/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. diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index f363dfd4216929..638c5a9c5820d2 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -128,19 +128,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 including Misc/NEWS issue_re = re.compile('(?:[Ii]ssue #|bpo-)([0-9]+)', re.I) @@ -267,7 +254,7 @@ 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.add_directive('miscnews', MiscNews) app.connect('env-check-consistency', patch_pairindextypes) return {'version': '1.0', 'parallel_read_safe': True}