Rar

`RarArchiver(path: Path)`

Bases: Archiver

A read-only archiver for RAR files.

This class provides an interface for reading files from RAR archives. Due to the proprietary nature of the RAR format, write operations are not supported. All modification attempts will fail gracefully with appropriate warnings.

The implementation depends on the rarfile library, which in turn requires external RAR tools (like unrar) to be installed on the system.

ATTRIBUTE	DESCRIPTION
`path`	The filesystem path to the RAR archive. TYPE: `Path`

Note

RAR files are read-only due to format limitations and licensing restrictions of the RAR compression algorithm.

Initialize a RarArchiver with the provided path.

PARAMETER	DESCRIPTION
`path`	The filesystem path to the RAR archive file. TYPE: `Path`

Note

This constructor does not validate that the file exists or is a valid RAR archive. Validation occurs when operations are performed on the archive.

Functions

`copy_from_archive(other_archive: Archiver) -> bool`

Attempt to copy files from another archive to the RAR archive.

PARAMETER	DESCRIPTION
`other_archive`	The source archive to copy files from. TYPE: `Archiver`

RETURNS	DESCRIPTION
`False`	RAR files are read-only, so this operation always fails. TYPE: `bool`

Note

This method logs a warning and returns False immediately. No actual copy operation is attempted since RAR format does not support modification of existing archives.

Warning

A warning will be logged indicating that the copy operation was attempted on a read-only RAR archive, including the path of the source archive.

Examples:

Python Console Session

>>> rar_archive = RarArchiver(Path("target.rar"))
>>> zip_archive = ZipArchiver(Path("source.cbz"))
>>> success = rar_archive.copy_from_archive(zip_archive)
>>> print(f"Copy successful: {success}")  # Will print: Copy successful: False

`get_filename_list() -> list[str]`

Get a list of all files in the RAR archive.

RETURNS	DESCRIPTION
`list[str]`	A sorted list of file paths within the archive. Paths use forward slashes as separators and are relative to the archive root. Empty directories may or may not be included depending on how the archive was created.

RAISES	DESCRIPTION
`ArchiverReadError`	If the archive cannot be read due to: RAR command execution failure (missing unrar tool) Corrupt or invalid RAR file File system or permission errors

Examples:

Python Console Session

>>> archiver = RarArchiver(Path("documents.rar"))
>>> files = archiver.get_filename_list()
>>> print(f"Archive contains {len(files)} files:")
>>> for file in files:
...     print(f"  {file}")

Note

The returned list is sorted alphabetically for consistent ordering. This may differ from the order in which files were added to the archive.

`is_write_operation_expected() -> bool`

Check if write operations are supported.

RETURNS	DESCRIPTION
`False`	RAR files are always read-only. TYPE: `bool`

Note

This method is used by the parent class to determine if write operations should be attempted. For RAR files, this always returns False to prevent unnecessary operation attempts.

`read_file(archive_file: str) -> bytes`

Read the contents of a file from the RAR archive.

PARAMETER	DESCRIPTION
`archive_file`	The path of the file within the archive. Should use forward slashes as path separators regardless of the operating system. TYPE: `str`

RETURNS	DESCRIPTION
`bytes`	The file contents as bytes. For text files, decode using the appropriate encoding (e.g., content.decode('utf-8')).

RAISES	DESCRIPTION
`ArchiverReadError`	If the file cannot be read due to: RAR command execution failure (missing unrar tool) Corrupt or invalid RAR file File not found in the archive Other I/O errors

Examples:

Python Console Session

>>> archiver = RarArchiver(Path("comics.rar"))
>>> image_data = archiver.read_file("page01.jpg")
>>> with open("extracted_page.jpg", "wb") as f:
...     f.write(image_data)

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

Attempt to remove multiple files from the RAR archive.

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

RETURNS	DESCRIPTION
`False`	RAR files are read-only, so this operation always fails. TYPE: `bool`

Note

This method logs a warning and returns False immediately. No actual removal operations are attempted since RAR format does not support modification of existing archives.

Warning

A warning will be logged indicating that the bulk remove operation was attempted on a read-only RAR archive, including the list of files that were requested to be removed.

`test() -> bool`

Test whether the file is a valid RAR archive.

RETURNS	DESCRIPTION
`bool`	True if the file is a valid RAR archive, False otherwise. TYPE: `bool`

Note

This method uses the rarfile library to validate the archive structure, not just the file extension.

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

Attempt to write data to a file in the RAR archive.

PARAMETER	DESCRIPTION
`archive_file`	The path of the file within the archive. TYPE: `str`
`data`	The data to write (string or bytes). TYPE: `str \| bytes`

RETURNS	DESCRIPTION
`False`	RAR files are read-only, so this operation always fails. TYPE: `bool`

Note

This method logs a warning and returns False immediately. No actual write operation is attempted since RAR format does not support modification of existing archives.

Warning

A warning will be logged indicating that the write operation was attempted on a read-only RAR archive.