dao-treasury 0.0.10__cp310-cp310-win32.whl → 0.0.70__cp310-cp310-win32.whl

dao_treasury/sorting/_matchers.py

@@ -14,12 +14,55 @@ logger: Final = getLogger("dao_treasury")
 
 
 class _Matcher:
+    """Base class for matching strings to a transaction group identifier.
+
+    Each subclass maintains a registry of instances and a cache for fast lookups.
+    Matching is performed by testing membership via `__contains__`.
+
+    Examples:
+        >>> from dao_treasury.sorting._matchers import FromAddressMatcher
+        >>> from dao_treasury.types import TxGroupDbid
+        >>> address = "0xAbC1230000000000000000000000000000000000"
+        >>> fam = FromAddressMatcher(TxGroupDbid(1), [address])
+        >>> FromAddressMatcher.match(address)
+        TxGroupDbid(1)
+        >>> FromAddressMatcher.match("missing")
+        None
+
+    See Also:
+        :class:`dao_treasury.sorting._matchers._HexStringMatcher`,
+        :class:`dao_treasury.sorting._matchers._AddressMatcher`,
+        :meth:`match`
+    """
+
     __instances__: ClassVar[List[Self]]
     __cache__: ClassVar[Dict[str, TxGroupDbid]]
 
     @classmethod
     def match(cls, string: str) -> Optional[TxGroupDbid]:
         # sourcery skip: use-next
+        """Return the TxGroupDbid for a matching instance or None if no match.
+
+        The lookup first checks the internal cache, then iterates through
+        all instances and tests membership with `__contains__`. On first hit,
+        the result is cached for future calls.
+
+        Args:
+            string: Input string to match (e.g., address or hash).
+
+        Examples:
+            >>> from dao_treasury.sorting._matchers import HashMatcher
+            >>> from dao_treasury.types import TxGroupDbid
+            >>> hash_str = "0xdeadbeef" + "00"*28
+            >>> hmatch = HashMatcher(TxGroupDbid(2), [hash_str])
+            >>> HashMatcher.match(hash_str)
+            TxGroupDbid(2)
+            >>> HashMatcher.match("0xother")
+            None
+
+        See Also:
+            :attr:`__cache__`
+        """
         try:
             return cls.__cache__[string]
         except KeyError:
@@ -31,45 +74,158 @@ class _Matcher:
             return None
 
     def __init__(self, txgroup: TxGroupDbid, validated_values: Set[str]) -> None:
+        """Initialize matcher with a txgroup and a set of validated strings.
+
+        Ensures that the txgroup identifier is unique among instances.
+
+        Args:
+            txgroup: Identifier of the transaction group.
+            validated_values: Set of unique, pre-validated strings for matching.
+
+        Raises:
+            TypeError: If txgroup is not an integer.
+            ValueError: If an instance for the same txgroup already exists.
+
+        See Also:
+            :attr:`txgroup_id`
+        """
         if not isinstance(txgroup, int):
             raise TypeError(txgroup)
-        
+
         for matcher in self.__instances__:
             if matcher.txgroup_id == txgroup:
-                raise ValueError(f"TxGroup[{txgroup}] already has a {type(self).__name__}: {matcher}")
+                raise ValueError(
+                    f"TxGroup[{txgroup}] already has a {type(self).__name__}: {matcher}"
+                )
         self.txgroup_id: Final[TxGroupDbid] = txgroup
-        
+
         self.__one_value: Final = len(validated_values) == 1
         self.__value: Final = list(validated_values)[0] if self.__one_value else ""
         self.__values: Final = validated_values
-    
+
     def __contains__(self, string: str) -> bool:
+        """Return True if the given string matches one of the validated values.
+
+        For a single-value matcher, performs equality; otherwise membership.
+
+        Args:
+            string: Input to test for membership.
+
+        See Also:
+            :meth:`match`
+        """
         return string == self.__value if self.__one_value else string in self.values
-    
+
     @property
     def values(self) -> Set[HexStr]:
