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.
In
importlib's documentation:ResourceReaderto be "superseded by"TraversableResources.TraversableResourcesinterface (itsfilesmethod).TraversableResourcesis a concrete implementation ofResourceReader, where onlyfilesis abstract, not an abstract base class as stated.resourcesheading, demarcate the old (soon to be deprecated) API from the new API and discourage usage of the old API.Traversableinterface. This is a particularly pernicious one because without documentation users do not know which attributes of apathlib.Pathobject, which is what would be typically returned fromfiles(), are safe to use, and which methods are safe to call, with which arguments.