dao-treasury 0.0.32__cp310-cp310-musllinux_1_2_i686.whl → 0.0.33__cp310-cp310-musllinux_1_2_i686.whl

dao_treasury/sorting/__init__.py

@@ -1,5 +1,28 @@
 """
-This module contains logic for sorting transactions into various categories.
+This module provides the core logic for sorting DAO Treasury transactions into transaction groups (categories).
+
+Sorting enables comprehensive financial reporting and categorization tailored for on-chain organizations.
+Transactions are matched against either statically defined rules or more advanced dynamic rules based on user-defined matching functions.
+
+Sorting works by attempting matches in this order:
+  1. Check if the transaction is an internal transfer (within treasury wallets).
+  2. Check if the transaction is "Out of Range" (neither sender nor receiver was a treasury wallet at the time of the tx).
+  3. Match by transaction hash using registered HashMatchers.
+  4. Match by sender address using registered FromAddressMatchers.
+  5. Match by recipient address using registered ToAddressMatchers.
+  6. Assign "Must Sort Inbound" or "Must Sort Outbound" groups if part of treasury.
+  7. Raise an error if no match is found (unexpected case).
+
+See the complete [sort rules documentation](https://bobthebuidler.github.io/dao-treasury/sort_rules.html) for detailed explanations
+and examples on defining and registering sort rules.
+
+See Also:
+    :func:`dao_treasury.sorting.sort_basic`
+    :func:`dao_treasury.sorting.sort_basic_entity`
+    :func:`dao_treasury.sorting.sort_advanced`
+    :class:`dao_treasury.sorting.HashMatcher`
+    :class:`dao_treasury.sorting.FromAddressMatcher`
+    :class:`dao_treasury.sorting.ToAddressMatcher`
 """
 
 from logging import getLogger
@@ -72,16 +95,54 @@ INTERNAL_TRANSFER_TXGROUP_DBID: Final = TxGroup.get_dbid(
     name="Internal Transfer",
     parent=TxGroup.get_dbid("Ignore"),
 )
-# TODO: write a docstring
+"""Database ID for the 'Internal Transfer' transaction group.
+
+This group represents transactions that occur internally between treasury-owned wallets.
+Such internal movements of funds within the DAO's treasury do not require separate handling or reporting.
+
+See Also:
+    :class:`dao_treasury.db.TxGroup`
+"""
 
 OUT_OF_RANGE_TXGROUP_DBID = TxGroup.get_dbid(
     name="Out of Range", parent=TxGroup.get_dbid("Ignore")
 )
-# TODO: write a docstring
+"""Database ID for the 'Out of Range' transaction group.
+
+This category is assigned to transactions where neither the sender nor the recipient
+wallet are members of the treasury at the time of the transaction.
+
+See Also:
+    :class:`dao_treasury.db.TxGroup`
+"""
 
 
 def sort_basic(entry: LedgerEntry) -> TxGroupDbid:
-    # TODO: write docstring
+    """Determine the transaction group ID for a basic ledger entry using static matching.
+
+    The function attempts to categorize the transaction by testing:
+      - If both 'from' and 'to' addresses are treasury wallets (internal transfer).
+      - If neither ‘to’ address is a treasury wallet at the time of the transaction (out of range).
+      - If the transaction hash matches a known HashMatcher.
+      - If the 'from' address matches a FromAddressMatcher.
+      - If the 'to' address matches a ToAddressMatcher.
+      - Assignment to 'Must Sort Outbound' or 'Must Sort Inbound' groups if applicable.
+      - Raises `NotImplementedError` if none of the above conditions are met (should not happen).
+
+    Args:
+        entry: A ledger entry representing a blockchain transaction.
+
+    Examples:
+        >>> from eth_portfolio.structs import Transaction
+        >>> entry = Transaction(from_address="0xabc...", to_address="0xdef...", block_number=1234567)
+        >>> group_id = sort_basic(entry)
+        >>> print(group_id)
+
+    See Also:
+        :func:`sort_basic_entity`
+        :func:`sort_advanced`
+        :class:`dao_treasury.sorting.HashMatcher`
+    """
     from_address = entry.from_address
     to_address = entry.to_address
     block = entry.block_number
