SQUASHME: Added comments to tests

Author: pR0Ps

Lib/test/test_zipfile/test_core.py

@@ -1082,6 +1082,26 @@ def test_generated_valid_zip64_extra(self):
 
     def test_force_zip64(self):
         """Test that forcing zip64 extensions correctly notes this in the zip file"""
+
+        # GH-103861 describes an issue where forcing a small file to use zip64
+        # extensions would add a zip64 extra record, but not change the
+        # compressed lengths to 0xFFFFFFFF to indicate to the extractor that
+        # the zip64 record should be read. Additionally, it would not set the
+        # required version to indicate that zip64 extensions are required to
+        # extract it.
+        # This test replicates the situation and reads the raw data to specifically ensure:
+        #  - The required extract version is always >= ZIP64_VERSION
+        #  - The compressed and uncompressed size in the file headers are both
+        #     0xFFFFFFFF (ie. point to zip64 record)
+        #  - The zip64 record is provided and has the correct sizes in it
+        # Other aspects of the zip are checked as well, but verifying the above is the main goal.
+        # Because this is hard to verify by parsing the data as a zip, the raw
+        # bytes are checked to ensure that they line up with the zip spec.
+        # The spec for this can be found at: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
+        # The relevent sections for this test are:
+        #  - 4.3.7 for local file header
+        #  - 4.5.3 for zip64 extra field
+
         data = io.BytesIO()
         with zipfile.ZipFile(data, mode="w", allowZip64=True) as zf:
             with zf.open("text.txt", mode="w", force_zip64=True) as zi:
@@ -1141,6 +1161,19 @@ def make_zip(fp):
     def test_unseekable_zip_known_filesize(self):
         """Test that creating a zip without seeking will use zip64 extensions if the file size is provided up-front"""
 
+        # This test ensures that the zip will use a zip64 data descriptor (same
+        # as a regular data descriptor except the sizes are 8 bytes instead of
+        # 4) record to communicate the size of a file if the zip is being
+        # written to an unseekable stream.
+        # Because this sort of thing is hard to verify by parsing the data back
+        # in as a zip, this test looks at the raw bytes created to ensure that
+        # the correct data has been generated.
+        # The spec for this can be found at: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
+        # The relevent sections for this test are:
+        #  - 4.3.7 for local file header
+        #  - 4.3.9 for the data descriptor
+        #  - 4.5.3 for zip64 extra field
+
         file_size = zipfile.ZIP64_LIMIT + 1
 
         def make_zip(fp):
@@ -1160,7 +1193,7 @@ def make_zip(fp):
             cd_sig
         ) = struct.unpack("<4sBBHH8xIIHH8shhQQ{}x4s".format(file_size), seekable_data[:62 + file_size])
 
-        self.assertEqual(header, b"PK\x03\x04")
+        self.assertEqual(header, b"PK\x03\x04")  # local file header
         self.assertGreaterEqual(vers, zipfile.ZIP64_VERSION)  # requires zip64 to extract
         self.assertEqual(os, 0)  # compatible with MS-DOS
         self.assertEqual(flags, 0)  # no flags set
@@ -1183,7 +1216,7 @@ def make_zip(fp):
             dd_header, dd_usize, dd_csize, cd_sig
         ) = struct.unpack("<4sBBHH8xIIHH8shhQQ{}x4s4xQQ4s".format(file_size), unseekable_data[:86 + file_size])
 
-        self.assertEqual(header, b"PK\x03\x04")
+        self.assertEqual(header, b"PK\x03\x04")  # local file header
         self.assertGreaterEqual(vers, zipfile.ZIP64_VERSION)  # requires zip64 to extract
         self.assertEqual(os, 0)  # compatible with MS-DOS
         self.assertEqual("{:b}".format(flags), "1000")  # streaming flag set