zipfile – Работа с ZIP-архивами¶zipfile – Work with ZIP archives

Объекты ZipFile¶ZipFile Objects

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

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

Параметр mode должен быть 'r' для чтения существующего файла, 'w' для усечения и записи нового файла, 'a' для добавления к существующему файлу или 'x' для исключительного создания и записи нового файла. Если mode равен 'x' и file указывает на существующий файл, будет вызвано исключение FileExistsError. Если mode равен 'a' и file указывает на существующий ZIP-файл, в него добавляются дополнительные файлы. Если file не указывает на ZIP-файл, то в конец файла добавляется новый ZIP-архив. Это предназначено для добавления ZIP-архива в другой файл (например, python.exe). Если mode равен 'a' и файл вообще не существует, он создаётся. Если mode равен 'r' или 'a', файл должен поддерживать позиционирование.

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

Если allowZip64 равен True (по умолчанию), zipfile будет создавать ZIP-файлы с расширениями ZIP64, когда размер zip-файла превышает 4 ГиБ. Если он равен false, zipfile возбудит исключение, когда ZIP-файлу потребуются расширения ZIP64.

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

Аргумент strict_timestamps при значении False позволяет архивировать файлы старше 1980-01-01, ценой установки временной метки на 1980-01-01. Аналогичное поведение для файлов новее 2107-12-31: временная метка также устанавливается на предельное значение.

Если режим равен 'r', metadata_encoding можно задать как имя кодека, который будет использоваться для декодирования метаданных, таких как имена элементов и ZIP-комментарии.

Если файл создан с режимом 'w', 'x' или 'a', а затем closed без добавления каких-либо файлов в архив, в файл будут записаны соответствующие структуры ZIP для пустого архива.

ZipFile также является контекстным менеджером и поэтому поддерживает оператор with. В примере myzip закрывается после завершения блока оператора with – даже если возникло исключение:

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

Примечание

metadata_encoding – настройка, применяемая ко всему экземпляру ZipFile. Задать её для каждого элемента по отдельности пока нельзя.

Этот атрибут – обходной путь для устаревших реализаций, которые создают архивы с именами в кодировке текущей локали или кодовой странице (в основном в Windows). Согласно стандарту .ZIP, кодировка метаданных может быть указана как IBM code page (по умолчанию) или UTF-8 с помощью флага в заголовке архива. Этот флаг имеет приоритет над metadata_encoding, который является расширением, специфичным для Python.

Изменено в версии 3.2: Добавлена возможность использования ZipFile в качестве контекстного менеджера.

Изменено в версии 3.3: Добавлена поддержка сжатия bzip2 и lzma.

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

Изменено в версии 3.5: Добавлена поддержка записи в непозиционируемые потоки. Добавлена поддержка режима 'x'.

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

Изменено в версии 3.6.2: Параметр file принимает объект, подобный пути.

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

Изменено в версии 3.8: Параметр strict_timestamps, передаваемый только по ключу.

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

При записи файла, если размер файла заранее неизвестен, но может превысить 2 ГБ, передайте force_zip64=True, чтобы формат заголовка мог поддерживать большие файлы. Если размер файла известен заранее, создайте объект ZipInfo с установленным file_size и используйте его в качестве параметра name.

Примечание

Методы open(), read() и extract() могут принимать имя файла или объект ZipInfo. Это пригодится при попытке чтения ZIP-файла, содержащего элементы с повторяющимися именами.

Изменено в версии 3.6: Удалена поддержка mode='U'. Используйте io.TextIOWrapper для чтения сжатых текстовых файлов в режиме универсальные символы новой строки.

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

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

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

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

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

Примечание

Если имя файла элемента является абсолютным путём, диск/UNC-точка и начальные (обратные) слеши будут удалены, например: ///foo/bar становится foo/bar на Unix, а C:\foo\bar становится foo\bar на Windows. Все компоненты ".." в имени файла элемента будут удалены, например: ../../foo../../ba..r становится foo../ba..r. На Windows недопустимые символы (:, <, >, |, ", ? и *) заменяются подчёркиванием (_).

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

Изменено в версии 3.6.2: Параметр path принимает объект, подобный пути.

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

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

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

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

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

Изменено в версии 3.6.2: Параметр path принимает объект, подобный пути.

ZipFile.printdir()¶

Выводит оглавление архива в sys.stdout.

ZipFile.setpassword(pwd)¶

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

ZipFile.read(name, pwd=None)¶

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

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

ZipFile.testzip()¶

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

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

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)¶

Записывает файл с именем filename в архив, присваивая ему архивное имя arcname (по умолчанию оно совпадает с filename, но без буквы диска и с удалёнными начальными разделителями путей). Если указан, compress_type переопределяет значение, переданное в параметре compression конструктору для новой записи. Аналогично, compresslevel переопределит конструктор, если указан. Архив должен быть открыт с режимом 'w', 'x' или 'a'.

Примечание

Стандарт ZIP-файлов исторически не определял кодировку метаданных, но настоятельно рекомендовал CP437 (оригинальную кодировку IBM PC) для совместимости. Последние версии допускают использование только UTF-8. В этом модуле UTF-8 будет автоматически использоваться для записи имён элементов, если они содержат любые не-ASCII символы. Невозможно записать имена элементов в любой кодировке, кроме 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¶Path Objects

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

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

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

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

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

Path.name¶

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

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

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

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

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

Path.iterdir()¶

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

Path.is_dir()¶

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

Path.is_file()¶

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

Path.exists()¶

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

Path.suffix¶

Расширение файла последнего компонента пути.

Новое в версии 3.11: Добавлено свойство Path.suffix.

Path.stem¶

Конечный компонент пути без его суффикса.

Новое в версии 3.11: Добавлено свойство Path.stem.

Path.suffixes¶

Список расширений файлов пути.

Новое в версии 3.11: Добавлено свойство Path.suffixes.

Path.read_text(*, **)¶

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

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

Path.read_bytes()¶

Читает текущий файл как байты.

Path.joinpath(*other)¶

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

Конструктор 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                   # Имя верхнего уровня
test/__init__.pyc            # Каталог пакета
test/testall.pyc             # Модуль test.testall
test/bogus/__init__.pyc      # Каталог подпакета
test/bogus/myfile.pyc        # Подмодуль test.bogus.myfile

Изменено в версии 3.4: Добавлен параметр filterfunc.

Изменено в версии 3.6.2: Параметр pathname теперь принимает объект, подобный пути.

Изменено в версии 3.7: Рекурсия сортирует записи каталога.

Объекты ZipInfo¶ZipInfo Objects

Экземпляры класса 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	Месяц (начиная с 1)
2	День месяца (начиная с 1)
3	Часы (начиная с 0)
4	Минуты (начиная с 0)
5	Секунды (начиная с 0)

Примечание

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

Размер несжатого файла.

Интерфейс командной строки¶Command-Line Interface

Модуль 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

Подводные камни распаковки¶Decompression pitfalls

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