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

13.6.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='surrogateescape', pax_headers=None, debug=0, errorlevel=0)

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

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' (эксклюзивное создание).

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.

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

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

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

Примечание

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

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

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

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

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

TarFile.extractfile(member)¶

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

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

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

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

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.pax_headers¶

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

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

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

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

13.6.3. Интерфейс командной строки¶Command-Line Interface

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

13.6.4. Примеры¶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()

Как создать архив и сбросить информацию о пользователе, используя параметр фильтр в 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()

13.6.5. Поддерживаемые форматы tar¶Supported tar formats

Существует три формата 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 умеют правильно обрабатывать pax-архивы.

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

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

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

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