gh-51067: Add remove() and repack() to ZipFile (GH-134627)

The docs included in the commit do the best job of describing this.

Much discussion on the PR and issue.

thank you to to core team folks jaraco, emmatyping, gpshead, and all others who added their constructive comments along the way.

---------

Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
Co-authored-by: Gregory P. Smith <greg@krypto.org>

Author: 3 people

Doc/library/zipfile.rst

@@ -550,6 +550,94 @@ ZipFile objects
    .. versionadded:: 3.11
 
 
+.. method:: ZipFile.remove(zinfo_or_arcname)
+
+   Removes a member entry from the archive's central directory.
+   *zinfo_or_arcname* may be the full path of the member or a :class:`ZipInfo`
+   instance.  If multiple members share the same full path and the path is
+   given as a string, only one of them is removed and which one is unspecified;
+   it should not be relied upon.  Pass the specific :class:`ZipInfo` instance to
+   remove a particular member.
+
+   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`.
+
+   .. note::
+      This method only removes the member's entry from the central directory,
+      making it inaccessible to most tools.  The member's local file entry,
+      including content and metadata, remains in the archive and is still
+      recoverable using forensic tools.  Call :meth:`repack` afterwards to
+      remove the local file entry and reclaim space; pass the returned
+      :class:`ZipInfo` to :meth:`repack` to ensure the data is removed
+      regardless of how the entry was written.
+
+   .. versionadded:: next
+
+
+.. method:: ZipFile.repack(removed=None, *, \
+                           strict_descriptor=True[, chunk_size])
+
+   Rewrites the archive to remove unreferenced local file entries, shrinking
+   its file size.  The archive must be opened with mode ``'a'``.
+
+   If *removed* is provided, it must be a sequence of :class:`ZipInfo` objects
+   representing the recently removed members, and only their corresponding
+   local file entries will be removed.  Otherwise, the archive is scanned to
+   locate and remove local file entries that are no longer referenced in the
+   central directory.
+
+   Passing *removed* is the most reliable way to reclaim space: the
+   corresponding local file entries are located directly from the central
+   directory and removed regardless of how they were written, whereas the scan
+   used when *removed* is omitted may leave some entries in place (see
+   *strict_descriptor* below).  To remove members and reclaim their space in a
+   single step::
+
+      with ZipFile('spam.zip', 'a') as myzip:
+          removed = [myzip.remove(name) for name in ('ham.txt', 'eggs.txt')]
+          myzip.repack(removed)
+
+   When scanning, *strict_descriptor* controls how entries written with an
+   unsigned *data descriptor* are handled.  A data descriptor is an optional
+   record holding an entry's CRC and sizes, stored just after the entry's data;
+   it is used when the archive is written to a non-seekable stream, and is
+   *signed* when it begins with a marker signature or *unsigned* otherwise.
+   Unsigned descriptors have been deprecated by the `PKZIP Application Note`_
+   since version 6.3.0 (released in 2006) and are written only by some legacy
+   tools; signed descriptors—written by Python and other modern tools—are always
+   detected.  When *strict_descriptor* is true (the default), only signed data
+   descriptors are detected, so an unreferenced entry written with an unsigned
+   descriptor is not located and its space is not reclaimed by the scan.
+   Setting ``strict_descriptor=False`` additionally detects unsigned
+   descriptors, at the cost of a significantly slower scan—around 100 to 1000
+   times in the worst case—which may be exploitable as a denial-of-service
+   vector on untrusted input.  This does not affect entries without a data
+   descriptor, and is not needed when *removed* is provided.
+
+   *chunk_size* may be specified to control the buffer size when moving
+   entry data (default is 1 MiB).
+
+   Calling :meth:`repack` on a closed ZipFile will raise a :exc:`ValueError`.
+
+   .. note::
+      The scanning algorithm is heuristic-based and assumes that the ZIP file
+      is normally structured—for example, with local file entries stored
+      consecutively, without overlap or interleaved binary data.  Prepended
+      binary data, such as a self-extractor stub, is recognized and preserved
+      unless it happens to contain bytes that coincidentally resemble a valid
+      local file entry in multiple respects—an extremely rare case. Embedded
+      ZIP payloads are also handled correctly, as long as they follow normal
+      structure.  However, the algorithm does not guarantee correctness or
+      safety on untrusted or intentionally crafted input.  It is generally
+      recommended to provide the *removed* argument for better reliability and
+      performance.
+
+   .. versionadded:: next
+
+
 The following data attributes are also available:
 
 .. attribute:: ZipFile.filename

Doc/whatsnew/3.16.rst

@@ -172,6 +172,15 @@ xml
   instead of failing later, when encounter non-ASCII data.
   (Contributed by Serhiy Storchaka in :gh:`62259`.)
 
+zipfile
+-------
+
+* Add :meth:`ZipFile.remove() <zipfile.ZipFile.remove>` to remove a member
+  from an archive's central directory, and
+  :meth:`ZipFile.repack() <zipfile.ZipFile.repack>` to reclaim the space used
+  by the local file entries of removed members.
+  (Contributed by Danny Lin in :gh:`51067`.)
+
 .. Add improved modules above alphabetically, not here at the end.
 
 Optimizations