# `tarfile` — Read and write tar archive files

Вихідний код: Lib/tarfile.py

Модуль `tarfile` дає змогу читати та записувати архіви tar, у тому числі ті, що використовують стиснення gzip, bz2 та lzma. Використовуйте модуль `zipfile` для читання або запису файлів `.zip` або функції вищого рівня в shutil.

Деякі факти та цифри:

- reads and writes `gzip`, `bz2`, `compression.zstd`, and `lzma` compressed archives if the respective modules are available.

- підтримка читання/запису для формату POSIX.1-1988 (ustar).

- підтримка читання/запису для формату GNU tar, включаючи розширення longname і longlink, підтримка лише читання для всіх варіантів розширення sparse, включаючи відновлення розріджених файлів.

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

- обробляє каталоги, звичайні файли, жорсткі посилання, символічні посилання, FIFO, символьні пристрої та блокові пристрої, а також може отримувати та відновлювати інформацію про файл, як-от мітку часу, права доступу та власника.

Змінено в версії 3.3: Додано підтримку стиснення `lzma`.

Змінено в версії 3.12: Archives are extracted using a filter, which makes it possible to either limit surprising/dangerous features, or to acknowledge that they are expected and the archive is fully trusted.

Змінено в версії 3.14: Set the default extraction filter to `data`, which disallows some dangerous features such as links to absolute paths or paths outside of the destination. Previously, the filter strategy was equivalent to `fully_trusted`.

Змінено в версії 3.14: Added support for Zstandard compression using `compression.zstd`.

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.
  `'r:xz''` | Відкритий для читання зі стисненням lzma.
  `'r:zst'` | Open for reading with Zstandard compression.
  `'x''` або `'x:''` | Create a tarfile exclusively without compression. Raise a `FileExistsError` exception if it already exists.
  `'x:gz''` | Create a tarfile with gzip compression. Raise a `FileExistsError` exception if it already exists.
  `'x:bz2''` | Create a tarfile with bzip2 compression. Raise a `FileExistsError` exception if it already exists.
  `'x:xz''` | Create a tarfile with lzma compression. Raise a `FileExistsError` exception if it already exists.
  `'x:zst'` | Create a tarfile with Zstandard compression. Raise a `FileExistsError` exception if it already exists.
  `'a'` or `'a:'` | Відкритий для додавання без стиснення. Файл створюється, якщо він не існує.
  `'w'` or `'w:'` | Відкритий для запису без стиснення.
  `'w:gz''` | Відкритий для стисненого запису gzip.
  `'w:bz2''` | Відкритий для стисненого запису bzip2.
  `'w:xz''` | Відкритий для стисненого запису lzma.
  `'w:zst'` | Open for Zstandard compressed writing.

  Зауважте, що `'a:gz'`, `'a:bz2'` або `'a:xz'` неможливі. Якщо режим не підходить для відкриття певного (стислого) файлу для читання, виникає `ReadError`. Щоб уникнути цього, використовуйте mode `'r'`. Якщо метод стиснення не підтримується, виникає `CompressionError`.

  Якщо вказано fileobj, він використовується як альтернатива file object, відкритому в двійковому режимі для name. Він має бути в позиції 0.

  For modes `'w:gz'`, `'x:gz'`, `'w|gz'`, `'w:bz2'`, `'x:bz2'`, `'w|bz2'`, `tarfile.open()` accepts the keyword argument compresslevel (default `9`) to specify the compression level of the file.

  For modes `'w:xz'`, `'x:xz'` and `'w|xz'`, `tarfile.open()` accepts the keyword argument preset to specify the compression level of the file.

  For modes `'w:zst'`, `'x:zst'` and `'w|zst'`, `tarfile.open()` accepts the keyword argument level to specify the compression level of the file. The keyword argument options may also be passed, providing advanced Zstandard compression parameters described by `CompressionParameter`. The keyword argument zstd_dict can be passed to provide a `ZstdDict`, a Zstandard dictionary used to improve compression of smaller amounts of data.

  For special purposes, there is a second format for mode: `'filemode|[compression]'`. `tarfile.open()` will return a `TarFile` object that processes its data as a stream of blocks. No random seeking will be done on the file. If given, fileobj may be any object that has a `read()` or `write()` method (depending on the mode) that works with bytes. bufsize specifies the blocksize and defaults to `20 * 512` bytes. Use this variant in combination with e.g. `sys.stdin.buffer`, a socket file object or a tape device. However, such a `TarFile` object is limited in that it does not allow random access, see Приклади. The currently possible modes:

  Режим | Дія
  --- | ---
  `'r|*'` | Відкрийте потік блоків tar для читання з прозорим стисненням.
  `'r|''` | Відкрийте потік нестиснутих блоків tar для читання.
  `'r|gz''` | Відкрийте потік, стиснутий gzip, для читання.
  `'r|bz2''` | Відкрийте потік, стиснений bzip2, для читання.
  `'r|xz''` | Відкрийте стислий потік lzma для читання.
  `'r|zst'` | Open a Zstandard compressed stream for reading.
  `'w|''` | Відкрийте нестиснений потік для запису.
  `'w|gz''` | Відкрийте стиснутий потік gzip для запису.
  `'w|bz2''` | Відкрийте потік, стиснений bzip2, для запису.
  `'w|xz''` | Відкрийте стислий потік lzma для запису.
  `'w|zst'` | Open a Zstandard compressed stream for writing.

  Змінено в версії 3.5: Додано режим `'x` (ексклюзивне створення).

  Змінено в версії 3.6: Параметр name приймає path-like object.

  Змінено в версії 3.12: The compresslevel keyword argument also works for streams.

  Змінено в версії 3.14: The preset keyword argument also works for streams.

