tarfile — Чтение и запись tar архивных файлов

Модуль tarfile позволяет читать и записывать tar-архивы, в том числе с использованием сжатия gzip, bz2 и lzma. Используйте модуль zipfile для чтения или записи .zip файлов или функций более высокого уровня в shutil.

Некоторые факты и цифры:

  • читает и записывает сжатые архивы gzip, bz2 и lzma, если соответствующие модули доступны.
  • поддержка чтения/записи для формата POSIX.1-1988 (ustar).
  • поддержка чтения/записи для формата GNU tar, включая расширения longname и longlink, поддержка только для чтения для всех вариантов расширения sparse, включая восстановление разрежённых файлов.
  • поддержка чтения/записи для формата POSIX.1-2001 (pax).
  • обрабатывает каталоги, обычные файлы, жёсткие ссылки, символические ссылки, FIFO, символьные устройства и блочные устройства, а также может получать и восстанавливать информацию о файлах, такую как временная метка, права доступа и владелец.

Изменено в версии 3.3: Добавлена поддержка сжатия lzma.

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

Возвращает объект TarFile для пути name. Для получения подробной информации об объектах TarFile и допустимых ключевых аргументах см. Объекты TarFile.

mode должен быть строкой в форме 'filemode[:compression]', по умолчанию — 'r'. Вот полный список комбинаций mode:

mode действие
'r' или 'r:*' Открыть для чтения с прозрачным сжатием (рекомендуется).
'r:' Открыть для чтения исключительно без сжатия.
'r:gz' Открыть для чтения со сжатием gzip.
'r:bz2' Открыть для чтения со сжатием bzip2.
'r:xz' Открыт для чтения со сжатием lzma.
'x' или 'x:' Создаёт файл tarfile исключительно без сжатия. Создаёт исключение FileExistsError, если оно уже существует.
'x:gz' Создаёт tar файл с gzip сжатием. Вызвать исключение FileExistsError, если он уже существует.
'x:bz2' Создаёт tar файл с bzip2 сжатием. Вызвать исключение FileExistsError, если он уже существует.
'x:xz' Создаёт tar файл с lzma сжатием. Вызвать исключение FileExistsError, если он уже существует.
'a' or 'a:' Открыть для добавления без сжатия. Файл создаётся, если он не существует.
'w' or 'w:' Открыть для несжатой записи.
'w:gz' Открыть для записи со сжатием gzip.
'w:bz2' Открыть для записи со сжатием bzip2.
'w:xz' Открыт для записи со сжатием lzma.

Обратите внимание, что 'a:gz', 'a:bz2' или 'a:xz' невозможны. Если mode не подходит для открытия определенного (сжатого) файла для чтения, возникает ReadError. Чтобы этого избежать, используйте mode 'r'. Если метод сжатия не поддерживается, возникает CompressionError.

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

Для режимов 'w:gz', 'r:gz', 'w:bz2', 'r:bz2', 'x:gz', 'x:bz2', tarfile.open() принимает ключевой аргумент compresslevel (по умолчанию 9), чтобы указать уровень сжатия файла.

Для специальных целей существует второй формат для mode: 'filemode|[compression]'. tarfile.open() вернёт объект TarFile, который обрабатывает свои данные как поток блоков. Случайный поиск по файлу производиться не будет. Если задан, fileobj может быть любым объектом, имеющим метод read() или write() (в зависимости от mode). bufsize определяет размер блока и по умолчанию 20 * 512 байт. Использовать этот вариант в сочетании, например, с sys.stdin, сокетом файлового объекта или ленточным устройством. Однако такой объект TarFile ограничен тем, что не разрешает произвольный доступ, см. Примеры. Возможные на данный момент mode:

mode Действие
'r|*' Открыть stream tar блоков для чтения с прозрачным сжатием.
'r|' Открыть stream несжатых tar блоков для чтения.
'r|gz' Открыть сжатый stream gzip для чтения.
'r|bz2' Открыть сжатый stream bzip2 для чтения.
'r|xz' Открыть сжатый stream lzma для чтения.
'w|' Открыть несжатый stream для записи.
'w|gz' Открыть сжатый stream gzip для записи.
'w|bz2' Открыть сжатый stream bzip2 для записи.
'w|xz' Открыть сжатый stream lzma для записи.

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

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

class tarfile.TarFile

Класс для чтения и записи tar-архивов. Не используйте этот класс напрямую: используйте вместо него tarfile.open(). См. Объекты TarFile.

tarfile.is_tarfile(name)

Возвращает True, если name — это файл архива tar, который может прочитать модуль tarfile.

Модуль tarfile определяет следующие исключения:

exception tarfile.TarError

Базовый класс для всех исключений tarfile.

exception tarfile.ReadError

