13.5. zipfile – Работа с ZIP-архивами¶zipfile – Work with ZIP archives

13.5.1. Объекты ZipFile¶ZipFile Objects

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True)¶

Открывает ZIP-файл. Параметр file может быть путём к файлу (строкой) или файлоподобным объектом. Параметр mode должен быть 'r' для чтения существующего файла, 'w' для создания нового (с усечением) или 'a' для добавления к существующему файлу. Если mode равен 'a' и file указывает на существующий ZIP- файл, в него добавляются новые файлы. Если file не указывает на ZIP-файл, то новый ZIP-архив добавляется в конец этого файла. Это предназначено для добавления ZIP-архива внутрь другого файла (например, python.exe). Если mode равен a и файл вообще не существует, он создаётся. compression – метод сжатия ZIP, используемый при записи архива; должен быть ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2 или ZIP_LZMA; нераспознанные значения приведут к возбуждению RuntimeError. Если указан ZIP_DEFLATED, ZIP_BZIP2 или ZIP_LZMA, но соответствующий модуль (zlib, bz2 или lzma) недоступен, также возбуждается RuntimeError. Значение по умолчанию – ZIP_STORED. Если allowZip64 равен True (значение по умолчанию), zipfile создаёт ZIP-файлы с использованием расширений ZIP64, когда размер архива превышает 2 ГБ. Если он равен False, zipfile возбудит исключение, когда ZIP-файл потребует расширений ZIP64.

Если файл создан в режиме 'a' или 'w', а затем закрыт без добавления файлов в архив, в файл будут записаны соответствующие структуры ZIP для пустого архива.

ZipFile также является контекстным менеджером, поэтому поддерживает инструкцию with. В примере myzip закрывается после завершения блока инструкции with, даже если возникло исключение:

with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')

Новое в версии 3.2: Добавлена возможность использовать ZipFile в качестве контекстного менеджера.

Изменено в версии 3.3: Добавлена поддержка сжатия bzip2 и lzma.

Изменено в версии 3.4: Расширения ZIP64 включены по умолчанию.

ZipFile.close()¶

Закрывает файл архива. Необходимо вызвать close() перед выходом из программы, иначе важные записи не будут записаны.

ZipFile.getinfo(name)¶

Возвращает объект ZipInfo с информацией об элементе архива name. Вызов getinfo() для имени, отсутствующего в архиве, возбуждает KeyError.

ZipFile.infolist()¶

Возвращает список, содержащий объект ZipInfo для каждого элемента архива. Объекты расположены в том же порядке, что и соответствующие записи в реальном ZIP- файле на диске (если был открыт существующий архив).

ZipFile.namelist()¶

Возвращает список элементов архива по именам.

ZipFile.open(name, mode='r', pwd=None)¶

Извлекает элемент из архива в виде файлоподобного объекта (ZipExtFile). name – это имя файла в архиве или объект ZipInfo. Параметр mode, если указан, должен быть одним из следующих: 'r' (по умолчанию), 'U' или 'rU'. Выбор 'U' или 'rU' включает поддержку универсальных символов новой строки в объекте, доступном только для чтения. pwd – это пароль для зашифрованных файлов. Вызов open() на закрытом ZipFile вызовет RuntimeError.

open() также является контекстным менеджером и поэтому поддерживает оператор with:

with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())

Примечание

Файлоподобный объект доступен только для чтения и предоставляет следующие методы: read(), readline(), readlines(), __iter__(), __next__().

Примечание

Если ZipFile был создан путём передачи файлоподобного объекта в качестве первого аргумента конструктора, то объект, возвращаемый open(), разделяет файловый указатель ZipFile. В таких условиях объект, возвращаемый open(), не следует использовать после выполнения любых дополнительных операций над объектом ZipFile. Если ZipFile был создан путём передачи строки (имени файла) в качестве первого аргумента конструктора, то open() создаст новый файловый объект, который будет удерживаться ZipExtFile, что позволяет ему работать независимо от ZipFile.

Примечание

Методы open(), read() и extract() могут принимать имя файла или объект ZipInfo. Это пригодится при попытке прочитать ZIP-файл, содержащий элементы с повторяющимися именами.

Устарело с версии 3.4, будет удалено в версии 3.6: Режимы 'U' или 'rU'. Используйте io.TextIOWrapper для чтения сжатых текстовых файлов в режиме универсальных новых строк.

ZipFile.extract(member, path=None, pwd=None)¶

Извлекает элемент из архива в текущий рабочий каталог; member должно быть его полным именем или объектом ZipInfo). Информация о файле извлекается максимально точно. path задаёт другой каталог для извлечения. member может быть именем файла или объектом ZipInfo. pwd – это пароль для зашифрованных файлов.