+        """Set of all validated strings used for matching.
+
+        Returns:
+            The original set of strings passed at initialization.
+
+        Example:
+            >>> from dao_treasury.sorting._matchers import HashMatcher
+            >>> from dao_treasury.types import TxGroupDbid
+            >>> hex_str = "0x" + "f"*64
+            >>> matcher = HashMatcher(TxGroupDbid(4), [hex_str])
+            >>> matcher.values
+            {'0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff'}
+
+        See Also:
+            :meth:`match`
+        """
         return self.__values
 
 
 class _HexStringMatcher(_Matcher):
+    """Matcher for fixed-length hexadecimal strings.
+
+    Validates and normalizes hex strings (must start with “0x”, lowercase)
+    to the length specified by :attr:`expected_length`.
+
+    See Also:
+        :attr:`expected_length`,
+        :meth:`_validate_hexstr`
+    """
+
     expected_length: ClassVar[int]
 
     @classmethod
     def _validate_hexstr(cls, hexstr: HexStr) -> HexStr:
+        """Validate that input is a hex string of length `expected_length`.
+
+        Normalizes to lowercase and prepends '0x' if necessary.
+
+        Args:
+            hexstr: Candidate hex string.
+
+        Raises:
+            ValueError: If not a valid hex string or wrong length.
+
+        See Also:
+            :attr:`expected_length`
+        """
         if not is_hexstr(hexstr):
             raise ValueError(f"value must be a hex string, not {hexstr}")
         hexstr = hexstr.lower()
         if not hexstr.startswith("0x"):
             hexstr = f"0x{hexstr}"
         if len(hexstr) != cls.expected_length:
-            raise ValueError(f"{hexstr} has incorrect length (expected {cls.expected_length}, actual {len(hexstr)})")
+            raise ValueError(
+                f"{hexstr} has incorrect length (expected {cls.expected_length}, actual {len(hexstr)})"
+            )
         return hexstr
 
 
 class _AddressMatcher(_HexStringMatcher):
+    """Matcher for Ethereum addresses, mapping them to a TxGroupDbid.
+
+    Ensures each address is unique across all matchers.
+
+    Examples:
+        >>> from dao_treasury.sorting._matchers import _AddressMatcher
+        >>> from dao_treasury.types import TxGroupDbid
+        >>> addr = "0xAbC1230000000000000000000000000000000000"
+        >>> am = _AddressMatcher(TxGroupDbid(5), [addr])
+        >>> addr in am
+        True
+        >>> "0x0000000000000000000000000000000000000000" in am
+        False
+
+    See Also:
+        :class:`FromAddressMatcher`,
+        :class:`ToAddressMatcher`
+    """
+
     expected_length: ClassVar[int] = 42
-        
+
     def __init__(self, txgroup: TxGroupDbid, addresses: Iterable[HexAddress]) -> None:
+        """Create an address matcher with checksum validation.
+
+        Converts inputs to checksummed addresses and ensures that each address is only
+        registered once. Duplicate addresses in the input iterable will log a warning,
+        but only the first occurrence is used.
+
+        Args:
+            txgroup: Identifier of the transaction group.
+            addresses: Iterable of hex address strings.
+
+        Raises:
+            ValueError: If `addresses` is empty, or if any address already has an
+                existing matcher.
+
+        Examples:
+            >>> from dao_treasury.sorting._matchers import _AddressMatcher
+            >>> from dao_treasury.types import TxGroupDbid
+            >>> addr = "0xAbC1230000000000000000000000000000000000"
+            >>> # duplicate in list triggers warning but does not raise
+            >>> am = _AddressMatcher(TxGroupDbid(5), [addr, addr])
+            >>> addr in am
+            True
+
+        See Also:
+            :meth:`_validate_hexstr`
+        """
         addresses = list(addresses)
         if not addresses:
             raise ValueError("You must provide at least one address")
@@ -79,43 +235,119 @@ class _AddressMatcher(_HexStringMatcher):
             address = convert.to_address(self._validate_hexstr(address))
             for matcher in self.__instances__:
                 if address in matcher:
