This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Document that's methods should raise FileNotFoundError
Type: Stage: resolved
Components: Documentation Versions: Python 3.10
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: FFY00, brett.cannon, docs@python, jaraco
Priority: normal Keywords: patch

Created on 2021-05-20 19:42 by FFY00, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 26272 closed FFY00, 2021-05-20 20:06
Messages (5)
msg394055 - (view) Author: Filipe Laíns (FFY00) * (Python triager) Date: 2021-05-20 19:42
ResourceReader used to have this requirement, Traversable does not. We cannot add a requirement as there might be users not doing this, but we can ask new users to do so.

We should document that FileNotFoundError should be raised if a file is not found, but that it is not guaranteed that it will for all Traversable implementations for compatibility reasons.
msg394198 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-05-23 13:41
After reviewing the PR, I'm not convinced the Traversable methods need any specification about when to raise FileNotFoundError (or other exceptions). Let's flesh out what conditions demand prescribed interfaces.
msg394205 - (view) Author: Filipe Laíns (FFY00) * (Python triager) Date: 2021-05-23 16:04

Having a better look at it, I think we should only add this specification to open().

Traversable, by design, makes it totally plausible that open() cannot be performed. It could be a nonexistent path, the Traversable could represent object where open() does not make sense given the underlying implementation (it's something that cannot be read), etc.

If Traversable makes it possible for open() to not work, it should give us a mechanism to handle such situations.
If the only thing I know about an object is that it implements Traversable, how can I use open() in a reliable manner without having my code explode?

This mechanism does not need to be FileNotFoundError. But, in my opinion, it is what probably makes the most sense in this case. Please let me know if you have a different/better idea.
msg394209 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-05-23 17:18
Having a look at the `open` function (, it does not define which exceptions might be thrown. Similarly for ( and (

And since the canonical implementation of a Traversable resource is those two Path classes, it seems infeasible for the protocol to enforce a specific constraint on the available exceptions.

I think the best this protocol can do is advertise that the underlying implementation may raise an Exception if the target indicated by self cannot be opened (allowing for an Exception where appropriate), but in my opinion, that's the default interface for any protocol (or function) unless otherwise specified.

I don't want to explicitly call out FileNotFoundError or IsADirectoryError because those exceptions happen to be the most common. Consider for example the case where permission is not granted for read:

$ pathlib.Path('./foo').open()
PermissionError: [Errno 13] Permission denied: 'foo'

That's yet another case where might raise something other than FileNotFoundError.

In my opinion, unless the Traversable objects are expected to handle or transform exceptions, it's fine to simply delegate to the underlying implementations and allow any exceptions to bubble through.
msg394210 - (view) Author: Filipe Laíns (FFY00) * (Python triager) Date: 2021-05-23 17:26
That makes sense, I wish all these details were documented, but it is more than enough precedent to choose to not add such enforcements to the specification.
Date User Action Args
2022-04-11 14:59:45adminsetgithub: 88362
2021-05-23 17:26:13FFY00setstatus: open -> closed
resolution: rejected
messages: + msg394210

stage: patch review -> resolved
2021-05-23 17:18:47jaracosetmessages: + msg394209
2021-05-23 16:04:27FFY00setmessages: + msg394205
2021-05-23 13:41:49jaracosetmessages: + msg394198
2021-05-20 20:06:31FFY00setkeywords: + patch
stage: patch review
pull_requests: + pull_request24878
2021-05-20 19:42:10FFY00create