class tarfile.TarFile

  Клас для читання та запису архівів tar. Не використовуйте цей клас безпосередньо: використовуйте замість нього `tarfile.open()`. Див. Об’єкти TarFile.

tarfile.is_tarfile(name)

  Повертає `True`, якщо name є архівним файлом tar, який може прочитати модуль `tarfile`. name може бути `str`, файлом або файлоподібним об’єктом.

  Змінено в версії 3.9: Підтримка файлів і файлоподібних об’єктів.

Модуль `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()`, якщо отриманий буфер недійсний.

exception tarfile.FilterError

  Base class for members refused by filters.

  tarinfo

    Information about the member that the filter refused to extract, as TarInfo.

exception tarfile.AbsolutePathError

  Raised to refuse extracting a member with an absolute path.

exception tarfile.OutsideDestinationError

  Raised to refuse extracting a member outside the destination directory.

exception tarfile.SpecialFileError

  Raised to refuse extracting a special file (e.g. a device or pipe).

exception tarfile.AbsoluteLinkError

  Raised to refuse extracting a symbolic link with an absolute path.

exception tarfile.LinkOutsideDestinationError

  Raised to refuse extracting a symbolic link pointing outside the destination directory.

exception tarfile.LinkFallbackError

  Raised to refuse emulating a link (hard or symbolic) by extracting another archive member, when that member would be rejected by the filter location. The exception that was raised to reject the replacement member is available as `BaseException.__context__`.

  Added in version 3.14.

Наступні константи доступні на рівні модуля:

tarfile.ENCODING

  Кодування символів за замовчуванням: `'utf-8'` у Windows, значення повертає `sys.getfilesystemencoding()` в інших випадках.

tarfile.REGTYPE
tarfile.AREGTYPE

  A regular file `type`.

tarfile.LNKTYPE

  A link (inside tarfile) `type`.

tarfile.SYMTYPE

  A symbolic link `type`.

tarfile.CHRTYPE

  A character special device `type`.

tarfile.BLKTYPE

  A block special device `type`.

tarfile.DIRTYPE

  A directory `type`.

tarfile.FIFOTYPE

  A FIFO special device `type`.

tarfile.CONTTYPE

  A contiguous file `type`.

tarfile.GNUTYPE_LONGNAME

  A GNU tar longname `type`.

tarfile.GNUTYPE_LONGLINK

  A GNU tar longlink `type`.

tarfile.GNUTYPE_SPARSE

  A GNU tar sparse file `type`.

Кожна з наступних констант визначає формат архіву 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

  Стандартний формат для створення архівів. Зараз це `PAX_FORMAT`.

  Змінено в версії 3.8: Стандартний формат для нових архівів було змінено на `PAX_FORMAT` з `GNU_FORMAT`.

Дивись також

Модуль `zipfile`

  Документація стандартного модуля `zipfile`.

Архівні операції

  Документація засобів архівування вищого рівня, які надає стандартний модуль `shutil`.

Посібник GNU tar, базовий формат Tar

  Документація для архівних файлів tar, включаючи розширення GNU tar.

## Об’єкти TarFile

Об’єкт `TarFile` надає інтерфейс до архіву tar. Архів tar — це послідовність блоків. Член архіву (збережений файл) складається з блоку заголовка, за яким слідують блоки даних. Можна зберігати файл в архіві tar кілька разів. Кожен член архіву представлений об’єктом `TarInfo`, подробиці див. у Об’єкти TarInfo.

