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

{usaspending_orm-0.8.0 → usaspending_orm-0.9.1}/.gitignore

@@ -4,6 +4,7 @@ __pycache__
 .*_cache
 repomix*
 dist/
+site/
 .claude/
 /~/
 .coverage

usaspending_orm-0.9.1/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+python:
+  install:
+    - method: uv
+      command: sync
+      groups:
+        - docs
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: true

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

@@ -4,6 +4,137 @@ 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.1] - 2026-08-27
+
+### Added
+
+- `client.references.def_codes()`: fetches the API's current Disaster Emergency
+  Fund Code reference data from `/api/v2/references/def_codes/` as `DefCode`
+  models. DEF codes change as legislation is enacted, so discover them at
+  runtime instead of maintaining a local list; the `def_codes(...)` search
+  filter itself remains network-free, and its docstring no longer carries a
+  hardcoded code list. `DefCode` moved to `usaspending/models/def_code.py` and
+  is exported from `usaspending.models`; the legacy
+  `usaspending.models.agency.DefCode` import path still resolves to the same
+  class.
+- Client-side validation of classification-filter complexity, mirroring the
+  API's hard-coded bounds as reviewed against upstream on 2026-08-25.
+  `naics_codes()` rejects more than 200 combined require/exclude codes.
+  `psc_codes()` rejects more than 200 simple codes, more than 100 hierarchical
+  paths per side, more than 200 combined paths after upstream's PSC Tier-1
+  group expansion, and paths deeper than 10 levels. `tas_codes()` enforces the
+  same per-side, combined, and depth bounds. Oversized filters now raise
+  `ValidationError` at construction instead of failing at the API.
+- MkDocs documentation site (getting-started guides, API reference, and the
+  upstream endpoint mapping) with Read the Docs configuration.
+
+### Changed
+
+- `client.agencies.search()` now follows the shared collection semantics.
+  `page_size(n)` maps to the endpoint's `limit` parameter (default 100, capped
+  at 500) instead of a fixed internal limit of 100; the upstream limit applies
+  independently to the toptier, subtier, and office buckets, so one request can
+  return up to `3n` rows. `limit(n)` bounds the flattened result consistently
+  across `all()`, `count()`, `len()`, indexing, and slicing, and indexing reads
+  the single flattened response rather than translating indices into pages the
+  endpoint does not have. Zero bounds (`limit(0)`, `max_pages(0)`) resolve
+  without a request.
+- `naics_codes()`, `psc_codes()`, and `tas_codes()` copy their inputs, so
+  mutating a caller-owned list after building a query no longer alters the
+  filter.
+
+### Documentation
+
+- Download failure text (`job.error_message`, `DownloadStatus.message`) is
+  documented as opaque server-provided text: it may be generic and can change
+  without notice, so application control flow should depend on `job.state`.
+  When a failed job carries no server message, `job.error_message` is
+  `"API reported failure."`.
+
+## [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 +393,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 +405,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 +413,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 +422,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 +434,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 +475,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.1}/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2025 Casey Dreier
+Copyright 2025 Casey Dreier/The Planetary Society
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the “Software”), to deal

