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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (303) hide show
  1. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/.gitignore +1 -0
  2. usaspending_orm-0.10.0/.readthedocs.yaml +17 -0
  3. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/CHANGELOG.md +127 -0
  4. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/LICENSE +1 -1
  5. usaspending_orm-0.10.0/PKG-INFO +153 -0
  6. usaspending_orm-0.10.0/README.md +124 -0
  7. usaspending_orm-0.10.0/docs/explanation/caching.md +115 -0
  8. usaspending_orm-0.10.0/docs/explanation/data-model.md +52 -0
  9. usaspending_orm-0.10.0/docs/explanation/query-execution.md +68 -0
  10. usaspending_orm-0.10.0/docs/getting-started/core-concepts.md +104 -0
  11. usaspending_orm-0.10.0/docs/getting-started/installation.md +47 -0
  12. usaspending_orm-0.10.0/docs/getting-started/quickstart.md +81 -0
  13. usaspending_orm-0.10.0/docs/guides/production.md +106 -0
  14. usaspending_orm-0.10.0/docs/guides/related-data.md +61 -0
  15. usaspending_orm-0.10.0/docs/guides/search-awards.md +215 -0
  16. usaspending_orm-0.10.0/docs/guides/search-transactions.md +71 -0
  17. usaspending_orm-0.10.0/docs/guides/spending-and-downloads.md +160 -0
  18. usaspending_orm-0.10.0/docs/index.md +56 -0
  19. usaspending_orm-0.10.0/docs/reference/client.md +41 -0
  20. usaspending_orm-0.10.0/docs/reference/configuration.md +60 -0
  21. usaspending_orm-0.10.0/docs/reference/models.md +59 -0
  22. usaspending_orm-0.10.0/docs/reference/queries.md +72 -0
  23. usaspending_orm-0.10.0/docs/usaspending-api/endpoint-mapping.md +81 -0
  24. usaspending_orm-0.10.0/docs/usaspending-api/limitations.md +59 -0
  25. usaspending_orm-0.10.0/docs/usaspending-api/terminology.md +55 -0
  26. usaspending_orm-0.10.0/mkdocs.yml +109 -0
  27. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/pyproject.toml +11 -2
  28. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/__init__.py +4 -0
  29. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/client.py +21 -1
  30. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/download/job.py +11 -3
  31. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/__init__.py +8 -0
  32. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/agency.py +2 -39
  33. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/award.py +12 -0
  34. usaspending_orm-0.10.0/src/usaspending/models/country.py +18 -0
  35. usaspending_orm-0.10.0/src/usaspending/models/def_code.py +51 -0
  36. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/download.py +6 -2
  37. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/loan.py +3 -3
  38. usaspending_orm-0.10.0/src/usaspending/models/state.py +20 -0
  39. usaspending_orm-0.10.0/src/usaspending/models/subaward_summary.py +67 -0
  40. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/subtier_agency.py +1 -1
  41. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/transaction.py +16 -0
  42. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/__init__.py +8 -0
  43. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/agencies_search.py +49 -10
  44. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/agency_award_summary.py +5 -4
  45. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/awards_search.py +2 -1
  46. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/base_query.py +12 -1
  47. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/client_side_query_builder.py +3 -20
  48. usaspending_orm-0.10.0/src/usaspending/queries/countries_query.py +37 -0
  49. usaspending_orm-0.10.0/src/usaspending/queries/def_codes_query.py +63 -0
  50. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/filter_tree_query.py +36 -20
  51. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/filters.py +137 -11
  52. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/mixins.py +32 -1
  53. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/query_builder.py +74 -51
  54. usaspending_orm-0.10.0/src/usaspending/queries/states_query.py +38 -0
  55. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/sub_agency_query.py +5 -1
  56. usaspending_orm-0.10.0/src/usaspending/queries/subaward_summary_search.py +132 -0
  57. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/__init__.py +2 -0
  58. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/award_resource.py +23 -0
  59. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/download_resource.py +5 -2
  60. usaspending_orm-0.10.0/src/usaspending/resources/references_resource.py +61 -0
  61. usaspending_orm-0.10.0/src/usaspending/utils/payloads.py +36 -0
  62. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/conftest.py +31 -31
  63. usaspending_orm-0.10.0/tests/fixtures/agency_autocomplete_subtier_offices.json +28 -0
  64. usaspending_orm-0.10.0/tests/fixtures/countries.json +12 -0
  65. usaspending_orm-0.10.0/tests/fixtures/def_codes.json +29 -0
  66. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/public_api_surface.json +152 -1
  67. usaspending_orm-0.10.0/tests/fixtures/spending_by_subaward_grouped.json +26 -0
  68. usaspending_orm-0.10.0/tests/fixtures/states.json +12 -0
  69. usaspending_orm-0.10.0/tests/markdown_examples.py +86 -0
  70. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/mocks/README.md +3 -3
  71. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/mocks/mock_client.py +6 -1
  72. usaspending_orm-0.9.0/tests/volatile_fields.py → usaspending_orm-0.10.0/tests/model_contracts.py +127 -65
  73. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_category_registry.py +6 -4
  74. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_common.py +2 -5
  75. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_types.py +9 -0
  76. usaspending_orm-0.10.0/tests/models/test_def_code.py +52 -0
  77. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_lazy_load.py +19 -15
  78. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_location.py +114 -57
  79. usaspending_orm-0.10.0/tests/models/test_model_field_contracts.py +159 -0
  80. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_recipient.py +25 -50
  81. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_recipient_spending.py +28 -38
  82. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_search_projection.py +47 -32
  83. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_subaward.py +2 -9
  84. usaspending_orm-0.10.0/tests/models/test_subaward_summary.py +61 -0
  85. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_subtier_agency.py +17 -0
  86. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_transaction.py +85 -75
  87. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_transaction_search_projection.py +2 -2
  88. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_agencies_search.py +185 -2
  89. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_agency_award_summary.py +6 -4
  90. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_federal_accounts_query.py +3 -3
  91. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_filters.py +87 -2
  92. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_search_query_builder.py +119 -3
  93. usaspending_orm-0.10.0/tests/queries/test_subaward_summary_search.py +202 -0
  94. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_subawards_search.py +2 -9
  95. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_tas_codes_query.py +3 -3
  96. usaspending_orm-0.10.0/tests/resources/test_references_resource.py +177 -0
  97. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/snapshot_support.py +4 -6
  98. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_client.py +0 -7
  99. usaspending_orm-0.10.0/tests/test_documentation.py +246 -0
  100. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_download_resource.py +57 -4
  101. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_integration.py +7 -5
  102. usaspending_orm-0.10.0/tests/test_live_contract_integration.py +286 -0
  103. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_readme_examples.py +11 -18
  104. usaspending_orm-0.10.0/tests/test_subaward_summary_integration.py +32 -0
  105. usaspending_orm-0.10.0/tests/utils/test_payloads.py +12 -0
  106. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/uv.lock +383 -1
  107. usaspending_orm-0.9.0/PKG-INFO +0 -586
  108. usaspending_orm-0.9.0/README.md +0 -557
  109. usaspending_orm-0.9.0/api-docs-links.md +0 -276
  110. usaspending_orm-0.9.0/tests/fixtures/golden/agency.json +0 -74
  111. usaspending_orm-0.9.0/tests/fixtures/golden/award_account_first_result.json +0 -29
  112. usaspending_orm-0.9.0/tests/fixtures/golden/award_contract.json +0 -190
  113. usaspending_orm-0.9.0/tests/fixtures/golden/award_contract_awarding_agency.json +0 -74
  114. usaspending_orm-0.9.0/tests/fixtures/golden/award_contract_period_of_performance.json +0 -15
  115. usaspending_orm-0.9.0/tests/fixtures/golden/award_contract_place_of_performance.json +0 -23
  116. usaspending_orm-0.9.0/tests/fixtures/golden/award_contract_recipient.json +0 -51
  117. usaspending_orm-0.9.0/tests/fixtures/golden/award_grant.json +0 -198
  118. usaspending_orm-0.9.0/tests/fixtures/golden/award_idv.json +0 -190
  119. usaspending_orm-0.9.0/tests/fixtures/golden/award_loan.json +0 -191
  120. usaspending_orm-0.9.0/tests/fixtures/golden/award_parent_of_contract.json +0 -136
  121. usaspending_orm-0.9.0/tests/fixtures/golden/funding_first_result.json +0 -35
  122. usaspending_orm-0.9.0/tests/fixtures/golden/idv_child_award_first_result.json +0 -192
  123. usaspending_orm-0.9.0/tests/fixtures/golden/recipient.json +0 -60
  124. usaspending_orm-0.9.0/tests/fixtures/golden/search_contract_first_result.json +0 -190
  125. usaspending_orm-0.9.0/tests/fixtures/golden/search_subaward_first_result.json +0 -91
  126. usaspending_orm-0.9.0/tests/fixtures/golden/spending_by_recipient_first_result.json +0 -68
  127. usaspending_orm-0.9.0/tests/fixtures/golden/spending_by_state_first_result.json +0 -17
  128. usaspending_orm-0.9.0/tests/fixtures/golden/transaction_first_result.json +0 -18
  129. usaspending_orm-0.9.0/tests/models/test_volatile_field_mapping.py +0 -177
  130. usaspending_orm-0.9.0/tests/test_golden_master_integration.py +0 -707
  131. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/cli/__init__.py +0 -0
  132. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/cli/download_award.py +0 -0
  133. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/config.py +0 -0
  134. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/download/__init__.py +0 -0
  135. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/download/manager.py +0 -0
  136. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/exceptions.py +0 -0
  137. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/logging_config.py +0 -0
  138. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/award_account.py +0 -0
  139. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/award_factory.py +0 -0
  140. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/award_identifier.py +0 -0
  141. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/award_types.py +0 -0
  142. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/base_model.py +0 -0
  143. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/contract.py +0 -0
  144. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/district_spending.py +0 -0
  145. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/federal_account.py +0 -0
  146. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/funding.py +0 -0
  147. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/grant.py +0 -0
  148. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/idv.py +0 -0
  149. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/lazy_record.py +0 -0
  150. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/location.py +0 -0
  151. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/period_of_performance.py +0 -0
  152. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/procurement_award.py +0 -0
  153. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/recipient.py +0 -0
  154. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/recipient_business_categories.py +0 -0
  155. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/recipient_spending.py +0 -0
  156. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/spending.py +0 -0
  157. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/state_spending.py +0 -0
  158. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/subaward.py +0 -0
  159. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/models/treasury_account_symbol.py +0 -0
  160. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/agency_query.py +0 -0
  161. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/award_accounts_query.py +0 -0
  162. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/award_query.py +0 -0
  163. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/award_transactions_search.py +0 -0
  164. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/awarding_agencies_search.py +0 -0
  165. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/federal_accounts_query.py +0 -0
  166. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/funding_agencies_search.py +0 -0
  167. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/funding_search.py +0 -0
  168. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/idv_child_awards.py +0 -0
  169. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/recipient_query.py +0 -0
  170. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/recipients_search.py +0 -0
  171. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/single_resource_base.py +0 -0
  172. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/spending_search.py +0 -0
  173. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/subawards_search.py +0 -0
  174. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/tas_agencies_query.py +0 -0
  175. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/tas_codes_query.py +0 -0
  176. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/queries/transactions_search.py +0 -0
  177. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/agency_resource.py +0 -0
  178. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/award_accounts_resource.py +0 -0
  179. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/base_resource.py +0 -0
  180. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/funding_resource.py +0 -0
  181. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/recipients_resource.py +0 -0
  182. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/spending_resource.py +0 -0
  183. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/subawards_resource.py +0 -0
  184. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/tas_resource.py +0 -0
  185. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/resources/transactions_resource.py +0 -0
  186. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/utils/__init__.py +0 -0
  187. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/utils/dates.py +0 -0
  188. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/utils/numbers.py +0 -0
  189. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/utils/rate_limit.py +0 -0
  190. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/utils/retry.py +0 -0
  191. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/utils/special_cases.yaml +0 -0
  192. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/utils/textcase.py +0 -0
  193. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/src/usaspending/utils/validations.py +0 -0
  194. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/__init__.py +0 -0
  195. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/agency.json +0 -0
  196. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/agency_autocomplete.json +0 -0
  197. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/agency_award_summary.json +0 -0
  198. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/agency_subagencies.json +0 -0
  199. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/accounts.json +0 -0
  200. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/award_funding_grant.json +0 -0
  201. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/contract.json +0 -0
  202. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/grant.json +0 -0
  203. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/idv.json +0 -0
  204. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/idv_awards.json +0 -0
  205. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/loan.json +0 -0
  206. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/search_results_contracts.json +0 -0
  207. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/search_results_grants.json +0 -0
  208. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/search_results_idvs.json +0 -0
  209. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/search_results_subawards.json +0 -0
  210. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/awards/transactions.json +0 -0
  211. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/download_assistance.json +0 -0
  212. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/download_search.json +0 -0
  213. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/download_status.json +0 -0
  214. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/recipient_university.json +0 -0
  215. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/recipients_search.json +0 -0
  216. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/spending_by_award_contracts.json +0 -0
  217. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/spending_by_district.json +0 -0
  218. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/spending_by_recipient.json +0 -0
  219. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/spending_by_state.json +0 -0
  220. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/spending_by_transaction.json +0 -0
  221. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/spending_by_transaction_count.json +0 -0
  222. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/spending_by_transaction_mixed.json +0 -0
  223. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/tas_agencies.json +0 -0
  224. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/tas_codes.json +0 -0
  225. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/tas_federal_accounts.json +0 -0
  226. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/top_recipients_params.json +0 -0
  227. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/fixtures/top_recipients_response.json +0 -0
  228. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/mocks/__init__.py +0 -0
  229. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/mocks/response_builder.py +0 -0
  230. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/mocks/test_mock_client.py +0 -0
  231. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/__init__.py +0 -0
  232. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_agency.py +0 -0
  233. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_agency_subagencies.py +0 -0
  234. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_agency_tas_integration.py +0 -0
  235. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_account.py +0 -0
  236. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_agency_integration.py +0 -0
  237. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_decimal_precision.py +0 -0
  238. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_factory.py +0 -0
  239. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_identifier.py +0 -0
  240. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_lazy_loading.py +0 -0
  241. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_office_integration.py +0 -0
  242. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_award_type_constants.py +0 -0
  243. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_base_model.py +0 -0
  244. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_district_spending.py +0 -0
  245. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_federal_account.py +0 -0
  246. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_funding.py +0 -0
  247. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_period_of_performance.py +0 -0
  248. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_recipient_business_categories.py +0 -0
  249. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_spending.py +0 -0
  250. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_state_spending.py +0 -0
  251. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/models/test_treasury_account_symbol.py +0 -0
  252. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_agency_query.py +0 -0
  253. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_award_accounts_query.py +0 -0
  254. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_award_transactions_search.py +0 -0
  255. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_awards_search.py +0 -0
  256. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_client_side_query_builder.py +0 -0
  257. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_count_respects_limits.py +0 -0
  258. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_funding_search.py +0 -0
  259. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_idv_child_awards.py +0 -0
  260. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_query_builder.py +0 -0
  261. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_query_builder_list_behavior.py +0 -0
  262. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_query_builder_pagination.py +0 -0
  263. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_recipient_query.py +0 -0
  264. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_recipients_search.py +0 -0
  265. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_single_resource_base.py +0 -0
  266. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_spending_search.py +0 -0
  267. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_spending_search_count.py +0 -0
  268. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_sub_agency_query.py +0 -0
  269. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_tas_agencies_query.py +0 -0
  270. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/queries/test_transactions_search.py +0 -0
  271. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/resources/test_agency_resource.py +0 -0
  272. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/resources/test_award_resource.py +0 -0
  273. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/resources/test_funding_resource.py +0 -0
  274. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/resources/test_recipients_resource.py +0 -0
  275. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/resources/test_spending_resource.py +0 -0
  276. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/resources/test_subawards_resource.py +0 -0
  277. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/resources/test_tas_resource.py +0 -0
  278. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/resources/test_transactions_resource.py +0 -0
  279. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_award_accounts_integration.py +0 -0
  280. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_cache_fallback.py +0 -0
  281. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_characterization.py +0 -0
  282. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_client_caching.py +0 -0
  283. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_client_funding.py +0 -0
  284. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_client_rate_limit.py +0 -0
  285. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_client_security.py +0 -0
  286. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_client_transactions.py +0 -0
  287. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_config.py +0 -0
  288. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_exceptions.py +0 -0
  289. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_logging_config.py +0 -0
  290. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_mock_client_example.py +0 -0
  291. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_public_api_surface.py +0 -0
  292. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/test_spending_integration.py +0 -0
  293. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/__init__.py +0 -0
  294. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/decimal_helpers.py +0 -0
  295. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/test_dates.py +0 -0
  296. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/test_doctests.py +0 -0
  297. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/test_numbers.py +0 -0
  298. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/test_rate_limit.py +0 -0
  299. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/test_retry.py +0 -0
  300. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/test_retry_session_reset.py +0 -0
  301. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/test_special_cases_data.py +0 -0
  302. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/test_textcase.py +0 -0
  303. {usaspending_orm-0.9.0 → usaspending_orm-0.10.0}/tests/utils/test_validations.py +0 -0
