tarfile – Чтение и запись файлов tar-архивов¶tarfile – Read and write tar archive files

Объекты TarFile¶TarFile Objects

Объект TarFile предоставляет интерфейс к архиву tar. Архив tar представляет собой последовательность блоков. Элемент архива (хранимый файл) состоит из заголовочного блока, за которым следуют блоки данных. Файл можно сохранить в архив tar несколько раз. Каждый элемент архива представляется объектом TarInfo, подробнее см. Объекты TarInfo.

Объект TarFile можно использовать как контекстный менеджер в операторе with. Он будет автоматически закрыт по завершении блока. Обратите внимание: в случае исключения архив, открытый для записи, не будет финализирован; будет закрыт только внутренний файловый объект. Пример использования см. в разделе Примеры.

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)¶

Все последующие аргументы необязательны и также могут быть доступны как атрибуты экземпляра.

name – это путь к архиву. name может быть объектом, подобным пути. Его можно опустить, если указан fileobj. В этом случае используется атрибут файлового объекта name, если он существует.

mode может быть 'r' для чтения из существующего архива, 'a' для добавления данных в существующий файл, 'w' для создания нового файла с перезаписью существующего или 'x' для создания нового файла только в том случае, если он ещё не существует.

Если указан fileobj, он используется для чтения или записи данных. Если это можно определить, mode переопределяется режимом fileobj. fileobj будет использоваться с позиции 0.

Примечание

fileobj не закрывается при закрытии TarFile.

format управляет форматом архива для записи. Он должен быть одной из констант USTAR_FORMAT, GNU_FORMAT или PAX_FORMAT, определённых на уровне модуля. При чтении формат будет определён автоматически, даже если в одном архиве присутствуют разные форматы.

Аргумент tarinfo можно использовать для замены класса по умолчанию TarInfo на другой.

Если dereference равно False, в архив добавляются символические и жёсткие ссылки. Если True, в архив добавляется содержимое целевых файлов. Это не влияет на системы, не поддерживающие символические ссылки.

Если ignore_zeros равно False, пустой блок считается концом архива. Если True, пустые (и недействительные) блоки пропускаются, и предпринимается попытка получить как можно больше элементов. Это полезно только для чтения объединённых или повреждённых архивов.

debug может быть установлен от 0 (нет отладочных сообщений) до 3 (все отладочные сообщения). Сообщения записываются в sys.stderr.

errorlevel управляет обработкой ошибок извлечения, см. the corresponding attribute.

Аргументы encoding и errors определяют кодировку символов, используемую для чтения или записи архива, и способ обработки ошибок преобразования. Настройки по умолчанию подходят для большинства пользователей. Подробную информацию см. в разделе Проблемы Unicode.

Аргумент pax_headers – необязательный словарь строк, который будет добавлен как глобальный заголовок pax, если format равно PAX_FORMAT.

Если поток данных установлен в True, то при чтении архива информация о файлах в архиве не кэшируется, экономя память.

Изменено в версии 3.2: В качестве значения по умолчанию для аргумента errors используется 'surrogateescape'.

Изменено в версии 3.5: Добавлен режим 'x' (эксклюзивное создание).

Изменено в версии 3.6: Параметр name принимает объект, подобный пути.

Изменено в версии 3.13: Добавлен параметр поток данных.

classmethod TarFile.open(...)¶

Альтернативный конструктор. Функция tarfile.open() на самом деле является сокращением для этого метода класса.

TarFile.getmember(name)¶

Возвращает объект TarInfo для элемента name. Если name не найден в архиве, возбуждается KeyError.

Примечание

Если элемент встречается в архиве более одного раза, последнее его вхождение считается самой актуальной версией.

TarFile.getmembers()¶

Возвращает элементы архива в виде списка объектов TarInfo. Порядок списка соответствует порядку элементов в архиве.

TarFile.getnames()¶

Возвращает элементы в виде списка их имён. Порядок списка соответствует порядку списка, возвращаемого getmembers().

TarFile.list(verbose=True, *, members=None)¶

Выводит оглавление в sys.stdout. Если verbose равно False, печатаются только имена элементов. Если же True, выводятся данные, аналогичные ls -l. Если задан необязательный параметр members, он должен быть подмножеством списка, возвращаемого getmembers().

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

