Spec-Zone.ru › Python 3.13

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

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

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

Класс, реализующий подмножество интерфейса, предоставляемого pathlib.Path, включая полный интерфейс importlib.resources.abc.Traversable.

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

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.

Изменено в версии 3.13: Добавлен общедоступный атрибут compress_level для доступа к ранее защищённому _compresslevel. Старое защищённое имя продолжает работать как свойство для обратной совместимости.

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-файл целиком либо не извлечь отдельные файлы.

См. также

Примечание к приложению PKZIP

Документация по формату ZIP, написанная Филом Кацем — создателем формата и использованных алгоритмов.

Главная страница Info-ZIP

Информация об архиваторах ZIP и библиотеках разработки проекта Info-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, если размер файла превышает 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 (по умолчанию), либо 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 байт. Более длинные комментарии будут усечены.

Объекты Path

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

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

at задаёт расположение этого Path в zipfile, например ‘dir/file.txt’, ‘dir/’ или ‘’. По умолчанию используется пустая строка, обозначающая корневой каталог.

Примечание

Класс Path не проверяет и не очищает имена файлов в ZIP-архиве. В отличие от методов ZipFile.extract() и ZipFile.extractall(), проверка или очистка имён файлов для предотвращения уязвимостей обхода каталогов (например, имён файлов, содержащих «..», или абсолютных путей) является обязанностью вызывающего кода. При работе с ненадёжными архивами рассмотрите возможность разрешения имён файлов с помощью os.path.abspath() и проверки их соответствия целевому каталогу с помощью os.path.commonpath().

Объекты 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.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(*, **)

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

Время и дата последнего изменения элемента архива. Это кортеж из шести значений, представляющих поля «время последнего [изменения] файла» и «дата последнего [изменения] файла» центрального каталога ZIP-файла.

Кортеж содержит:

Индекс

Значение

0

Год (>= 1980)

1

Месяц (начиная с единицы)

2

День месяца (начиная с единицы)

3

Часы (начиная с нуля)

4

Минуты (начиная с нуля)

5

Секунды (начиная с нуля)

Примечание

Формат ZIP поддерживает несколько полей временных меток в разных местах (центральный каталог, дополнительные поля для систем NTFS/UNIX и т. д.). Этот атрибут возвращает именно временную метку из центрального каталога. Формат временной метки центрального каталога в ZIP-файлах не поддерживает даты ранее 1980 года. Хотя некоторые форматы дополнительных полей (например, временные метки UNIX) могут представлять более ранние даты, этот атрибут возвращает только временную метку центрального каталога.

Временная метка центрального каталога интерпретируется как местное время, а не время UTC, чтобы соответствовать поведению других инструментов для работы с zip-файлами.

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

Параметры командной строки

-l <zipfile>
--list <zipfile>

Вывести список файлов в zipfile.

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

Создать zipfile из исходных файлов.

-e <zipfile> <output_dir>
--extract <zipfile> <output_dir>

Распаковать zipfile в целевой каталог.

-t <zipfile>
--test <zipfile>

Проверить, является ли zipfile корректным.

--metadata-encoding <encoding>

Указать кодировку имён элементов для параметров -l, -e и -t.

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

Проблемы при распаковке

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

Связанные с самим файлом

Распаковка может завершиться ошибкой из-за неверного пароля, несовпадения контрольной суммы CRC, ошибок формата ZIP или неподдерживаемого метода сжатия или расшифровки.

Ограничения файловой системы

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

Ограничения ресурсов

Недостаток памяти или места на диске может привести к сбою распаковки. Например, zipfile может столкнуться с архивами-бомбами (также известными как ZIP-бомбы), которые способны исчерпать место на диске.

Прерывание

Прерывание распаковки, например нажатием Ctrl-C или завершением процесса распаковки, может привести к неполной распаковке архива.

Поведение распаковки по умолчанию

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

© 2001–2025 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.13/library/zipfile.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API