yaralyzer 1.0.8__py3-none-any.whl → 1.0.9__py3-none-any.whl

yaralyzer/encoding_detection/encoding_detector.py

@@ -1,4 +1,6 @@
-"""EncodingDetector class for managing chardet encoding detection."""
+"""
+`EncodingDetector` class for managing chardet encoding detection.
+"""
 from operator import attrgetter
 from typing import List
 
@@ -16,17 +18,36 @@ CONFIDENCE_SCORE_RANGE = range(0, 101)
 
 class EncodingDetector:
     """
-    Manager class to ease dealing with the chardet encoding detection library 'chardet'.
-    Each instance of this class manages a chardet.detect_all() scan on a single set of bytes.
+    Manager class to ease dealing with the encoding detection library `chardet`.
+
+    Each instance of this class manages a `chardet.detect_all()` scan on a single set of bytes.
+
+    Attributes:
+        bytes (bytes): The bytes to analyze.
+        bytes_len (int): The length of the bytes.
+        table (Table): A rich `Table` object summarizing the chardet results.
+        assessments (List[EncodingAssessment]): List of `EncodingAssessment` objects from `chardet` results.
+        unique_assessments (List[EncodingAssessment]): Unique assessments by encoding, highest confidence only.
+        raw_chardet_assessments (List[dict]): Raw list of dicts returned by `chardet.detect_all()`.
+        force_decode_assessments (List[EncodingAssessment]): Assessments above force decode threshold.
+        force_display_assessments (List[EncodingAssessment]): Assessments above force display threshold.
+        has_any_idea (Optional[bool]): `True` if `chardet` had any idea what the encoding might be,
+            `False` if not, `None` if `chardet` wasn't run yet.
+        force_display_threshold (float): `[class variable]` Default confidence threshold for forcing display
+            in decoded table.
+        force_decode_threshold (float): `[class variable]` Default confidence threshold for forcing a decode attempt.
     """
 
     # Default value for encodings w/confidences below this will not be displayed in the decoded table
     force_display_threshold = 20.0
-
     # Default value for what chardet.detect() confidence % should we force a decode with an obscure encoding.
     force_decode_threshold = 50.0
 
     def __init__(self, _bytes: bytes) -> None:
+        """
+        Args:
+            _bytes (bytes): The bytes to analyze with `chardet`.
+        """
         self.bytes = _bytes
         self.bytes_len = len(_bytes)
         self.table = _empty_chardet_results_table()
@@ -55,12 +76,20 @@ class EncodingDetector:
         self.force_display_assessments = self.assessments_above_confidence(type(self).force_display_threshold)
 
     def get_encoding_assessment(self, encoding: str) -> EncodingAssessment:
-        """If chardet produced one, return it, otherwise return a dummy node with confidence of 0."""
+        """
+        Get the `chardet` assessment for a specific encoding.
+
+        Args:
+            encoding (str): The encoding to look for.
+
+        Returns:
+            EncodingAssessment: Assessment for the given encoding if it exists, otherwise a dummy with 0 confidence.
+        """
         assessment = next((r for r in self.unique_assessments if r.encoding == encoding), None)
         return assessment or EncodingAssessment.dummy_encoding_assessment(encoding)
 
     def has_enough_bytes(self) -> bool:
-        """Return true if we have enough bytes to run chardet.detect()."""
+        """Return `True` if we have enough bytes to run `chardet.detect()`."""
         return self.bytes_len >= YaralyzerConfig.args.min_chardet_bytes
 
     def assessments_above_confidence(self, cutoff: float) -> List[EncodingAssessment]:
@@ -71,7 +100,7 @@ class EncodingDetector:
         return Padding(self.table, (0, 0, 0, 0))
 
     def _uniquify_results_and_build_table(self) -> None:
-        """Keep the highest result per encoding, ignoring the language chardet has indicated."""
+        """Keep the highest result per encoding, ignoring the language `chardet` has indicated."""
         already_seen_encodings = {}
 
         for i, result in enumerate(self.assessments):
@@ -91,7 +120,7 @@ class EncodingDetector:
         self.unique_assessments.sort(key=attrgetter('confidence'), reverse=True)
 
     def _set_empty_results(self) -> None:
