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

Объекты ZipFile

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

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

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

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

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

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

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

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

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

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

at задает расположение этого Path внутри zipfile, например ‘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: Добавлена поддержка текстового и двоичного режимов при открытии. Режимом по умолчанию теперь является текстовый.

Изменено в версии 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 принимает те же параметры, что и конструктор ZipFile, а также один дополнительный параметр — optimize.

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

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

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

Помимо методов объектов ZipFile, экземпляры имеют еще один метод:

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

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

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

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

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

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

Если задан параметр filterfunc, он должен быть функцией, принимающей один строковый аргумент. Она вызывается для каждого пути (включая полный путь к каждому отдельному файлу) перед его добавлением в архив. Если filterfunc возвращает ложное значение, путь не добавляется; если это каталог, его содержимое также игнорируется. Например, если все наши тестовые файлы находятся в каталогах test или начинаются со строки test_, можно использовать filterfunc, чтобы исключить их:

>>> zf = PyZipFile('myprog.zip')
>>> def notests(s):
...     fn = os.path.basename(s)
...     return (not (fn == 'test' or fn.startswith('test_')))
...
>>> zf.writepy('myprog', filterfunc=notests)

Метод writepy() создает архивы с такими именами файлов:

string.pyc                   # Top level name
test/__init__.pyc            # Package directory
test/testall.pyc             # Module test.testall
test/bogus/__init__.pyc      # Subpackage directory
test/bogus/myfile.pyc        # Submodule test.bogus.myfile

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

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

Изменено в версии 3.7: При рекурсивном обходе записи каталогов сортируются.

Объекты ZipInfo

Экземпляры класса ZipInfo возвращаются методами getinfo() и infolist() объектов ZipFile. Каждый объект хранит сведения об одном элементе ZIP-архива.

Для создания экземпляра ZipInfo для файла в файловой системе предусмотрен один метод класса:

classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)

Создает экземпляр ZipInfo для файла в файловой системе, чтобы подготовить его к добавлению в zip-файл.

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

Если задан параметр arcname, он используется как имя внутри архива. Если arcname не задан, имя будет таким же, как filename, но без буквы диска и начальных разделителей пути.

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

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

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

Изменено в версии 3.8: Добавлен параметр только с именованной передачей strict_timestamps.

Экземпляры имеют следующие методы и атрибуты:

ZipInfo.is_dir()

Возвращает True, если этот элемент архива является каталогом.

Для этого используется имя элемента: имена каталогов всегда должны оканчиваться на /.

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

ZipInfo.filename

Имя файла в архиве.

ZipInfo.date_time

Время и дата последнего изменения элемента архива. Это кортеж из шести значений:

Индекс	Значение
0	Год (>= 1980)
1	Месяц (нумерация начинается с единицы)
2	День месяца (нумерация начинается с единицы)
3	Часы (нумерация начинается с нуля)
4	Минуты (нумерация начинается с нуля)
5	Секунды (нумерация начинается с нуля)

Примечание

Формат ZIP-файла не поддерживает временные метки, предшествующие 1980 году.

ZipInfo.compress_type

Тип сжатия элемента архива.

ZipInfo.comment

Комментарий к отдельному элементу архива в виде объекта bytes.

ZipInfo.extra

Данные поля расширения. В примечании к приложению PKZIP содержатся комментарии о внутренней структуре данных этого объекта bytes.

ZipInfo.create_system

Система, создавшая ZIP-архив.

ZipInfo.create_version

Версия PKZIP, создавшая ZIP-архив.

ZipInfo.extract_version

Версия PKZIP, необходимая для распаковки архива.

ZipInfo.reserved

Должно быть равно нулю.

ZipInfo.flag_bits

Биты флагов ZIP.

ZipInfo.volume

Номер тома в заголовке файла.

ZipInfo.internal_attr

Внутренние атрибуты.

ZipInfo.external_attr

Внешние атрибуты файла.

ZipInfo.header_offset

Смещение заголовка файла в байтах.

ZipInfo.CRC

CRC-32 несжатого файла.

ZipInfo.compress_size

Размер сжатых данных.

ZipInfo.file_size

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

Интерфейс командной строки

Модуль zipfile предоставляет простой интерфейс командной строки для работы с ZIP-архивами.

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

$ python -m zipfile -c monty.zip spam.txt eggs.txt

Можно также указать каталог:

$ python -m zipfile -c monty.zip life-of-brian_1979/

Чтобы распаковать ZIP-архив в указанный каталог, используйте параметр -e:

$ python -m zipfile -e monty.zip target-dir/

Чтобы получить список файлов в ZIP-архиве, используйте параметр -l:

$ python -m zipfile -l monty.zip

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

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