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