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

12.4.1. Объекты 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).

Изменено в версии 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 (утилиты InfoZIP) не поддерживают эти расширения.

Изменено в версии 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]])¶

Извлекает элемент из архива в виде файлоподобного объекта (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-файла, содержащего элементы с повторяющимися именами.

Новое в версии 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-файлов не существует официальной кодировки имён файлов. Если у вас есть имена файлов в Юникоде, вы должны преобразовать их в байтовые строки в нужной кодировке перед передачей в 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().

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

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

PyZipFile.writepy(pathname[, basename])¶

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

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

12.4.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¶

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

12.4.4. Интерфейс командной строки¶Command-Line Interface

Модуль 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