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

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

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

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

О других форматах архивов см. модули bz2, gzip и tarfile.

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

exception zipfile.BadZipfile¶: Исключение, вызываемое для повреждённых ZIP-файлов (старое название: zipfile.error).

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

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

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

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

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

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

zipfile.ZIP_DEFLATED¶: Числовая константа для стандартного метода сжатия ZIP. Для её использования требуется модуль zlib. Другие методы сжатия в настоящее время не поддерживаются.

См. также

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

Объекты ZipFile¶ZipFile Objects

class zipfile.ZipFile(file[, mode[, compression[, allowZip64]]])

Открывает ZIP-файл. file может быть путём к файлу (строка) или объектом, похожим на файл. Параметр mode должен быть равен 'r' для чтения существующего файла, 'w' для усечения и записи нового файла, или 'a' для добавления к существующему файлу. Если mode равен 'a' и file ссылается на существующий ZIP-файл, то в него добавляются дополнительные файлы. Если file не ссылается на ZIP-файл, то к файлу добавляется новый ZIP-архив. Это предназначено для встраивания ZIP-архива в другой файл, например python.exe. Использование

cat myzip.zip >> python.exe

... тоже работает, и как минимум WinZip может читать такие файлы. Если mode равен a и файл вообще не существует, он создаётся. compression – это метод сжатия ZIP, используемый при записи архива; он должен быть ZIP_STORED или ZIP_DEFLATED; нераспознанные значения приведут к возникновению RuntimeError. Если указан ZIP_DEFLATED, но модуль zlib недоступен, также возникает RuntimeError. Значение по умолчанию – ZIP_STORED. Если allowZip64 равно True, zipfile будет создавать ZIP-файлы, использующие расширения ZIP64, когда размер архива превышает 2 ГБ. Если оно равно False (по умолчанию), zipfile вызовет исключение, когда ZIP-файлу потребуются расширения ZIP64. Расширения ZIP64 отключены по умолчанию, потому что стандартные команды zip и unzip в Unix (утилиты InfoZIP) не поддерживают эти расширения.

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

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

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

ZipFile.namelist()¶: Возвращает список элементов архива по именам.

ZipFile.open(name[, mode[, pwd]])¶: Извлекает элемент из архива в виде файлоподобного объекта (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[, pwd]])¶: Извлекает элемент из архива в текущий рабочий каталог; member должно быть его полным именем или объектом ZipInfo). Информация о файле извлекается максимально точно. path задаёт другой каталог для извлечения. member может быть именем файла или объектом ZipInfo. pwd – это пароль для зашифрованных файлов.

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

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

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

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

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

ZipFile.write(filename[, arcname[, compress_type]])¶: Записывает файл с именем 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)¶: Записывает строку bytes в архив; zinfo_or_arcname – это либо имя файла, которое будет присвоено в архиве, либо экземпляр ZipInfo. Если это экземпляр, необходимо указать как минимум имя файла, дату и время. Если это имя, дата и время устанавливаются на текущие. Архив должен быть открыт в режиме 'w' или 'a' – вызов writestr() на ZipFile, созданном в режиме 'r', вызовет RuntimeError. Вызов writestr() на закрытом ZipFile вызовет RuntimeError.

Примечание

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

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

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

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

Объекты PyZipFile¶PyZipFile Objects

Конструктор PyZipFile принимает те же параметры, что и конструктор ZipFile. Экземпляры имеют один дополнительный метод по сравнению с объектами ZipFile.

PyZipFile.writepy(pathname[, basename])¶

Search for files *.py and add the corresponding file to the archive. The corresponding file is a *.pyo file if available, else a *.pyc file, compiling if necessary. If the pathname is a file, the filename must end with .py, and just the (corresponding *.py[co]) file is added at the top level (no path information). If the pathname is a file that does not end with .py, a RuntimeError will be raised. If it is a directory, and the directory is not a package directory, then all the files *.py[co] are added at the top level. If the directory is a package directory, then all *.py[co] are added under the package name as a file path, and if any subdirectories are package directories, all of these are added recursively. basename is intended for internal use only. The writepy() method makes archives with file names like this:

string.pyc                                # Top level name
test/__init__.pyc                         # Package directory
test/testall.pyc                          # Module test.testall
test/bogus/__init__.pyc                   # Subpackage directory
test/bogus/myfile.pyc                     # Submodule test.bogus.myfile

Объекты ZipInfo¶ZipInfo Objects

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

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

ZipInfo.filename¶: Имя файла в архиве.

ZipInfo.date_time¶

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

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

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¶: Размер несжатого файла.