From 5e1d5bb0e0914eced26fc185cb734581fe76e77c Mon Sep 17 00:00:00 2001 From: Chester Li Date: Thu, 2 Apr 2026 18:23:05 +0800 Subject: [PATCH 1/3] gh-148001: Add shutil.ReadError and RegistryError to __all__ and document them Both exceptions are raised by public API functions (unpack_archive() and register_unpack_format()) but were never included in __all__ when they were introduced in Python 3.2. --- Doc/library/shutil.rst | 17 +++++++++++++++++ Lib/shutil.py | 1 + Lib/test/test_shutil.py | 3 ++- ...-04-02-10-05-49.gh-issue-148001.ShutilEx.rst | 2 ++ 4 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index d289ba58c24065..f8f3f5c23ffda9 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -101,6 +101,21 @@ Directory and files operations .. versionadded:: 3.4 +.. exception:: ReadError + + This exception is raised when an archive cannot be read or is not recognized + as a supported archive format. It is raised by :func:`unpack_archive`. + + .. versionadded:: 3.2 + +.. exception:: RegistryError + + This exception is raised when a registry operation with the archiving + and unpacking registries fails, such as registering a duplicate archive + format extension. It is raised by :func:`register_unpack_format`. + + .. versionadded:: 3.2 + .. function:: copymode(src, dst, *, follow_symlinks=True) @@ -737,6 +752,8 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. registered for that extension. In case none is found, a :exc:`ValueError` is raised. + If the archive file cannot be read, a :exc:`ReadError` is raised. + The keyword-only *filter* argument is passed to the underlying unpacking function. For zip files, *filter* is not accepted. For tar files, it is recommended to use ``'data'`` (default since Python diff --git a/Lib/shutil.py b/Lib/shutil.py index 44ccdbb503d4fb..c7c64e6653f8f3 100644 --- a/Lib/shutil.py +++ b/Lib/shutil.py @@ -64,6 +64,7 @@ __all__ = ["copyfileobj", "copyfile", "copymode", "copystat", "copy", "copy2", "copytree", "move", "rmtree", "Error", "SpecialFileError", + "ReadError", "RegistryError", "make_archive", "get_archive_formats", "register_archive_format", "unregister_archive_format", "get_unpack_formats", "register_unpack_format", diff --git a/Lib/test/test_shutil.py b/Lib/test/test_shutil.py index a4bd113bc7f1fc..0e2e18f9602a4f 100644 --- a/Lib/test/test_shutil.py +++ b/Lib/test/test_shutil.py @@ -3508,7 +3508,8 @@ def test_module_all_attribute(self): self.assertHasAttr(shutil, '__all__') target_api = ['copyfileobj', 'copyfile', 'copymode', 'copystat', 'copy', 'copy2', 'copytree', 'move', 'rmtree', 'Error', - 'SpecialFileError', 'make_archive', + 'SpecialFileError', 'ReadError', 'RegistryError', + 'make_archive', 'get_archive_formats', 'register_archive_format', 'unregister_archive_format', 'get_unpack_formats', 'register_unpack_format', 'unregister_unpack_format', diff --git a/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst b/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst new file mode 100644 index 00000000000000..02e61ea6002274 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst @@ -0,0 +1,2 @@ +Add :exc:`shutil.ReadError` and :exc:`shutil.RegistryError` to +:data:`shutil.__all__` and document them. From e6d6cdb9dd78eec3d814809b4c4f8a3010ed2f7d Mon Sep 17 00:00:00 2001 From: Chester Li Date: Thu, 2 Apr 2026 18:27:58 +0800 Subject: [PATCH 2/3] Fix NEWS entry: use literal markup for shutil.__all__ Use ``shutil.__all__`` instead of :data:`shutil.__all__` to avoid Sphinx ref.data warning. --- .../Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst b/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst index 02e61ea6002274..f4487eee0176c8 100644 --- a/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst +++ b/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst @@ -1,2 +1,2 @@ Add :exc:`shutil.ReadError` and :exc:`shutil.RegistryError` to -:data:`shutil.__all__` and document them. +``shutil.__all__`` and document them. From d3f839df54fad509474232cef33543c3c0039f5f Mon Sep 17 00:00:00 2001 From: Chester Li Date: Fri, 3 Apr 2026 11:30:31 +0800 Subject: [PATCH 3/3] Address review: move exceptions to Archiving operations section - Move ReadError docs near unpack_archive() - Move RegistryError docs near register_unpack_format() - Add note that register_unpack_format() raises RegistryError - Simplify NEWS entry --- Doc/library/shutil.rst | 33 ++++++++++--------- ...4-02-10-05-49.gh-issue-148001.ShutilEx.rst | 3 +- 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index f8f3f5c23ffda9..ec4d1be265ab4b 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -101,21 +101,6 @@ Directory and files operations .. versionadded:: 3.4 -.. exception:: ReadError - - This exception is raised when an archive cannot be read or is not recognized - as a supported archive format. It is raised by :func:`unpack_archive`. - - .. versionadded:: 3.2 - -.. exception:: RegistryError - - This exception is raised when a registry operation with the archiving - and unpacking registries fails, such as registering a duplicate archive - format extension. It is raised by :func:`register_unpack_format`. - - .. versionadded:: 3.2 - .. function:: copymode(src, dst, *, follow_symlinks=True) @@ -781,6 +766,13 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. .. versionchanged:: 3.12 Added the *filter* argument. +.. exception:: ReadError + + This exception is raised when an archive cannot be read or is not recognized + as a supported archive format. It is raised by :func:`unpack_archive`. + + .. versionadded:: 3.2 + .. function:: register_unpack_format(name, extensions, function[, extra_args[, description]]) Registers an unpack format. *name* is the name of the format and @@ -800,6 +792,17 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. *description* can be provided to describe the format, and will be returned by the :func:`get_unpack_formats` function. + Raises :exc:`RegistryError` if any of the given *extensions* are already + registered for another format. + +.. exception:: RegistryError + + This exception is raised when a registry operation with the archiving + and unpacking registries fails, such as registering a duplicate archive + format extension. It is raised by :func:`register_unpack_format`. + + .. versionadded:: 3.2 + .. function:: unregister_unpack_format(name) diff --git a/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst b/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst index f4487eee0176c8..28057f6e8ce297 100644 --- a/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst +++ b/Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst @@ -1,2 +1 @@ -Add :exc:`shutil.ReadError` and :exc:`shutil.RegistryError` to -``shutil.__all__`` and document them. +Publicly expose :exc:`shutil.ReadError` and :exc:`shutil.RegistryError`.