Об’єкт `TarFile` можна використовувати як менеджер контексту в операторі `with`. Він автоматично закриється, коли блок буде завершено. Зверніть увагу, що у випадку винятку архів, відкритий для запису, не буде завершено; буде закрито лише внутрішньо використовуваний файловий об’єкт. Перегляньте розділ Приклади для прикладу використання.

Added in version 3.2: Додано підтримку протоколу керування контекстом.

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=1, stream=False)

  Усі наступні аргументи є необов’язковими, і до них також можна отримати доступ як до атрибутів екземпляра.

  name is the pathname of the archive. name may be a path-like object. It can be omitted if fileobj is given. In this case, the file object’s `name` attribute is used if it exists.

  режим — це або `'r'` для читання з існуючого архіву, `'a'` для додавання даних до існуючого файлу, `'w'` для створення нового файлу, перезаписуючого існуючий , або `'x''`, щоб створити новий файл, лише якщо він ще не існує.

  Якщо вказано fileobj, він використовується для читання або запису даних. Якщо це можна визначити, mode замінюється режимом fileobj. fileobj використовуватиметься з позиції 0.

  Примітка

  fileobj не закривається, коли `TarFile` закрито.

  format контролює формат архіву для запису. Це має бути одна з констант `USTAR_FORMAT`, `GNU_FORMAT` або `PAX_FORMAT`, визначених на рівні модуля. Під час читання формат буде автоматично визначено, навіть якщо в одному архіві присутні різні формати.

  Аргумент tarinfo можна використати для заміни стандартного класу `TarInfo` на інший.

  Якщо розіменування має значення `False`, додайте символічні та жорсткі посилання до архіву. Якщо це `True`, додайте вміст цільових файлів до архіву. Це не впливає на системи, які не підтримують символічні посилання.

  Якщо ignore_zeros дорівнює `False`, розглядайте порожній блок як кінець архіву. Якщо це `True`, пропускайте порожні (і недійсні) блоки та намагайтеся отримати якомога більше учасників. Це корисно лише для читання об’єднаних або пошкоджених архівів.

  debug можна встановити від `0` (без повідомлень налагодження) до `3` (усі повідомлення налагодження). Повідомлення записуються в `sys.stderr`.

  errorlevel controls how extraction errors are handled, see `the corresponding attribute`.

  Аргументи encoding і errors визначають кодування символів, яке буде використовуватися для читання або запису архіву, і спосіб обробки помилок перетворення. Налаштування за замовчуванням працюватимуть для більшості користувачів. Дивіться розділ Проблеми з Unicode для отримання детальної інформації.

  Аргумент pax_headers — це необов’язковий словник рядків, який буде додано як глобальний заголовок pax, якщо format має значення `PAX_FORMAT`.

  If stream is set to `True` then while reading the archive info about files in the archive are not cached, saving memory.

  Змінено в версії 3.2: Використовуйте `'surrogateescape'` як типове значення для аргументу errors.

  Змінено в версії 3.5: Додано режим `'x` (ексклюзивне створення).

  Змінено в версії 3.6: Параметр name приймає path-like object.

  Змінено в версії 3.13: Add the stream parameter.

classmethod TarFile.open(...)

  Альтернативний конструктор. Функція `tarfile.open()` насправді є ярликом цього методу класу.

TarFile.getmember(name)

  Повертає об’єкт `TarInfo` для ім’я члена. Якщо name не вдається знайти в архіві, виникає `KeyError`.

  Примітка

  Якщо член зустрічається в архіві більше одного разу, вважається, що його остання зустріч є найновішою версією.

TarFile.getmembers()

  Повернути членів архіву як список об’єктів `TarInfo`. Список має той самий порядок, що й учасники в архіві.

TarFile.getnames()

  Повернути учасників у вигляді списку їхніх імен. Він має той самий порядок, що й список, який повертає `getmembers()`.

TarFile.list(verbose=True, *, members=None)

  Надрукуйте зміст у `sys.stdout`. Якщо verbose має значення `False`, друкуються лише імена учасників. Якщо це `True`, буде створено вихід, схожий на той, який виконує ls -l. Якщо вказано необов’язковий members, він має бути підмножиною списку, який повертає `getmembers()`.

  Змінено в версії 3.5: Додано параметр члени.

TarFile.next()

  Повертає наступний елемент архіву як об’єкт `TarInfo`, коли `TarFile` відкрито для читання. Повернути `None`, якщо більше немає доступних.

TarFile.extractall(path='.', members=None, *, numeric_owner=False, filter=None)

  Витягніть усі члени з архіву в поточний робочий каталог або шлях до каталогу. Якщо вказано необов’язковий members, він має бути підмножиною списку, який повертає `getmembers()`. Інформація про каталог, як-от власник, час зміни та дозволи, встановлюється після вилучення всіх учасників. Це зроблено, щоб вирішити дві проблеми: Час модифікації каталогу скидається кожного разу, коли в ньому створюється файл. І якщо дозволи каталогу не дозволяють записувати, видобути файли в нього не вдасться.

  Якщо numeric_owner має значення `True`, номери uid і gid з tar-файлу використовуються для встановлення власника/групи для вилучених файлів. В іншому випадку використовуються іменовані значення з tarfile.

  The filter argument specifies how `members` are modified or rejected before extraction. See Extraction filters for details. It is recommended to set this explicitly only if specific tar features are required, or as `filter='data'` to support Python versions with a less secure default (3.13 and lower).

  Попередження

  Never extract archives from untrusted sources without prior inspection.

  Since Python 3.14, the default (`data`) will prevent the most dangerous security issues. However, it will not prevent all unintended or insecure behavior. Read the Extraction filters section for details.

  Змінено в версії 3.5: Додано параметр numeric_owner.

  Змінено в версії 3.6: Параметр path приймає path-like object.

  Змінено в версії 3.12: Додано параметр фільтр.

  Змінено в версії 3.14: The filter parameter now defaults to `'data'`.

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

  Розпакуйте учасника з архіву в поточний робочий каталог, використовуючи його повне ім’я. Інформація про його файл витягується якомога точніше. member може бути назвою файлу або об’єктом `TarInfo`. Ви можете вказати інший каталог за допомогою шляху. path може бути path-like object. Атрибути файлу (власник, mtime, режим) встановлено, якщо set_attrs не має значення false.

  The numeric_owner and filter arguments are the same as for `extractall()`.

  Примітка

  Метод `extract()` не вирішує деякі проблеми вилучення. У більшості випадків вам слід розглянути можливість використання методу `extractall()`.

  Попередження

  Never extract archives from untrusted sources without prior inspection. See the warning for `extractall()` for details.

  Змінено в версії 3.2: Додано параметр set_attrs.

  Змінено в версії 3.5: Додано параметр numeric_owner.

  Змінено в версії 3.6: Параметр path приймає path-like object.

  Змінено в версії 3.12: Додано параметр фільтр.

TarFile.extractfile(member)

  Витягти член з архіву як файловий об’єкт. member може бути назвою файлу або об’єктом `TarInfo`. Якщо member є звичайним файлом або посиланням, повертається об’єкт `io.BufferedReader`. Для всіх інших існуючих учасників повертається `None`. Якщо member не відображається в архіві, виникає `KeyError`.

  Змінено в версії 3.3: Повертає об’єкт `io.BufferedReader`.

  Змінено в версії 3.13: The returned `io.BufferedReader` object has the `mode` attribute which is always equal to `'rb'`.

TarFile.errorlevel: int

  If errorlevel is `0`, errors are ignored when using `TarFile.extract()` and `TarFile.extractall()`. Nevertheless, they appear as error messages in the debug output when debug is greater than 0. If `1` (the default), all fatal errors are raised as `OSError` or `FilterError` exceptions. If `2`, all non-fatal errors are raised as `TarError` exceptions as well.

  Some exceptions, e.g. ones caused by wrong argument types or data corruption, are always raised.

  Custom extraction filters should raise `FilterError` for fatal errors and `ExtractError` for non-fatal ones.

  Note that when an exception is raised, the archive may be partially extracted. It is the user’s responsibility to clean up.

TarFile.extraction_filter

  Added in version 3.12.

  The extraction filter used as a default for the filter argument of `extract()` and `extractall()`.

  The attribute may be `None` or a callable. String names are not allowed for this attribute, unlike the filter argument to `extract()`.

  If `extraction_filter` is `None` (the default), extraction methods will use the `data` filter by default.

  The attribute may be set on instances or overridden in subclasses. It also is possible to set it on the `TarFile` class itself to set a global default, although, since it affects all uses of tarfile, it is best practice to only do so in top-level applications or `site configuration`. To set a global default this way, a filter function needs to be wrapped in `staticmethod()` to prevent injection of a `self` argument.

  Змінено в версії 3.14: The default filter is set to `data`, which disallows some dangerous features such as links to absolute paths or paths outside of the destination. Previously, the default was equivalent to `fully_trusted`.

TarFile.add(name, arcname=None, recursive=True, *, filter=None)

  Додайте ім’я файлу в архів. ім’я може бути будь-яким типом файлу (каталог, FIFO, символьне посилання тощо). Якщо задано, arcname визначає альтернативне ім’я для файлу в архіві. За замовчуванням каталоги додаються рекурсивно. Цього можна уникнути, встановивши recursive на `False`. Рекурсія додає записи у відсортованому порядку. Якщо вказано фільтр, це має бути функція, яка приймає аргумент об’єкта `TarInfo` і повертає змінений об’єкт `TarInfo`. Якщо замість цього він повертає `None`, об’єкт `TarInfo` буде виключено з архіву. Перегляньте Приклади для прикладу.

  Змінено в версії 3.2: Додано параметр фільтр.

  Змінено в версії 3.7: Рекурсія додає записи у відсортованому порядку.

TarFile.addfile(tarinfo, fileobj=None)

  Add the `TarInfo` object tarinfo to the archive. If tarinfo represents a non zero-size regular file, the fileobj argument should be a binary file, and `tarinfo.size` bytes are read from it and added to the archive. You can create `TarInfo` objects directly, or by using `gettarinfo()`.

  Змінено в версії 3.13: fileobj must be given for non-zero-sized regular files.

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

  Створіть об’єкт `TarInfo` з результату `os.stat()` або еквівалентного в існуючому файлі. Файл або має назву name, або вказується як file object fileobj з дескриптором файлу. name може бути path-like object. Якщо задано, arcname визначає альтернативне ім’я для файлу в архіві, інакше ім’я береться з атрибута fileobj `name` або аргументу name. Назва має бути текстовим рядком.

  Ви можете змінити деякі атрибути `TarInfo` перед тим, як додати його за допомогою `addfile()`. Якщо файловий об’єкт не є звичайним файловим об’єктом, розміщеним на початку файлу, можливо, потрібно буде змінити атрибути, такі як `size`. Це стосується таких об’єктів, як `GzipFile`. `name` також можна змінити, у цьому випадку arcname може бути фіктивним рядком.

  Змінено в версії 3.6: Параметр name приймає path-like object.

TarFile.close()

  Закрийте `TarFile`. У режимі запису до архіву додаються два завершальних нульових блоки.

TarFile.pax_headers: dict

  Словник, що містить пари ключ-значення глобальних заголовків pax.

## Об’єкти TarInfo

Об’єкт `TarInfo` представляє один член у `TarFile`. Окрім зберігання всіх необхідних атрибутів файлу (наприклад, типу файлу, розміру, часу, дозволів, власника тощо), він надає деякі корисні методи визначення його типу. Він не містить дані самого файлу.

`TarInfo` objects are returned by `TarFile`’s methods `getmember()`, `getmembers()` and `gettarinfo()`.

Modifying the objects returned by `getmember()` or `getmembers()` will affect all subsequent operations on the archive. For cases where this is unwanted, you can use `copy.copy()` or call the `replace()` method to create a modified copy in one step.

Several attributes can be set to `None` to indicate that a piece of metadata is unused or unknown. Different `TarInfo` methods handle `None` differently:

- The `extract()` or `extractall()` methods will ignore the corresponding metadata, leaving it set to a default.

- `addfile()` will fail.

- `list()` will print a placeholder string.

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: str

  ПІБ учасника архіву.

TarInfo.size: int

  Розмір у байтах.

TarInfo.mtime: int | float

  Time of last modification in seconds since the epoch, as in `os.stat_result.st_mtime`.

  Змінено в версії 3.12: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

TarInfo.mode: int

  Permission bits, as for `os.chmod()`.

  Змінено в версії 3.12: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

TarInfo.type

  Тип файлу. type зазвичай є однією з таких констант: `REGTYPE`, `AREGTYPE`, `LNKTYPE`, `SYMTYPE`, `DIRTYPE`, `FIFOTYPE`, `CONTTYPE`, `CHRTYPE`, `BLKTYPE`, `GNUTYPE_SPARSE`. Щоб зручніше визначити тип об’єкта `TarInfo`, скористайтеся наведеними нижче методами `is*()`.

TarInfo.linkname: str

  Ім’я імені цільового файлу, яке присутнє лише в об’єктах `TarInfo` типу `LNKTYPE` і `SYMTYPE`.

  For symbolic links (`SYMTYPE`), the linkname is relative to the directory that contains the link. For hard links (`LNKTYPE`), the linkname is relative to the root of the archive.

TarInfo.uid: int

  Ідентифікатор користувача, який спочатку зберіг цього учасника.

  Змінено в версії 3.12: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

TarInfo.gid: int

  Ідентифікатор групи користувача, який спочатку зберіг цього учасника.

  Змінено в версії 3.12: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

TarInfo.uname: str

  Ім’я користувача.

  Змінено в версії 3.12: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

TarInfo.gname: str

  Назва групи.

  Змінено в версії 3.12: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

TarInfo.chksum: int

  Header checksum.

TarInfo.devmajor: int

  Device major number.

