mirror of
https://github.com/python/cpython.git
synced 2025-10-30 21:21:22 +00:00
e712a5b277
* bpo-46118: Move importlib.resources to its own package. * Expand compatibility shims with documentation and explicit imports.
121 lines
3.4 KiB
Python
121 lines
3.4 KiB
Python
import functools
|
|
import os
|
|
import pathlib
|
|
import types
|
|
import warnings
|
|
|
|
from typing import Union, Iterable, ContextManager, BinaryIO, TextIO, Any
|
|
|
|
from . import _common
|
|
|
|
Package = Union[types.ModuleType, str]
|
|
Resource = str
|
|
|
|
|
|
def deprecated(func):
|
|
@functools.wraps(func)
|
|
def wrapper(*args, **kwargs):
|
|
warnings.warn(
|
|
f"{func.__name__} is deprecated. Use files() instead. "
|
|
"Refer to https://importlib-resources.readthedocs.io"
|
|
"/en/latest/using.html#migrating-from-legacy for migration advice.",
|
|
DeprecationWarning,
|
|
stacklevel=2,
|
|
)
|
|
return func(*args, **kwargs)
|
|
|
|
return wrapper
|
|
|
|
|
|
def normalize_path(path):
|
|
# type: (Any) -> str
|
|
"""Normalize a path by ensuring it is a string.
|
|
|
|
If the resulting string contains path separators, an exception is raised.
|
|
"""
|
|
str_path = str(path)
|
|
parent, file_name = os.path.split(str_path)
|
|
if parent:
|
|
raise ValueError(f'{path!r} must be only a file name')
|
|
return file_name
|
|
|
|
|
|
@deprecated
|
|
def open_binary(package: Package, resource: Resource) -> BinaryIO:
|
|
"""Return a file-like object opened for binary reading of the resource."""
|
|
return (_common.files(package) / normalize_path(resource)).open('rb')
|
|
|
|
|
|
@deprecated
|
|
def read_binary(package: Package, resource: Resource) -> bytes:
|
|
"""Return the binary contents of the resource."""
|
|
return (_common.files(package) / normalize_path(resource)).read_bytes()
|
|
|
|
|
|
@deprecated
|
|
def open_text(
|
|
package: Package,
|
|
resource: Resource,
|
|
encoding: str = 'utf-8',
|
|
errors: str = 'strict',
|
|
) -> TextIO:
|
|
"""Return a file-like object opened for text reading of the resource."""
|
|
return (_common.files(package) / normalize_path(resource)).open(
|
|
'r', encoding=encoding, errors=errors
|
|
)
|
|
|
|
|
|
@deprecated
|
|
def read_text(
|
|
package: Package,
|
|
resource: Resource,
|
|
encoding: str = 'utf-8',
|
|
errors: str = 'strict',
|
|
) -> str:
|
|
"""Return the decoded string of the resource.
|
|
|
|
The decoding-related arguments have the same semantics as those of
|
|
bytes.decode().
|
|
"""
|
|
with open_text(package, resource, encoding, errors) as fp:
|
|
return fp.read()
|
|
|
|
|
|
@deprecated
|
|
def contents(package: Package) -> Iterable[str]:
|
|
"""Return an iterable of entries in `package`.
|
|
|
|
Note that not all entries are resources. Specifically, directories are
|
|
not considered resources. Use `is_resource()` on each entry returned here
|
|
to check if it is a resource or not.
|
|
"""
|
|
return [path.name for path in _common.files(package).iterdir()]
|
|
|
|
|
|
@deprecated
|
|
def is_resource(package: Package, name: str) -> bool:
|
|
"""True if `name` is a resource inside `package`.
|
|
|
|
Directories are *not* resources.
|
|
"""
|
|
resource = normalize_path(name)
|
|
return any(
|
|
traversable.name == resource and traversable.is_file()
|
|
for traversable in _common.files(package).iterdir()
|
|
)
|
|
|
|
|
|
@deprecated
|
|
def path(
|
|
package: Package,
|
|
resource: Resource,
|
|
) -> ContextManager[pathlib.Path]:
|
|
"""A context manager providing a file path object to the resource.
|
|
|
|
If the resource does not already exist on its own on the file system,
|
|
a temporary file will be created. If the file was created, the file
|
|
will be deleted upon exiting the context manager (no exception is
|
|
raised if the file was deleted prior to the context manager
|
|
exiting).
|
|
"""
|
|
return _common.as_file(_common.files(package) / normalize_path(resource))
|