zipfile — Работа с архивами ZIP

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

Формат ZIP — распространённый стандарт архивирования и сжатия. Этот модуль предоставляет инструменты для создания, чтения, записи, добавления и просмотра содержимого архива ZIP. Для продвинутого использования этого модуля необходимо понимание формата, как определено в приложении PKZIP.

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

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

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.

zipfile.is_zipfile(filename)

Возвращает True если *filename* — действительный ZIP-архив по его магическому числу, иначе возвращает False. *filename* может быть файлом или объектом-подобным файлу.

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

zipfile.ZIP_STORED

Числовая константа для нескомпрессированного члена архива.

zipfile.ZIP_DEFLATED

Числовая константа для обычного метода сжатия ZIP. Требуется модуль zlib. Другие методы сжатия в настоящее время не поддерживаются.

1. Объекты ZipFile

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

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

Изменено в версии 2.6: Если *mode* равен a, и файл вообще не существует, он создаётся.

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

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

ZipFile также является менеджером контекста и, следовательно, поддерживает оператор with. В примере, *myzip* закрывается после выполнения блока оператора with, даже если произошла ошибка:

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

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

ZipFile.close()

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

ZipFile.getinfo(name)

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

ZipFile.infolist()

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

ZipFile.namelist()

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

ZipFile.open(name[, mode[, pwd]])

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

Примечание

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

Примечание

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

Примечание

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

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

ZipFile.extract(member[, path[, pwd]])

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

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

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

Примечание

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

ZipFile.extractall([path[, members[, pwd]]])

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

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

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

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

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

ZipFile.printdir()

Вывести таблицу содержания архива в sys.stdout.

ZipFile.setpassword(pwd)

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

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

ZipFile.read(name[, pwd])

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

Изменено в версии 2.6: Добавлен pwd, и name теперь может быть объектом ZipInfo.

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[, 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.

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

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

ZipFile.debug

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

ZipFile.comment

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

2. Объекты PyZipFile

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

PyZipFile.writepy(pathname[, basename])

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

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

3. Объекты ZipInfo

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

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

ZipInfo.filename

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

ZipInfo.date_time

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

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

Примечание

Формат файла 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

Размер нескомпрессированного файла.

4. Командная строка

Модуль zipfile предоставляет простой интерфейс командной строки для взаимодействия с архивами ZIP.

Если вы хотите создать новый архив ZIP, укажите его имя после опции -c, а затем перечислите имена файлов, которые должны быть включены:

$ python -m zipfile -c monty.zip spam.txt eggs.txt

Также можно передать директорию:

$ python -m zipfile -c monty.zip life-of-brian_1979/

Если вы хотите извлечь архив ZIP в указанную директорию, используйте опцию -e:

$ python -m zipfile -e monty.zip target-dir/

Для просмотра списка файлов в архиве ZIP используйте опцию -l:

$ python -m zipfile -l monty.zip

4.1. Опции командной строки

-l <zipfile>

Отобразить файлы в архиве ZIP.

-c <zipfile> <source1> ... <sourceN>

Создать архив ZIP из исходных файлов.

-e <zipfile> <output_dir>

Извлечь архив ZIP в целевую директорию.

-t <zipfile>

Проверить, является ли архив ZIP допустимым.