TarInfo.devminor: int

  Device minor number.

TarInfo.offset: int

  The tar header starts here.

TarInfo.offset_data: int

  The file’s data starts here.

TarInfo.sparse

  Sparse member information.

TarInfo.pax_headers: dict

  Словник, що містить пари ключ-значення пов’язаного розширеного заголовка pax.

TarInfo.replace(name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)

  Added in version 3.12.

  Return a new copy of the `TarInfo` object with the given attributes changed. For example, to return a `TarInfo` with the group name set to `'staff'`, use:

      new_tarinfo = old_tarinfo.replace(gname='staff')

  By default, a deep copy is made. If deep is false, the copy is shallow, i.e. `pax_headers` and any custom attributes are shared with the original `TarInfo` object.

Об’єкт `TarInfo` також надає деякі зручні методи запиту:

TarInfo.isfile()

  Return `True` if the `TarInfo` object is a regular file.

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.

## Extraction filters

Added in version 3.12.

The tar format is designed to capture all details of a UNIX-like filesystem, which makes it very powerful. Unfortunately, the features make it easy to create tar files that have unintended – and possibly malicious – effects when extracted. For example, extracting a tar file can overwrite arbitrary files in various ways (e.g. by using absolute paths, `..` path components, or symlinks that affect later members).

In most cases, the full functionality is not needed. Therefore, tarfile supports extraction filters: a mechanism to limit functionality, and thus mitigate some of the security issues.

Попередження

None of the available filters blocks all dangerous archive features. Never extract archives from untrusted sources without prior inspection. See also Hints for further verification.

Дивись також

PEP 706

  Contains further motivation and rationale behind the design.

The filter argument to `TarFile.extract()` or `extractall()` can be:

- the string `'fully_trusted'`: Honor all metadata as specified in the archive. Should be used if the user trusts the archive completely, or implements their own complex verification.

- the string `'tar'`: Honor most tar-specific features (i.e. features of UNIX-like filesystems), but block features that are very likely to be surprising or malicious. See `tar_filter()` for details.

- the string `'data'`: Ignore or block most features specific to UNIX-like filesystems. Intended for extracting cross-platform data archives. See `data_filter()` for details.

- `None` (default): Use `TarFile.extraction_filter`.

  If that is also `None` (the default), the `'data'` filter will be used.

  > Змінено в версії 3.14: The default filter is set to `data`. Previously, the default was equivalent to `fully_trusted`.

- A callable which will be called for each extracted member with a TarInfo describing the member and the destination path to where the archive is extracted (i.e. the same path is used for all members):

      filter(member: TarInfo, path: str, /) -> TarInfo | None

  The callable is called just before each member is extracted, so it can take the current state of the disk into account. It can:

  - return a `TarInfo` object which will be used instead of the metadata in the archive, or

  - return `None`, in which case the member will be skipped, or

  - raise an exception to abort the operation or skip the member, depending on `errorlevel`. Note that when extraction is aborted, `extractall()` may leave the archive partially extracted. It does not attempt to clean up.

### Default named filters

The pre-defined, named filters are available as functions, so they can be reused in custom filters:

tarfile.fully_trusted_filter(member, path)

  Return member unchanged.

  This implements the `'fully_trusted'` filter.

tarfile.tar_filter(member, path)

  Implements the `'tar'` filter.

  - Strip leading slashes (`/` and `os.sep`) from filenames.

  - Refuse to extract files with absolute paths (in case the name is absolute even after stripping slashes, e.g. `C:/foo` on Windows). This raises `AbsolutePathError`.

  - Refuse to extract files whose absolute path (after following symlinks) would end up outside the destination. This raises `OutsideDestinationError`.

  - Clear high mode bits (setuid, setgid, sticky) and group/other write bits (`S_IWGRP` | `S_IWOTH`).

  Return the modified `TarInfo` member.

tarfile.data_filter(member, path)

  Implements the `'data'` filter. In addition to what `tar_filter` does:

  - Normalize link targets (`TarInfo.linkname`) using `os.path.normpath()`. Note that this removes internal `..` components, which may change the meaning of the link if the path in `TarInfo.linkname` traverses symbolic links.

  - Refuse to extract links (hard or soft) that link to absolute paths, or ones that link outside the destination.

    This raises `AbsoluteLinkError` or `LinkOutsideDestinationError`.

    Note that such files are refused even on platforms that do not support symbolic links.

  - Refuse to extract device files (including pipes). This raises `SpecialFileError`.

  - For regular files, including hard links:

    - Set the owner read and write permissions (`S_IRUSR` | `S_IWUSR`).

    - Remove the group & other executable permission (`S_IXGRP` | `S_IXOTH`) if the owner doesn’t have it (`S_IXUSR`).

  - For other files (directories), set `mode` to `None`, so that extraction methods skip applying permission bits.

  - Set user and group info (`uid`, `gid`, `uname`, `gname`) to `None`, so that extraction methods skip setting it.

  Return the modified `TarInfo` member.

  Note that this filter does not block all dangerous archive features. See Hints for further verification for details.

  Змінено в версії 3.14: Link targets are now normalized.