TarFile.next()¶

Возвращает следующий элемент архива в виде объекта TarInfo, когда TarFile открыт для чтения. Если больше нет элементов, возвращает None.

TarFile.extractall(path='.', members=None, *, numeric_owner=False, filter=None)¶

Извлекает все элементы из архива в текущую рабочую директорию или в директорию path. Если задан необязательный параметр members, он должен быть подмножеством списка, возвращаемого getmembers(). Сведения о директории (владелец, время изменения, права доступа) устанавливаются после извлечения всех элементов. Это сделано для обхода двух проблем: время изменения директории сбрасывается при каждом создании в ней файла, и если права директории не разрешают запись, извлечение в неё файлов завершится ошибкой.

Если numeric_owner равно True, для установки владельца и группы извлечённых файлов используются числовые uid и gid из tar-файла. В противном случае используются именованные значения из tar-файла.

Аргумент filter определяет, как members изменяются или отклоняются перед извлечением. Подробнее см. в разделе Фильтры извлечения. Рекомендуется задавать его явно только в тех случаях, когда требуются специфические возможности tar, или в качестве filter='data' для поддержки версий Python с менее безопасным значением по умолчанию (3.13 и ниже).

Предупреждение

Никогда не извлекайте архивы из ненадёжных источников без предварительной проверки.

Начиная с Python 3.14, значение по умолчанию (data) предотвращает наиболее опасные проблемы безопасности. Однако оно не предотвращает все непреднамеренные или небезопасные действия. Подробнее читайте в разделе Фильтры извлечения.

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

Изменено в версии 3.6: Параметр path теперь принимает объект, подобный пути.

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

Изменено в версии 3.14: Параметр filter теперь по умолчанию равен 'data'.

TarFile.extract(member, path='', set_attrs=True, *, numeric_owner=False, filter=None)¶

Извлекает элемент из архива в текущую рабочую директорию, используя его полное имя. Информация о файле извлекается максимально точно. member может быть именем файла или объектом TarInfo. Можно указать другую директорию с помощью path. path может быть объектом, подобным пути. Атрибуты файла (владелец, mtime, права доступа) устанавливаются, если set_attrs не равно false.

Аргументы numeric_owner и filter такие же, как для extractall().

Примечание

Метод extract() не решает ряд проблем извлечения. В большинстве случаев стоит рассмотреть использование метода extractall().

Предупреждение

Никогда не извлекайте архивы из ненадёжных источников без предварительной проверки. Подробнее см. предупреждение для extractall().

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

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

Изменено в версии 3.6: Параметр path теперь принимает объект, подобный пути.

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

TarFile.extractfile(member)¶

Извлекает элемент из архива в виде файлового объекта. member может быть именем файла или объектом TarInfo. Если member – обычный файл или ссылка, возвращается объект io.BufferedReader. Для всех остальных существующих элементов возвращается None. Если member не найден в архиве, вызывается KeyError.

Изменено в версии 3.3: Возвращается объект io.BufferedReader.

Изменено в версии 3.13: Возвращаемый объект io.BufferedReader имеет атрибут mode который всегда равен 'rb'.

TarFile.errorlevel: int¶

Если errorlevel равен 0, ошибки игнорируются при использовании TarFile.extract() и TarFile.extractall(). Тем не менее, они отображаются как сообщения об ошибках в отладочном выводе, когда debug больше 0. Если 1 (по умолчанию), все фатальные ошибки вызываются как исключения OSError или FilterError. Если 2, все нефатальные ошибки также вызываются как исключения TarError.

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

Пользовательские фильтры извлечения должны вызывать FilterError для фатальных ошибок и ExtractError для нефатальных.

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

TarFile.extraction_filter¶

Добавлено в версии 3.12.

Фильтр извлечения, используемый по умолчанию для аргумента filter методов extract() и extractall().

Атрибут может быть None или вызываемым объектом. Строковые имена для этого атрибута не допускаются, в отличие от аргумента filter для extract().

Если extraction_filter равен None (по умолчанию), методы извлечения будут по умолчанию использовать фильтр data.

