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

12.5.1. Объекты 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=None, 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, определённых на уровне модуля.

Новое в версии 2.6.

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

Новое в версии 2.6.

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

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

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

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

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

Новое в версии 2.6.

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

Новое в версии 2.6.

classmethod 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, например, элементов с абсолютными именами, начинающимися с "/", или с именами, содержащими две точки "..".

Новое в версии 2.5.

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

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

Примечание

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

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

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

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 будет исключён из архива. См. Примеры для примера.

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

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

Устарело с версии 2.7: Параметр exclude устарел, пожалуйста, используйте вместо него параметр filter. Для максимальной переносимости filter следует использовать как ключевой аргумент, а не как позиционный, чтобы код не пострадал, когда exclude будет окончательно удалён.

TarFile.addfile(tarinfo, fileobj=None)¶

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

Примечание

На платформах Windows fileobj следует всегда открывать с режимом 'rb', чтобы избежать проблем с размером файла.

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

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

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

TarFile.close()¶

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

TarFile.posix¶

Установка этого в True эквивалентна установке атрибута format в USTAR_FORMAT, а False эквивалентно GNU_FORMAT.

Изменено в версии 2.4: posix по умолчанию равен False.

Устарело с версии 2.6: Вместо этого используйте атрибут format.

TarFile.pax_headers¶

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

Новое в версии 2.6.

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

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

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

class tarfile.TarInfo(name="")¶

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

TarInfo.frombuf(buf)¶

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

Новое в версии 2.6: Вызывает HeaderError, если буфер недействителен..

TarInfo.fromtarfile(tarfile)¶

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

Новое в версии 2.6.

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

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

Изменено в версии 2.6: Аргументы были добавлены.

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

Новое в версии 2.6.

Объект 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",
    if tarinfo.isreg():
        print "a regular file."
    elif tarinfo.isdir():
        print "a directory."
    else:
        print "something else."
tar.close()

Как создать архив и сбросить информацию о пользователе, используя параметр фильтр в 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. При чтении pax-архива эти имена в UTF-8 преобразуются в кодировку локальной файловой системы.

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

Значением по умолчанию для encoding является локальная кодировка символов. Она определяется из sys.getfilesystemencoding() и sys.getdefaultencoding(). В режиме чтения encoding используется исключительно для преобразования имён в Unicode из pax-архива в строки локальной кодировки. В режиме записи использование encoding зависит от выбранного формата архива. В случае PAX_FORMAT входные имена, содержащие символы не из ASCII, должны быть декодированы перед сохранением в виде строк UTF-8. Другие форматы не используют encoding, если только в качестве входных имён не используются объекты Unicode. Они преобразуются в 8-битные строки символов перед добавлением в архив.

Аргумент errors определяет, как обрабатываются символы, которые невозможно преобразовать в или из кодировки encoding. Возможные значения перечислены в разделе Базовые классы кодеков. В режиме чтения существует дополнительная схема 'utf-8', означающая, что некорректные символы заменяются их представлением в UTF-8. Это схема по умолчанию. В режиме записи значением по умолчанию для errors является 'strict', чтобы гарантировать, что информация об имени не будет изменена незаметно.