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

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

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