-                    raise ValueError(f"address {address} already has a matcher: {matcher}")
+                    raise ValueError(
+                        f"address {address} already has a matcher: {matcher}"
+                    )
             if address in validated:
-                logger.warning("duplicate hash %s", address)
+                logger.warning("duplicate address %s", address)
             validated.add(address)
-        
+
         super().__init__(txgroup, validated)
 
         logger.info("%s created", self)
         self.__instances__.append(self)  # type: ignore [arg-type]
-    
+
     @db_session  # type: ignore [misc]
     def __repr__(self) -> str:
+        """Return a string representation including the full txgroup path and addresses.
+
+        Queries the database for the TxGroup entity to show its full path.
+
+        Examples:
+            >>> from dao_treasury.sorting._matchers import FromAddressMatcher
+            >>> from dao_treasury.types import TxGroupDbid
+            >>> fam = FromAddressMatcher(TxGroupDbid(6), ["0xAbC1230000000000000000000000000000000000"])
+            >>> repr(fam)
+            "FromAddressMatcher(txgroup='Parent:Child', addresses=['0xAbC1230000000000000000000000000000000000'])"
+        """
         from dao_treasury.db import TxGroup
 
         txgroup = TxGroup.get(txgroup_id=self.txgroup_id)
-        return f"{type(self).__name__}(txgroup='{txgroup.full_string}', addresses={list(self.values)})"
+        return f"{type(self).__name__}(txgroup='{txgroup.fullname}', addresses={list(self.values)})"
 
 
 @final
 class FromAddressMatcher(_AddressMatcher):
+    """Final matcher that categorizes by transaction `from_address`.
+
+    Examples:
+        >>> from dao_treasury.sorting._matchers import FromAddressMatcher
+        >>> from dao_treasury.types import TxGroupDbid
+        >>> address = "0xAbC1230000000000000000000000000000000000"
+        >>> fam = FromAddressMatcher(TxGroupDbid(7), [address])
+        >>> FromAddressMatcher.match(address)
+        TxGroupDbid(7)
+    """
+
     __instances__: ClassVar[List["FromAddressMatcher"]] = []
     __cache__: ClassVar[Dict[ChecksumAddress, TxGroupDbid]] = {}
 
 
 @final
 class ToAddressMatcher(_AddressMatcher):
+    """Final matcher that categorizes by transaction `to_address`.
+
+    Examples:
+        >>> from dao_treasury.sorting._matchers import ToAddressMatcher
+        >>> from dao_treasury.types import TxGroupDbid
+        >>> address = "0xDef4560000000000000000000000000000000000"
+        >>> tam = ToAddressMatcher(TxGroupDbid(8), [address])
+        >>> ToAddressMatcher.match(address)
+        TxGroupDbid(8)
+    """
+
     __instances__: ClassVar[List["ToAddressMatcher"]] = []
     __cache__: ClassVar[Dict[ChecksumAddress, TxGroupDbid]] = {}
 
 
 @final
 class HashMatcher(_HexStringMatcher):
+    """Final matcher that categorizes by transaction hash.
+
+    Matches full 66-character hex transaction hashes.
+
+    Examples:
+        >>> from dao_treasury.sorting._matchers import HashMatcher
+        >>> from dao_treasury.types import TxGroupDbid
+        >>> hash_str = '0x' + 'f' * 64
+        >>> hm = HashMatcher(TxGroupDbid(9), [hash_str])
+        >>> HashMatcher.match(hash_str)
+        TxGroupDbid(9)
+        >>> repr(hm)
+        "HashMatcher(txgroup='Root:Group', hashes=['0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff'])"
+    """
+
     expected_length: ClassVar[int] = 66
     __instances__: ClassVar[List["HashMatcher"]] = []
     __cache__: ClassVar[Dict[HexStr, TxGroupDbid]] = {}