Атрибут может быть установлен для экземпляров или переопределён в подклассах. Также возможно установить его для самого класса TarFile, чтобы задать глобальное значение по умолчанию; однако, поскольку это влияет на все случаи использования tarfile, лучшей практикой будет делать это только в приложениях верхнего уровня или site configuration. Чтобы задать глобальное значение по умолчанию таким образом, функцию фильтра необходимо обернуть в staticmethod(), чтобы предотвратить внедрение аргумента self.

Изменено в версии 3.14: Фильтр по умолчанию установлен на data, что запрещает некоторые опасные возможности, такие как ссылки на абсолютные пути или пути за пределами целевого каталога. Ранее значение по умолчанию было эквивалентно fully_trusted.

TarFile.add(name, arcname=None, recursive=True, *, filter=None)¶

Добавляет файл name в архив. name может быть любым типом файла (каталог, FIFO, символическая ссылка и т.д.). Если задан, arcname указывает альтернативное имя файла в архиве. Каталоги добавляются рекурсивно по умолчанию. Этого можно избежать, установив recursive в False. Рекурсия добавляет записи в отсортированном порядке. Если задан filter, он должен быть функцией, которая принимает аргумент объекта TarInfo и возвращает изменённый объект TarInfo. Если же она возвращает None, объект TarInfo будет исключён из архива. Пример см. в Примерах.

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

Изменено в версии 3.7: Рекурсия добавляет записи в отсортированном порядке.

TarFile.addfile(tarinfo, fileobj=None)¶

Добавляет объект TarInfo tarinfo в архив. Если tarinfo представляет обычный файл ненулевого размера, аргумент fileobj должен быть двоичным файлом, и из него читается tarinfo.size байт, которые добавляются в архив. Можно создавать объекты TarInfo напрямую или с помощью gettarinfo().

Изменено в версии 3.13: fileobj должен быть указан для обычных файлов ненулевого размера.

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)¶

Создаёт объект TarInfo из результата os.stat() или эквивалентного для существующего файла. Файл задаётся либо именем name, либо указывается как файловый объект fileobj с файловым дескриптором. name может быть объектом, подобным пути. Если задан, arcname указывает альтернативное имя файла в архиве; в противном случае имя берётся из атрибута name объекта fileobj или из аргумента name. Имя должно быть текстовой строкой.

Можно изменить некоторые атрибуты объекта TarInfo перед его добавлением с помощью addfile(). Если файловый объект не является обычным файловым объектом, расположенным в начале файла, такие атрибуты, как size, могут потребовать изменения. Это относится к таким объектам, как GzipFile. Атрибут name также может быть изменён, и в этом случае arcname может быть фиктивной строкой.

Изменено в версии 3.6: Параметр name принимает объект, подобный пути.

TarFile.close()¶

Закрывает TarFile. В режиме записи в архив добавляются два завершающих нулевых блока.

TarFile.pax_headers: dict¶

Словарь, содержащий пары ключ-значение глобальных заголовков pax.

Объекты TarInfo¶TarInfo Objects

Объект TarInfo представляет один элемент в TarFile. Помимо хранения всех необходимых атрибутов файла (таких как тип, размер, время, права доступа, владелец и т.д.), он предоставляет некоторые полезные методы для определения его типа. Он не содержит сами данные файла.

Объекты TarInfo возвращаются методами TarFile: getmember(), getmembers() и gettarinfo().

Изменение объектов, возвращённых методами getmember() или getmembers(), повлияет на все последующие операции с архивом. В случаях, когда это нежелательно, можно использовать copy.copy() или вызвать метод replace(), чтобы создать изменённую копию за один шаг.

Некоторые атрибуты могут быть установлены в None, чтобы указать, что часть метаданных не используется или неизвестна. Разные методы TarInfo обрабатывают None по-разному:

• Методы extract() и extractall() будут игнорировать соответствующие метаданные, оставляя их установленными по умолчанию.

• addfile() завершится ошибкой.

• list() выведет строку-заполнитель.

class tarfile.TarInfo(name='')¶

Создаёт объект TarInfo.

classmethod TarInfo.frombuf(buf, encoding, errors)¶

Создаёт и возвращает объект TarInfo из строкового буфера buf.

Вызывает HeaderError, если буфер некорректен.