Возвращает нормализованный путь (каталог или новый файл).

Примечание

Если имя файла элемента является абсолютным путём, то буква диска/UNC-точка и начальные (обратные) слеши будут удалены, например: ///foo/bar становится foo/bar в Unix, а C:\foo\bar становится foo\bar в Windows. И все компоненты ".." в имени файла элемента будут удалены, например: ../../foo../../ba..r становится foo../ba..r. В Windows недопустимые символы (:, <, >, |, ", ? и *) заменяются символом подчёркивания (_).

ZipFile.extractall(path=None, members=None, pwd=None)¶

Извлекает все элементы из архива в текущий рабочий каталог. path задаёт другой каталог для извлечения. members является необязательным и должен быть подмножеством списка, возвращаемого namelist(). pwd – это пароль для зашифрованных файлов.

Предупреждение

Никогда не извлекайте архивы из ненадёжных источников без предварительной проверки. Возможно создание файлов за пределами path, например, элементы с абсолютными именами файлов, начинающимися с "/", или именами файлов с двумя точками "..". Этот модуль пытается предотвратить это. См. примечание к extract().

ZipFile.printdir()¶

Выводит оглавление архива в sys.stdout.

ZipFile.setpassword(pwd)¶

Устанавливает pwd в качестве пароля по умолчанию для извлечения зашифрованных файлов.

ZipFile.read(name, pwd=None)¶

Возвращает байты файла name в архиве. name – это имя файла в архиве или объект ZipInfo. Архив должен быть открыт для чтения или дополнения. pwd – это пароль для зашифрованных файлов, и если он указан, он переопределяет пароль по умолчанию, заданный с помощью setpassword(). Вызов read() на закрытом ZipFile вызовет RuntimeError. Вызов read() на ZipFile, использующем метод сжатия, отличный от ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2 или ZIP_LZMA, вызовет NotImplementedError. Ошибка также будет вызвана, если соответствующий модуль сжатия недоступен.

ZipFile.testzip()¶

Читает все файлы в архиве и проверяет их CRC и заголовки файлов. Возвращает имя первого повреждённого файла или None, если все файлы в порядке. Вызов testzip() на закрытом ZipFile вызовет RuntimeError.

ZipFile.write(filename, arcname=None, compress_type=None)¶

Записывает файл с именем filename в архив, присваивая ему имя в архиве arcname (по умолчанию оно будет таким же, как filename, но без буквы диска и с удалёнными начальными разделителями пути). Если указан, compress_type переопределяет значение, заданное для параметра compression конструктора для новой записи. Архив должен быть открыт в режиме 'w' или 'a' – вызов write() на ZipFile, созданном в режиме 'r', вызовет RuntimeError. Вызов write() на закрытом ZipFile вызовет RuntimeError.

Примечание

Официальной кодировки имён файлов для ZIP-файлов не существует. Если используются имена файлов в Unicode, необходимо преобразовать их в байтовые строки в нужной кодировке перед передачей в write(). WinZip интерпретирует все имена файлов как закодированные в CP437, также известной как DOS Latin.

Примечание

Архивные имена должны быть относительными по отношению к корню архива, то есть не должны начинаться с разделителя пути.

Примечание

Если arcname (или filename, если arcname не указан) содержит нулевой байт, имя файла в архиве будет обрезано по нулевому байту.

ZipFile.writestr(zinfo_or_arcname, bytes[, compress_type])¶

Записывает строку bytes в архив; zinfo_or_arcname – это либо имя файла, которое будет присвоено в архиве, либо экземпляр ZipInfo. Если это экземпляр, необходимо указать как минимум имя файла, дату и время. Если это имя, дата и время устанавливаются на текущие. Архив должен быть открыт в режиме 'w' или 'a' – вызов writestr() на ZipFile, созданном в режиме 'r', вызовет RuntimeError. Вызов writestr() на закрытом ZipFile вызовет RuntimeError.

Если указан, compress_type переопределяет значение, заданное для параметра compression конструктора для новой записи, или значение в zinfo_or_arcname (если это экземпляр ZipInfo).

Примечание

При передаче экземпляра ZipInfo в качестве параметра zinfo_or_arcname используемый метод сжатия будет тем, который указан в члене compress_type данного экземпляра ZipInfo. По умолчанию конструктор ZipInfo устанавливает этот член в ZIP_STORED.

Изменено в версии 3.2: Аргумент compress_type.

Также доступны следующие атрибуты данных:

ZipFile.debug¶

Уровень отладочного вывода. Может быть установлен от 0 (по умолчанию, без вывода) до 3 (максимальный вывод). Отладочная информация записывается в sys.stdout.

ZipFile.comment¶

