`tarfile` --- Read and write tar archive files¶

Kod źródłowy: 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, символьні пристрої та блокові пристрої, а також може отримувати та відновлювати інформацію про файл, як-от мітку часу, права доступу та власника.

Berubah pada versi 3.3: Додано підтримку стиснення lzma.

Berubah pada versi 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.

Berubah pada versi 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.

Berubah pada versi 3.14: Added support for Zstandard compression using compression.zstd.

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

Повертає об’єкт TarFile для шляху name. Для отримання детальної інформації про об’єкти TarFile та дозволені ключові аргументи дивіться Objek TarFile.

mode має бути рядком у формі 'filemode[:compression]', за замовчуванням це 'r'. Ось повний список комбінацій режимів:

mode	aksi
`'r'` or `'r:*'`	Відкрити для читання з прозорим стисненням (рекомендовано).
`'r:'`	Відкритий виключно для читання без стиснення.
`'r:gz'`	Відкрити для читання зі стисненням gzip.
`'r:bz2'`	Відкрити для читання зі стисненням bzip2.
`'r:xz'`	Відкритий для читання зі стисненням lzma.
`'r:zst'`	Open for reading with Zstandard compression.
`'x'` or `'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 Contoh-contoh. 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.

Berubah pada versi 3.5: Додано режим 'x (ексклюзивне створення).

Berubah pada versi 3.6: Параметр name приймає path-like object.

Berubah pada versi 3.12: The compresslevel keyword argument also works for streams.

Berubah pada versi 3.14: The preset keyword argument also works for streams.

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

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

Berubah pada versi 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¶

Базовый класс для членов refused по фильтрам.

tarinfo¶: Информация об элементе, который фильтр отказался извлечь, в виде TarInfo.

exception tarfile.AbsolutePathError¶: Поднят, чтобы отказаться от извлечения члена с абсолютным путем.

exception tarfile.OutsideDestinationError¶: Вызывается для отказа в извлечении члена за пределы каталога назначения.

exception tarfile.SpecialFileError¶: Вызывается для отказа в извлечении специального файла (например, устройства или канала).

exception tarfile.AbsoluteLinkError¶: Поднят, чтобы отказаться от извлечения символической ссылки с абсолютным путем.

exception tarfile.LinkOutsideDestinationError¶: Поднят, чтобы отказаться от извлечения символической ссылки, указывающей за пределы каталога назначения.

exception tarfile.LinkFallbackError¶: Levantada para recusar a emulação de um link (físico ou simbólico) extraindo outro membro do arquivo, quando esse membro seria rejeitado pelo local do filtro. A exceção levantada para rejeitar o membro substituto está disponível como 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¶: format POSIX.1-1988 (ustar).

tarfile.GNU_FORMAT¶: format GNU tar.

tarfile.PAX_FORMAT¶: format POSIX.1-2001 (pax).

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

Berubah pada versi 3.8: Стандартний формат для нових архівів було змінено на PAX_FORMAT з GNU_FORMAT.

Lihat juga

Modul zipfile: Документація стандартного модуля zipfile.
Архівні операції: Документація засобів архівування вищого рівня, які надає стандартний модуль shutil.
Посібник GNU tar, базовий формат Tar: Документація для архівних файлів tar, включаючи розширення GNU tar.

Objek TarFile¶

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

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

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.

Catatan

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.

Berubah pada versi 3.2: Використовуйте 'surrogateescape' як типове значення для аргументу errors.

Berubah pada versi 3.5: Додано режим 'x (ексклюзивне створення).

Berubah pada versi 3.6: Параметр name приймає path-like object.

Berubah pada versi 3.13: Add the stream parameter.

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

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

Catatan

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

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

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

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

Berubah pada versi 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 Фильтры для извлечения 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).

Peringatan

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 Фильтры для извлечения section for details.

Berubah pada versi 3.5: Додано параметр numeric_owner.

Berubah pada versi 3.6: Параметр path приймає path-like object.

Berubah pada versi 3.12: Додано параметр фільтр.

Berubah pada versi 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.

Аргументы numeric_owner и filter такие же, как и для extractall().

Catatan

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

Peringatan

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

Berubah pada versi 3.2: Додано параметр set_attrs.

Berubah pada versi 3.5: Додано параметр numeric_owner.

Berubah pada versi 3.6: Параметр path приймає path-like object.

Berubah pada versi 3.12: Додано параметр фільтр.

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

Berubah pada versi 3.3: Повертає об’єкт io.BufferedReader.

Berubah pada versi 3.13: The returned io.BufferedReader object has the mode attribute which is always equal to 'rb'.

TarFile.errorlevel: int¶

Если errorlevel равен 0, ошибки игнорируются при использовании TarFile.extract() и TarFile.extractall(). Тем не менее, они появляются в виде сообщений об ошибках в выходных данных отладки, когда debug больше 0. Если 1 (по умолчанию), все фатальные ошибки выдаются как OSError или :exc:` Исключения FilterError`. Если 2, все нефатальные ошибки также вызываются как исключения TarError.

Некоторые исключения, например, вызванные неправильными типами аргументов или повреждением данных, возникают всегда.

Пользовательские фильтры извлечения должны вызывать FilterError для фатальных ошибок и ExtractError для нефатальных ошибок.

Обратите внимание, что при возникновении исключения архив может быть частично извлечен. Ответственность за очистку лежит на пользователе.

TarFile.extraction_filter¶

Added in version 3.12.

Фильтр извлечения <tarfile-extraction-filter>, используемый по умолчанию для аргумента filter extract() и extractall().

Атрибут может быть None или вызываемым. Для этого атрибута не допускаются строковые имена, в отличие от аргумента filter для 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.

Berubah pada versi 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 буде виключено з архіву. Перегляньте Contoh-contoh для прикладу.

Berubah pada versi 3.2: Додано параметр фільтр.

Berubah pada versi 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().

Berubah pada versi 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 може бути фіктивним рядком.

Berubah pada versi 3.6: Параметр name приймає path-like object.

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

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

Objek TarInfo¶

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

Объекты TarInfo возвращаются методами TarFile getmember(), getmembers() и 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.

Для некоторых атрибутов можно установить значение «Нет», чтобы указать, что часть метаданных не используется или неизвестна. Различные методы TarInfo обрабатывают None по-разному:

Методы extract() или extractall() будут игнорировать соответствующие метаданные, оставляя для них значение по умолчанию.
addfile() завершится неудачно.
list() напечатает строку-заполнитель.

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.

Berubah pada versi 3.2: Використовуйте 'surrogateescape' як типове значення для аргументу errors.

Об’єкт TarInfo має такі загальнодоступні атрибути даних:

TarInfo.name: str¶: ПІБ учасника архіву.

TarInfo.size: int¶: Розмір у байтах.

TarInfo.mtime: int | float¶: Время последнего изменения в секундах с epoch, например os.stat_result.st_mtime.

Berubah pada versi 3.12: Может быть установлено значение None для extract() и extractall(), в результате чего при извлечении пропускается применение этого атрибута.

TarInfo.mode: int¶: Биты разрешения, как для os.chmod().

Berubah pada versi 3.12: Может быть установлено значение None для extract() и extractall(), в результате чего при извлечении пропускается применение этого атрибута.

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

TarInfo.linkname: str¶

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

Для символических ссылок (SYMTYPE) linkname относится к каталогу, в котором содержится ссылка. Для жестких ссылок (LNKTYPE) linkname относится к корню архива.

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

Berubah pada versi 3.12: Может быть установлено значение None для extract() и extractall(), в результате чего при извлечении пропускается применение этого атрибута.

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

Berubah pada versi 3.12: Может быть установлено значение None для extract() и extractall(), в результате чего при извлечении пропускается применение этого атрибута.

TarInfo.uname: str¶: Ім'я користувача.

Berubah pada versi 3.12: Может быть установлено значение None для extract() и extractall(), в результате чего при извлечении пропускается применение этого атрибута.

TarInfo.gname: str¶: Назва групи.

Berubah pada versi 3.12: Может быть установлено значение None для extract() и extractall(), в результате чего при извлечении пропускается применение этого атрибута.

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.

Вернуть новую копию объекта TarInfo с измененными заданными атрибутами. Например, чтобы вернуть TarInfo с именем группы, установленным на «staff», используйте:

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

По умолчанию создается глубокая копия. Если deep имеет значение false, копия является мелкой, т. е. pax_headers и любые пользовательские атрибуты используются совместно с исходным объектом TarInfo.

Об’єкт 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.

Фильтры для извлечения¶

Added in version 3.12.

Формат tar предназначен для сбора всех деталей UNIX-подобной файловой системы, что делает его очень мощным. К сожалению, эти функции позволяют легко создавать tar-файлы, которые при извлечении имеют непреднамеренные и, возможно, вредоносные последствия. Например, извлечение tar-файла может перезаписать произвольные файлы различными способами (например, с использованием абсолютных путей, компонентов пути .. или символических ссылок, которые влияют на последующие элементы).

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

Peringatan

None of the available filters blocks all dangerous archive features. Never extract archives from untrusted sources without prior inspection. See also Советы для дальнейшей проверки.

Lihat juga

PEP 706: Содержит дополнительную мотивацию и обоснование дизайна.

Аргумент filter для TarFile.extract() или extractall() может быть:

строка 'fully_trusted': учитывайте все метаданные, указанные в архиве. Следует использовать, если пользователь полностью доверяет архиву или реализует собственную сложную проверку.
строка 'tar': учитывайте большинство функций, специфичных для tar (т.е. функций UNIX-подобных файловых систем), но блокируйте функции, которые могут оказаться неожиданными или вредоносными. Подробности смотрите в tar_filter().
строка 'data': игнорировать или блокировать большинство функций, специфичных для UNIX-подобных файловых систем. Предназначен для извлечения кроссплатформенных архивов данных. Подробности смотрите в data_filter().
Нет (по умолчанию): используйте TarFile.extraction_filter.

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

Berubah pada versi 3.14: The default filter is set to data. Previously, the default was equivalent to fully_trusted.
Вызываемый объект, который будет вызываться для каждого извлеченного элемента с TarInfo, описывающим элемент и путь назначения, куда извлекается архив (т.е. один и тот же путь используется для всех членов):
```
filter(member: TarInfo, path: str, /) -> TarInfo | None
```
Вызываемый объект вызывается непосредственно перед извлечением каждого члена, поэтому он может учитывать текущее состояние диска. Он может:
- вернуть объект TarInfo, который будет использоваться вместо метаданных в архиве, или
- верните None, и в этом случае элемент будет пропущен, или
- вызвать исключение, чтобы прервать операцию или пропустить элемент, в зависимости от errorlevel. Обратите внимание, что при прерывании извлечения extractall() может оставить архив частично извлеченным. Он не пытается очистить.

Именованные фильтры по умолчанию¶

Предопределенные именованные фильтры доступны как функции, поэтому их можно повторно использовать в пользовательских фильтрах:

tarfile.fully_trusted_filter(member, path)¶

Вернуть member без изменений.

Это реализует фильтр «полностью_доверенный».

tarfile.tar_filter(member, path)¶

Реализует фильтр 'tar'.

Strip leading slashes (/ and os.sep) from filenames.
Refuse для извлечения файлов с абсолютными путями (в случае, если имя является абсолютным даже после удаления косых черт, например C:/foo в Windows). Это вызывает AbsolutePathError.
Refuse для извлечения файлов, абсолютный путь которых (после перехода по символическим ссылкам) окажется за пределами места назначения. Это вызывает OutsideDestinationError.
Clear high mode bits (setuid, setgid, sticky) and group/other write bits (S_IWGRP | S_IWOTH).

Верните измененный член TarInfo.

tarfile.data_filter(member, path)¶

Реализует фильтр данных. В дополнение к тому, что делает tar_filter:

使用 os.path.normpath() 来正规化链接目标 (TarInfo.linkname)。请注意这将移除内部的 .. 组件，这可能在 TarInfo.linkname 中的路径会遍历符号链接时改变链接的含义。
Refuse для извлечения ссылок (жестких или программных), которые ссылаются на абсолютные пути или ссылки за пределами места назначения.

Это вызывает AbsoluteLinkError или LinkOutsideDestinationError.

Обратите внимание, что такие файлы отклоняются даже на платформах, не поддерживающих символические ссылки.
Refuse для извлечения файлов устройства (включая каналы). Это вызывает SpecialFileError.
Для обычных файлов, включая жесткие ссылки:
- 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).
Для других файлов (каталогов) установите для параметра mode значение None, чтобы методы извлечения пропускали применение битов разрешений.
Установите для информации о пользователе и группе (uid, gid, uname, gname) значение None, чтобы методы извлечения пропустили ее установку.

Верните измененный член TarInfo.

Note that this filter does not block all dangerous archive features. See Советы для дальнейшей проверки for details.

Berubah pada versi 3.14: 链接目标现在会被正规化。

Ошибки фильтрации¶

Когда фильтр отказывается извлечь файл, он выдает соответствующее исключение, подкласс FilterError. Это прервет извлечение, если TarFile.errorlevel равен 1 или более. При errorlevel=0 ошибка будет зарегистрирована, и элемент будет пропущен, но извлечение продолжится.

Советы для дальнейшей проверки¶

Даже с filter='data' tarfile не подходит для извлечения ненадежных файлов без предварительной проверки. Помимо прочего, предопределенные фильтры не предотвращают атаки типа «отказ в обслуживании». Пользователям следует выполнить дополнительные проверки.

Вот неполный список вещей, на которые стоит обратить внимание:

Извлеките файлы в новый временный каталог, чтобы предотвратить, например, использование уже существующих ссылок и облегчить очистку после неудачного извлечения.
如果你不需要此功能则请禁用符号链接。
При работе с ненадежными данными используйте внешние (например, на уровне ОС) ограничения на использование диска, памяти и ЦП.
Check filenames against an allow-list of characters (to filter out control characters, confusables, foreign path separators, and so on).
Убедитесь, что имена файлов имеют ожидаемые расширения (не рекомендуется использовать файлы, которые выполняются при нажатии на них, или файлы без расширений, такие как имена специальных устройств Windows).
Ограничьте количество извлеченных файлов, общий размер извлеченных данных, длину имени файла (включая длину символической ссылки) и размер отдельных файлов.
Проверьте наличие файлов, которые будут дублироваться в файловых системах, нечувствительных к регистру.

Также обратите внимание, что:

Файлы Tar могут содержать несколько версий одного и того же файла. Ожидается, что более поздние записи перезапишут более ранние. Эта функция имеет решающее значение для обновления ленточных архивов, но ею можно злоупотреблять.
tarfile не защищает от проблем с «живыми» данными, например, если злоумышленник изменяет целевой (или исходный) каталог во время извлечения (или архивирования).

Поддержка старых версий Python¶

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.

В следующих примерах показано, как поддерживать версии Python с этой функцией и без нее. Обратите внимание, что установка «extraction_filter» повлияет на любые последующие операции.

Полностью доверенный архив:

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

Используйте фильтр 'data', если он доступен, но вернитесь к поведению Python 3.11 ('full_trusted'), если эта функция недоступна:

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

Используйте фильтр 'данные'; fail, если он недоступен:

my_tarfile.extractall(filter=tarfile.data_filter)

atau:

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

Используйте фильтр 'данные'; предупреждать, если он недоступен:

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

Пример фильтра извлечения с отслеживанием состояния¶

В то время как методы извлечения tarfile используют простой вызываемый filter, пользовательские фильтры могут представлять собой более сложные объекты с внутренним состоянием. Может быть полезно написать их как менеджеры контекста, чтобы использовать их следующим образом:

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

Такой фильтр можно записать, например, так:

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>¶: Указывает фильтр для --extract. Подробности смотрите в Фильтры для извлечения. Принимаются только строковые имена (т. е. «fully_trusted», «tar» и «data»).

Contoh-contoh¶

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 визначає, як обробляються символи, які не можна перетворити. Можливі значення перераховані в розділі Penangan Kesalahan. Типовою схемою є 'surrogateescape', яку Python також використовує для викликів своєї файлової системи, див. Nama Berkas, Argumen Command Line, dan Variabel Lingkungan.

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

`tarfile` --- Read and write tar archive files¶

Objek TarFile¶

Objek TarInfo¶

Фильтры для извлечения¶

Именованные фильтры по умолчанию¶

Ошибки фильтрации¶

Советы для дальнейшей проверки¶

Поддержка старых версий Python¶

Пример фильтра извлечения с отслеживанием состояния¶

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

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

Contoh-contoh¶

Reading examples¶

Writing examples¶

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

Проблеми з Unicode¶

Daftar Isi

Topik sebelumnya

Topik berikutnya

This page

tarfile --- Read and write tar archive files¶

Objek TarFile¶

Objek TarInfo¶

Фильтры для извлечения¶

Именованные фильтры по умолчанию¶

Ошибки фильтрации¶

Советы для дальнейшей проверки¶

Поддержка старых версий Python¶

Пример фильтра извлечения с отслеживанием состояния¶

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

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

Contoh-contoh¶

Reading examples¶

Writing examples¶

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

Проблеми з Unicode¶

`tarfile` --- Read and write tar archive files¶