diff options
Diffstat (limited to 'Lib/importlib/abc.py')
| -rw-r--r-- | Lib/importlib/abc.py | 250 |
1 files changed, 45 insertions, 205 deletions
diff --git a/Lib/importlib/abc.py b/Lib/importlib/abc.py index 387567a450..7752ac4778 100644 --- a/Lib/importlib/abc.py +++ b/Lib/importlib/abc.py @@ -37,9 +37,8 @@ class Finder(metaclass=abc.ABCMeta): 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. + Returns a Loader object or None. """ - raise NotImplementedError class MetaPathFinder(Finder): @@ -49,16 +48,14 @@ class MetaPathFinder(Finder): @abc.abstractmethod def find_module(self, fullname, path): """Abstract method which, when implemented, should find a module. - The fullname is a str and the path is a str or None. - Returns a Loader object. + The fullname is a str and the path is a list of strings or None. + Returns a Loader object or None. """ - raise NotImplementedError def invalidate_caches(self): """An optional method for clearing the finder's cache, if any. This method is used by importlib.invalidate_caches(). """ - return NotImplemented _register(MetaPathFinder, machinery.BuiltinImporter, machinery.FrozenImporter, machinery.PathFinder, machinery.WindowsRegistryFinder) @@ -70,13 +67,14 @@ class PathEntryFinder(Finder): @abc.abstractmethod def find_loader(self, fullname): - """Abstract method which, when implemented, returns a module loader. + """Abstract method which, when implemented, returns a module loader or + a possible part of a namespace. The fullname is a str. Returns a 2-tuple of (Loader, portion) where portion is a sequence of file system locations contributing to part of a namespace package. The sequence may be empty and the loader may be None. """ - raise NotImplementedError + return None, [] find_module = _bootstrap._find_module_shim @@ -84,25 +82,34 @@ class PathEntryFinder(Finder): """An optional method for clearing the finder's cache, if any. This method is used by PathFinder.invalidate_caches(). """ - return NotImplemented _register(PathEntryFinder, machinery.FileFinder) class Loader(metaclass=abc.ABCMeta): - """Abstract base class for import loaders.""" + """Abstract base class for import loaders. + + The optional method module_repr(module) may be defined to provide a + repr for a module when appropriate (see PEP 420). The __repr__() method on + the module type will use the method as appropriate. + + """ @abc.abstractmethod def load_module(self, fullname): """Abstract method which when implemented should load a module. - The fullname is a str.""" - raise NotImplementedError + The fullname is a str. + + ImportError is raised on failure. + """ + raise ImportError - @abc.abstractmethod def module_repr(self, module): - """Abstract method which when implemented calculates and returns the - given module's repr.""" + """Return a module's repr. + + Used by the module type when implemented without raising an exception. + """ raise NotImplementedError @@ -119,7 +126,7 @@ class ResourceLoader(Loader): 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 NotImplementedError + raise IOError class InspectLoader(Loader): @@ -134,20 +141,29 @@ class InspectLoader(Loader): @abc.abstractmethod def is_package(self, fullname): """Abstract method which when implemented should return whether the - module is a package. The fullname is a str. Returns a bool.""" - raise NotImplementedError + module is a package. The fullname is a str. Returns a bool. + + Raises ImportError is the module cannot be found. + """ + raise ImportError @abc.abstractmethod def get_code(self, fullname): """Abstract method which when implemented should return the code object - for the module. The fullname is a str. Returns a types.CodeType.""" - raise NotImplementedError + for the module. The fullname is a str. Returns a types.CodeType. + + Raises ImportError if the module cannot be found. + """ + raise ImportError @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.""" - raise NotImplementedError + module. The fullname is a str. Returns a str. + + Raises ImportError if the module cannot be found. + """ + raise ImportError _register(InspectLoader, machinery.BuiltinImporter, machinery.FrozenImporter, machinery.ExtensionFileLoader) @@ -165,8 +181,11 @@ class ExecutionLoader(InspectLoader): @abc.abstractmethod def get_filename(self, fullname): """Abstract method which should return the value that __file__ is to be - set to.""" - raise NotImplementedError + set to. + + Raises ImportError if the module cannot be found. + """ + raise ImportError class FileLoader(_bootstrap.FileLoader, ResourceLoader, ExecutionLoader): @@ -198,7 +217,7 @@ class SourceLoader(_bootstrap.SourceLoader, ResourceLoader, ExecutionLoader): def path_mtime(self, path): """Return the (int) modification time for the path (str).""" if self.path_stats.__func__ is SourceLoader.path_stats: - raise NotImplementedError + raise IOError return int(self.path_stats(path)['mtime']) def path_stats(self, path): @@ -209,7 +228,7 @@ class SourceLoader(_bootstrap.SourceLoader, ResourceLoader, ExecutionLoader): - 'size' (optional) is the size in bytes of the source code. """ if self.path_mtime.__func__ is SourceLoader.path_mtime: - raise NotImplementedError + raise IOError return {'mtime': self.path_mtime(path)} def set_data(self, path, data): @@ -220,185 +239,6 @@ class SourceLoader(_bootstrap.SourceLoader, ResourceLoader, ExecutionLoader): Any needed intermediary directories are to be created. If for some reason the file cannot be written because of permissions, fail silently. - """ - raise NotImplementedError _register(SourceLoader, machinery.SourceFileLoader) - -class PyLoader(SourceLoader): - - """Implement the deprecated PyLoader ABC in terms of SourceLoader. - - This class has been deprecated! It is slated for removal in Python 3.4. - If compatibility with Python 3.1 is not needed then implement the - SourceLoader ABC instead of this class. If Python 3.1 compatibility is - needed, then use the following idiom to have a single class that is - compatible with Python 3.1 onwards:: - - try: - from importlib.abc import SourceLoader - except ImportError: - from importlib.abc import PyLoader as SourceLoader - - - class CustomLoader(SourceLoader): - def get_filename(self, fullname): - # Implement ... - - def source_path(self, fullname): - '''Implement source_path in terms of get_filename.''' - try: - return self.get_filename(fullname) - except ImportError: - return None - - def is_package(self, fullname): - filename = os.path.basename(self.get_filename(fullname)) - return os.path.splitext(filename)[0] == '__init__' - - """ - - @abc.abstractmethod - def is_package(self, fullname): - raise NotImplementedError - - @abc.abstractmethod - def source_path(self, fullname): - """Abstract method. Accepts a str module name and returns the path to - the source code for the module.""" - raise NotImplementedError - - def get_filename(self, fullname): - """Implement get_filename in terms of source_path. - - As get_filename should only return a source file path there is no - chance of the path not existing but loading still being possible, so - ImportError should propagate instead of being turned into returning - None. - - """ - warnings.warn("importlib.abc.PyLoader is deprecated and is " - "slated for removal in Python 3.4; " - "use SourceLoader instead. " - "See the importlib documentation on how to be " - "compatible with Python 3.1 onwards.", - DeprecationWarning) - path = self.source_path(fullname) - if path is None: - raise ImportError(name=fullname) - else: - return path - - -class PyPycLoader(PyLoader): - - """Abstract base class to assist in loading source and bytecode by - requiring only back-end storage methods to be implemented. - - This class has been deprecated! Removal is slated for Python 3.4. Implement - the SourceLoader ABC instead. If Python 3.1 compatibility is needed, see - PyLoader. - - The methods get_code, get_source, and load_module are implemented for the - user. - - """ - - def get_filename(self, fullname): - """Return the source or bytecode file path.""" - path = self.source_path(fullname) - if path is not None: - return path - path = self.bytecode_path(fullname) - if path is not None: - return path - raise ImportError("no source or bytecode path available for " - "{0!r}".format(fullname), name=fullname) - - def get_code(self, fullname): - """Get a code object from source or bytecode.""" - warnings.warn("importlib.abc.PyPycLoader is deprecated and slated for " - "removal in Python 3.4; use SourceLoader instead. " - "If Python 3.1 compatibility is required, see the " - "latest documentation for PyLoader.", - DeprecationWarning) - source_timestamp = self.source_mtime(fullname) - # Try to use bytecode if it is available. - bytecode_path = self.bytecode_path(fullname) - if bytecode_path: - data = self.get_data(bytecode_path) - try: - magic = data[:4] - if len(magic) < 4: - raise ImportError( - "bad magic number in {}".format(fullname), - name=fullname, path=bytecode_path) - raw_timestamp = data[4:8] - if len(raw_timestamp) < 4: - raise EOFError("bad timestamp in {}".format(fullname)) - pyc_timestamp = _bootstrap._r_long(raw_timestamp) - raw_source_size = data[8:12] - if len(raw_source_size) != 4: - raise EOFError("bad file size in {}".format(fullname)) - # Source size is unused as the ABC does not provide a way to - # get the size of the source ahead of reading it. - bytecode = data[12:] - # Verify that the magic number is valid. - if imp.get_magic() != magic: - raise ImportError( - "bad magic number in {}".format(fullname), - name=fullname, path=bytecode_path) - # Verify that the bytecode is not stale (only matters when - # there is source to fall back on. - if source_timestamp: - if pyc_timestamp < source_timestamp: - raise ImportError("bytecode is stale", name=fullname, - path=bytecode_path) - except (ImportError, EOFError): - # If source is available give it a shot. - if source_timestamp is not None: - pass - else: - raise - else: - # Bytecode seems fine, so try to use it. - return marshal.loads(bytecode) - elif source_timestamp is None: - raise ImportError("no source or bytecode available to create code " - "object for {0!r}".format(fullname), - name=fullname) - # Use the source. - source_path = self.source_path(fullname) - if source_path is None: - message = "a source path must exist to load {0}".format(fullname) - raise ImportError(message, name=fullname) - source = self.get_data(source_path) - code_object = compile(source, source_path, 'exec', dont_inherit=True) - # Generate bytecode and write it out. - if not sys.dont_write_bytecode: - data = bytearray(imp.get_magic()) - data.extend(_bootstrap._w_long(source_timestamp)) - data.extend(_bootstrap._w_long(len(source) & 0xFFFFFFFF)) - data.extend(marshal.dumps(code_object)) - self.write_bytecode(fullname, data) - return code_object - - @abc.abstractmethod - def source_mtime(self, fullname): - """Abstract method. Accepts a str filename and returns an int - modification time for the source of the module.""" - raise NotImplementedError - - @abc.abstractmethod - def bytecode_path(self, fullname): - """Abstract method. Accepts a str filename and returns the str pathname - to the bytecode for the module.""" - raise NotImplementedError - - @abc.abstractmethod - def write_bytecode(self, fullname, bytecode): - """Abstract method. Accepts a str filename and bytes object - representing the bytecode for the module. Returns a boolean - representing whether the bytecode was written or not.""" - raise NotImplementedError |