Содержание страницы

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

Исходный код: Lib/zipfile.py

Формат ZIP – распространённый стандарт архивации и сжатия. Этот модуль предоставляет инструменты для создания, чтения, записи, добавления и просмотра содержимого ZIP-файлов. Любое продвинутое использование модуля требует понимания формата, описанного в PKZIP Application Note.

Модуль пока не поддерживает многодисковые ZIP-файлы. Он может обрабатывать ZIP-файлы, использующие расширения ZIP64 (то есть ZIP-файлы размером более 4 ГБ). Поддерживается расшифровка зашифрованных файлов в ZIP-архивах, но пока невозможно создать зашифрованный файл. Расшифровка выполняется очень медленно, так как реализована на чистом Python, а не на C.

Модуль определяет следующие элементы:

exception zipfile.BadZipFile¶: Исключение, возникающее при повреждённых ZIP-файлах.

Новое в версии 3.2.

exception zipfile.BadZipfile¶: Псевдоним BadZipFile для совместимости со старыми версиями Python.

Устарело с версии 3.2.

exception zipfile.LargeZipFile¶: Исключение, возникающее, когда ZIP-файлу требуется функциональность ZIP64, но она не включена.

class zipfile.ZipFile: Класс для чтения и записи ZIP-файлов. Подробнее о конструкторе см. раздел Объекты ZipFile.

class zipfile.PyZipFile: Класс для создания ZIP-архивов, содержащих библиотеки Python.

class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))¶: Класс, используемый для представления информации об элементе архива. Экземпляры этого класса возвращаются методами getinfo() и infolist() объектов ZipFile. Большинству пользователей модуля zipfile не нужно создавать такие объекты, достаточно использовать те, что созданы этим модулем. Параметр filename должен содержать полное имя элемента архива, а date_time – кортеж из шести полей, описывающих время последнего изменения файла; эти поля описаны в разделе ZipInfo Objects.

zipfile.is_zipfile(filename)¶: Возвращает True, если filename является допустимым ZIP-файлом на основе его сигнатуры, в противном случае возвращает False. Параметр filename может быть файлом или файлоподобным объектом.

Изменено в версии 3.1: Добавлена поддержка файлов и файлоподобных объектов.

zipfile.ZIP_STORED¶: Числовая константа для несжатого элемента архива.

zipfile.ZIP_DEFLATED¶: Числовая константа для обычного метода сжатия ZIP. Требует модуль zlib.

zipfile.ZIP_BZIP2¶: Числовая константа для метода сжатия BZIP2. Требует модуль bz2.

Новое в версии 3.3.

zipfile.ZIP_LZMA¶: Числовая константа для метода сжатия LZMA. Требует модуль lzma.

Новое в версии 3.3.

Примечание

Спецификация формата ZIP поддерживает сжатие bzip2 с 2001 года и сжатие LZMA с 2006 года. Однако некоторые инструменты (включая старые версии Python) не поддерживают эти методы сжатия и могут либо полностью отказаться обрабатывать ZIP-файл, либо не извлечь отдельные файлы.

См. также

Примечание по применению PKZIP: Документация по формату ZIP-файлов от Фила Каца, создателя формата и используемых алгоритмов.
Домашняя страница Info-ZIP: Информация о программах для работы с ZIP-архивами и библиотеках для разработки проекта Info-ZIP.

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

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

Открывает 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 GiB. Если же установлено ложное значение (по умолчанию), zipfile возбудит исключение, когда ZIP-файлу потребуются расширения ZIP64. Расширения ZIP64 отключены по умолчанию, так как стандартные команды zip и unzip в Unix (утилиты InfoZIP) не поддерживают их.

Если файл создан в режиме '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.

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.

Примечание

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

Примечание

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

Примечание

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

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, например, элементов с абсолютными именами, начинающимися с "/", или с именами, содержащими две точки "..".

Изменено в версии 3.3.1: Модуль zipfile пытается это предотвратить. См. примечание к extract().

ZipFile.printdir()¶: Выводит оглавление архива в sys.stdout.

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

ZipFile.read(name, pwd=None)¶: Возвращает байты файла name в архиве. name – это имя файла в архиве или объект ZipInfo. Архив должен быть открыт для чтения или добавления. pwd – пароль, используемый для зашифрованных файлов; если указан, он переопределяет пароль по умолчанию, заданный с помощью setpassword(). Вызов read() на закрытом ZipFile приведёт к возникновению RuntimeError.

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=False, optimize=-1)¶

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

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

writepy(pathname, basename='')¶

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

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

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

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

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

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)