-        
-    def __init__(self, txgroup: TxGroupDbid, hashes: Iterable[HexStr]) -> None:        
+
+    def __init__(self, txgroup: TxGroupDbid, hashes: Iterable[HexStr]) -> None:
+        """Initialize hash matcher ensuring unique transaction hashes.
+
+        Validates and normalizes hashes to fixed length, and ensures that each hash is
+        only registered once. Duplicate hashes in the input iterable will log a warning,
+        but only the first occurrence is used.
+
+        Args:
+            txgroup: Identifier of the transaction group.
+            hashes: Iterable of hex string hashes.
+
+        Raises:
+            ValueError: If `hashes` is empty, or if any hash already has an existing
+                matcher.
+
+        Examples:
+            >>> from dao_treasury.sorting._matchers import HashMatcher
+            >>> from dao_treasury.types import TxGroupDbid
+            >>> hash_str = '0x' + 'f' * 64
+            >>> # duplicate in list logs warning but does not raise
+            >>> hm = HashMatcher(TxGroupDbid(9), [hash_str, hash_str])
+            >>> HashMatcher.match(hash_str)
+            TxGroupDbid(9)
+
+        See Also:
+            :meth:`_validate_hexstr`
+        """
         hashes = list(hashes)
         if not hashes:
             raise ValueError("You must provide at least one transaction hash")
@@ -129,15 +361,27 @@ class HashMatcher(_HexStringMatcher):
             if txhash in validated:
                 logger.warning("duplicate hash %s", txhash)
             validated.add(txhash)
-        
+
         super().__init__(txgroup, validated)
 
         logger.info("%s created", self)
         HashMatcher.__instances__.append(self)
-    
+
     @db_session  # type: ignore [misc]
     def __repr__(self) -> str:
+        """Return a string representation including the full txgroup path and hashes.
+
+        Queries the database for the TxGroup entity to show its full path.
+
+        Examples:
+            >>> from dao_treasury.sorting._matchers import HashMatcher
+            >>> from dao_treasury.types import TxGroupDbid
+            >>> hash_str = '0x' + 'f' * 64
+            >>> hm = HashMatcher(TxGroupDbid(10), [hash_str])
+            >>> repr(hm)
+            "HashMatcher(txgroup='Root:Group', hashes=['0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff'])"
+        """
         from dao_treasury.db import TxGroup
 
         txgroup = TxGroup.get(txgroup_id=self.txgroup_id)
-        return f"{type(self).__name__}(txgroup='{txgroup.full_string}', hashes={list(self.values)})"
+        return f"{type(self).__name__}(txgroup='{txgroup.fullname}', hashes={list(self.values)})"

dao_treasury/sorting/_rules.py

@@ -4,20 +4,73 @@ from typing import Final, Type, Union, final
 
 import yaml
 from pony.orm import db_session
-from y import constants
 
-from dao_treasury.sorting import _Matcher, FromAddressMatcher, HashMatcher, ToAddressMatcher
+from dao_treasury.constants import CHAINID
+from dao_treasury.sorting import (
+    _Matcher,
+    FromAddressMatcher,
+    HashMatcher,
+    ToAddressMatcher,
+)
 from dao_treasury.types import TopLevelCategory, TxGroupDbid
 
 
-CHAINID: Final = constants.CHAINID
-
 logger: Final = getLogger("dao_treasury.rules")
 
 
 @final
 class Rules:
