python / python/cpython

Publicly expose `shutil.ReadError` and `shutil.RegistryError`

Open
#148,001 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

stdlib type-feature
Dominant language
Python
Stars
77.2k
Forks
35.9k
PR merge metrics
PR metrics pending

Description

Bug report
Bug description

shutil.ReadError and shutil.RegistryError are not included in shutil.__all__, making them inaccessible via wildcard import. Both exceptions are actively raised by public API functions:

  • ReadError is raised by unpack_archive()
  • RegistryError is raised by register_unpack_format()

The other shutil exceptions (Error, SameFileError, SpecialFileError) are all in __all__.

>>> from shutil import *
>>> try:
...     unpack_archive("nonexistent.zip")
... except ReadError:
...     pass
...
NameError: name 'ReadError' is not defined. Did you mean: 'KeyError'?
Impact
  • from shutil import * does not export ReadError or RegistryError, so users cannot catch exceptions raised by unpack_archive() or register_unpack_format() without explicitly importing them by name.
  • Neither exception is documented in Doc/library/shutil.rst, while the other three shutil exceptions (Error, SameFileError, SpecialFileError) all have dedicated .. exception:: entries.
  • Tools that rely on __all__ for API discovery (linters, IDE autocompletion, documentation generators) will not surface these exceptions.

This was introduced in commit 6ac91723bd7 (bpo-8295, 2010) which added the archive functions and exceptions but did not add ReadError or RegistryError to __all__. A later fix for incomplete __all__ (#66855, 2014) added SameFileError but missed these two.

Verified on Python 3.14.3 in a clean venv.

Proposed fix

Add "ReadError" and "RegistryError" to __all__ in Lib/shutil.py, and add .. exception:: entries in Doc/library/shutil.rst to document them alongside the other exceptions.

CPython versions tested on:

3.14

Operating system:

All

Linked PRs
  • gh-148004

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Inspect all in Lib/shutil.py and the exception entries in Doc/library/shutil.rst, then review linked PR gh-148004 before starting. Verify that both exceptions are exposed by wildcard import and documented alongside the other shutil exceptions.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.