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' для добавления к существующему файлу или 'x' для исключительного создания и записи нового файла. Если mode равен 'x', а file ссылается на существующий файл, будет возбуждено FileExistsError. Если mode равен 'a' и file ссылается на существующий ZIP-файл, то в него добавляются новые файлы. Если file не ссылается на ZIP-файл, то новый ZIP-архив добавляется в конец файла. Это предназначено для добавления ZIP-архива в другой файл (например, python.exe). Если mode равен 'a' и файл вообще не существует, он создаётся. Если mode равен 'r' или '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, когда размер zip-файла превышает 4 ГиБ. Если он ложен zipfile, при необходимости расширений ZIP64 будет возбуждено исключение.

Если файл создан с режимом 'w', 'x' или 'a', а затем closed без добавления каких-либо файлов в архив, в файл будут записаны соответствующие структуры 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 включены по умолчанию.

Изменено в версии 3.5: Добавлена поддержка записи в непозиционируемые потоки. Добавлена поддержка режима 'x'.

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__().

Примечание

Объекты, возвращаемые open(), могут работать независимо от 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', 'x' или 'a' – вызов write() для ZipFile, созданного с режимом 'r', возбудит RuntimeError. Вызов write() для закрытого ZipFile возбудит RuntimeError.

Примечание

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

Примечание

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

Примечание

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

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

Записывает строку data в архив; zinfo_or_arcname – это либо имя файла, которое он получит в архиве, либо экземпляр ZipInfo. Если это экземпляр, должны быть указаны как минимум имя файла, дата и время. Если это имя, дата и время устанавливаются равными текущим. Архив должен быть открыт в режиме 'w', 'x' или '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, созданному с режимом 'w', 'x' или 'a', это должна быть строка длиной не более 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, то соответствующим файлом является *.pyc файл, при необходимости компилируемый.

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

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

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¶

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

13.5.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