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

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

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

Изменено в версии 3.5: Добавлен режим 'x' (эксклюзивное создание).

Изменено в версии 3.6: Параметр name принимает значение path-like object.

classmethod TarFile.open(...)¶

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

TarFile.getmember(name)¶

Возвращает объект TarInfo для члена 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 из tarfile. В противном случае используются именованные значения из tarfile.

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

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

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

Изменено в версии 3.6: Параметр path принимает значение path-like object.

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

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

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

Примечание

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

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

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

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

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

Изменено в версии 3.6: Параметр path принимает значение path-like object.

TarFile.extractfile(member)¶

Извлечение члена из архива в виде объекта файла. член может быть именем файла или объектом TarInfo. Если член является обычным файлом или ссылкой, возвращается объект io.BufferedReader. Для всех остальных существующих членов возвращается None. Если член не встречается в архиве, выдается сообщение 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: Добавлен параметр фильтр.

Изменено в версии 3.7: Рекурсия добавляет записи в отсортированном порядке.

TarFile.addfile(tarinfo, fileobj=None)¶

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

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

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

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

Изменено в версии 3.6: Параметр name принимает значение path-like object.

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:

• Формат POSIX.1-1988 ustar (USTAR_FORMAT). Он поддерживает имена файлов длиной в лучшем случае 256 символов и имена ссылок длиной до 100 символов. Максимальный размер файла составляет 8 Гигабайт. Это старый и ограниченный, но широко поддерживаемый формат.

• Формат GNU tar (GNU_FORMAT). Он поддерживает длинные имена файлов и имена ссылок, файлы размером более 8 Гб и разреженные файлы. Это стандарт де-факто в системах GNU/Linux. tarfile полностью поддерживает расширения GNU tar для длинных имен, поддержка разреженных файлов доступна только для чтения.

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

Проблемы с юникодом¶

Изначально формат 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 или когда хранятся строки с суррогатными символами.