Debian Codegraph @

Lib/zipfile/_path/__init__.py

raw
1 """
2 A Path-like interface for zipfiles.
3
4 This codebase is shared between zipfile.Path in the stdlib
5 and zipp in PyPI. See
6 https://github.com/python/importlib_metadata/wiki/Development-Methodology
7 for more detail.
8 """
9
10 import contextlib
11 import io
12 import itertools
13 import pathlib
14 import posixpath
15 import re
16 import stat
17 import sys
18 import zipfile
19
20 from .glob import Translator
21
22 __all__ = ['Path']
23
24
25 def _parents(path):
26 """
27 Given a path with elements separated by
28 posixpath.sep, generate all parents of that path.
29
30 >>> list(_parents('b/d'))
31 ['b']
32 >>> list(_parents('/b/d/'))
33 ['/b']
34 >>> list(_parents('b/d/f/'))
35 ['b/d', 'b']
36 >>> list(_parents('b'))
37 []
38 >>> list(_parents(''))
39 []
40 """
41 return itertools.islice(_ancestry(path), 1, None)
42
43
44 def _ancestry(path):
45 """
46 Given a path with elements separated by
47 posixpath.sep, generate all elements of that path.
48
49 >>> list(_ancestry('b/d'))
50 ['b/d', 'b']
51 >>> list(_ancestry('/b/d/'))
52 ['/b/d', '/b']
53 >>> list(_ancestry('b/d/f/'))
54 ['b/d/f', 'b/d', 'b']
55 >>> list(_ancestry('b'))
56 ['b']
57 >>> list(_ancestry(''))
58 []
59
60 Multiple separators are treated like a single.
61
62 >>> list(_ancestry('//b//d///f//'))
63 ['//b//d///f', '//b//d', '//b']
64 """
65 path = path.rstrip(posixpath.sep)
66 while path.rstrip(posixpath.sep):
67 yield path
68 path, tail = posixpath.split(path)
69
70
71 _dedupe = dict.fromkeys
72 """Deduplicate an iterable in original order"""
73
74
75 def _difference(minuend, subtrahend):
76 """
77 Return items in minuend not in subtrahend, retaining order
78 with O(1) lookup.
79 """
80 return itertools.filterfalse(set(subtrahend).__contains__, minuend)
81
82
83 class InitializedState:
84 """
85 Mix-in to save the initialization state for pickling.
86 """
87
88 def __init__(self, *args, **kwargs):
89 self.__args = args
90 self.__kwargs = kwargs
91 super().__init__(*args, **kwargs)
92
93 def __getstate__(self):
94 return self.__args, self.__kwargs
95
96 def __setstate__(self, state):
97 args, kwargs = state
98 super().__init__(*args, **kwargs)
99
100
101 class CompleteDirs(InitializedState, zipfile.ZipFile):
102 """
103 A ZipFile subclass that ensures that implied directories
104 are always included in the namelist.
105
106 >>> list(CompleteDirs._implied_dirs(['foo/bar.txt', 'foo/bar/baz.txt']))
107 ['foo/', 'foo/bar/']
108 >>> list(CompleteDirs._implied_dirs(['foo/bar.txt', 'foo/bar/baz.txt', 'foo/bar/']))
109 ['foo/']
110 """
111
112 @staticmethod
113 def _implied_dirs(names):
114 parents = itertools.chain.from_iterable(map(_parents, names))
115 as_dirs = (p + posixpath.sep for p in parents)
116 return _dedupe(_difference(as_dirs, names))
117
118 def namelist(self):
119 names = super().namelist()
120 return names + list(self._implied_dirs(names))
121
122 def _name_set(self):
123 return set(self.namelist())
124
125 def resolve_dir(self, name):
126 """
127 If the name represents a directory, return that name
128 as a directory (with the trailing slash).
129 """
130 names = self._name_set()
131 dirname = name + '/'
132 dir_match = name not in names and dirname in names
133 return dirname if dir_match else name
134
135 def getinfo(self, name):
136 """
137 Supplement getinfo for implied dirs.
138 """
139 try:
140 return super().getinfo(name)
141 except KeyError:
142 if not name.endswith('/') or name not in self._name_set():
143 raise
144 return zipfile.ZipInfo(filename=name)
145
146 @classmethod
147 def make(cls, source):
148 """
149 Given a source (filename or zipfile), return an
150 appropriate CompleteDirs subclass.
151 """
152 if isinstance(source, CompleteDirs):
153 return source
154
155 if not isinstance(source, zipfile.ZipFile):
156 return cls(source)
157
158 # Only allow for FastLookup when supplied zipfile is read-only
159 if 'r' not in source.mode:
160 cls = CompleteDirs
161
162 source.__class__ = cls
163 return source
164
165 @classmethod
166 def inject(cls, zf: zipfile.ZipFile) -> zipfile.ZipFile:
167 """
168 Given a writable zip file zf, inject directory entries for
169 any directories implied by the presence of children.
170 """
171 for name in cls._implied_dirs(zf.namelist()):
172 zf.writestr(name, b"")
173 return zf
174
175
176 class FastLookup(CompleteDirs):
177 """
178 ZipFile subclass to ensure implicit
179 dirs exist and are resolved rapidly.
180 """
181
182 def namelist(self):
183 with contextlib.suppress(AttributeError):
184 return self.__names
185 self.__names = super().namelist()
186 return self.__names
187
188 def _name_set(self):
189 with contextlib.suppress(AttributeError):
190 return self.__lookup
191 self.__lookup = super()._name_set()
192 return self.__lookup
193
194 def _extract_text_encoding(encoding=None, *args, **kwargs):
195 # compute stack level so that the caller of the caller sees any warning.
196 is_pypy = sys.implementation.name == 'pypy'
197 # PyPy no longer special cased after 7.3.19 (or maybe 7.3.18)
198 # See jaraco/zipp#143
199 is_old_pypi = is_pypy and sys.pypy_version_info < (7, 3, 19)
200 stack_level = 3 + is_old_pypi
201 return io.text_encoding(encoding, stack_level), args, kwargs
202
203
204 class Path:
205 """
206 A :class:`importlib.resources.abc.Traversable` interface for zip files.
207
208 Implements many of the features users enjoy from
209 :class:`pathlib.Path`.
210
211 Consider a zip file with this structure::
212
213 .
214 ├── a.txt
215 └── b
216 ├── c.txt
217 └── d
218 └── e.txt
219
220 >>> data = io.BytesIO()
221 >>> zf = ZipFile(data, 'w')
222 >>> zf.writestr('a.txt', 'content of a')
223 >>> zf.writestr('b/c.txt', 'content of c')
224 >>> zf.writestr('b/d/e.txt', 'content of e')
225 >>> zf.filename = 'mem/abcde.zip'
226
227 Path accepts the zipfile object itself or a filename
228
229 >>> path = Path(zf)
230
231 From there, several path operations are available.
232
233 Directory iteration (including the zip file itself):
234
235 >>> a, b = path.iterdir()
236 >>> a
237 Path('mem/abcde.zip', 'a.txt')
238 >>> b
239 Path('mem/abcde.zip', 'b/')
240
241 name property:
242
243 >>> b.name
244 'b'
245
246 join with divide operator:
247
248 >>> c = b / 'c.txt'
249 >>> c
250 Path('mem/abcde.zip', 'b/c.txt')
251 >>> c.name
252 'c.txt'
253
254 Read text:
255
256 >>> c.read_text(encoding='utf-8')
257 'content of c'
258
259 existence:
260
261 >>> c.exists()
262 True
263 >>> (b / 'missing.txt').exists()
264 False
265
266 Coercion to string:
267
268 >>> import os
269 >>> str(c).replace(os.sep, posixpath.sep)
270 'mem/abcde.zip/b/c.txt'
271
272 At the root, ``name``, ``filename``, and ``parent``
273 resolve to the zipfile.
274
275 >>> str(path)
276 'mem/abcde.zip/'
277 >>> path.name
278 'abcde.zip'
279 >>> path.filename == pathlib.Path('mem/abcde.zip')
280 True
281 >>> str(path.parent)
282 'mem'
283
284 If the zipfile has no filename, such attributes are not
285 valid and accessing them will raise an Exception.
286
287 >>> zf.filename = None
288 >>> path.name
289 Traceback (most recent call last):
290 ...
291 TypeError: ...
292
293 >>> path.filename
294 Traceback (most recent call last):
295 ...
296 TypeError: ...
297
298 >>> path.parent
299 Traceback (most recent call last):
300 ...
301 TypeError: ...
302
303 # workaround python/cpython#106763
304 >>> pass
305 """
306
307 __repr = "{self.__class__.__name__}({self.root.filename!r}, {self.at!r})"
308
309 def __init__(self, root, at=""):
310 """
311 Construct a Path from a ZipFile or filename.
312
313 Note: When the source is an existing ZipFile object,
314 its type (__class__) will be mutated to a
315 specialized type. If the caller wishes to retain the
316 original type, the caller should either create a
317 separate ZipFile object or pass a filename.
318 """
319 self.root = FastLookup.make(root)
320 self.at = at
321
322 def __eq__(self, other):
323 """
324 >>> Path(zipfile.ZipFile(io.BytesIO(), 'w')) == 'foo'
325 False
326 """
327 if self.__class__ is not other.__class__:
328 return NotImplemented
329 return (self.root, self.at) == (other.root, other.at)
330
331 def __hash__(self):
332 return hash((self.root, self.at))
333
334 def open(self, mode='r', *args, pwd=None, **kwargs):
335 """
336 Open this entry as text or binary following the semantics
337 of ``pathlib.Path.open()`` by passing arguments through
338 to io.TextIOWrapper().
339 """
340 if self.is_dir():
341 raise IsADirectoryError(self)
342 zip_mode = mode[0]
343 if zip_mode == 'r' and not self.exists():
344 raise FileNotFoundError(self)
345 stream = self.root.open(self.at, zip_mode, pwd=pwd)
346 if 'b' in mode:
347 if args or kwargs:
348 raise ValueError("encoding args invalid for binary operation")
349 return stream
350 # Text mode:
351 encoding, args, kwargs = _extract_text_encoding(*args, **kwargs)
352 return io.TextIOWrapper(stream, encoding, *args, **kwargs)
353
354 def _base(self):
355 return pathlib.PurePosixPath(self.at) if self.at else self.filename
356
357 @property
358 def name(self):
359 return self._base().name
360
361 @property
362 def suffix(self):
363 return self._base().suffix
364
365 @property
366 def suffixes(self):
367 return self._base().suffixes
368
369 @property
370 def stem(self):
371 return self._base().stem
372
373 @property
374 def filename(self):
375 return pathlib.Path(self.root.filename).joinpath(self.at)
376
377 def read_text(self, *args, **kwargs):
378 encoding, args, kwargs = _extract_text_encoding(*args, **kwargs)
379 with self.open('r', encoding, *args, **kwargs) as strm:
380 return strm.read()
381
382 def read_bytes(self):
383 with self.open('rb') as strm:
384 return strm.read()
385
386 def _is_child(self, path):
387 return posixpath.dirname(path.at.rstrip("/")) == self.at.rstrip("/")
388
389 def _next(self, at):
390 return self.__class__(self.root, at)
391
392 def is_dir(self):
393 return not self.at or self.at.endswith("/")
394
395 def is_file(self):
396 return self.exists() and not self.is_dir()
397
398 def exists(self):
399 return self.at in self.root._name_set()
400
401 def iterdir(self):
402 if not self.is_dir():
403 raise ValueError("Can't listdir a file")
404 subs = map(self._next, self.root.namelist())
405 return filter(self._is_child, subs)
406
407 def match(self, path_pattern):
408 return pathlib.PurePosixPath(self.at).match(path_pattern)
409
410 def is_symlink(self):
411 """
412 Return whether this path is a symlink.
413 """
414 info = self.root.getinfo(self.at)
415 mode = info.external_attr >> 16
416 return stat.S_ISLNK(mode)
417
418 def glob(self, pattern):
419 if not pattern:
420 raise ValueError(f"Unacceptable pattern: {pattern!r}")
421
422 prefix = re.escape(self.at)
423 tr = Translator(seps='/')
424 matches = re.compile(prefix + tr.translate(pattern)).fullmatch
425 return map(self._next, filter(matches, self.root.namelist()))
426
427 def rglob(self, pattern):
428 return self.glob(f'**/{pattern}')
429
430 def relative_to(self, other, *extra):
431 return posixpath.relpath(str(self), str(other.joinpath(*extra)))
432
433 def __str__(self):
434 return posixpath.join(self.root.filename, self.at)
435
436 def __repr__(self):
437 return self.__repr.format(self=self)
438
439 def joinpath(self, *other):
440 next = posixpath.join(self.at, *other)
441 return self._next(self.root.resolve_dir(next))
442
443 __truediv__ = joinpath
444
445 @property
446 def parent(self):
447 if not self.at:
448 return self.filename.parent
449 parent_at = posixpath.dirname(self.at.rstrip('/'))
450 if parent_at:
451 parent_at += '/'
452 return self._next(parent_at)