mirror of https://github.com/python/cpython
443 lines
14 KiB
Python
443 lines
14 KiB
Python
"""Abstract base classes related to import."""
|
|
from . import _bootstrap_external
|
|
from . import machinery
|
|
try:
|
|
import _frozen_importlib
|
|
except ImportError as exc:
|
|
if exc.name != '_frozen_importlib':
|
|
raise
|
|
_frozen_importlib = None
|
|
try:
|
|
import _frozen_importlib_external
|
|
except ImportError:
|
|
_frozen_importlib_external = _bootstrap_external
|
|
from ._abc import Loader
|
|
import abc
|
|
import warnings
|
|
from typing import BinaryIO, Iterable, Text
|
|
from typing import Protocol, runtime_checkable
|
|
|
|
|
|
def _register(abstract_cls, *classes):
|
|
for cls in classes:
|
|
abstract_cls.register(cls)
|
|
if _frozen_importlib is not None:
|
|
try:
|
|
frozen_cls = getattr(_frozen_importlib, cls.__name__)
|
|
except AttributeError:
|
|
frozen_cls = getattr(_frozen_importlib_external, cls.__name__)
|
|
abstract_cls.register(frozen_cls)
|
|
|
|
|
|
class Finder(metaclass=abc.ABCMeta):
|
|
|
|
"""Legacy abstract base class for import finders.
|
|
|
|
It may be subclassed for compatibility with legacy third party
|
|
reimplementations of the import system. Otherwise, finder
|
|
implementations should derive from the more specific MetaPathFinder
|
|
or PathEntryFinder ABCs.
|
|
|
|
Deprecated since Python 3.3
|
|
"""
|
|
|
|
def __init__(self):
|
|
warnings.warn("the Finder ABC is deprecated and "
|
|
"slated for removal in Python 3.12; use MetaPathFinder "
|
|
"or PathEntryFinder instead",
|
|
DeprecationWarning)
|
|
|
|
@abc.abstractmethod
|
|
def find_module(self, fullname, path=None):
|
|
"""An abstract method that should find a module.
|
|
The fullname is a str and the optional path is a str or None.
|
|
Returns a Loader object or None.
|
|
"""
|
|
warnings.warn("importlib.abc.Finder along with its find_module() "
|
|
"method are deprecated and "
|
|
"slated for removal in Python 3.12; use "
|
|
"MetaPathFinder.find_spec() or "
|
|
"PathEntryFinder.find_spec() instead",
|
|
DeprecationWarning)
|
|
|
|
|
|
class MetaPathFinder(metaclass=abc.ABCMeta):
|
|
|
|
"""Abstract base class for import finders on sys.meta_path."""
|
|
|
|
# We don't define find_spec() here since that would break
|
|
# hasattr checks we do to support backward compatibility.
|
|
|
|
def find_module(self, fullname, path):
|
|
"""Return a loader for the module.
|
|
|
|
If no module is found, return None. The fullname is a str and
|
|
the path is a list of strings or None.
|
|
|
|
This method is deprecated since Python 3.4 in favor of
|
|
finder.find_spec(). If find_spec() exists then backwards-compatible
|
|
functionality is provided for this method.
|
|
|
|
"""
|
|
warnings.warn("MetaPathFinder.find_module() is deprecated since Python "
|
|
"3.4 in favor of MetaPathFinder.find_spec() and is "
|
|
"slated for removal in Python 3.12",
|
|
DeprecationWarning,
|
|
stacklevel=2)
|
|
if not hasattr(self, 'find_spec'):
|
|
return None
|
|
found = self.find_spec(fullname, path)
|
|
return found.loader if found is not None else None
|
|
|
|
def invalidate_caches(self):
|
|
"""An optional method for clearing the finder's cache, if any.
|
|
This method is used by importlib.invalidate_caches().
|
|
"""
|
|
|
|
_register(MetaPathFinder, machinery.BuiltinImporter, machinery.FrozenImporter,
|
|
machinery.PathFinder, machinery.WindowsRegistryFinder)
|
|
|
|
|
|
class PathEntryFinder(metaclass=abc.ABCMeta):
|
|
|
|
"""Abstract base class for path entry finders used by PathFinder."""
|
|
|
|
# We don't define find_spec() here since that would break
|
|
# hasattr checks we do to support backward compatibility.
|
|
|
|
def find_loader(self, fullname):
|
|
"""Return (loader, namespace portion) for the path entry.
|
|
|
|
The fullname is a str. The namespace portion is a sequence of
|
|
path entries contributing to part of a namespace package. The
|
|
sequence may be empty. If loader is not None, the portion will
|
|
be ignored.
|
|
|
|
The portion will be discarded if another path entry finder
|
|
locates the module as a normal module or package.
|
|
|
|
This method is deprecated since Python 3.4 in favor of
|
|
finder.find_spec(). If find_spec() is provided than backwards-compatible
|
|
functionality is provided.
|
|
"""
|
|
warnings.warn("PathEntryFinder.find_loader() is deprecated since Python "
|
|
"3.4 in favor of PathEntryFinder.find_spec() "
|
|
"(available since 3.4)",
|
|
DeprecationWarning,
|
|
stacklevel=2)
|
|
if not hasattr(self, 'find_spec'):
|
|
return None, []
|
|
found = self.find_spec(fullname)
|
|
if found is not None:
|
|
if not found.submodule_search_locations:
|
|
portions = []
|
|
else:
|
|
portions = found.submodule_search_locations
|
|
return found.loader, portions
|
|
else:
|
|
return None, []
|
|
|
|
find_module = _bootstrap_external._find_module_shim
|
|
|
|
def invalidate_caches(self):
|
|
"""An optional method for clearing the finder's cache, if any.
|
|
This method is used by PathFinder.invalidate_caches().
|
|
"""
|
|
|
|
_register(PathEntryFinder, machinery.FileFinder)
|
|
|
|
|
|
class ResourceLoader(Loader):
|
|
|
|
"""Abstract base class for loaders which can return data from their
|
|
back-end storage.
|
|
|
|
This ABC represents one of the optional protocols specified by PEP 302.
|
|
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
def get_data(self, path):
|
|
"""Abstract method which when implemented should return the bytes for
|
|
the specified path. The path must be a str."""
|
|
raise OSError
|
|
|
|
|
|
class InspectLoader(Loader):
|
|
|
|
"""Abstract base class for loaders which support inspection about the
|
|
modules they can load.
|
|
|
|
This ABC represents one of the optional protocols specified by PEP 302.
|
|
|
|
"""
|
|
|
|
def is_package(self, fullname):
|
|
"""Optional method which when implemented should return whether the
|
|
module is a package. The fullname is a str. Returns a bool.
|
|
|
|
Raises ImportError if the module cannot be found.
|
|
"""
|
|
raise ImportError
|
|
|
|
def get_code(self, fullname):
|
|
"""Method which returns the code object for the module.
|
|
|
|
The fullname is a str. Returns a types.CodeType if possible, else
|
|
returns None if a code object does not make sense
|
|
(e.g. built-in module). Raises ImportError if the module cannot be
|
|
found.
|
|
"""
|
|
source = self.get_source(fullname)
|
|
if source is None:
|
|
return None
|
|
return self.source_to_code(source)
|
|
|
|
@abc.abstractmethod
|
|
def get_source(self, fullname):
|
|
"""Abstract method which should return the source code for the
|
|
module. The fullname is a str. Returns a str.
|
|
|
|
Raises ImportError if the module cannot be found.
|
|
"""
|
|
raise ImportError
|
|
|
|
@staticmethod
|
|
def source_to_code(data, path='<string>'):
|
|
"""Compile 'data' into a code object.
|
|
|
|
The 'data' argument can be anything that compile() can handle. The'path'
|
|
argument should be where the data was retrieved (when applicable)."""
|
|
return compile(data, path, 'exec', dont_inherit=True)
|
|
|
|
exec_module = _bootstrap_external._LoaderBasics.exec_module
|
|
load_module = _bootstrap_external._LoaderBasics.load_module
|
|
|
|
_register(InspectLoader, machinery.BuiltinImporter, machinery.FrozenImporter, machinery.NamespaceLoader)
|
|
|
|
|
|
class ExecutionLoader(InspectLoader):
|
|
|
|
"""Abstract base class for loaders that wish to support the execution of
|
|
modules as scripts.
|
|
|
|
This ABC represents one of the optional protocols specified in PEP 302.
|
|
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
def get_filename(self, fullname):
|
|
"""Abstract method which should return the value that __file__ is to be
|
|
set to.
|
|
|
|
Raises ImportError if the module cannot be found.
|
|
"""
|
|
raise ImportError
|
|
|
|
def get_code(self, fullname):
|
|
"""Method to return the code object for fullname.
|
|
|
|
Should return None if not applicable (e.g. built-in module).
|
|
Raise ImportError if the module cannot be found.
|
|
"""
|
|
source = self.get_source(fullname)
|
|
if source is None:
|
|
return None
|
|
try:
|
|
path = self.get_filename(fullname)
|
|
except ImportError:
|
|
return self.source_to_code(source)
|
|
else:
|
|
return self.source_to_code(source, path)
|
|
|
|
_register(ExecutionLoader, machinery.ExtensionFileLoader)
|
|
|
|
|
|
class FileLoader(_bootstrap_external.FileLoader, ResourceLoader, ExecutionLoader):
|
|
|
|
"""Abstract base class partially implementing the ResourceLoader and
|
|
ExecutionLoader ABCs."""
|
|
|
|
_register(FileLoader, machinery.SourceFileLoader,
|
|
machinery.SourcelessFileLoader)
|
|
|
|
|
|
class SourceLoader(_bootstrap_external.SourceLoader, ResourceLoader, ExecutionLoader):
|
|
|
|
"""Abstract base class for loading source code (and optionally any
|
|
corresponding bytecode).
|
|
|
|
To support loading from source code, the abstractmethods inherited from
|
|
ResourceLoader and ExecutionLoader need to be implemented. To also support
|
|
loading from bytecode, the optional methods specified directly by this ABC
|
|
is required.
|
|
|
|
Inherited abstractmethods not implemented in this ABC:
|
|
|
|
* ResourceLoader.get_data
|
|
* ExecutionLoader.get_filename
|
|
|
|
"""
|
|
|
|
def path_mtime(self, path):
|
|
"""Return the (int) modification time for the path (str)."""
|
|
if self.path_stats.__func__ is SourceLoader.path_stats:
|
|
raise OSError
|
|
return int(self.path_stats(path)['mtime'])
|
|
|
|
def path_stats(self, path):
|
|
"""Return a metadata dict for the source pointed to by the path (str).
|
|
Possible keys:
|
|
- 'mtime' (mandatory) is the numeric timestamp of last source
|
|
code modification;
|
|
- 'size' (optional) is the size in bytes of the source code.
|
|
"""
|
|
if self.path_mtime.__func__ is SourceLoader.path_mtime:
|
|
raise OSError
|
|
return {'mtime': self.path_mtime(path)}
|
|
|
|
def set_data(self, path, data):
|
|
"""Write the bytes to the path (if possible).
|
|
|
|
Accepts a str path and data as bytes.
|
|
|
|
Any needed intermediary directories are to be created. If for some
|
|
reason the file cannot be written because of permissions, fail
|
|
silently.
|
|
"""
|
|
|
|
_register(SourceLoader, machinery.SourceFileLoader)
|
|
|
|
|
|
class ResourceReader(metaclass=abc.ABCMeta):
|
|
"""Abstract base class for loaders to provide resource reading support."""
|
|
|
|
@abc.abstractmethod
|
|
def open_resource(self, resource: Text) -> BinaryIO:
|
|
"""Return an opened, file-like object for binary reading.
|
|
|
|
The 'resource' argument is expected to represent only a file name.
|
|
If the resource cannot be found, FileNotFoundError is raised.
|
|
"""
|
|
# This deliberately raises FileNotFoundError instead of
|
|
# NotImplementedError so that if this method is accidentally called,
|
|
# it'll still do the right thing.
|
|
raise FileNotFoundError
|
|
|
|
@abc.abstractmethod
|
|
def resource_path(self, resource: Text) -> Text:
|
|
"""Return the file system path to the specified resource.
|
|
|
|
The 'resource' argument is expected to represent only a file name.
|
|
If the resource does not exist on the file system, raise
|
|
FileNotFoundError.
|
|
"""
|
|
# This deliberately raises FileNotFoundError instead of
|
|
# NotImplementedError so that if this method is accidentally called,
|
|
# it'll still do the right thing.
|
|
raise FileNotFoundError
|
|
|
|
@abc.abstractmethod
|
|
def is_resource(self, path: Text) -> bool:
|
|
"""Return True if the named 'path' is a resource.
|
|
|
|
Files are resources, directories are not.
|
|
"""
|
|
raise FileNotFoundError
|
|
|
|
@abc.abstractmethod
|
|
def contents(self) -> Iterable[str]:
|
|
"""Return an iterable of entries in `package`."""
|
|
raise FileNotFoundError
|
|
|
|
|
|
@runtime_checkable
|
|
class Traversable(Protocol):
|
|
"""
|
|
An object with a subset of pathlib.Path methods suitable for
|
|
traversing directories and opening files.
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
def iterdir(self):
|
|
"""
|
|
Yield Traversable objects in self
|
|
"""
|
|
|
|
def read_bytes(self):
|
|
"""
|
|
Read contents of self as bytes
|
|
"""
|
|
with self.open('rb') as strm:
|
|
return strm.read()
|
|
|
|
def read_text(self, encoding=None):
|
|
"""
|
|
Read contents of self as text
|
|
"""
|
|
with self.open(encoding=encoding) as strm:
|
|
return strm.read()
|
|
|
|
@abc.abstractmethod
|
|
def is_dir(self) -> bool:
|
|
"""
|
|
Return True if self is a dir
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
def is_file(self) -> bool:
|
|
"""
|
|
Return True if self is a file
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
def joinpath(self, child):
|
|
"""
|
|
Return Traversable child in self
|
|
"""
|
|
|
|
def __truediv__(self, child):
|
|
"""
|
|
Return Traversable child in self
|
|
"""
|
|
return self.joinpath(child)
|
|
|
|
@abc.abstractmethod
|
|
def open(self, mode='r', *args, **kwargs):
|
|
"""
|
|
mode may be 'r' or 'rb' to open as text or binary. Return a handle
|
|
suitable for reading (same as pathlib.Path.open).
|
|
|
|
When opening as text, accepts encoding parameters such as those
|
|
accepted by io.TextIOWrapper.
|
|
"""
|
|
|
|
@abc.abstractproperty
|
|
def name(self) -> str:
|
|
"""
|
|
The base name of this object without any parent references.
|
|
"""
|
|
|
|
|
|
class TraversableResources(ResourceReader):
|
|
"""
|
|
The required interface for providing traversable
|
|
resources.
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
def files(self):
|
|
"""Return a Traversable object for the loaded package."""
|
|
|
|
def open_resource(self, resource):
|
|
return self.files().joinpath(resource).open('rb')
|
|
|
|
def resource_path(self, resource):
|
|
raise FileNotFoundError(resource)
|
|
|
|
def is_resource(self, path):
|
|
return self.files().joinpath(path).is_file()
|
|
|
|
def contents(self):
|
|
return (item.name for item in self.files().iterdir())
|