-        """Set empty results for when chardet can't help us."""
+        """Set empty results for when `chardet` can't help us."""
         self.assessments = []
         self.unique_assessments = []
         self.raw_chardet_assessments = []
@@ -99,8 +128,8 @@ class EncodingDetector:
         self.force_display_assessments = []
 
 
-def _empty_chardet_results_table():
-    """Returns a fresh table."""
+def _empty_chardet_results_table() -> Table:
+    """Returns an empty `Table` with appropriate columns for `chardet` results."""
     table = Table(
         'Rank', 'Encoding', 'Confidence',
         title='chardet.detect results',

yaralyzer/helpers/bytes_helper.py

@@ -25,14 +25,15 @@ HEX_CHARS_PER_LINE = HEX_CHARS_PER_GROUP * HEX_GROUPS_PER_LINE
 
 
 def get_bytes_before_and_after_match(_bytes: bytes, match: re.Match, num_before=None, num_after=None) -> bytes:
-    r"""
+    """
     Get bytes before and after a regex match within a byte sequence.
 
     Args:
         _bytes (bytes): The full byte sequence.
-        match (re.Match): The regex match object.
-        num_before (int, optional): Number of bytes before the match to include. Defaults to config.
-        num_after (int, optional): Number of bytes after the match to include. Defaults to either config or num_before value.
+        match (re.Match): The regex `Match` object.
+        num_before (int, optional): Number of bytes before the match to include. Defaults to configured value.
+        num_after (int, optional): Number of bytes after the match to include. Defaults to either configured value
+            or the `num_before` arg value.
 
     Returns:
         bytes: The surrounding bytes including the match.
@@ -41,15 +42,15 @@ def get_bytes_before_and_after_match(_bytes: bytes, match: re.Match, num_before=
 
 
 def get_bytes_surrounding_range(_bytes: bytes, start_idx: int, end_idx: int, num_before=None, num_after=None) -> bytes:
-    r"""
+    """
     Get bytes surrounding a specified range in a byte sequence.
 
     Args:
         _bytes (bytes): The full byte sequence.
         start_idx (int): Start index of the range.
         end_idx (int): End index of the range.
-        num_before (int, optional): Number of bytes before the range. Defaults to config.
-        num_after (int, optional): Number of bytes after the range. Defaults to config.
+        num_before (int, optional): Number of bytes before the range. Defaults to configured value.
+        num_after (int, optional): Number of bytes after the range. Defaults to configured value.
 
     Returns:
         bytes: The surrounding bytes including the range.
@@ -87,8 +88,8 @@ def clean_byte_string(bytes_array: bytes) -> str:
 
 
 def rich_text_view_of_raw_bytes(_bytes: bytes, bytes_match: BytesMatch) -> Text:
-    r"""
-    Return a rich Text object of raw bytes, highlighting the matched bytes.
+    """
+    Return a rich `Text` object of raw bytes, highlighting the matched bytes.
 
     Args:
         _bytes (bytes): The full byte sequence.
@@ -110,7 +111,7 @@ def rich_text_view_of_raw_bytes(_bytes: bytes, bytes_match: BytesMatch) -> Text:
 
 
 def hex_view_of_raw_bytes(_bytes: bytes, bytes_match: BytesMatch) -> Text:
-    r"""
+    """
     Return a hexadecimal view of raw bytes, highlighting the matched bytes.
 
     Args:
@@ -129,7 +130,7 @@ def hex_view_of_raw_bytes(_bytes: bytes, bytes_match: BytesMatch) -> Text:
 
 
 def ascii_view_of_raw_bytes(_bytes: bytes, bytes_match: BytesMatch) -> Text:
-    r"""
+    """
     Return an ASCII view of raw bytes, highlighting the matched bytes.
 
     Args:
@@ -171,7 +172,7 @@ def ascii_view_of_raw_bytes(_bytes: bytes, bytes_match: BytesMatch) -> Text:
 
 
 def hex_text(_bytes: bytes) -> Text:
-    r"""
+    """
     Return a rich Text object of the hex string for the given bytes.
 
     Args:
@@ -184,7 +185,7 @@ def hex_text(_bytes: bytes) -> Text:
 
 
 def hex_string(_bytes: bytes) -> str:
-    r"""
+    """
     Return a hex string representation of the given bytes.
 
     Args:
@@ -197,8 +198,8 @@ def hex_string(_bytes: bytes) -> str:
 
 
 def print_bytes(bytes_array: bytes, style=None) -> None:
-    r"""
-    Print a string representation of bytes to the console.
+    """
+    Print a string representation of some bytes to the console.
 
     Args:
         bytes_array (bytes): The bytes to print.
@@ -209,7 +210,7 @@ def print_bytes(bytes_array: bytes, style=None) -> None:
 
 
 def truncate_for_encoding(_bytes: bytes, encoding: str) -> bytes:
-    r"""
+    """
     Truncate bytes to a multiple of the character width for the given encoding.
     For example, for utf-16 this means truncating to a multiple of 2, for utf-32 to a multiple of 4.
 
@@ -246,8 +247,8 @@ def _find_str_rep_of_bytes(surrounding_bytes_str: str, highlighted_bytes_str: st
         int: The index in the surrounding string where the highlighted bytes start, or -1 if not found.
     """
     # Start a few chars in to avoid errors: sometimes we're searching for 1 or 2 bytes and there's a false positive
-    # in the extra bytes. Tthis isn't perfect - it's starting us at the first index into the *bytes* that's safe to
-    # check but this is almost certainly far too soon given the large % of bytes that take 4 chars to print ('\x02' etc)
+    # in the extra bytes. This isn't perfect - it's starting us at the first index into the *bytes* that's safe to
+    # check but this is almost certainly too soon given the large % of bytes that take 4 chars to print ('\x02' etc)
     highlight_idx = surrounding_bytes_str.find(highlighted_bytes_str, highlighted_bytes.highlight_start_idx)
 
     # TODO: Somehow \' and ' don't always come out the same :(

yaralyzer/helpers/file_helper.py

@@ -3,16 +3,21 @@ Helper methods to work with files.
 """
 from datetime import datetime
 from os import listdir, path
+from pathlib import Path
 from typing import List, Optional
 
 
-def timestamp_for_filename() -> str:
-    """Returns a string showing current time in a file name friendly format."""
-    return datetime.now().strftime("%Y-%m-%dT%H.%M.%S")
+def files_in_dir(dir: Path | str, with_extname: Optional[str] = None) -> List[str]:
+    """
+    Returns paths for all non dot files in `dir` (optionally filtered to only those ending in 'with_extname').
 
+    Args:
+        dir (str): Directory to list files from.
+        with_extname (Optional[str], optional): If set, only return files with this extension. Defaults to None.
 
-def files_in_dir(dir: str, with_extname: Optional[str] = None) -> List[str]:
-    """paths for non dot files, optionally ending in 'with_extname'."""
+    Returns:
+        List[str]: List of file paths.
+    """
     files = [path.join(dir, path.basename(file)) for file in listdir(dir) if not file.startswith('.')]
     files = [file for file in files if not path.isdir(file)]
 
@@ -23,20 +28,22 @@ def files_in_dir(dir: str, with_extname: Optional[str] = None) -> List[str]:
 
 
 def files_with_extname(files: List[str], extname: str) -> List[str]:
+    """Return only files from the list that end with the given `extname`."""
     return [f for f in files if f.endswith(f".{extname}")]
 
 
-def load_word_list(file_path):
-    """For very simple files (1 col CSVs, if you will)."""
-    with open(file_path, 'r') as f:
-        return [line.rstrip().lstrip() for line in f.readlines()]
-
-
-def load_binary_data(file_path) -> bytes:
+def load_binary_data(file_path: Path | str) -> bytes:
+    """Load and return the raw `bytes` from a file."""
     with open(file_path, 'rb') as f:
         return f.read()
 
 
-def load_file(file_path) -> str:
+def load_file(file_path: Path | str) -> str:
+    """Load and return the text contents of a file."""
     with open(file_path, 'r') as f:
         return f.read()
+
+
+def timestamp_for_filename() -> str:
+    """Returns a string showing current time in a file name friendly format."""
+    return datetime.now().strftime("%Y-%m-%dT%H.%M.%S")

yaralyzer/helpers/rich_text_helper.py

@@ -1,10 +1,10 @@
 """
 Methods to handle turning various objects into Rich text/table/etc representations
 
-Rich colors: https://rich.readthedocs.io/en/stable/appendix/colors.html
+[Rich color names](https://rich.readthedocs.io/en/stable/appendix/colors.html)
 TODO: interesting colors # row_styles[0] = 'reverse bold on color(144)' <-
 """
-from typing import List, Union
+from typing import List, Optional, Union
 
 from rich.columns import Columns
 from rich.panel import Panel
@@ -38,15 +38,16 @@ DECODING_ERRORS_MSG = Text('Yes', style='dark_red dim')
 
 
 def na_txt(style: Union[str, Style] = 'white'):
+    """Standard N/A text for tables and such."""
     return Text('N/A', style=style)
 
 
-def prefix_with_style(_str: str, style: str, root_style=None) -> Text:
+def prefix_with_style(_str: str, style: str, root_style: Optional[Union[Style, str]] = None) -> Text:
     """Sometimes you need a Text() object to start plain lest the underline or whatever last forever."""
     return Text('', style=root_style or 'white') + Text(_str, style)
 
 
-def meter_style(meter_pct):
+def meter_style(meter_pct: float | int) -> str:
     """For coloring numbers between 0 and 100 (AKA pcts). Closer to 100 means greener, closer to 0.0 means bluer."""
     if meter_pct > 100 or meter_pct < 0:
         log.warning(f"Invalid meter_pct: {meter_pct}")
@@ -86,11 +87,6 @@ def reverse_color(style: Style) -> Style:
     return Style(color=style.bgcolor, bgcolor=style.color, underline=style.underline, bold=style.bold)
 
 
-def yaralyzer_show_color_theme() -> None:
-    """Script method to show yaralyzer's color theme. Invocable with 'yaralyzer_show_colors'."""
-    show_color_theme(YARALYZER_THEME_DICT)
-
-
 def show_color_theme(styles: dict) -> None:
     """Print all colors in 'styles' to screen in a grid"""
     console.print(Panel('The Yaralyzer Color Theme', style='reverse'))
@@ -119,3 +115,8 @@ def size_in_bytes_text(num_bytes: int) -> Text:
 def newline_join(texts: List[Text]) -> Text:
     """Join a list of Text objects with newlines between them."""
     return Text("\n").join(texts)
+
+
+def yaralyzer_show_color_theme() -> None:
+    """Script method to show yaralyzer's color theme. Invocable with 'yaralyzer_show_colors'."""
+    show_color_theme(YARALYZER_THEME_DICT)

yaralyzer/output/decoding_attempts_table.py

@@ -1,14 +1,20 @@
 """
-Methods to build the rich.table used to display decoding attempts of a given bytes array.
+Methods to build the `rich.table` used to display decoding attempts of a given bytes array.
 
-Final output should be rich.table of decoding attempts that are sorted like this:
+Final output should be a `rich.table` of decoding attempts that are sorted like this:
 
     1. String representation of undecoded bytes is always the first row
-    2. Encodings which chardet.detect() ranked as > 0% likelihood are sorted based on that confidence
+
+    2. Encodings which `chardet.detect()` ranked as > 0% likelihood are sorted based on that confidence
+
     3. Then the unchardetectable:
+
         1. Decodings that were successful, unforced, and new
-        2. Decodings that 'successful' but forced
+
+        2. Decodings that were "successful" but forced
+
         3. Decodings that were the same as other decodings
+
         4. Failed decodings
 """
 from collections import namedtuple
@@ -45,7 +51,7 @@ RAW_BYTES = Text('Raw', style=f"bytes")
 
 
 def new_decoding_attempts_table(bytes_match: BytesMatch) -> Table:
-    """Build a new rich Table with two rows, the raw and hex views of the bytes_match data."""
+    """Build a new rich `Table` with two rows, the raw and hex views of the `bytes_match` data."""
     table = Table(show_lines=True, border_style='bytes', header_style='decode.table_header')
 
     def add_col(title, **kwargs):
@@ -65,7 +71,18 @@ def new_decoding_attempts_table(bytes_match: BytesMatch) -> Table:
 
 
 def decoding_table_row(assessment: EncodingAssessment, is_forced: Text, txt: Text, score: float) -> DecodingTableRow:
-    """Build a table row for a decoding attempt."""
+    """
+    Build a table row for a decoding attempt.
+
+    Args:
+        assessment (EncodingAssessment): The `chardet` assessment for the encoding used.
+        is_forced (Text): Text indicating if the decode was forced.
+        txt (Text): The decoded string as a rich `Text` object (with highlighting).
+        score (float): The score to use for sorting this row in the table.
+
+    Returns:
+        DecodingTableRow: The constructed table row named tuple.
+    """
     return DecodingTableRow(
         assessment.encoding_label,
         assessment.confidence_text,
@@ -78,13 +95,30 @@ def decoding_table_row(assessment: EncodingAssessment, is_forced: Text, txt: Tex
     )
 
 
-def assessment_only_row(assessment: EncodingAssessment, score) -> DecodingTableRow:
-    """Build a row with just chardet assessment confidence data and no actual decoding attempt string."""
+def assessment_only_row(assessment: EncodingAssessment, score: float) -> DecodingTableRow:
+    """
+    Build a `DecodingTableRow` with just `chardet` assessment confidence data and no actual decoding attempt string.
+
+    Args:
+        assessment (EncodingAssessment): The `chardet` assessment for the encoding used.
+        score (float): The score to use for sorting this row within the table.
+
+    Returns:
+        DecodingTableRow: The constructed table row named tuple with no decoding attempt string.
+    """
     return decoding_table_row(assessment, na_txt(), DECODE_NOT_ATTEMPTED_MSG, score)
 
 
 def _hex_preview_subtable(bytes_match: BytesMatch) -> Table:
-    """Build a sub table for hex view (hex on one side, ascii on the other side)."""
+    """
+    Build a sub `Table` for hex view row (hex on one side, ascii on the other side).
+
+    Args:
+        bytes_match (BytesMatch): The `BytesMatch` object containing the bytes to display.
+
+    Returns:
+        Table: A `rich.table` with hex and ascii views of the bytes.
+    """
     hex_table = Table(
         'hex',
         'ascii',

yaralyzer/output/file_export.py

@@ -1,8 +1,10 @@
-"""Functions to export Yaralyzer results to various file formats."""
+"""
+Functions to export Yaralyzer results to various file formats.
+"""
 import json
 import time
 from os import path
-from typing import Optional
+from typing import Callable, Optional
 
 from rich.terminal_theme import TerminalTheme
 
@@ -52,7 +54,16 @@ _EXPORT_KWARGS = {
 
 
 def export_json(yaralyzer: Yaralyzer, output_basepath: Optional[str]) -> str:
-    """Export YARA scan results to JSON. Returns the path to the output file that was written."""
+    """
+    Export YARA scan results to JSON.
+
+    Args:
+        yaralyzer (Yaralyzer): The `Yaralyzer` object containing the results to export.
+        output_basepath (Optional[str]): Base path to write output to. Should have no file extension.
+
+    Returns:
+        str: Path data was exported to.
+    """
     output_path = f"{output_basepath or 'yara_matches'}.json"
 
     matches_data = [
@@ -67,11 +78,16 @@ def export_json(yaralyzer: Yaralyzer, output_basepath: Optional[str]) -> str:
     return output_path
 
 
-def invoke_rich_export(export_method, output_file_basepath) -> str:
+def invoke_rich_export(export_method: Callable, output_file_basepath: str) -> str:
     """
-    Announce the export, perform the export, announce completion.
-    export_method is a Rich.console.save_blah() method, output_file_path is file path w/no extname.
-    Returns the path to path data was exported to.
+    Announce the export, perform the export, and announce completion.
+
+    Args:
+        export_method (Callable): Usually a `Rich.console.save_whatever()` method
+        output_file_basepath (str): Path to write output to. Should have no file extension.
+
+    Returns:
+        str: Path data was exported to.
     """
     method_name = export_method.__name__
     extname = 'txt' if method_name == 'save_text' else method_name.split('_')[-1]

yaralyzer/output/file_hashes_table.py

@@ -19,15 +19,16 @@ def bytes_hashes_table(
     title_justify: str = LEFT
 ) -> Table:
     """
-    Build a Rich Table displaying the size, MD5, SHA1, and SHA256 hashes of a byte sequence.
+    Build a Rich `Table` displaying the size, MD5, SHA1, and SHA256 hashes of a byte sequence.
 
     Args:
-        bytes_or_bytes_info (Union[bytes, BytesInfo]): The bytes to hash, or a BytesInfo namedtuple with precomputed values.
-        title (Optional[str], optional): Optional title for the table. Defaults to None.
-        title_justify (str, optional): Justification for the table title. Defaults to LEFT.
+        bytes_or_bytes_info (Union[bytes, BytesInfo]): The `bytes` to hash, or a `BytesInfo`
+            namedtuple with precomputed values.
+        title (Optional[str], optional): Optional title for the table. Defaults to `None`.
+        title_justify (str, optional): Justification for the table title. Defaults to `"LEFT"`.
 
     Returns:
-        Table: A Rich Table object with the size and hash values.
+        Table: A Rich `Table` object with the size and hash values.
     """
     if isinstance(bytes_or_bytes_info, bytes):
         bytes_info = compute_file_hashes(bytes_or_bytes_info)
@@ -54,10 +55,10 @@ def compute_file_hashes(_bytes: bytes) -> BytesInfo:
     Compute the size, MD5, SHA1, and SHA256 hashes for a given byte sequence.
 
     Args:
-        _bytes (bytes): The bytes to hash.
+        _bytes (bytes): The `bytes` to hash.
 
     Returns:
-        BytesInfo: Namedtuple containing size, md5, sha1, and sha256 values.
+        BytesInfo: `BytesInfo` namedtuple containing size, md5, sha1, and sha256 values.
     """
     return BytesInfo(
         size=len(_bytes),
@@ -75,7 +76,7 @@ def compute_file_hashes_for_file(file_path) -> BytesInfo:
         file_path (str): Path to the file to hash.
 
     Returns:
-        BytesInfo: Namedtuple containing size, md5, sha1, and sha256 values for the file contents.
+        BytesInfo: `BytesInfo` namedtuple containing size, md5, sha1, and sha256 values for the file contents.
     """
     with open(file_path, 'rb') as file:
         return compute_file_hashes(file.read())

yaralyzer/output/regex_match_metrics.py

@@ -1,4 +1,6 @@
-"""RegexMatchMetrics class."""
+"""
+`RegexMatchMetrics` class.
+"""
 from collections import defaultdict
 
 from yaralyzer.decoding.bytes_decoder import BytesDecoder
@@ -7,13 +9,25 @@ from yaralyzer.util.logging import log
 
 class RegexMatchMetrics:
     """
-    Class to  measure what we enounter as we iterate over every single match of a relatively simple byte level regex.
-
-    (e.g. "bytes between quotes") against a relatively large pool of close to random encrypted binary data.
+    Class to measure what we enounter as we iterate over all matches of a relatively simple byte level regex.
 
     Things like how much many of our matched bytes were we able to decode easily vs. by force vs. not at all,
-    were some encodings have a higher pct of success than others (indicating part of our mystery data might be encoded
-    that way?
+    were some encodings have a higher pct of success than others (indicating part of our mystery data might be
+    encoded that way?
+
+    Example:
+        "Find bytes between quotes" against a relatively large pool of close to random encrypted binary data.
+
+    Attributes:
+        match_count (int): Total number of matches found.
+        bytes_matched (int): Total number of bytes matched across all matches.
+        matches_decoded (int): Number of matches where we were able to decode at least some of the matched bytes.
+        easy_decode_count (int): Number of matches where we were able to decode the matched bytes without forcing.
+        forced_decode_count (int): Number of matches where we were only able to decode the matched bytes by forcing.
+        undecodable_count (int): Number of matches where we were unable to decode any of the matched bytes.
+        skipped_matches_lengths (defaultdict): Dictionary mapping lengths of skipped matches to their counts.
+        bytes_match_objs (list): List of `BytesMatch` objects for all matches encountered.
+        per_encoding_stats (defaultdict): Dictionary mapping encoding names to their respective `RegexMatchMetrics`.
 
     TODO: use @dataclass decorator https://realpython.com/python-data-classes/
     """
@@ -30,12 +44,20 @@ class RegexMatchMetrics:
         self.per_encoding_stats = defaultdict(lambda: RegexMatchMetrics())
 
     def num_matches_skipped_for_being_empty(self) -> int:
+        """Number of matches skipped for being empty (0 length)."""
         return self.skipped_matches_lengths[0]
 
     def num_matches_skipped_for_being_too_big(self) -> int:
+        """Number of matches skipped for being too big to decode."""
         return sum({k: v for k, v in self.skipped_matches_lengths.items() if k > 0}.values())
 
     def tally_match(self, decoder: BytesDecoder) -> None:
+        """
+        Tally statistics from a `BytesDecoder` after it has processed a match.
+
+        Args:
+            decoder (BytesDecoder): The `BytesDecoder` that processed a match.
+        """
         log.debug(f"Tallying {decoder.bytes_match} ({len(decoder.decodings)} decodings)")
         self.match_count += 1
         self.bytes_matched += decoder.bytes_match.match_length

yaralyzer/output/rich_console.py

@@ -86,11 +86,6 @@ def console_width_possibilities():
     return [get_terminal_size().columns - 2, DEFAULT_CONSOLE_WIDTH]
 
 
-def console_width() -> int:
-    """Current width set in console obj."""
-    return console._width or 40
-
-
 # Maximize output width if YARALYZER_MAXIMIZE_WIDTH is set (also can changed with --maximize-width option)
 if is_invoked_by_pytest():
     CONSOLE_WIDTH = DEFAULT_CONSOLE_WIDTH
@@ -104,8 +99,8 @@ CONSOLE_PRINT_BYTE_WIDTH = int(CONSOLE_WIDTH / 4.0)
 console = Console(theme=YARALYZER_THEME, color_system='256', highlight=False, width=CONSOLE_WIDTH)
 
 
-def console_print_with_fallback(_string, style=None) -> None:
-    """Fallback to regular print() if there's a Markup issue."""
+def console_print_with_fallback(_string: Text | str, style=None) -> None:
+    """`rich.console.print()` with fallback to regular `print()` if there's a Rich Markup issue."""
     try:
         console.print(_string, style=style)
     except MarkupError:
@@ -113,13 +108,18 @@ def console_print_with_fallback(_string, style=None) -> None:
         print(_string.plain if isinstance(_string, Text) else _string)
 
 
-def theme_colors_with_prefix(prefix: str) -> List[Text]:
-    """Return a list of (name, style) Text objects for all styles in the theme that start with 'prefix'."""
-    return [Text(k, v) for k, v in YARALYZER_THEME.styles.items() if k.startswith(prefix)]
+def console_width() -> int:
+    """Current width set in `console` object."""
+    return console._width or 40
 
 
 def print_fatal_error_and_exit(error_message: str) -> None:
-    """Print a fatal error message in a panel and exit."""
+    """
+    Print a fatal error message in a `Panel` and exit.
+
+    Args:
+        error_message (str): The error message to display.
+    """
     console.line(1)
     print_header_panel(error_message, style='bold red reverse')
     console.line(1)
@@ -128,15 +128,17 @@ def print_fatal_error_and_exit(error_message: str) -> None:
 
 def print_header_panel(headline: str, style: str, expand: bool = True, padding: tuple = (0, 2)) -> None:
     """
-    Print a headline inside a styled Rich Panel to the console.
+    Print a headline inside a styled Rich `Panel` to the console.
 
     Args:
         headline (str): The text to display as the panel's headline.
         style (str): The style to apply to the panel (e.g., color, bold, reverse).
-        expand (bool, optional): Whether the panel should expand to the full console width. Defaults to True.
-        padding (tuple, optional): Padding around the panel content (top/bottom, left/right). Defaults to (0, 2).
-
-    Returns:
-        None
+        expand (bool, optional): Whether the panel should expand to the full console width. Defaults to `True`.
+        padding (tuple, optional): Padding around the panel content (top/bottom, left/right). Defaults to `(0, 2)`.
     """
     console.print(Panel(headline, box=box.DOUBLE_EDGE, style=style, expand=expand, padding=padding))
+
+
+def theme_colors_with_prefix(prefix: str) -> List[Text]:
+    """Return a list of (name, style) `Text` objects for all styles in the theme that start with `prefix`."""
+    return [Text(k, v) for k, v in YARALYZER_THEME.styles.items() if k.startswith(prefix)]