tarfile — Чтение и запись архивов TAR

Объекты TarFile

Объект 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=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 определяют кодировку символов, используемую для чтения или записи архива, и то, как обрабатываются ошибки преобразования. По умолчанию настройки подойдут большинству пользователей. Подробная информация содержится в разделе Проблемы с Unicode.

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

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

Изменено в версии 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 не равно false.

Если 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. Если member не найден в архиве, возникает исключение KeyError.

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

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 в архив. Если задан 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

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

TarInfo.gid

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

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.

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

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

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

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

Также допустимо передать каталог:

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

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

$ python -m tarfile -e monty.tar

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

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

Для просмотра списка файлов в тар-архиве используйте опцию -l:

$ python -m tarfile -l monty.tar

Примеры

Как извлечь весь тар-архив в текущую рабочую директорию:

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

Как извлечь подмножество тар-архива с помощью 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()

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

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)

Как прочитать 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 для длинных имен, поддержка разреженных файлов — только для чтения.

• Формат pax POSIX.1-2001 (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, но несовместим.

Вопросы Unicode

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