@@ -484,7 +484,7 @@ ABC hierarchy::
484484 versus on the file system.
485485
486486 For any of methods of this class, a *resource * argument is
487- expected to be a :term: `file -like object
487+ expected to be a :term: `path -like object
488488 conceptually just a file name. This means that no subdirectory
489489 paths should be included in the *resource * argument. This is
490490 because the location of the package that the loader is for acts
@@ -775,6 +775,131 @@ ABC hierarchy::
775775 itself does not end in ``__init__ ``.
776776
777777
778+ :mod: `importlib.resources ` -- Resources
779+ ---------------------------------------
780+
781+ .. module :: importlib.resources
782+ :synopsis: Package resource reading, opening, and access
783+
784+ **Source code: ** :source: `Lib/importlib/resources.py `
785+
786+ --------------
787+
788+ .. versionadded :: 3.7
789+
790+ This module leverages Python's import system to provide access to *resources *
791+ within *packages *. If you can import a package, you can access resources
792+ within that package. Resources can be opened or read, in either binary or
793+ text mode.
794+
795+ Resources are roughly akin to files inside directories, though it's important
796+ to keep in mind that this is just a metaphor. Resources and packages **do
797+ not ** have to exist as physical files and directories on the file system.
798+
799+ Loaders can support resources by implementing the :class: `ResourceReader `
800+ abstract base class.
801+
802+ The following types are defined.
803+
804+ .. data :: Package
805+
806+ The ``Package `` type is defined as ``Union[str, ModuleType] ``. This means
807+ that where the function describes accepting a ``Package ``, you can pass in
808+ either a string or a module. Module objects must have a resolvable
809+ ``__spec__.submodule_search_locations `` that is not ``None ``.
810+
811+ .. data :: Resource
812+
813+ This type describes the resource names passed into the various functions
814+ in this package. This is defined as ``Union[str, os.PathLike] ``.
815+
816+
817+ The following functions are available.
818+
819+ .. function :: open_binary(package, resource)
820+
821+ Open for binary reading the *resource * within *package *.
822+
823+ *package * is either a name or a module object which conforms to the
824+ ``Package `` requirements. *resource * is the name of the resource to open
825+ within *package *; it may not contain path separators and it may not have
826+ sub-resources (i.e. it cannot be a directory). This function returns a
827+ ``typing.BinaryIO `` instance, a binary I/O stream open for reading.
828+
829+
830+ .. function :: open_text(package, resource, encoding='utf-8', errors='strict')
831+
832+ Open for text reading the *resource * within *package *. By default, the
833+ resource is opened for reading as UTF-8.
834+
835+ *package * is either a name or a module object which conforms to the
836+ ``Package `` requirements. *resource * is the name of the resource to open
837+ within *package *; it may not contain path separators and it may not have
838+ sub-resources (i.e. it cannot be a directory). *encoding * and *errors *
839+ have the same meaning as with built-in :func: `open `.
840+
841+ This function returns a ``typing.TextIO `` instance, a text I/O stream open
842+ for reading.
843+
844+
845+ .. function :: read_binary(package, resource)
846+
847+ Read and return the contents of the *resource * within *package * as
848+ ``bytes ``.
849+
850+ *package * is either a name or a module object which conforms to the
851+ ``Package `` requirements. *resource * is the name of the resource to open
852+ within *package *; it may not contain path separators and it may not have
853+ sub-resources (i.e. it cannot be a directory). This function returns the
854+ contents of the resource as :class: `bytes `.
855+
856+
857+ .. function :: read_text(package, resource, encoding='utf-8', errors='strict')
858+
859+ Read and return the contents of *resource * within *package * as a ``str ``.
860+ By default, the contents are read as strict UTF-8.
861+
862+ *package * is either a name or a module object which conforms to the
863+ ``Package `` requirements. *resource * is the name of the resource to open
864+ within *package *; it may not contain path separators and it may not have
865+ sub-resources (i.e. it cannot be a directory). *encoding * and *errors *
866+ have the same meaning as with built-in :func: `open `. This function
867+ returns the contents of the resource as :class: `str `.
868+
869+
870+ .. function :: path(package, resource)
871+
872+ Return the path to the *resource * as an actual file system path. This
873+ function returns a context manager for use in a :keyword: `with ` statement.
874+ The context manager provides a :class: `pathlib.Path ` object.
875+
876+ Exiting the context manager cleans up any temporary file created when the
877+ resource needs to be extracted from e.g. a zip file.
878+
879+ *package * is either a name or a module object which conforms to the
880+ ``Package `` requirements. *resource * is the name of the resource to open
881+ within *package *; it may not contain path separators and it may not have
882+ sub-resources (i.e. it cannot be a directory).
883+
884+
885+ .. function :: is_resource(package, name)
886+
887+ Return ``True `` if there is a resource named *name * in the package,
888+ otherwise ``False ``. Remember that directories are *not * resources!
889+ *package * is either a name or a module object which conforms to the
890+ ``Package `` requirements.
891+
892+
893+ .. function :: contents(package)
894+
895+ Return an iterator over the named items within the package. The iterator
896+ returns :class: `str ` resources (e.g. files) and non-resources
897+ (e.g. directories). The iterator does not recurse into subdirectories.
898+
899+ *package * is either a name or a module object which conforms to the
900+ ``Package `` requirements.
901+
902+
778903:mod: `importlib.machinery ` -- Importers and path hooks
779904------------------------------------------------------
780905
0 commit comments