Document the fact that `shutil.Error` is a subclass of `OSError`

[ShaiAvr]

Documentation

When I looked at the docs of the shutil module, I noticed that it doesn't mention that shutil.Error is a subclass of OSError. running shutil.Error.mro() reveals that indeed shutil.Error subclasses OSError and it can also be seen in the code. I think it would be nice to document this fact, so I know that if I do multiple operations which could raise other subclasses of OSError like shutil.copy, then I can use:

try:
    ... # Use shutil.copytree which raises shutil.Error and/or shutil.copy/shutil.copy2 which raises OSError
except OSError as e:
    ... # Handle any error that occured.

instead of:

try:
    ...
except (OSError, shutil.Error) as e:  # The docs don't mention that shutil.Error and OSError are related, so I need to catch both of them
    ...

If it's intentionally not documented since it's an implementation detail, then I still think the docs should mention that and say that it could change, and users shouldn't rely on shutil.Error being a subclass of OSError.

Linked PRs

• gh-141045: Document that shutil.Error is a subclass of OSError #141152

[Lakshya-Upadhyaya]

Hello! I'm interested in contributing to this. I can add documentation to indicate that shutil.Error inherits from OSError in Doc/library/shutil.rst.

Should I:

1. Add a note to the exception description indicating that it inherit from OSError, or
2. Add an example that shows catching OSError handles catching shutil.Error?

Once we determine the approach, I'm happy to do a PR!

[StanFromIreland]

Add an example that shows catching OSError handles catching shutil.Error?

This is overkill for the docs of an exception IMO. See what was done for http.cookiejar.LoadError.

[Lakshya-Upadhyaya]

Thank you for the advice!
I looked at how http.cookiejar.LoadError is documented and I'll reference that.
More precisely, I would add a brief note under the shutil.Error exception description with the text:
"Error is a subclass of OSError."
No examples, just consistency in documentation style.
Let me know if that is consistent with your expectation of my contributions prior to opening a PR.

[StanFromIreland]

SGTM