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

Объекты ZipFile¶

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

Откройте 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', файл должен быть доступен для поиска.

сжатие - это метод сжатия ZIP, который используется при записи архива, и он должен быть ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2 или ZIP_LZMA; нераспознанные значения приведут к увеличению NotImplementedError. Если указано значение ZIP_DEFLATED, ZIP_BZIP2 или ZIP_LZMA, но соответствующий модуль (zlib, bz2 или lzma недоступен, то вызывается значение RuntimeError. Значение по умолчанию равно ZIP_STORED.

Если значение allowZip64 равно True (по умолчанию), zip-файл будет создавать 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-структуры для пустого архива.

Zip-файл также является контекстным менеджером и, следовательно, поддерживает инструкцию with. В примере myzip закрывается после завершения набора инструкций with, даже если возникает исключение:

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

Примечание

metadata_encoding - это параметр для всего экземпляра Zip-файла. В настоящее время невозможно установить его для каждого пользователя.

Этот атрибут является обходным путем для устаревших реализаций, которые создают архивы с именами в текущей языковой кодировке или на кодовой странице (в основном в 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 принимает значение path-like object.

Изменено в версии 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)¶

Получите доступ к элементу архива как к объекту, подобному двоичному файлу. имя может быть либо именем файла в архиве, либо 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__(). Эти объекты могут работать независимо от ZIP-файла.

При использовании 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() для закрытого ZIP-файла вызовет ValueError. Ранее вызывался RuntimeError.

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

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

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

Примечание

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

Изменено в версии 3.6: Вызов extract() для закрытого ZIP-файла вызовет ValueError. Ранее вызывался RuntimeError.

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

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

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

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

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

Изменено в версии 3.6: Вызов extractall() для закрытого ZIP-файла вызовет ValueError. Ранее вызывался RuntimeError.

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

ZipFile.printdir()¶

Распечатайте оглавление архива в формате sys.stdout.

ZipFile.setpassword(pwd)¶

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

ZipFile.read(name, pwd=None)¶

Возвращает байты файла name в архиве. name - это имя файла в архиве или объекта ZipInfo. Архив должен быть открыт для чтения или добавления. pwd - это пароль, используемый для зашифрованных файлов в качестве объекта bytes и, если он указан, заменяет пароль по умолчанию, установленный с помощью setpassword(). Вызов read() для ZIP-файла, который использует метод сжатия, отличный от ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2 или ZIP_LZMA, приведет к появлению NotImplementedError. Также будет выдана ошибка, если соответствующий модуль сжатия недоступен.

Изменено в версии 3.6: Вызов read() для закрытого ZIP-файла вызовет ValueError. Ранее вызывался RuntimeError.

ZipFile.testzip()¶

Прочитайте все файлы в архиве и проверьте их CRC и заголовки файлов. Верните имя первого поврежденного файла или верните None.

Изменено в версии 3.6: Вызов testzip() для закрытого ZIP-файла вызовет 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() для Zip-файла, созданного в режиме 'r', или закрытого ZIP-файла вызовет ValueError. Ранее вызывался RuntimeError.

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)¶

Запишите файл в архив. Содержимым являются данные, которые могут быть либо 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() для Zip-файла, созданного в режиме 'r', или закрытого ZIP-файла вызовет 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, созданному с помощью mode 'w', 'x' или 'a', его длина не должна превышать 65535 байт. Комментарии, длина которых превышает указанную, будут сокращены.

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

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

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

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

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

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

Path.name¶

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

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

Вызовите ZipFile.open() по текущему пути. Позволяет открывать файл для чтения или записи, текстовый или двоичный в поддерживаемых режимах: „r“, „w“, „rb“, „wbb“. Аргументы позиции и ключевого слова передаются в 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(*, **)¶

Считайте текущий файл как текст в юникоде. Позиционные аргументы и ключевые слова передаются в 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: Добавлен параметр оптимизировать.

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

Экземпляры имеют один метод в дополнение к методам объектов ZipFile:

writepy(pathname, basename='', filterfunc=None)¶

Найдите файлы *.py и добавьте соответствующий файл в архив.

Если параметр optimize, равный PyZipFile, не был задан или -1, то соответствующий файл является файлом *.pyc, который при необходимости компилируется.

Если для параметра optimize указано значение PyZipFile 0, 1 или 2, в архив добавляются только файлы с таким уровнем оптимизации (см. compile()), при необходимости выполняется компиляция.

Если pathname - это файл, то имя файла должно заканчиваться на .py, и на верхнем уровне добавляется только файл (соответствующий *.pyc) (без указания пути). Если путь к файлу не заканчивается на .py, то будет поднят RuntimeError. Если это каталог, а каталог не является каталогом пакета, то все файлы *.pyc добавляются на верхнем уровне. Если каталог является каталогом пакета, то все *.pyc добавляются под именем пакета в качестве пути к файлу, а если какие-либо подкаталоги являются каталогами пакетов, то все они добавляются рекурсивно в отсортированном порядке.

базовое имя предназначено только для внутреннего использования.

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-файл.

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

Если указано 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¶

Фрагменты почтового флага.

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