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

Объекты ZipFile

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=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, если размер zip-файла превышает 4 ГБ. Если это false zipfile вызовет исключение, если ZIP-файлу потребуются расширения ZIP64.

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

Аргумент strict_timestamps, установленный в значение False, позволяет архивировать файлы, более старые, чем 01.01.1980, в ущерб установке метки времени на 01.01.1980. Аналогичное поведение наблюдается с файлами, более новыми, чем 31.12.2107, метка времени также устанавливается на предел.

При режиме 'r', metadata_encoding может быть задан как имя кодека, который будет использоваться для декодирования метаданных, таких как имена членов и комментарии ZIP.

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

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

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

Примечание

metadata_encoding — это глобальная настройка для ZipFile. В настоящее время невозможно настроить это значение для каждого элемента.

Это свойство является обходным решением для устаревших реализаций, которые создают архивы с именами в кодировке текущего языка или кодовой странице (в основном на Windows). Согласно стандарту .ZIP, кодировка метаданных может быть указана как IBM code page (по умолчанию) или UTF-8 флагом в заголовке архива. Этот флаг имеет приоритет над metadata_encoding, что является расширением, специфичным для Python.

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

Изменено в версии 3.3: Добавлена поддержка сжатия с помощью bzip2 и lzma.

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

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

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

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

Изменено в версии 3.7: Добавлен параметр compresslevel.

Изменено в версии 3.8: Ключевой параметр strict_timestamps.

Изменено в версии 3.11: Добавлена поддержка указания кодировки имен членов для чтения метаданных в каталоге и заголовках файла zip.

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-архивов, заданный как объект bytes.

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: ZipFile.open() теперь можно использовать для записи файлов в архив с опцией mode='w'.

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

ZipFile.extract(member, path=None, pwd=None)

Извлечение элемента из архива в текущий рабочий каталог; member должно быть полным именем или объектом ZipInfo. Информация о файле извлекается как можно точнее. path задаёт другой каталог для извлечения. member может быть именем файла или объектом ZipInfo. pwd — пароль для зашифрованных файлов в виде объекта bytes.

Возвращает нормализованный созданный путь (каталог или новый файл).

Примечание

Если имя файла элемента — абсолютный путь, приводящая (обратная) косая черта и имя диска/сетевого ресурса будут удалены, например: ///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 — пароль для зашифрованных файлов в виде объекта bytes.

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

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

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

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

ZipFile.printdir()

Вывод таблицы содержания архива в sys.stdout.

ZipFile.setpassword(pwd)

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

ZipFile.read(name, pwd=None)

Возвращает байты файла name в архиве. name — имя файла в архиве или объект ZipInfo. Архив должен быть открыт для чтения или добавления. pwd — пароль, используемый для зашифрованных файлов, как объект bytes, и, если указан, переопределяет пароль по умолчанию, заданный с помощью 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'.

Примечание

Стандарт ZIP-файлов исторически не определял кодировку метаданных, но настоятельно рекомендовал CP437 (исходную кодировку IBM PC) для межплатформенной совместимости. Недавние версии допускают использование только UTF-8. В этом модуле UTF-8 будет автоматически использоваться для записи имён членов, если они содержат символы, отличные от ASCII. Невозможно записать имена членов в кодировках, отличных от ASCII или UTF-8.

Примечание

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

Примечание

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

Примечание

Начальный слэш в имени файла может привести к тому, что архив станет невозможным для открытия в некоторых программах zip на системах Windows.

Изменено в версии 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.mkdir(zinfo_or_directory, mode=511)

Создает директорию внутри архива. Если zinfo_or_directory является строкой, создаётся директория внутри архива с режимом, указанным в аргументе mode. Если же zinfo_or_directory является экземпляром ZipInfo, то аргумент mode игнорируется.

Архив должен быть открыт в режиме 'w', 'x' или 'a'.

Добавлена в версии 3.11.

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

ZipFile.filename

