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.

13.6.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 — путь к архиву. name может быть объектом пути. Его можно опустить, если задан fileobj. В этом случае используется атрибут fileobj’s name если он существует.

mode может принимать значения: 'r' для чтения из существующего архива, 'a' для добавления данных в существующий файл, 'w' для создания нового файла, перезаписывая существующий, или 'x' для создания нового файла только если он не существует.

Если задан fileobj, он используется для чтения или записи данных. Если это возможно, mode переопределяется по fileobj’s mode. 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 из tar-файла используются для установки владельца/группы для извлеченных файлов. В противном случае используются именованные значения из tar-файла.

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

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

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

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

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

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

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

Примечание

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

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

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

TarFile.close()

Закрыть TarFile. В режиме записи в архив добавляются два завершающих нулевых блока.

TarFile.pax_headers

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

13.6.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.

13.6.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

13.6.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

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

13.6.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()

13.6.5. Поддерживаемые форматы 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 сегодня могут правильно обрабатывать архивы 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

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