`zipfile.md`

306 строк · 29.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.2/library/zipfile.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 12.4. [`zipfile`](https://python-all.ru/3.2/library/zipfile.html#module-zipfile) – Работа с ZIP-архивами89**Исходный код:** [Lib/zipfile.py](https://python-all.ru/src/3.2/Lib/zipfile.py)1011---1213Формат ZIP – распространённый стандарт архивации и сжатия. Этот модуль предоставляет инструменты для создания, чтения, записи, добавления и просмотра содержимого ZIP-файлов. Любое продвинутое использование модуля требует понимания формата, описанного в [PKZIP Application Note](https://python-all.ru/3.2/library/zipfile.html).1415Этот модуль в настоящее время не поддерживает многодисковые ZIP-файлы. Он может обрабатывать ZIP-файлы, использующие расширения ZIP64 (то есть ZIP-файлы размером более 4 Гбайт). Он поддерживает дешифрование зашифрованных файлов в ZIP-архивах, но в настоящее время не может создать зашифрованный файл. Дешифрование выполняется крайне медленно, так как реализовано на чистом Python, а не на C.1617Модуль определяет следующие элементы:1819#### `exception zipfile.BadZipFile`2021Исключение, возникающее при повреждённых ZIP-файлах.2223Новое в версии 3.2.2425#### `exception zipfile.BadZipfile`2627Псевдоним [`BadZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.BadZipFile) для совместимости со старыми версиями Python.2829Устарело с версии 3.2.3031#### `exception zipfile.LargeZipFile`3233Исключение, возникающее, когда ZIP-файлу требуется функциональность ZIP64, но она не включена.3435#### `class zipfile.ZipFile`3637Класс для чтения и записи ZIP-файлов. Подробнее о конструкторе см. раздел [*Объекты ZipFile*](https://python-all.ru/3.2/library/zipfile.html#zipfile-objects).3839#### `class zipfile.PyZipFile`4041Класс для создания ZIP-архивов, содержащих библиотеки Python.4243#### `class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))`4445Класс, используемый для представления информации об элементе архива. Экземпляры этого класса возвращаются методами [`getinfo()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.getinfo) и [`infolist()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.infolist) объектов [`ZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile). Большинству пользователей модуля [`zipfile`](https://python-all.ru/3.2/library/zipfile.html#module-zipfile) не нужно создавать такие объекты, достаточно использовать те, что созданы этим модулем. Параметр *filename* должен содержать полное имя элемента архива, а *date\_time* – кортеж из шести полей, описывающих время последнего изменения файла; эти поля описаны в разделе [*ZipInfo Objects*](https://python-all.ru/3.2/library/zipfile.html#zipinfo-objects).4647#### `zipfile.is_zipfile(filename)`4849Возвращает `True`, если *filename* является допустимым ZIP-файлом на основе его сигнатуры, в противном случае возвращает `False`. Параметр *filename* может быть файлом или файлоподобным объектом.5051Изменено в версии 3.1: Поддержка файлов и файлоподобных объектов.5253#### `zipfile.ZIP_STORED`5455Числовая константа для несжатого элемента архива.5657#### `zipfile.ZIP_DEFLATED`5859Числовая константа для обычного метода сжатия ZIP. Для этого требуется модуль [`zlib`](https://python-all.ru/3.2/library/zlib.html#module-zlib). В настоящее время другие методы сжатия не поддерживаются.6061> **См. также**62>63> **[Примечание по применению PKZIP](https://python-all.ru/3.2/library/zipfile.html)**64>65> Документация по формату ZIP-файлов от Фила Каца, создателя формата и используемых алгоритмов.66>67> **[Домашняя страница Info-ZIP](https://python-all.ru/3.2/library/zipfile.html)**68>69> Информация о программах для работы с ZIP-архивами и библиотеках для разработки проекта Info-ZIP.7071## 12.4.1. Объекты ZipFile7273#### `class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=False)`7475Открывает ZIP-файл, где *file* может быть либо путём к файлу (строка), либо файлоподобным объектом. Параметр *mode* должен быть равен `'r'` для чтения существующего файла, `'w'` для усечения и записи нового файла или `'a'` для добавления к существующему файлу. Если *mode* равен `'a'` и *file* ссылается на существующий ZIP-файл, то в него добавляются новые файлы. Если *file* не ссылается на ZIP-файл, то в конец файла добавляется новый ZIP-архив. Это предназначено для встраивания ZIP-архива в другой файл (например, `python.exe`). Если *mode* равен `a` и файл вообще не существует, он создаётся. *compression* – метод сжатия ZIP, используемый при записи архива; должен быть [`ZIP_STORED`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZIP_STORED) или [`ZIP_DEFLATED`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZIP_DEFLATED); нераспознанные значения приведут к возбуждению [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError). Если указан [`ZIP_DEFLATED`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZIP_DEFLATED), но модуль [`zlib`](https://python-all.ru/3.2/library/zlib.html#module-zlib) недоступен, также возбуждается [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError). Значение по умолчанию – [`ZIP_STORED`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZIP_STORED). Если *allowZip64* равно `True`, zipfile будет создавать ZIP-файлы, использующие расширения ZIP64, когда размер zip-файла превышает 2 ГБ. Если оно равно false (по умолчанию), [`zipfile`](https://python-all.ru/3.2/library/zipfile.html#module-zipfile) возбудит исключение, когда для ZIP-файла потребуются расширения ZIP64. Расширения ZIP64 отключены по умолчанию, поскольку стандартные команды **zip** и **unzip** в Unix (утилиты InfoZIP) не поддерживают эти расширения.7677Если файл создан в режиме `'a'` или `'w'`, а затем [`закрыт`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.close) без добавления файлов в архив, в файл будут записаны соответствующие структуры ZIP для пустого архива.7879ZipFile также является контекстным менеджером, поэтому поддерживает инструкцию [`with`](https://python-all.ru/3.2/reference/compound_stmts.html#with). В примере *myzip* закрывается после завершения блока инструкции [`with`](https://python-all.ru/3.2/reference/compound_stmts.html#with), даже если возникло исключение:8081```python82with ZipFile('spam.zip', 'w') as myzip:83    myzip.write('eggs.txt')84```8586Новое в версии 3.2: Добавлена возможность использования [`ZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile) в качестве менеджера контекста.8788#### `ZipFile.close()`8990Закрывает файл архива. Необходимо вызвать [`close()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.close) перед выходом из программы, иначе важные записи не будут записаны.9192#### `ZipFile.getinfo(name)`9394Возвращает объект [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo) с информацией об элементе архива *name*. Вызов [`getinfo()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.getinfo) для имени, отсутствующего в архиве, возбуждает [`KeyError`](https://python-all.ru/3.2/library/exceptions.html#KeyError).9596#### `ZipFile.infolist()`9798Возвращает список, содержащий объект [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo) для каждого элемента архива. Объекты расположены в том же порядке, что и соответствующие записи в реальном ZIP- файле на диске (если был открыт существующий архив).99100#### `ZipFile.namelist()`101102Возвращает список элементов архива по именам.103104#### `ZipFile.open(name, mode='r', pwd=None)`105106Извлекает элемент из архива в виде файлоподобного объекта (ZipExtFile). *name* – это имя файла в архиве или объект [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo). Параметр *mode*, если указан, должен быть одним из следующих: `'r'` (по умолчанию), `'U'` или `'rU'`. Выбор `'U'` или `'rU'` включает поддержку [*универсальных символов новой строки*](https://python-all.ru/3.2/glossary.html#term-universal-newlines) в объекте, доступном только для чтения. *pwd* – это пароль для зашифрованных файлов. Вызов [`open()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.open) на закрытом ZipFile вызовет [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError).107108> **Примечание**109>110> Файлоподобный объект доступен только для чтения и предоставляет следующие методы: `read()`, `readline()`, `readlines()`, `__iter__()`, `__next__()`.111112> **Примечание**113>114> Если ZipFile был создан путём передачи файлоподобного объекта в качестве первого аргумента конструктора, то объект, возвращаемый [`open()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.open), разделяет файловый указатель ZipFile. В таких условиях объект, возвращаемый [`open()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.open), не следует использовать после выполнения любых дополнительных операций над объектом ZipFile. Если ZipFile был создан путём передачи строки (имени файла) в качестве первого аргумента конструктора, то [`open()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.open) создаст новый файловый объект, который будет удерживаться ZipExtFile, что позволяет ему работать независимо от ZipFile.115116> **Примечание**117>118> Методы [`open()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.open), [`read()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.read) и [`extract()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.extract) могут принимать имя файла или объект [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo). Это пригодится при попытке прочитать ZIP-файл, содержащий элементы с повторяющимися именами.119120#### `ZipFile.extract(member, path=None, pwd=None)`121122Извлекает элемент из архива в текущий рабочий каталог; *member* должно быть его полным именем или объектом [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo)). Информация о файле извлекается максимально точно. *path* задаёт другой каталог для извлечения. *member* может быть именем файла или объектом [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo). *pwd* – это пароль для зашифрованных файлов.123124> **Примечание**125>126> Если имя файла элемента является абсолютным путём, то буква диска/UNC-точка и начальные (обратные) слеши будут удалены, например: `///foo/bar` становится `foo/bar` в Unix, а `C:\foo\bar` становится `foo\bar` в Windows. И все компоненты `".."` в имени файла элемента будут удалены, например: `../../foo../../ba..r` становится `foo../ba..r`. В Windows недопустимые символы (`:`, `<`, `>`, `|`, `"`, `?` и `*`) заменяются символом подчёркивания (`_`).127128#### `ZipFile.extractall(path=None, members=None, pwd=None)`129130Извлекает все элементы из архива в текущий рабочий каталог. *path* задаёт другой каталог для извлечения. *members* является необязательным и должен быть подмножеством списка, возвращаемого [`namelist()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.namelist). *pwd* – это пароль для зашифрованных файлов.131132> **Предупреждение**133>134> Никогда не извлекайте архивы из ненадёжных источников без предварительной проверки. Возможно создание файлов за пределами *path*, например, элементов с абсолютными именами, начинающимися с `"/"`, или с именами, содержащими две точки `".."`.135136Изменено в версии 3.2.4: Модуль zipfile пытается предотвратить это. См. примечание к [`extract()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.extract).137138#### `ZipFile.printdir()`139140Выводит оглавление архива в `sys.stdout`.141142#### `ZipFile.setpassword(pwd)`143144Устанавливает *pwd* в качестве пароля по умолчанию для извлечения зашифрованных файлов.145146#### `ZipFile.read(name, pwd=None)`147148Возвращает байты файла *name* в архиве. *name* – это имя файла в архиве или объект [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo). Архив должен быть открыт для чтения или добавления. *pwd* – пароль, используемый для зашифрованных файлов; если указан, он переопределяет пароль по умолчанию, заданный с помощью [`setpassword()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.setpassword). Вызов [`read()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.read) на закрытом ZipFile приведёт к возникновению [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError).149150#### `ZipFile.testzip()`151152Читает все файлы в архиве и проверяет их CRC и заголовки файлов. Возвращает имя первого повреждённого файла или `None`, если все файлы в порядке. Вызов [`testzip()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.testzip) на закрытом ZipFile вызовет [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError).153154#### `ZipFile.write(filename, arcname=None, compress_type=None)`155156Записывает файл с именем *filename* в архив, присваивая ему имя в архиве *arcname* (по умолчанию оно будет таким же, как *filename*, но без буквы диска и с удалёнными начальными разделителями пути). Если указан, *compress\_type* переопределяет значение, заданное для параметра *compression* конструктора для новой записи. Архив должен быть открыт в режиме `'w'` или `'a'` – вызов [`write()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.write) на ZipFile, созданном в режиме `'r'`, вызовет [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError). Вызов [`write()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.write) на закрытом ZipFile вызовет [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError).157158> **Примечание**159>160> Официальной кодировки имён файлов для ZIP-файлов не существует. Если используются имена файлов в Unicode, необходимо преобразовать их в байтовые строки в нужной кодировке перед передачей в [`write()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.write). WinZip интерпретирует все имена файлов как закодированные в CP437, также известной как DOS Latin.161162> **Примечание**163>164> Архивные имена должны быть относительными по отношению к корню архива, то есть не должны начинаться с разделителя пути.165166> **Примечание**167>168> Если `arcname` (или `filename`, если `arcname` не указан) содержит нулевой байт, имя файла в архиве будет обрезано по нулевому байту.169170#### `ZipFile.writestr(zinfo_or_arcname, bytes[, compress_type])`171172Записывает строку *bytes* в архив; *zinfo\_or\_arcname* – это либо имя файла, которое будет присвоено в архиве, либо экземпляр [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo). Если это экземпляр, необходимо указать как минимум имя файла, дату и время. Если это имя, дата и время устанавливаются на текущие. Архив должен быть открыт в режиме `'w'` или `'a'` – вызов [`writestr()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.writestr) на ZipFile, созданном в режиме `'r'`, вызовет [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError). Вызов [`writestr()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.writestr) на закрытом ZipFile вызовет [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError).173174Если указан, *compress\_type* переопределяет значение, заданное для параметра *compression* конструктора для новой записи, или значение в *zinfo\_or\_arcname* (если это экземпляр [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo)).175176> **Примечание**177>178> При передаче экземпляра [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo) в качестве параметра *zinfo\_or\_arcname* используемый метод сжатия будет тем, который указан в члене *compress\_type* данного экземпляра [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo). По умолчанию конструктор [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo) устанавливает этот член в [`ZIP_STORED`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZIP_STORED).179180Изменено в версии 3.2: Аргумент *compress\_type*.181182Также доступны следующие атрибуты данных:183184#### `ZipFile.debug`185186Уровень отладочного вывода. Может быть установлен от `0` (по умолчанию, без вывода) до `3` (максимальный вывод). Отладочная информация записывается в `sys.stdout`.187188#### `ZipFile.comment`189190Текст комментария, связанного с ZIP-файлом. Если присваивается комментарий экземпляру [`ZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile), созданному в режиме 'a' или 'w', это должна быть строка длиной не более 65535 байт. Комментарии длиннее этого значения будут обрезаны в записанном архиве при вызове [`close()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.close).191192## 12.4.2. Объекты PyZipFile193194Конструктор [`PyZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.PyZipFile) принимает те же параметры, что и конструктор [`ZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile), и один дополнительный параметр *optimize*.195196#### `class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=False, optimize=-1)`197198Новое в версии 3.2: Параметр *optimize*.199200Помимо методов, имеющихся у объектов [`ZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile), у экземпляров есть один дополнительный метод:201202#### `writepy(pathname, basename='')`203204Ищет файлы `*.py` и добавляет соответствующий файл в архив.205206Если параметр *optimize* конструктора [`PyZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.PyZipFile) не был задан или равен `-1`, то соответствующим файлом будет `*.pyo`, если такой доступен, иначе `*.pyc`, при необходимости компилируя исходный код.207208Если параметр *optimize* конструктора [`PyZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.PyZipFile) был равен `0`, `1` или `2`, в архив добавляются только файлы с этим уровнем оптимизации (см. [`compile()`](https://python-all.ru/3.2/library/functions.html#compile)), при необходимости компилируя исходный код.209210Если путь является файлом, имя файла должно заканчиваться на `.py`, и на верхний уровень (без информации о пути) добавляется только соответствующий файл `*.py[co]`. Если путь является файлом, который не заканчивается на `.py`, будет возбуждено [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError). Если это каталог, и этот каталог не является каталогом пакета, то на верхнем уровне добавляются все файлы `*.py[co]`. Если каталог является пакетным, то все `*.py[co]` добавляются под именем пакета в качестве пути к файлу, и если какие-либо подкаталоги являются пакетными, все они добавляются рекурсивно. *basename* предназначен только для внутреннего использования. Метод [`writepy()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.PyZipFile.writepy) создаёт архивы с именами файлов, как в примере:211212```python213string.pyc                   # Имя верхнего уровня214test/__init__.pyc            # Каталог пакета215test/testall.pyc             # Модуль test.testall216test/bogus/__init__.pyc      # Каталог подпакета217test/bogus/myfile.pyc        # Подмодуль test.bogus.myfile218```219220## 12.4.3. Объекты ZipInfo221222Экземпляры класса [`ZipInfo`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipInfo) возвращаются методами [`getinfo()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.getinfo) и [`infolist()`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile.infolist) объектов [`ZipFile`](https://python-all.ru/3.2/library/zipfile.html#zipfile.ZipFile). Каждый объект хранит информацию об одном элементе ZIP-архива.223224Экземпляры имеют следующие атрибуты:225226#### `ZipInfo.filename`227228Имя файла в архиве.229230#### `ZipInfo.date_time`231232Время и дата последнего изменения элемента архива. Это кортеж из шести значений:233234| Индекс | Значение |235| --- | --- |236| `0` | Год (\>= 1980) |237| `1` | Месяц (начиная с 1) |238| `2` | День месяца (начиная с 1) |239| `3` | Часы (начиная с 0) |240| `4` | Минуты (начиная с 0) |241| `5` | Секунды (начиная с 0) |242243> **Примечание**244>245> Формат ZIP-файлов не поддерживает метки времени до 1980 года.246247#### `ZipInfo.compress_type`248249Тип сжатия для элемента архива.250251#### `ZipInfo.comment`252253Комментарий для отдельного элемента архива.254255#### `ZipInfo.extra`256257Данные поля расширения. В [Примечании к приложению PKZIP](https://python-all.ru/3.2/library/zipfile.html) содержатся комментарии о внутренней структуре данных, содержащихся в этой строке.258259#### `ZipInfo.create_system`260261Система, создавшая ZIP-архив.262263#### `ZipInfo.create_version`264265Версия PKZIP, создавшая ZIP-архив.266267#### `ZipInfo.extract_version`268269Версия PKZIP, необходимая для извлечения архива.270271#### `ZipInfo.reserved`272273Должно быть равно нулю.274275#### `ZipInfo.flag_bits`276277Биты флагов ZIP.278279#### `ZipInfo.volume`280281Номер тома заголовка файла.282283#### `ZipInfo.internal_attr`284285Внутренние атрибуты.286287#### `ZipInfo.external_attr`288289Внешние атрибуты файла.290291#### `ZipInfo.header_offset`292293Смещение в байтах до заголовка файла.294295#### `ZipInfo.CRC`296297CRC-32 несжатого файла.298299#### `ZipInfo.compress_size`300301Размер сжатых данных.302303#### `ZipInfo.file_size`304305Размер несжатого файла.306