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

Изменено в версии 3.6: Параметр name принимает объект-путь.

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.

Объекты 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 может быть объектом-путь. Он может быть опущен, если задан fileobj. В этом случае используется атрибут mode объекта fileobj, если он существует.

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

Изменено в версии 3.6: Параметр name принимает объект-путь.

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 из архива используются для установки владельца/группы для извлечённых файлов. В противном случае используются именованные значения из архива.

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

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

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

Изменено в версии 3.6: Параметр path принимает объект пути.

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

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

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

Примечание

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

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

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

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

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

Изменено в версии 3.6: Параметр path принимает объект пути.

TarFile.extractfile(member)

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

Изменено в версии 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: Добавлен параметр filter.

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

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 с дескриптором файла. name может быть объектом пути. Если задано, arcname задаёт альтернативное имя файла в архиве, в противном случае имя берётся из атрибута name объекта fileobj или аргумента name. Имя должно быть строкой.

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

Изменено в версии 3.6: Параметр name принимает объект пути.

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 предоставляет простой интерфейс командной строки для взаимодействия с тар-архивами.

Если вы хотите создать новый тар-архив, укажите его имя после опции -c, а затем перечислите имена файлов, которые должны быть включены:

$ python -m tarfile -c monty.tar  spam.txt eggs.txt

Также допустимо передать каталог:

$ python -m tarfile -c monty.tar life-of-brian_1979/

Если вы хотите извлечь тар-архив в текущий каталог, используйте опцию -e:

$ python -m tarfile -e monty.tar

Вы также можете извлечь тар-архив в другой каталог, передав имя каталога:

$ python -m tarfile -e monty.tar  other-dir/

Для получения списка файлов в тар-архиве используйте опцию -l:

$ python -m tarfile -l monty.tar

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

-l <tarfile>

--list <tarfile>

Список файлов в тар-файле.

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

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

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

-e <tarfile> [<output_dir>]

--extract <tarfile> [<output_dir>]

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

-t <tarfile>

--test <tarfile>

Проверка, является ли тар-файл валидным.

-v, --verbose

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

Примеры

Как извлечь весь тар-архив в текущий рабочий каталог:

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall()
tar.close()

Как извлечь подмножество тар-архива с помощью 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()

Как создать неархивированный тар-архив из списка имён файлов:

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-сжатый тар-архив и отобразить информацию о некоторых членах:

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:

• Формат 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, но не совместим с ним.

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