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

13.5.1. Объекты ZipFile¶ZipFile Objects

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True)¶

Открывает 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.

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

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

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

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

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

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

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

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

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

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

open() также является контекстным менеджером и поэтому поддерживает оператор with:

with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())

С mode 'r' файлоподобный объект (ZipExtFile) доступен только для чтения и предоставляет следующие методы: read(), readline(), readlines(), __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: Теперь open() можно использовать для записи файлов в архив с опцией mode='w'.

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

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

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

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

Примечание

Если имя файла элемента является абсолютным путём, диск/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 – пароль для зашифрованных файлов.

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

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

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

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

ZipFile.printdir()¶

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

ZipFile.setpassword(pwd)¶

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

ZipFile.read(name, pwd=None)¶

Возвращает байты файла name из архива. name – это имя файла в архиве или объект ZipInfo. Архив должен быть открыт для чтения или добавления. pwd – пароль для зашифрованных файлов; если указан, он переопределяет пароль по умолчанию, заданный с помощью 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)¶

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

Примечание

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

Примечание

Если arcname (или filename, если arcname не указан) содержит нулевой байт, имя файла в архиве будет обрезано по этому байту.

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

ZipFile.writestr(zinfo_or_arcname, data[, compress_type])¶

Записывает файл в архив. Содержимое – это data, который может быть экземпляром str или bytes; если это str, то он сначала кодируется в UTF-8. zinfo_or_arcname – это либо имя файла, которое он получит в архиве, либо экземпляр ZipInfo. Если это экземпляр, должны быть указаны как минимум имя файла, дата и время. Если это имя, дата и время устанавливаются на текущие дату и время. Архив должен быть открыт с режимом 'w', 'x' или 'a'.

Если указан, compress_type переопределяет значение, заданное для параметра compression в конструкторе для новой записи, или в zinfo_or_arcname (если это экземпляр ZipInfo).

Примечание

При передаче экземпляра ZipInfo в качестве параметра zinfo_or_arcname используемый метод сжатия будет тем, который указан в элементе compress_type данного экземпляра ZipInfo. По умолчанию конструктор ZipInfo устанавливает этот элемент в ZIP_STORED.

Изменено в версии 3.2: Аргумент compress_type.

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

Также доступны следующие атрибуты данных:

ZipFile.filename¶

Имя ZIP-файла.

ZipFile.debug¶

Уровень отладочного вывода. Может быть установлен от 0 (по умолчанию, без вывода) до 3 (максимальный вывод). Отладочная информация записывается в sys.stdout.

ZipFile.comment¶

Комментарий, связанный с ZIP-файлом, в виде объекта bytes. Если присваивать комментарий экземпляру ZipFile, созданному с режимом 'w', 'x' или 'a', его длина не должна превышать 65535 байт. Комментарии длиннее этого будут обрезаны.

13.5.2. Объекты 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 теперь принимает объект, подобный пути.

13.5.3. Объекты ZipInfo¶ZipInfo Objects

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

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

classmethod ZipInfo.from_file(filename, arcname=None)¶

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

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

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

Новое в версии 3.6.

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

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

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¶

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

13.5.4. Интерфейс командной строки¶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