usaspending-orm 0.8.0__tar.gz → 0.9.0__tar.gz

{usaspending_orm-0.8.0 → usaspending_orm-0.9.0}/CHANGELOG.md

@@ -4,6 +4,90 @@ All notable changes to the USASpending ORM library are documented here.
 The format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.9.0] - 2026-07-30
+
+Adds the global transaction search: `client.transactions.search()` covers the
+`/search/spending_by_transaction/` endpoint with the full fluent filter set,
+mixed award-type categories, exact bucketed counts, and a `Transaction` model
+that reads both of the API's row shapes.
+
+**Breaking changes**
+
+- `TransactionsSearch` is renamed to `AwardTransactionsSearch`. The freed name is
+  reused in this release for the new global `/search/spending_by_transaction/`
+  builder, so code importing `TransactionsSearch` directly keeps importing
+  cleanly but gets a different class rather than an `ImportError`. No
+  deprecation alias is provided. `client.transactions.award_id()` and
+  `award.transactions` are unchanged in both behavior and return value; only the
+  class and module names moved.
+
+- `Transaction.transaction_amount` and its alias `amt` now return the first
+  nonzero of `federal_action_obligation`, `face_value_loan_guarantee` and
+  `original_loan_subsidy_cost`, and return the zero when every figure the row
+  carries is zero. Previously a zero obligation read as no value at all, so a
+  genuine zero-dollar transaction was indistinguishable from a row carrying no
+  amount, and a loan row, which reports a zero obligation with the real figure
+  in the loan fields, reported nothing. Negative figures such as deobligations
+  are preserved rather than skipped over. `amt is None` used to be true for
+  every zero-dollar transaction and is now true only for a row carrying none of
+  the three fields, so an `is None` check standing in for "no money moved"
+  needs `not amt` instead, and loan rows now report their face value, which
+  changes any total taken over a loan result set. Note that USAspending.gov's
+  own internal "pragmatic obligation" convention uses the subsidy cost, not
+  the face value, as a loan transaction's budgetary figure; this library
+  reports the face value the website displays, and
+  `original_loan_subsidy_cost` remains directly readable for budgetary totals.
+
+### Added
+
+- `client.transactions.search()`, returning the new `TransactionsSearch` query
+  builder over `/search/spending_by_transaction/`. It searches every
+  transaction the API holds rather than the transactions of one award, and
+  takes the same fluent filters the award search takes: `keywords()`,
+  `agency()`, `time_period()` and `fiscal_year()`, the location, code and
+  amount filters, plus `order_by()` over the endpoint's sort fields. An
+  `award_type_codes` filter is required, and unlike the award search this
+  endpoint accepts codes from more than one category at once, so
+  `.contracts().grants()` is a single valid query where the same chain on
+  `client.awards.search()` raises `ValidationError`. `count()` and `len()` read
+  `/search/spending_by_transaction_count/`, summing the buckets of the
+  categories the query selected. `TransactionsSearch` is exported from
+  `usaspending` and `usaspending.queries`.
+
+- `Transaction` reads both row shapes the API sends: the snake_case keys of the
+  award-scoped `/transactions/` listing and the display-name keys of the global
+  search (`"Action Date"`, `"Transaction Amount"` and the rest). The existing
+  properties gained the second spelling, and the search rows carry fields the
+  award-scoped listing never had: `award_internal_id`,
+  `generated_unique_award_id`, `award_identifier`, `recipient_name`,
+  `recipient_uei`, `recipient_id`, the four agency-name properties,
+  `issued_date`, `last_date_to_order`, `naics_code`, `naics_description`,
+  `psc_code`, `psc_description`, `cfda_title`, `def_codes`,
+  `recipient_location` and `place_of_performance`. `id` is `None` for a global
+  search row, which identifies only the parent award, and
+  `transaction_description` is the preferred name for what `award_description`
+  has always returned. Every raw row key also has a getter under its
+  snake_cased name (`award_id`, `mod`, `award_type`, `loan_value`,
+  `subsidy_cost`, `description`, `primary_place_of_performance`, `amount`),
+  aliasing the normalized helpers, with the exceptions documented in the
+  model: agency names live under `*_agency_name`, dict-valued classifications
+  under their scalar helpers, and the server's award identifiers under
+  `award_internal_id` and `generated_unique_award_id`.
+
+### Known limitations
+
+- `TransactionsSearch` is bounded by the API's 50,000-row result window.
+  Iterating past that point raises `APIError` rather than truncating silently.
+  Narrow the filters, set `limit()`, or use `client.downloads` for larger
+  result sets; `count()` is not subject to the window.
+
+- With a `program_activities()` filter set, `TransactionsSearch.count()` and
+  `len()` raise `ValidationError`: the count endpoint silently ignores that
+  filter while the search endpoint honors it, so passing it through would
+  report a confidently wrong count. `list(query)`, indexing and slicing
+  consult the count and so raise too; iteration, `all()`, `first()` and
+  `bool()` need no count and work regardless.
+
 ## [0.8.0] - 2026-07-28
 
 Mostly refactoring internals to DRY the codebase and standardize the query interface.
