ArchiverFactory

UnknownArchiver(path: Path)

Bases: Archiver

Fallback archiver for unsupported file types.

This archiver is used when the file extension is not recognized by the factory. All operations return failure states or raise NotImplementedError to indicate that the archive format is not supported.

Examples:

Python Console Session

>>> from pathlib import Path
>>> archiver = UnknownArchiver(Path("file.unknown"))
>>> archiver.name()
'Unknown'
>>> archiver.get_filename_list()
[]

Functions

copy_from_archive(other_archive: Archiver) -> bool

Copy files from another archive.

This method is not implemented for unknown archive types and always returns False.

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

RETURNS	DESCRIPTION
bool	Always False, indicating that copying is not supported for unknown archive types. TYPE: bool

Examples:

Python Console Session

>>> source = ZipArchiver(Path("source.cbz"))
>>> target = UnknownArchiver(Path("target.unknown"))
>>> target.copy_from_archive(source)
False

get_filename_list() -> list[str]

Return a list of filenames in the archive.

For unknown archive types, this always returns an empty list since the archive format cannot be parsed.

RETURNS	DESCRIPTION
list[str]	list[str]: Always an empty list, as filenames cannot be determined for unknown archive types.

Examples:

Python Console Session

>>> archiver = UnknownArchiver(Path("file.unknown"))
>>> archiver.get_filename_list()
[]

name() -> str staticmethod

Return the name of the archiver.

RETURNS	DESCRIPTION
str	Always returns "Unknown" to identify this as the fallback archiver. TYPE: str

read_file(archive_file: str) -> bytes

Read a file from the archive.

This method is not implemented for unknown archive types and always raises NotImplementedError.

PARAMETER	DESCRIPTION
archive_file	The filename to read from the archive. TYPE: str

RAISES	DESCRIPTION
NotImplementedError	Always raised for unknown archive types, indicating that the archive format is not supported.

RETURNS	DESCRIPTION
bytes	This method does not return; it always raises an exception. TYPE: bytes

Examples:

Python Console Session

>>> archiver = UnknownArchiver(Path("file.unknown"))
>>> archiver.read_file("some_file.txt")
Traceback (most recent call last):
    ...
NotImplementedError: Unknown archive format

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

Remove multiple files from the archive.

This method is not implemented for unknown archive types and always returns False.

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

RETURNS	DESCRIPTION
bool	Always False, indicating that file removal is not supported for unknown archive types. TYPE: bool

Examples:

Python Console Session

>>> archiver = UnknownArchiver(Path("file.unknown"))
>>> archiver.remove_files(["file1.txt", "file2.txt"])
False

test() -> bool

Test whether the file is a RAR archive.

RETURNS	DESCRIPTION
bool	Returns False, as validity test for archive is unavailable. TYPE: bool

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

Write a file to the archive.

This method is not implemented for unknown archive types and always returns False.

PARAMETER	DESCRIPTION
archive_file	The filename to write to the archive. TYPE: str
data	The data to write to the file. Can be either string or bytes. TYPE: str | bytes

RETURNS	DESCRIPTION
bool	Always False, indicating that writing is not supported for unknown archive types. TYPE: bool

Examples:

Python Console Session

>>> archiver = UnknownArchiver(Path("file.unknown"))
>>> archiver.write_file("new_file.txt", "content")
False

ArchiverFactory

Factory for creating appropriate archiver instances based on file type.

This factory uses the file extension to determine the appropriate archiver class and returns an instance configured for the given file. It supports registration of new archiver types and provides a fallback for unknown formats.

The factory maintains a mapping of file extensions to archiver classes and can be extended at runtime by registering new archiver types.

ATTRIBUTE	DESCRIPTION
_ARCHIVER_MAP	Class variable mapping file extensions to archiver classes. TYPE: dict[str, type[Archiver]]

Examples:

Creating archivers for different file types:

Python Console Session

>>> from pathlib import Path
>>>
>>> # Create archiver for ZIP file
>>> zip_archiver = ArchiverFactory.create_archiver(Path("archive.cbz"))
>>> print(zip_archiver.name())  # "Zip"
>>>
>>> # Create archiver for RAR file
>>> rar_archiver = ArchiverFactory.create_archiver(Path("archive.rar"))
>>> print(rar_archiver.name())  # "Rar"
>>>
>>> # Create archiver for unknown format
>>> unknown_archiver = ArchiverFactory.create_archiver(Path("archive.7z"))
>>> print(unknown_archiver.name())  # "Unknown"

Registering a new archiver type:

Python Console Session

>>> from darkseid.archivers.seven_zip import SevenZipArchiver
>>> ArchiverFactory.register_archiver(".7z", SevenZipArchiver)
>>> archiver = ArchiverFactory.create_archiver(Path("archive.7z"))
>>> print(archiver.name())  # "SevenZip"