### Filter errors

When a filter refuses to extract a file, it will raise an appropriate exception, a subclass of `FilterError`. This will abort the extraction if `TarFile.errorlevel` is 1 or more. With `errorlevel=0` the error will be logged and the member will be skipped, but extraction will continue.

### Hints for further verification

Even with `filter='data'`, tarfile is not suited for extracting untrusted files without prior inspection. Among other issues, the pre-defined filters do not prevent denial-of-service attacks. Users should do additional checks.

Here is an incomplete list of things to consider:

- Extract to a `new temporary directory` to prevent e.g. exploiting pre-existing links, and to make it easier to clean up after a failed extraction.

- Disallow symbolic links if you do not need the functionality.

- When working with untrusted data, use external (e.g. OS-level) limits on disk, memory and CPU usage.

- Check filenames against an allow-list of characters (to filter out control characters, confusables, foreign path separators, and so on).

- Check that filenames have expected extensions (discouraging files that execute when you “click on them”, or extension-less files like Windows special device names).

- Limit the number of extracted files, total size of extracted data, filename length (including symlink length), and size of individual files.

- Check for files that would be shadowed on case-insensitive filesystems.

Also note that:

- Tar files may contain multiple versions of the same file. Later ones are expected to overwrite any earlier ones. This feature is crucial to allow updating tape archives, but can be abused maliciously.

- tarfile does not protect against issues with “live” data, e.g. an attacker tinkering with the destination (or source) directory while extraction (or archiving) is in progress.

### Supporting older Python versions

Extraction filters were added to Python 3.12, but may be backported to older versions as security updates. To check whether the feature is available, use e.g. `hasattr(tarfile, 'data_filter')` rather than checking the Python version.

The following examples show how to support Python versions with and without the feature. Note that setting `extraction_filter` will affect any subsequent operations.

- Fully trusted archive:

      my_tarfile.extraction_filter = (lambda member, path: member)
      my_tarfile.extractall()

- Use the `'data'` filter if available, but revert to Python 3.11 behavior (`'fully_trusted'`) if this feature is not available:

      my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                             (lambda member, path: member))
      my_tarfile.extractall()

- Use the `'data'` filter; fail if it is not available:

      my_tarfile.extractall(filter=tarfile.data_filter)

  або:

      my_tarfile.extraction_filter = tarfile.data_filter
      my_tarfile.extractall()

- Use the `'data'` filter; warn if it is not available:

      if hasattr(tarfile, 'data_filter'):
          my_tarfile.extractall(filter='data')
      else:
          # remove this when no longer needed
          warn_the_user('Extracting may be unsafe; consider updating Python')
          my_tarfile.extractall()

### Stateful extraction filter example

While tarfile’s extraction methods take a simple filter callable, custom filters may be more complex objects with an internal state. It may be useful to write these as context managers, to be used like this:

    with StatefulFilter() as filter_func:
        tar.extractall(path, filter=filter_func)

Such a filter can be written as, for example:

    class StatefulFilter:
        def __init__(self):
            self.file_count = 0

        def __enter__(self):
            return self

        def __call__(self, member, path):
            self.file_count += 1
            return member

        def __exit__(self, *exc_info):
            print(f'{self.file_count} files extracted')

## Інтерфейс командного рядка

Added in version 3.4.

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

### Параметри командного рядка

-l <tarfile>
--list <tarfile>

  Список файлів у tar-файлі.

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

  Створення tarfile з вихідних файлів.

-e <tarfile> [<output_dir>]
--extract <tarfile> [<output_dir>]

  Розпакуйте tarfile у поточний каталог, якщо output_dir не вказано.

-t <tarfile>
--test <tarfile>

  Перевірте, чи дійсний tarfile чи ні.

-v, --verbose

  Детальний висновок.

--filter <filtername>

  Specifies the filter for `--extract`. See Extraction filters for details. Only string names are accepted (that is, `fully_trusted`, `tar`, and `data`).

## Приклади

### Reading examples

Як розпакувати цілий архів tar до поточного робочого каталогу:

    import tarfile
    tar = tarfile.open("sample.tar.gz")
    tar.extractall(filter='data')
    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, стиснений 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()

### Writing examples

