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:

• Automatic compression format detection
• Efficient batch operations
• Proper resource cleanup via context manager

Thread Safety

See darkseid.archivers.archiver.Archiver for the full contract.

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

Methods:

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

Existing files in this archive are kept unless the source archive has a file with the same name. Nothing is written if any file can't be copied. Files with unsafe names (absolute paths, drive letters or '..' components) are skipped with a warning.

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, max_size: int | None = None) -> bytes

Read the contents of a file from the TAR archive.

PARAMETER	DESCRIPTION
archive_file	Path of the file within the archive. TYPE: str
max_size	Maximum uncompressed size in bytes to read. Defaults to MAX_READ_SIZE when None. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
bytes	The complete file contents as bytes.

RAISES	DESCRIPTION
ArchiverFileTooLargeError	If the file's size exceeds max_size.
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. The original archive is left untouched on failure.

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.

The archive is rebuilt in a temporary file that replaces the original only once it is complete, so the original is left untouched if the write fails.

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.

RAISES	DESCRIPTION
ArchiverWriteError	If the existing archive can't be read or the write fails.