Skip to content

Commit

Permalink
Update documentation (#96)
Browse files Browse the repository at this point in the history
* Add docstrings
* Update project deps
* Use __future__ annotations
* Use better variable name
  • Loading branch information
bpepple authored Jun 16, 2024
1 parent ae49c44 commit c76b052
Show file tree
Hide file tree
Showing 11 changed files with 886 additions and 278 deletions.
13 changes: 13 additions & 0 deletions darkseid/archivers/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,21 @@


class UnknownArchiver(Archiver):
"""
Represents an unknown archiver.
This class provides functionality for an unknown archiver type.
"""

@staticmethod
def name() -> str:
"""
Returns the name of the archiver as "Unknown".
Returns:
str: The name of the archiver.
"""

return "Unknown"

__all__: ClassVar[list] = [Archiver, RarArchiver, "UnknownArchiver", ZipArchiver]
100 changes: 90 additions & 10 deletions darkseid/archivers/archiver.py
Original file line number Diff line number Diff line change
@@ -1,36 +1,116 @@
from pathlib import Path
from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
from pathlib import Path


class Archiver:
"""Unknown implementation."""
"""
Handles archiving operations for files.
This class provides methods for reading, writing, and removing files within an archive.
"""

def __init__(self: Archiver, path: Path) -> None:
"""
Initializes an Archiver object with a specified path.
Args:
path (Path): The path associated with the Archiver.
Returns:
None
"""

def __init__(self: "Archiver", path: Path) -> None:
self.path = path

def read_file(self: "Archiver", archive_file: str) -> bytes:
def read_file(self: Archiver, archive_file: str) -> bytes:
"""
Reads the content of a file from the archive.
Args:
archive_file (str): The file to read from the archive.
Returns:
bytes: The content of the file as bytes.
Raises:
NotImplementedError
"""

raise NotImplementedError

def write_file(
self: "Archiver",
self: Archiver,
archive_file: str, # noqa: ARG002
data: str, # noqa: ARG002
) -> bool:
"""
Writes data to a file in the archive.
Args:
archive_file (str): The file to write to in the archive.
data (str): The data to write to the file.
Returns:
bool: True if the write operation was successful, False otherwise.
"""

return False

def remove_file(self: "Archiver", archive_file: str) -> bool: # noqa: ARG002
def remove_file(self: Archiver, archive_file: str) -> bool: # noqa: ARG002
"""
Removes a file from the archive.
Args:
archive_file (str): The file to remove from the archive.
Returns:
bool: True if the file was successfully removed, False otherwise.
"""

return False

def remove_files(
self: "Archiver",
self: Archiver,
filename_lst: list[str], # noqa: ARG002
) -> bool:
"""
Removes multiple files from the archive.
Args:
filename_lst (list[str]): The list of files to remove from the archive.
Returns:
bool: True if all files were successfully removed, False otherwise.
"""

return False

def get_filename_list(self: "Archiver") -> list[str]:
def get_filename_list(self: Archiver) -> list[str]:
"""
Returns an empty list of filenames from the archive.
Returns:
list[str]: An empty list of filenames.
"""

return []

def copy_from_archive(
self: "Archiver",
other_archive: "Archiver", # noqa: ARG002
self: Archiver,
other_archive: Archiver, # noqa: ARG002
) -> bool:
"""
Copies files from another archive.
Args:
other_archive (Archiver): The archive to copy files from.
Returns:
bool: True if the copy operation was successful, False otherwise.
"""

return False
107 changes: 91 additions & 16 deletions darkseid/archivers/rar.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
from __future__ import annotations

import io
from pathlib import Path
from typing import TYPE_CHECKING

if TYPE_CHECKING:
from pathlib import Path

import rarfile

Expand All @@ -8,13 +13,39 @@


class RarArchiver(Archiver):
"""Rar implementation."""
"""
Handles archiving operations specific to RAR files.
This class provides methods for reading, writing, and removing files within a RAR archive.
"""

def __init__(self: RarArchiver, path: Path) -> None:
"""
Initializes a RarArchiver object with the provided path.
Args:
path (Path): The path associated with the RAR file.
Returns:
None
"""

def __init__(self: "RarArchiver", path: Path) -> None:
super().__init__(path)

def read_file(self: "RarArchiver", archive_file: str) -> bytes:
"""Read the contents of a comic archive."""
def read_file(self: RarArchiver, archive_file: str) -> bytes:
"""
Reads the contents of a file from the RAR archive.
Args:
archive_file (str): The file to read from the archive.
Returns:
bytes: The content of the file as bytes.
Raises:
RarError: If an error occurs during reading.
"""

try:
with rarfile.RarFile(self.path) as rf:
data: bytes = rf.read(archive_file)
Expand All @@ -26,29 +57,73 @@ def read_file(self: "RarArchiver", archive_file: str) -> bytes:
else:
return data

def remove_file(self: "RarArchiver", archive_file: str) -> bool: # noqa: ARG002
"""Rar files are read-only, so we return False."""
def remove_file(self: RarArchiver, archive_file: str) -> bool: # noqa: ARG002
"""
Removes a file from the RAR archive.
Args:
archive_file (str): The file to remove from the archive.
Returns:
bool: False, as RAR files are read-only.
"""

return False

def remove_files(self: "RarArchiver", filename_lst: list[str]) -> bool: # noqa: ARG002
"""Rar files are read-only, so we return False."""
def remove_files(self: RarArchiver, filename_lst: list[str]) -> bool: # noqa: ARG002
"""
Removes multiple files from the RAR archive.
Args:
filename_lst (list[str]): The list of files to remove from the archive.
Returns:
bool: False, as RAR files are read-only.
"""

return False

def write_file(self: "RarArchiver", archive_file: str, data: str) -> bool: # noqa: ARG002
"""Rar files are read-only, so we return False."""
def write_file(self: RarArchiver, archive_file: str, data: str) -> bool: # noqa: ARG002
"""
Writes data to a file in the RAR archive.
Args:
archive_file (str): The file to write to in the archive.
data (str): The data to write to the file.
Returns:
bool: False, as RAR files are read-only.
"""
return False

def get_filename_list(self: "RarArchiver") -> list[str]:
"""Returns a list of the filenames in an archive."""
def get_filename_list(self: RarArchiver) -> list[str]:
"""
Returns a list of filenames in the RAR archive.
Returns:
list[str]: A sorted list of filenames in the archive.
Raises:
RarError: If an error occurs during retrieval.
"""

try:
with rarfile.RarFile(self.path) as rf:
return sorted(rf.namelist())
except rarfile.RarCannotExec as e:
raise RarError(e) from e

def copy_from_archive(
self: "RarArchiver",
other_archive: "Archiver", # noqa: ARG002
self: RarArchiver,
other_archive: Archiver, # noqa: ARG002
) -> bool:
"""Rar files are read-only, so we return False."""
"""
Copies files from another archive to the RAR archive.
Args:
other_archive (Archiver): The archive to copy files from.
Returns:
bool: False, as RAR files are read-only.
"""

return False
Loading

0 comments on commit c76b052

Please sign in to comment.