venv/lib/python3.11/site-packages/setuptools/_vendor/importlib_resources/_legacy.py

   1 import functools
   2 import os
   3 import pathlib
   4 import types
   5 import warnings
   6
   7 from typing import Union, Iterable, ContextManager, BinaryIO, TextIO, Any
   8
   9 from . import _common
  10
  11 Package = Union[types.ModuleType, str]
  12 Resource = str
  13
  14
  15 def deprecated(func):
  16     @functools.wraps(func)
  17     def wrapper(*args, **kwargs):
  18         warnings.warn(
  19             f"{func.__name__} is deprecated. Use files() instead. "
  20             "Refer to https://importlib-resources.readthedocs.io"
  21             "/en/latest/using.html#migrating-from-legacy for migration advice.",
  22             DeprecationWarning,
  23             stacklevel=2,
  24         )
  25         return func(*args, **kwargs)
  26
  27     return wrapper
  28
  29
  30 def normalize_path(path: Any) -> str:
  31     """Normalize a path by ensuring it is a string.
  32
  33     If the resulting string contains path separators, an exception is raised.
  34     """
  35     str_path = str(path)
  36     parent, file_name = os.path.split(str_path)
  37     if parent:
  38         raise ValueError(f'{path!r} must be only a file name')
  39     return file_name
  40
  41
  42 @deprecated
  43 def open_binary(package: Package, resource: Resource) -> BinaryIO:
  44     """Return a file-like object opened for binary reading of the resource."""
  45     return (_common.files(package) / normalize_path(resource)).open('rb')
  46
  47
  48 @deprecated
  49 def read_binary(package: Package, resource: Resource) -> bytes:
  50     """Return the binary contents of the resource."""
  51     return (_common.files(package) / normalize_path(resource)).read_bytes()
  52
  53
  54 @deprecated
  55 def open_text(
  56     package: Package,
  57     resource: Resource,
  58     encoding: str = 'utf-8',
  59     errors: str = 'strict',
  60 ) -> TextIO:
  61     """Return a file-like object opened for text reading of the resource."""
  62     return (_common.files(package) / normalize_path(resource)).open(
  63         'r', encoding=encoding, errors=errors
  64     )
  65
  66
  67 @deprecated
  68 def read_text(
  69     package: Package,
  70     resource: Resource,
  71     encoding: str = 'utf-8',
  72     errors: str = 'strict',
  73 ) -> str:
  74     """Return the decoded string of the resource.
  75
  76     The decoding-related arguments have the same semantics as those of
  77     bytes.decode().
  78     """
  79     with open_text(package, resource, encoding, errors) as fp:
  80         return fp.read()
  81
  82
  83 @deprecated
  84 def contents(package: Package) -> Iterable[str]:
  85     """Return an iterable of entries in `package`.
  86
  87     Note that not all entries are resources.  Specifically, directories are
  88     not considered resources.  Use `is_resource()` on each entry returned here
  89     to check if it is a resource or not.
  90     """
  91     return [path.name for path in _common.files(package).iterdir()]
  92
  93
  94 @deprecated
  95 def is_resource(package: Package, name: str) -> bool:
  96     """True if `name` is a resource inside `package`.
  97
  98     Directories are *not* resources.
  99     """
 100     resource = normalize_path(name)
 101     return any(
 102         traversable.name == resource and traversable.is_file()
 103         for traversable in _common.files(package).iterdir()
 104     )
 105
 106
 107 @deprecated
 108 def path(
 109     package: Package,
 110     resource: Resource,
 111 ) -> ContextManager[pathlib.Path]:
 112     """A context manager providing a file path object to the resource.
 113
 114     If the resource does not already exist on its own on the file system,
 115     a temporary file will be created. If the file was created, the file
 116     will be deleted upon exiting the context manager (no exception is
 117     raised if the file was deleted prior to the context manager
 118     exiting).
 119     """
 120     return _common.as_file(_common.files(package) / normalize_path(resource))