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

Объекты ZipFile¶

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

Открыть ZIP-файл, где file может быть путем к файлу (строка), файлоподобным объектом или path-like object.

Параметр 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, временная метка также устанавливается на предельное значение.

Если файл создан в режиме '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 принимает значение path-like object.

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

Добавлено в версии 3.8: Аргумент strict_timestamps только для ключевого слова

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 для чтения сжатых текстовых файлов в режиме universal newlines.

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

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

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

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

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

Примечание

Если имя файла-члена является абсолютным путем, диск/UNC sharepoint и ведущие (обратные) косые черты будут удалены, например: ///foo/bar становится foo/bar на Unix, а C:\foo\bar становится foo\bar на Windows. И все компоненты ".." в имени файла-члена будут удалены, например, : ../../foo../../ba..r becomes foo../ba..r. On Windows illegal characters (:, <, >, |, ", ?, and *) replaced by underscore (_).

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

Изменено в версии 3.6.2: Параметр path принимает значение path-like object.

ZipFile.extractall(path=None, members=None, pwd=None)¶

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

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

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

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

Изменено в версии 3.6.2: Параметр path принимает значение path-like object.

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

Примечание

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

Имя файла ZIP.

ZipFile.debug¶

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

ZipFile.comment¶

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

Объекты пути¶

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

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

at указывает расположение этого Пути в zip-файле, например, „dir/file.txt“, „dir/“, или „“. По умолчанию это пустая строка, указывающая на корень.

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

Объекты пути можно обходить с помощью оператора / или joinpath.

Path.name¶

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

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

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

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

Path.iterdir()¶

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

Path.is_dir()¶

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

Path.is_file()¶

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

Path.exists()¶

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

Path.read_text(*, **)¶

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

Path.read_bytes()¶

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

Path.joinpath(*other)¶

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

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

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

Объекты PyZipFile¶

Конструктор PyZipFile принимает те же параметры, что и конструктор ZipFile, и один дополнительный параметр, optimize.

class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=- 1)¶

Добавлено в версии 3.2: Параметр оптимизировать.

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

Изменено в версии 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 принимает значение path-like object.

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