usaspending_orm-0.9.1/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: usaspending-orm
+Version: 0.9.1
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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
+
+[![Tests](https://github.com/planetary-society/usaspending-orm/actions/workflows/test.yml/badge.svg)](https://github.com/planetary-society/usaspending-orm/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/usaspending-orm.svg)](https://pypi.org/project/usaspending-orm/)
+[![Python](https://img.shields.io/pypi/pyversions/usaspending-orm.svg)](https://pypi.org/project/usaspending-orm/)
+
+USASpending ORM is a typed, ORM-style Python interface to the
+[USAspending.gov API](https://api.usaspending.gov/). It provides fluent query
+builders and navigable models for federal awards, transactions, recipients,
+agencies, spending summaries, Treasury Account Symbols, and bulk downloads.
+
+The library is maintained by [The Planetary Society](https://www.planetary.org/).
+
+## Why use it?
+
+- Express complex USAspending searches through chainable Python methods.
+- Work with normalized models, `date` values, and exact `Decimal` amounts.
+- Navigate from awards to recipients, agencies, transactions, funding, accounts,
+  and subawards.
+- Retain the original API response through each model's `.raw` property.
+- Use built-in pagination, retries, rate limiting, optional caching, and result
+  safeguards.
+
+No API key is required.
+
+## Installation
+
+```console
+python -m pip install usaspending-orm
+```
+
+Requires Python 3.9 or newer.
+
+## Quickstart
+
+```python
+from usaspending import USASpendingClient
+
+with USASpendingClient() as client:
+    awards = (
+        client.awards.search()
+        .contracts()
+        .agency("National Aeronautics and Space Administration")
+        .recipient_search_text("Space Exploration Technologies")
+        .fiscal_year(2024)
+        .order_by("Award Amount", "desc")
+        .limit(5)
+    )
+
+    for award in awards:
+        amount = award.total_obligation or 0
+        print(f"{award.award_identifier}: {award.recipient.name} - ${amount:,.2f}")
+```
+
+Queries are lazy. Building the chain makes no request; iteration, `.first()`,
+`.all()`, `.count()`, `len(query)`, indexing, and truth-value testing execute
+the appropriate USAspending operation.
+
+## Documentation
+
+The full documentation covers:
+
+- [installation and core concepts](docs/getting-started/installation.md);
+- [award and transaction searches](docs/guides/search-awards.md);
+- [sessions, lazy loading, caching, and production use](docs/guides/production.md);
+- [generated Python API reference](docs/reference/client.md);
+- [mappings to canonical USAspending endpoints](docs/usaspending-api/endpoint-mapping.md);
+- [known upstream limits and contract differences](docs/usaspending-api/limitations.md).
+
+The repository includes Read the Docs configuration for the published site.
+
+## Development
+
+```console
+git clone https://github.com/planetary-society/usaspending-orm.git
+cd usaspending-orm
+uv sync --locked --group docs
+
+uv run pytest -q
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run --group docs mkdocs build --strict
+```
+
+Integration tests make live USAspending requests and run separately:
+
+```console
+uv run pytest -m integration -q
+```
+
+Preview the documentation site locally with `uv run --group docs mkdocs serve`.
+
+> **Note for contributors**
+>
+> Documentation examples are enforced, not just reviewed. `tests/test_documentation.py`
+> compiles every fenced `python` block under `docs/`, checks that method names cited in
+> prose exist on the public API, and executes most blocks against the live API under the
+> `integration` marker. Adding or removing an example changes the runnable count, so
+> update `_EXPECTED_RUNNABLE_BLOCKS` in the same change.
+>
+> The public API surface is snapshot-tested. When a deliberate change adds, removes, or
+> alters a public callable, regenerate the fixture and review the diff:
+>
+> ```console
+> USASPENDING_REGEN_API_SURFACE=1 uv run pytest tests/test_public_api_surface.py
+> ```
+>
+> The published site builds from `.readthedocs.yaml`. To activate hosting: import
+> `planetary-society/usaspending-orm` in Read the Docs, use `usaspending-orm` as the
+> project slug, and enable pull-request builds. Keep `latest` as the default until a
+> release tag contains the docs configuration, then make `stable` the default
+> user-facing version while retaining `latest` for `main`.
+
+## Project status
+
+The project is in beta. USAspending itself changes over time, and live federal
+data is revised as agencies submit corrections. Counts and values shown in
+examples should not be treated as permanent fixtures.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history and compatibility notes.
+
+## License
+
+USASpending ORM is released under the [MIT License](LICENSE).

usaspending_orm-0.9.1/README.md

@@ -0,0 +1,124 @@
+# USASpending ORM
+
+[![Tests](https://github.com/planetary-society/usaspending-orm/actions/workflows/test.yml/badge.svg)](https://github.com/planetary-society/usaspending-orm/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/usaspending-orm.svg)](https://pypi.org/project/usaspending-orm/)
+[![Python](https://img.shields.io/pypi/pyversions/usaspending-orm.svg)](https://pypi.org/project/usaspending-orm/)
+
+USASpending ORM is a typed, ORM-style Python interface to the
+[USAspending.gov API](https://api.usaspending.gov/). It provides fluent query
+builders and navigable models for federal awards, transactions, recipients,
+agencies, spending summaries, Treasury Account Symbols, and bulk downloads.
+
+The library is maintained by [The Planetary Society](https://www.planetary.org/).
+
+## Why use it?
+
+- Express complex USAspending searches through chainable Python methods.
+- Work with normalized models, `date` values, and exact `Decimal` amounts.
+- Navigate from awards to recipients, agencies, transactions, funding, accounts,
+  and subawards.
+- Retain the original API response through each model's `.raw` property.
+- Use built-in pagination, retries, rate limiting, optional caching, and result
+  safeguards.
+
+No API key is required.
+
+## Installation
+
+```console
+python -m pip install usaspending-orm
+```
+
+Requires Python 3.9 or newer.
+
+## Quickstart
+
+```python
+from usaspending import USASpendingClient
+
+with USASpendingClient() as client:
+    awards = (
+        client.awards.search()
+        .contracts()
+        .agency("National Aeronautics and Space Administration")
+        .recipient_search_text("Space Exploration Technologies")
+        .fiscal_year(2024)
+        .order_by("Award Amount", "desc")
+        .limit(5)
+    )
+
+    for award in awards:
+        amount = award.total_obligation or 0
+        print(f"{award.award_identifier}: {award.recipient.name} - ${amount:,.2f}")
+```
+
+Queries are lazy. Building the chain makes no request; iteration, `.first()`,
+`.all()`, `.count()`, `len(query)`, indexing, and truth-value testing execute
+the appropriate USAspending operation.
+
+## Documentation
+
+The full documentation covers:
+
+- [installation and core concepts](docs/getting-started/installation.md);
+- [award and transaction searches](docs/guides/search-awards.md);
+- [sessions, lazy loading, caching, and production use](docs/guides/production.md);
+- [generated Python API reference](docs/reference/client.md);
+- [mappings to canonical USAspending endpoints](docs/usaspending-api/endpoint-mapping.md);
+- [known upstream limits and contract differences](docs/usaspending-api/limitations.md).
+
+The repository includes Read the Docs configuration for the published site.
+
+## Development
+
+```console
+git clone https://github.com/planetary-society/usaspending-orm.git
+cd usaspending-orm
+uv sync --locked --group docs
+
+uv run pytest -q
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run --group docs mkdocs build --strict
+```
+
+Integration tests make live USAspending requests and run separately:
+
+```console
+uv run pytest -m integration -q
+```
+
+Preview the documentation site locally with `uv run --group docs mkdocs serve`.
+
+> **Note for contributors**
+>
+> Documentation examples are enforced, not just reviewed. `tests/test_documentation.py`
+> compiles every fenced `python` block under `docs/`, checks that method names cited in
+> prose exist on the public API, and executes most blocks against the live API under the
+> `integration` marker. Adding or removing an example changes the runnable count, so
+> update `_EXPECTED_RUNNABLE_BLOCKS` in the same change.
+>
+> The public API surface is snapshot-tested. When a deliberate change adds, removes, or
+> alters a public callable, regenerate the fixture and review the diff:
+>
+> ```console
+> USASPENDING_REGEN_API_SURFACE=1 uv run pytest tests/test_public_api_surface.py
+> ```
+>
+> The published site builds from `.readthedocs.yaml`. To activate hosting: import
+> `planetary-society/usaspending-orm` in Read the Docs, use `usaspending-orm` as the
+> project slug, and enable pull-request builds. Keep `latest` as the default until a
+> release tag contains the docs configuration, then make `stable` the default
+> user-facing version while retaining `latest` for `main`.
+
+## Project status
+
+The project is in beta. USAspending itself changes over time, and live federal
+data is revised as agencies submit corrections. Counts and values shown in
+examples should not be treated as permanent fixtures.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history and compatibility notes.
+
+## License
+
+USASpending ORM is released under the [MIT License](LICENSE).

usaspending_orm-0.9.1/docs/explanation/caching.md

@@ -0,0 +1,115 @@
+# Caching
+
+Caching is off by default. When enabled, the client stores successful API
+responses and serves repeat requests from the store instead of the network.
+
+```python
+from datetime import timedelta
+
+from usaspending import USASpendingClient, config
+
+config.configure(
+    cache_enabled=True,
+    cache_backend="file",
+    cache_ttl=timedelta(days=1),
+)
+
+with USASpendingClient() as client:
+    award = client.awards.find_by_award_id("80GSFC18C0008")
+```
+
+Configure caching before creating a client. Settings are applied through an
+observer, so a later `configure()` call rebuilds the cache wrapper rather than
+leaving clients on stale settings.
+
+## What gets cached
+
+The unit of caching is one HTTP request, not one query. A cache entry is keyed
+on the endpoint and the full request payload, so two searches that differ in any
+filter, sort, or page are separate entries, and a repeat of the identical
+request is a hit.
+
+Because the unit is the request, caching covers everything the library sends:
+search pages, count calls, award detail lookups, and the follow-up requests
+behind lazy relationships. A loop that reads `award.recipient.location` for many
+awards still issues one request per award the first time, but pays nothing on a
+second pass over the same awards.
+
+Two things are deliberately not stored:
+
+- **Failures.** Errors are never cached, so a transient outage does not poison
+  the store. The next call re-issues the request.
+- **Empty results.** A response the client could not interpret is not stored,
+  and the request falls back to the network.
+
+## Cache misses are never fatal
+
+Reading from the cache is best-effort. If the store is unreadable, locked, or
+corrupt, the client logs a warning and issues the request normally. A broken
+cache degrades performance, never correctness.
+
+API errors are the exception to that fallback: `APIError`, `HTTPError`,
+`RateLimitError`, and `ValidationError` propagate to the caller rather than
+being retried uncached, because they describe the request rather than the cache.
+
+## Backends
+
+`cache_backend="memory"` keeps entries in the process and discards them on exit.
+It suits tests and short scripts, and avoids writing anything to disk.
+
+`cache_backend="file"` is the default and writes pickled responses under
+`cache_dir`, which defaults to `$XDG_CACHE_HOME/usaspending` or
+`~/.cache/usaspending`. Entries survive the process, so a later run reuses what
+an earlier one fetched. That is what makes an interrupted batch job cheap to
+restart, and what lets a script re-run during development stop paying for the
+same pages.
+
+Reuse depends on the request serializing identically each time. The library
+sorts the values of match-any filters for that reason, so a filter built from a
+Python set produces the same request, and therefore the same cache entry, on
+every run.
+
+!!! warning "The file backend unpickles data it reads"
+
+    Unpickling executes code, so the cache directory is a trust boundary. The
+    library creates it with `0700` permissions and restores those permissions if
+    they have been widened, but do not point `cache_dir` at a shared,
+    world-writable, or otherwise untrusted location, and do not use a directory
+    another user can write to.
+
+## Expiry and namespaces
+
+`cache_ttl` sets how long an entry stays fresh; the default is one week. An
+entry older than the TTL is recomputed on next use. `configure()` accepts either
+a `timedelta` or a number of seconds.
+
+Federal spending data is revised after publication, so the TTL is a correctness
+decision as much as a performance one. A long TTL on a reporting job can serve
+figures that agencies have since corrected. Prefer hours or days for anything
+whose numbers get published, and reserve a week for exploratory work.
+
+`cache_namespace` is part of every key, so two projects sharing a `cache_dir` do
+not read each other's entries. Change it to isolate a workload, or to abandon an
+existing set of entries wholesale.
+
+`cache_timeout` bounds how long a caller waits for another worker that is
+already computing the same entry, which keeps concurrent callers from
+stampeding the same request.
+
+## Clearing the cache
+
+There is no public API for clearing the cache. With the file backend, delete the
+files under `cache_dir`; with the memory backend, ending the process is enough.
+Changing `cache_namespace` also abandons the previous entries without deleting
+them.
+
+## Choosing a TTL
+
+- Interactive analysis over a stable slice of history: hours to a day.
+- Repeatedly re-running the same broad query while developing: a day or more,
+  since the point is to stop paying for the same pages.
+- Anything producing published figures: short, or disabled, so a correction
+  upstream is not masked by a stale entry.
+
+See [Production use](../guides/production.md) for how caching interacts with
+rate limiting and long batch runs.

usaspending_orm-0.9.1/docs/explanation/data-model.md

@@ -0,0 +1,52 @@
+# USAspending data model
+
+The library presents several related grains of federal spending data.
+
+## Prime awards
+
+An award is the durable agreement between the federal government and a
+recipient: a contract, grant, loan, direct payment, other assistance, or
+Indefinite Delivery Vehicle. An award accumulates financial activity over its
+lifetime.
+
+`Award` and its subclasses normalize the details endpoint and expose
+relationships such as recipient, agencies, period of performance, place of
+performance, transactions, accounts, funding records, and subawards.
+
+## Transactions
+
+A transaction is an action that changes or reports an award. Examples include
+the initial obligation, a contract modification, an incremental funding
+action, or a deobligation.
+
+Transaction searches therefore have a different grain from award searches:
+
+- award search returns one row per matching award;
+- global transaction search returns one row per matching action;
+- `award.transactions` returns actions belonging to one award.
+
+Summing transaction amounts and reading an award's current total obligation are
+different analytical operations.
+
+## Subawards
+
+A subaward records funding passed from a prime recipient to another
+organization. Subawards are reported separately and do not share every field or
+filter available for prime awards.
+
+## Accounts and funding records
+
+Federal accounts and Treasury Account Symbols describe the appropriations
+accounts behind spending. Award funding records connect transactions to those
+accounts and agencies. These records are useful when the question concerns
+budget authority or the source of funds rather than only the recipient and
+award.
+
+## Aggregations
+
+Spending-by-category endpoints return grouped totals by dimensions such as
+recipient or geography. Their rows are summaries, not awards, and use dedicated
+models.
+
+See [Terminology](../usaspending-api/terminology.md) for links to canonical
+USAspending definitions.