bpo-32248: Implement importlib.abc.ResourceReader #4892
Conversation
Doc/library/importlib.rst
Outdated
| .. class:: ResourceReader | ||
|
|
||
| An :term:`abstract base class` for :term:`loaders <loader>` | ||
| representing a :term:`package` to provide the ability to read |
There was a problem hiding this comment.
This reads a bit awkwardly for me. What about "An abstract base class for package loaders which provide the ability to read resources"?
Doc/library/importlib.rst
Outdated
|
|
||
| From the perspective of this class, a *resource* is a binary | ||
| artifact that is shipped within the package that this loader | ||
| represents. Typically this is something like a data file that |
There was a problem hiding this comment.
That's another awkward turn of a similar phrase. "package that this loader represents" seems weird to me ;)
Doc/library/importlib.rst
Outdated
| representing a :term:`package` to provide the ability to read | ||
| *resources*. | ||
|
|
||
| From the perspective of this class, a *resource* is a binary |
There was a problem hiding this comment.
Should it say "from the perspective of this ABC"?
Doc/library/importlib.rst
Outdated
| If the resource does not concretely exist on the file system, | ||
| raise :exc:`FileNotFoundError`. | ||
|
|
||
| .. abstractmethod:: is_resource(path) |
There was a problem hiding this comment.
In the standalone package I called this name so that it doesn't necessarily imply a path (which could include slashes).
Doc/library/importlib.rst
Outdated
| .. abstractmethod:: contents() | ||
|
|
||
| Returns an :term:`iterator` of strings over the contents of | ||
| the package. Due note that it is not required that all names |
|
|
||
| class ResourceReaderDefaultsTests(ABCTestHarness): | ||
|
|
||
| SPLIT = make_abc_subclasses(ResourceReader) |
There was a problem hiding this comment.
Is SPLIT required by ABCTestHarness? It seems an odd choice of terms.
There was a problem hiding this comment.
Yes and I didn't name it.
|
When you're done making the requested changes, leave the comment: |
|
I didn't expect the Spanish Inquisition! |
|
Nobody expects the Spanish Inquisition! @warsaw: please review the changes made to this pull request. |
|
LGTM, thanks @brettcannon ! If you close the bug, can you open a new one for the implementation? I'm also cool with keeping the original bug open for the ABC implementation branch. 'Sup to you! |
|
I say just keep the issue open. We can just expand on the NEWS entry as necessary. |
| versus on the file system. | ||
|
|
||
| For any of methods of this class, a *resource* argument is | ||
| expected to be a :term:`file-like object` which represents |
There was a problem hiding this comment.
So open_resource takes a file object and returns a file object? I may be misunderstanding here...
There was a problem hiding this comment.
I think that term should say that a resource is a path-like object. I'll fix that in my follow up branch.
| Returns the file system path to the *resource*. | ||
|
|
||
| If the resource does not concretely exist on the file system, | ||
| raise :exc:`FileNotFoundError`. |
There was a problem hiding this comment.
Hmm... is the same error returned when the given resource doesn't exist, or when the given resource exists but underlying storage is not a regular directory (e.g. a zip file)?
There was a problem hiding this comment.
Yes. In either case, importlib.resources will know what to do with that (e.g. extract it to a temporary file in the case where it exists in the loader's view of the world, but not on the physical file system).
| .. abstractmethod:: is_resource(name) | ||
|
|
||
| Returns ``True`` if the named *name* is considered a resource. | ||
| :exc:`FileNotFoundError` is raised if *name* does not exist. |
There was a problem hiding this comment.
...it isn't. :) Do you think we need to clarify that?
There was a problem hiding this comment.
if it was me I would actually have the method return False instead of an exception if name does not exist. That is how I do it in my own python code. At least I would think getters and setters and checks like this that returns bools should have an no throw garentee.
https://bugs.python.org/issue32248