12.5. tarfile – чтение и запись tar-архивов¶tarfile – Read and write tar archive files

12.5.1. Объекты TarFile¶TarFile Objects

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

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

Новое в версии 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 – это путь к архиву. Его можно опустить, если указан fileobj. В этом случае используется атрибут name файлового объекта, если он существует.

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

Если указан 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 или IOError. Если 2, все нефатальные ошибки также возбуждаются как исключения TarError.

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

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

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

TarFile.open(...)¶

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

TarFile.getmember(name)¶

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

Примечание

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

TarFile.getmembers()¶

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

TarFile.getnames()¶

Возвращает элементы в виде списка их имён. Он имеет тот же порядок, что и список, возвращаемый getmembers().

TarFile.list(verbose=True)¶

Выводит оглавление в sys.stdout. Если verbose равен False, печатаются только имена элементов. Если он равен True, вывод аналогичен выводу ls -l.

TarFile.next()¶

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

TarFile.extractall(path=".", members=None)¶

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

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

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

TarFile.extract(member, path="", set_attrs=True)¶

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

Примечание

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

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

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

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

TarFile.extractfile(member)¶

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

Примечание

Файлоподобный объект доступен только для чтения. Он предоставляет методы read(), readline(), readlines(), seek(), tell() и close(), а также поддерживает итерацию по строкам.

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

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

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

Устарело с версии 3.2: Параметр exclude устарел, используйте вместо него параметр filter.

TarFile.addfile(tarinfo, fileobj=None)¶

Add the TarInfo object tarinfo to the archive. If fileobj is given, tarinfo.size bytes are read from it and added to the archive. You can create TarInfo objects using gettarinfo().

Примечание

On Windows platforms, fileobj should always be opened with mode 'rb' to avoid irritation about the file size.

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

Create a TarInfo object for either the file name or the file object fileobj (using os.fstat() on its file descriptor). You can modify some of the TarInfo‘s attributes before you add it using addfile(). If given, arcname specifies an alternative name for the file in the archive.

TarFile.close()¶

Close the TarFile. In write mode, two finishing zero blocks are appended to the archive.

TarFile.pax_headers¶

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

12.5.2. Объекты TarInfo¶TarInfo Objects

A TarInfo object represents one member in a TarFile. Aside from storing all required attributes of a file (like file type, size, time, permissions, owner etc.), it provides some useful methods to determine its type. It does not contain the file’s data itself.

TarInfo objects are returned by TarFile‘s methods getmember(), getmembers() and gettarinfo().

class tarfile.TarInfo(name="")¶

Create a TarInfo object.

TarInfo.frombuf(buf)¶

Create and return a TarInfo object from string buffer buf.

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

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.

12.5.3. Примеры¶Examples

Как извлечь полный 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()

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

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

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

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

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

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