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

См. также

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

Объекты ZipFile

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None)

Открыть 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; неразпознанные значения приведут к поднятию исключения NotImplementedError. Если ZIP_DEFLATED, ZIP_BZIP2 или ZIP_LZMA указаны, но соответствующий модуль (zlib, bz2 или lzma) недоступен, будет поднято исключение RuntimeError. По умолчанию используется ZIP_STORED.

Если allowZip64 равно True (по умолчанию), zipfile будет создавать ZIP-файлы, использующие расширения ZIP64, когда размер zipfile превышает 4 ГБ. Если оно равно false zipfile вызовет исключение, когда ZIP-файл будет требовать расширения ZIP64.

Параметр compresslevel управляет уровнем сжатия при записи файлов в архив. При использовании ZIP_STORED или ZIP_LZMA он не оказывает никакого влияния. При использовании ZIP_DEFLATED принимаются целые числа от 0 до 9 (подробнее см. zlib). При использовании ZIP_BZIP2 принимаются целые числа от 1 до 9 (подробнее см. bz2).

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

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

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

New in version 3.2: Добавлена возможность использования ZipFile как менеджера контекста.

Changed in version 3.3: Добавлена поддержка сжатия bzip2 и lzma.

Changed in version 3.4: Расширения ZIP64 включены по умолчанию.

Changed in version 3.5: Добавлена поддержка записи в потоки без возможности поиска. Добавлена поддержка режима 'x'.

Changed in version 3.6: Ранее для нераспознанных значений сжатия поднималось исключение RuntimeError.

Changed in version 3.6.2: Параметр file принимает объект, подобный пути.

Changed in version 3.7: Добавлен параметр compresslevel.

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

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

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

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

ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)

Получение доступа к элементу архива в виде двоичного файла-подобного объекта. name может быть либо именем файла внутри архива, либо объектом ZipInfo. Параметр mode, если указан, должен быть 'r' (по умолчанию) или 'w'. pwd — пароль для расшифровки зашифрованных ZIP-архивов.

open() также является менеджером контекста и поэтому поддерживает оператор with:

with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())

При использовании mode 'r' файл-подобный объект (ZipExtFile) является только для чтения и предоставляет следующие методы: read(), readline(), readlines(), seek(), tell(), __iter__(), __next__(). Эти объекты могут работать независимо от ZipFile.

При использовании mode='w', возвращается открытый для записи дескриптор файла, который поддерживает метод write(). Пока открыт дескриптор для записи, попытка чтения или записи других файлов в ZIP-архиве вызовет исключение ValueError.

При записи файла, если размер файла неизвестен заранее, но может превышать 2 ГБ, передайте force_zip64=True для обеспечения того, что формат заголовка поддерживает большие файлы. Если размер файла известен заранее, создайте объект ZipInfo со значением file_size, и используйте его в качестве параметра name.

Примечание

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

Изменено в версии 3.6: Удалена поддержка mode='U'. Используйте io.TextIOWrapper для чтения сжатых текстовых файлов в режиме универсальных новых строк.

Изменено в версии 3.6: open() теперь можно использовать для записи файлов в архив с опцией mode='w'.

Изменено в версии 3.6: Вызов open() для закрытого объекта ZipFile вызовет исключение ValueError. Ранее выбрасывалось исключение RuntimeError.

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 недопустимые символы (:, <, >, |, ", ?, и *) заменятся на символ подчеркивания (_).

Изменено в версии 3.6: Вызов extract() для закрытого объекта ZipFile вызовет исключение ValueError. Ранее выбрасывалось исключение RuntimeError.

Изменено в версии 3.6.2: Параметр path принимает объект, подобный пути.

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

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

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

Изменено в версии 3.6: Вызов extractall() для закрытого объекта ZipFile вызовет исключение ValueError. Ранее выбрасывалось исключение RuntimeError.

Изменено в версии 3.6.2: Параметр path принимает объект, подобный пути.

ZipFile.printdir(): Вывод таблицы содержимого архива в sys.stdout.

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

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

Изменено в версии 3.6: Вызов read() для закрытого объекта ZipFile вызовет исключение ValueError. Ранее выбрасывалось исключение RuntimeError.

ZipFile.testzip(): Прочитайте все файлы в архиве и проверьте их контрольные суммы CRC и заголовки файлов. Верните имя первого плохого файла, в противном случае верните None.

Изменено в версии 3.6: Вызов testzip() для закрытого объекта ZipFile вызовет исключение ValueError. Ранее генерировалось исключение RuntimeError.

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None): Запишите файл с именем filename в архив, присвоив ему имя arcname (по умолчанию это будет то же самое, что filename, но без буквенно-цифрового обозначения диска и с удаленными начальными разделителями пути). Если задано compress_type, то оно переопределяет значение, заданное параметром compression конструктору для новой записи. Аналогично, compresslevel переопределит конструктор, если задано. Архив должен быть открыт в режиме 'w', 'x' или 'a'.