@@ -117,7 +178,25 @@ def sort_basic(entry: LedgerEntry) -> TxGroupDbid:
 
 
 def sort_basic_entity(tx: db.TreasuryTx) -> TxGroupDbid:
-    # TODO: write docstring
+    """Determine the transaction group ID for a TreasuryTx database entity using static matching.
+
+    Similar to :func:`sort_basic` but operates on a TreasuryTx entity from the database.
+    It considers additional constants such as `DISPERSE_APP` when determining whether
+    a transaction is out of range.
+
+    Args:
+        tx: A TreasuryTx database entity representing a treasury transaction.
+
+    Examples:
+        >>> from dao_treasury.db import TreasuryTx
+        >>> tx = TreasuryTx[123]
+        >>> group_id = sort_basic_entity(tx)
+        >>> print(group_id)
+
+    See Also:
+        :func:`sort_basic`
+        :func:`sort_advanced`
+    """
     from_address = tx.from_address.address
     to_address = tx.to_address
     block = tx.block
@@ -167,7 +246,31 @@ def sort_basic_entity(tx: db.TreasuryTx) -> TxGroupDbid:
 
 
 async def sort_advanced(entry: db.TreasuryTx) -> TxGroupDbid:
-    # TODO: write docstring
+    """Determine the transaction group ID for a TreasuryTx entity using advanced dynamic rules.
+
+    Starts with the result of static matching via :func:`sort_basic_entity`, then
+    applies advanced asynchronous matching rules registered under :data:`SORT_RULES`.
+    Applies rules sequentially until a match is found or all rules are exhausted.
+
+    If a rule's match attempt raises a `ContractNotVerified` exception, the rule is skipped.
+
+    Updates the TreasuryTx entity's transaction group in the database when a match
+    other than 'Must Sort Inbound/Outbound' is found.
+
+    Args:
+        entry: A TreasuryTx database entity representing a treasury transaction.
+
+    Examples:
+        >>> from dao_treasury.db import TreasuryTx
+        >>> import asyncio
+        >>> tx = TreasuryTx[123]
+        >>> group_id = asyncio.run(sort_advanced(tx))
+        >>> print(group_id)
+
+    See Also:
+        :func:`sort_basic_entity`
+        :data:`SORT_RULES`
+    """
     txgroup_dbid = sort_basic_entity(entry)
 
     if txgroup_dbid in (

{dao_treasury-0.0.32.dist-info → dao_treasury-0.0.33.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dao_treasury
-Version: 0.0.32
+Version: 0.0.33
 Summary: Produce comprehensive financial reports for your on-chain org
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -14,7 +14,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10,<3.13
 Description-Content-Type: text/markdown
-Requires-Dist: eth-portfolio-temp<0.1,>=0.0.29.dev0
+Requires-Dist: eth-portfolio-temp<0.1,>=0.0.30.dev0
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type

{dao_treasury-0.0.32.dist-info → dao_treasury-0.0.33.dist-info}/RECORD

@@ -1,4 +1,4 @@
-bf2b4fe1f86ad2ea158b__mypyc.cpython-310-i386-linux-gnu.so,sha256=FVv9J-fNBNm_lACMzRRx-1JLOAEOreVPZO5Y-i1HTdA,1454192
+bf2b4fe1f86ad2ea158b__mypyc.cpython-310-i386-linux-gnu.so,sha256=dMzZrXy-1JCQsHSuY4OiPpgSC36NIb_eK-TtsKhUXTc,1454196
 dao_treasury/ENVIRONMENT_VARIABLES.py,sha256=yKvgOMUyU7-fF_-1zSMXML7ah7-r2f0oHrOV0p10LPc,195
 dao_treasury/__init__.py,sha256=ZQ0ZROQzSyJdYuQS1Z_VD0c7CiV8BWZcLTX66wO4slc,1004
 dao_treasury/_docker.cpython-310-i386-linux-gnu.so,sha256=CN3BW4fzOrm_JFh-7OJn2sTkLUQdd5vWMrB53LnuH98,16572
@@ -9,22 +9,24 @@ dao_treasury/_wallet.cpython-310-i386-linux-gnu.so,sha256=ZBqDRhPMRPRLIoDb1gzeUf
 dao_treasury/_wallet.py,sha256=sIeUsyu9Y8MmOm-9bfwIEYjJ9Owgv1GXdTLZpcXMnCg,10338
 dao_treasury/constants.cpython-310-i386-linux-gnu.so,sha256=4AaK5_3W297jgmdDNcgnpjV3Xzi21k83RlrdhM0U9sY,16580
 dao_treasury/constants.py,sha256=IFg_CyVnfPhPjKyFX1Ix4QaB8ghbOI5QZGSy2TNsUSA,507
-dao_treasury/db.py,sha256=pGz4C2OmxHI9CyrphbFzs04aiVP_VQeViaavCiJuR3o,44831
+dao_treasury/db.py,sha256=F-ZZQ21KCTCNusOgQADIMXl1mpuuI7g26nCV2Y7U8Yk,46136
 dao_treasury/docker-compose.yaml,sha256=Q6NPNT9iKkKOehDcKtxltvQjbxZuXmb51Tjwb1M21_I,1376
 dao_treasury/main.py,sha256=31EA10Fpaj9y-cRJPnNnvCBI38UM0848xlzn7A0BzC4,8047
 dao_treasury/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dao_treasury/treasury.py,sha256=7xLVQPqnDd3cexbYuF1opTjCiHgkPqHFOanRom8wiLE,6506
 dao_treasury/types.cpython-310-i386-linux-gnu.so,sha256=-Wlq5_Bt9wAXmHm-_6Po-ZgKddgEuB5POyN9doSa1uA,16564
 dao_treasury/types.py,sha256=dJDx0hYfDDL3slcUzRnCgrzFFsgCzoqg8uaTtLaT4kk,3685
-dao_treasury/.grafana/provisioning/dashboards/dashboards.yaml,sha256=ecu7lHpcrYFTSEHbZErX63mn2CFPqEXcprtcYDcHPSo,713
+dao_treasury/.grafana/provisioning/dashboards/dashboards.yaml,sha256=tr6FBJeAAPX76db8E3qBBVWnq2-yrWDXDGuclMDg6dw,1277
 dao_treasury/.grafana/provisioning/dashboards/streams/LlamaPay.json,sha256=7bDAboObB2LsY6EicAL-DAC0HKIaSRVW6AbGzmy_xUI,3403
-dao_treasury/.grafana/provisioning/dashboards/summary/Monthly.json,sha256=y7t4O0ujImcfVULGsV_0WxcZCm7sz1jtAB5ZXUfPww4,7911
-dao_treasury/.grafana/provisioning/dashboards/transactions/Treasury Transactions.json,sha256=2IuiXuDGAx_PUAFiiu5omNntDpidi8axXEUXLcvA_b8,15974
-dao_treasury/.grafana/provisioning/dashboards/treasury/Cashflow.json,sha256=52LHxaxfPj5NoPB1guTvayd08ETIfFjlydBsoywnxjI,42349
+dao_treasury/.grafana/provisioning/dashboards/summary/Monthly.json,sha256=O6ghjzBf333baPjuMuUNguxF2v6rvPCiOu39sm1zxxY,6533
+dao_treasury/.grafana/provisioning/dashboards/transactions/Treasury Transactions.json,sha256=jefr19wdT7r2zNXOG_3GzKDaq3WFIQkou8veHxkisnY,13230
+dao_treasury/.grafana/provisioning/dashboards/treasury/Cashflow (Including Unsorted).json,sha256=lpSE0g8lU9rEPMUxJPo1ObkHk_B2Qvp8LMrJEMzeYSk,25530
+dao_treasury/.grafana/provisioning/dashboards/treasury/Cashflow.json,sha256=DOpO3leNVyUUQD5ou5FkdGCGc1xJmCRQjuzSUCvBnGU,18139
+dao_treasury/.grafana/provisioning/dashboards/treasury/Operating Cashflow.json,sha256=xGQTzjF9dKzV3QSifRAbU5eGz2SrzJ7MJlmQKcFq5TE,14311
 dao_treasury/.grafana/provisioning/dashboards/treasury/Treasury.json,sha256=p9bupL06-CKqkqCOb6KkgP1LCa6P1VMkq3yhkyqMAzI,70178
 dao_treasury/.grafana/provisioning/datasources/datasources.yaml,sha256=mjQs8or651NgD_bZnKBm8vSghzjw_g3enL01YPt0dik,327
 dao_treasury/sorting/__init__.cpython-310-i386-linux-gnu.so,sha256=GDRmThf4QH7gQJY8MJcrRs6ee4LckBBGd8gRXaWMWTU,16572
-dao_treasury/sorting/__init__.py,sha256=F_yKKdpdHKGH5RRt-8cZ-M1CuHFI_XvSypnE0YHdovo,5785
+dao_treasury/sorting/__init__.py,sha256=vKj3NPB7EWbX7_fSUWKXk-NsyPasOkFhJvJVGclBOAE,10371
 dao_treasury/sorting/_matchers.cpython-310-i386-linux-gnu.so,sha256=bVwimtyQO0coY3j6yV3qYlAunOgjJ6Jnm1PhJC2v_9s,16596
 dao_treasury/sorting/_matchers.py,sha256=u0GfPYiODr_NtzbfyLxEKDuXmWRiaeuZulDj9FPDOH8,14005
 dao_treasury/sorting/_rules.cpython-310-i386-linux-gnu.so,sha256=chyA1u_nEQ0nkndcRGWi1grHbjtsKoO7nq8s2i_nzzU,16580
@@ -43,7 +45,7 @@ dao_treasury/streams/__init__.cpython-310-i386-linux-gnu.so,sha256=CSSJTizhz2lhW
 dao_treasury/streams/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dao_treasury/streams/llamapay.cpython-310-i386-linux-gnu.so,sha256=WeyPGWhuevhvC0Is5A9uZoNjg8e18bgsWOs14pZcYUA,16588
 dao_treasury/streams/llamapay.py,sha256=xc2sgmTV4EnQFFemea87QoUdIeGtO9OJQCwJG9c-SJQ,12774
-dao_treasury-0.0.32.dist-info/METADATA,sha256=CtChVdcnb51eL9ngQP9PEA_D4uYWnelEtQuAUkD9G_g,7030
-dao_treasury-0.0.32.dist-info/WHEEL,sha256=U4i16otdlfBhNVHGS7XHFbWxUW-DEunqf9S09fwcX-w,110
-dao_treasury-0.0.32.dist-info/top_level.txt,sha256=Gw-ri_26lZA_3hwhnOX48mffUbmBGr8NhtoQ0XoMeF8,41
-dao_treasury-0.0.32.dist-info/RECORD,,
+dao_treasury-0.0.33.dist-info/METADATA,sha256=oVCiHn3_IVPb94PL9AgbZGva7AU88_vmhfO8VU1r2Qk,7030
+dao_treasury-0.0.33.dist-info/WHEEL,sha256=U4i16otdlfBhNVHGS7XHFbWxUW-DEunqf9S09fwcX-w,110
+dao_treasury-0.0.33.dist-info/top_level.txt,sha256=Gw-ri_26lZA_3hwhnOX48mffUbmBGr8NhtoQ0XoMeF8,41
+dao_treasury-0.0.33.dist-info/RECORD,,