@@ -645,6 +645,160 @@ ABC hierarchy::
645645 itself does not end in ``__init__ ``.
646646
647647
648+ .. class :: ResourceReader
649+
650+ *Superseded by TraversableResources *
651+
652+ An :term: `abstract base class ` to provide the ability to read
653+ *resources *.
654+
655+ From the perspective of this ABC, a *resource * is a binary
656+ artifact that is shipped within a package. Typically this is
657+ something like a data file that lives next to the ``__init__.py ``
658+ file of the package. The purpose of this class is to help abstract
659+ out the accessing of such data files so that it does not matter if
660+ the package and its data file(s) are stored in a e.g. zip file
661+ versus on the file system.
662+
663+ For any of methods of this class, a *resource * argument is
664+ expected to be a :term: `path-like object ` which represents
665+ conceptually just a file name. This means that no subdirectory
666+ paths should be included in the *resource * argument. This is
667+ because the location of the package the reader is for, acts as the
668+ "directory". Hence the metaphor for directories and file
669+ names is packages and resources, respectively. This is also why
670+ instances of this class are expected to directly correlate to
671+ a specific package (instead of potentially representing multiple
672+ packages or a module).
673+
674+ Loaders that wish to support resource reading are expected to
675+ provide a method called ``get_resource_reader(fullname) `` which
676+ returns an object implementing this ABC's interface. If the module
677+ specified by fullname is not a package, this method should return
678+ :const: `None `. An object compatible with this ABC should only be
679+ returned when the specified module is a package.
680+
681+ .. versionadded :: 3.7
682+
683+ .. deprecated-removed :: 3.12 3.14
684+ Use :class: `importlib.resources.abc.TraversableResources ` instead.
685+
686+ .. abstractmethod :: open_resource(resource)
687+
688+ Returns an opened, :term: `file-like object ` for binary reading
689+ of the *resource *.
690+
691+ If the resource cannot be found, :exc: `FileNotFoundError ` is
692+ raised.
693+
694+ .. abstractmethod :: resource_path(resource)
695+
696+ Returns the file system path to the *resource *.
697+
698+ If the resource does not concretely exist on the file system,
699+ raise :exc: `FileNotFoundError `.
700+
701+ .. abstractmethod :: is_resource(name)
702+
703+ Returns ``True `` if the named *name * is considered a resource.
704+ :exc: `FileNotFoundError ` is raised if *name * does not exist.
705+
706+ .. abstractmethod :: contents()
707+
708+ Returns an :term: `iterable ` of strings over the contents of
709+ the package. Do note that it is not required that all names
710+ returned by the iterator be actual resources, e.g. it is
711+ acceptable to return names for which :meth: `is_resource ` would
712+ be false.
713+
714+ Allowing non-resource names to be returned is to allow for
715+ situations where how a package and its resources are stored
716+ are known a priori and the non-resource names would be useful.
717+ For instance, returning subdirectory names is allowed so that
718+ when it is known that the package and resources are stored on
719+ the file system then those subdirectory names can be used
720+ directly.
721+
722+ The abstract method returns an iterable of no items.
723+
724+
725+ .. class :: Traversable
726+
727+ An object with a subset of :class: `pathlib.Path ` methods suitable for
728+ traversing directories and opening files.
729+
730+ For a representation of the object on the file-system, use
731+ :meth: `importlib.resources.as_file `.
732+
733+ .. versionadded :: 3.9
734+
735+ .. deprecated-removed :: 3.12 3.14
736+ Use :class: `importlib.resources.abc.Traversable ` instead.
737+
738+ .. attribute :: name
739+
740+ Abstract. The base name of this object without any parent references.
741+
742+ .. abstractmethod :: iterdir()
743+
744+ Yield ``Traversable `` objects in ``self ``.
745+
746+ .. abstractmethod :: is_dir()
747+
748+ Return ``True `` if ``self `` is a directory.
749+
750+ .. abstractmethod :: is_file()
751+
752+ Return ``True `` if ``self `` is a file.
753+
754+ .. abstractmethod :: joinpath(child)
755+
756+ Return Traversable child in ``self ``.
757+
758+ .. abstractmethod :: __truediv__(child)
759+
760+ Return ``Traversable `` child in ``self ``.
761+
762+ .. abstractmethod :: open(mode='r', *args, **kwargs)
763+
764+ *mode * may be 'r' or 'rb' to open as text or binary. Return a handle
765+ suitable for reading (same as :attr: `pathlib.Path.open `).
766+
767+ When opening as text, accepts encoding parameters such as those
768+ accepted by :attr: `io.TextIOWrapper `.
769+
770+ .. method :: read_bytes()
771+
772+ Read contents of ``self `` as bytes.
773+
774+ .. method :: read_text(encoding=None)
775+
776+ Read contents of ``self `` as text.
777+
778+
779+ .. class :: TraversableResources
780+
781+ An abstract base class for resource readers capable of serving
782+ the :meth: `importlib.resources.files ` interface. Subclasses
783+ :class: `importlib.resources.abc.ResourceReader ` and provides
784+ concrete implementations of the :class: `importlib.resources.abc.ResourceReader `'s
785+ abstract methods. Therefore, any loader supplying
786+ :class: `importlib.abc.TraversableResources ` also supplies ResourceReader.
787+
788+ Loaders that wish to support resource reading are expected to
789+ implement this interface.
790+
791+ .. versionadded :: 3.9
792+
793+ .. deprecated-removed :: 3.12 3.14
794+ Use :class: `importlib.resources.abc.TraversableResources ` instead.
795+
796+ .. abstractmethod :: files()
797+
798+ Returns a :class: `importlib.resources.abc.Traversable ` object for the loaded
799+ package.
800+
801+
648802
649803:mod: `importlib.machinery ` -- Importers and path hooks
650804------------------------------------------------------
0 commit comments