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, позволяет архивировать файлы, которые старше 1980-01-01, но при этом устанавливает временную метку на 1980-01-01. Аналогичное поведение имеет место для файлов, которые новее 2107-12-31, временная метка также устанавливается на ограничение.

Когда режим равен '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.

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

Примечание

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

Примечание

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

Примечание

Если 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; если это строка, она сначала кодируется как 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 байт. Комментарии, превышающие эту длину, будут усечены.

Объекты Path

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

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

at определяет расположение этого объекта Path внутри 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: Добавлена поддержка текстовых и двоичных режимов для open. По умолчанию режим — текстовый.

Изменено в версии 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 предоставляет обратные порты новейших возможностей объектов path для более старых версий 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 Application Note содержит некоторые комментарии по внутренней структуре данных, содержащихся в этом объекте 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 может завершиться сбоем из-за перечисленных ниже проблем.