usaspending-orm 0.7.1__tar.gz → 0.7.3__tar.gz

usaspending_orm-0.7.3/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+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.7.3] - 2026-07-05
+
+### Added
+
+- `AwardsSearch.object_classes(*codes)`: filter awards by federal object class codes (per Office of Management and Budget Circular A-11) on the `/search/spending_by_award/` and `/search/spending_by_award_count/` endpoints. Pass codes such as `"10"` or `"252"`, not names; multiple codes use OR logic.
+- `SubAwardsSearch.object_classes()` raises `ValidationError`. The USASpending API accepts the `object_classes` filter for award searches only and returns HTTP 422 when it is combined with `spending_level=subawards`.
+- `client.downloads.search()` emits a `UserWarning` when the query contains an `object_classes` filter, because the `/api/v2/download/search/` endpoint drops the key. The filter is still forwarded unmodified.
+- Known upstream limitation as of 2026-07-05: the production API accepts `object_classes` but the rollout is incomplete. The search endpoint returns zero results for any object class, the count endpoint does not narrow, and the subawards rejection is not yet enforced server side. The filter should begin returning data once USAspending finishes deploying the feature and populating its award index.
+- `tests/test_readme_examples.py`: integration tests that extract the README's Python code blocks and execute the runnable ones verbatim against the live API, so broken or rotted examples fail mechanically. A network-free guard in the default suite catches extraction drift. The live `client` fixture moved to `tests/conftest.py` and is now shared with `tests/test_integration.py`.
+
+### Documentation
+
+- Corrected the `api-docs-links.md` subawards entry: `SubAwardsSearch` POSTs `/api/v2/search/spending_by_award/` with `subawards=true` and `spending_level=subawards` (inheriting `AwardsSearch`) rather than calling `/api/v2/subawards/`.
+- Added missing `api-docs-links.md` entries for `/api/v2/idvs/awards/` (IDV child awards) and the TAS filter-tree endpoints (`/api/v2/references/filter_tree/tas/` and its `{toptier_code}/` and `{toptier_code}/{federal_account}/` variants).
+- An upstream API compatibility review of USASpending API releases from April through June 2026 found no breaking changes for this library. The 0.7.2 release already handles the `spending_by_award` Pydantic migration (HTTP 422 validation errors), the `program_activities` filter rename, and the new F001 through F010 assistance type codes.
+- Revalidated all README examples against live USAspending data. Fixed two broken chains (`location.full_address` is actually `location.formatted_address`; a subaward's place of performance is on the subaward, not its recipient), refreshed stale sample outputs, and added examples for the `client.spending` category rollups and the list-style `len(query)` interface.
+
+## [0.7.2] - 2026-06-05
+
+### Added
+
+- `client.downloads.search(query, ...)` backed by the new `/api/v2/download/search/` endpoint, which bundles award, transaction, and subaward data into a single download built from an awards search query. Supports `file_format`, `spending_level`, `columns`, and `limit`.
+- `QueryBuilder.to_filters_payload()`: public accessor returning the assembled API `filters` object for a query without executing a search.
+
+### Changed
+
+- HTTP 422 (Unprocessable Entity) validation responses are now surfaced as `APIError` with the response detail instead of a generic `HTTPError`. This aligns with the USASpending API's move to Pydantic request validation on `/search/spending_by_award/`.
+
+### Deprecated
+
+- `program_activity()` is deprecated and now forwards to `program_activities()`, emitting a `DeprecationWarning`. The USASpending API removed the `program_activity` filter from `/search/spending_by_award/` in favor of `program_activities`. Existing calls continue to work; integer codes are forwarded as string `code` values.
+
+## [0.7.1] - 2026-04-16
+
+### Added
+
+- Public export of `DetachedInstanceError` so callers can `from usaspending import DetachedInstanceError` as documented in the README.
+- `config.allowed_download_hosts`: an allow-list of hostnames the library will fetch binary downloads from. Defaults to `{"api.usaspending.gov", "files.usaspending.gov"}`.
+- `config.validate()` now rejects malformed `base_url`, CR/LF in `user_agent`, and empty `cache_dir`.
+
+### Changed
+
+- `ValidationError` now inherits from both `USASpendingError` and the built-in `ValueError`. Callers that previously caught `ValueError` for invalid parameters continue to work unchanged; new code can catch the library-specific `ValidationError`.
+- `RateLimiter` now raises `ValidationError` (rather than a bare `ValueError`) for invalid `max_calls`/`period` arguments. Non-breaking due to the dual inheritance above.
+- `RecipientsResource.find_by_recipient_id` is now annotated as non-Optional. This matches its long-standing behavior of raising on miss via the direct-ID lookup path; runtime behavior is unchanged. `find_by_duns` and `find_by_uei` remain Optional because they use the search-delegation path.
+- `Agency.get_obligations` return annotation corrected from `float | None` to `Decimal | None` to match actual runtime type.
+- `Agency.total_obligations` now applies `Decimal` coercion to stored values to match its declared return type.
+- `TransactionsSearch._award_id` and `FundingSearch._award_id` annotated as `str | None` rather than `str` (they are always `None` until set).
+- `time_period()` now rejects date ranges where `end_date` is earlier than `start_date`.
+
+### Fixed
+
+- `to_date()` now extracts the `date` portion from `datetime` inputs instead of passing them through unchanged.
+- `IDVChildAwardsSearch._clone()` no longer silently drops `_filter_objects`, `_max_pages`, `_order_by`, and `_order_direction` when chaining.
+- `SubAwardsSearch._clone()` now delegates to `super()._clone()` so base-class state changes propagate.
+- `AwardAccountsQuery._clone()` no longer copies a stale `_cached_count` across filter changes.
+- `Agency.latest_action_date` no longer crashes when the award-summary endpoint returns no data.
+- `round_to_millions()` cleaned up redundant disjunct in threshold check.
+- Removed unused `DEFAULT_KEEP_UPPERCASE` set, which also contained a latent missing-comma bug that concatenated two entries.
+- Fixed malformed `Raises:` block in `AwardResource.find_by_generated_id` docstring.
+- `Agency.id` was missing its return-type annotation.
+
+### Security
+
+- Binary downloads (`_download_binary_file`) now require `https` and a hostname on `config.allowed_download_hosts`, mitigating SSRF if API responses are tampered with.
+- File-backed cache directory is now created with `0700` and tightened to `0700` if it already exists with looser bits. Protects the pickle-backed cache on shared hosts.
+- ZIP extraction creates the extract directory with `0700`, detects absolute paths with stdlib `posixpath.isabs` / `ntpath.isabs` (covers Windows drive letters and UNC prefixes), and uses `normpath`-based prefix comparison for traversal detection.
+
+### Removed
+
+- Dead code: `get_past_fiscal_years`, `custom_titlecase_callback`, `parse_agency_type`, `parse_agency_tier`, `QueryBuilder._fetch_page`, empty `AwardsSearch.__init__`, redundant `AwardsSearch._clone` override, unreachable `try/except` in `_derived_award_identifier`.
+
+## [0.7.0] - 2026-04-12
+
+Previous release. See git history for details.

{usaspending_orm-0.7.1 → usaspending_orm-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usaspending-orm
-Version: 0.7.1
+Version: 0.7.3
 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
@@ -39,7 +39,7 @@ The platform has a [comprehensive API](https://api.usaspending.gov) for querying
 
 **🔗 ORM-Style Chained Interface** - Access related data through object associations (e.g., `award.recipient.location.city`) inspired by ActiveRecord and SQLAlchemy. Navigate related data without manual API calls.
 
-**🔎 Comprehensive Award Queries** - Build complex searches with chainable filters for agencies, award types, fiscal years, and more. 
+**🔎 Comprehensive Award Queries** - Build complex searches with chainable filters for agencies, award types, fiscal years, and more.
 
 **⚡️ Smart Caching & Rate Limiting** - Optional file-based caching to dramatically improve performance for repeated queries. Automatic rate limiting and retry logic handles API throttle limits during bulk operations.
 
@@ -61,25 +61,31 @@ The library provides a `USASpendingClient` class that manages the connection to
 or can be instantiated directly.
 
 #### Load the client
+
 ```python
 from usaspending import USASpendingClient
 ```
 
 #### Then load a specific award by its Award ID
+
 ```python
 with USASpendingClient() as client:
     award = client.awards.find_by_award_id("80GSFC18C0008")
 ```
 
 #### Access related Award properties via chained object associations
+
 ```python
 with USASpendingClient() as client:
     award = client.awards.find_by_award_id("80GSFC18C0008")
-    award.recipient.location.full_address # -> 105 Jessup Hall, Iowa City, IA, 52242, United States
-    award.subawards.count() # -> 100
-    award.subawards[2].recipient.place_of_performance.district # -> AL-03
+    award.recipient.name # -> "The University of Iowa"
+    award.recipient.location.formatted_address # -> "105 Jessup Hall\nIowa City, IA, 52242\nUnited States"
+    award.subawards.count() # -> 150
+    award.subawards[2].recipient.name # -> "Bison Aerospace, Inc"
 ```
 
+Sample outputs throughout this document were validated against live USAspending data in July 2026. Counts, amounts, and dates will drift as agencies report new spending.
+
 #### Searching for Awards
 
 You can query awards data using the `search()` method on the `client.awards` object:
@@ -90,24 +96,34 @@ with USASpendingClient() as client:
     awards_query = client.awards.search()
 ```
 
-Search parameters are outlined in the [spending_by_award](https://github.com/fedspendingtransparency/usaspending-api/raw/refs/heads/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_award.md) endpoint of the USASpending API. Every search parameter is applied via a matching "snake_case" method name. These methods can be chained together to build complex queries.
+Search parameters are outlined in the [spending_by_award](https://raw.githubusercontent.com/fedspendingtransparency/usaspending-api/refs/heads/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_award.md) endpoint of the USASpending API. Every search parameter is applied via a matching "snake_case" method name. These methods can be chained together to build complex queries.
 
-``` python
+```python
 awards_query = client.awards.search() \
-    .agencies({"name":"National Aeronautics and Space Administration", "type":"awarding", "tier":"toptier"}) \  
+    .agencies({"name":"National Aeronautics and Space Administration", "type":"awarding", "tier":"toptier"}) \
     .grants() \
     .keywords("Perseverance","Mars")
 ```
 
 This returns a query object that can be further refined or executed to return results.
-The methods `.all()`, `.first()`, `.count()` will trigger a query to the API, as will iterating over the query object.
+The methods `.all()`, `.first()`, `.count()` will trigger a query to the API, as will iterating over the query object. Query objects also support the standard Python list interface, so `len(awards_query)` fires the corresponding count endpoint:
+
+```python
+len(client.awards.search()
+    .agency("National Aeronautics and Space Administration")
+    .grants()
+    .keywords("Mars")
+    .fiscal_year(2024))  # -> 404
+```
+
+Additional filters follow the same snake_case pattern. For example, `.object_classes("10", "252")` filters awards by object class codes (per Office of Management and Budget Circular A-11; pass codes, not names).
 
 ### Example: Searching for National Aeronautics and Space Administration Contracts to SpaceX in 2023
 
 ```python
 
 with USASpendingClient() as client:
-    
+
     # Create query object with chained filters
     awards_query = client.awards.search() \
         .agency("National Aeronautics and Space Administration") \
@@ -115,41 +131,99 @@ with USASpendingClient() as client:
         .contracts() \
         .fiscal_year(2023) \
         .order_by("Award Amount", "desc")
-    
+
     # -> <AwardQuery ...> object, no API call made yet
-    
+
     # Return results count without fetching all records
     count = awards_query.count() # -> 8
 
     # Fetch first result (query executes here)
     top_spacex_award = awards_query.first()
-    
+
     # Returned value is an Award object with all properties mapped
-    # and properly typed. 
-    top_spacex_award.total_obligation  # -> Decimal('3029850123.69')
+    # and properly typed. The top result is the Human Landing System contract.
+    top_spacex_award.total_obligation  # -> Decimal('3047851482.99')
     top_spacex_award.category  # -> "contract"
-    top_spacex_award.description  # -> "The Commercial Crew Program (CCP) contract ...."
-    
+    top_spacex_award.description  # -> "Work required for the design, development, manufacture, test, launch..."
+
     # Helper methods provide easy access to common fields without having to account for
     # inconsistent naming or nested structures in the raw API response
-    top_spacex_award.award_identifier  # -> "80GSFC18C0008"
-    top_spacex_award.start_date  # -> datetime.date(2016, 12, 30)
-    top_spacex_award.end_date  # -> datetime.date(2023,12,31)
+    top_spacex_award.award_identifier  # -> "80MSFC20C0034"
+    top_spacex_award.start_date  # -> datetime.date(2020, 5, 13)
+    top_spacex_award.end_date  # -> datetime.date(2027, 12, 6)
 
     # The resulting object provides a normalized interface to the full Award record,
     # and provides access to related data via chained associations
-    
+
     # Recipient information
     top_spacex_award.recipient.name  # -> "Space Exploration Technologies Corp."
     top_spacex_award.recipient.location.city  # -> "Hawthorne"
 
     # Award Transactions
     last_transaction = top_spacex_award.transactions.order_by("action_date", "desc").first()
-    last_transaction.action_date  # -> datetime.date(2025, 10, 08)
+    last_transaction.action_date  # -> datetime.date(2026, 7, 1)
     last_transaction.action_type_description  # -> "SUPPLEMENTAL AGREEMENT FOR WORK WITHIN SCOPE"
 
 ```
 
+### Example: Top National Aeronautics and Space Administration Contractors in Fiscal Year 2024
+
+Aggregation endpoints are available through `client.spending`. The same fluent filters
+build a category rollup instead of an award list, and iterating the query handles
+pagination automatically:
+
+```python
+with USASpendingClient() as client:
+    top_recipients = (
+        client.spending.search()
+        .by_recipient()
+        .agency("National Aeronautics and Space Administration")
+        .contracts()
+        .fiscal_year(2024)
+        .limit(5)
+    )
+
+    for spending in top_recipients:
+        print(f"{spending.name}: ${spending.amount:,.0f}")
+
+# California Institute of Technology: $2,175,598,668
+# Space Exploration Technologies Corp.: $1,589,359,578
+# The Boeing Company: $1,123,735,127
+# Lockheed Martin Corp: $570,859,903
+# Blue Origin Washington, LLC: $502,942,297
+```
+
+Spending rollups can also be grouped geographically with `.by_district()` or `.by_state()`.
+
+### Downloading Bulk Data
+
+The `client.downloads` resource queues server-side download jobs and returns a `DownloadJob`
+you can poll. Single awards are downloaded by their generated award ID:
+
+```python
+job = client.downloads.contract("CONT_AWD_...")   # also .assistance(...) and .idv(...)
+status = job.wait_for_completion()
+```
+
+To download many awards at once, build an awards search and pass it to `client.downloads.search()`.
+The same fluent filters used for searching drive the download, which can combine award,
+transaction, and subaward data into a single zip archive:
+
+```python
+query = (
+    client.awards.search()
+    .contracts()
+    .agency("National Aeronautics and Space Administration")
+    .fiscal_year(2024)
+)
+
+# spending_level defaults to awards, transactions, and subawards when omitted.
+job = client.downloads.search(query, spending_level=["awards"], file_format="csv")
+status = job.wait_for_completion()
+```
+
+The `/api/v2/download/search/` endpoint does not accept every search filter. In particular, `object_classes` is ignored by the endpoint, so the library emits a `UserWarning` when a download query includes it.
+
 ## Configuration
 
 ### Session Management and Lazy-Loading
@@ -221,6 +295,7 @@ This is a fundamental limitation of the USASpending API, which does not provide
 **Recommended patterns to minimize API calls:**
 
 1. **Access only search result properties** - Properties returned by the search endpoint don't trigger additional API calls:
+
    ```python
    for award in client.awards.search().contracts().limit(100):
        # These properties are included in search results - no extra API calls
@@ -228,6 +303,7 @@ This is a fundamental limitation of the USASpending API, which does not provide
    ```
 
 2. **Enable caching** - Cache responses to avoid repeated fetches for the same data:
+
    ```python
    from usaspending import config as usaspending_config
    usaspending_config.configure(cache_enabled=True)
@@ -291,6 +367,7 @@ usaspending_config.configure(
 ```
 
 **File-based caching** (default):
+
 - Persists between Python sessions
 - Stored in `~/.cache/usaspending` directory
 - Uses pickle for serialization
@@ -301,6 +378,7 @@ applications. The default namespace is `usaspending-orm`. Override this if you n
 separate cache pools for different environments or applications.
 
 **Memory-based caching**:
+
 - Faster access, no disk I/O
 - Cleared when Python process ends
 - Best for single-session data exploration
@@ -423,7 +501,7 @@ We welcome contributions to improve and expand the implementation and functional
 
 This library was initially developed to serve the needs of The Planetary Society's Space Policy and Advocacy team in tracking and analyzing National Aeronautics and Space Administration contract data, and is in-use in our internal and external data tools.
 
-We have open-sourced the project to enable others to better use USASpending data. 
+We have open-sourced the project to enable others to better use USASpending data.
 
 [The Planetary Society](https://planetary.org) is an independent nonprofit organization that empowers the world's citizens to advance space science and exploration. The organization is supported by individuals across the world, and does not accept government grants nor does it have major aerospace donations.
 

usaspending_orm-0.7.1/~/.cache/uv/archive-v0/lgVXT3CfkHHR_J8UVSDrC/usaspending_orm-0.7.0.dist-info/METADATA → usaspending_orm-0.7.3/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.4
-Name: usaspending-orm
-Version: 0.7.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
-Project-URL: Issues, https://github.com/planetary-society/usaspending-orm/issues
-Project-URL: Documentation, https://github.com/planetary-society/usaspending-orm/blob/main/README.md
-Author-email: Casey Dreier <casey.dreier@planetary.org>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: api-wrapper,contracts,federal-spending,government-data,grants,orm,usaspending
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
-Requires-Dist: cachier<5.0.0,>=4.1.0
-Requires-Dist: pyyaml<7.0.0,>=6.0.2
-Requires-Dist: requests<3.0.0,>=2.32.4
-Requires-Dist: titlecase<3.0.0,>=2.4.1
-Description-Content-Type: text/markdown
-
 # USASpending ORM
 
 A python library that provides an object-relational mapping layer to the USAspending.gov API.
@@ -39,7 +12,7 @@ The platform has a [comprehensive API](https://api.usaspending.gov) for querying
 
 **🔗 ORM-Style Chained Interface** - Access related data through object associations (e.g., `award.recipient.location.city`) inspired by ActiveRecord and SQLAlchemy. Navigate related data without manual API calls.
 
-**🔎 Comprehensive Award Queries** - Build complex searches with chainable filters for agencies, award types, fiscal years, and more. 
+**🔎 Comprehensive Award Queries** - Build complex searches with chainable filters for agencies, award types, fiscal years, and more.
 
 **⚡️ Smart Caching & Rate Limiting** - Optional file-based caching to dramatically improve performance for repeated queries. Automatic rate limiting and retry logic handles API throttle limits during bulk operations.
 
@@ -61,25 +34,31 @@ The library provides a `USASpendingClient` class that manages the connection to
 or can be instantiated directly.
 
 #### Load the client
+
 ```python
 from usaspending import USASpendingClient
 ```
 
 #### Then load a specific award by its Award ID
+
 ```python
 with USASpendingClient() as client:
     award = client.awards.find_by_award_id("80GSFC18C0008")
 ```
 
 #### Access related Award properties via chained object associations
+
 ```python
 with USASpendingClient() as client:
     award = client.awards.find_by_award_id("80GSFC18C0008")
-    award.recipient.location.full_address # -> 105 Jessup Hall, Iowa City, IA, 52242, United States
-    award.subawards.count() # -> 100
-    award.subawards[2].recipient.place_of_performance.district # -> AL-03
+    award.recipient.name # -> "The University of Iowa"
+    award.recipient.location.formatted_address # -> "105 Jessup Hall\nIowa City, IA, 52242\nUnited States"
+    award.subawards.count() # -> 150
+    award.subawards[2].recipient.name # -> "Bison Aerospace, Inc"
 ```
 
+Sample outputs throughout this document were validated against live USAspending data in July 2026. Counts, amounts, and dates will drift as agencies report new spending.
+
 #### Searching for Awards
 
 You can query awards data using the `search()` method on the `client.awards` object:
@@ -90,24 +69,34 @@ with USASpendingClient() as client:
     awards_query = client.awards.search()
 ```
 
-Search parameters are outlined in the [spending_by_award](https://github.com/fedspendingtransparency/usaspending-api/raw/refs/heads/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_award.md) endpoint of the USASpending API. Every search parameter is applied via a matching "snake_case" method name. These methods can be chained together to build complex queries.
+Search parameters are outlined in the [spending_by_award](https://raw.githubusercontent.com/fedspendingtransparency/usaspending-api/refs/heads/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_award.md) endpoint of the USASpending API. Every search parameter is applied via a matching "snake_case" method name. These methods can be chained together to build complex queries.
 
-``` python
+```python
 awards_query = client.awards.search() \
-    .agencies({"name":"National Aeronautics and Space Administration", "type":"awarding", "tier":"toptier"}) \  
+    .agencies({"name":"National Aeronautics and Space Administration", "type":"awarding", "tier":"toptier"}) \
     .grants() \
     .keywords("Perseverance","Mars")
 ```
 
 This returns a query object that can be further refined or executed to return results.
-The methods `.all()`, `.first()`, `.count()` will trigger a query to the API, as will iterating over the query object.
+The methods `.all()`, `.first()`, `.count()` will trigger a query to the API, as will iterating over the query object. Query objects also support the standard Python list interface, so `len(awards_query)` fires the corresponding count endpoint:
+
+```python
+len(client.awards.search()
+    .agency("National Aeronautics and Space Administration")
+    .grants()
+    .keywords("Mars")
+    .fiscal_year(2024))  # -> 404
+```
+
+Additional filters follow the same snake_case pattern. For example, `.object_classes("10", "252")` filters awards by object class codes (per Office of Management and Budget Circular A-11; pass codes, not names).
 
 ### Example: Searching for National Aeronautics and Space Administration Contracts to SpaceX in 2023
 
 ```python
 
 with USASpendingClient() as client:
-    
+
     # Create query object with chained filters
     awards_query = client.awards.search() \
         .agency("National Aeronautics and Space Administration") \
@@ -115,41 +104,99 @@ with USASpendingClient() as client:
         .contracts() \
         .fiscal_year(2023) \
         .order_by("Award Amount", "desc")
-    
+
     # -> <AwardQuery ...> object, no API call made yet
-    
+
     # Return results count without fetching all records
     count = awards_query.count() # -> 8
 
     # Fetch first result (query executes here)
     top_spacex_award = awards_query.first()
-    
+
     # Returned value is an Award object with all properties mapped
-    # and properly typed. 
-    top_spacex_award.total_obligation  # -> Decimal('3029850123.69')
+    # and properly typed. The top result is the Human Landing System contract.
+    top_spacex_award.total_obligation  # -> Decimal('3047851482.99')
     top_spacex_award.category  # -> "contract"
-    top_spacex_award.description  # -> "The Commercial Crew Program (CCP) contract ...."
-    
+    top_spacex_award.description  # -> "Work required for the design, development, manufacture, test, launch..."
+
     # Helper methods provide easy access to common fields without having to account for
     # inconsistent naming or nested structures in the raw API response
-    top_spacex_award.award_identifier  # -> "80GSFC18C0008"
-    top_spacex_award.start_date  # -> datetime.date(2016, 12, 30)
-    top_spacex_award.end_date  # -> datetime.date(2023,12,31)
+    top_spacex_award.award_identifier  # -> "80MSFC20C0034"
+    top_spacex_award.start_date  # -> datetime.date(2020, 5, 13)
+    top_spacex_award.end_date  # -> datetime.date(2027, 12, 6)
 
     # The resulting object provides a normalized interface to the full Award record,
     # and provides access to related data via chained associations
-    
+
     # Recipient information
     top_spacex_award.recipient.name  # -> "Space Exploration Technologies Corp."
     top_spacex_award.recipient.location.city  # -> "Hawthorne"
 
     # Award Transactions
     last_transaction = top_spacex_award.transactions.order_by("action_date", "desc").first()
-    last_transaction.action_date  # -> datetime.date(2025, 10, 08)
+    last_transaction.action_date  # -> datetime.date(2026, 7, 1)
     last_transaction.action_type_description  # -> "SUPPLEMENTAL AGREEMENT FOR WORK WITHIN SCOPE"
 
 ```
 
+### Example: Top National Aeronautics and Space Administration Contractors in Fiscal Year 2024
+
+Aggregation endpoints are available through `client.spending`. The same fluent filters
+build a category rollup instead of an award list, and iterating the query handles
+pagination automatically:
+
+```python
+with USASpendingClient() as client:
+    top_recipients = (
+        client.spending.search()
+        .by_recipient()
+        .agency("National Aeronautics and Space Administration")
+        .contracts()
+        .fiscal_year(2024)
+        .limit(5)
+    )
+
+    for spending in top_recipients:
+        print(f"{spending.name}: ${spending.amount:,.0f}")
+
+# California Institute of Technology: $2,175,598,668
+# Space Exploration Technologies Corp.: $1,589,359,578
+# The Boeing Company: $1,123,735,127
+# Lockheed Martin Corp: $570,859,903
+# Blue Origin Washington, LLC: $502,942,297
+```
+
+Spending rollups can also be grouped geographically with `.by_district()` or `.by_state()`.
+
+### Downloading Bulk Data
+
+The `client.downloads` resource queues server-side download jobs and returns a `DownloadJob`
+you can poll. Single awards are downloaded by their generated award ID:
+
+```python
+job = client.downloads.contract("CONT_AWD_...")   # also .assistance(...) and .idv(...)
+status = job.wait_for_completion()
+```
+
+To download many awards at once, build an awards search and pass it to `client.downloads.search()`.
+The same fluent filters used for searching drive the download, which can combine award,
+transaction, and subaward data into a single zip archive:
+
+```python
+query = (
+    client.awards.search()
+    .contracts()
+    .agency("National Aeronautics and Space Administration")
+    .fiscal_year(2024)
+)
+
+# spending_level defaults to awards, transactions, and subawards when omitted.
+job = client.downloads.search(query, spending_level=["awards"], file_format="csv")
+status = job.wait_for_completion()
+```
+
+The `/api/v2/download/search/` endpoint does not accept every search filter. In particular, `object_classes` is ignored by the endpoint, so the library emits a `UserWarning` when a download query includes it.
+
 ## Configuration
 
 ### Session Management and Lazy-Loading
@@ -221,6 +268,7 @@ This is a fundamental limitation of the USASpending API, which does not provide
 **Recommended patterns to minimize API calls:**
 
 1. **Access only search result properties** - Properties returned by the search endpoint don't trigger additional API calls:
+
    ```python
    for award in client.awards.search().contracts().limit(100):
        # These properties are included in search results - no extra API calls
@@ -228,6 +276,7 @@ This is a fundamental limitation of the USASpending API, which does not provide
    ```
 
 2. **Enable caching** - Cache responses to avoid repeated fetches for the same data:
+
    ```python
    from usaspending import config as usaspending_config
    usaspending_config.configure(cache_enabled=True)
@@ -291,6 +340,7 @@ usaspending_config.configure(
 ```
 
 **File-based caching** (default):
+
 - Persists between Python sessions
 - Stored in `~/.cache/usaspending` directory
 - Uses pickle for serialization
@@ -301,6 +351,7 @@ applications. The default namespace is `usaspending-orm`. Override this if you n
 separate cache pools for different environments or applications.
 
 **Memory-based caching**:
+
 - Faster access, no disk I/O
 - Cleared when Python process ends
 - Best for single-session data exploration
@@ -423,7 +474,7 @@ We welcome contributions to improve and expand the implementation and functional
 
 This library was initially developed to serve the needs of The Planetary Society's Space Policy and Advocacy team in tracking and analyzing National Aeronautics and Space Administration contract data, and is in-use in our internal and external data tools.
 
-We have open-sourced the project to enable others to better use USASpending data. 
+We have open-sourced the project to enable others to better use USASpending data.
 
 [The Planetary Society](https://planetary.org) is an independent nonprofit organization that empowers the world's citizens to advance space science and exploration. The organization is supported by individuals across the world, and does not accept government grants nor does it have major aerospace donations.