@@ -4,6 +4,7 @@ __pycache__
4
4
  .*_cache
5
5
  repomix*
6
6
  dist/
7
+ site/
7
8
  .claude/
8
9
  /~/
9
10
  .coverage
@@ -0,0 +1,17 @@
1
+ version: 2
2
+
3
+ build:
4
+ os: ubuntu-24.04
5
+ tools:
6
+ python: "3.13"
7
+
8
+ python:
9
+ install:
10
+ - method: uv
11
+ command: sync
12
+ groups:
13
+ - docs
14
+
15
+ mkdocs:
16
+ configuration: mkdocs.yml
17
+ fail_on_warning: true
@@ -4,6 +4,133 @@ All notable changes to the USASpending ORM library are documented here.
4
4
  The format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
5
5
  and the project adheres to [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## [0.10.0] - 2026-11-03
8
+
9
+ Tracks upstream usaspending-api changes through November 3, 2026: adds grouped
10
+ subaward summaries per prime award and lazy country and state reference
11
+ queries, and makes `client.references.def_codes()` a lazy query like the other
12
+ reference lookups.
13
+
14
+ **Breaking changes**
15
+
16
+ - `client.references.def_codes()` now returns a lazy `DefCodesQuery` instead
17
+ of a list, matching `client.tas.agencies`. It requests on first evaluation
18
+ and supports in-memory `code()`, `codes()`, and `description()` filters.
19
+ Iteration, `len()`, and indexing remain supported. Call `.all()` when a
20
+ real list is needed, for example for list equality or `append()`.
21
+
22
+ ### Added
23
+
24
+ - `client.awards.subaward_summary()` returns lazy `SubAwardSummarySearch`
25
+ queries over prime awards and their whole-award subaward counts, obligations,
26
+ and ratios. Supports empty filters, mixed award categories, generated-ID
27
+ lookup, and descending generated-ID ordering by default. Counts use one
28
+ award-count request; pagination compensates for incorrect upstream
29
+ continuation metadata. Program activity filters raise `ValidationError`
30
+ because this endpoint silently ignores them. Row retrieval remains subject
31
+ to the API's 50,000-row window.
32
+ - `award_generated_internal_id` on `Award` and `Transaction`, and
33
+ `generated_unique_award_id` on `SubAwardSummary`: aliases, so the generated
34
+ unique award ID reads the same under either name on every model that has it.
35
+ - `client.references.countries()` and `.states()` return fresh lazy
36
+ `CountriesQuery` and `StatesQuery` objects with in-memory `code()`, `codes()`,
37
+ and `description()` filtering. Their `Country` and `State` dataclasses
38
+ preserve API reference strings, including special country codes and
39
+ leading-zero state FIPS values. Call `.all()` for a plain list.
40
+
41
+ ### Changed
42
+
43
+ - Agency autocomplete `search_text()` and `name()` strip surrounding
44
+ whitespace and reject blank or nonstring inputs with `ValidationError`
45
+ during query construction, before making a request. Previously text
46
+ validation occurred when the query was evaluated.
47
+ - `client.agencies.search()`: a set `limit(n)` now sizes the single
48
+ autocomplete request (capped at 500) instead of being clipped to
49
+ `page_size`, so `limit(250)` can return 250 matches.
50
+ `config.default_result_limit` no longer applies to this single-request
51
+ endpoint, keeping `all()`, `len()`, and indexing consistent.
52
+ - A bare string passed as a `psc_codes()` or `tas_codes()` path, such as
53
+ `require=["091"]`, now raises `ValidationError` instead of being split
54
+ into one path level per character.
55
+
56
+ ### Fixed
57
+
58
+ - `SubTierAgency.offices` exposes the `offices` list returned by agency
59
+ autocomplete. Agency-profile `children` still takes precedence when present.
60
+ - `canonical_order()` preserves all iterator values when sorting fails
61
+ because the values are not mutually comparable. Previously the fallback
62
+ could return an empty list after sorting had consumed the iterator.
63
+ - Filter-tree queries (`client.references.def_codes()`, `.countries()`,
64
+ `.states()`, `client.tas.agencies`, and federal account and TAS levels)
65
+ request a level once per query and the filters derived from it. Previously,
66
+ each filtered query evaluated before the original made its own request, so
67
+ `q.code("CA").all()` then `q.code("TX").all()` made two.
68
+
69
+ ### Documentation
70
+
71
+ - Assistance transaction action codes follow GSDM 1.2, can contain multiple
72
+ characters, and are backfilled for historical records. Contract codes are
73
+ unchanged; the existing getter preserves either response shape.
74
+ - Added a grants-only transaction export example for amount/recipient basis
75
+ columns, including row identifiers. Clarified that custom columns replace
76
+ defaults and unknown names may fail after queueing, during file generation.
77
+ Download limits remain server-validated in the current 1 to 500,000 range,
78
+ preserving numeric-string compatibility.
79
+ - Corrected DEFC examples: COVID relief includes `V`; IIJA uses `1` and `Z`.
80
+ Removed the incorrect IRA example. Filter construction remains network-free.
81
+ - Reviewed upstream reveal-date filtering for funding/accounts, narrower
82
+ award-ID regex matching, spending-level-dependent filenames and server-side
83
+ level deduplication; no wrapper changes are needed. LLM integration remains
84
+ deferred because it requires an API key and affects no wrapped endpoint.
85
+
86
+ ## [0.9.1] - 2026-08-27
87
+
88
+ ### Added
89
+
90
+ - `client.references.def_codes()`: fetches the API's current Disaster Emergency
91
+ Fund Code reference data from `/api/v2/references/def_codes/` as `DefCode`
92
+ models. DEF codes change as legislation is enacted, so discover them at
93
+ runtime instead of maintaining a local list; the `def_codes(...)` search
94
+ filter itself remains network-free, and its docstring no longer carries a
95
+ hardcoded code list. `DefCode` moved to `usaspending/models/def_code.py` and
96
+ is exported from `usaspending.models`; the legacy
97
+ `usaspending.models.agency.DefCode` import path still resolves to the same
98
+ class.
99
+ - Client-side validation of classification-filter complexity, mirroring the
100
+ API's hard-coded bounds as reviewed against upstream on 2026-08-25.
101
+ `naics_codes()` rejects more than 200 combined require/exclude codes.
102
+ `psc_codes()` rejects more than 200 simple codes, more than 100 hierarchical
103
+ paths per side, more than 200 combined paths after upstream's PSC Tier-1
104
+ group expansion, and paths deeper than 10 levels after a leading PSC Tier-1
105
+ group name is removed. `tas_codes()` enforces the
106
+ same per-side, combined, and depth bounds. Oversized filters now raise
107
+ `ValidationError` at construction instead of failing at the API.
108
+ - MkDocs documentation site (getting-started guides, API reference, and the
109
+ upstream endpoint mapping) with Read the Docs configuration.
110
+
111
+ ### Changed
112
+
113
+ - `client.agencies.search()` now follows the shared collection semantics.
114
+ `page_size(n)` maps to the endpoint's `limit` parameter (default 100, capped
115
+ at 500) instead of a fixed internal limit of 100; the upstream limit applies
116
+ independently to the toptier, subtier, and office buckets, so one request can
117
+ return up to `3n` rows. `limit(n)` bounds the flattened result consistently
118
+ across `all()`, `count()`, `len()`, indexing, and slicing, and indexing reads
119
+ the single flattened response rather than translating indices into pages the
120
+ endpoint does not have. Zero bounds (`limit(0)`, `max_pages(0)`) resolve
121
+ without a request.
122
+ - `naics_codes()`, `psc_codes()`, and `tas_codes()` copy their inputs, so
123
+ mutating a caller-owned list after building a query no longer alters the
124
+ filter.
125
+
126
+ ### Documentation
127
+
128
+ - Download failure text (`job.error_message`, `DownloadStatus.message`) is
129
+ documented as opaque server-provided text: it may be generic and can change
130
+ without notice, so application control flow should depend on `job.state`.
131
+ When a failed job carries no server message, `job.error_message` is
132
+ `"API reported failure."`.
133
+
7
134
  ## [0.9.0] - 2026-07-30
