Skip to content

bpo-44196: document that Traversable's methods should raise FileNotFoundError #26272

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

Closed
FFY00 wants to merge 1 commit into from
Closed

bpo-44196: document that Traversable's methods should raise FileNotFoundError #26272

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
67 changes: 64 additions & 3 deletions Doc/library/importlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -810,10 +810,71 @@ ABC hierarchy::

.. class:: Traversable

An object with a subset of pathlib.Path methods suitable for
traversing directories and opening files.
An object with a subset of pathlib.Path methods suitable for
traversing directories and opening files.

.. versionadded:: 3.9
.. versionadded:: 3.9

.. abstractmethod:: name()

@jaraco jaraco May 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I'm inclined to say let's not duplicate the docs from the code. Let's just link to the code if needed.


The base name of this object without any parent references.

.. abstractmethod:: iterdir()

Yield Traversable objects in self

.. abstractmethod:: is_dir()

Return True if self is a dir

If the directory/file cannot be found, :exc:`FileNotFoundError` should be raised,
although this is not guaranteed for compatibility reasons.

.. abstractmethod:: is_file()

Return True if self is a file

If the directory/file cannot be found, :exc:`FileNotFoundError` should be raised,
although this is not guaranteed for compatibility reasons.

.. abstractmethod:: joinpath(child)

Return Traversable child in self

If the file cannot be found, :exc:`FileNotFoundError` should be raised,
although this is not guaranteed for compatibility reasons.

.. abstractmethod:: __truediv__(child)

Return Traversable child in self

If the file cannot be found, :exc:`FileNotFoundError` should be raised,
although this is not guaranteed for compatibility reasons.

.. abstractmethod:: open(mode='r', *args, **kwargs)

*mode* may be 'r' or 'rb' to open as text or binary. Return a handle
suitable for reading (same as :attr:`pathlib.Path.open`).

When opening as text, accepts encoding parameters such as those
accepted by :attr:`io.TextIOWrapper`.

If the file cannot be found, :exc:`FileNotFoundError` should be raised,
although this is not guaranteed for compatibility reasons.

.. method:: read_bytes()

Read contents of self as bytes

If the file cannot be found, :exc:`FileNotFoundError` should be raised,
although this is not guaranteed for compatibility reasons.

.. method:: read_text(encoding=None)

Read contents of self as text

If the file cannot be found, :exc:`FileNotFoundError` should be raised,
although this is not guaranteed for compatibility reasons.


.. class:: TraversableReader
Expand Down
21 changes: 21 additions & 0 deletions Lib/importlib/abc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -367,13 +367,19 @@ def iterdir(self):
def read_bytes(self):
"""
Read contents of self as bytes

If the file cannot be found, FileNotFoundError should be raised,
although this is not guaranteed for compatibility reasons.
"""
with self.open('rb') as strm:
return strm.read()

def read_text(self, encoding=None):
"""
Read contents of self as text

If the file cannot be found, FileNotFoundError should be raised,
although this is not guaranteed for compatibility reasons.
Comment on lines +370 to +382

@jaraco jaraco May 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Since these implementations don't perform any specific checks on fileness, I'd leave out any documentation about what exceptions are raised and defer to the docs for open.

"""
with self.open(encoding=encoding) as strm:
return strm.read()
Expand All @@ -382,23 +388,35 @@ def read_text(self, encoding=None):
def is_dir(self) -> bool:
"""
Return True if self is a dir

If the directory/file cannot be found, FileNotFoundError should be raised,
Comment thread
FFY00 marked this conversation as resolved.
although this is not guaranteed for compatibility reasons.
"""

@abc.abstractmethod
def is_file(self) -> bool:
"""
Return True if self is a file

If the directory/file cannot be found, FileNotFoundError should be raised,
Comment thread
FFY00 marked this conversation as resolved.
although this is not guaranteed for compatibility reasons.
"""

@abc.abstractmethod
def joinpath(self, child):
"""
Return Traversable child in self

If the file cannot be found, FileNotFoundError should be raised,
Comment thread
FFY00 marked this conversation as resolved.
although this is not guaranteed for compatibility reasons.
"""

def __truediv__(self, child):
"""
Return Traversable child in self

If the file cannot be found, FileNotFoundError should be raised,
Comment thread
FFY00 marked this conversation as resolved.
although this is not guaranteed for compatibility reasons.
"""
return self.joinpath(child)

Expand All @@ -410,6 +428,9 @@ def open(self, mode='r', *args, **kwargs):

When opening as text, accepts encoding parameters such as those
accepted by io.TextIOWrapper.

If the file cannot be found, FileNotFoundError should be raised,

@jaraco jaraco May 23, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I'd probably change the terminology. The term "the file" could be more clear. Maybe something like "the object referenced by self".

Also, "open" may raise other exceptions. For example, if self references a directory and someone attempts to open it, they should expect "IsADirectoryError" to be raised. Or if the resource was on a network and the network has dropped, they might get a socket.ConnectionError. Or if it was an HTTP resource and access has been revoked, they may get an HTTPAccessDenied error. I'm not sure it's appropriate to attempt to prescribe which exceptions should or shouldn't be expected.

although this is not guaranteed for compatibility reasons.
"""

@abc.abstractproperty
Expand Down
2 changes: 2 additions & 0 deletions Misc/NEWS.d/next/Documentation/2021-05-20-21-04-34.bpo-44196.KAbNb8.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Document that importlib.abc.Traversable methods should raise
FileNotFoundError.