Add docstrings

pyproject.toml

@@ -43,10 +43,14 @@ line-length = 120
 [tool.ruff.lint]
 select = ["ALL"]
 ignore = [
-    "D",
     "T201",  # `print` found
     "S101",  # Use of assert detected
     "ANN101",  # Missing type annotation for self in method
+    "D100", # Missing docstring in public module
+    "D104", # Missing docstring in public package
+    "D105", # Missing docstring in magic method
+    "D200", # One-line docstring should fit on one line
+    "D212", # Multi-line docstring summary should start at the first line
 ]
 unfixable = []
 

search_offsets/patterns.py

@@ -7,6 +7,10 @@
 
 
 class Pattern(NamedTuple):
+    """
+    A named tuple to contain information about a pattern: it's name and the pattern in bytes.
+    """
+
     name: str
     pattern: bytes
 
@@ -18,14 +22,23 @@ def __repr__(self) -> str:
 
 
 def hex_to_bytes(s: str) -> bytes:
+    """
+    Convert hexadecimal string to bytes.
+    """
     return int(s, 16).to_bytes(1, "little")
 
 
 def convert_to_pattern(s: list[str]) -> list[int | None]:
+    """
+    Convert list of the pattern tokens to a list of byte values or None if the token is "??".
+    """
     return [None if item == "??" else int(item, 16) for item in s]
 
 
 def load_patterns(filename: str = "fn_byte_patterns.ffsess") -> list[Pattern]:
+    """
+    Load patterns to a list from ffsess file.
+    """
     patterns = []
 
     with Path(filename).open() as patterns_file:
@@ -43,13 +56,19 @@ def load_patterns(filename: str = "fn_byte_patterns.ffsess") -> list[Pattern]:
 
 
 def group_patterns(patterns: list[Pattern]) -> Mapping[int, list[Pattern]]:
+    """
+    Group patterns by their first byte.
+    """
     patterns_dict = defaultdict(list)
     for pattern in patterns:
         patterns_dict[pattern.pattern[0]].append(pattern)
     return patterns_dict
 
 
 def check_pattern(buffer: bytes, start_index: int, pattern: list[int | None]) -> bool:
+    """
+    Check if the pattern matches the buffer starting at the given index.
+    """
     for i, c in enumerate(pattern):
         if c is None:
             continue

search_offsets/search.py

@@ -14,6 +14,9 @@
 
 
 def search(path: str, patterns: list[Pattern]) -> Mapping[str, list[int]]:
+    """
+    Search patterns in the given file.
+    """
     patterns_dict: Mapping[int, list[Pattern]] = group_patterns(patterns)
 
     found = defaultdict(list)
@@ -29,6 +32,9 @@ def search(path: str, patterns: list[Pattern]) -> Mapping[str, list[int]]:
 
 
 def print_found(section_table: SectionTable, pattern_names: Iterable[str], found: Mapping[str, int]) -> None:
+    """
+    Print offsets of the found patterns.
+    """
     for pattern in pattern_names:
         if not found[pattern]:
             print(f"{pattern}: NOT FOUND")
@@ -49,6 +55,9 @@ def print_found(section_table: SectionTable, pattern_names: Iterable[str], found
 
 @app.command()
 def main(path: Path) -> None:
+    """
+    Process the given portable executable file, print its checksum(time stamp) and offsets of the found patterns.
+    """
     patterns: list[Pattern] = load_patterns()
 
     with path.open("rb") as exe: