Skip to content

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

Open
WYSIATI wants to merge 5 commits into
python:mainfrom
WYSIATI:shutil-missing-exceptions
Open

gh-148001: Expose shutil.ReadError and shutil.RegistryError#148004
WYSIATI wants to merge 5 commits into
python:mainfrom
WYSIATI:shutil-missing-exceptions

Conversation

@WYSIATI
Copy link
Copy Markdown
Contributor

@WYSIATI WYSIATI commented Apr 2, 2026 •
edited
Loading

ReadError and RegistryError were added in Python 3.2 but never included in shutil.__all__ or documented. Both are raised by public API functions (unpack_archive() and register_unpack_format()), so they should be discoverable and importable via wildcard import.

This PR adds them to __all__, documents them in shutil.rst, and updates the existing __all__ test.

@WYSIATI WYSIATI requested a review from giampaolo as a code owner April 2, 2026 10:23
@bedevere-app bedevere-app Bot mentioned this pull request Apr 2, 2026
Open
@WYSIATI WYSIATI force-pushed the shutil-missing-exceptions branch 2 times, most recently from 37e2888 to e6d6cdb Compare April 2, 2026 13:46
picnixz
picnixz requested changes Apr 2, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@picnixz picnixz left a comment

Choose a reason for hiding this comment

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

Please also indicate that register_* may raise.

Comment thread Doc/library/shutil.rst Outdated

.. 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().

Comment thread Misc/NEWS.d/next/Library/2026-04-02-10-05-49.gh-issue-148001.ShutilEx.rst Outdated
Comment on lines +1 to +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

Comment thread Doc/library/shutil.rst Outdated

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

@bedevere-app
Copy link
Copy Markdown

bedevere-app Bot commented Apr 2, 2026

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

@picnixz picnixz changed the title gh-148001: Add shutil.ReadError and RegistryError to __all__ and document them gh-148001: Expose shutil.ReadError and shutil.RegistryError Apr 2, 2026
@WYSIATI
Copy link
Copy Markdown
Contributor Author

WYSIATI commented Apr 3, 2026

Please also indicate that register_* may raise.

Will do — I'll add a note to register_unpack_format() and register_archive_format() docs indicating they raise RegistryError

@WYSIATI
Copy link
Copy Markdown
Contributor Author

WYSIATI commented Apr 3, 2026

I have made the requested changes; please review again

@bedevere-app
Copy link
Copy Markdown

bedevere-app Bot commented Apr 3, 2026

Thanks for making the requested changes!

@picnixz: please review the changes made to this pull request.

@bedevere-app bedevere-app Bot requested a review from picnixz April 3, 2026 03:58
picnixz
picnixz reviewed Apr 12, 2026
View reviewed changes
Comment thread Doc/library/shutil.rst Outdated
Comment thread Doc/library/shutil.rst Outdated
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 18, 2026

This PR is stale because it has been open for 30 days with no activity.

@github-actions github-actions Bot added the stale Stale PR or inactive for long period of time. label May 18, 2026
WYSIATI added 4 commits May 18, 2026 15:37
@WYSIATI
pythongh-148001: Add shutil.ReadError and RegistryError to __all__ an…
3712fc0 
…d 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.
@WYSIATI
Fix NEWS entry: use literal markup for shutil.__all__
f70d618 
Use ``shutil.__all__`` instead of :data:`shutil.__all__` to avoid
Sphinx ref.data warning.
@WYSIATI
Address review: move exceptions to Archiving operations section
54c85ce 
- Move ReadError docs near unpack_archive()
- Move RegistryError docs near register_unpack_format()
- Add note that register_unpack_format() raises RegistryError
- Simplify NEWS entry
@WYSIATI
Address review: collapse double spaces in exception docs
ecacc8c
@read-the-docs-community
Copy link
Copy Markdown

read-the-docs-community Bot commented May 18, 2026 •
edited
Loading

Documentation build overview

📚 cpython-previews | 🛠️ Build #32732388 | 📁 Comparing b4de572 against main (18281db)

  🔍 Preview build  

2 files changed
± library/shutil.html
± whatsnew/changelog.html

@WYSIATI WYSIATI force-pushed the shutil-missing-exceptions branch from e17f560 to ecacc8c Compare May 18, 2026 07:37
@WYSIATI
Copy link
Copy Markdown
Contributor Author

WYSIATI commented May 18, 2026

I have made the requested changes; please review again

@bedevere-app
Copy link
Copy Markdown

bedevere-app Bot commented May 18, 2026

Thanks for making the requested changes!

@picnixz: please review the changes made to this pull request.

@bedevere-app bedevere-app Bot requested a review from picnixz May 18, 2026 07:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@giampaolo giampaolo Awaiting requested review from giampaolo giampaolo is a code owner

@picnixz picnixz Awaiting requested review from picnixz

Assignees

No one assigned

Labels

awaiting change review stale Stale PR or inactive for long period of time.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@WYSIATI @picnixz