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

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

Аргумент strict_timestamps, если установлен в False, позволяет добавлять в ZIP-архив файлы, которые старше 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: Добавлена поддержка задания кодировки имени члена для чтения метаданных в каталоге и заголовках файла zipfile.

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.

В обоих случаях объект-подобный файлу также имеет атрибуты name, который эквивалентен имени файла в архиве, и mode, который представляет собой 'rb' или 'wb' в зависимости от режима ввода.

При записи файла, если размер файла неизвестен заранее, но может превышать 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.

Изменено в версии 3.13: Добавлены атрибуты name и mode для объекта-подобного файлу для записи. Значение атрибута mode для объекта-подобного файлу для чтения было изменено с 'r' на 'rb'.

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 символы. Запись имён членов в любой кодировке, отличной от 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: Добавлена поддержка текстовых и бинарных режимов для 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.is_symlink()

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

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

Изменено в версии 3.13: Ранее, is_symlink безусловно возвращало False.

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

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

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

Path.read_bytes()

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

Path.joinpath(*other)

Возвращает новый объект Path с соединёнными аргументами other. Следующие выражения эквивалентны:

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

Добавлен в версии 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 может завершиться ошибкой из-за перечисленных ниже проблем.