+    """Loader for transaction‐sorting rule matchers defined in YAML files.
+
+    This class discovers and instantiates matchers based on simple YAML definitions
+    organized under subdirectories for each top‐level category in a given base path.
+
+    The expected directory layout is:
+
+        base_path/
+            revenue/
+            cost_of_revenue/
+            expenses/
+            other_income/
+            other_expense/
+            ignore/
+
+    Under each category directory, files named `match_on_hash.(yml|yaml)`,
+    `match_on_from_address.(yml|yaml)`, and `match_on_to_address.(yml|yaml)`
+    define mappings of subgroup names to lists or nested dicts of values keyed by
+    the active chain ID.
+
+    Upon initialization, all available matchers are built exactly once and registered
+    in the global in‐memory registry, allowing transactions to be routed to the
+    appropriate `TxGroup` by hash, sender address, or recipient address.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> from dao_treasury.sorting._rules import Rules
+        >>> rules = Rules(Path("config/sorting_rules"))
+        # If config/sorting_rules/revenue/match_on_hash.yml contains:
+        #   1:
+        #     DonationReceived:
+        #       - 0xabc123...
+        # Then this creates a `TxGroup` named "Revenue:DonationReceived"
+        # and a `HashMatcher` that routes hash "0xabc123..." accordingly.
+
+    See Also:
+        :class:`dao_treasury.sorting.HashMatcher`
+        :class:`dao_treasury.sorting.FromAddressMatcher`
+        :class:`dao_treasury.sorting.ToAddressMatcher`
+    """
+
     def __init__(self, path: Path):
+        """Initialize rule directories and build matchers.
+
+        Args:
+            path: Base directory containing subdirectories for each top‐level category.
+
+        Example:
+            >>> from pathlib import Path
+            >>> rules = Rules(Path("/absolute/path/to/rules"))
+        """
         self.__initialized = False
         self.rules_dir: Final = path
         self.revenue_dir: Final = path / "revenue"
@@ -30,41 +83,115 @@ class Rules:
 
     @db_session  # type: ignore [misc]
     def __build_matchers(self) -> None:
+        """Scan all categories and rule types, instantiate matchers.
+
+        This method must only run once per `Rules` instance, raising a RuntimeError
+        if invoked again. It iterates over the three rule file prefixes and calls
+        :meth:`__build_matchers_for_all_groups` for each.
+
+        Raises:
+            RuntimeError: If this method is called more than once on the same object.
+
+        Example:
+            >>> rules = Rules(Path("rules_dir"))
+            # Second build attempt:
+            >>> rules._Rules__build_matchers()
+            RuntimeError: You cannot initialize the rules more than once
+        """
         if self.__initialized:
             raise RuntimeError("You cannot initialize the rules more than once")
         self.__build_matchers_for_all_groups("match_on_hash", HashMatcher)
-        self.__build_matchers_for_all_groups("match_on_from_address", FromAddressMatcher)
+        self.__build_matchers_for_all_groups(
+            "match_on_from_address", FromAddressMatcher
+        )
         self.__build_matchers_for_all_groups("match_on_to_address", ToAddressMatcher)
         self.__initialized = True
-    
-    def __build_matchers_for_all_groups(self, match_rules_filename: str, matcher_cls: Type[_Matcher]) -> None:
-        self.__build_matchers_for_group("Revenue", self.revenue_dir, match_rules_filename, matcher_cls)
-        self.__build_matchers_for_group("Cost of Revenue", self.cost_of_revenue_dir, match_rules_filename, matcher_cls)
-        self.__build_matchers_for_group("Expenses", self.expenses_dir, match_rules_filename, matcher_cls)
-        self.__build_matchers_for_group("Other Income", self.other_income_dir, match_rules_filename, matcher_cls)
-        self.__build_matchers_for_group("Other Expenses", self.other_expense_dir, match_rules_filename, matcher_cls)
-        self.__build_matchers_for_group("Ignore", self.ignore_dir, match_rules_filename, matcher_cls)
-    
+
+    def __build_matchers_for_all_groups(
+        self, match_rules_filename: str, matcher_cls: Type[_Matcher]
+    ) -> None:
+        """Register one type of matcher across all top‐level categories.
+
+        Args:
+            match_rules_filename: Base filename of the YAML rule files (without extension),
+                                  e.g. `"match_on_hash"`.
+            matcher_cls: Matcher class to instantiate
+                         (HashMatcher, FromAddressMatcher, or ToAddressMatcher).
+
+        This will call :meth:`__build_matchers_for_group` for each of the
+        fixed categories: Revenue, Cost of Revenue, Expenses, Other Income,
+        Other Expenses, Ignore.
+
+        Example:
+            >>> rules = Rules(Path("rules"))
+            >>> rules._Rules__build_matchers_for_all_groups("match_on_hash", HashMatcher)
+        """
+        self.__build_matchers_for_group(
+            "Revenue", self.revenue_dir, match_rules_filename, matcher_cls
+        )
+        self.__build_matchers_for_group(
+            "Cost of Revenue",
+            self.cost_of_revenue_dir,
+            match_rules_filename,
+            matcher_cls,
+        )
+        self.__build_matchers_for_group(
+            "Expenses", self.expenses_dir, match_rules_filename, matcher_cls
+        )
+        self.__build_matchers_for_group(
+            "Other Income", self.other_income_dir, match_rules_filename, matcher_cls
+        )
+        self.__build_matchers_for_group(
+            "Other Expenses", self.other_expense_dir, match_rules_filename, matcher_cls
+        )
+        self.__build_matchers_for_group(
+            "Ignore", self.ignore_dir, match_rules_filename, matcher_cls
+        )
+
     def __build_matchers_for_group(
-        self, 
-        top_level_name: TopLevelCategory, 
-        rules: Path, 
-        filename: str, 
+        self,
+        top_level_name: TopLevelCategory,
+        rules: Path,
+        filename: str,
         matcher_cls: Type[_Matcher],
     ) -> None:
+        """Load and instantiate matchers defined in a specific category directory.
+
+        This method locates `<filename>.yml` or `<filename>.yaml` under `rules`
+        and parses it. If the file is missing, it is skipped silently. If the file
+        is empty, a warning is logged. Otherwise:
+
+          1. Reads and YAML-parses the file.
+          2. Extracts the mapping for the current `CHAINID`.
+          3. For each subgroup name and its values (list or dict),
+             obtains or creates a child `TxGroup`, then instantiates `matcher_cls`
+             for the values.
+
+        Args:
+            top_level_name: Top‐level category name used as parent TxGroup
+                            (e.g. `"Revenue"`, `"Expenses"`, `"Ignore"`).
+            rules: Path to the directory containing the rule file.
+            filename: Base filename of the rules (no extension).
+            matcher_cls: Matcher class to register rules.
+
+        Raises:
+            ValueError: If the YAML mapping under the chain ID is neither a list nor a dict.
+        """
         try:
             matchers = self.__get_rule_file(rules, filename)
         except FileNotFoundError:
             return
-        
+
         from dao_treasury.db import TxGroup
 
-        parent: Union[TxGroup, TxGroupDbid] = TxGroup.get_or_insert(top_level_name, None)
+        parent: Union[TxGroup, TxGroupDbid] = TxGroup.get_or_insert(
+            top_level_name, None
+        )
         parsed = yaml.safe_load(matchers.read_bytes())
         if not parsed:
             logger.warning(f"no content in rule file: {rules}")
             return
-        
+
         matching_rules: dict = parsed.get(CHAINID, {})  # type: ignore [type-arg]
         for name, hashes in matching_rules.items():
             txgroup_dbid = TxGroup.get_dbid(name, parent)
@@ -81,6 +208,24 @@ class Rules:
                 raise ValueError(hashes)
 
     def __get_rule_file(self, path: Path, filename: str) -> Path:
+        """Locate a YAML rule file by trying `.yml` and `.yaml` extensions.
+
+        Args:
+            path: Directory in which to search.
+            filename: Base name of the file (no extension).
+
+        Returns:
+            Full `Path` to the found file.
+
+        Raises:
+            FileNotFoundError: If neither `<filename>.yml` nor `<filename>.yaml` exists.
+
+        Example:
+            >>> rules_dir = Path("rules/revenue")
+            >>> path = rules._Rules__get_rule_file(rules_dir, "match_on_hash")
+            >>> print(path.name)
+            match_on_hash.yaml
+        """
         for suffix in (".yml", ".yaml"):
             fullname = filename + suffix
             p = path / fullname