Примечание

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

Примечание

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

Изменено в версии 3.6: Вызов write() для объекта ZipFile, созданного в режиме 'r' или закрытого объекта ZipFile, вызовет исключение ValueError. Ранее генерировалось исключение RuntimeError.

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)

Записать файл в архив. Содержимое — data, которое может быть строкой str или объектом bytes; если это строка str, она сначала кодируется в UTF-8. zinfo_or_arcname — это имя файла, которое он получит в архиве, или объект ZipInfo. Если это объект, то должны быть указаны, по крайней мере, имя файла, дата и время. Если это имя, то дата и время устанавливаются на текущую дату и время. Архив должен быть открыт в режиме 'w', 'x' или 'a'.

Если задано compress_type, то оно переопределяет значение, заданное параметром compression конструктору для новой записи, или в zinfo_or_arcname (если это объект ZipInfo). Аналогично, compresslevel переопределит конструктор, если задано.

Примечание

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

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

Изменено в версии 3.6: Вызов writestr() для объекта ZipFile, созданного в режиме 'r' или закрытого объекта ZipFile, вызовет исключение ValueError. Ранее генерировалось исключение RuntimeError.

Доступны следующие данные-атрибуты:

ZipFile.filename: Имя файла ZIP.

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

ZipFile.comment: Комментарий к файлу ZIP как объект bytes. При присваивании комментария объекту ZipFile, созданному в режиме 'w', 'x' или 'a', он не должен превышать 65535 байт. Комментарии, превышающие этот размер, будут усечены.

Объекты 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.6.2: Параметр pathname принимает объект-путь.

Изменено в версии 3.7: Рекурсивный сортировка записей каталога.

Объекты ZipInfo

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

Существует один статический метод для создания объекта ZipInfo для файла файловой системы:

classmethod ZipInfo.from_file(filename, arcname=None)

Создайте экземпляр ZipInfo для файла в файловой системе, в преддверии добавления его в архив zip.

filename должен быть путем к файлу или каталогу в файловой системе.

Если задано arcname, оно используется как имя внутри архива. Если arcname не задано, имя будет таким же, как filename, но с удалением буквенного обозначения диска и начальных разделителей путей.

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

Изменено в версии 3.6.2: Параметр filename принимает объект-путь.

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

ZipInfo.is_dir()

Возвращает True, если этот элемент архива является каталогом.

Это использует имя записи: каталоги всегда должны заканчиваться /.

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

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

ZipInfo.date_time

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

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

Примечание

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

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

ZipInfo.comment: Комментарий для отдельного элемента архива как объект bytes.

ZipInfo.extra: Данные расширения. Приложения PKZIP содержит некоторые комментарии по внутренней структуре данных, содержащихся в этом объекте bytes.

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

Интерфейс командной строки

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

Параметры командной строки

-l <zipfile>
--list <zipfile>: Список файлов в файле zip.

-c <zipfile> <source1> ... <sourceN>
--create <zipfile> <source1> ... <sourceN>: Создание файла zip из исходных файлов.

-e <zipfile> <output_dir>
--extract <zipfile> <output_dir>: Извлечение файла zip в целевой каталог.

-t <zipfile>
--test <zipfile>: Проверка, является ли файл zip валидным или нет.