mirror of https://github.com/python/cpython
gh-106531: Remove importlib.resources._legacy (#106532)
* gh-106531: Remove importlib.resources._legacy Syncs with importlib_resources 6.0. * Remove documentation for removed functionality.
This commit is contained in:
Jason R. Coombs
GitHub
parent
7c95345e4f
commit
243fdcb40e
|
|
@ -94,159 +94,3 @@ for example, a package and its resources can be imported from a zip file using
|
|||
the file system is required.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
|
||||
Deprecated functions
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
An older, deprecated set of functions is still available, but is
|
||||
scheduled for removal in a future version of Python.
|
||||
The main drawback of these functions is that they do not support
|
||||
directories: they assume all resources are located directly within a *package*.
|
||||
|
||||
.. data:: Package
|
||||
|
||||
Whenever a function accepts a ``Package`` argument, you can pass in
|
||||
either a :class:`module object <types.ModuleType>` or a module name
|
||||
as a string. You can only pass module objects whose
|
||||
``__spec__.submodule_search_locations`` is not ``None``.
|
||||
|
||||
The ``Package`` type is defined as ``Union[str, ModuleType]``.
|
||||
|
||||
.. deprecated:: 3.12
|
||||
|
||||
|
||||
.. data:: Resource
|
||||
|
||||
For *resource* arguments of the functions below, you can pass in
|
||||
the name of a resource as a string or
|
||||
a :class:`path-like object <os.PathLike>`.
|
||||
|
||||
The ``Resource`` type is defined as ``Union[str, os.PathLike]``.
|
||||
|
||||
|
||||
.. function:: open_binary(package, resource)
|
||||
|
||||
Open for binary reading the *resource* within *package*.
|
||||
|
||||
*package* is either a name or a module object which conforms to the
|
||||
``Package`` requirements. *resource* is the name of the resource to open
|
||||
within *package*; it may not contain path separators and it may not have
|
||||
sub-resources (i.e. it cannot be a directory). This function returns a
|
||||
``typing.BinaryIO`` instance, a binary I/O stream open for reading.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
Calls to this function can be replaced by::
|
||||
|
||||
files(package).joinpath(resource).open('rb')
|
||||
|
||||
|
||||
.. function:: open_text(package, resource, encoding='utf-8', errors='strict')
|
||||
|
||||
Open for text reading the *resource* within *package*. By default, the
|
||||
resource is opened for reading as UTF-8.
|
||||
|
||||
*package* is either a name or a module object which conforms to the
|
||||
``Package`` requirements. *resource* is the name of the resource to open
|
||||
within *package*; it may not contain path separators and it may not have
|
||||
sub-resources (i.e. it cannot be a directory). *encoding* and *errors*
|
||||
have the same meaning as with built-in :func:`open`.
|
||||
|
||||
This function returns a ``typing.TextIO`` instance, a text I/O stream open
|
||||
for reading.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
Calls to this function can be replaced by::
|
||||
|
||||
files(package).joinpath(resource).open('r', encoding=encoding)
|
||||
|
||||
|
||||
.. function:: read_binary(package, resource)
|
||||
|
||||
Read and return the contents of the *resource* within *package* as
|
||||
``bytes``.
|
||||
|
||||
*package* is either a name or a module object which conforms to the
|
||||
``Package`` requirements. *resource* is the name of the resource to open
|
||||
within *package*; it may not contain path separators and it may not have
|
||||
sub-resources (i.e. it cannot be a directory). This function returns the
|
||||
contents of the resource as :class:`bytes`.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
Calls to this function can be replaced by::
|
||||
|
||||
files(package).joinpath(resource).read_bytes()
|
||||
|
||||
|
||||
.. function:: read_text(package, resource, encoding='utf-8', errors='strict')
|
||||
|
||||
Read and return the contents of *resource* within *package* as a ``str``.
|
||||
By default, the contents are read as strict UTF-8.
|
||||
|
||||
*package* is either a name or a module object which conforms to the
|
||||
``Package`` requirements. *resource* is the name of the resource to open
|
||||
within *package*; it may not contain path separators and it may not have
|
||||
sub-resources (i.e. it cannot be a directory). *encoding* and *errors*
|
||||
have the same meaning as with built-in :func:`open`. This function
|
||||
returns the contents of the resource as :class:`str`.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
Calls to this function can be replaced by::
|
||||
|
||||
files(package).joinpath(resource).read_text(encoding=encoding)
|
||||
|
||||
|
||||
.. function:: path(package, resource)
|
||||
|
||||
Return the path to the *resource* as an actual file system path. This
|
||||
function returns a context manager for use in a :keyword:`with` statement.
|
||||
The context manager provides a :class:`pathlib.Path` object.
|
||||
|
||||
Exiting the context manager cleans up any temporary file created when the
|
||||
resource needs to be extracted from e.g. a zip file.
|
||||
|
||||
*package* is either a name or a module object which conforms to the
|
||||
``Package`` requirements. *resource* is the name of the resource to open
|
||||
within *package*; it may not contain path separators and it may not have
|
||||
sub-resources (i.e. it cannot be a directory).
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
Calls to this function can be replaced using :func:`as_file`::
|
||||
|
||||
as_file(files(package).joinpath(resource))
|
||||
|
||||
|
||||
.. function:: is_resource(package, name)
|
||||
|
||||
Return ``True`` if there is a resource named *name* in the package,
|
||||
otherwise ``False``.
|
||||
This function does not consider directories to be resources.
|
||||
*package* is either a name or a module object which conforms to the
|
||||
``Package`` requirements.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
Calls to this function can be replaced by::
|
||||
|
||||
files(package).joinpath(resource).is_file()
|
||||
|
||||
|
||||
.. function:: contents(package)
|
||||
|
||||
Return an iterable over the named items within the package. The iterable
|
||||
returns :class:`str` resources (e.g. files) and non-resources
|
||||
(e.g. directories). The iterable does not recurse into subdirectories.
|
||||
|
||||
*package* is either a name or a module object which conforms to the
|
||||
``Package`` requirements.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
Calls to this function can be replaced by::
|
||||
|
||||
(resource.name for resource in files(package).iterdir() if resource.is_file())
|
||||
|
|
|
|||
|
|
@ -6,31 +6,12 @@ from ._common import (
|
|||
Package,
|
||||
)
|
||||
|
||||
from ._legacy import (
|
||||
contents,
|
||||
open_binary,
|
||||
read_binary,
|
||||
open_text,
|
||||
read_text,
|
||||
is_resource,
|
||||
path,
|
||||
Resource,
|
||||
)
|
||||
|
||||
from .abc import ResourceReader
|
||||
|
||||
|
||||
__all__ = [
|
||||
'Package',
|
||||
'Resource',
|
||||
'ResourceReader',
|
||||
'as_file',
|
||||
'contents',
|
||||
'files',
|
||||
'is_resource',
|
||||
'open_binary',
|
||||
'open_text',
|
||||
'path',
|
||||
'read_binary',
|
||||
'read_text',
|
||||
]
|
||||
|
|
|
|||
|
|
@ -1,120 +0,0 @@
|
|||
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: 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))
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
Removed ``_legacy`` and the names it provided from ``importlib.resources``:
|
||||
``Resource``, ``contents``, ``is_resource``, ``open_binary``, ``open_text``,
|
||||
``path``, ``read_binary``, and ``read_text``.
|
||||
Loading…
Reference in New Issue