@@ -262,7 +346,7 @@ truthiness agree under the bounds you set. Adding CI tests to verify compatabili
   `q1 = search().keywords("alpha")` followed by `q2 = q1.keywords("beta")`
   left `q1` sending `["alpha", "beta", "beta"]`. Affected chained `keywords`,
   `award_type_codes`, simple `psc_codes` and `treasury_account_components`
-  filters. 
+  filters.
 
 - `client.recipients.find_by_recipient_id()` no longer addresses the wrong
   record for a recipient ID carrying several levels, such as
@@ -274,7 +358,7 @@ truthiness agree under the bounds you set. Adding CI tests to verify compatabili
   pass the suffix yourself (see `Recipient.recipient_level` under Added).
   `client.spending.search().recipient_id()` also normalizes its argument now,
   so a multi-level ID copied out of `raw` produces a filter the API can
-  match. 
+  match.
 
 - `award.transactions` no longer reports a count that disagrees with what it
   yields. `since()` and `until()` filter in memory, but the count came from
@@ -282,7 +366,7 @@ truthiness agree under the bounds you set. Adding CI tests to verify compatabili
   and `len()` said three where iteration yielded two, slices disagreed with
   `len()`, and `query[-1]` raised `IndexError`. All of them now agree, and
   `limit(1)` means one matching row rather than one row that may then be
-  discarded. 
+  discarded.
 
 - A `Recipient` built directly from an award search result now reports its
   `uei` and `location`, which read only the nested spellings a detail
@@ -291,7 +375,7 @@ truthiness agree under the bounds you set. Adding CI tests to verify compatabili
   not. `PeriodOfPerformance` had the same gap for `"Base Obligation Date"`.
   Both models now read every spelling of their own fields, and `Award` hands
   its payload over rather than reproducing the mapping; nested spellings
-  still take precedence where a payload carries both. 
+  still take precedence where a payload carries both.
 
 - Indexing and slicing an in-memory query now read the limited collection:
   `agency.federal_accounts.limit(3)[:]` returned every account and
@@ -303,10 +387,10 @@ truthiness agree under the bounds you set. Adding CI tests to verify compatabili
   fieldless `@dataclass` declaration generated an `__eq__` comparing empty
   tuples, so any two transactions were equal and none was hashable. They now
   compare by identity, like every other model, and can be used in sets and as
-  dict keys. 
+  dict keys.
 
 - `Recipient.parents` returns a fresh list on each read, so sorting or
-  popping the result no longer corrupts the model. 
+  popping the result no longer corrupts the model.
 
 - Iterating `idv.child_awards` no longer raises
   `AttributeError: 'str' object has no attribute 'get'` when reading the four
@@ -344,7 +428,6 @@ truthiness agree under the bounds you set. Adding CI tests to verify compatabili
 - `FederalAccount.count` no longer fires an API request when the count is
   already in the response; the fallback was an eagerly evaluated default
   argument, so every access paid for a request whose result was discarded.
-  
 
 - `query.limit(0).first()` returned a row, contradicting `.all()` and
   `len()`. It now respects the zero, which is also what makes `__bool__`