classmethod TarInfo.fromtarfile(tarfile)¶

Читает следующий элемент из объекта TarFile tarfile и возвращает его в виде объекта TarInfo.

TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')¶

Создаёт строковый буфер из объекта TarInfo. Подробнее об аргументах см. конструктор класса TarFile.

Изменено в версии 3.2: В качестве значения по умолчанию для аргумента errors используется 'surrogateescape'.

Объект TarInfo имеет следующие открытые атрибуты данных:

TarInfo.name: str¶

Имя элемента архива.

TarInfo.size: int¶

Размер в байтах.

TarInfo.mtime: int | float¶

Время последнего изменения в секундах с начала эпохи, как в os.stat_result.st_mtime.

Изменено в версии 3.12: Можно установить в None для extract() и extractall(), что приведёт к пропуску применения этого атрибута при извлечении.

TarInfo.mode: int¶

Биты прав доступа, как для os.chmod().

Изменено в версии 3.12: Можно установить в None для extract() и extractall(), что приведёт к пропуску применения этого атрибута при извлечении.

TarInfo.type¶

Тип файла. Обычно type – это одна из следующих констант: REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE. Чтобы более удобно определить тип объекта TarInfo, используйте методы is*(), описанные ниже.

TarInfo.linkname: str¶

Имя целевого файла, которое присутствует только в объектах TarInfo типов LNKTYPE и SYMTYPE.

Для символических ссылок (SYMTYPE) значение linkname указывается относительно каталога, содержащего ссылку. Для жёстких ссылок (LNKTYPE) значение linkname указывается относительно корня архива.

TarInfo.uid: int¶

Идентификатор пользователя, который изначально сохранил этот элемент.

Изменено в версии 3.12: Можно установить в None для extract() и extractall(), что приведёт к пропуску применения этого атрибута при извлечении.

TarInfo.gid: int¶

Идентификатор группы пользователя, который изначально сохранил этот элемент.

Изменено в версии 3.12: Можно установить в None для extract() и extractall(), что приведёт к пропуску применения этого атрибута при извлечении.

TarInfo.uname: str¶

Имя пользователя.

Изменено в версии 3.12: Можно установить в None для extract() и extractall(), что приведёт к пропуску применения этого атрибута при извлечении.

TarInfo.gname: str¶

Имя группы.

Изменено в версии 3.12: Можно установить в None для extract() и extractall(), что приведёт к пропуску применения этого атрибута при извлечении.

TarInfo.chksum: int¶

Контрольная сумма заголовка.

TarInfo.devmajor: int¶

Старший номер устройства.

TarInfo.devminor: int¶

Младший номер устройства.

TarInfo.offset: int¶

Заголовок tar начинается здесь.

TarInfo.offset_data: int¶

Данные файла начинаются здесь.

TarInfo.sparse¶

Информация о разреженном элементе.

TarInfo.pax_headers: dict¶

Словарь, содержащий пары ключ-значение связанного расширенного заголовка pax.

TarInfo.replace(name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)¶

Добавлено в версии 3.12.

Возвращает новую копию объекта TarInfo с указанными изменёнными атрибутами. Например, чтобы вернуть TarInfo с именем группы, установленным в 'staff', используйте:

new_tarinfo = old_tarinfo.replace(gname='staff')

По умолчанию создаётся глубокая копия. Если deep равен false, копия поверхностная, то есть pax_headers и любые пользовательские атрибуты являются общими с исходным объектом TarInfo.

Объект TarInfo также предоставляет несколько удобных запросных методов:

TarInfo.isfile()¶

Возвращает True, если объект TarInfo является обычным файлом.

TarInfo.isreg()¶

То же, что и isfile().

TarInfo.isdir()¶

Возвращает True, если это каталог.

TarInfo.issym()¶

Возвращает True, если это символическая ссылка.

TarInfo.islnk()¶

Возвращает True, если это жёсткая ссылка.

TarInfo.ischr()¶

Возвращает True, если это символьное устройство.

TarInfo.isblk()¶

Возвращает True, если это блочное устройство.

TarInfo.isfifo()¶

Возвращает True, если это FIFO.

TarInfo.isdev()¶

Возвращает True, если это символьное устройство, блочное устройство или FIFO.

