tarfile — Чтение и запись архивов TAR

Исходный код: Lib/tarfile.py

Модуль tarfile позволяет читать и записывать архивы TAR, включая архивы сжатые с помощью gzip, bz2 и lzma. Используйте модуль zipfile для чтения или записи .zip файлов, или функции более высокого уровня в shutil.

Некоторые факты и цифры:

• читает и записывает архивы, сжатые с помощью gzip, bz2 и lzma, если соответствующие модули доступны.
• поддержка чтения/записи формата POSIX.1-1988 (ustar).
• поддержка чтения/записи формата GNU tar, включая расширения longname и longlink, поддержка только чтения для всех вариантов расширения sparse, включая восстановление разреженных файлов.
• поддержка чтения/записи формата POSIX.1-2001 (pax).
• обрабатывает каталоги, обычные файлы, жёсткие ссылки, символические ссылки, FIFO, символьные и блочные устройства и может получить и восстановить информацию о файлах, такие как метка времени, права доступа и владелец.

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

Возвращает объект TarFile для пути name. Для подробной информации об объектах TarFile и допустимых ключевых аргументах см. Объекты TarFile.

mode должен быть строкой вида 'filemode[:compression]', по умолчанию 'r'. Вот полный список комбинаций режимов:

mode	действие
'r' or 'r:*'	Открытие для чтения с прозрачным сжатием (рекомендуется).
'r:'	Открытие для чтения только без сжатия.
'r:gz'	Открытие для чтения со сжатием gzip.
'r:bz2'	Открытие для чтения со сжатием bzip2.
'r:xz'	Открытие для чтения со сжатием lzma.
'x' или 'x:'	Создание архива tar только без сжатия. Вызывает исключение FileExistsError, если файл уже существует.
'x:gz'	Создание архива tar со сжатием gzip. Вызывает исключение FileExistsError, если файл уже существует.
'x:bz2'	Создание архива tar со сжатием bzip2. Вызывает исключение FileExistsError, если файл уже существует.
'x:xz'	Создание архива tar со сжатием lzma. Вызывает исключение FileExistsError, если файл уже существует.
'a' or 'a:'	Открытие для добавления без сжатия. Файл создаётся, если он не существует.
'w' or 'w:'	Открытие для записи без сжатия.
'w:gz'	Открытие для записи со сжатием gzip.
'w:bz2'	Открытие для записи со сжатием bzip2.
'w:xz'	Открытие для записи со сжатием lzma.

Обратите внимание, что 'a:gz', 'a:bz2' или 'a:xz' невозможны. Если mode не подходит для открытия определённого (сжатого) файла на чтение, возникает исключение ReadError. Используйте mode 'r' чтобы избежать этого. Если метод сжатия не поддерживается, возникает исключение CompressionError.

Если указан fileobj, он используется как альтернатива объекту файла, открытому в двоичном режиме для name. Предполагается, что он находится в позиции 0.

Для режимов 'w:gz', 'r:gz', 'w:bz2', 'r:bz2', 'x:gz', 'x:bz2', tarfile.open() принимает ключевой аргумент compresslevel (по умолчанию 9) для указания уровня сжатия файла.

Для особых целей существует второй формат для mode: 'filemode|[compression]'. tarfile.open() вернёт объект TarFile, который обрабатывает данные как поток блоков. Случайный поиск по файлу не будет осуществляться. Если указан, fileobj может быть любым объектом, имеющим метод read() или write() (в зависимости от mode). bufsize задаёт размер блока и по умолчанию равен 20 * 512 байтам. Используйте этот вариант в сочетании с, например, sys.stdin, объектом сокета или устройством ленты. Однако такой объект TarFile ограничен тем, что не позволяет случайный доступ, см. Примеры. Доступные в настоящее время режимы:

Режим	Действие
'r|*'	Открытие потока блоков tar для чтения с прозрачным сжатием.
'r|'	Открытие потока нескомпрессированных блоков tar для чтения.
'r|gz'	Открытие сжатого gzip потока для чтения.
'r|bz2'	Открытие сжатого bzip2 потока для чтения.
'r|xz'	Открытие сжатого lzma потока для чтения.
'w|'	Открытие нескомпрессированного потока для записи.
'w|gz'	Открытие сжатого gzip потока для записи.
'w|bz2'	Открытие сжатого bzip2 потока для записи.
'w|xz'	Открытие сжатого lzma потока для записи.

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

class tarfile.TarFile

Класс для чтения и записи архивов tar. Не используйте этот класс напрямую: используйте tarfile.open() вместо него. См. Объекты TarFile.

tarfile.is_tarfile(name)

Возвращает True, если name является архивом tar, который модуль tarfile может прочитать.

Модуль tarfile определяет следующие исключения:

exception tarfile.TarError

Базовый класс для всех исключений модуля tarfile.

exception tarfile.ReadError

Возникает, когда архив tar открывается, но не может быть обработан модулем tarfile или по какой-то причине является некорректным.

exception tarfile.CompressionError

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

exception tarfile.StreamError

Возникает для ограничений, характерных для объектов TarFile потокового типа.

exception tarfile.ExtractError

Возникает для некритичных ошибок при использовании TarFile.extract(), но только если TarFile.errorlevel== 2.

exception tarfile.HeaderError

Возникает в TarInfo.frombuf(), если полученный буфер некорректен.

Следующие константы доступны на уровне модуля:

tarfile.ENCODING

По умолчанию кодировка символов: 'utf-8' в Windows, иначе значение, возвращаемое sys.getfilesystemencoding().

Каждая из следующих констант определяет формат архива tar, который может создавать модуль tarfile. Подробности см. в разделе Поддерживаемые форматы tar.

tarfile.USTAR_FORMAT

Формат POSIX.1-1988 (ustar).

tarfile.GNU_FORMAT

Формат GNU tar.

tarfile.PAX_FORMAT

Формат POSIX.1-2001 (pax).

tarfile.DEFAULT_FORMAT

Формат по умолчанию для создания архивов. В настоящее время это GNU_FORMAT.

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

Изменено в версии 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. Атрибуты файла (владелец, время последнего изменения, режим) устанавливаются, если 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.

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

3. Интерфейс командной строки

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

3.1. Опции командной строки

-l <tarfile>

--list <tarfile>

Список файлов в архиве tar.

-c <tarfile> <source1> ... <sourceN>

--create <tarfile> <source1> ... <sourceN>

Создание архива tar из исходных файлов.

-e <tarfile> [<output_dir>]

--extract <tarfile> [<output_dir>]

Извлечение архива tar в текущий каталог, если output_dir не указан.

-t <tarfile>

--test <tarfile>

Проверка на валидность архива tar.

-v, --verbose

Подробный вывод.

4. Примеры

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

5. Поддерживаемые форматы tar

Модуль tarfile поддерживает три формата tar:

• Формат 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 символами.
• Расширенный формат tar SunOS. Этот формат является вариантом формата pax POSIX.1-2001, но не совместим.

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