Як створити нестиснений архів 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)

How to create and write an archive to stdout using `sys.stdout.buffer` in the fileobj parameter in `TarFile.add()`:

    import sys
    import tarfile
    with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar:
        for name in ["foo", "bar", "quux"]:
            tar.add(name)

Як створити архів і скинути інформацію про користувача за допомогою параметра filter у `TarFile.add()`:

    import tarfile
    def reset(tarinfo):
        tarinfo.uid = tarinfo.gid = 0
        tarinfo.uname = tarinfo.gname = "root"
        return tarinfo
    tar = tarfile.open("sample.tar.gz", "w:gz")
    tar.add("foo", filter=reset)
    tar.close()

## Підтримувані формати tar

Існує три формати tar, які можна створити за допомогою модуля `tarfile`:

- Формат POSIX.1-1988 ustar (`USTAR_FORMAT`). Він підтримує назви файлів довжиною щонайбільше 256 символів і назви посилань довжиною до 100 символів. Максимальний розмір файлу становить 8 ГіБ. Це старий і обмежений, але широко підтримуваний формат.

- Формат GNU tar (`GNU_FORMAT`). Він підтримує довгі імена файлів та імена посилань, файли розміром понад 8 ГіБ і розріджені файли. Це стандарт де-факто для систем GNU/Linux. `tarfile` повністю підтримує розширення GNU tar для довгих імен, підтримка розріджених файлів доступна лише для читання.

- The POSIX.1-2001 pax format (`PAX_FORMAT`). It is the most flexible format with virtually no limits. It supports long filenames and linknames, large files and stores pathnames in a portable way. Modern tar implementations, including GNU tar, bsdtar/libarchive and star, fully support extended pax features; some old or unmaintained libraries may not, but should treat pax archives as if they were in the universally supported ustar format. It is the current default format for new archives.

  Він розширює існуючий формат ustar додатковими заголовками для інформації, яку неможливо зберегти іншим способом. Є два варіанти заголовків pax: розширені заголовки впливають лише на наступний заголовок файлу, глобальні заголовки дійсні для всього архіву та впливають на всі наступні файли. Усі дані в заголовку pax закодовано в UTF-8 з міркувань переносимості.

Є ще кілька варіантів формату tar, які можна читати, але не створювати:

- Старовинний формат V7. Це перший формат tar із Unix Seventh Edition, який зберігає лише звичайні файли та каталоги. Імена не повинні бути довшими за 100 символів, інформація про ім’я користувача/групи відсутня. Деякі архіви мають неправильно обчислені контрольні суми заголовків у випадку полів із символами, відмінними від ASCII.

- Розширений формат SunOS tar. Цей формат є варіантом формату POSIX.1-2001 pax, але він не сумісний.

## Проблеми з Unicode

Формат tar спочатку був задуманий для створення резервних копій на стрічкових накопичувачах з основним фокусом на збереженні інформації про файлову систему. Зараз архіви tar широко використовуються для розповсюдження файлів та обміну архівами в мережах. Однією з проблем вихідного формату (який є основою всіх інших форматів) є відсутність концепції підтримки різних кодувань символів. Наприклад, звичайний архів tar, створений у системі UTF-8, не може бути правильно прочитаний у системі Latin-1, якщо він містить символи, відмінні від ASCII. Текстові метадані (як-от імена файлів, імена посилань, імена користувачів/груп) відображатимуться пошкодженими. На жаль, немає способу автоматичного визначення кодування архіву. Формат pax був розроблений для вирішення цієї проблеми. Він зберігає метадані, відмінні від ASCII, використовуючи універсальне кодування символів UTF-8.

Деталі перетворення символів у `tarfile` контролюються ключовими аргументами encoding і errors класу `TarFile`.

encoding визначає кодування символів для метаданих в архіві. Значення за замовчуванням — `sys.getfilesystemencoding()` або `'ascii'` як запасний варіант. Залежно від того, читається чи записується архів, метадані повинні бути або декодовані, або закодовані. Якщо кодування не встановлено належним чином, це перетворення може не вдатися.

Аргумент errors визначає, як обробляються символи, які не можна перетворити. Можливі значення перераховані в розділі Обробники помилок. Типовою схемою є `'surrogateescape'`, яку Python також використовує для викликів своєї файлової системи, див. Імена файлів, аргументи командного рядка та змінні середовища.

Для архівів `PAX_FORMAT` (за замовчуванням) кодування зазвичай не потрібне, оскільки всі метадані зберігаються за допомогою UTF-8. кодування використовується лише в рідкісних випадках, коли двійкові заголовки pax декодуються або коли зберігаються рядки із сурогатними символами.