Skip to content

gh-148001: Expose shutil.ReadError and shutil.RegistryError #148004

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
WYSIATI wants to merge 3 commits into
base: main
Choose a base branch
from
+24 −1
Open

gh-148001: Expose shutil.ReadError and shutil.RegistryError #148004

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e1d5bb
gh-148001: Add shutil.ReadError and RegistryError to __all__ and docu…
Apr 2, 2026
e6d6cdb
Fix NEWS entry: use literal markup for shutil.__all__
Apr 2, 2026
d3f839d
Address review: move exceptions to Archiving operations section
Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions Doc/library/shutil.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,21 @@ Directory and files operations

.. versionadded:: 3.4

.. exception:: ReadError
Copy link
Copy Markdown
Member

@picnixz picnixz Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't make sense to document this under the file operations. This should be documented under the unpack_* section (i.e. "Archiving operations").

Copy link
Copy Markdown
Contributor Author

@WYSIATI WYSIATI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, I'll move this to the Archiving operations section near unpack_archive().


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`.
Copy link
Copy Markdown
Member

@picnixz picnixz Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be documented near the function that is raising it.

Copy link
Copy Markdown
Contributor Author

@WYSIATI WYSIATI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will move this near register_unpack_format() and add a note that it raises RegistryError


.. versionadded:: 3.2


.. function:: copymode(src, dst, *, follow_symlinks=True)

Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions Lib/shutil.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
3 changes: 2 additions & 1 deletion Lib/test/test_shutil.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
2 changes: 2 additions & 0 deletions Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Add :exc:`shutil.ReadError` and :exc:`shutil.RegistryError` to
``shutil.__all__`` and document them.
Copy link
Copy Markdown
Member

@picnixz picnixz Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Add :exc:`shutil.ReadError` and :exc:`shutil.RegistryError` to
``shutil.__all__`` and document them.
Publicly expose :exc:`shutil.ReadError` and :exc:`shutil.RegistryError`.

Copy link
Copy Markdown
Contributor Author

@WYSIATI WYSIATI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, updated

Loading