From e793c011dfdcbb3442ebc1324552e7b9621fa59b Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sat, 25 Nov 2023 22:18:22 +0200 Subject: [PATCH 1/9] Fix Sphinx warning in library/xml.rst Direct use of the pyexpat module is deprecated, but this is how to check the version for security purposes --- Doc/library/xml.rst | 2 +- Doc/tools/.nitignore | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/xml.rst b/Doc/library/xml.rst index 1e49b6568dfc28..909022ea4ba6a4 100644 --- a/Doc/library/xml.rst +++ b/Doc/library/xml.rst @@ -73,7 +73,7 @@ decompression bomb Safe Safe Safe 1. Expat 2.4.1 and newer is not vulnerable to the "billion laughs" and "quadratic blowup" vulnerabilities. Items still listed as vulnerable due to potential reliance on system-provided libraries. Check - :const:`pyexpat.EXPAT_VERSION`. + :const:`!pyexpat.EXPAT_VERSION`. 2. :mod:`xml.etree.ElementTree` doesn't expand external entities and raises a :exc:`~xml.etree.ElementTree.ParseError` when an entity occurs. 3. :mod:`xml.dom.minidom` doesn't expand external entities and simply returns diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index fbf4c1adfb14b8..b9eb062478953c 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -122,7 +122,6 @@ Doc/library/wsgiref.rst Doc/library/xml.dom.minidom.rst Doc/library/xml.dom.pulldom.rst Doc/library/xml.dom.rst -Doc/library/xml.rst Doc/library/xml.sax.handler.rst Doc/library/xml.sax.reader.rst Doc/library/xml.sax.rst From 7cd50ae4fcf695ff224fef79df07a4ed6fba9cc7 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sat, 25 Nov 2023 22:18:57 +0200 Subject: [PATCH 2/9] Fix Sphinx warning in library/importlib.resources.rst --- Doc/library/importlib.resources.rst | 4 ++-- Doc/tools/.nitignore | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 3de97e80311a17..1e2011cca3a6de 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -50,7 +50,7 @@ for example, a package and its resources can be imported from a zip file using ``get_resource_reader(fullname)`` method as specified by :class:`importlib.resources.abc.ResourceReader`. -.. data:: Anchor +.. class:: Anchor Represents an anchor for resources, either a :class:`module object ` or a module name as a string. Defined as @@ -63,7 +63,7 @@ for example, a package and its resources can be imported from a zip file using (think files). A Traversable may contain other containers (think subdirectories). - *anchor* is an optional :data:`Anchor`. If the anchor is a + *anchor* is an optional :class:`Anchor`. If the anchor is a package, resources are resolved from that package. If a module, resources are resolved adjacent to that module (in the same package or the package root). If the anchor is omitted, the caller's module diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index b9eb062478953c..d864f78697ce57 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -68,7 +68,6 @@ Doc/library/http.client.rst Doc/library/http.cookiejar.rst Doc/library/http.cookies.rst Doc/library/http.server.rst -Doc/library/importlib.resources.rst Doc/library/importlib.rst Doc/library/inspect.rst Doc/library/locale.rst From da6503d8e6f59676ca974fca8b5c6fb242b57497 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sat, 25 Nov 2023 22:21:15 +0200 Subject: [PATCH 3/9] Use italics for parameters --- Doc/library/importlib.resources.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 1e2011cca3a6de..fc9f6be91f1898 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -72,9 +72,9 @@ for example, a package and its resources can be imported from a zip file using .. versionadded:: 3.9 .. versionchanged:: 3.12 - "package" parameter was renamed to "anchor". "anchor" can now + *package* parameter was renamed to *anchor*. *anchor* can now be a non-package module and if omitted will default to the caller's - module. "package" is still accepted for compatibility but will raise + module. *package* is still accepted for compatibility but will raise a DeprecationWarning. Consider passing the anchor positionally or using ``importlib_resources >= 5.10`` for a compatible interface on older Pythons. @@ -96,4 +96,4 @@ for example, a package and its resources can be imported from a zip file using .. versionadded:: 3.9 .. versionchanged:: 3.12 - Added support for ``traversable`` representing a directory. + Added support for *traversable* representing a directory. From 8ab6552152f770fb7fc3f4a694096fa246f00776 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sat, 25 Nov 2023 22:21:29 +0200 Subject: [PATCH 4/9] Link to the exception --- Doc/library/importlib.resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index fc9f6be91f1898..a5adf0b8546dbf 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -75,7 +75,7 @@ for example, a package and its resources can be imported from a zip file using *package* parameter was renamed to *anchor*. *anchor* can now be a non-package module and if omitted will default to the caller's module. *package* is still accepted for compatibility but will raise - a DeprecationWarning. Consider passing the anchor positionally or + a :exc:`DeprecationWarning`. Consider passing the anchor positionally or using ``importlib_resources >= 5.10`` for a compatible interface on older Pythons. From d888ebf7adff31f9164ca3cbf932264a908afd25 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sat, 25 Nov 2023 22:26:04 +0200 Subject: [PATCH 5/9] Fix Sphinx warning in library/gzip.rst --- Doc/library/gzip.rst | 2 +- Doc/tools/.nitignore | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst index f931d0e399c9f2..50cde09fa10a9d 100644 --- a/Doc/library/gzip.rst +++ b/Doc/library/gzip.rst @@ -105,7 +105,7 @@ The module defines the following items: should only be provided in compression mode. If omitted or ``None``, the current time is used. See the :attr:`mtime` attribute for more details. - Calling a :class:`GzipFile` object's :meth:`close` method does not close + Calling a :class:`GzipFile` object's :meth:`!close` method does not close *fileobj*, since you might wish to append more material after the compressed data. This also allows you to pass an :class:`io.BytesIO` object opened for writing as *fileobj*, and retrieve the resulting memory buffer using the diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index d864f78697ce57..d6461118ff7ae6 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -63,7 +63,6 @@ Doc/library/ftplib.rst Doc/library/functions.rst Doc/library/functools.rst Doc/library/gettext.rst -Doc/library/gzip.rst Doc/library/http.client.rst Doc/library/http.cookiejar.rst Doc/library/http.cookies.rst From e0e1ad3d7126a40fa098ed010312384023c810f5 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sun, 26 Nov 2023 00:30:03 +0200 Subject: [PATCH 6/9] Document message and header defect base classes to fix Sphinx warning in library/email.headerregistry.rst --- Doc/library/email.errors.rst | 9 +++++++++ Doc/tools/.nitignore | 1 - 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/Doc/library/email.errors.rst b/Doc/library/email.errors.rst index 194a98696f437d..56aea6598b8615 100644 --- a/Doc/library/email.errors.rst +++ b/Doc/library/email.errors.rst @@ -58,6 +58,15 @@ The following exception classes are defined in the :mod:`email.errors` module: :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g. :class:`~email.mime.image.MIMEImage`). +.. exception:: MessageDefect() + + This is the base class for all defects found when parsing email messages. + It is derived from :exc:`ValueError`. + +.. exception:: HeaderDefect() + + This is the base class for all defects found when parsing email headers. + It is derived from :exc:`MessageDefect`. Here is the list of the defects that the :class:`~email.parser.FeedParser` can find while parsing messages. Note that the defects are added to the message diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index d6461118ff7ae6..9fff7b0a6dfe6f 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -51,7 +51,6 @@ Doc/library/decimal.rst Doc/library/email.charset.rst Doc/library/email.compat32-message.rst Doc/library/email.errors.rst -Doc/library/email.headerregistry.rst Doc/library/email.mime.rst Doc/library/email.parser.rst Doc/library/email.policy.rst From add95f39d067fcdcc6930d257dcd62f92d255b8a Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sun, 26 Nov 2023 00:45:53 +0200 Subject: [PATCH 7/9] Restore feed_eof() doc to fix Sphinx warning in library/asyncio-stream.rst --- Doc/library/asyncio-stream.rst | 4 ++++ Doc/tools/.nitignore | 1 - 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index d8186b6ce75c79..0736e783bbc8c8 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -204,6 +204,10 @@ StreamReader directly; use :func:`open_connection` and :func:`start_server` instead. + .. method:: feed_eof() + + Acknowledge the EOF. + .. coroutinemethod:: read(n=-1) Read up to *n* bytes from the stream. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 9fff7b0a6dfe6f..40e9a49432de97 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -32,7 +32,6 @@ Doc/library/abc.rst Doc/library/ast.rst Doc/library/asyncio-extending.rst Doc/library/asyncio-policy.rst -Doc/library/asyncio-stream.rst Doc/library/asyncio-subprocess.rst Doc/library/asyncio-task.rst Doc/library/bdb.rst From 8dc76b8acd927f0bfa50631641d5f70917a65768 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sun, 26 Nov 2023 00:52:30 +0200 Subject: [PATCH 8/9] Fix Sphinx warning in extending/newtypes.rst --- Doc/extending/newtypes.rst | 2 +- Doc/tools/.nitignore | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index 9f166eb8a4c3ff..7a92b3257c6cd3 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -296,7 +296,7 @@ An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table descriptors that are used at runtime is that any attribute defined this way can have an associated doc string simply by providing the text in the table. An application can use the introspection API to retrieve the descriptor from the -class object, and get the doc string using its :attr:`__doc__` attribute. +class object, and get the doc string using its :attr:`!__doc__` attribute. As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value of ``NULL`` is required. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 40e9a49432de97..c796c849347b56 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -21,7 +21,6 @@ Doc/c-api/sys.rst Doc/c-api/type.rst Doc/c-api/typeobj.rst Doc/extending/extending.rst -Doc/extending/newtypes.rst Doc/glossary.rst Doc/howto/descriptor.rst Doc/howto/enum.rst From 6ba4afd0d0e3945d86851d7a29333546ba07b898 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Sun, 26 Nov 2023 01:06:11 +0200 Subject: [PATCH 9/9] Fix Sphinx warning in c-api/set.rst On stdtypes.rst, set and frozenset are documented together and the frozenset has the working refs --- Doc/c-api/set.rst | 2 +- Doc/tools/.nitignore | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index 09c0fb6b9c5f23..cba823aa027bd6 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -147,7 +147,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes. Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a - :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard` + :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~frozenset.discard` method, this function does not automatically convert unhashable sets into temporary frozensets. Raise :exc:`SystemError` if *set* is not an instance of :class:`set` or its subtype. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index c796c849347b56..1e3e367460147a 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -14,7 +14,6 @@ Doc/c-api/memory.rst Doc/c-api/memoryview.rst Doc/c-api/module.rst Doc/c-api/object.rst -Doc/c-api/set.rst Doc/c-api/stable.rst Doc/c-api/structures.rst Doc/c-api/sys.rst