mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-11 11:31:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

gh-106531: Remove importlib.resources._legacy (#106532)

Browse source 
* 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 2023-07-14 13:38:28 -04:00 • committed by GitHub
parent 7c95345e4f
commit 243fdcb40e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 3 additions and 295 deletions
Download patch file Download diff file Expand all files Collapse all files

156
Doc/library/importlib.resources.rst
View file

@ -94,159 +94,3 @@ for example, a package and its resources can be imported from a zip file using
the file system is required. the file system is required.
.. versionadded:: 3.9 .. 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())

19
Lib/importlib/resources/__init__.py
View file

@ -6,31 +6,12 @@ from ._common import (
Package, Package,
) )
from ._legacy import (
contents,
open_binary,
read_binary,
open_text,
read_text,
is_resource,
path,
Resource,
)
from .abc import ResourceReader from .abc import ResourceReader
__all__ = [ __all__ = [
'Package', 'Package',
'Resource',
'ResourceReader', 'ResourceReader',
'as_file', 'as_file',
'contents',
'files', 'files',
'is_resource',
'open_binary',
'open_text',
'path',
'read_binary',
'read_text',
] ]

120
Lib/importlib/resources/_legacy.py
View file

@ -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))

3
Misc/NEWS.d/next/Library/2023-07-07-16-19-59.gh-issue-106531.eMfNm8.rst Normal file
View file

@ -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``.