`tarfile.md`

563 строк · 51.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.6/library/tarfile.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 13.6. [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile) – Чтение и запись tar-архивов89**Исходный код:** [Lib/tarfile.py](https://python-all.ru/src/3.6/Lib/tarfile.py)1011---1213Модуль [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile) позволяет читать и записывать tar-архивы, в том числе сжатые gzip, bz2 и lzma. Используйте модуль [`zipfile`](https://python-all.ru/3.6/library/zipfile.html#module-zipfile) для чтения и записи файлов `.zip` или функции более высокого уровня из [shutil](https://python-all.ru/3.6/library/shutil.html#archiving-operations).1415Некоторые факты и цифры:1617- читает и записывает сжатые архивы [`gzip`](https://python-all.ru/3.6/library/gzip.html#module-gzip), [`bz2`](https://python-all.ru/3.6/library/bz2.html#module-bz2) и [`lzma`](https://python-all.ru/3.6/library/lzma.html#module-lzma) если соответствующие модули доступны.18- поддержка чтения/записи формата POSIX.1-1988 (ustar).19- поддержка чтения/записи формата GNU tar, включая расширения *longname* и *longlink*, поддержка только чтения всех вариантов расширения *sparse*, включая восстановление разрежённых файлов.20- поддержка чтения/записи формата POSIX.1-2001 (pax).21- работает с директориями, обычными файлами, жёсткими ссылками, символическими ссылками, каналами FIFO, символьными и блочными устройствами, а также может получать и восстанавливать информацию о файлах, такую как временная метка, права доступа и владелец.2223Изменено в версии 3.3: Добавлена поддержка сжатия [`lzma`](https://python-all.ru/3.6/library/lzma.html#module-lzma).2425#### `tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)`2627Возвращает объект [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile) для имени пути *name*. Подробную информацию об объектах [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile) и допустимых именованных аргументах см. в разделе [Объекты TarFile](https://python-all.ru/3.6/library/tarfile.html#tarfile-objects).2829*mode* должен быть строкой вида `'filemode[:compression]'`, по умолчанию равен `'r'`. Вот полный список комбинаций режимов:3031| Режим | Действие |32| --- | --- |33| `'r' or 'r:*'` | Открыть для чтения с прозрачным сжатием (рекомендуется). |34| `'r:'` | Открыть для чтения исключительно без сжатия. |35| `'r:gz'` | Открыть для чтения со сжатием gzip. |36| `'r:bz2'` | Открыть для чтения со сжатием bzip2. |37| `'r:xz'` | Открыть для чтения со сжатием lzma. |38| `'x'` или `'x:'` | Создаёт tar-файл без сжатия. Вызывает исключение [`FileExistsError`](https://python-all.ru/3.6/library/exceptions.html#FileExistsError), если файл уже существует. |39| `'x:gz'` | Создаёт tar-файл со сжатием gzip. Вызывает исключение [`FileExistsError`](https://python-all.ru/3.6/library/exceptions.html#FileExistsError), если файл уже существует. |40| `'x:bz2'` | Создаёт tar-файл со сжатием bzip2. Вызывает исключение [`FileExistsError`](https://python-all.ru/3.6/library/exceptions.html#FileExistsError), если файл уже существует. |41| `'x:xz'` | Создаёт tar-файл со сжатием lzma. Вызывает исключение [`FileExistsError`](https://python-all.ru/3.6/library/exceptions.html#FileExistsError), если файл уже существует. |42| `'a' or 'a:'` | Открыть для добавления без сжатия. Файл создаётся, если он не существует. |43| `'w' or 'w:'` | Открывается для записи без сжатия. |44| `'w:gz'` | Открывается для записи со сжатием gzip. |45| `'w:bz2'` | Открывается для записи со сжатием bzip2. |46| `'w:xz'` | Открывается для записи со сжатием lzma. |4748Обратите внимание, что `'a:gz'`, `'a:bz2'` или `'a:xz'` невозможны. Если *режим* не подходит для открытия определённого (сжатого) файла для чтения, возбуждается [`ReadError`](https://python-all.ru/3.6/library/tarfile.html#tarfile.ReadError). Используйте *режим* `'r'`, чтобы избежать этого. Если метод сжатия не поддерживается, возбуждается [`CompressionError`](https://python-all.ru/3.6/library/tarfile.html#tarfile.CompressionError).4950Если указан *fileobj*, он используется вместо [файлового объекта](https://python-all.ru/3.6/glossary.html#term-file-object), открытого в бинарном режиме для *имени*. Предполагается, что он находится на позиции 0.5152Для режимов `'w:gz'`, `'r:gz'`, `'w:bz2'`, `'r:bz2'`, `'x:gz'`, `'x:bz2'`, [`tarfile.open()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.open) принимает именованный аргумент *compresslevel* (по умолчанию `9`) для указания уровня сжатия файла.5354Для специальных целей существует второй формат для *mode*: `'filemode|[compression]'`. [`tarfile.open()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.open) вернёт объект [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile), который обрабатывает данные как поток блоков. Поиск по файлу с произвольным доступом не выполняется. Если задан *fileobj*, это может быть любой объект с методами `read()` или `write()` (в зависимости от *mode*). *bufsize* задаёт размер блока; по умолчанию `20 * 512` байт. Используйте этот вариант в сочетании, например, с `sys.stdin`, сокетным [файловым объектом](https://python-all.ru/3.6/glossary.html#term-file-object) или ленточным устройством. Однако такой объект [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile) ограничен тем, что не допускает произвольный доступ – см. [Примеры](https://python-all.ru/3.6/library/tarfile.html#tar-examples). Возможные режимы на текущий момент:5556| Режим | Действие |57| --- | --- |58| `'r\|*'` | Открывает *поток данных* tar-блоков для чтения с прозрачным сжатием. |59| `'r\|'` | Открывает *поток данных* несжатых tar-блоков для чтения. |60| `'r\|gz'` | Открывает сжатый gzip *поток данных* для чтения. |61| `'r\|bz2'` | Открывает сжатый bzip2 *поток данных* для чтения. |62| `'r\|xz'` | Открывает сжатый lzma *поток данных* для чтения. |63| `'w\|'` | Открывает несжатый *поток данных* для записи. |64| `'w\|gz'` | Открывает сжатый gzip *поток данных* для записи. |65| `'w\|bz2'` | Открывает сжатый bzip2 *поток данных* для записи. |66| `'w\|xz'` | Открывает сжатый lzma *поток данных* для записи. |6768Изменено в версии 3.5: Добавлен режим `'x'` (эксклюзивное создание).6970Изменено в версии 3.6: Параметр *name* принимает [объект, подобный пути](https://python-all.ru/3.6/glossary.html#term-path-like-object).7172#### `class tarfile.TarFile`7374Класс для чтения и записи tar-архивов. Не используйте этот класс напрямую: вместо него используйте [`tarfile.open()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.open). См. [Объекты TarFile](https://python-all.ru/3.6/library/tarfile.html#tarfile-objects).7576#### `tarfile.is_tarfile(name)`7778Возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если *name* является tar-архивом, который может прочитать модуль [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile).7980Модуль [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile) определяет следующие исключения:8182#### `exception tarfile.TarError`8384Базовый класс для всех исключений [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile).8586#### `exception tarfile.ReadError`8788Возникает при открытии tar-архива, который не может быть обработан модулем [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile) или является некорректным.8990#### `exception tarfile.CompressionError`9192Возникает, когда метод сжатия не поддерживается или данные не удаётся корректно декодировать.9394#### `exception tarfile.StreamError`9596Возникает при ограничениях, типичных для объектов, работающих в режиме потока [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile).9798#### `exception tarfile.ExtractError`99100Возникает при *нефатальных* ошибках при использовании [`TarFile.extract()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.extract), но только если `TarFile.errorlevel``== 2`.101102#### `exception tarfile.HeaderError`103104Возникает при вызове [`TarInfo.frombuf()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo.frombuf), если полученный буфер некорректен.105106На уровне модуля доступны следующие константы:107108#### `tarfile.ENCODING`109110Кодировка символов по умолчанию: `'utf-8'` в Windows, значение, возвращаемое [`sys.getfilesystemencoding()`](https://python-all.ru/3.6/library/sys.html#sys.getfilesystemencoding) в остальных случаях.111112Каждая из следующих констант определяет формат tar-архива, который модуль [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile) может создавать. Подробнее см. раздел [Поддерживаемые форматы tar](https://python-all.ru/3.6/library/tarfile.html#tar-formats) для получения подробностей.113114#### `tarfile.USTAR_FORMAT`115116Формат POSIX.1-1988 (ustar).117118#### `tarfile.GNU_FORMAT`119120Формат GNU tar.121122#### `tarfile.PAX_FORMAT`123124Формат POSIX.1-2001 (pax).125126#### `tarfile.DEFAULT_FORMAT`127128Формат по умолчанию для создания архивов. В настоящее время это [`GNU_FORMAT`](https://python-all.ru/3.6/library/tarfile.html#tarfile.GNU_FORMAT).129130> **См. также**131>132> **Модуль [`zipfile`](https://python-all.ru/3.6/library/zipfile.html#module-zipfile)**133>134> Документация стандартного модуля [`zipfile`](https://python-all.ru/3.6/library/zipfile.html#module-zipfile).135>136> **[Операции архивирования](https://python-all.ru/3.6/library/shutil.html#archiving-operations)**137>138> Документация средств архивирования высокого уровня, предоставляемых стандартным модулем [`shutil`](https://python-all.ru/3.6/library/shutil.html#module-shutil).139>140> **[Руководство GNU tar, базовый формат tar](https://python-all.ru/3.6/library/tarfile.html)**141>142> Документация для файлов архивов tar, включая расширения GNU tar.143144## 13.6.1. Объекты TarFile145146Объект [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile) предоставляет интерфейс к архиву tar. Архив tar представляет собой последовательность блоков. Элемент архива (хранимый файл) состоит из заголовочного блока, за которым следуют блоки данных. Файл можно сохранить в архив tar несколько раз. Каждый элемент архива представляется объектом [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo), подробнее см. [Объекты TarInfo](https://python-all.ru/3.6/library/tarfile.html#tarinfo-objects).147148Объект [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile) можно использовать как контекстный менеджер в операторе [`with`](https://python-all.ru/3.6/reference/compound_stmts.html#with). Он будет автоматически закрыт по завершении блока. Обратите внимание: в случае исключения архив, открытый для записи, не будет финализирован; будет закрыт только внутренний файловый объект. Пример использования см. в разделе [Примеры](https://python-all.ru/3.6/library/tarfile.html#tar-examples).149150Новое в версии 3.2: Добавлена поддержка протокола менеджера контекста.151152#### `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=0)`153154Все последующие аргументы необязательны и также могут быть доступны как атрибуты экземпляра.155156*name* – это путь к архиву. *name* может быть [объектом, подобным пути](https://python-all.ru/3.6/glossary.html#term-path-like-object). Его можно опустить, если указан *fileobj*. В этом случае используется атрибут файлового объекта `name`, если он существует.157158*mode* может быть `'r'` для чтения из существующего архива, `'a'` для добавления данных в существующий файл, `'w'` для создания нового файла с перезаписью существующего или `'x'` для создания нового файла только в том случае, если он ещё не существует.159160Если указан *fileobj*, он используется для чтения или записи данных. Если это можно определить, *mode* переопределяется режимом *fileobj*. *fileobj* будет использоваться с позиции 0.161162> **Примечание**163>164> *fileobj* не закрывается при закрытии [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile).165166*format* управляет форматом архива. Значением должна быть одна из констант [`USTAR_FORMAT`](https://python-all.ru/3.6/library/tarfile.html#tarfile.USTAR_FORMAT), [`GNU_FORMAT`](https://python-all.ru/3.6/library/tarfile.html#tarfile.GNU_FORMAT) или [`PAX_FORMAT`](https://python-all.ru/3.6/library/tarfile.html#tarfile.PAX_FORMAT), определённых на уровне модуля.167168Аргумент *tarinfo* можно использовать для замены класса по умолчанию [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) на другой.169170Если *dereference* равно [`False`](https://python-all.ru/3.6/library/constants.html#False), в архив добавляются символические и жёсткие ссылки. Если [`True`](https://python-all.ru/3.6/library/constants.html#True), в архив добавляется содержимое целевых файлов. Это не влияет на системы, не поддерживающие символические ссылки.171172Если *ignore\_zeros* равно [`False`](https://python-all.ru/3.6/library/constants.html#False), пустой блок считается концом архива. Если [`True`](https://python-all.ru/3.6/library/constants.html#True), пустые (и недействительные) блоки пропускаются, и предпринимается попытка получить как можно больше элементов. Это полезно только для чтения объединённых или повреждённых архивов.173174*debug* может быть установлен от `0` (нет отладочных сообщений) до `3` (все отладочные сообщения). Сообщения записываются в `sys.stderr`.175176Если *errorlevel* равен `0`, при использовании [`TarFile.extract()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.extract) все ошибки игнорируются. Тем не менее, если отладка включена, они отображаются как сообщения об ошибках в отладочном выводе. Если `1`, все *фатальные* ошибки вызывают исключения [`OSError`](https://python-all.ru/3.6/library/exceptions.html#OSError). Если `2`, все *нефатальные* ошибки также вызывают исключения [`TarError`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarError).177178Аргументы *encoding* и *errors* определяют кодировку символов, используемую для чтения или записи архива, и способ обработки ошибок преобразования. Настройки по умолчанию подходят для большинства пользователей. Подробную информацию см. в разделе [Проблемы Unicode](https://python-all.ru/3.6/library/tarfile.html#tar-unicode).179180Аргумент *pax\_headers* – необязательный словарь строк, который будет добавлен как глобальный заголовок pax, если *format* равно [`PAX_FORMAT`](https://python-all.ru/3.6/library/tarfile.html#tarfile.PAX_FORMAT).181182Изменено в версии 3.2: В качестве значения по умолчанию для аргумента *errors* используется `'surrogateescape'`.183184Изменено в версии 3.5: Добавлен режим `'x'` (эксклюзивное создание).185186Изменено в версии 3.6: Параметр *name* принимает [объект, подобный пути](https://python-all.ru/3.6/glossary.html#term-path-like-object).187188#### `classmethod TarFile.open(...)`189190Альтернативный конструктор. Функция [`tarfile.open()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.open) на самом деле является сокращением для этого метода класса.191192#### `TarFile.getmember(name)`193194Возвращает объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) для элемента *name*. Если *name* не найден в архиве, возбуждается [`KeyError`](https://python-all.ru/3.6/library/exceptions.html#KeyError).195196> **Примечание**197>198> Если элемент встречается в архиве более одного раза, последнее его вхождение считается самой актуальной версией.199200#### `TarFile.getmembers()`201202Возвращает элементы архива в виде списка объектов [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo). Порядок списка соответствует порядку элементов в архиве.203204#### `TarFile.getnames()`205206Возвращает элементы в виде списка их имён. Порядок списка соответствует порядку списка, возвращаемого [`getmembers()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.getmembers).207208#### `TarFile.list(verbose=True, *, members=None)`209210Выводит оглавление в `sys.stdout`. Если *verbose* равно [`False`](https://python-all.ru/3.6/library/constants.html#False), печатаются только имена элементов. Если же [`True`](https://python-all.ru/3.6/library/constants.html#True), выводятся данные, аналогичные **ls -l**. Если задан необязательный параметр *members*, он должен быть подмножеством списка, возвращаемого [`getmembers()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.getmembers).211212Изменено в версии 3.5: Добавлен параметр *members*.213214#### `TarFile.next()`215216Возвращает следующий элемент архива в виде объекта [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo), когда [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile) открыт для чтения. Если больше нет элементов, возвращает [`None`](https://python-all.ru/3.6/library/constants.html#None).217218#### `TarFile.extractall(path=".", members=None, *, numeric_owner=False)`219220Извлекает все элементы из архива в текущую рабочую директорию или в директорию *path*. Если задан необязательный параметр *members*, он должен быть подмножеством списка, возвращаемого [`getmembers()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.getmembers). Сведения о директории (владелец, время изменения, права доступа) устанавливаются после извлечения всех элементов. Это сделано для обхода двух проблем: время изменения директории сбрасывается при каждом создании в ней файла, и если права директории не разрешают запись, извлечение в неё файлов завершится ошибкой.221222Если *numeric\_owner* равно [`True`](https://python-all.ru/3.6/library/constants.html#True), для установки владельца и группы извлечённых файлов используются числовые uid и gid из tar-файла. В противном случае используются именованные значения из tar-файла.223224> **Предупреждение**225>226> Никогда не извлекайте архивы из ненадёжных источников без предварительной проверки. Возможно создание файлов за пределами *path*, например, элементов с абсолютными именами, начинающимися с `"/"`, или с именами, содержащими две точки `".."`.227228Изменено в версии 3.5: Добавлен параметр *numeric\_owner*.229230Изменено в версии 3.6: Параметр *path* теперь принимает [объект, подобный пути](https://python-all.ru/3.6/glossary.html#term-path-like-object).231232#### `TarFile.extract(member, path="", set_attrs=True, *, numeric_owner=False)`233234Извлекает элемент из архива в текущую рабочую директорию, используя его полное имя. Информация о файле извлекается максимально точно. *member* может быть именем файла или объектом [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo). Можно указать другую директорию с помощью *path*. *path* может быть [объектом, подобным пути](https://python-all.ru/3.6/glossary.html#term-path-like-object). Атрибуты файла (владелец, mtime, права доступа) устанавливаются, если *set\_attrs* не равно false.235236Если *numeric\_owner* равно [`True`](https://python-all.ru/3.6/library/constants.html#True), для установки владельца и группы извлечённых файлов используются числовые uid и gid из tar-файла. В противном случае используются именованные значения из tar-файла.237238> **Примечание**239>240> Метод [`extract()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.extract) не решает ряд проблем извлечения. В большинстве случаев стоит рассмотреть использование метода [`extractall()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.extractall).241242> **Предупреждение**243>244> См. предупреждение для [`extractall()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.extractall).245246Изменено в версии 3.2: Добавлен параметр *set\_attrs*.247248Изменено в версии 3.5: Добавлен параметр *numeric\_owner*.249250Изменено в версии 3.6: Параметр *path* теперь принимает [объект, подобный пути](https://python-all.ru/3.6/glossary.html#term-path-like-object).251252#### `TarFile.extractfile(member)`253254Извлекает элемент архива в виде файлового объекта. *member* может быть именем файла или объектом [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo). Если *member* является обычным файлом или ссылкой, возвращается объект [`io.BufferedReader`](https://python-all.ru/3.6/library/io.html#io.BufferedReader). В противном случае возвращается [`None`](https://python-all.ru/3.6/library/constants.html#None).255256Изменено в версии 3.3: Возвращается объект [`io.BufferedReader`](https://python-all.ru/3.6/library/io.html#io.BufferedReader).257258#### `TarFile.add(name, arcname=None, recursive=True, exclude=None, *, filter=None)`259260Добавляет файл *name* в архив. *name* может быть файлом любого типа (каталогом, FIFO, символической ссылкой и т.д.). Если указан, *arcname* задаёт альтернативное имя файла в архиве. Каталоги добавляются рекурсивно по умолчанию. Этого можно избежать, установив *recursive* в [`False`](https://python-all.ru/3.6/library/constants.html#False). Если задан *exclude*, это должна быть функция, принимающая один аргумент – имя файла – и возвращающая логическое значение. В зависимости от этого значения соответствующий файл либо исключается ([`True`](https://python-all.ru/3.6/library/constants.html#True)), либо добавляется ([`False`](https://python-all.ru/3.6/library/constants.html#False)). Если указан *filter*, это должен быть именованный аргумент. Это должна быть функция, принимающая объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) и возвращающая изменённый объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo). Если вместо этого она возвращает [`None`](https://python-all.ru/3.6/library/constants.html#None), объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) будет исключён из архива. Пример см. в [Примерах](https://python-all.ru/3.6/library/tarfile.html#tar-examples).261262Изменено в версии 3.2: Добавлен параметр *filter*.263264Устарело с версии 3.2: Параметр *exclude* устарел; используйте вместо него параметр *filter* вместо него.265266#### `TarFile.addfile(tarinfo, fileobj=None)`267268Добавляет объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) *tarinfo* в архив. Если указан *fileobj*, он должен быть [двоичным файлом](https://python-all.ru/3.6/glossary.html#term-binary-file), из которого читаются `tarinfo.size` байтов и добавляются в архив. Можно создавать объекты [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) напрямую или с помощью [`gettarinfo()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.gettarinfo).269270#### `TarFile.gettarinfo(name=None, arcname=None, fileobj=None)`271272Создаёт объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) из результата [`os.stat()`](https://python-all.ru/3.6/library/os.html#os.stat) или эквивалентного для существующего файла. Файл задаётся либо именем *name*, либо указывается как [файловый объект](https://python-all.ru/3.6/glossary.html#term-file-object) *fileobj* с файловым дескриптором. *name* может быть [объектом, подобным пути](https://python-all.ru/3.6/glossary.html#term-path-like-object). Если задан, *arcname* указывает альтернативное имя файла в архиве; в противном случае имя берётся из атрибута [`name`](https://python-all.ru/3.6/library/io.html#io.FileIO.name) объекта *fileobj* или из аргумента *name*. Имя должно быть текстовой строкой.273274Можно изменить некоторые атрибуты объекта [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) перед его добавлением с помощью [`addfile()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.addfile). Если файловый объект не является обычным файловым объектом, расположенным в начале файла, такие атрибуты, как [`size`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo.size), могут потребовать изменения. Это относится к таким объектам, как [`GzipFile`](https://python-all.ru/3.6/library/gzip.html#gzip.GzipFile). Атрибут [`name`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo.name) также может быть изменён, и в этом случае *arcname* может быть фиктивной строкой.275276Изменено в версии 3.6: Параметр *name* принимает [объект, подобный пути](https://python-all.ru/3.6/glossary.html#term-path-like-object).277278#### `TarFile.close()`279280Закрывает [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile). В режиме записи в архив добавляются два завершающих нулевых блока.281282#### `TarFile.pax_headers`283284Словарь, содержащий пары ключ-значение глобальных заголовков pax.285286## 13.6.2. Объекты TarInfo287288Объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) представляет один элемент в [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile). Помимо хранения всех необходимых атрибутов файла (таких как тип, размер, время, права доступа, владелец и т.д.), он предоставляет некоторые полезные методы для определения его типа. Он *не* содержит сами данные файла.289290[`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) возвращаются методами [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile): `getmember()`, `getmembers()` и `gettarinfo()`.291292#### `class tarfile.TarInfo(name="")`293294Создаёт объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo).295296#### `classmethod TarInfo.frombuf(buf, encoding, errors)`297298Создаёт и возвращает объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) из строкового буфера *buf*.299300Вызывает [`HeaderError`](https://python-all.ru/3.6/library/tarfile.html#tarfile.HeaderError), если буфер некорректен.301302#### `classmethod TarInfo.fromtarfile(tarfile)`303304Читает следующий элемент из объекта [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile) *tarfile* и возвращает его в виде объекта [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo).305306#### `TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')`307308Создаёт строковый буфер из объекта [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo). Подробнее об аргументах см. конструктор класса [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile).309310Изменено в версии 3.2: В качестве значения по умолчанию для аргумента *errors* используется `'surrogateescape'`.311312Объект `TarInfo` имеет следующие открытые атрибуты данных:313314#### `TarInfo.name`315316Имя элемента архива.317318#### `TarInfo.size`319320Размер в байтах.321322#### `TarInfo.mtime`323324Время последнего изменения.325326#### `TarInfo.mode`327328Биты разрешений.329330#### `TarInfo.type`331332Тип файла. Обычно *type* – это одна из следующих констант: `REGTYPE`, `AREGTYPE`, `LNKTYPE`, `SYMTYPE`, `DIRTYPE`, `FIFOTYPE`, `CONTTYPE`, `CHRTYPE`, `BLKTYPE`, `GNUTYPE_SPARSE`. Чтобы более удобно определить тип объекта [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo), используйте методы `is*()`, описанные ниже.333334#### `TarInfo.linkname`335336Имя целевого файла, которое присутствует только в объектах [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) типов `LNKTYPE` и `SYMTYPE`.337338#### `TarInfo.uid`339340Идентификатор пользователя, который изначально сохранил этот элемент.341342#### `TarInfo.gid`343344Идентификатор группы пользователя, который изначально сохранил этот элемент.345346#### `TarInfo.uname`347348Имя пользователя.349350#### `TarInfo.gname`351352Имя группы.353354#### `TarInfo.pax_headers`355356Словарь, содержащий пары ключ-значение связанного расширенного заголовка pax.357358Объект [`TarInfo`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo) также предоставляет несколько удобных запросных методов:359360#### `TarInfo.isfile()`361362Возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если объект `Tarinfo` является обычным файлом.363364#### `TarInfo.isreg()`365366То же, что и [`isfile()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarInfo.isfile).367368#### `TarInfo.isdir()`369370Возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если это каталог.371372#### `TarInfo.issym()`373374Возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если это символическая ссылка.375376#### `TarInfo.islnk()`377378Возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если это жёсткая ссылка.379380#### `TarInfo.ischr()`381382Возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если это символьное устройство.383384#### `TarInfo.isblk()`385386Возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если это блочное устройство.387388#### `TarInfo.isfifo()`389390Возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если это FIFO.391392#### `TarInfo.isdev()`393394Возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если это символьное устройство, блочное устройство или FIFO.395396## 13.6.3. Интерфейс командной строки397398Новое в версии 3.4.399400Модуль [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile) предоставляет простой интерфейс командной строки для работы с tar-архивами.401402Если вы хотите создать новый tar-архив, укажите его имя после опции [`-c`](https://python-all.ru/3.6/library/tarfile.html#cmdoption-tarfile-c), а затем перечислите имена файлов, которые должны быть включены:403404```console405$ python -m tarfile -c monty.tar  spam.txt eggs.txt406```407408Можно также передать каталог:409410```console411$ python -m tarfile -c monty.tar life-of-brian_1979/412```413414Если вы хотите извлечь tar-архив в текущий каталог, используйте опцию [`-e`](https://python-all.ru/3.6/library/tarfile.html#cmdoption-tarfile-e):415416```console417$ python -m tarfile -e monty.tar418```419420Вы также можете извлечь tar-архив в другой каталог, передав его имя:421422```console423$ python -m tarfile -e monty.tar  other-dir/424```425426Чтобы получить список файлов в tar-архиве, используйте опцию [`-l`](https://python-all.ru/3.6/library/tarfile.html#cmdoption-tarfile-l):427428```console429$ python -m tarfile -l monty.tar430```431432### 13.6.3.1. Параметры командной строки433434#### `-l <tarfile>`435436#### `--list <tarfile>`437438Выводит список файлов в tar-архиве.439440#### `-c <tarfile> <source1> ... <sourceN>`441442#### `--create <tarfile> <source1> ... <sourceN>`443444Создаёт tar-архив из исходных файлов.445446#### `-e <tarfile> [<output_dir>]`447448#### `--extract <tarfile> [<output_dir>]`449450Извлекает tar-архив в текущий каталог, если *output\_dir* не указан.451452#### `-t <tarfile>`453454#### `--test <tarfile>`455456Проверяет, является ли tar-файл допустимым.457458#### `-v, --verbose`459460Подробный вывод.461462## 13.6.4. Примеры463464Как извлечь полный tar-архив в текущий рабочий каталог:465466```python467import tarfile468tar = tarfile.open("sample.tar.gz")469tar.extractall()470tar.close()471```472473Как извлечь подмножество tar-архива с помощью [`TarFile.extractall()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.extractall), используя функцию-генератор вместо списка:474475```python476import os477import tarfile478479def py_files(members):480    for tarinfo in members:481        if os.path.splitext(tarinfo.name)[1] == ".py":482            yield tarinfo483484tar = tarfile.open("sample.tar.gz")485tar.extractall(members=py_files(tar))486tar.close()487```488489Как создать несжатый tar-архив из списка имён файлов:490491```python492import tarfile493tar = tarfile.open("sample.tar", "w")494for name in ["foo", "bar", "quux"]:495    tar.add(name)496tar.close()497```498499Тот же пример с использованием оператора [`with`](https://python-all.ru/3.6/reference/compound_stmts.html#with):500501```python502import tarfile503with tarfile.open("sample.tar", "w") as tar:504    for name in ["foo", "bar", "quux"]:505        tar.add(name)506```507508Как прочитать tar-архив, сжатый gzip, и вывести информацию о некоторых элементах:509510```python511import tarfile512tar = tarfile.open("sample.tar.gz", "r:gz")513for tarinfo in tar:514    print(tarinfo.name, "is", tarinfo.size, "bytes in size and is", end="")515    if tarinfo.isreg():516        print("a regular file.")517    elif tarinfo.isdir():518        print("a directory.")519    else:520        print("something else.")521tar.close()522```523524Как создать архив и сбросить информацию о пользователе, используя параметр *фильтр* в [`TarFile.add()`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile.add):525526```python527import tarfile528def reset(tarinfo):529    tarinfo.uid = tarinfo.gid = 0530    tarinfo.uname = tarinfo.gname = "root"531    return tarinfo532tar = tarfile.open("sample.tar.gz", "w:gz")533tar.add("foo", filter=reset)534tar.close()535```536537## 13.6.5. Поддерживаемые форматы tar538539Существует три формата tar, которые можно создать с помощью модуля [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile):540541- Формат ustar POSIX.1-1988 ([`USTAR_FORMAT`](https://python-all.ru/3.6/library/tarfile.html#tarfile.USTAR_FORMAT)). Поддерживает имена файлов длиной не более 256 символов и имена ссылок не более 100 символов. Максимальный размер файла – 8 ГиБ. Это старый и ограниченный, но широко поддерживаемый формат.542- Формат GNU tar ([`GNU_FORMAT`](https://python-all.ru/3.6/library/tarfile.html#tarfile.GNU_FORMAT)). Он поддерживает длинные имена файлов и ссылок, файлы размером более 8 ГиБ и разрежённые файлы. Это де-факто стандарт в системах GNU/Linux. [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile) полностью поддерживает расширения GNU tar для длинных имён; поддержка разрежённых файлов – только для чтения.543- Формат pax POSIX.1-2001 ([`PAX_FORMAT`](https://python-all.ru/3.6/library/tarfile.html#tarfile.PAX_FORMAT)). Это самый гибкий формат, практически без ограничений. Поддерживает длинные имена файлов и ссылок, большие файлы и хранит пути портативным образом. Однако не все современные реализации tar умеют правильно обрабатывать pax-архивы.544545  Формат *pax* является расширением существующего формата *ustar*. Он использует дополнительные заголовки для информации, которую иначе сохранить невозможно. Существует две разновидности pax-заголовков: расширенные заголовки действуют только на последующий заголовок файла, а глобальные заголовки действительны для всего архива и влияют на все последующие файлы. Все данные в pax-заголовке для портативности кодируются в *UTF-8*.546547Существуют ещё некоторые варианты формата tar, которые можно читать, но не создавать:548549- Древний формат V7. Это первый формат tar из Unix Seventh Edition, хранящий только обычные файлы и каталоги. Имена не должны быть длиннее 100 символов, информация об имени пользователя/группы отсутствует. Некоторые архивы имеют неправильные контрольные суммы заголовков в случае полей с не-ASCII символами.550- Расширенный формат SunOS tar. Этот формат является вариантом формата POSIX.1-2001 pax, но несовместим с ним.551552## 13.6.6. Проблемы с Unicode553554Формат tar изначально был задуман для создания резервных копий на ленточных накопителях с основным упором на сохранение информации о файловой системе. Сегодня tar-архивы обычно используются для распространения файлов и обмена архивами по сетям. Одна проблема исходного формата (который является основой всех других форматов) заключается в том, что нет концепции поддержки разных кодировок символов. Например, обычный tar-архив, созданный в системе с *UTF-8*, не может быть корректно прочитан в системе с *Latin-1*, если он содержит символы, отличные от *ASCII*. Текстовые метаданные (например, имена файлов, имена ссылок, имена пользователей/групп) будут повреждены. К сожалению, нет способа автоматически определить кодировку архива. Формат pax был разработан для решения этой проблемы. Он хранит не-ASCII метаданные, используя универсальную кодировку символов *UTF-8*.555556Детали преобразования символов в [`tarfile`](https://python-all.ru/3.6/library/tarfile.html#module-tarfile) управляются ключевыми аргументами *encoding* и *errors* класса [`TarFile`](https://python-all.ru/3.6/library/tarfile.html#tarfile.TarFile).557558*encoding* определяет кодировку символов, используемую для метаданных в архиве. Значение по умолчанию – [`sys.getfilesystemencoding()`](https://python-all.ru/3.6/library/sys.html#sys.getfilesystemencoding) или `'ascii'` в качестве запасного варианта. В зависимости от того, читается или записывается архив, метаданные должны быть либо декодированы, либо закодированы. Если *encoding* не установлена соответствующим образом, это преобразование может завершиться ошибкой.559560Аргумент *errors* определяет, как обрабатываются символы, которые невозможно преобразовать. Возможные значения перечислены в разделе [Обработчики ошибок](https://python-all.ru/3.6/library/codecs.html#error-handlers). Схема по умолчанию – `'surrogateescape'`, которую Python также использует для своих системных вызовов, см. [Имена файлов, аргументы командной строки и переменные окружения](https://python-all.ru/3.6/library/os.html#os-filenames).561562В случае архивов [`PAX_FORMAT`](https://python-all.ru/3.6/library/tarfile.html#tarfile.PAX_FORMAT) *encoding* обычно не нужен, поскольку все метаданные хранятся с использованием *UTF-8*. *encoding* используется только в редких случаях, когда декодируются бинарные pax-заголовки или когда сохраняются строки с суррогатными символами.563