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

Исходный код: 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.

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-файла, либо не смогут извлечь отдельные файлы.

1. Объекты ZipFile

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_STORED. Если allowZip64 равно True (по умолчанию), zipfile будет создавать ZIP-файлы с использованием расширений ZIP64, когда размер ZIP-файла превышает 4 ГБ. Если оно ложно, zipfile будет выбрасывать исключение, когда для ZIP-файла потребуются расширения 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().

2. Объекты PyZipFile

Конструктор 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                   # 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

Добавлен в версии 3.4: Параметр filterfunc.

3. Объекты ZipInfo

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

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

ZipInfo.filename

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

ZipInfo.date_time

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

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

Примечание

Формат ZIP-файлов не поддерживает временные метки до 1980 года.

ZipInfo.compress_type

Тип сжатия для элемента архива.

ZipInfo.comment

Комментарий к отдельному элементу архива.

ZipInfo.extra

Данные расширения. PKZIP Application Note содержит некоторые комментарии по внутренней структуре данных, содержащихся в этой строке.

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-архива.