Имя ZIP-файла.

ZipFile.debug

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

ZipFile.comment

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

Объекты путей

class zipfile.Path(root, at='')

Создает объект Path из root архива ZIP (который может быть экземпляром ZipFile или file подходящим для передачи в конструктор ZipFile).

at определяет расположение этого пути внутри архива ZIP, например, 'dir/file.txt', 'dir/' или ''. По умолчанию — пустая строка, что указывает на корень.

Объекты Path предоставляют следующие возможности объектов pathlib.Path:

Объекты Path можно перебирать, используя оператор / или joinpath.

Path.name

Последний компонент пути.

Path.open(mode='r', *, pwd, **)

Вызывает ZipFile.open() для текущего пути. Позволяет открывать на чтение или запись, в текстовом или бинарном формате через поддерживаемые режимы: 'r', 'w', 'rb', 'wb'. Позиционные и ключевые аргументы передаются в io.TextIOWrapper при открытии в текстовом формате и игнорируются в противном случае. pwd — параметр pwd для ZipFile.open().

Изменено в версии 3.9: Добавлена поддержка текстового и бинарного режимов для открытия. Режим по умолчанию теперь текстовый.

Изменено в версии 3.11.2: Параметр encoding может быть передан как позиционный аргумент без вызова TypeError. Как это было в 3.9. Код, требующий совместимости с неисправленными версиями 3.10 и 3.11, должен передавать все аргументы io.TextIOWrapper, включая encoding, в качестве ключевых.

Path.iterdir()

Перечислить дочерние элементы текущей директории.

Path.is_dir()

Возвращает True, если текущий контекст ссылается на директорию.

Path.is_file()

Возвращает True если текущий контекст ссылается на файл.

Path.exists()

Возвращает True если текущий контекст ссылается на файл или директорию в архиве ZIP.

Path.suffix

Расширение файла последнего компонента.

Добавлена в версии 3.11: Добавлена свойство Path.suffix.

Path.stem

Последний компонент пути без расширения.

Добавлена в версии 3.11: Добавлена свойство Path.stem.

Path.suffixes

Список расширений файла пути.

Добавлена в версии 3.11: Добавлена свойство Path.suffixes.

Path.read_text(*, **)

Чтение текущего файла как текстовой строки Unicode. Позиционные и ключевые аргументы передаются в io.TextIOWrapper (кроме buffer, которое подразумевается контекстом).

Изменено в версии 3.11.2: Параметр encoding может быть передан как позиционный аргумент без вызова TypeError. Как это было в 3.9. Код, требующий совместимости с неисправленными версиями 3.10 и 3.11, должен передавать все аргументы io.TextIOWrapper, включая encoding, в качестве ключевых.

Path.read_bytes()

Чтение текущего файла в виде байтов.

Path.joinpath(*other)

Возвращает новый объект Path, в котором каждый из других аргументов соединён.

>>> Path(...).joinpath('child').joinpath('grandchild')
>>> Path(...).joinpath('child', 'grandchild')
>>> Path(...) / 'child' / 'grandchild'

Изменено в версии 3.10: До версии 3.10, joinpath не был задокументирован и принимал ровно один параметр.

Проект zipp предоставляет обратные порты новейших функций объектов пути для более старых версий Python. Используйте zipp.Path вместо zipfile.Path для раннего доступа к изменениям.

Объекты 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, *, strict_timestamps=True)

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

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

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

Аргумент strict_timestamps, когда установлен в значение False, позволяет архивировать файлы, более старые, чем 01.01.1980, ценой установки метки времени на 01.01.1980. Аналогичное поведение наблюдается для файлов, более новых, чем 31.12.2107, метка времени также устанавливается на предельное значение.

Добавлен в версии 3.6.

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

Изменён в версии 3.8: Добавлен ключевой параметр strict_timestamps.

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

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

Возможные ошибки при распаковке

Распаковка в модуле zipfile может завершиться неудачей из-за следующих проблем.