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

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

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

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

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

• поддержка чтения/записи формата POSIX.1-2001 (pax).

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

• обрабатывает каталоги, обычные файлы, жёсткие ссылки, символические ссылки, fifo, символьные и блочные устройства и может получить и восстановить информацию о файлах, такие как метка времени, разрешения доступа и владелец.

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

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

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

режим	действие
'r' or 'r:*'	Открытие для чтения со сжатием (рекомендуется).
'r:'	Открытие для чтения без сжатия.
'r:gz'	Открытие для чтения со сжатием gzip.
'r:bz2'	Открытие для чтения со сжатием bzip2.
'a' or 'a:'	Открытие для добавления без сжатия. Файл создается, если он не существует.
'w' or 'w:'	Открытие для записи без сжатия.
'w:gz'	Открытие для записи со сжатием gzip.
'w:bz2'	Открытие для записи со сжатием bzip2.

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

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

Для режимов 'w:gz', 'r:gz', 'w:bz2', 'r: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 поток для чтения.
'w|'	Открыть несжатый поток для записи.
'w|gz'	Открыть сжатый gzip поток для записи.
'w|bz2'	Открыть сжатый bzip2 поток для записи.

class tarfile.TarFile

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

tarfile.is_tarfile(name)

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

class tarfile.TarFileCompat(filename, mode='r', compression=TAR_PLAIN)

Класс для ограниченного доступа к архивам tar с интерфейсом, подобным zipfile. Для получения более подробной информации обратитесь к документации модуля zipfile. compression должен быть одним из следующих констант:

TAR_PLAIN

Константа для несжатого архива tar.

TAR_GZIPPED

Константа для архива tar, сжатого с помощью gzip.

Устарел начиная с версии 2.6: Класс TarFileCompat был удален в Python 3.

exception tarfile.TarError

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

exception tarfile.ReadError

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

exception tarfile.CompressionError

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

exception tarfile.StreamError

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

exception tarfile.ExtractError

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

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

tarfile.ENCODING

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

exception tarfile.HeaderError

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

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

Каждый из следующих констант определяет формат архива 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=None, pax_headers=None, debug=0, errorlevel=0)

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

name — путь к файлу архива. Он может быть опущен, если задан fileobj. В этом случае используется атрибут fileobj файла, если он существует.

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, все ошибки fatal поднимаются как исключения OSError или IOError. Если 2, все non-fatal ошибки также поднимаются как исключения 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.

2. Объекты TarInfo

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

3. Примеры

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

4. Поддерживаемые форматы 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, хранящий только обычные файлы и каталоги. Имена не должны быть длиннее 100 символов, информация о имени пользователя/группы отсутствует. Некоторые архивы имеют неправильно рассчитанные контрольные суммы заголовков в случае полей с символами, не являющимися ASCII.
• Расширенный формат tar SunOS. Этот формат является вариантом формата pax POSIX.1-2001, но не совместим.

5. Проблемы с Unicode

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