Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/importlib/abc.py @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 """Abstract base classes related to import."""
jpayne@69 2 from . import _bootstrap
jpayne@69 3 from . import _bootstrap_external
jpayne@69 4 from . import machinery
jpayne@69 5 try:
jpayne@69 6 import _frozen_importlib
jpayne@69 7 except ImportError as exc:
jpayne@69 8 if exc.name != '_frozen_importlib':
jpayne@69 9 raise
jpayne@69 10 _frozen_importlib = None
jpayne@69 11 try:
jpayne@69 12 import _frozen_importlib_external
jpayne@69 13 except ImportError as exc:
jpayne@69 14 _frozen_importlib_external = _bootstrap_external
jpayne@69 15 import abc
jpayne@69 16 import warnings
jpayne@69 17
jpayne@69 18
jpayne@69 19 def _register(abstract_cls, *classes):
jpayne@69 20 for cls in classes:
jpayne@69 21 abstract_cls.register(cls)
jpayne@69 22 if _frozen_importlib is not None:
jpayne@69 23 try:
jpayne@69 24 frozen_cls = getattr(_frozen_importlib, cls.__name__)
jpayne@69 25 except AttributeError:
jpayne@69 26 frozen_cls = getattr(_frozen_importlib_external, cls.__name__)
jpayne@69 27 abstract_cls.register(frozen_cls)
jpayne@69 28
jpayne@69 29
jpayne@69 30 class Finder(metaclass=abc.ABCMeta):
jpayne@69 31
jpayne@69 32 """Legacy abstract base class for import finders.
jpayne@69 33
jpayne@69 34 It may be subclassed for compatibility with legacy third party
jpayne@69 35 reimplementations of the import system. Otherwise, finder
jpayne@69 36 implementations should derive from the more specific MetaPathFinder
jpayne@69 37 or PathEntryFinder ABCs.
jpayne@69 38
jpayne@69 39 Deprecated since Python 3.3
jpayne@69 40 """
jpayne@69 41
jpayne@69 42 @abc.abstractmethod
jpayne@69 43 def find_module(self, fullname, path=None):
jpayne@69 44 """An abstract method that should find a module.
jpayne@69 45 The fullname is a str and the optional path is a str or None.
jpayne@69 46 Returns a Loader object or None.
jpayne@69 47 """
jpayne@69 48
jpayne@69 49
jpayne@69 50 class MetaPathFinder(Finder):
jpayne@69 51
jpayne@69 52 """Abstract base class for import finders on sys.meta_path."""
jpayne@69 53
jpayne@69 54 # We don't define find_spec() here since that would break
jpayne@69 55 # hasattr checks we do to support backward compatibility.
jpayne@69 56
jpayne@69 57 def find_module(self, fullname, path):
jpayne@69 58 """Return a loader for the module.
jpayne@69 59
jpayne@69 60 If no module is found, return None. The fullname is a str and
jpayne@69 61 the path is a list of strings or None.
jpayne@69 62
jpayne@69 63 This method is deprecated since Python 3.4 in favor of
jpayne@69 64 finder.find_spec(). If find_spec() exists then backwards-compatible
jpayne@69 65 functionality is provided for this method.
jpayne@69 66
jpayne@69 67 """
jpayne@69 68 warnings.warn("MetaPathFinder.find_module() is deprecated since Python "
jpayne@69 69 "3.4 in favor of MetaPathFinder.find_spec() "
jpayne@69 70 "(available since 3.4)",
jpayne@69 71 DeprecationWarning,
jpayne@69 72 stacklevel=2)
jpayne@69 73 if not hasattr(self, 'find_spec'):
jpayne@69 74 return None
jpayne@69 75 found = self.find_spec(fullname, path)
jpayne@69 76 return found.loader if found is not None else None
jpayne@69 77
jpayne@69 78 def invalidate_caches(self):
jpayne@69 79 """An optional method for clearing the finder's cache, if any.
jpayne@69 80 This method is used by importlib.invalidate_caches().
jpayne@69 81 """
jpayne@69 82
jpayne@69 83 _register(MetaPathFinder, machinery.BuiltinImporter, machinery.FrozenImporter,
jpayne@69 84 machinery.PathFinder, machinery.WindowsRegistryFinder)
jpayne@69 85
jpayne@69 86
jpayne@69 87 class PathEntryFinder(Finder):
jpayne@69 88
jpayne@69 89 """Abstract base class for path entry finders used by PathFinder."""
jpayne@69 90
jpayne@69 91 # We don't define find_spec() here since that would break
jpayne@69 92 # hasattr checks we do to support backward compatibility.
jpayne@69 93
jpayne@69 94 def find_loader(self, fullname):
jpayne@69 95 """Return (loader, namespace portion) for the path entry.
jpayne@69 96
jpayne@69 97 The fullname is a str. The namespace portion is a sequence of
jpayne@69 98 path entries contributing to part of a namespace package. The
jpayne@69 99 sequence may be empty. If loader is not None, the portion will
jpayne@69 100 be ignored.
jpayne@69 101
jpayne@69 102 The portion will be discarded if another path entry finder
jpayne@69 103 locates the module as a normal module or package.
jpayne@69 104
jpayne@69 105 This method is deprecated since Python 3.4 in favor of
jpayne@69 106 finder.find_spec(). If find_spec() is provided than backwards-compatible
jpayne@69 107 functionality is provided.
jpayne@69 108 """
jpayne@69 109 warnings.warn("PathEntryFinder.find_loader() is deprecated since Python "
jpayne@69 110 "3.4 in favor of PathEntryFinder.find_spec() "
jpayne@69 111 "(available since 3.4)",
jpayne@69 112 DeprecationWarning,
jpayne@69 113 stacklevel=2)
jpayne@69 114 if not hasattr(self, 'find_spec'):
jpayne@69 115 return None, []
jpayne@69 116 found = self.find_spec(fullname)
jpayne@69 117 if found is not None:
jpayne@69 118 if not found.submodule_search_locations:
jpayne@69 119 portions = []
jpayne@69 120 else:
jpayne@69 121 portions = found.submodule_search_locations
jpayne@69 122 return found.loader, portions
jpayne@69 123 else:
jpayne@69 124 return None, []
jpayne@69 125
jpayne@69 126 find_module = _bootstrap_external._find_module_shim
jpayne@69 127
jpayne@69 128 def invalidate_caches(self):
jpayne@69 129 """An optional method for clearing the finder's cache, if any.
jpayne@69 130 This method is used by PathFinder.invalidate_caches().
jpayne@69 131 """
jpayne@69 132
jpayne@69 133 _register(PathEntryFinder, machinery.FileFinder)
jpayne@69 134
jpayne@69 135
jpayne@69 136 class Loader(metaclass=abc.ABCMeta):
jpayne@69 137
jpayne@69 138 """Abstract base class for import loaders."""
jpayne@69 139
jpayne@69 140 def create_module(self, spec):
jpayne@69 141 """Return a module to initialize and into which to load.
jpayne@69 142
jpayne@69 143 This method should raise ImportError if anything prevents it
jpayne@69 144 from creating a new module. It may return None to indicate
jpayne@69 145 that the spec should create the new module.
jpayne@69 146 """
jpayne@69 147 # By default, defer to default semantics for the new module.
jpayne@69 148 return None
jpayne@69 149
jpayne@69 150 # We don't define exec_module() here since that would break
jpayne@69 151 # hasattr checks we do to support backward compatibility.
jpayne@69 152
jpayne@69 153 def load_module(self, fullname):
jpayne@69 154 """Return the loaded module.
jpayne@69 155
jpayne@69 156 The module must be added to sys.modules and have import-related
jpayne@69 157 attributes set properly. The fullname is a str.
jpayne@69 158
jpayne@69 159 ImportError is raised on failure.
jpayne@69 160
jpayne@69 161 This method is deprecated in favor of loader.exec_module(). If
jpayne@69 162 exec_module() exists then it is used to provide a backwards-compatible
jpayne@69 163 functionality for this method.
jpayne@69 164
jpayne@69 165 """
jpayne@69 166 if not hasattr(self, 'exec_module'):
jpayne@69 167 raise ImportError
jpayne@69 168 return _bootstrap._load_module_shim(self, fullname)
jpayne@69 169
jpayne@69 170 def module_repr(self, module):
jpayne@69 171 """Return a module's repr.
jpayne@69 172
jpayne@69 173 Used by the module type when the method does not raise
jpayne@69 174 NotImplementedError.
jpayne@69 175
jpayne@69 176 This method is deprecated.
jpayne@69 177
jpayne@69 178 """
jpayne@69 179 # The exception will cause ModuleType.__repr__ to ignore this method.
jpayne@69 180 raise NotImplementedError
jpayne@69 181
jpayne@69 182
jpayne@69 183 class ResourceLoader(Loader):
jpayne@69 184
jpayne@69 185 """Abstract base class for loaders which can return data from their
jpayne@69 186 back-end storage.
jpayne@69 187
jpayne@69 188 This ABC represents one of the optional protocols specified by PEP 302.
jpayne@69 189
jpayne@69 190 """
jpayne@69 191
jpayne@69 192 @abc.abstractmethod
jpayne@69 193 def get_data(self, path):
jpayne@69 194 """Abstract method which when implemented should return the bytes for
jpayne@69 195 the specified path. The path must be a str."""
jpayne@69 196 raise OSError
jpayne@69 197
jpayne@69 198
jpayne@69 199 class InspectLoader(Loader):
jpayne@69 200
jpayne@69 201 """Abstract base class for loaders which support inspection about the
jpayne@69 202 modules they can load.
jpayne@69 203
jpayne@69 204 This ABC represents one of the optional protocols specified by PEP 302.
jpayne@69 205
jpayne@69 206 """
jpayne@69 207
jpayne@69 208 def is_package(self, fullname):
jpayne@69 209 """Optional method which when implemented should return whether the
jpayne@69 210 module is a package. The fullname is a str. Returns a bool.
jpayne@69 211
jpayne@69 212 Raises ImportError if the module cannot be found.
jpayne@69 213 """
jpayne@69 214 raise ImportError
jpayne@69 215
jpayne@69 216 def get_code(self, fullname):
jpayne@69 217 """Method which returns the code object for the module.
jpayne@69 218
jpayne@69 219 The fullname is a str. Returns a types.CodeType if possible, else
jpayne@69 220 returns None if a code object does not make sense
jpayne@69 221 (e.g. built-in module). Raises ImportError if the module cannot be
jpayne@69 222 found.
jpayne@69 223 """
jpayne@69 224 source = self.get_source(fullname)
jpayne@69 225 if source is None:
jpayne@69 226 return None
jpayne@69 227 return self.source_to_code(source)
jpayne@69 228
jpayne@69 229 @abc.abstractmethod
jpayne@69 230 def get_source(self, fullname):
jpayne@69 231 """Abstract method which should return the source code for the
jpayne@69 232 module. The fullname is a str. Returns a str.
jpayne@69 233
jpayne@69 234 Raises ImportError if the module cannot be found.
jpayne@69 235 """
jpayne@69 236 raise ImportError
jpayne@69 237
jpayne@69 238 @staticmethod
jpayne@69 239 def source_to_code(data, path='<string>'):
jpayne@69 240 """Compile 'data' into a code object.
jpayne@69 241
jpayne@69 242 The 'data' argument can be anything that compile() can handle. The'path'
jpayne@69 243 argument should be where the data was retrieved (when applicable)."""
jpayne@69 244 return compile(data, path, 'exec', dont_inherit=True)
jpayne@69 245
jpayne@69 246 exec_module = _bootstrap_external._LoaderBasics.exec_module
jpayne@69 247 load_module = _bootstrap_external._LoaderBasics.load_module
jpayne@69 248
jpayne@69 249 _register(InspectLoader, machinery.BuiltinImporter, machinery.FrozenImporter)
jpayne@69 250
jpayne@69 251
jpayne@69 252 class ExecutionLoader(InspectLoader):
jpayne@69 253
jpayne@69 254 """Abstract base class for loaders that wish to support the execution of
jpayne@69 255 modules as scripts.
jpayne@69 256
jpayne@69 257 This ABC represents one of the optional protocols specified in PEP 302.
jpayne@69 258
jpayne@69 259 """
jpayne@69 260
jpayne@69 261 @abc.abstractmethod
jpayne@69 262 def get_filename(self, fullname):
jpayne@69 263 """Abstract method which should return the value that __file__ is to be
jpayne@69 264 set to.
jpayne@69 265
jpayne@69 266 Raises ImportError if the module cannot be found.
jpayne@69 267 """
jpayne@69 268 raise ImportError
jpayne@69 269
jpayne@69 270 def get_code(self, fullname):
jpayne@69 271 """Method to return the code object for fullname.
jpayne@69 272
jpayne@69 273 Should return None if not applicable (e.g. built-in module).
jpayne@69 274 Raise ImportError if the module cannot be found.
jpayne@69 275 """
jpayne@69 276 source = self.get_source(fullname)
jpayne@69 277 if source is None:
jpayne@69 278 return None
jpayne@69 279 try:
jpayne@69 280 path = self.get_filename(fullname)
jpayne@69 281 except ImportError:
jpayne@69 282 return self.source_to_code(source)
jpayne@69 283 else:
jpayne@69 284 return self.source_to_code(source, path)
jpayne@69 285
jpayne@69 286 _register(ExecutionLoader, machinery.ExtensionFileLoader)
jpayne@69 287
jpayne@69 288
jpayne@69 289 class FileLoader(_bootstrap_external.FileLoader, ResourceLoader, ExecutionLoader):
jpayne@69 290
jpayne@69 291 """Abstract base class partially implementing the ResourceLoader and
jpayne@69 292 ExecutionLoader ABCs."""
jpayne@69 293
jpayne@69 294 _register(FileLoader, machinery.SourceFileLoader,
jpayne@69 295 machinery.SourcelessFileLoader)
jpayne@69 296
jpayne@69 297
jpayne@69 298 class SourceLoader(_bootstrap_external.SourceLoader, ResourceLoader, ExecutionLoader):
jpayne@69 299
jpayne@69 300 """Abstract base class for loading source code (and optionally any
jpayne@69 301 corresponding bytecode).
jpayne@69 302
jpayne@69 303 To support loading from source code, the abstractmethods inherited from
jpayne@69 304 ResourceLoader and ExecutionLoader need to be implemented. To also support
jpayne@69 305 loading from bytecode, the optional methods specified directly by this ABC
jpayne@69 306 is required.
jpayne@69 307
jpayne@69 308 Inherited abstractmethods not implemented in this ABC:
jpayne@69 309
jpayne@69 310 * ResourceLoader.get_data
jpayne@69 311 * ExecutionLoader.get_filename
jpayne@69 312
jpayne@69 313 """
jpayne@69 314
jpayne@69 315 def path_mtime(self, path):
jpayne@69 316 """Return the (int) modification time for the path (str)."""
jpayne@69 317 if self.path_stats.__func__ is SourceLoader.path_stats:
jpayne@69 318 raise OSError
jpayne@69 319 return int(self.path_stats(path)['mtime'])
jpayne@69 320
jpayne@69 321 def path_stats(self, path):
jpayne@69 322 """Return a metadata dict for the source pointed to by the path (str).
jpayne@69 323 Possible keys:
jpayne@69 324 - 'mtime' (mandatory) is the numeric timestamp of last source
jpayne@69 325 code modification;
jpayne@69 326 - 'size' (optional) is the size in bytes of the source code.
jpayne@69 327 """
jpayne@69 328 if self.path_mtime.__func__ is SourceLoader.path_mtime:
jpayne@69 329 raise OSError
jpayne@69 330 return {'mtime': self.path_mtime(path)}
jpayne@69 331
jpayne@69 332 def set_data(self, path, data):
jpayne@69 333 """Write the bytes to the path (if possible).
jpayne@69 334
jpayne@69 335 Accepts a str path and data as bytes.
jpayne@69 336
jpayne@69 337 Any needed intermediary directories are to be created. If for some
jpayne@69 338 reason the file cannot be written because of permissions, fail
jpayne@69 339 silently.
jpayne@69 340 """
jpayne@69 341
jpayne@69 342 _register(SourceLoader, machinery.SourceFileLoader)
jpayne@69 343
jpayne@69 344
jpayne@69 345 class ResourceReader(metaclass=abc.ABCMeta):
jpayne@69 346
jpayne@69 347 """Abstract base class to provide resource-reading support.
jpayne@69 348
jpayne@69 349 Loaders that support resource reading are expected to implement
jpayne@69 350 the ``get_resource_reader(fullname)`` method and have it either return None
jpayne@69 351 or an object compatible with this ABC.
jpayne@69 352 """
jpayne@69 353
jpayne@69 354 @abc.abstractmethod
jpayne@69 355 def open_resource(self, resource):
jpayne@69 356 """Return an opened, file-like object for binary reading.
jpayne@69 357
jpayne@69 358 The 'resource' argument is expected to represent only a file name
jpayne@69 359 and thus not contain any subdirectory components.
jpayne@69 360
jpayne@69 361 If the resource cannot be found, FileNotFoundError is raised.
jpayne@69 362 """
jpayne@69 363 raise FileNotFoundError
jpayne@69 364
jpayne@69 365 @abc.abstractmethod
jpayne@69 366 def resource_path(self, resource):
jpayne@69 367 """Return the file system path to the specified resource.
jpayne@69 368
jpayne@69 369 The 'resource' argument is expected to represent only a file name
jpayne@69 370 and thus not contain any subdirectory components.
jpayne@69 371
jpayne@69 372 If the resource does not exist on the file system, raise
jpayne@69 373 FileNotFoundError.
jpayne@69 374 """
jpayne@69 375 raise FileNotFoundError
jpayne@69 376
jpayne@69 377 @abc.abstractmethod
jpayne@69 378 def is_resource(self, name):
jpayne@69 379 """Return True if the named 'name' is consider a resource."""
jpayne@69 380 raise FileNotFoundError
jpayne@69 381
jpayne@69 382 @abc.abstractmethod
jpayne@69 383 def contents(self):
jpayne@69 384 """Return an iterable of strings over the contents of the package."""
jpayne@69 385 return []
jpayne@69 386
jpayne@69 387
jpayne@69 388 _register(ResourceReader, machinery.SourceFileLoader)