Фильтры извлечения¶Extraction filters

Формат tar предназначен для сохранения всех деталей файловых систем UNIX-подобных ОС, что делает его очень мощным. К сожалению, эти возможности позволяют легко создавать tar-файлы, которые при извлечении могут иметь непреднамеренные – а возможно и вредоносные – эффекты. Например, извлечение tar-файла может перезаписать произвольные файлы различными способами (например, с использованием абсолютных путей, компонентов пути .. или символических ссылок, влияющих на последующие элементы).

В большинстве случаев полная функциональность не требуется. Поэтому tarfile поддерживает фильтры извлечения: механизм ограничения функциональности, что позволяет смягчить некоторые проблемы безопасности.

Аргумент filter для TarFile.extract() или extractall() может быть:

• строка 'fully_trusted': соблюдать все метаданные, указанные в архиве. Следует использовать, если пользователь полностью доверяет архиву или реализует собственную сложную проверку.

• строка 'tar': соблюдать большинство специфических для tar возможностей (т.е. возможностей файловых систем UNIX-подобных ОС), но блокировать те, которые могут быть неожиданными или вредоносными. Подробнее см. tar_filter().

• строка 'data': игнорировать или блокировать большинство специфических для UNIX-подобных файловых систем возможностей. Предназначен для извлечения кроссплатформенных архивов. Подробнее см. data_filter().

• None (по умолчанию): использовать TarFile.extraction_filter.

  Если он тоже None (по умолчанию), будет использован фильтр 'data'.

  Изменено в версии 3.14: Фильтр по умолчанию установлен на data. Ранее значение по умолчанию было эквивалентно fully_trusted.

• Вызываемый объект, который будет вызываться для каждого извлекаемого элемента с объектом TarInfo, описывающим элемент и путь назначения, куда извлекается архив (т.е. один и тот же путь используется для всех элементов):

  filter(member: TarInfo, path: str, /) -> TarInfo | None
  

  Вызываемый объект вызывается непосредственно перед извлечением каждого элемента, поэтому он может учитывать текущее состояние диска. Он может:

  • вернуть объект TarInfo, который будет использоваться вместо метаданных в архиве, или

  • вернуть None, в этом случае элемент будет пропущен, или

  • вызвать исключение для прерывания операции или пропуска элемента, в зависимости от errorlevel. Обратите внимание, что при прерывании извлечения extractall() может оставить архив частично извлечённым. Он не пытается выполнить очистку.

with StatefulFilter() as filter_func:
    tar.extractall(path, filter=filter_func)

class StatefulFilter:
    def __init__(self):
        self.file_count = 0

    def __enter__(self):
        return self

    def __call__(self, member, path):
        self.file_count += 1
        return member

    def __exit__(self, *exc_info):
        print(f'{self.file_count} files extracted')

Интерфейс командной строки¶Command-Line Interface

Модуль tarfile предоставляет простой интерфейс командной строки для работы с tar-архивами.

Если вы хотите создать новый tar-архив, укажите его имя после опции -c, а затем перечислите имена файлов, которые должны быть включены:

$ python -m tarfile -c monty.tar  spam.txt eggs.txt

Можно также передать каталог:

$ python -m tarfile -c monty.tar life-of-brian_1979/

Если вы хотите извлечь tar-архив в текущий каталог, используйте опцию -e:

$ python -m tarfile -e monty.tar

Вы также можете извлечь tar-архив в другой каталог, передав его имя:

$ python -m tarfile -e monty.tar  other-dir/

Чтобы получить список файлов в tar-архиве, используйте опцию -l:

$ python -m tarfile -l monty.tar

Примеры¶Examples

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall(filter='data')
tar.close()

import os
import tarfile

def py_files(members):
    for tarinfo in members:
        if os.path.splitext(tarinfo.name)[1] == ".py":
            yield tarinfo

tar = tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()

import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
    print(tarinfo.name, "is", tarinfo.size, "bytes in size and is ", end="")
    if tarinfo.isreg():
        print("a regular file.")
    elif tarinfo.isdir():
        print("a directory.")
    else:
        print("something else.")
tar.close()

import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()

import tarfile
with tarfile.open("sample.tar", "w") as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

import sys
import tarfile
with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

