Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/importlib_resources/_legacy.py: 64%

1import functools 

2import os 

3import pathlib 

4import types 

5import warnings 

6 

7from typing import Union, Iterable, ContextManager, BinaryIO, TextIO, Any 

8 

9from . import _common 

10 

11Package = Union[types.ModuleType, str] 

12Resource = str 

13 

14 

15def 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 

30def 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 

43def 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 

49def 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 

55def 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 

68def 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 

84def 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 

95def 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 

108def 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))