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

Объекты ZipFile¶ZipFile Objects

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=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).

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

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

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(), 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: Теперь 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, compresslevel=None)¶

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

Примечание

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

Примечание

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

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

Имя ZIP-файла.

ZipFile.debug¶

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

ZipFile.comment¶

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

Объекты 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)¶

Создаёт экземпляр 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¶

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

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