gh-51067: Add remove() and repack() to ZipFile
#134627
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -518,6 +518,66 @@ ZipFile Objects | |
| .. versionadded:: 3.11 | ||
|
|
||
|
|
||
| .. method:: ZipFile.remove(zinfo_or_arcname) | ||
|
|
||
| Removes a member from the archive. *zinfo_or_arcname* may be the full path | ||
| of the member or a :class:`ZipInfo` instance. | ||
|
|
||
| If multiple members share the same full path, only one is removed when | ||
| a path is provided. | ||
|
|
||
| This does not physically remove the local file entry from the archive. | ||
| Call :meth:`repack` afterwards to reclaim space. | ||
danny0838 marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| The archive must be opened with mode ``'w'``, ``'x'`` or ``'a'``. | ||
|
|
||
| Returns the removed :class:`ZipInfo` instance. | ||
|
|
||
| Calling :meth:`remove` on a closed ZipFile will raise a :exc:`ValueError`. | ||
|
|
||
| .. versionadded:: next | ||
|
|
||
|
|
||
| .. method:: ZipFile.repack(removed=None, *, \ | ||
| strict_descriptor=False[, chunk_size]) | ||
|
|
||
| Rewrites the archive to remove stale local file entries, shrinking its file | ||
| size. | ||
|
|
||
| If *removed* is provided, it must be a sequence of :class:`ZipInfo` objects | ||
| representing removed entries; only their corresponding local file entries | ||
| will be removed. | ||
|
|
||
| If *removed* is not provided, the archive is scanned to identify and remove | ||
| local file entries that are no longer referenced in the central directory. | ||
| The algorithm assumes that local file entries (and the central directory, | ||
| which is mostly treated as the "last entry") are stored consecutively: | ||
|
||
|
|
||
| #. Data before the first referenced entry is removed only when it appears to | ||
| be a sequence of consecutive entries with no extra following bytes; extra | ||
| preceding bytes are preserved. | ||
|
||
| #. Data between referenced entries is removed only when it appears to | ||
| be a sequence of consecutive entries with no extra preceding bytes; extra | ||
| following bytes are preserved. | ||
| #. Entries must not overlap. If any entry's data overlaps with another, a | ||
| :exc:`BadZipFile` error is raised and no changes are made. | ||
|
|
||
| When scanning, setting ``strict_descriptor=True`` disables detection of any | ||
|
There was a problem hiding this comment. Why not default to strict_descriptor=True given that it performs better and the zip files we expect people to be manipulating in remove/repack manners are presumed most likely to be "modern" forms? There was a problem hiding this comment. This is exactly one of the open question(#134627 (comment), #134627 (comment)). The current quick decision is primarily since it adheres better to the spec and most Python stdlib tend to prioritize compatibility than performance. E.g. |
||
| entry using an unsigned data descriptor (deprecated in the ZIP specification | ||
| since version 6.3.0, released on 2006-09-29, and used only by some legacy | ||
| tools). This improves performance, but may cause some stale entries to be | ||
| preserved. | ||
|
|
||
| *chunk_size* may be specified to control the buffer size when moving | ||
| entry data (default is 1 MiB). | ||
|
|
||
| The archive must be opened with mode ``'a'``. | ||
danny0838 marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| Calling :meth:`repack` on a closed ZipFile will raise a :exc:`ValueError`. | ||
|
|
||
| .. versionadded:: next | ||
|
|
||
|
|
||
| The following data attributes are also available: | ||
|
|
||
| .. attribute:: ZipFile.filename | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it would be good to add that which one gets removed is unspecified and should not be relied on (to defensively discourage mis-use).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually the current implementation is definite that the one mapped by
ZipFile.getinfo(name)will get removed and the last one in the filelist with the same name (if exists) will be the new mapped one.This is similar to what will be mapped by
ZipFile.getinfo(name)if there are multiple zinfos with same name. The current implementation is always the last one in the filelist, though it's also undocumented.The question is that should we document the definite behavior or state that it's actually undefined and the current behavior should not be relied on? Before the question is solved I would just keep the current statement.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think I would lean towards saying the behavior is undefined in this method. I would want some discussion about documenting the behavior with multiple zinfos.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I haven't gone back and looked, but I have a vague recollection that multiple zip entries with the same name is/was a "normal" zip file legacy-ish "feature" as that was how replacing the contents of one zip file member was implemented in cases where the entire thing cannot be rewritten as it could be done solely by rewriting the end of the file and central directory.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gpshead This is the convention of many ZIP tools, including Python, at least currently. Unfortunately it's not clearly documented in the ZIP spec.