Functions

clear_registry() -> None classmethod

Clear all registered archivers and restore defaults.

This method removes all archiver registrations and restores the factory to its default state with only built-in archiver types.

Warning

This method will remove all custom archiver registrations. Use with caution.

Examples:

Python Console Session

>>> # After registering custom archivers
>>> ArchiverFactory.register_archiver(".7z", SevenZipArchiver)
>>> len(ArchiverFactory.get_supported_extensions())  # 5
>>>
>>> # Clear and restore defaults
>>> ArchiverFactory.clear_registry()
>>> len(ArchiverFactory.get_supported_extensions())  # 4

create_archiver(path: Path) -> Archiver classmethod

Create an appropriate archiver for the given file.

Analyzes the file extension and returns an archiver instance capable of handling that file type. If the extension is not recognized, returns an UnknownArchiver instance.

PARAMETER	DESCRIPTION
path	Path to the archive file. The file extension is used to determine the appropriate archiver type. TYPE: Path

RETURNS	DESCRIPTION
Archiver	An archiver instance appropriate for the file type. This will be a specific archiver (ZipArchiver, RarArchiver, etc.) for known formats, or UnknownArchiver for unsupported formats. TYPE: Archiver

Examples:

Python Console Session

>>> from pathlib import Path
>>>
>>> # Create archiver for different file types
>>> zip_archiver = ArchiverFactory.create_archiver(Path("comics/issue.cbz"))
>>> rar_archiver = ArchiverFactory.create_archiver(Path("archive.rar"))
>>> unknown_archiver = ArchiverFactory.create_archiver(Path("data.tar.gz"))
>>>
>>> print(zip_archiver.name())      # "Zip"
>>> print(rar_archiver.name())      # "Rar"
>>> print(unknown_archiver.name())  # "Unknown"

get_supported_extensions() -> list[str] classmethod

Get list of supported file extensions.

Returns a list of all file extensions that the factory can handle. This includes both built-in extensions and any extensions registered via register_archiver().

RETURNS	DESCRIPTION
list[str]	list[str]: Sorted list of supported file extensions, including the dot (e.g., ['.cbr', '.cbz', '.rar']).

Examples:

Python Console Session

>>> extensions = ArchiverFactory.get_supported_extensions()
>>> print(extensions)  # ['.cbr', '.cbz', '.rar'']
>>>
>>> # After registering new types
>>> ArchiverFactory.register_archiver(".7z", SevenZipArchiver)
>>> extensions = ArchiverFactory.get_supported_extensions()
>>> print(extensions)  # ['.cb7', '.cbr', '.cbz', '.rar'']

is_supported(path: Path) -> bool classmethod

Check if a file extension is supported by the factory.

PARAMETER	DESCRIPTION
path	Path to check for support. TYPE: Path

RETURNS	DESCRIPTION
bool	True if the file extension is supported, False otherwise. TYPE: bool

Examples:

Python Console Session

>>> from pathlib import Path
>>>
>>> ArchiverFactory.is_supported(Path("archive.cbz"))  # True
>>> ArchiverFactory.is_supported(Path("archive.7z"))   # False
>>>
>>> # After registering .7z support
>>> ArchiverFactory.register_archiver(".7z", SevenZipArchiver)
>>> ArchiverFactory.is_supported(Path("archive.7z"))   # True

register_archiver(extension: str, archiver_class: type[Archiver]) -> None classmethod

Register a new archiver for a file extension.

Adds a new archiver class to the factory's mapping, allowing it to handle additional file types. The extension is automatically converted to lowercase for consistent matching.

PARAMETER	DESCRIPTION
extension	File extension including the dot (e.g., '.7z', '.tar.gz'). The extension will be converted to lowercase for storage. TYPE: str
archiver_class	Archiver class that should handle files with this extension. Must be a subclass of Archiver and implement the required interface. TYPE: type[Archiver]

RAISES	DESCRIPTION
TypeError	If archiver_class is not a subclass of Archiver.

Examples:

Python Console Session

>>> from darkseid.archivers.seven_zip import SevenZipArchiver
>>> from darkseid.archivers.tar import TarArchiver
>>>
>>> # Register new archiver types
>>> ArchiverFactory.register_archiver(".7z", SevenZipArchiver)
>>> ArchiverFactory.register_archiver(".tar.gz", TarArchiver)
>>>
>>> # Now these extensions are supported
>>> archiver = ArchiverFactory.create_archiver(Path("archive.7z"))
>>> print(archiver.name())  # "SevenZip"

Python Console Session

>>> # Case insensitive registration
>>> ArchiverFactory.register_archiver(".TAR", TarArchiver)
>>> archiver = ArchiverFactory.create_archiver(Path("archive.tar"))
>>> print(archiver.name())  # "Tar"