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

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

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

В настоящее время этот модуль не поддерживает многодисковые 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-файл, либо не смогут извлечь отдельные файлы.

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

Изменено в версии 3.6: Ранее, для нераспознанных значений сжатия поднималась ошибка RuntimeError.

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

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

Записать файл с именем filename в архив, присвоив ему имя arcname (по умолчанию, это будет то же самое, что filename, но без буквы диска и с удаленными ведущими разделителями пути). Если задано, compress_type переопределяет значение, заданное для параметра compression конструктору для новой записи. Архив должен быть открыт в режиме 'w', 'x' или 'a'.

Примечание

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

Примечание

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

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

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

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

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

Примечание

При передаче объекта 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 байт. Комментарии длиннее этого будут обрезанны.

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

13.5.3. Объекты 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	Месяц (с 1)
2	День месяца (с 1)
3	Часы (с 0)
4	Минуты (с 0)
5	Секунды (с 0)

Примечание

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

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

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

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

-l <zipfile>

Вывод списка файлов в zip-архиве.

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

Создание zip-архива из исходных файлов.

-e <zipfile> <output_dir>

Извлечение zip-архива в целевой каталог.

-t <zipfile>

Проверка валидности zip-архива.