{usaspending_orm-0.8.0 → usaspending_orm-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usaspending-orm
-Version: 0.8.0
+Version: 0.9.0
 Summary: A Python ORM wrapper for the USAspending.gov API with intuitive queries, automatic pagination, and smart caching
 Project-URL: Homepage, https://github.com/planetary-society/usaspending-orm
 Project-URL: Repository, https://github.com/planetary-society/usaspending-orm
@@ -168,6 +168,73 @@ with USASpendingClient() as client:
 
 ```
 
+### Searching Transactions Across Awards
+
+`award.transactions` lists the modifications of a single award. `client.transactions.search()` searches every transaction the API holds, takes the same fluent filters the award search takes, and returns one row per transaction rather than one row per award:
+
+```python
+with USASpendingClient() as client:
+
+    # Award-level keyword search: one row per matching award
+    awards = client.awards.search() \
+        .contracts() \
+        .agency("National Aeronautics and Space Administration") \
+        .keywords("Mars") \
+        .fiscal_year(2024)
+
+    print(awards.count())  # -> 106
+
+    # Transaction-level keyword search: one row per matching transaction,
+    # across every award rather than within one
+    transactions = client.transactions.search() \
+        .contracts() \
+        .agency("National Aeronautics and Space Administration") \
+        .keywords("Mars") \
+        .fiscal_year(2024) \
+        .order_by("transaction_amount", "desc")
+
+    print(transactions.count())  # -> 264
+
+    for transaction in transactions.limit(3):
+        print(f"{transaction.action_date} {transaction.award_identifier}: ${transaction.amount or 0:,.2f}")
+
+# 2023-12-15 80NM0021F0008: $45,874,344.00
+# 2023-11-01 80NM0021F0008: $39,011,361.00
+# 2024-04-12 80NM0021F0008: $36,306,819.00
+```
+
+An award type filter is required. Unlike the award search, this endpoint accepts codes from more than one category at once, so contracts and grants can be searched in a single query:
+
+```python
+with USASpendingClient() as client:
+
+    mixed = client.transactions.search() \
+        .contracts() \
+        .grants() \
+        .agency("National Aeronautics and Space Administration") \
+        .keywords("asteroid") \
+        .fiscal_year(2024) \
+        .order_by("action_date", "desc")
+
+    print(mixed.count())  # -> 115
+
+    for transaction in mixed.limit(5):
+        print(f"{transaction.action_date} {transaction.type_description}: ${transaction.amount or 0:,.2f}")
+
+# 2024-09-25 COOPERATIVE AGREEMENT (B): $319,834.00
+# 2024-09-23 PROJECT GRANT (B): $-0.26
+# 2024-09-19 COOPERATIVE AGREEMENT (B): $0.00
+# 2024-09-18 COOPERATIVE AGREEMENT (B): $0.00
+# 2024-09-18 DEFINITIVE CONTRACT: $3,815,000.00
+```
+
+The same chain on `client.awards.search()` raises `ValidationError`, because `spending_by_award` offers different fields and filters per category and so accepts only one at a time.
+
+Two limits are worth knowing:
+
+- The API serves at most the first 50,000 matching rows. Iterating past that point raises `APIError` rather than truncating silently, so narrow the filters, set a `limit()`, or use `client.downloads` for larger result sets. `count()` is not subject to the window.
+- `count()` reads the dedicated transaction count endpoint, which reports one bucket per award-type category, so the figure is the sum of the buckets the query selected. That endpoint does not accept the `program_activities` filter, so with one set `count()` and `len()` raise `ValidationError`; iterating the query and calling `.all()` work regardless, as neither needs a count.
+
 ### Example: Top National Aeronautics and Space Administration Contractors in Fiscal Year 2024
 
 Aggregation endpoints are available through `client.spending`. The same fluent filters

{usaspending_orm-0.8.0 → usaspending_orm-0.9.0}/README.md

@@ -139,6 +139,73 @@ with USASpendingClient() as client:
 
 ```
 
+### Searching Transactions Across Awards
+
+`award.transactions` lists the modifications of a single award. `client.transactions.search()` searches every transaction the API holds, takes the same fluent filters the award search takes, and returns one row per transaction rather than one row per award:
+
+```python
+with USASpendingClient() as client:
+
+    # Award-level keyword search: one row per matching award
+    awards = client.awards.search() \
+        .contracts() \
+        .agency("National Aeronautics and Space Administration") \
+        .keywords("Mars") \
+        .fiscal_year(2024)
+
+    print(awards.count())  # -> 106
+
+    # Transaction-level keyword search: one row per matching transaction,
+    # across every award rather than within one
+    transactions = client.transactions.search() \
+        .contracts() \
+        .agency("National Aeronautics and Space Administration") \
+        .keywords("Mars") \
+        .fiscal_year(2024) \
+        .order_by("transaction_amount", "desc")
+
+    print(transactions.count())  # -> 264
+
+    for transaction in transactions.limit(3):
+        print(f"{transaction.action_date} {transaction.award_identifier}: ${transaction.amount or 0:,.2f}")
+
+# 2023-12-15 80NM0021F0008: $45,874,344.00
+# 2023-11-01 80NM0021F0008: $39,011,361.00
+# 2024-04-12 80NM0021F0008: $36,306,819.00
+```
+
+An award type filter is required. Unlike the award search, this endpoint accepts codes from more than one category at once, so contracts and grants can be searched in a single query:
+
+```python
+with USASpendingClient() as client:
+
+    mixed = client.transactions.search() \
+        .contracts() \
+        .grants() \
+        .agency("National Aeronautics and Space Administration") \
+        .keywords("asteroid") \
+        .fiscal_year(2024) \
+        .order_by("action_date", "desc")
+
+    print(mixed.count())  # -> 115
+
+    for transaction in mixed.limit(5):
+        print(f"{transaction.action_date} {transaction.type_description}: ${transaction.amount or 0:,.2f}")
+
+# 2024-09-25 COOPERATIVE AGREEMENT (B): $319,834.00
+# 2024-09-23 PROJECT GRANT (B): $-0.26
+# 2024-09-19 COOPERATIVE AGREEMENT (B): $0.00
+# 2024-09-18 COOPERATIVE AGREEMENT (B): $0.00
+# 2024-09-18 DEFINITIVE CONTRACT: $3,815,000.00
+```
+
+The same chain on `client.awards.search()` raises `ValidationError`, because `spending_by_award` offers different fields and filters per category and so accepts only one at a time.
+
+Two limits are worth knowing:
+
+- The API serves at most the first 50,000 matching rows. Iterating past that point raises `APIError` rather than truncating silently, so narrow the filters, set a `limit()`, or use `client.downloads` for larger result sets. `count()` is not subject to the window.
+- `count()` reads the dedicated transaction count endpoint, which reports one bucket per award-type category, so the figure is the sum of the buckets the query selected. That endpoint does not accept the `program_activities` filter, so with one set `count()` and `len()` raise `ValidationError`; iterating the query and calling `.all()` work regardless, as neither needs a count.
+
 ### Example: Top National Aeronautics and Space Administration Contractors in Fiscal Year 2024
 
 Aggregation endpoints are available through `client.spending`. The same fluent filters

{usaspending_orm-0.8.0 → usaspending_orm-0.9.0}/api-docs-links.md

@@ -83,7 +83,7 @@ These documentation links provide detailed information about request parameters,
 - **Method**: POST
 - **Documentation**: https://raw.githubusercontent.com/fedspendingtransparency/usaspending-api/refs/heads/master/usaspending_api/api_contracts/contracts/v2/transactions.md
 - **Purpose**: List obligations and modifications for a given award
-- **Corresponding Query Builder**: `src/usaspending/queries/transactions_search.py`
+- **Corresponding Query Builder**: `src/usaspending/queries/award_transactions_search.py`
 
 ### Award Transaction Count
 
@@ -91,7 +91,25 @@ These documentation links provide detailed information about request parameters,
 - **Method**: GET
 - **Documentation**: https://raw.githubusercontent.com/fedspendingtransparency/usaspending-api/refs/heads/master/usaspending_api/api_contracts/contracts/v2/awards/count/transaction/award_id.md
 - **Purpose**: Return the number of transactions associated with a given award
+- **Corresponding Query Builder**: `src/usaspending/queries/award_transactions_search.py`
+
+### Transaction Search
+
+- **Endpoint**: `/api/v2/search/spending_by_transaction/`
+- **Method**: POST
+- **Documentation**: https://raw.githubusercontent.com/fedspendingtransparency/usaspending-api/refs/heads/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_transaction.md
+- **Purpose**: Search transactions across all awards using the standard search filters
+- **Corresponding Query Builder**: `src/usaspending/queries/transactions_search.py`
+- **Note**: `filters.award_type_codes`, `fields`, `sort` and `order` are all required, and the sort field must be one of the requested `fields`. Unlike `/api/v2/search/spending_by_award/`, this endpoint accepts award type codes from more than one category in a single request. The API serves at most the first 50,000 matching rows and returns an error past that point.
+
+### Transaction Search Count
+
+- **Endpoint**: `/api/v2/search/spending_by_transaction_count/`
+- **Method**: POST
+- **Documentation**: https://raw.githubusercontent.com/fedspendingtransparency/usaspending-api/refs/heads/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_transaction_count.md
+- **Purpose**: Return transaction counts by award-type category for a set of search filters
 - **Corresponding Query Builder**: `src/usaspending/queries/transactions_search.py`
+- **Note**: The response reports one bucket per category (`contracts`, `idvs`, `grants`, `loans`, `direct_payments`, `other`), so a count for a query is the sum of the buckets its award type codes select. This endpoint's validator does not accept the `program_activities` filter, which the search endpoint does accept.
 
 ### Award funding history
 

{usaspending_orm-0.8.0 → usaspending_orm-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usaspending-orm"
-version = "0.8.0"
+version = "0.9.0"
 description = "A Python ORM wrapper for the USAspending.gov API with intuitive queries, automatic pagination, and smart caching"
 authors = [
     {name = "Casey Dreier", email = "casey.dreier@planetary.org"}

{usaspending_orm-0.8.0 → usaspending_orm-0.9.0}/src/usaspending/__init__.py

@@ -60,6 +60,7 @@ from .queries import (
     AgenciesSearch,
     AwardingAgenciesSearch,
     AwardsSearch,
+    AwardTransactionsSearch,
     FundingAgenciesSearch,
     FundingSearch,
     RecipientsSearch,
@@ -98,6 +99,7 @@ __all__ = [
     "Award",
     "AwardAmountFilter",
     "AwardDateType",
+    "AwardTransactionsSearch",
     "AwardingAgenciesSearch",
     # Query builders
     "AwardsSearch",

{usaspending_orm-0.8.0 → usaspending_orm-0.9.0}/src/usaspending/models/award.py

@@ -27,9 +27,9 @@ if TYPE_CHECKING:
     from ..client import USASpendingClient
     from ..download.job import DownloadJob
     from ..queries.award_accounts_query import AwardAccountsQuery
+    from ..queries.award_transactions_search import AwardTransactionsSearch
     from ..queries.funding_search import FundingSearch
     from ..queries.subawards_search import SubAwardsSearch
-    from ..queries.transactions_search import TransactionsSearch
 
 logger = USASpendingLogger.get_logger(__name__)
 
@@ -488,7 +488,7 @@ class Award(LazyRecord):
     # - place_of_performance (Location object: location where the work is performed)
     #
     # Has Many (one-to-many relationships):
-    # - transactions (TransactionsSearch object: query builder for transactions associated with the award)
+    # - transactions (AwardTransactionsSearch object: query builder for transactions associated with the award)
     # - funding (FundingSearch object: query builder for treasury funding records (outlay and obligation) associated with the award)
     # - subawards (SubAwardsSearch object: query builder for subawards associated with the award)
 
@@ -702,10 +702,10 @@ class Award(LazyRecord):
         return self._build_subtier_agency("awarding")
 
     @property
-    def transactions(self) -> TransactionsSearch:
+    def transactions(self) -> AwardTransactionsSearch:
         """Get transactions query builder for this award.
 
-        Returns a TransactionsSearch object that can be further filtered and chained.
+        Returns an AwardTransactionsSearch object that can be further filtered and chained.
 
         Examples:
             >>> award.transactions.count()  # Get count without loading all data
@@ -713,7 +713,7 @@ class Award(LazyRecord):
             >>> award.transactions.all()  # Every transaction, as a list
 
         Returns:
-            TransactionsSearch: The query builder for transactions.
+            AwardTransactionsSearch: The query builder for transactions.
         """
         return self._client.transactions.award_id(self.generated_unique_award_id)
 

{usaspending_orm-0.8.0 → usaspending_orm-0.9.0}/src/usaspending/models/award_types.py

@@ -23,11 +23,13 @@ missing, so the omission surfaces immediately.
 
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
 from functools import cached_property
 from types import MappingProxyType
 
+from ..exceptions import ValidationError
+
 
 @dataclass(frozen=True)
 class AwardCategory:
@@ -308,6 +310,27 @@ def is_valid_award_type(code: str) -> bool:
     return code in ALL_AWARD_CODES
 
 
+def validate_award_type_codes(codes: Iterable[str]) -> None:
+    """Raise if any supplied code is not a valid award type code.
+
+    The award-search and transaction-search builders both accept caller-supplied
+    codes and share this check, so the error message cannot drift between them.
+
+    Args:
+        codes: Award type codes to validate.
+
+    Raises:
+        ValidationError: If any code is not in :data:`ALL_AWARD_CODES`, naming
+            the offending codes and listing the valid ones.
+    """
+    invalid_codes = [code for code in codes if code not in ALL_AWARD_CODES]
+    if invalid_codes:
+        raise ValidationError(
+            f"Invalid award type code(s): {', '.join(sorted(invalid_codes))}. "
+            f"Valid codes are: {', '.join(sorted(ALL_AWARD_CODES))}"
+        )
+
+
 def get_description(code: str) -> str:
     """Get the description for a given award type code.