Skip to content
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.

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

Improving the documentation #240

Closed
layday opened this issue Oct 22, 2021 · 7 comments
Closed

Improving the documentation #240

layday opened this issue Oct 22, 2021 · 7 comments
Labels
help wanted Extra attention is needed

Comments

@layday
Copy link

layday commented Oct 22, 2021

In importlib's documentation:

  • Explain what is meant for ResourceReader to be "superseded by" TraversableResources.
  • Document the TraversableResources interface (its files method).
  • Explain that TraversableResources is a concrete implementation of ResourceReader, where only files is abstract, not an abstract base class as stated.
  • Under the resources heading, demarcate the old (soon to be deprecated) API from the new API and discourage usage of the old API.
  • Document the Traversable interface. This is a particularly pernicious one because without documentation users do not know which attributes of a pathlib.Path object, which is what would be typically returned from files(), are safe to use, and which methods are safe to call, with which arguments.
@FFY00
Copy link
Member

FFY00 commented Oct 22, 2021

Explain what is meant for ResourceReader to be "superseded by" TraversableResources.

Perhaps it could be made clearer, but it is explained. TraversableResources takes your files() and implements ResourceReader. I am not sure how we would reword it, though.
Defining ResourceReader directly is superseded by using TraversableResources instead and just defining files(). You still get the ResourceReader implementation for compatibility, but you make available a files() API, which is a much better abstraction than what we had before.

Document the TraversableResources interface (its files method).

Yup. This was on my TODO list, I meant to do it earlier this week but it feel down.

python/cpython#29173

Explain that TraversableResources is a concrete implementation of ResourceReader, where only files is abstract, not an abstract base class as stated.

This goes into the first point, we could update the description to be clearer.

Under the resources heading, demarcate the old (soon to be deprecated) API from the new API and discourage usage of the old API.

Yup. I think the docs could use a touch-up. I was meaning to add an API reference section, which would clearly mark the legacy API as deprecated or slated for deprecation, whatever we end up doing. Ideally, the rest of the documentation would only reference this API in the migration sections. I am gonna wait for resolution on #80 to do this.

Document the Traversable interface. This is a particularly pernicious one because without documentation users do not know which attributes of a pathlib.Path object, which is what would be typically returned from files(), are safe to use, and which methods are safe to call, with which arguments.

python/cpython#29039
https://docs.python.org/3.11/library/importlib.html#importlib.abc.Traversable

@layday
Copy link
Author

layday commented Oct 22, 2021

python/cpython#29039

Not sure I understand why that can't be backported to 3.9 and 3.10 if the docs are maintained independently?

@layday
Copy link
Author

layday commented Oct 22, 2021

python/cpython#29039 has

    .. abstractmethod:: name()

       The base name of this object without any parent references.

but name is a property there.

@FFY00
Copy link
Member

FFY00 commented Oct 22, 2021

Agh!

@jaraco
Copy link
Member

jaraco commented Oct 31, 2021

I am gonna wait for resolution on #80 to do this.

I'd also wait on a call for python/cpython#29036 as that PR is the one that marks the functions as deprecated.

@jaraco
Copy link
Member

jaraco commented Oct 31, 2021

I realize it's a little awkward having issues in this repo and also bpo, especially for importlib.resources, whose code lives primarily here but whose docs are exclusively in CPython but where there's a separate set of docs for this project. For the future, please consider filing docs bugs for importlib.resources in bpo.

@jaraco
Copy link
Member

jaraco commented Jul 7, 2023

Since some work has been done and this issue seems to be languishing, I'm going to go ahead and close it. That said, I'd welcome anyone to re-invigorate the conversation or provide PRs to improve the situation.

@jaraco jaraco closed this as completed Jul 7, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

3 participants