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, все ошибки fatal генерируются как исключения OSError. Если 2, все некритические ошибки генерируются как исключения TarError также.

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

Аргумент 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 не равно 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.

Изменено в версии 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 предоставляет простой интерфейс командной строки для взаимодействия с архивами 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

Примеры

Как извлечь весь архив 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)

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

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. Этот формат является вариантом формата POSIX.1-2001 pax, но несовместим.

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