Текст комментария, связанного с ZIP-файлом. Если присваивается комментарий экземпляру ZipFile, созданному в режиме 'a' или 'w', это должна быть строка длиной не более 65535 байт. Комментарии длиннее этого значения будут обрезаны в записанном архиве при вызове close().

13.5.2. Объекты PyZipFile¶PyZipFile Objects

Конструктор PyZipFile принимает те же параметры, что и конструктор ZipFile, и один дополнительный параметр optimize.

class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)¶

Новое в версии 3.2: Параметр optimize.

Изменено в версии 3.4: Расширения ZIP64 включены по умолчанию.

Помимо методов, имеющихся у объектов ZipFile, у экземпляров есть один дополнительный метод:

writepy(pathname, basename='', filterfunc=None)¶

Ищет файлы *.py и добавляет соответствующий файл в архив.

Если параметр optimize конструктора PyZipFile не был задан или равен -1, то соответствующим файлом будет *.pyo, если такой доступен, иначе *.pyc, при необходимости компилируя исходный код.

Если параметр optimize конструктора PyZipFile был равен 0, 1 или 2, в архив добавляются только файлы с этим уровнем оптимизации (см. compile()), при необходимости компилируя исходный код.

Если pathname является файлом, его имя должно оканчиваться на .py, и в корень архива (без пути) добавляется только (соответствующий *.py[co]) файл. Если pathname – файл, не оканчивающийся на .py, будет возбуждено RuntimeError. Если это каталог, и он не является каталогом пакета, то все файлы *.py[co] добавляются в корень. Если же каталог является каталогом пакета, то все *.py[co] добавляются внутрь пути, соответствующего имени пакета; если какие-то подкаталоги также являются каталогами пакетов, они обрабатываются рекурсивно.

basename предназначен только для внутреннего использования.

Параметр filterfunc, если задан, должен быть функцией, принимающей один строковый аргумент. Она будет вызываться для каждого пути (включая каждый полный путь к файлу) перед его добавлением в архив. Если filterfunc возвращает ложное значение, путь не будет добавлен, а если это каталог, его содержимое будет проигнорировано. Например, если все тестовые файлы находятся в каталогах test или начинаются со строки test_, можно использовать filterfunc для их исключения:

>>> zf = PyZipFile('myprog.zip')
>>> def notests(s):
...     fn = os.path.basename(s)
...     return (not (fn == 'test' or fn.startswith('test_')))
>>> zf.writepy('myprog', filterfunc=notests)

Метод writepy() создаёт архивы с именами файлов следующего вида:

string.pyc                   # Имя верхнего уровня
test/__init__.pyc            # Каталог пакета
test/testall.pyc             # Модуль test.testall
test/bogus/__init__.pyc      # Каталог подпакета
test/bogus/myfile.pyc        # Подмодуль test.bogus.myfile

Новое в версии 3.4: Параметр filterfunc.

13.5.3. Объекты ZipInfo¶ZipInfo Objects

Экземпляры класса ZipInfo возвращаются методами getinfo() и infolist() объектов ZipFile. Каждый объект хранит информацию об одном элементе ZIP-архива.

Экземпляры имеют следующие атрибуты:

ZipInfo.filename¶

Имя файла в архиве.

ZipInfo.date_time¶

Время и дата последнего изменения элемента архива. Это кортеж из шести значений:

Индекс	Значение
0	Год (>= 1980)
1	Месяц (начиная с 1)
2	День месяца (начиная с 1)
3	Часы (начиная с 0)
4	Минуты (начиная с 0)
5	Секунды (начиная с 0)

Примечание

Формат ZIP-файлов не поддерживает метки времени до 1980 года.

ZipInfo.compress_type¶

Тип сжатия для элемента архива.

ZipInfo.comment¶

Комментарий для отдельного элемента архива.

ZipInfo.extra¶

Данные поля расширения. В Примечании к приложению PKZIP содержатся комментарии о внутренней структуре данных, содержащихся в этой строке.

ZipInfo.create_system¶

Система, создавшая ZIP-архив.

ZipInfo.create_version¶

Версия PKZIP, создавшая ZIP-архив.

ZipInfo.extract_version¶

Версия PKZIP, необходимая для извлечения архива.

ZipInfo.reserved¶

Должно быть равно нулю.

ZipInfo.flag_bits¶

Биты флагов ZIP.

ZipInfo.volume¶

Номер тома заголовка файла.

ZipInfo.internal_attr¶

Внутренние атрибуты.

ZipInfo.external_attr¶

Внешние атрибуты файла.

ZipInfo.header_offset¶

Смещение в байтах до заголовка файла.

ZipInfo.CRC¶

CRC-32 несжатого файла.

ZipInfo.compress_size¶

Размер сжатых данных.

ZipInfo.file_size¶

Размер несжатого файла.