8
135
 
9
136
  Adds the global transaction search: `client.transactions.search()` covers the
@@ -1,4 +1,4 @@
1
- Copyright 2025 Casey Dreier
1
+ Copyright 2025 Casey Dreier/The Planetary Society
2
2
 
3
3
  Permission is hereby granted, free of charge, to any person obtaining a copy
4
4
  of this software and associated documentation files (the “Software”), to deal
@@ -0,0 +1,153 @@
1
+ Metadata-Version: 2.5
2
+ Name: usaspending-orm
3
+ Version: 0.10.0
4
+ Summary: A Python ORM wrapper for the USAspending.gov API with intuitive queries, automatic pagination, and smart caching
5
+ Project-URL: Homepage, https://github.com/planetary-society/usaspending-orm
6
+ Project-URL: Repository, https://github.com/planetary-society/usaspending-orm
7
+ Project-URL: Issues, https://github.com/planetary-society/usaspending-orm/issues
8
+ Project-URL: Documentation, https://github.com/planetary-society/usaspending-orm/blob/main/README.md
9
+ Author-email: Casey Dreier <casey.dreier@planetary.org>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: api-wrapper,contracts,federal-spending,government-data,grants,orm,usaspending
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Requires-Python: >=3.9
24
+ Requires-Dist: cachier<5.0.0,>=4.1.0
25
+ Requires-Dist: pyyaml<7.0.0,>=6.0.2
26
+ Requires-Dist: requests<3.0.0,>=2.32.4
27
+ Requires-Dist: titlecase<3.0.0,>=2.4.1
28
+ Description-Content-Type: text/markdown
29
+
30
+ # USASpending ORM
31
+
32
+ [![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)
33
+ [![PyPI](https://img.shields.io/pypi/v/usaspending-orm.svg)](https://pypi.org/project/usaspending-orm/)
34
+ [![Python](https://img.shields.io/pypi/pyversions/usaspending-orm.svg)](https://pypi.org/project/usaspending-orm/)
35
+
36
+ USASpending ORM is a typed, ORM-style Python interface to the
37
+ [USAspending.gov API](https://api.usaspending.gov/). It provides fluent query
38
+ builders and navigable models for federal awards, transactions, recipients,
39
+ agencies, spending summaries, Treasury Account Symbols, and bulk downloads.
40
+
41
+ The library is maintained by [The Planetary Society](https://www.planetary.org/).
42
+
43
+ ## Why use it?
44
+
45
+ - Express complex USAspending searches through chainable Python methods.
46
+ - Work with normalized models, `date` values, and exact `Decimal` amounts.
47
+ - Navigate from awards to recipients, agencies, transactions, funding, accounts,
48
+ and subawards.
49
+ - Retain the original API response through each model's `.raw` property.
50
+ - Use built-in pagination, retries, rate limiting, optional caching, and result
51
+ safeguards.
52
+
53
+ No API key is required.
54
+
55
+ ## Installation
56
+
57
+ ```console
58
+ python -m pip install usaspending-orm
59
+ ```
60
+
61
+ Requires Python 3.9 or newer.
62
+
63
+ ## Quickstart
64
+
65
+ ```python
66
+ from usaspending import USASpendingClient
67
+
68
+ with USASpendingClient() as client:
69
+ awards = (
70
+ client.awards.search()
71
+ .contracts()
72
+ .agency("National Aeronautics and Space Administration")
73
+ .recipient_search_text("Space Exploration Technologies")
74
+ .fiscal_year(2024)
75
+ .order_by("Award Amount", "desc")
76
+ .limit(5)
77
+ )
78
+
79
+ for award in awards:
80
+ amount = award.total_obligation or 0
81
+ print(f"{award.award_identifier}: {award.recipient.name} - ${amount:,.2f}")
82
+ ```
83
+
84
+ Queries are lazy. Building the chain makes no request; iteration, `.first()`,
85
+ `.all()`, `.count()`, `len(query)`, indexing, and truth-value testing execute
86
+ the appropriate USAspending operation.
87
+
88
+ ## Documentation
89
+
90
+ The full documentation covers:
91
+
92
+ - [installation and core concepts](docs/getting-started/installation.md);
93
+ - [award and transaction searches](docs/guides/search-awards.md);
94
+ - [sessions, lazy loading, caching, and production use](docs/guides/production.md);
95
+ - [generated Python API reference](docs/reference/client.md);
96
+ - [mappings to canonical USAspending endpoints](docs/usaspending-api/endpoint-mapping.md);
97
+ - [known upstream limits and contract differences](docs/usaspending-api/limitations.md).
98
+
99
+ The repository includes Read the Docs configuration for the published site.
100
+
101
+ ## Development
102
+
103
+ ```console
104
+ git clone https://github.com/planetary-society/usaspending-orm.git
105
+ cd usaspending-orm
106
+ uv sync --locked --group docs
107
+
108
+ uv run pytest -q
109
+ uv run ruff check src/ tests/
110
+ uv run ruff format --check src/ tests/
111
+ uv run --group docs mkdocs build --strict
112
+ ```
113
+
114
+ Integration tests make live USAspending requests and run separately:
115
+
116
+ ```console
117
+ uv run pytest -m integration -q
118
+ ```
119
+
120
+ Preview the documentation site locally with `uv run --group docs mkdocs serve`.
121
+
122
+ > **Note for contributors**
123
+ >
124
+ > Documentation examples are enforced, not just reviewed. `tests/test_documentation.py`
125
+ > compiles every fenced `python` block under `docs/`, checks that method names cited in
126
+ > prose exist on the public API, and executes most blocks against the live API under the
127
+ > `integration` marker. Adding or removing an example changes the runnable count, so
128
+ > update `_EXPECTED_RUNNABLE_BLOCKS` in the same change.
129
+ >
130
+ > The public API surface is snapshot-tested. When a deliberate change adds, removes, or
131
+ > alters a public callable, regenerate the fixture and review the diff:
132
+ >
133
+ > ```console
134
+ > USASPENDING_REGEN_API_SURFACE=1 uv run pytest tests/test_public_api_surface.py
135
+ > ```
136
+ >
137
+ > The published site builds from `.readthedocs.yaml`. To activate hosting: import
138
+ > `planetary-society/usaspending-orm` in Read the Docs, use `usaspending-orm` as the
139
+ > project slug, and enable pull-request builds. Keep `latest` as the default until a
140
+ > release tag contains the docs configuration, then make `stable` the default
141
+ > user-facing version while retaining `latest` for `main`.
142
+
143
+ ## Project status
144
+
145
+ The project is in beta. USAspending itself changes over time, and live federal
146
+ data is revised as agencies submit corrections. Counts and values shown in
147
+ examples should not be treated as permanent fixtures.
148
+
149
+ See [CHANGELOG.md](CHANGELOG.md) for release history and compatibility notes.
150
+
151
+ ## License
152
+
153
+ USASpending ORM is released under the [MIT License](LICENSE).
@@ -0,0 +1,124 @@
1
+ # USASpending ORM
2
+
3
+ [![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)
4
+ [![PyPI](https://img.shields.io/pypi/v/usaspending-orm.svg)](https://pypi.org/project/usaspending-orm/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/usaspending-orm.svg)](https://pypi.org/project/usaspending-orm/)
6
+
7
+ USASpending ORM is a typed, ORM-style Python interface to the
8
+ [USAspending.gov API](https://api.usaspending.gov/). It provides fluent query
9
+ builders and navigable models for federal awards, transactions, recipients,
10
+ agencies, spending summaries, Treasury Account Symbols, and bulk downloads.
11
+
12
+ The library is maintained by [The Planetary Society](https://www.planetary.org/).
13
+
14
+ ## Why use it?
15
+
16
+ - Express complex USAspending searches through chainable Python methods.
17
+ - Work with normalized models, `date` values, and exact `Decimal` amounts.
18
+ - Navigate from awards to recipients, agencies, transactions, funding, accounts,
19
+ and subawards.
20
+ - Retain the original API response through each model's `.raw` property.
21
+ - Use built-in pagination, retries, rate limiting, optional caching, and result
22
+ safeguards.
23
+
24
+ No API key is required.
25
+
26
+ ## Installation
27
+
28
+ ```console
29
+ python -m pip install usaspending-orm
30
+ ```
31
+
32
+ Requires Python 3.9 or newer.
33
+
34
+ ## Quickstart
35
+
36
+ ```python
37
+ from usaspending import USASpendingClient
38
+
39
+ with USASpendingClient() as client:
40
+ awards = (
41
+ client.awards.search()
42
+ .contracts()
43
+ .agency("National Aeronautics and Space Administration")
44
+ .recipient_search_text("Space Exploration Technologies")
45
+ .fiscal_year(2024)
46
+ .order_by("Award Amount", "desc")
47
+ .limit(5)
48
+ )
49
+
50
+ for award in awards:
51
+ amount = award.total_obligation or 0
52
+ print(f"{award.award_identifier}: {award.recipient.name} - ${amount:,.2f}")
53
+ ```
54
+
55
+ Queries are lazy. Building the chain makes no request; iteration, `.first()`,
56
+ `.all()`, `.count()`, `len(query)`, indexing, and truth-value testing execute
57
+ the appropriate USAspending operation.
58
+
59
+ ## Documentation
60
+
61
+ The full documentation covers:
62
+
63
+ - [installation and core concepts](docs/getting-started/installation.md);
64
+ - [award and transaction searches](docs/guides/search-awards.md);
65
+ - [sessions, lazy loading, caching, and production use](docs/guides/production.md);
66
+ - [generated Python API reference](docs/reference/client.md);
67
+ - [mappings to canonical USAspending endpoints](docs/usaspending-api/endpoint-mapping.md);
68
+ - [known upstream limits and contract differences](docs/usaspending-api/limitations.md).
69
+
70
+ The repository includes Read the Docs configuration for the published site.
71
+
72
+ ## Development
73
+
74
+ ```console
75
+ git clone https://github.com/planetary-society/usaspending-orm.git
76
+ cd usaspending-orm
77
+ uv sync --locked --group docs
78
+
79
+ uv run pytest -q
80
+ uv run ruff check src/ tests/
81
+ uv run ruff format --check src/ tests/
82
+ uv run --group docs mkdocs build --strict
83
+ ```
84
+
85
+ Integration tests make live USAspending requests and run separately:
86
+
87
+ ```console
88
+ uv run pytest -m integration -q
89
+ ```
90
+
91
+ Preview the documentation site locally with `uv run --group docs mkdocs serve`.
92
+
93
+ > **Note for contributors**
94
+ >
95
+ > Documentation examples are enforced, not just reviewed. `tests/test_documentation.py`
96
+ > compiles every fenced `python` block under `docs/`, checks that method names cited in
97
+ > prose exist on the public API, and executes most blocks against the live API under the
98
+ > `integration` marker. Adding or removing an example changes the runnable count, so
99
+ > update `_EXPECTED_RUNNABLE_BLOCKS` in the same change.
100
+ >
101
+ > The public API surface is snapshot-tested. When a deliberate change adds, removes, or
102
+ > alters a public callable, regenerate the fixture and review the diff:
103
+ >
104
+ > ```console
105
+ > USASPENDING_REGEN_API_SURFACE=1 uv run pytest tests/test_public_api_surface.py
106
+ > ```
107
+ >
108
+ > The published site builds from `.readthedocs.yaml`. To activate hosting: import
109
+ > `planetary-society/usaspending-orm` in Read the Docs, use `usaspending-orm` as the
110
+ > project slug, and enable pull-request builds. Keep `latest` as the default until a
111
+ > release tag contains the docs configuration, then make `stable` the default
112
+ > user-facing version while retaining `latest` for `main`.
113
+
114
+ ## Project status
115
+
116
+ The project is in beta. USAspending itself changes over time, and live federal
117
+ data is revised as agencies submit corrections. Counts and values shown in
118
+ examples should not be treated as permanent fixtures.
119
+
120
+ See [CHANGELOG.md](CHANGELOG.md) for release history and compatibility notes.
121
+
122
+ ## License
123
+
124
+ USASpending ORM is released under the [MIT License](LICENSE).
@@ -0,0 +1,115 @@
1
+ # Caching
2
+
3
+ Caching is off by default. When enabled, the client stores successful API
4
+ responses and serves repeat requests from the store instead of the network.
5
+
6
+ ```python
7
+ from datetime import timedelta
8
+
9
+ from usaspending import USASpendingClient, config
10
+
11
+ config.configure(
12
+ cache_enabled=True,
13
+ cache_backend="file",
14
+ cache_ttl=timedelta(days=1),
15
+ )
16
+
17
+ with USASpendingClient() as client:
18
+ award = client.awards.find_by_award_id("80GSFC18C0008")
19
+ ```
20
+
21
+ Configure caching before creating a client. Settings are applied through an
22
+ observer, so a later `configure()` call rebuilds the cache wrapper rather than
23
+ leaving clients on stale settings.
24
+
25
+ ## What gets cached
26
+
27
+ The unit of caching is one HTTP request, not one query. A cache entry is keyed
28
+ on the endpoint and the full request payload, so two searches that differ in any
29
+ filter, sort, or page are separate entries, and a repeat of the identical
30
+ request is a hit.
31
+
32
+ Because the unit is the request, caching covers everything the library sends:
33
+ search pages, count calls, award detail lookups, and the follow-up requests
34
+ behind lazy relationships. A loop that reads `award.recipient.location` for many
35
+ awards still issues one request per award the first time, but pays nothing on a
36
+ second pass over the same awards.
37
+
38
+ Two things are deliberately not stored:
39
+
40
+ - **Failures.** Errors are never cached, so a transient outage does not poison
41
+ the store. The next call re-issues the request.
42
+ - **Empty results.** A response the client could not interpret is not stored,
43
+ and the request falls back to the network.
44
+
45
+ ## Cache misses are never fatal
46
+
47
+ Reading from the cache is best-effort. If the store is unreadable, locked, or
48
+ corrupt, the client logs a warning and issues the request normally. A broken
49
+ cache degrades performance, never correctness.
50
+
51
+ API errors are the exception to that fallback: `APIError`, `HTTPError`,
52
+ `RateLimitError`, and `ValidationError` propagate to the caller rather than
53
+ being retried uncached, because they describe the request rather than the cache.
54
+
55
+ ## Backends
56
+
57
+ `cache_backend="memory"` keeps entries in the process and discards them on exit.
58
+ It suits tests and short scripts, and avoids writing anything to disk.
59
+
60
+ `cache_backend="file"` is the default and writes pickled responses under
61
+ `cache_dir`, which defaults to `$XDG_CACHE_HOME/usaspending` or
62
+ `~/.cache/usaspending`. Entries survive the process, so a later run reuses what
63
+ an earlier one fetched. That is what makes an interrupted batch job cheap to
64
+ restart, and what lets a script re-run during development stop paying for the
65
+ same pages.
66
+
67
+ Reuse depends on the request serializing identically each time. The library
68
+ sorts the values of match-any filters for that reason, so a filter built from a
69
+ Python set produces the same request, and therefore the same cache entry, on
70
+ every run.
71
+
72
+ !!! warning "The file backend unpickles data it reads"
73
+
74
+ Unpickling executes code, so the cache directory is a trust boundary. The
75
+ library creates it with `0700` permissions and restores those permissions if
76
+ they have been widened, but do not point `cache_dir` at a shared,
77
+ world-writable, or otherwise untrusted location, and do not use a directory
78
+ another user can write to.
79
+
80
+ ## Expiry and namespaces
81
+
82
+ `cache_ttl` sets how long an entry stays fresh; the default is one week. An
83
+ entry older than the TTL is recomputed on next use. `configure()` accepts either
84
+ a `timedelta` or a number of seconds.
85
+
86
+ Federal spending data is revised after publication, so the TTL is a correctness
87
+ decision as much as a performance one. A long TTL on a reporting job can serve
88
+ figures that agencies have since corrected. Prefer hours or days for anything
89
+ whose numbers get published, and reserve a week for exploratory work.
90
+
91
+ `cache_namespace` is part of every key, so two projects sharing a `cache_dir` do
92
+ not read each other's entries. Change it to isolate a workload, or to abandon an
93
+ existing set of entries wholesale.
94
+
95
+ `cache_timeout` bounds how long a caller waits for another worker that is
96
+ already computing the same entry, which keeps concurrent callers from
97
+ stampeding the same request.
98
+
99
+ ## Clearing the cache
100
+
101
+ There is no public API for clearing the cache. With the file backend, delete the
102
+ files under `cache_dir`; with the memory backend, ending the process is enough.
103
+ Changing `cache_namespace` also abandons the previous entries without deleting
104
+ them.
105
+
106
+ ## Choosing a TTL
107
+
108
+ - Interactive analysis over a stable slice of history: hours to a day.
109
+ - Repeatedly re-running the same broad query while developing: a day or more,
110
+ since the point is to stop paying for the same pages.
111
+ - Anything producing published figures: short, or disabled, so a correction
112
+ upstream is not masked by a stale entry.
113
+
114
+ See [Production use](../guides/production.md) for how caching interacts with
115
+ rate limiting and long batch runs.
@@ -0,0 +1,52 @@
1
+ # USAspending data model
2
+
3
+ The library presents several related grains of federal spending data.
4
+
5
+ ## Prime awards
6
+
7
+ An award is the durable agreement between the federal government and a
8
+ recipient: a contract, grant, loan, direct payment, other assistance, or
9
+ Indefinite Delivery Vehicle. An award accumulates financial activity over its
10
+ lifetime.
11
+
12
+ `Award` and its subclasses normalize the details endpoint and expose
13
+ relationships such as recipient, agencies, period of performance, place of
14
+ performance, transactions, accounts, funding records, and subawards.
15
+
16
+ ## Transactions
17
+
18
+ A transaction is an action that changes or reports an award. Examples include
19
+ the initial obligation, a contract modification, an incremental funding
20
+ action, or a deobligation.
21
+
22
+ Transaction searches therefore have a different grain from award searches:
23
+
24
+ - award search returns one row per matching award;
25
+ - global transaction search returns one row per matching action;
26
+ - `award.transactions` returns actions belonging to one award.
27
+
28
+ Summing transaction amounts and reading an award's current total obligation are
29
+ different analytical operations.
30
+
31
+ ## Subawards
32
+
33
+ A subaward records funding passed from a prime recipient to another
34
+ organization. Subawards are reported separately and do not share every field or
35
+ filter available for prime awards.
36
+
37
+ ## Accounts and funding records
38
+
39
+ Federal accounts and Treasury Account Symbols describe the appropriations
40
+ accounts behind spending. Award funding records connect transactions to those
41
+ accounts and agencies. These records are useful when the question concerns
42
+ budget authority or the source of funds rather than only the recipient and
43
+ award.
44
+
45
+ ## Aggregations
46
+
47
+ Spending-by-category endpoints return grouped totals by dimensions such as
48
+ recipient or geography. Their rows are summaries, not awards, and use dedicated
49
+ models.
50
+
51
+ See [Terminology](../usaspending-api/terminology.md) for links to canonical
52
+ USAspending definitions.
@@ -0,0 +1,68 @@
1
+ # Query execution
2
+
3
+ Query builders separate request construction from execution.
4
+
5
+ ## Lazy construction
6
+
7
+ Filter, sort, and limit calls modify the builder without making an HTTP
8
+ request:
9
+
10
+ ```python
11
+ query = (
12
+ client.awards.search()
13
+ .contracts()
14
+ .agency("National Aeronautics and Space Administration")
15
+ .fiscal_year(2024)
16
+ .limit(25)
17
+ )
18
+ ```
19
+
20
+ The request begins when code:
21
+
22
+ - iterates over the query;
23
+ - calls `.all()`, `.first()`, or `.count()`;
24
+ - calls `len(query)`;
25
+ - indexes or slices the query;
26
+ - evaluates its truth value.
27
+
28
+ ## Pagination
29
+
30
+ Iteration requests pages as needed and stops when the API is exhausted or a
31
+ configured bound is reached. Query builders expose list-like operations, but
32
+ they do not pre-load the entire result set.
33
+
34
+ `.all()` materializes the bounded query into a list. Prefer iteration when
35
+ streaming pages is sufficient.
36
+
37
+ ## Count consistency
38
+
39
+ `count()` uses a companion endpoint when USAspending provides one. Library
40
+ limits are applied to the reported value so these expressions agree for a
41
+ bounded query:
42
+
43
+ ```python
44
+ query = client.awards.search().contracts().fiscal_year(2024).limit(10)
45
+
46
+ query.count()
47
+ len(query)
48
+ len(query.all())
49
+ ```
50
+
51
+ Some upstream search and count endpoints accept different filters. When a
52
+ correct count cannot be requested, the library raises `ValidationError` rather
53
+ than returning a misleading number.
54
+
55
+ ## Immutable chaining
56
+
57
+ Fluent methods return a clone with the new filter, sort, or bound. A partly
58
+ built query can therefore be used as an immutable template:
59
+
60
+ ```python
61
+ base = client.awards.search().contracts().fiscal_year(2024)
62
+ california = base.place_of_performance_locations(
63
+ {"country_code": "USA", "state_code": "CA"}
64
+ )
65
+ ```
66
+
67
+ After this call, `base` remains unchanged and `california` carries the added
68
+ location filter.