Возникает при открытии tar-архива, который либо не может быть обработан модулем tarfile, либо некорректен.

exception tarfile.CompressionError

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

exception tarfile.StreamError

Вызывается для ограничений, типичных для потоковых объектов TarFile.

exception tarfile.ExtractError

Вызывается для несмертельных ошибок при использовании TarFile.extract(), но только если TarFile.errorlevel == 2.

exception tarfile.HeaderError

Вызывается TarInfo.frombuf(), если полученный буфер недействителен.

Следующие константы доступны на уровне модуля:

tarfile.ENCODING

Кодировка символов по умолчанию: 'utf-8' в Windows, в противном случае возвращаемое значение sys.getfilesystemencoding().

Каждая из следующих констант определяет формат tar-архива, который может создать модуль tarfile. См. подробности в разделе Поддерживаемые форматы tar.

tarfile.USTAR_FORMAT

Формат POSIX.1-1988 (ustar).

tarfile.GNU_FORMAT

GNU tar формат.

tarfile.PAX_FORMAT

Формат POSIX.1-2001 (pax).

tarfile.DEFAULT_FORMAT

Формат по умолчанию для создания архивов. В настоящее время это PAX_FORMAT.

Изменено в версии 3.8: Формат по умолчанию для новых архивов был изменён на PAX_FORMAT с GNU_FORMAT.

См.также

Модуль zipfile
Документация на стандартный модуль zipfile.
Архивные операции
Документация по средствам архивации более высокого уровня, предоставляемым стандартным модулем shutil.
Руководство по GNU tar, базовый формат Tar
Документация для файлов архивов tar, включая расширения GNU tar.

Объекты TarFile

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

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

Добавлено в версии 3.2: Добавлена поддержка протокола управления контекстом.

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)

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

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 — 0, все ошибки игнорируются при использовании TarFile.extract(). Тем не менее, они появляются как сообщения об ошибках в отладочных данных, когда отладка включена. Если 1, все фатальные ошибки возникают как исключения OSError. Если 2, все ошибки нефатальные также возникают как исключения TarError.

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

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

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

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

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

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)

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

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

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

Никогда не извлекайте архивы из ненадёжных источников без предварительной проверки. Возможно, что файлы созданы вне path, например элементы, которые имеют абсолютные имена файлов, начинающиеся с "/", или имена файлов с двумя точками "..".

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

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

TarFile.extract(member, path="", set_attrs=True, *, numeric_owner=False)

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

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

Примечание

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

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

См. предупреждение для extractall().

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

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

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

TarFile.extractfile(member)

Извлечь элемент из архива как файловый объект. member может быть именем файла или объектом TarInfo. Если member — обычный файл или ссылка, возвращается объект io.BufferedReader. В противном случае возвращается None.

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

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

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

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

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

TarFile.addfile(tarinfo, fileobj=None)

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

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

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

Объекты TarInfo

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

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

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: Использовать 'surrogateescape' по умолчанию для аргумента errors.

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

TarInfo.name

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

TarInfo.size

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

TarInfo.mtime

Время последней модификации.

TarInfo.mode

Биты разрешения.

TarInfo.type

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

TarInfo.linkname

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

TarInfo.uid

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

TarInfo.gid

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

TarInfo.uname

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

TarInfo.gname

Имя группы.

TarInfo.pax_headers

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

Объект 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.

Интерфейс командной строки

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

Модуль 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

Параметры командной строки

-l <tarfile>
--list <tarfile>

Перечислить файлы в tar-файле.

-c <tarfile> <source1> ... <sourceN>
--create <tarfile> <source1> ... <sourceN>

Создаёт tar-файл из исходных файлов.

-e <tarfile> [<output_dir>]
--extract <tarfile> [<output_dir>]

Распаковать tar-файл в текущий каталог, если output_dir не указан.

-t <tarfile>
--test <tarfile>

Проверить, действителен ли tar-файл.

-v, --verbose

Подробный вывод.

Примеры

Как распаковать весь tar-архив в текущий рабочий каталог:

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

Как извлечь подмножество tar-архива с помощью TarFile.extractall(), используя функцию генератора вместо списка:

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

Как создать несжатый tar-архив из списка имён файлов:

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

Тот же пример с использованием оператора with:

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

Как читать tar-архив, сжатый gzip, и отображать некоторую информацию о элементах:

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

Как создать архив и сбросить информацию о пользователе с помощью параметра filter в TarFile.add():

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

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

  • Формат ustar POSIX.1-1988 (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.
  • Расширенный формат tar SunOS. Этот формат является вариантом формата pax POSIX.1-2001, но несовместим.

Проблемы с Юникодом

Формат 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 декодируются или когда хранятся строки с суррогатными символами.