`tarfile.md`

967 строк · 91.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/library/tarfile.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `tarfile` – Чтение и запись файлов tar-архивов89**Исходный код:** [Lib/tarfile.py](https://python-all.ru/src/3.15/Lib/tarfile.py)1011---1213Модуль `tarfile` позволяет читать и записывать tar-архивы, в том числе сжатые gzip, bz2 и lzma. Используйте модуль [`zipfile`](https://python-all.ru/3.15/library/zipfile.html#module-zipfile) для чтения и записи файлов `.zip` или функции более высокого уровня из [shutil](https://python-all.ru/3.15/library/shutil.html#archiving-operations).1415Некоторые факты и цифры:1617- читает и записывает архивы [`gzip`](https://python-all.ru/3.15/library/gzip.html#module-gzip), [`bz2`](https://python-all.ru/3.15/library/bz2.html#module-bz2), [`compression.zstd`](https://python-all.ru/3.15/library/compression.zstd.html#module-compression.zstd) и [`lzma`](https://python-all.ru/3.15/library/lzma.html#module-lzma), если соответствующие модули доступны.1819  Если каких-либо из этих [дополнительных модулей](https://python-all.ru/3.15/glossary.html#term-optional-module) нет в вашей копии CPython, обратитесь к документации от распространителя (то есть того, кто предоставил вам Python). Если вы распространитель, см. [Требования к дополнительным модулям](https://python-all.ru/3.15/using/configure.html#optional-module-requirements).20- поддержка чтения/записи формата POSIX.1-1988 (ustar).21- поддержка чтения/записи формата GNU tar, включая расширения *longname* и *longlink*, поддержка только чтения всех вариантов расширения *sparse*, включая восстановление разрежённых файлов.22- поддержка чтения/записи формата POSIX.1-2001 (pax).23- работает с директориями, обычными файлами, жёсткими ссылками, символическими ссылками, каналами FIFO, символьными и блочными устройствами, а также может получать и восстанавливать информацию о файлах, такую как временная метка, права доступа и владелец.2425Изменено в версии 3.3: Добавлена поддержка сжатия [`lzma`](https://python-all.ru/3.15/library/lzma.html#module-lzma).2627Изменено в версии 3.12: Архивы извлекаются с использованием [фильтра](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-filter), что позволяет либо ограничить неожиданные/опасные возможности, либо признать их ожидаемыми и полностью доверять архиву.2829Изменено в версии 3.14: Фильтр извлечения по умолчанию установлен на [`data`](https://python-all.ru/3.15/library/tarfile.html#tarfile.data_filter), что запрещает некоторые опасные возможности, такие как ссылки на абсолютные пути или пути за пределами целевой директории. Ранее стратегия фильтрации была эквивалентна [`fully_trusted`](https://python-all.ru/3.15/library/tarfile.html#tarfile.fully_trusted_filter).3031Изменено в версии 3.14: Добавлена поддержка сжатия Zstandard с использованием [`compression.zstd`](https://python-all.ru/3.15/library/compression.zstd.html#module-compression.zstd).3233#### `tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)`3435Возвращает объект [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile) для имени пути *name*. Подробную информацию об объектах `TarFile` и допустимых именованных аргументах см. в разделе [Объекты TarFile](https://python-all.ru/3.15/library/tarfile.html#tarfile-objects).3637*mode* должен быть строкой вида `'filemode[:compression]'`, по умолчанию равен `'r'`. Вот полный список комбинаций режимов:3839| Режим | Действие |40| --- | --- |41| `'r'` или `'r:*'` | Открыть для чтения с прозрачным сжатием (рекомендуется). |42| `'r:'` | Открыть для чтения исключительно без сжатия. |43| `'r:gz'` | Открыть для чтения со сжатием gzip. |44| `'r:bz2'` | Открыть для чтения со сжатием bzip2. |45| `'r:xz'` | Открыть для чтения со сжатием lzma. |46| `'r:zst'` | Открыть для чтения со сжатием Zstandard. |47| `'x'` или `'x:'` | Создать tar-файл исключительно без сжатия. Вызывает исключение [`FileExistsError`](https://python-all.ru/3.15/library/exceptions.html#FileExistsError), если файл уже существует. |48| `'x:gz'` | Создать tar-файл со сжатием gzip. Вызывает исключение [`FileExistsError`](https://python-all.ru/3.15/library/exceptions.html#FileExistsError), если файл уже существует. |49| `'x:bz2'` | Создать tar-файл со сжатием bzip2. Вызывает исключение [`FileExistsError`](https://python-all.ru/3.15/library/exceptions.html#FileExistsError), если файл уже существует. |50| `'x:xz'` | Создать tar-файл со сжатием lzma. Вызывает исключение [`FileExistsError`](https://python-all.ru/3.15/library/exceptions.html#FileExistsError), если файл уже существует. |51| `'x:zst'` | Создать tar-файл со сжатием Zstandard. Вызывает исключение [`FileExistsError`](https://python-all.ru/3.15/library/exceptions.html#FileExistsError), если файл уже существует. |52| `'a'` или `'a:'` | Открыть для добавления без сжатия. Файл создаётся, если он не существует. |53| `'w'` или `'w:'` | Открывается для записи без сжатия. |54| `'w:gz'` | Открывается для записи со сжатием gzip. |55| `'w:bz2'` | Открывается для записи со сжатием bzip2. |56| `'w:xz'` | Открывается для записи со сжатием lzma. |57| `'w:zst'` | Открывается для записи со сжатием Zstandard. |5859Обратите внимание, что `'a:gz'`, `'a:bz2'` или `'a:xz'` невозможны. Если *режим* не подходит для открытия определённого (сжатого) файла для чтения, возбуждается [`ReadError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.ReadError). Используйте *режим* `'r'`, чтобы избежать этого. Если метод сжатия не поддерживается, возбуждается [`CompressionError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.CompressionError).6061Если указан *fileobj*, он используется вместо [файлового объекта](https://python-all.ru/3.15/glossary.html#term-file-object), открытого в бинарном режиме для *имени*. Предполагается, что он находится на позиции 0.6263Для режимов `'w:gz'`, `'x:gz'`, `'w|gz'`, `'w:bz2'`, `'x:bz2'`, `'w|bz2'`, `tarfile.open()` принимает именованный аргумент *compresslevel* (по умолчанию `6`) для указания уровня сжатия файла.6465Для режимов `'w:xz'`, `'x:xz'` и `'w|xz'`, `tarfile.open()` принимает именованный аргумент *preset* для указания уровня сжатия файла.6667Для режимов `'w:zst'`, `'x:zst'` и `'w|zst'`, `tarfile.open()` принимает именованный аргумент *level* для указания уровня сжатия файла. Также можно передать именованный аргумент *options*, задающий дополнительные параметры сжатия Zstandard, описанные в [`CompressionParameter`](https://python-all.ru/3.15/library/compression.zstd.html#compression.zstd.CompressionParameter). Именованный аргумент *zstd\_dict* можно использовать для передачи [`ZstdDict`](https://python-all.ru/3.15/library/compression.zstd.html#compression.zstd.ZstdDict), словаря Zstandard, применяемого для улучшения сжатия небольших объёмов данных.6869Для режимов `'w:gz'` и `'w|gz'` `tarfile.open()` принимает именованный аргумент *mtime* для создания заголовка gzip-архива с этой mtime. По умолчанию mtime устанавливается равным времени создания архива. Используйте *mtime* `0` для создания сжатого потока, не зависящего от времени создания, для воспроизводимого вывода.7071Для специальных целей существует второй формат для *mode*: `'filemode|[compression]'`. `tarfile.open()` вернёт объект [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile), который обрабатывает данные как поток блоков. Произвольный доступ к файлу не осуществляется. Если передан *fileobj*, им может быть любой объект, имеющий метод [`read()`](https://python-all.ru/3.15/library/io.html#io.RawIOBase.read) или [`write()`](https://python-all.ru/3.15/library/io.html#io.RawIOBase.write) (в зависимости от *режима*), работающий с байтами. *bufsize* задаёт размер блока, по умолчанию `20 * 512` байт. Используйте этот вариант в сочетании, например, с `sys.stdin.buffer`, сокетным [файловым объектом](https://python-all.ru/3.15/glossary.html#term-file-object) или ленточным устройством. Однако такой объект `TarFile` ограничен тем, что не допускает произвольного доступа; см. [Примеры](https://python-all.ru/3.15/library/tarfile.html#tar-examples). Текущие возможные режимы:7273| Режим | Действие |74| --- | --- |75| `'r\|*'` | Открывает *поток данных* tar-блоков для чтения с прозрачным сжатием. |76| `'r\|'` | Открывает *поток данных* несжатых tar-блоков для чтения. |77| `'r\|gz'` | Открывает сжатый gzip *поток данных* для чтения. |78| `'r\|bz2'` | Открывает сжатый bzip2 *поток данных* для чтения. |79| `'r\|xz'` | Открывает сжатый lzma *поток данных* для чтения. |80| `'r\|zst'` | Открывает сжатый Zstandard *поток данных* для чтения. |81| `'w\|'` | Открывает несжатый *поток данных* для записи. |82| `'w\|gz'` | Открывает сжатый gzip *поток данных* для записи. |83| `'w\|bz2'` | Открывает сжатый bzip2 *поток данных* для записи. |84| `'w\|xz'` | Открывает сжатый lzma *поток данных* для записи. |85| `'w\|zst'` | Открывает сжатый Zstandard *поток данных* для записи. |8687Изменено в версии 3.5: Добавлен режим `'x'` (эксклюзивное создание).8889Изменено в версии 3.6: Параметр *name* принимает [объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object).9091Изменено в версии 3.12: Именованный аргумент *compresslevel* теперь также работает для потоков данных.9293Изменено в версии 3.14: Именованный аргумент *preset* теперь также работает для потоков данных.9495Изменено в версии 3.15: Уровень сжатия по умолчанию был снижен до 6 (с 9). Это уровень, используемый большинством инструментов сжатия, и он обеспечивает более удачный компромисс между скоростью и производительностью.9697#### `class tarfile.TarFile`9899Класс для чтения и записи tar-архивов. Не используйте этот класс напрямую: вместо него используйте [`tarfile.open()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.open). См. [Объекты TarFile](https://python-all.ru/3.15/library/tarfile.html#tarfile-objects).100101#### `tarfile.is_tarfile(name)`102103Возвращает [`True`](https://python-all.ru/3.15/library/constants.html#True), если *name* является tar-архивом, который может прочитать модуль `tarfile`. *name* может быть [`str`](https://python-all.ru/3.15/library/stdtypes.html#str), файлом или файлоподобным объектом.104105Изменено в версии 3.9: Добавлена поддержка файлов и файлоподобных объектов.106107Модуль `tarfile` определяет следующие исключения:108109#### `exception tarfile.TarError`110111Базовый класс для всех исключений `tarfile`.112113#### `exception tarfile.ReadError`114115Возникает при открытии tar-архива, который не может быть обработан модулем `tarfile` или является некорректным.116117#### `exception tarfile.CompressionError`118119Возникает, когда метод сжатия не поддерживается или данные не удаётся корректно декодировать.120121#### `exception tarfile.StreamError`122123Возникает при ограничениях, типичных для объектов, работающих в режиме потока [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile).124125#### `exception tarfile.ExtractError`126127Возникает при *нефатальных* ошибках при использовании [`TarFile.extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract), но только если [`TarFile.errorlevel`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.errorlevel)`== 2`.128129#### `exception tarfile.HeaderError`130131Возникает при вызове [`TarInfo.frombuf()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.frombuf), если полученный буфер некорректен.132133#### `exception tarfile.FilterError`134135Базовый класс для элементов, [отклонённых](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-refuse) фильтрами.136137#### `tarinfo`138139Информация об элементе, который фильтр отказался извлекать, в виде [TarInfo](https://python-all.ru/3.15/library/tarfile.html#tarinfo-objects).140141#### `exception tarfile.AbsolutePathError`142143Возникает при отказе извлекать элемент с абсолютным путём.144145#### `exception tarfile.OutsideDestinationError`146147Возникает при отказе извлекать элемент за пределами целевого каталога.148149#### `exception tarfile.SpecialFileError`150151Возникает при отказе извлекать специальный файл (например, устройство или канал).152153#### `exception tarfile.AbsoluteLinkError`154155Возникает при отказе извлекать символическую ссылку с абсолютным путём.156157#### `exception tarfile.LinkOutsideDestinationError`158159Возникает при отказе извлекать символическую ссылку, указывающую за пределы целевого каталога.160161#### `exception tarfile.LinkFallbackError`162163Возникает при отказе эмулировать ссылку (жёсткую или символическую) путём извлечения другого элемента архива, если этот элемент был бы отклонён расположением фильтра. Исключение, вызванное для отклонения заменяющего элемента, доступно как `BaseException.__context__`.164165Добавлено в версии 3.15.166167На уровне модуля доступны следующие константы:168169#### `tarfile.ENCODING`170171Кодировка символов по умолчанию: `'utf-8'` в Windows, значение, возвращаемое [`sys.getfilesystemencoding()`](https://python-all.ru/3.15/library/sys.html#sys.getfilesystemencoding) в остальных случаях.172173#### `tarfile.REGTYPE`174175#### `tarfile.AREGTYPE`176177Обычный файл [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).178179#### `tarfile.LNKTYPE`180181Ссылка (внутри tar-файла) [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).182183#### `tarfile.SYMTYPE`184185Символическая ссылка [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).186187#### `tarfile.CHRTYPE`188189Символьное устройство [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).190191#### `tarfile.BLKTYPE`192193Блочное устройство [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).194195#### `tarfile.DIRTYPE`196197Каталог [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).198199#### `tarfile.FIFOTYPE`200201FIFO-устройство [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).202203#### `tarfile.CONTTYPE`204205Непрерывный файл [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).206207#### `tarfile.GNUTYPE_LONGNAME`208209Длинное имя GNU tar [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).210211#### `tarfile.GNUTYPE_LONGLINK`212213Длинная ссылка GNU tar [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).214215#### `tarfile.GNUTYPE_SPARSE`216217Разрежённый файл GNU tar [`type`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.type).218219Каждая из следующих констант определяет формат tar-архива, который модуль `tarfile` может создавать. Подробнее см. раздел [Поддерживаемые форматы tar](https://python-all.ru/3.15/library/tarfile.html#tar-formats) для получения подробностей.220221#### `tarfile.USTAR_FORMAT`222223Формат POSIX.1-1988 (ustar).224225#### `tarfile.GNU_FORMAT`226227Формат GNU tar.228229#### `tarfile.PAX_FORMAT`230231Формат POSIX.1-2001 (pax).232233#### `tarfile.DEFAULT_FORMAT`234235Формат по умолчанию для создания архивов. В настоящее время это [`PAX_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.PAX_FORMAT).236237Изменено в версии 3.8: Формат по умолчанию для новых архивов был изменён на [`PAX_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.PAX_FORMAT) с [`GNU_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.GNU_FORMAT).238239> **См. также**240>241> **Модуль [`zipfile`](https://python-all.ru/3.15/library/zipfile.html#module-zipfile)**242>243> Документация стандартного модуля [`zipfile`](https://python-all.ru/3.15/library/zipfile.html#module-zipfile).244>245> **[Операции архивирования](https://python-all.ru/3.15/library/shutil.html#archiving-operations)**246>247> Документация средств архивирования высокого уровня, предоставляемых стандартным модулем [`shutil`](https://python-all.ru/3.15/library/shutil.html#module-shutil).248>249> **[Руководство GNU tar, базовый формат tar](https://python-all.ru/3.15/library/tarfile.html)**250>251> Документация для файлов архивов tar, включая расширения GNU tar.252253## Объекты TarFile254255Объект [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile) предоставляет интерфейс к архиву tar. Архив tar представляет собой последовательность блоков. Элемент архива (хранимый файл) состоит из заголовочного блока, за которым следуют блоки данных. Файл можно сохранить в архив tar несколько раз. Каждый элемент архива представляется объектом [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo), подробнее см. [Объекты TarInfo](https://python-all.ru/3.15/library/tarfile.html#tarinfo-objects).256257Объект [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile) можно использовать как контекстный менеджер в операторе [`with`](https://python-all.ru/3.15/reference/compound_stmts.html#with). Он будет автоматически закрыт по завершении блока. Обратите внимание: в случае исключения архив, открытый для записи, не будет финализирован; будет закрыт только внутренний файловый объект. Пример использования см. в разделе [Примеры](https://python-all.ru/3.15/library/tarfile.html#tar-examples).258259Добавлено в версии 3.2: Добавлена поддержка протокола контекстного менеджмента.260261#### `class tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=1, stream=False)`262263Все последующие аргументы необязательны и также могут быть доступны как атрибуты экземпляра.264265*name* – это путь к архиву. *name* может быть [объектом, подобным пути](https://python-all.ru/3.15/glossary.html#term-path-like-object). Его можно опустить, если указан *fileobj*. В этом случае используется атрибут файлового объекта `name`, если он существует.266267*mode* может быть `'r'` для чтения из существующего архива, `'a'` для добавления данных в существующий файл, `'w'` для создания нового файла с перезаписью существующего или `'x'` для создания нового файла только в том случае, если он ещё не существует.268269Если указан *fileobj*, он используется для чтения или записи данных. Если это можно определить, *mode* переопределяется режимом *fileobj*. *fileobj* будет использоваться с позиции 0.270271> **Примечание**272>273> *fileobj* не закрывается при закрытии `TarFile`.274275*format* управляет форматом архива для записи. Он должен быть одной из констант [`USTAR_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.USTAR_FORMAT), [`GNU_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.GNU_FORMAT) или [`PAX_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.PAX_FORMAT), определённых на уровне модуля. При чтении формат будет определён автоматически, даже если в одном архиве присутствуют разные форматы.276277Аргумент *tarinfo* можно использовать для замены класса по умолчанию [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) на другой.278279Если *dereference* равно [`False`](https://python-all.ru/3.15/library/constants.html#False), в архив добавляются символические и жёсткие ссылки. Если [`True`](https://python-all.ru/3.15/library/constants.html#True), в архив добавляется содержимое целевых файлов. Это не влияет на системы, не поддерживающие символические ссылки.280281Если *ignore\_zeros* равно [`False`](https://python-all.ru/3.15/library/constants.html#False), пустой блок считается концом архива. Если [`True`](https://python-all.ru/3.15/library/constants.html#True), пустые (и недействительные) блоки пропускаются, и предпринимается попытка получить как можно больше элементов. Это полезно только для чтения объединённых или повреждённых архивов.282283*debug* может быть установлен от `0` (нет отладочных сообщений) до `3` (все отладочные сообщения). Сообщения записываются в `sys.stderr`.284285*errorlevel* управляет обработкой ошибок извлечения, см. [`the corresponding attribute`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.errorlevel).286287Аргументы *encoding* и *errors* определяют кодировку символов, используемую для чтения или записи архива, и способ обработки ошибок преобразования. Настройки по умолчанию подходят для большинства пользователей. Подробную информацию см. в разделе [Проблемы Unicode](https://python-all.ru/3.15/library/tarfile.html#tar-unicode).288289Аргумент *pax\_headers* – необязательный словарь строк, который будет добавлен как глобальный заголовок pax, если *format* равно [`PAX_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.PAX_FORMAT).290291Если *поток данных* установлен в [`True`](https://python-all.ru/3.15/library/constants.html#True), то при чтении архива информация о файлах в архиве не кэшируется, экономя память.292293Изменено в версии 3.2: В качестве значения по умолчанию для аргумента *errors* используется `'surrogateescape'`.294295Изменено в версии 3.5: Добавлен режим `'x'` (эксклюзивное создание).296297Изменено в версии 3.6: Параметр *name* принимает [объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object).298299Изменено в версии 3.13: Добавлен параметр *поток данных*.300301#### `classmethod TarFile.open(...)`302303Альтернативный конструктор. Функция [`tarfile.open()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.open) на самом деле является сокращением для этого метода класса.304305#### `TarFile.getmember(name)`306307Возвращает объект [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) для элемента *name*. Если *name* не найден в архиве, возбуждается [`KeyError`](https://python-all.ru/3.15/library/exceptions.html#KeyError).308309> **Примечание**310>311> Если элемент встречается в архиве более одного раза, последнее его вхождение считается самой актуальной версией.312313#### `TarFile.getmembers()`314315Возвращает элементы архива в виде списка объектов [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo). Порядок списка соответствует порядку элементов в архиве.316317#### `TarFile.getnames()`318319Возвращает элементы в виде списка их имён. Порядок списка соответствует порядку списка, возвращаемого [`getmembers()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.getmembers).320321#### `TarFile.list(verbose=True, *, members=None)`322323Выводит оглавление в `sys.stdout`. Если *verbose* равно [`False`](https://python-all.ru/3.15/library/constants.html#False), печатаются только имена элементов. Если же [`True`](https://python-all.ru/3.15/library/constants.html#True), выводятся данные, аналогичные **ls -l**. Если задан необязательный параметр *members*, он должен быть подмножеством списка, возвращаемого [`getmembers()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.getmembers).324325Изменено в версии 3.5: Добавлен параметр *members*.326327#### `TarFile.next()`328329Возвращает следующий элемент архива в виде объекта [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo), когда [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile) открыт для чтения. Если больше нет элементов, возвращает [`None`](https://python-all.ru/3.15/library/constants.html#None).330331#### `TarFile.extractall(path='.', members=None, *, numeric_owner=False, filter=None)`332333Извлекает все элементы из архива в текущую рабочую директорию или в директорию *path*. Если задан необязательный параметр *members*, он должен быть подмножеством списка, возвращаемого [`getmembers()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.getmembers). Сведения о директории (владелец, время изменения, права доступа) устанавливаются после извлечения всех элементов. Это сделано для обхода двух проблем: время изменения директории сбрасывается при каждом создании в ней файла, и если права директории не разрешают запись, извлечение в неё файлов завершится ошибкой.334335Если *numeric\_owner* равно [`True`](https://python-all.ru/3.15/library/constants.html#True), для установки владельца и группы извлечённых файлов используются числовые uid и gid из tar-файла. В противном случае используются именованные значения из tar-файла.336337Аргумент *filter* определяет, как `members` изменяются или отклоняются перед извлечением. Подробнее см. в разделе [Фильтры извлечения](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-filter). Рекомендуется задавать его явно только в тех случаях, когда требуются специфические возможности *tar*, или в качестве `filter='data'` для поддержки версий Python с менее безопасным значением по умолчанию (3.13 и ниже).338339> **Предупреждение**340>341> Никогда не извлекайте архивы из ненадёжных источников без предварительной проверки.342>343> Начиная с Python 3.14, значение по умолчанию ([`data`](https://python-all.ru/3.15/library/tarfile.html#tarfile.data_filter)) предотвращает наиболее опасные проблемы безопасности. Однако оно не предотвращает *все* непреднамеренные или небезопасные действия. Подробнее читайте в разделе [Фильтры извлечения](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-filter).344345Изменено в версии 3.5: Добавлен параметр *numeric\_owner*.346347Изменено в версии 3.6: Параметр *path* теперь принимает [объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object).348349Изменено в версии 3.12: Добавлен параметр *filter*.350351Изменено в версии 3.14: Параметр *filter* теперь по умолчанию равен `'data'`.352353#### `TarFile.extract(member, path='', set_attrs=True, *, numeric_owner=False, filter=None)`354355Извлекает элемент из архива в текущую рабочую директорию, используя его полное имя. Информация о файле извлекается максимально точно. *member* может быть именем файла или объектом [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo). Можно указать другую директорию с помощью *path*. *path* может быть [объектом, подобным пути](https://python-all.ru/3.15/glossary.html#term-path-like-object). Атрибуты файла (владелец, mtime, права доступа) устанавливаются, если *set\_attrs* не равно false.356357Аргументы *numeric\_owner* и *filter* такие же, как для [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall).358359> **Примечание**360>361> Метод `extract()` не решает ряд проблем извлечения. В большинстве случаев стоит рассмотреть использование метода [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall).362363> **Предупреждение**364>365> Никогда не извлекайте архивы из ненадёжных источников без предварительной проверки. Подробнее см. предупреждение для [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall).366367Изменено в версии 3.2: Добавлен параметр *set\_attrs*.368369Изменено в версии 3.5: Добавлен параметр *numeric\_owner*.370371Изменено в версии 3.6: Параметр *path* теперь принимает [объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object).372373Изменено в версии 3.12: Добавлен параметр *filter*.374375#### `TarFile.extractfile(member)`376377Извлекает элемент из архива в виде файлового объекта. *member* может быть именем файла или объектом [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo). Если *member* – обычный файл или ссылка, возвращается объект [`io.BufferedReader`](https://python-all.ru/3.15/library/io.html#io.BufferedReader). Для всех остальных существующих элементов возвращается [`None`](https://python-all.ru/3.15/library/constants.html#None). Если *member* не найден в архиве, вызывается [`KeyError`](https://python-all.ru/3.15/library/exceptions.html#KeyError).378379Изменено в версии 3.3: Возвращается объект [`io.BufferedReader`](https://python-all.ru/3.15/library/io.html#io.BufferedReader).380381Изменено в версии 3.13: Возвращаемый объект [`io.BufferedReader`](https://python-all.ru/3.15/library/io.html#io.BufferedReader) имеет атрибут `mode` который всегда равен `'rb'`.382383#### `TarFile.errorlevel: int`384385Если *errorlevel* равен `0`, ошибки игнорируются при использовании [`TarFile.extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) и [`TarFile.extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall). Тем не менее, они отображаются как сообщения об ошибках в отладочном выводе, когда *debug* больше 0. Если `1` (по умолчанию), все *фатальные* ошибки вызываются как исключения [`OSError`](https://python-all.ru/3.15/library/exceptions.html#OSError) или [`FilterError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.FilterError). Если `2`, все *нефатальные* ошибки также вызываются как исключения [`TarError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarError).386387Некоторые исключения, например, вызванные неправильными типами аргументов или повреждением данных, всегда вызываются.388389Пользовательские [фильтры извлечения](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-filter) должны вызывать [`FilterError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.FilterError) для *фатальных* ошибок и [`ExtractError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.ExtractError) для *нефатальных*.390391Обратите внимание, что при возникновении исключения архив может быть извлечён частично. Ответственность за очистку лежит на пользователе.392393#### `TarFile.extraction_filter`394395Добавлено в версии 3.12.396397[Фильтр извлечения](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-filter), используемый по умолчанию для аргумента *filter* методов [`extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) и [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall).398399Атрибут может быть `None` или вызываемым объектом. Строковые имена для этого атрибута не допускаются, в отличие от аргумента *filter* для [`extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract).400401Если `extraction_filter` равен `None` (по умолчанию), методы извлечения будут по умолчанию использовать фильтр [`data`](https://python-all.ru/3.15/library/tarfile.html#tarfile.data_filter).402403Атрибут может быть установлен для экземпляров или переопределён в подклассах. Также возможно установить его для самого класса `TarFile`, чтобы задать глобальное значение по умолчанию; однако, поскольку это влияет на все случаи использования *tarfile*, лучшей практикой будет делать это только в приложениях верхнего уровня или [`site configuration`](https://python-all.ru/3.15/library/site.html#module-site). Чтобы задать глобальное значение по умолчанию таким образом, функцию фильтра необходимо обернуть в [`staticmethod()`](https://python-all.ru/3.15/library/functions.html#staticmethod), чтобы предотвратить внедрение аргумента `self`.404405Изменено в версии 3.14: Фильтр по умолчанию установлен на [`data`](https://python-all.ru/3.15/library/tarfile.html#tarfile.data_filter), что запрещает некоторые опасные возможности, такие как ссылки на абсолютные пути или пути за пределами целевого каталога. Ранее значение по умолчанию было эквивалентно [`fully_trusted`](https://python-all.ru/3.15/library/tarfile.html#tarfile.fully_trusted_filter).406407#### `TarFile.add(name, arcname=None, recursive=True, *, filter=None)`408409Добавляет файл *name* в архив. *name* может быть любым типом файла (каталог, FIFO, символическая ссылка и т.д.). Если задан, *arcname* указывает альтернативное имя файла в архиве. Каталоги добавляются рекурсивно по умолчанию. Этого можно избежать, установив *recursive* в [`False`](https://python-all.ru/3.15/library/constants.html#False). Рекурсия добавляет записи в отсортированном порядке. Если задан *filter*, он должен быть функцией, которая принимает аргумент объекта [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) и возвращает изменённый объект `TarInfo`. Если же она возвращает [`None`](https://python-all.ru/3.15/library/constants.html#None), объект `TarInfo` будет исключён из архива. Пример см. в [Примерах](https://python-all.ru/3.15/library/tarfile.html#tar-examples).410411Изменено в версии 3.2: Добавлен параметр *filter*.412413Изменено в версии 3.7: Рекурсия добавляет записи в отсортированном порядке.414415#### `TarFile.addfile(tarinfo, fileobj=None)`416417Добавляет объект [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) *tarinfo* в архив. Если *tarinfo* представляет обычный файл ненулевого размера, аргумент *fileobj* должен быть [двоичным файлом](https://python-all.ru/3.15/glossary.html#term-binary-file), и из него читается `tarinfo.size` байт, которые добавляются в архив. Можно создавать объекты `TarInfo` напрямую или с помощью [`gettarinfo()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.gettarinfo).418419Изменено в версии 3.13: *fileobj* должен быть указан для обычных файлов ненулевого размера.420421#### `TarFile.gettarinfo(name=None, arcname=None, fileobj=None)`422423Создаёт объект [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) из результата [`os.stat()`](https://python-all.ru/3.15/library/os.html#os.stat) или эквивалентного для существующего файла. Файл задаётся либо именем *name*, либо указывается как [файловый объект](https://python-all.ru/3.15/glossary.html#term-file-object) *fileobj* с файловым дескриптором. *name* может быть [объектом, подобным пути](https://python-all.ru/3.15/glossary.html#term-path-like-object). Если задан, *arcname* указывает альтернативное имя файла в архиве; в противном случае имя берётся из атрибута [`name`](https://python-all.ru/3.15/library/io.html#io.FileIO.name) объекта *fileobj* или из аргумента *name*. Имя должно быть текстовой строкой.424425Можно изменить некоторые атрибуты объекта [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) перед его добавлением с помощью [`addfile()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.addfile). Если файловый объект не является обычным файловым объектом, расположенным в начале файла, такие атрибуты, как [`size`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.size), могут потребовать изменения. Это относится к таким объектам, как [`GzipFile`](https://python-all.ru/3.15/library/gzip.html#gzip.GzipFile). Атрибут [`name`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.name) также может быть изменён, и в этом случае *arcname* может быть фиктивной строкой.426427Изменено в версии 3.6: Параметр *name* принимает [объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object).428429#### `TarFile.close()`430431Закрывает [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile). В режиме записи в архив добавляются два завершающих нулевых блока.432433#### `TarFile.pax_headers: dict`434435Словарь, содержащий пары ключ-значение глобальных заголовков pax.436437## Объекты TarInfo438439Объект [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) представляет один элемент в [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile). Помимо хранения всех необходимых атрибутов файла (таких как тип, размер, время, права доступа, владелец и т.д.), он предоставляет некоторые полезные методы для определения его типа. Он *не* содержит сами данные файла.440441Объекты [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) возвращаются методами [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile): [`getmember()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.getmember), [`getmembers()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.getmembers) и [`gettarinfo()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.gettarinfo).442443Изменение объектов, возвращённых методами [`getmember()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.getmember) или [`getmembers()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.getmembers), повлияет на все последующие операции с архивом. В случаях, когда это нежелательно, можно использовать [`copy.copy()`](https://python-all.ru/3.15/library/copy.html#module-copy) или вызвать метод [`replace()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.replace), чтобы создать изменённую копию за один шаг.444445Некоторые атрибуты могут быть установлены в `None`, чтобы указать, что часть метаданных не используется или неизвестна. Разные методы [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) обрабатывают `None` по-разному:446447- Методы [`extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) и [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall) будут игнорировать соответствующие метаданные, оставляя их установленными по умолчанию.448- [`addfile()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.addfile) завершится ошибкой.449- [`list()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.list) выведет строку-заполнитель.450451#### `class tarfile.TarInfo(name='')`452453Создаёт объект `TarInfo`.454455#### `classmethod TarInfo.frombuf(buf, encoding, errors)`456457Создаёт и возвращает объект [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) из строкового буфера *buf*.458459Вызывает [`HeaderError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.HeaderError), если буфер некорректен.460461#### `classmethod TarInfo.fromtarfile(tarfile)`462463Читает следующий элемент из объекта [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile) *tarfile* и возвращает его в виде объекта [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo).464465#### `TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')`466467Создаёт строковый буфер из объекта [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo). Подробнее об аргументах см. конструктор класса [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile).468469Изменено в версии 3.2: В качестве значения по умолчанию для аргумента *errors* используется `'surrogateescape'`.470471Объект `TarInfo` имеет следующие открытые атрибуты данных:472473#### `TarInfo.name: str`474475Имя элемента архива.476477#### `TarInfo.size: int`478479Размер в байтах.480481#### `TarInfo.mtime: int | float`482483Время последнего изменения в секундах с [начала эпохи](https://python-all.ru/3.15/library/time.html#epoch), как в [`os.stat_result.st_mtime`](https://python-all.ru/3.15/library/os.html#os.stat_result.st_mtime).484485Изменено в версии 3.12: Можно установить в `None` для [`extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) и [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall), что приведёт к пропуску применения этого атрибута при извлечении.486487#### `TarInfo.mode: int`488489Биты прав доступа, как для [`os.chmod()`](https://python-all.ru/3.15/library/os.html#os.chmod).490491Изменено в версии 3.12: Можно установить в `None` для [`extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) и [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall), что приведёт к пропуску применения этого атрибута при извлечении.492493#### `TarInfo.type`494495Тип файла. Обычно *type* – это одна из следующих констант: [`REGTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.REGTYPE), [`AREGTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.AREGTYPE), [`LNKTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.LNKTYPE), [`SYMTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.SYMTYPE), [`DIRTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.DIRTYPE), [`FIFOTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.FIFOTYPE), [`CONTTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.CONTTYPE), [`CHRTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.CHRTYPE), [`BLKTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.BLKTYPE), [`GNUTYPE_SPARSE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.GNUTYPE_SPARSE). Чтобы более удобно определить тип объекта [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo), используйте методы `is*()`, описанные ниже.496497#### `TarInfo.linkname: str`498499Имя целевого файла, которое присутствует только в объектах [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) типов [`LNKTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.LNKTYPE) и [`SYMTYPE`](https://python-all.ru/3.15/library/tarfile.html#tarfile.SYMTYPE).500501Для символических ссылок (`SYMTYPE`) значение *linkname* указывается относительно каталога, содержащего ссылку. Для жёстких ссылок (`LNKTYPE`) значение *linkname* указывается относительно корня архива.502503#### `TarInfo.uid: int`504505Идентификатор пользователя, который изначально сохранил этот элемент.506507Изменено в версии 3.12: Можно установить в `None` для [`extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) и [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall), что приведёт к пропуску применения этого атрибута при извлечении.508509#### `TarInfo.gid: int`510511Идентификатор группы пользователя, который изначально сохранил этот элемент.512513Изменено в версии 3.12: Можно установить в `None` для [`extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) и [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall), что приведёт к пропуску применения этого атрибута при извлечении.514515#### `TarInfo.uname: str`516517Имя пользователя.518519Изменено в версии 3.12: Можно установить в `None` для [`extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) и [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall), что приведёт к пропуску применения этого атрибута при извлечении.520521#### `TarInfo.gname: str`522523Имя группы.524525Изменено в версии 3.12: Можно установить в `None` для [`extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) и [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall), что приведёт к пропуску применения этого атрибута при извлечении.526527#### `TarInfo.chksum: int`528529Контрольная сумма заголовка.530531#### `TarInfo.devmajor: int`532533Старший номер устройства.534535#### `TarInfo.devminor: int`536537Младший номер устройства.538539#### `TarInfo.offset: int`540541Заголовок tar начинается здесь.542543#### `TarInfo.offset_data: int`544545Данные файла начинаются здесь.546547#### `TarInfo.sparse`548549Информация о разреженном элементе.550551#### `TarInfo.pax_headers: dict`552553Словарь, содержащий пары ключ-значение связанного расширенного заголовка pax.554555#### `TarInfo.replace(name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)`556557Добавлено в версии 3.12.558559Возвращает *новую* копию объекта `TarInfo` с указанными изменёнными атрибутами. Например, чтобы вернуть `TarInfo` с именем группы, установленным в `'staff'`, используйте:560561```python562new_tarinfo = old_tarinfo.replace(gname='staff')563```564565По умолчанию создаётся глубокая копия. Если *deep* равен false, копия поверхностная, то есть `pax_headers` и любые пользовательские атрибуты являются общими с исходным объектом `TarInfo`.566567Объект [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) также предоставляет несколько удобных запросных методов:568569#### `TarInfo.isfile()`570571Возвращает [`True`](https://python-all.ru/3.15/library/constants.html#True), если объект [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo) является обычным файлом.572573#### `TarInfo.isreg()`574575То же, что и [`isfile()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.isfile).576577#### `TarInfo.isdir()`578579Возвращает [`True`](https://python-all.ru/3.15/library/constants.html#True), если это каталог.580581#### `TarInfo.issym()`582583Возвращает [`True`](https://python-all.ru/3.15/library/constants.html#True), если это символическая ссылка.584585#### `TarInfo.islnk()`586587Возвращает [`True`](https://python-all.ru/3.15/library/constants.html#True), если это жёсткая ссылка.588589#### `TarInfo.ischr()`590591Возвращает [`True`](https://python-all.ru/3.15/library/constants.html#True), если это символьное устройство.592593#### `TarInfo.isblk()`594595Возвращает [`True`](https://python-all.ru/3.15/library/constants.html#True), если это блочное устройство.596597#### `TarInfo.isfifo()`598599Возвращает [`True`](https://python-all.ru/3.15/library/constants.html#True), если это FIFO.600601#### `TarInfo.isdev()`602603Возвращает [`True`](https://python-all.ru/3.15/library/constants.html#True), если это символьное устройство, блочное устройство или FIFO.604605## Фильтры извлечения606607Добавлено в версии 3.12.608609Формат *tar* предназначен для сохранения всех деталей файловых систем UNIX-подобных ОС, что делает его очень мощным. К сожалению, эти возможности позволяют легко создавать tar-файлы, которые при извлечении могут иметь непреднамеренные – а возможно и вредоносные – эффекты. Например, извлечение tar-файла может перезаписать произвольные файлы различными способами (например, с использованием абсолютных путей, компонентов пути `..` или символических ссылок, влияющих на последующие элементы).610611В большинстве случаев полная функциональность не требуется. Поэтому *tarfile* поддерживает фильтры извлечения: механизм ограничения функциональности, что позволяет смягчить некоторые проблемы безопасности.612613> **Предупреждение**614>615> Ни один из доступных фильтров не блокирует *все* опасные функции архивов. Никогда не извлекайте архивы из непроверенных источников без предварительной проверки. См. также [Подсказки для дальнейшей проверки](https://python-all.ru/3.15/library/tarfile.html#tarfile-further-verification).616617> **См. также**618>619> **[**PEP 706**](https://python-all.ru/3.15/library/tarfile.html)**620>621> Содержит дополнительную мотивацию и обоснование дизайна.622623Аргумент *filter* для [`TarFile.extract()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extract) или [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall) может быть:624625- строка `'fully_trusted'`: соблюдать все метаданные, указанные в архиве. Следует использовать, если пользователь полностью доверяет архиву или реализует собственную сложную проверку.626- строка `'tar'`: соблюдать большинство специфических для *tar* возможностей (т.е. возможностей файловых систем UNIX-подобных ОС), но блокировать те, которые могут быть неожиданными или вредоносными. Подробнее см. [`tar_filter()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.tar_filter).627- строка `'data'`: игнорировать или блокировать большинство специфических для UNIX-подобных файловых систем возможностей. Предназначен для извлечения кроссплатформенных архивов. Подробнее см. [`data_filter()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.data_filter).628- `None` (по умолчанию): использовать [`TarFile.extraction_filter`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extraction_filter).629630  Если он тоже `None` (по умолчанию), будет использован фильтр `'data'`.631632  > Изменено в версии 3.14: Фильтр по умолчанию установлен на [`data`](https://python-all.ru/3.15/library/tarfile.html#tarfile.data_filter). Ранее значение по умолчанию было эквивалентно [`fully_trusted`](https://python-all.ru/3.15/library/tarfile.html#tarfile.fully_trusted_filter).633- Вызываемый объект, который будет вызываться для каждого извлекаемого элемента с объектом [TarInfo](https://python-all.ru/3.15/library/tarfile.html#tarinfo-objects), описывающим элемент и путь назначения, куда извлекается архив (т.е. один и тот же путь используется для всех элементов):634635  ```python636  filter(member: TarInfo, path: str, /) -> TarInfo | None637  ```638639  Вызываемый объект вызывается непосредственно перед извлечением каждого элемента, поэтому он может учитывать текущее состояние диска. Он может:640641  - вернуть объект [`TarInfo`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo), который будет использоваться вместо метаданных в архиве, или642  - вернуть `None`, в этом случае элемент будет пропущен, или643  - вызвать исключение для прерывания операции или пропуска элемента, в зависимости от [`errorlevel`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.errorlevel). Обратите внимание, что при прерывании извлечения [`extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall) может оставить архив частично извлечённым. Он не пытается выполнить очистку.644645### Именованные фильтры по умолчанию646647Предопределённые именованные фильтры доступны как функции, поэтому их можно повторно использовать в пользовательских фильтрах:648649#### `tarfile.fully_trusted_filter(member, path)`650651Возвращает *элемент* без изменений.652653Это реализует фильтр `'fully_trusted'`.654655#### `tarfile.tar_filter(member, path)`656657Реализует фильтр `'tar'`.658659- Удаляет начальные слеши (`/` и [`os.sep`](https://python-all.ru/3.15/library/os.html#os.sep)) из имён файлов.660- [Отказывается](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-refuse) извлекать файлы с абсолютными путями (если имя является абсолютным даже после удаления слешей, например `C:/foo` в Windows). Это вызывает [`AbsolutePathError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.AbsolutePathError).661- [Отказывается](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-refuse) извлекать файлы, абсолютный путь которых (после разрешения симлинков) оказался бы за пределами целевой директории. Это вызывает [`OutsideDestinationError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.OutsideDestinationError).662- Сбрасывает биты высоких режимов (setuid, setgid, sticky) и биты записи для группы и остальных ([`S_IWGRP`](https://python-all.ru/3.15/library/stat.html#stat.S_IWGRP) | [`S_IWOTH`](https://python-all.ru/3.15/library/stat.html#stat.S_IWOTH)).663664Возвращает изменённый элемент `TarInfo`.665666#### `tarfile.data_filter(member, path)`667668Реализует фильтр `'data'`. В дополнение к тому, что делает `tar_filter`:669670- Нормализует цели ссылок ([`TarInfo.linkname`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarInfo.linkname)) с помощью [`os.path.normpath()`](https://python-all.ru/3.15/library/os.path.html#os.path.normpath). Обратите внимание, что это удаляет внутренние компоненты `..`, что может изменить смысл ссылки, если путь в `TarInfo.linkname` проходит через символические ссылки.671- [Отказывается](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-refuse) извлекать ссылки (жёсткие или символические), которые указывают на абсолютные пути или ведут за пределы целевой директории.672673  Это вызывает [`AbsoluteLinkError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.AbsoluteLinkError) или [`LinkOutsideDestinationError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.LinkOutsideDestinationError).674675  Обратите внимание, что такие файлы отклоняются даже на платформах, не поддерживающих символические ссылки.676- [Отказывается](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-refuse) извлекать файлы устройств (включая каналы). Это вызывает [`SpecialFileError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.SpecialFileError).677- Для обычных файлов, включая жёсткие ссылки:678679  - Устанавливает права на чтение и запись для владельца ([`S_IRUSR`](https://python-all.ru/3.15/library/stat.html#stat.S_IRUSR) | [`S_IWUSR`](https://python-all.ru/3.15/library/stat.html#stat.S_IWUSR)).680  - Удаляет права на выполнение для группы и остальных ([`S_IXGRP`](https://python-all.ru/3.15/library/stat.html#stat.S_IXGRP) | [`S_IXOTH`](https://python-all.ru/3.15/library/stat.html#stat.S_IXOTH)), если владелец ими не обладает ([`S_IXUSR`](https://python-all.ru/3.15/library/stat.html#stat.S_IXUSR)).681- Для остальных файлов (каталогов) устанавливает `mode` в `None`, чтобы методы извлечения пропускали применение битов разрешений.682- Устанавливает информацию о пользователе и группе (`uid`, `gid`, `uname`, `gname`) в `None`, чтобы методы извлечения пропускали её установку.683684Возвращает изменённый элемент `TarInfo`.685686Обратите внимание, что этот фильтр не блокирует *все* опасные возможности архива. Подробнее см. [Рекомендации по дополнительной проверке](https://python-all.ru/3.15/library/tarfile.html#tarfile-further-verification).687688Изменено в версии 3.15: Цели ссылок теперь нормализованы.689690### Ошибки фильтра691692Когда фильтр отказывается извлекать файл, он возбуждает соответствующее исключение, подкласс [`FilterError`](https://python-all.ru/3.15/library/tarfile.html#tarfile.FilterError). Это прервёт извлечение, если [`TarFile.errorlevel`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.errorlevel) равно 1 или больше. При `errorlevel=0` ошибка будет зарегистрирована, а элемент будет пропущен, но извлечение продолжится.693694### Рекомендации по дополнительной проверке695696Даже с `filter='data'`, *tarfile* не подходит для извлечения недоверенных файлов без предварительной проверки. Среди прочих проблем, предопределённые фильтры не предотвращают атаки типа «отказ в обслуживании». Пользователям следует проводить дополнительные проверки.697698Вот неполный список аспектов, которые стоит учесть:699700- Извлекайте в [`new temporary directory`](https://python-all.ru/3.15/library/tempfile.html#tempfile.mkdtemp), чтобы предотвратить, например, использование существующих ссылок, и упростить очистку после неудачного извлечения.701- Запретите символические ссылки, если эта функциональность не требуется.702- При работе с недоверенными данными используйте внешние (например, на уровне ОС) ограничения на использование диска, памяти и процессора.703- Проверяет имена файлов по разрешённому списку символов (для фильтрации управляющих символов, похожих символов, разделителей путей других ОС и т.д.).704- Проверяет, что имена файлов имеют ожидаемые расширения (чтобы исключить файлы, запускающиеся при двойном щелчке, или файлы без расширения, например специальные имена устройств Windows).705- Ограничивает количество извлечённых файлов, общий объём извлечённых данных, длину имён файлов (включая длину символических ссылок) и размер отдельных файлов.706- Проверяет наличие файлов, которые будут затенены на файловых системах без учёта регистра.707708Также обратите внимание:709710- Tar-файлы могут содержать несколько версий одного и того же файла. Ожидается, что более поздние версии перезапишут любые предыдущие. Эта возможность критически важна для обновления ленточных архивов, но может быть злонамеренно использована.711- *tarfile* не защищает от проблем с «активными» данными, например, когда злоумышленник манипулирует целевым (или исходным) каталогом во время извлечения (или архивирования).712713### Поддержка старых версий Python714715Фильтры извлечения были добавлены в Python 3.12, но могут быть перенесены на старые версии в качестве обновлений безопасности. Чтобы проверить, доступна ли эта возможность, используйте, например, `hasattr(tarfile, 'data_filter')`, а не проверку версии Python.716717Следующие примеры показывают, как поддерживать версии Python с этой возможностью и без неё. Обратите внимание, что установка `extraction_filter` повлияет на все последующие операции.718719- Полностью доверенный архив:720721  ```python722  my_tarfile.extraction_filter = (lambda member, path: member)723  my_tarfile.extractall()724  ```725- Используйте фильтр `'data'`, если он доступен, иначе вернитесь к поведению Python 3.11 (`'fully_trusted'`), если эта возможность недоступна:726727  ```python728  my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',729                                         (lambda member, path: member))730  my_tarfile.extractall()731  ```732- Используйте фильтр `'data'`; *завершить ошибкой*, если он недоступен:733734  ```python735  my_tarfile.extractall(filter=tarfile.data_filter)736  ```737738  или:739740  ```python741  my_tarfile.extraction_filter = tarfile.data_filter742  my_tarfile.extractall()743  ```744- Используйте фильтр `'data'`; *предупредить*, если он недоступен:745746  ```python747  if hasattr(tarfile, 'data_filter'):748      my_tarfile.extractall(filter='data')749  else:750      # удалить, когда больше не нужно751      warn_the_user('Extracting may be unsafe; consider updating Python')752      my_tarfile.extractall()753  ```754755### Пример фильтра извлечения с состоянием756757Хотя методы извлечения *tarfile* принимают простой вызываемый объект *filter*, пользовательские фильтры могут быть более сложными объектами с внутренним состоянием. Может быть полезно реализовать их в виде контекстных менеджеров, чтобы использовать следующим образом:758759```python760with StatefulFilter() as filter_func:761    tar.extractall(path, filter=filter_func)762```763764Такой фильтр можно написать, например, так:765766```python767class StatefulFilter:768    def __init__(self):769        self.file_count = 0770771    def __enter__(self):772        return self773774    def __call__(self, member, path):775        self.file_count += 1776        return member777778    def __exit__(self, *exc_info):779        print(f'{self.file_count} files extracted')780```781782## Интерфейс командной строки783784Добавлено в версии 3.4.785786Модуль `tarfile` предоставляет простой интерфейс командной строки для работы с tar-архивами.787788Если вы хотите создать новый tar-архив, укажите его имя после опции [`-c`](https://python-all.ru/3.15/library/tarfile.html#cmdoption-tarfile-c), а затем перечислите имена файлов, которые должны быть включены:789790```console791$ python -m tarfile -c monty.tar  spam.txt eggs.txt792```793794Можно также передать каталог:795796```console797$ python -m tarfile -c monty.tar life-of-brian_1979/798```799800Если вы хотите извлечь tar-архив в текущий каталог, используйте опцию [`-e`](https://python-all.ru/3.15/library/tarfile.html#cmdoption-tarfile-e):801802```console803$ python -m tarfile -e monty.tar804```805806Вы также можете извлечь tar-архив в другой каталог, передав его имя:807808```console809$ python -m tarfile -e monty.tar  other-dir/810```811812Чтобы получить список файлов в tar-архиве, используйте опцию [`-l`](https://python-all.ru/3.15/library/tarfile.html#cmdoption-tarfile-l):813814```console815$ python -m tarfile -l monty.tar816```817818### Параметры командной строки819820#### `-l <tarfile>`821822#### `--list <tarfile>`823824Выводит список файлов в tar-архиве.825826#### `-c <tarfile> <source1> ... <sourceN>`827828#### `--create <tarfile> <source1> ... <sourceN>`829830Создаёт tar-архив из исходных файлов.831832#### `-e <tarfile> [<output_dir>]`833834#### `--extract <tarfile> [<output_dir>]`835836Извлекает tar-архив в текущий каталог, если *output\_dir* не указан.837838#### `-t <tarfile>`839840#### `--test <tarfile>`841842Проверяет, является ли tar-файл допустимым.843844#### `-v, --verbose`845846Подробный вывод.847848#### `--filter <filtername>`849850Указывает *фильтр* для `--extract`. Подробнее см. [Фильтры извлечения](https://python-all.ru/3.15/library/tarfile.html#tarfile-extraction-filter). Принимаются только строковые имена (то есть `fully_trusted`, `tar`, и `data`).851852## Примеры853854### Примеры чтения855856Как извлечь полный tar-архив в текущий рабочий каталог:857858```python859import tarfile860tar = tarfile.open("sample.tar.gz")861tar.extractall(filter='data')862tar.close()863```864865Как извлечь подмножество tar-архива с помощью [`TarFile.extractall()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.extractall), используя функцию-генератор вместо списка:866867```python868import os869import tarfile870871def py_files(members):872    for tarinfo in members:873        if os.path.splitext(tarinfo.name)[1] == ".py":874            yield tarinfo875876tar = tarfile.open("sample.tar.gz")877tar.extractall(members=py_files(tar))878tar.close()879```880881Как прочитать tar-архив, сжатый gzip, и вывести информацию о некоторых элементах:882883```python884import tarfile885tar = tarfile.open("sample.tar.gz", "r:gz")886for tarinfo in tar:887    print(tarinfo.name, "is", tarinfo.size, "bytes in size and is ", end="")888    if tarinfo.isreg():889        print("a regular file.")890    elif tarinfo.isdir():891        print("a directory.")892    else:893        print("something else.")894tar.close()895```896897### Примеры записи898899Как создать несжатый tar-архив из списка имён файлов:900901```python902import tarfile903tar = tarfile.open("sample.tar", "w")904for name in ["foo", "bar", "quux"]:905    tar.add(name)906tar.close()907```908909Тот же пример с использованием оператора [`with`](https://python-all.ru/3.15/reference/compound_stmts.html#with):910911```python912import tarfile913with tarfile.open("sample.tar", "w") as tar:914    for name in ["foo", "bar", "quux"]:915        tar.add(name)916```917918Как создать архив и записать его в stdout, используя [`sys.stdout.buffer`](https://python-all.ru/3.15/library/sys.html#sys.stdout) в параметре *fileobj* в [`TarFile.add()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.add):919920```python921import sys922import tarfile923with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar:924    for name in ["foo", "bar", "quux"]:925        tar.add(name)926```927928Как создать архив и сбросить информацию о пользователе, используя параметр *фильтр* в [`TarFile.add()`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile.add):929930```python931import tarfile932def reset(tarinfo):933    tarinfo.uid = tarinfo.gid = 0934    tarinfo.uname = tarinfo.gname = "root"935    return tarinfo936tar = tarfile.open("sample.tar.gz", "w:gz")937tar.add("foo", filter=reset)938tar.close()939```940941## Поддерживаемые форматы tar942943Существует три формата tar, которые можно создать с помощью модуля `tarfile`:944945- Формат POSIX.1-1988 ustar ([`USTAR_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.USTAR_FORMAT)). Он поддерживает имена файлов длиной не более 256 символов и имена ссылок – до 100 символов. Максимальный размер файла – 8 ГиБ. Это старый и ограниченный, но широко поддерживаемый формат.946- Формат GNU tar ([`GNU_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.GNU_FORMAT)). Он поддерживает длинные имена файлов и ссылок, файлы размером более 8 ГиБ и разрежённые файлы. Это де-факто стандарт в системах GNU/Linux. `tarfile` полностью поддерживает расширения GNU tar для длинных имён; поддержка разрежённых файлов – только для чтения.947- Формат POSIX.1-2001 pax ([`PAX_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.PAX_FORMAT)). Это самый гибкий формат, практически без ограничений. Он поддерживает длинные имена файлов и ссылок, большие файлы и хранит пути переносимым способом. Современные реализации tar, включая GNU tar, bsdtar/libarchive и star, полностью поддерживают расширенные возможности *pax*; некоторые старые или неподдерживаемые библиотеки могут не поддерживать, но должны обрабатывать архивы *pax* так, как если бы они были в универсально поддерживаемом формате *ustar*. Это текущий формат по умолчанию для новых архивов.948949  Он расширяет существующий формат *ustar* дополнительными заголовками для информации, которую иначе нельзя сохранить. Существует две разновидности заголовков pax: расширенные заголовки влияют только на последующий заголовок файла, глобальные заголовки действительны для всего архива и влияют на все последующие файлы. Все данные в заголовке pax кодируются в *UTF-8* по соображениям переносимости.950951Существуют ещё некоторые варианты формата tar, которые можно читать, но не создавать:952953- Древний формат V7. Это первый формат tar из Unix Seventh Edition, хранящий только обычные файлы и каталоги. Имена не должны быть длиннее 100 символов, информация об имени пользователя/группы отсутствует. Некоторые архивы имеют неправильные контрольные суммы заголовков в случае полей с не-ASCII символами.954- Расширенный формат SunOS tar. Этот формат является вариантом формата POSIX.1-2001 pax, но несовместим с ним.955956## Проблемы Unicode957958Формат tar изначально был задуман для создания резервных копий на ленточных накопителях с основным упором на сохранение информации о файловой системе. Сегодня tar-архивы обычно используются для распространения файлов и обмена архивами по сетям. Одна проблема исходного формата (который является основой всех других форматов) заключается в том, что нет концепции поддержки разных кодировок символов. Например, обычный tar-архив, созданный в системе с *UTF-8*, не может быть корректно прочитан в системе с *Latin-1*, если он содержит символы, отличные от *ASCII*. Текстовые метаданные (например, имена файлов, имена ссылок, имена пользователей/групп) будут повреждены. К сожалению, нет способа автоматически определить кодировку архива. Формат pax был разработан для решения этой проблемы. Он хранит не-ASCII метаданные, используя универсальную кодировку символов *UTF-8*.959960Детали преобразования символов в `tarfile` управляются ключевыми аргументами *encoding* и *errors* класса [`TarFile`](https://python-all.ru/3.15/library/tarfile.html#tarfile.TarFile).961962*encoding* определяет кодировку символов, используемую для метаданных в архиве. Значение по умолчанию – [`sys.getfilesystemencoding()`](https://python-all.ru/3.15/library/sys.html#sys.getfilesystemencoding) или `'ascii'` в качестве запасного варианта. В зависимости от того, читается или записывается архив, метаданные должны быть либо декодированы, либо закодированы. Если *encoding* не установлена соответствующим образом, это преобразование может завершиться ошибкой.963964Аргумент *errors* определяет, как обрабатываются символы, которые невозможно преобразовать. Возможные значения перечислены в разделе [Обработчики ошибок](https://python-all.ru/3.15/library/codecs.html#error-handlers). Схема по умолчанию – `'surrogateescape'`, которую Python также использует для своих системных вызовов, см. [Имена файлов, аргументы командной строки и переменные окружения](https://python-all.ru/3.15/library/os.html#os-filenames).965966Для архивов [`PAX_FORMAT`](https://python-all.ru/3.15/library/tarfile.html#tarfile.PAX_FORMAT) (по умолчанию) *encoding* обычно не требуется, потому что все метаданные хранятся с использованием *UTF-8*. *encoding* используется только в редких случаях, когда декодируются бинарные заголовки pax или когда хранятся строки с суррогатными символами.967