import tarfile
def reset(tarinfo):
    tarinfo.uid = tarinfo.gid = 0
    tarinfo.uname = tarinfo.gname = "root"
    return tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()

Поддерживаемые форматы tar¶Supported tar formats

Существует три формата tar, которые можно создать с помощью модуля tarfile:

• Формат POSIX.1-1988 ustar (USTAR_FORMAT). Он поддерживает имена файлов длиной не более 256 символов и имена ссылок – до 100 символов. Максимальный размер файла – 8 ГиБ. Это старый и ограниченный, но широко поддерживаемый формат.

• Формат GNU tar (GNU_FORMAT). Он поддерживает длинные имена файлов и ссылок, файлы размером более 8 ГиБ и разрежённые файлы. Это де-факто стандарт в системах GNU/Linux. tarfile полностью поддерживает расширения GNU tar для длинных имён; поддержка разрежённых файлов – только для чтения.

• Формат POSIX.1-2001 pax (PAX_FORMAT). Это самый гибкий формат, практически без ограничений. Он поддерживает длинные имена файлов и ссылок, большие файлы и хранит пути переносимым способом. Современные реализации tar, включая GNU tar, bsdtar/libarchive и star, полностью поддерживают расширенные возможности pax; некоторые старые или неподдерживаемые библиотеки могут не поддерживать, но должны обрабатывать архивы pax так, как если бы они были в универсально поддерживаемом формате ustar. Это текущий формат по умолчанию для новых архивов.

  Он расширяет существующий формат ustar дополнительными заголовками для информации, которую иначе нельзя сохранить. Существует две разновидности заголовков pax: расширенные заголовки влияют только на последующий заголовок файла, глобальные заголовки действительны для всего архива и влияют на все последующие файлы. Все данные в заголовке pax кодируются в UTF-8 по соображениям переносимости.

Существуют ещё некоторые варианты формата tar, которые можно читать, но не создавать:

• Древний формат V7. Это первый формат tar из Unix Seventh Edition, хранящий только обычные файлы и каталоги. Имена не должны быть длиннее 100 символов, информация об имени пользователя/группы отсутствует. Некоторые архивы имеют неправильные контрольные суммы заголовков в случае полей с не-ASCII символами.

• Расширенный формат SunOS tar. Этот формат является вариантом формата POSIX.1-2001 pax, но несовместим с ним.

Проблемы Unicode¶Unicode issues

Формат tar изначально был задуман для создания резервных копий на ленточных накопителях с основным упором на сохранение информации о файловой системе. Сегодня tar-архивы обычно используются для распространения файлов и обмена архивами по сетям. Одна проблема исходного формата (который является основой всех других форматов) заключается в том, что нет концепции поддержки разных кодировок символов. Например, обычный tar-архив, созданный в системе с UTF-8, не может быть корректно прочитан в системе с Latin-1, если он содержит символы, отличные от ASCII. Текстовые метаданные (например, имена файлов, имена ссылок, имена пользователей/групп) будут повреждены. К сожалению, нет способа автоматически определить кодировку архива. Формат pax был разработан для решения этой проблемы. Он хранит не-ASCII метаданные, используя универсальную кодировку символов UTF-8.

Детали преобразования символов в tarfile управляются ключевыми аргументами encoding и errors класса TarFile.

encoding определяет кодировку символов, используемую для метаданных в архиве. Значение по умолчанию – sys.getfilesystemencoding() или 'ascii' в качестве запасного варианта. В зависимости от того, читается или записывается архив, метаданные должны быть либо декодированы, либо закодированы. Если encoding не установлена соответствующим образом, это преобразование может завершиться ошибкой.

Аргумент errors определяет, как обрабатываются символы, которые невозможно преобразовать. Возможные значения перечислены в разделе Обработчики ошибок. Схема по умолчанию – 'surrogateescape', которую Python также использует для своих системных вызовов, см. Имена файлов, аргументы командной строки и переменные окружения.

Для архивов PAX_FORMAT (по умолчанию) encoding обычно не требуется, потому что все метаданные хранятся с использованием UTF-8. encoding используется только в редких случаях, когда декодируются бинарные заголовки pax или когда хранятся строки с суррогатными символами.