Tar

TarArchiver(path: Path)

Bases: Archiver

Tar archiver implementation for handling TAR files.

This class provides support for TAR archives including compressed variants. It automatically detects the compression format based on the file extension and handles the appropriate compression/decompression transparently.

Supported formats:

• .cbt: Uncompressed TAR
• .tar: Uncompressed TAR
• .tar.gz, .tgz: Gzip compressed TAR
• .tar.bz2, .tbz2: Bzip2 compressed TAR
• .tar.xz, .txz: XZ compressed TAR

Features:

• Thread-safe for reading operations (multiple readers)
• Write operations should be performed by a single thread
• Automatic compression format detection
• Efficient batch operations
• Proper resource cleanup via context manager

Performance Notes

• Filename lists are cached to avoid repeated archive parsing

Note

TAR files are append-only by nature. When removing files, the entire archive is reconstructed without the specified files. This can be expensive for large archives.

Initialize TarArchiver with the specified path.

PARAMETER	DESCRIPTION
path	Path to the TAR file. The compression format is determined automatically based on the file extension. TYPE: Path

Functions

__enter__() -> Self

Context manager entry for Tar archive operations.

RETURNS	DESCRIPTION
Self	The archiver instance for use in the context. TYPE: Self

Examples:

Python Console Session

>>> with TarArchiver(Path("archive.cbt")) as archive:
...     # Use archive here
...     files = archive.get_filename_list()

__exit__(*_: object) -> None

Context manager exit with proper cleanup.

Ensures the archive is properly closed and caches are cleared to prevent memory leaks and resource issues.

PARAMETER	DESCRIPTION
*_	Exception information (ignored) TYPE: object DEFAULT: ()

Note

This method is called automatically when exiting a 'with' block. It handles exceptions gracefully and always cleans up resources.

copy_from_archive(other_archive: Archiver) -> bool

Copy files from another archive to this TAR archive.

PARAMETER	DESCRIPTION
other_archive	Source archive to copy files from. TYPE: Archiver

RETURNS	DESCRIPTION
bool	True if all files were successfully copied, False otherwise.

get_filename_list() -> list[str]

Get list of all files in the Tar archive.

Returns a sorted list of all file paths contained in the archive. The list is cached for performance and updated when files are added or removed.

RETURNS	DESCRIPTION
list[str]	List of file paths in the archive, sorted alphabetically. Returns empty list if archive doesn't exist or is empty.

Examples:

Python Console Session

>>> with TarArchiver(Path("archive.cbt")) as archive:
...     files = archive.get_filename_list()
...     print(f"Archive contains {len(files)} files:")
...     for file in files:
...         print(f"  - {file}")
...
...     # Check if specific file exists
...     if "config.txt" in files:
...         print("Config file found")

Performance

The filename list is cached after first access, so subsequent calls are very fast. Cache is invalidated when files are added or removed.

Note

File paths use forward slashes regardless of platform.

read_file(archive_file: str) -> bytes

Read the contents of a file from the TAR archive.

PARAMETER	DESCRIPTION
archive_file	Path of the file within the archive. TYPE: str

RETURNS	DESCRIPTION
bytes	The complete file contents as bytes.

RAISES	DESCRIPTION
ArchiverReadError	If the file cannot be read from the archive.

remove_files(filename_list: list[str]) -> bool

Remove multiple files from the TAR archive.

PARAMETER	DESCRIPTION
filename_list	List of file paths to remove from the archive. TYPE: list[str]

RETURNS	DESCRIPTION
bool	True if all files were successfully removed, False otherwise.

test() -> bool

Test whether the TAR archive is valid.

RETURNS	DESCRIPTION
bool	True if the file is a valid TAR archive, False otherwise.

write_file(archive_file: str, data: str | bytes) -> bool

Write data to a file in the TAR archive.

PARAMETER	DESCRIPTION
archive_file	Path of the file within the archive. TYPE: str
data	Data to write to the file. TYPE: str | bytes

RETURNS	DESCRIPTION
bool	True if the write operation was successful, False otherwise.

RAISES	DESCRIPTION
ArchiverWriteError	If the write operation fails.