`zipfile.md`

423 строк · 25.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/zipfile.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 12.4. `zipfile` – работа с ZIP-архивами89Формат ZIP – распространённый стандарт архивации и сжатия. Этот модуль предоставляет инструменты для создания, чтения, записи, добавления и просмотра содержимого ZIP-файлов. Любое продвинутое использование модуля требует понимания формата, описанного в [PKZIP Application Note](https://python-all.ru/3.1/library/zipfile.html).1011Этот модуль в настоящее время не поддерживает многодисковые ZIP-файлы. Он может обрабатывать ZIP-файлы, использующие расширения ZIP64 (то есть ZIP-файлы размером более 4 Гбайт). Он поддерживает дешифрование зашифрованных файлов в ZIP-архивах, но в настоящее время не может создать зашифрованный файл. Дешифрование выполняется крайне медленно, так как реализовано на чистом Python, а не на C.1213О других форматах архивов см. модули [`bz2`](https://python-all.ru/3.1/library/bz2.html#module-bz2), [`gzip`](https://python-all.ru/3.1/library/gzip.html#module-gzip) и [`tarfile`](https://python-all.ru/3.1/library/tarfile.html#module-tarfile).1415Модуль определяет следующие элементы:1617#### `exception zipfile.BadZipfile`1819Исключение, вызываемое для повреждённых ZIP-файлов (старое название:2021`zipfile.error`2223).2425#### `exception zipfile.LargeZipFile`2627Исключение, возникающее, когда ZIP-файлу требуется функциональность ZIP64, но она не включена.2829#### `class zipfile.ZipFile`3031Класс для чтения и записи ZIP-файлов. Подробнее о конструкторе см. раздел3233[*Объекты ZipFile*](https://python-all.ru/3.1/library/zipfile.html#zipfile-objects)3435.3637#### `class zipfile.PyZipFile`3839Класс для создания ZIP-архивов, содержащих библиотеки Python.4041#### `class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))`4243Класс, используемый для представления информации об элементе архива. Экземпляры этого класса возвращаются методами4445`getinfo()`4647и4849`infolist()`5051объектов5253[`ZipFile`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile)5455. Большинству пользователей модуля5657`zipfile`5859не потребуется создавать их – достаточно использовать те, что созданы этим модулем.6061*filename*6263должно быть полным именем элемента архива, а6465*date\_time*6667– кортежем из шести полей, описывающих время последнего изменения файла; поля описаны в разделе6869[*ZipInfo Objects*](https://python-all.ru/3.1/library/zipfile.html#zipinfo-objects)7071.7273#### `zipfile.is_zipfile(filename)`7475Возвращает `True`, если *filename* является допустимым ZIP-файлом на основе его сигнатуры, в противном случае возвращает `False`. Параметр *filename* может быть файлом или файлоподобным объектом.7677Изменено в версии 3.1: Добавлена поддержка файлов и файлоподобных объектов.7879#### `zipfile.ZIP_STORED`8081Числовая константа для несжатого элемента архива.8283#### `zipfile.ZIP_DEFLATED`8485Числовая константа для стандартного метода сжатия ZIP. Для её использования требуется модуль zlib. Другие методы сжатия в настоящее время не поддерживаются.8687> **См. также**88>89> **[Примечание по применению PKZIP](https://python-all.ru/3.1/library/zipfile.html)**90>91> Документация по формату ZIP-файлов от Фила Каца, создателя формата и используемых алгоритмов.92>93> **[Домашняя страница Info-ZIP](https://python-all.ru/3.1/library/zipfile.html)**94>95> Информация о программах для работы с ZIP-архивами и библиотеках для разработки проекта Info-ZIP.9697## 12.4.1. Объекты ZipFile9899#### `class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=False)`100101Открывает ZIP-файл. *file* может быть путём к файлу (строка) или объектом, похожим на файл. Параметр *mode* должен быть равен `'r'` для чтения существующего файла, `'w'` для усечения и записи нового файла, или `'a'` для добавления к существующему файлу. Если *mode* равен `'a'` и *file* ссылается на существующий ZIP-файл, то в него добавляются дополнительные файлы. Если *file* не ссылается на ZIP-файл, то к файлу добавляется новый ZIP-архив. Это предназначено для встраивания ZIP-архива в другой файл, например `python.exe`. Использование102103```python104cat myzip.zip >> python.exe105```106107... тоже работает, и как минимум **WinZip** может читать такие файлы. Если *mode* равен `a` и файл вообще не существует, он создаётся. *compression* – это метод сжатия ZIP, используемый при записи архива; он должен быть [`ZIP_STORED`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZIP_STORED) или [`ZIP_DEFLATED`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZIP_DEFLATED); нераспознанные значения приведут к возникновению [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError). Если указан [`ZIP_DEFLATED`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZIP_DEFLATED), но модуль [`zlib`](https://python-all.ru/3.1/library/zlib.html#module-zlib) недоступен, также возникает [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError). Значение по умолчанию – [`ZIP_STORED`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZIP_STORED). Если *allowZip64* равно `True`, zipfile будет создавать ZIP-файлы, использующие расширения ZIP64, когда размер архива превышает 2 ГБ. Если оно равно False (по умолчанию), `zipfile` вызовет исключение, когда ZIP-файлу потребуются расширения ZIP64. Расширения ZIP64 отключены по умолчанию, потому что стандартные команды **zip** и **unzip** в Unix (утилиты InfoZIP) не поддерживают эти расширения.108109Если файл создан в режиме `'a'` или `'w'`, а затем вызван [`close()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.close)d без добавления каких-либо файлов в архив, в файл будут записаны соответствующие структуры ZIP для пустого архива.110111#### `ZipFile.close()`112113Закрывает файл архива. Необходимо вызвать114115[`close()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.close)116117перед выходом из программы, иначе важные записи не будут записаны.118119#### `ZipFile.getinfo(name)`120121Возвращает объект122123[`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo)124125с информацией об элементе архива126127*name*128129. Вызов130131[`getinfo()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.getinfo)132133для имени, отсутствующего в архиве, возбуждает134135[`KeyError`](https://python-all.ru/3.1/library/exceptions.html#KeyError)136137.138139#### `ZipFile.infolist()`140141Возвращает список, содержащий объект142143[`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo)144145для каждого элемента архива. Объекты расположены в том же порядке, что и соответствующие записи в реальном ZIP- файле на диске (если был открыт существующий архив).146147#### `ZipFile.namelist()`148149Возвращает список элементов архива по именам.150151#### `ZipFile.open(name, mode='r', pwd=None)`152153Извлекает элемент из архива в виде файлоподобного объекта (ZipExtFile). *name* – это имя файла в архиве или объект [`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo). Параметр *mode*, если указан, должен быть одним из следующих: `'r'` (по умолчанию), `'U'` или `'rU'`. Выбор `'U'` или `'rU'` включает поддержку универсальных символов новой строки в объекте, доступном только для чтения. *pwd* – пароль для зашифрованных файлов. Вызов [`open()`](https://python-all.ru/3.1/library/functions.html#open) для закрытого ZipFile приведёт к возникновению [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError).154155> **Примечание**156>157> Файлоподобный объект доступен только для чтения и предоставляет следующие методы: `read()`, `readline()`, `readlines()`, `__iter__()`, `__next__()`.158159> **Примечание**160>161> Если ZipFile был создан путём передачи файлоподобного объекта в качестве первого аргумента конструктора, то объект, возвращаемый [`open()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.open), разделяет файловый указатель ZipFile. В таких условиях объект, возвращаемый [`open()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.open), не следует использовать после выполнения любых дополнительных операций над объектом ZipFile. Если ZipFile был создан путём передачи строки (имени файла) в качестве первого аргумента конструктора, то [`open()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.open) создаст новый файловый объект, который будет удерживаться ZipExtFile, что позволяет ему работать независимо от ZipFile.162163> **Примечание**164>165> Методы [`open()`](https://python-all.ru/3.1/library/functions.html#open), [`read()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.read) и [`extract()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.extract) могут принимать имя файла или объект [`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo). Это пригодится при попытке прочитать ZIP-файл, содержащий элементы с повторяющимися именами.166167#### `ZipFile.extract(member, path=None, pwd=None)`168169Извлекает элемент из архива в текущий рабочий каталог;170171*member*172173должно быть его полным именем или объектом174175[`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo)176177). Информация о файле извлекается максимально точно.178179*path*180181задаёт другой каталог для извлечения.182183*member*184185может быть именем файла или объектом186187[`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo)188189.190191*pwd*192193– это пароль для зашифрованных файлов.194195#### `ZipFile.extractall(path=None, members=None, pwd=None)`196197Извлекает все элементы из архива в текущий рабочий каталог. *path* задаёт другой каталог для извлечения. *members* является необязательным и должен быть подмножеством списка, возвращаемого [`namelist()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.namelist). *pwd* – это пароль для зашифрованных файлов.198199> **Предупреждение**200>201> Никогда не извлекайте архивы из ненадёжных источников без предварительной проверки. Возможно создание файлов за пределами *path*, например, элементов с абсолютными именами, начинающимися с `"/"`, или с именами, содержащими две точки `".."`.202203#### `ZipFile.printdir()`204205Выводит оглавление архива в206207`sys.stdout`208209.210211#### `ZipFile.setpassword(pwd)`212213Устанавливает214215*pwd*216217в качестве пароля по умолчанию для извлечения зашифрованных файлов.218219#### `ZipFile.read(name, pwd=None)`220221Возвращает байты файла222223*name*224225в архиве.226227*name*228229– это имя файла в архиве или объект230231[`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo)232233. Архив должен быть открыт для чтения или добавления.234235*pwd*236237– пароль, используемый для зашифрованных файлов; если указан, он переопределяет пароль по умолчанию, заданный с помощью238239[`setpassword()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.setpassword)240241. Вызов242243[`read()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.read)244245на закрытом ZipFile приведёт к возникновению246247[`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError)248249.250251#### `ZipFile.testzip()`252253Читает все файлы в архиве и проверяет их CRC и заголовки файлов. Возвращает имя первого повреждённого файла или254255`None`256257, если все файлы в порядке. Вызов258259[`testzip()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.testzip)260261на закрытом ZipFile вызовет262263[`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError)264265.266267#### `ZipFile.write(filename, arcname=None, compress_type=None)`268269Записывает файл с именем *filename* в архив, присваивая ему имя в архиве *arcname* (по умолчанию оно будет таким же, как *filename*, но без буквы диска и с удалёнными начальными разделителями пути). Если указан, *compress\_type* переопределяет значение, заданное для параметра *compression* конструктора для новой записи. Архив должен быть открыт в режиме `'w'` или `'a'` – вызов [`write()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.write) на ZipFile, созданном в режиме `'r'`, вызовет [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError). Вызов [`write()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.write) на закрытом ZipFile вызовет [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError).270271> **Примечание**272>273> Официальной кодировки имён файлов для ZIP-файлов не существует. Если используются имена файлов в Unicode, необходимо преобразовать их в байтовые строки в нужной кодировке перед передачей в [`write()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.write). WinZip интерпретирует все имена файлов как закодированные в CP437, также известной как DOS Latin.274275> **Примечание**276>277> Архивные имена должны быть относительными по отношению к корню архива, то есть не должны начинаться с разделителя пути.278279> **Примечание**280>281> Если `arcname` (или `filename`, если `arcname` не указан) содержит нулевой байт, имя файла в архиве будет обрезано по нулевому байту.282283#### `ZipFile.writestr(zinfo_or_arcname, bytes)`284285Записывает строку *bytes* в архив; *zinfo\_or\_arcname* – это либо имя файла, которое будет присвоено в архиве, либо экземпляр [`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo). Если это экземпляр, необходимо указать как минимум имя файла, дату и время. Если это имя, дата и время устанавливаются на текущие. Архив должен быть открыт в режиме `'w'` или `'a'` – вызов [`writestr()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.writestr) на ZipFile, созданном в режиме `'r'`, вызовет [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError). Вызов [`writestr()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.writestr) на закрытом ZipFile вызовет [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError).286287> **Примечание**288>289> При передаче экземпляра [`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo) в качестве параметра *zinfo\_or\_arcname* используемый метод сжатия будет тем, который указан в члене *compress\_type* данного экземпляра [`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo). По умолчанию конструктор [`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo) устанавливает этот член в [`ZIP_STORED`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZIP_STORED).290291Также доступны следующие атрибуты данных:292293#### `ZipFile.debug`294295Уровень отладочного вывода. Может быть установлен от296297`0`298299(по умолчанию, без вывода) до300301`3`302303(максимальный вывод). Отладочная информация записывается в304305`sys.stdout`306307.308309#### `ZipFile.comment`310311Текст комментария, связанного с ZIP-файлом. При назначении комментария экземпляру312313[`ZipFile`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile)314315, созданному в режиме 'a' или 'w', это должна быть строка длиной не более 65535 байт. Комментарии длиннее этого значения будут усечены в записываемом архиве при вызове316317[`ZipFile.close()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile.close)318319.320321## 12.4.2. Объекты PyZipFile322323Конструктор [`PyZipFile`](https://python-all.ru/3.1/library/zipfile.html#zipfile.PyZipFile) принимает те же параметры, что и конструктор [`ZipFile`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile). Экземпляры имеют один дополнительный метод по сравнению с объектами [`ZipFile`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile).324325#### `PyZipFile.writepy(pathname, basename='')`326327Search for files `*.py` and add the corresponding file to the archive. The corresponding file is a `*.pyo` file if available, else a `*.pyc` file, compiling if necessary. If the pathname is a file, the filename must end with `.py`, and just the (corresponding `*.py[co]`) file is added at the top level (no path information). If the pathname is a file that does not end with `.py`, a [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError) will be raised. If it is a directory, and the directory is not a package directory, then all the files `*.py[co]` are added at the top level. If the directory is a package directory, then all `*.py[co]` are added under the package name as a file path, and if any subdirectories are package directories, all of these are added recursively. *basename* is intended for internal use only. The [`writepy()`](https://python-all.ru/3.1/library/zipfile.html#zipfile.PyZipFile.writepy) method makes archives with file names like this:328329```python330string.pyc                                # Имя верхнего уровня331test/__init__.pyc                         # Каталог пакета332test/testall.pyc                          # Модуль test.testall333test/bogus/__init__.pyc                   # Каталог подпакета334test/bogus/myfile.pyc                     # Подмодуль test.bogus.myfile335```336337## 12.4.3. Объекты ZipInfo338339Экземпляры класса [`ZipInfo`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipInfo) возвращаются методами `getinfo()` и `infolist()` объектов [`ZipFile`](https://python-all.ru/3.1/library/zipfile.html#zipfile.ZipFile). Каждый объект хранит информацию об одном элементе ZIP-архива.340341Экземпляры имеют следующие атрибуты:342343#### `ZipInfo.filename`344345Имя файла в архиве.346347#### `ZipInfo.date_time`348349Время и дата последнего изменения элемента архива. Это кортеж из шести значений:350351| Индекс | Значение |352| --- | --- |353| `0` | Год |354| `1` | Месяц (начиная с 1) |355| `2` | День месяца (начиная с 1) |356| `3` | Часы (начиная с 0) |357| `4` | Минуты (начиная с 0) |358| `5` | Секунды (начиная с 0) |359360#### `ZipInfo.compress_type`361362Тип сжатия для элемента архива.363364#### `ZipInfo.comment`365366Комментарий для отдельного элемента архива.367368#### `ZipInfo.extra`369370Данные поля расширения. В371372[Примечании к приложению PKZIP](https://python-all.ru/3.1/library/zipfile.html)373374содержатся комментарии о внутренней структуре данных, содержащихся в этой строке.375376#### `ZipInfo.create_system`377378Система, создавшая ZIP-архив.379380#### `ZipInfo.create_version`381382Версия PKZIP, создавшая ZIP-архив.383384#### `ZipInfo.extract_version`385386Версия PKZIP, необходимая для извлечения архива.387388#### `ZipInfo.reserved`389390Должно быть равно нулю.391392#### `ZipInfo.flag_bits`393394Биты флагов ZIP.395396#### `ZipInfo.volume`397398Номер тома заголовка файла.399400#### `ZipInfo.internal_attr`401402Внутренние атрибуты.403404#### `ZipInfo.external_attr`405406Внешние атрибуты файла.407408#### `ZipInfo.header_offset`409410Смещение в байтах до заголовка файла.411412#### `ZipInfo.CRC`413414CRC-32 несжатого файла.415416#### `ZipInfo.compress_size`417418Размер сжатых данных.419420#### `ZipInfo.file_size`421422Размер несжатого файла.423