usaspending-orm 0.6.0__py3-none-any.whl

usaspending_orm-0.6.0.dist-info/METADATA

@@ -0,0 +1,324 @@
+Metadata-Version: 2.3
+Name: usaspending-orm
+Version: 0.6.0
+Summary: A Python ORM wrapper for the USAspending.gov API with intuitive queries, automatic pagination, and smart caching
+License: MIT
+Keywords: usaspending,federal-spending,government-data,api-wrapper,orm,contracts,grants
+Author: Casey Dreier
+Author-email: casey.dreier@planetary.org
+Requires-Python: >=3.9
+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-Dist: cachier (>=4.1.0,<5.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: requests (>=2.32.4,<3.0.0)
+Requires-Dist: titlecase (>=2.4.1,<3.0.0)
+Project-URL: Documentation, https://github.com/planetary-society/usaspending-orm/blob/main/README.md
+Project-URL: Homepage, https://github.com/planetary-society/usaspending-orm
+Project-URL: Issues, https://github.com/planetary-society/usaspending-orm/issues
+Project-URL: Repository, https://github.com/planetary-society/usaspending-orm
+Description-Content-Type: text/markdown
+
+# USASpending ORM
+
+A python library that provides an object-relational mapping layer to the USAspending.gov API.
+
+## Why This Library?
+
+[USASpending.gov](https://usaspending.gov) is the official federal database for tracking U.S. government spending, and provides extensive data on federal contracts, grants, and other awards since 2007-10-01, enabling citizens to track how federal money is spent.
+
+The platform has a [comprehensive API](https://api.usaspending.gov) for querying the data, but the API is complex and can be cumbersome to work with. This library provides an abstraction layer and other quality-of-life improvements to enable rapid development of applications that consume USASpending data.
+
+## Key Features
+
+**🔗 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. 
+
+**⚡️ 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.
+
+**🛡️ Data Normalization and Type Casting** - Consistent field naming across resources, with lazy-loading for nested data and automatic type conversion.
+
+**🥩 Raw API Output Preserved** - Access the original API JSON response via the `.raw` property on any resource object when you need the underlying data structure.
+
+## Installation
+
+```bash
+pip install usaspending-orm
+```
+
+Requires Python 3.9 or higher. No API key required.
+
+## Usage
+
+The library provides a `USASpendingClient` class that manages the connection to the USASpending API and provides access to various resources such as awards, recipients, agencies, etc. This can be used as a context manager to ensure proper session management
+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
+```
+
+#### Searching for Awards
+
+You can query awards data using the `search()` method on the `client.awards` object:
+
+```python
+
+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.
+
+``` python
+awards_query = client.awards.search() \
+    .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.
+
+### Example: Searching for NASA 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") \
+        .recipient_search_text("Space Exploration Technologies") \
+        .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')
+    top_spacex_award.category  # -> "contract"
+    top_spacex_award.description  # -> "The Commercial Crew Program (CCP) contract ...."
+    
+    # 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)
+
+    # 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_type_description  # -> "SUPPLEMENTAL AGREEMENT FOR WORK WITHIN SCOPE"
+
+```
+
+## Configuration
+
+### Session Management and Lazy-Loading
+
+The library uses lazy-loading to avoid unnecessary API calls. Missing award and Recipient properties will trigger an API call to fetch the missing data. This means models require an active client session to load missing data on demand.
+
+#### Session Lifecycle
+
+Use the client as a context manager (recommended) or explicitly call `close()`:
+
+```python
+with USASpendingClient() as client:
+    awards = client.awards.search().agencies("NASA").all()
+    for award in awards:
+        # Access lazy-loaded properties inside the context
+        print(f"{award.recipient.name}: ${award.total_obligation:,.2f}")
+        print(f"Subawards: {award.subaward_count}")
+# Session automatically closed here
+
+# Or explicitly manage session
+client = USASpendingClient()
+awards = client.awards.search().agencies("NASA").all()
+client.close()
+```
+
+Accessing related properties after the client session closes raises a `DetachedInstanceError`:
+
+```python
+# This will raise DetachedInstanceError
+with USASpendingClient() as client:
+    awards = client.awards.search().all()
+# Client is closed here
+
+# This will raise DetachedInstanceError
+print(awards[0].transactions.count())
+```
+
+You can also reattach objects to a new session if needed:
+
+```python
+# Create objects in one session
+with USASpendingClient() as client:
+    award = client.awards.find_by_award_id("80GSFC18C0008")
+
+# Reattach to a new session to access related properties
+with USASpendingClient() as new_client:
+    award.reattach(new_client)
+    print(f"Subawards: {award.subawards.count()}")  # Works!
+
+    # Recursive reattach for nested objects
+    award.reattach(new_client, recursive=True)
+    print(f"Recipient: {award.recipient.name}")  # Recipient also reattached
+```
+
+### Performance & Caching
+
+By default, caching is **disabled**. However, enabling caching can dramatically improve performance and reduce API load for repeated queries, especially during development or when working with large datasets.
+
+To enable caching, load the configuration module and set `cache_enabled=True` before creating a client instance:
+
+```python
+from usaspending import config as usaspending_config, USASpendingClient
+
+# Enable with defaults (1 week TTL, file-based storage)
+usaspending_config.configure(cache_enabled=True)
+
+with USASpendingClient() as client:
+    # All queries will now be cached
+    awards = client.awards.search().agencies("NASA").all()
+```
+
+The library defaults to file-based caching with a 1-week TTL, but you can customize these settings as needed:
+
+```python
+usaspending_config.configure(
+    cache_enabled=True,           # Enable caching
+    cache_ttl=86400,              # Cache for 1 day (default: 1 week)
+    cache_backend="memory",         # "file" or "memory" (default: "file")
+)
+```
+
+**File-based caching** (default):
+- Persists between Python sessions
+- Stored in `~/.cache/usaspending` directory
+- Uses pickle for serialization
+- Best for production and development workflows
+
+**Memory-based caching**:
+- Faster access, no disk I/O
+- Cleared when Python process ends
+- Best for single-session data exploration
+- Enable with `cache_backend="memory"`
+
+### Customizable Settings
+
+The library applies some sensible defaults that work for most use cases:
+
+- Rate limiting: 1000 calls per 5 minutes (respecting USASpending API limits)
+- Caching: disabled by default (see Performance & Caching section above to enable)
+
+Customize these settings before creating a client instance if needed:
+
+```python
+from usaspending import config as usaspending_config
+
+# Configure settings before creating the client
+usaspending_config.configure(
+    # Cache settings (caching is disabled by default)
+    cache_enabled=True,           # Enable caching
+    # Set file-cache directory (default: ~/.usaspending_cache)
+    cache_dir="/tmp/usaspending_cache",
+    # Set cache expiration time (default 1 week)
+    cache_ttl=86400,
+    # Set cache backend to be in-memory "memory" or "file" for file-based caching via pickle (default: "file")
+    cache_backend="memory",
+
+    # Set rate limiting parameters
+    # Set number of calls allowed within the rate limit period (default: 1000)
+    rate_limit_calls=500,
+    # Rate limit period (in seconds, default: 300)
+    rate_limit_period=60,
+
+    # Set HTTP request parameters (default: max_retries=3, timeout=30)
+    # Set number of retries for failed requests (default: 3)
+    max_retries=5,
+    # Set delay between retries in seconds (default: 1.0)
+    retry_delay=10.0,
+    # Set exponential backoff factor for retries (default: 2.0)
+    retry_backoff=2.0,
+    # Set request timeout in seconds (default: 30)
+    timeout=60  # Longer timeout for slow connections (default: 30)
+)
+
+```
+
+### Logging Configuration
+
+The library provides detailed logging, which you can configure in your application:
+
+```python
+import logging
+from usaspending import USASpendingClient
+
+# Configure root logger (affects all loggers)
+logging.basicConfig(
+    level=logging.DEBUG,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+```
+
+## Project Status
+
+USASpending Python Wrapper is under active development. The API is stabilizing but may change as we refine the abstractions based on real-world usage. We welcome feedback on the interface design and feature priorities.
+
+## Contributing
+
+We welcome contributions to improve and expand the implementation and functionality.
+
+## About The Planetary Society
+
+This library was initially developed to serve the needs of The Planetary Society's Space Policy and Advocacy team in tracking and analyzing NASA 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. 
+
+[The Planetary Society](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.
+
+Please consider supporting our work by [becoming a member](https://www.planetary.org/join).
+
+## License
+
+MIT License

usaspending_orm-0.6.0.dist-info/RECORD

@@ -0,0 +1,71 @@
+usaspending/__init__.py,sha256=BPvQX8G5KWBENY_8FGLKM1Hw3zhX6wFaTy1Le9Owg0w,2883
+usaspending/cli/__init__.py,sha256=sPye9ET6WpgL2cV0f87VwwFxW0vdkUJCD8GhvXw1bfA,97
+usaspending/cli/download_award.py,sha256=Hpd_xWIJE5cDXyUUabN5ET9r8nhT4PJqtC5RAcYYOGU,3880
+usaspending/client.py,sha256=qEefGeDnA66hvrW3ewlw3cOO9iSmNcCMaoveHUdah9c,20542
+usaspending/config.py,sha256=540_eb0lrLtSNLecoJYkimjtdkeJyE7TqfeixD7413s,4660
+usaspending/download/__init__.py,sha256=J0m49mqDahgaBaqkMWh40YIdv9s2qbUDzFDlxRtYB4A,217
+usaspending/download/job.py,sha256=NhBO-Q3Ps7LV_prqwMLdkgQYEnmGRXaut-0wg13aUyg,9141
+usaspending/download/manager.py,sha256=y-LB6LsusxHzKv3mtlVbpoR5m_w13a9WzlsJQc6L-ko,4866
+usaspending/exceptions.py,sha256=qJBIXscEMOAGCPatsGw8LV_QykNFcF8kDshRyAgU6kM,2122
+usaspending/logging_config.py,sha256=u1RUobFwqTxdApTL2bkmD9CrFsDNyPOWR7dLv4j_I54,10035
+usaspending/models/__init__.py,sha256=qq280kZ1eBimRnXRnGoP1PjuzVlGMK9cgSSgwzRTkuQ,1929
+usaspending/models/agency.py,sha256=qaeeC9uZ7V_6Kr07EZBdZAEW-lf7mq8j1N3WJS4cb9o,22860
+usaspending/models/award.py,sha256=Z7KNJwWThJSpIREKmGYPGxNu9zI0BCpsJu9awhev92k,35115
+usaspending/models/award_factory.py,sha256=qSZlvE3aH_wmEb7NBUvpwdsWT-N06LecUms8pcZ4B8k,2344
+usaspending/models/award_types.py,sha256=qg-IpV-nfmOw4DY_1Pv6Y-rLAMw-6gjVDGhesr7Ic8s,3454
+usaspending/models/base_model.py,sha256=ckpGUMAXV9Es_--Qe8JLFhjzeYjXUoOoABaLw6_lZT8,7871
+usaspending/models/contract.py,sha256=g365RGmRwbtR-70lgvn4KN8dwu4slL7cqRJ-plse86U,5530
+usaspending/models/district_spending.py,sha256=F-1rRQzjaigjZgR_NQX9wz0qy1xg5TZ1GGIGYec5EXY,2251
+usaspending/models/download.py,sha256=2EtYV5HfOw-k2kiJ00CP29ycc5yoDj3z_7u64Bu340A,2256
+usaspending/models/funding.py,sha256=kSDf-89eHiuceZMA42OnsvR3EtrOYU34WTh1trUDtKk,6264
+usaspending/models/grant.py,sha256=xC6eZUeJAejMOmTmjQLArF0yoUobWtdmyxw_W_cjXaQ,5361
+usaspending/models/idv.py,sha256=yCoETfmSS0XGd4l4sk3URs3D21aTGEl9ybDSfOL36Ic,6000
+usaspending/models/lazy_record.py,sha256=MDTDI-jllvFoNlD5ehR62uHrSpEH9OtnLAkHAcGBm_c,2696
+usaspending/models/loan.py,sha256=DX70qy5qqdzj9ld9LWC92FWggn5RT7T9-EBlEkJzG2w,2737
+usaspending/models/location.py,sha256=OxJoW6GuPV2Y1a53EFae3Zj7exnVpq1KLva4HitjBss,4243
+usaspending/models/period_of_performance.py,sha256=b3PINSlNS8CXApQuL1IxlcDQA7SpPbgR_nULuMmRIq8,1310
+usaspending/models/recipient.py,sha256=gWjds0VwsdTFLf6pKfc3NGXbkQBotAQs3tUZUNhqs9E,7033
+usaspending/models/recipient_business_categories.py,sha256=NktngrJVNj-pZgEcNPC5dpo2pomIBQL3IGAktL5Ei14,13541
+usaspending/models/recipient_spending.py,sha256=HG9HFNmN31UY-1wQOiwa4fKwxKnIVAWUYy2MVG3HSAM,1911
+usaspending/models/spending.py,sha256=knRZFu73n0pQE4olxkem5mn2tP_2gEECDoIOnNaPYxM,2273
+usaspending/models/state_spending.py,sha256=WJqgDkod6vPob2bjT66LyQnaIBjK-pZ1hZh-bHhKai0,1243
+usaspending/models/subaward.py,sha256=ZrSL2Rmt-IfmKoEs3-KvAPIT8ZzQM878ASKjQJ2SpfY,9143
+usaspending/models/subtier_agency.py,sha256=VnONlbhXSoODBDjtBDaqaxWOVz9lluFIJ8MTGrLv8Ag,3248
+usaspending/models/transaction.py,sha256=I89e6x8BxHTCuFNxNP-elCPvrRiI6DFhjWyeUzSpnl0,2614
+usaspending/queries/__init__.py,sha256=M4oSxgREUItpdjYsK0zlHdePeyOVYfkwZRLTI_dhubw,2573
+usaspending/queries/agencies_search.py,sha256=Z5AouE7OjwPtcDFBLupByCKyTqasjx0E9XswCytHJAU,6671
+usaspending/queries/agency_award_summary.py,sha256=0d6TeNAqfzUjEMZv-om34aPP7nbquGO563OYctsubjI,4736
+usaspending/queries/agency_query.py,sha256=JZwHKJDbgS1deF_0a6-Ui2RSiPVOk90VSZ_umv-PJ1A,3282
+usaspending/queries/award_query.py,sha256=W5dnL27PEM_ltwN93ZtRZPgxtpR-82I8zhucOuqlmQs,1325
+usaspending/queries/awarding_agencies_search.py,sha256=kyVBSj_nWy7A2PBHNI0ucZPGvsIac3kVL05_EKvXs9c,522
+usaspending/queries/awards_search.py,sha256=W4gq69p5H02IXMABuC2HJihdhqD1fTeH7Kc5AZ6INQE,21796
+usaspending/queries/filters.py,sha256=V-qk1vbY44M63yetqWeRLwbMH9BUgIB0iY-mUxEN3wc,13151
+usaspending/queries/funding_agencies_search.py,sha256=OVoxZ85okyHT-zWvQxvIUps4QCM2l74Mb6Krd6ITY8c,579
+usaspending/queries/funding_search.py,sha256=zuXtfYoaT7UP6ltip-2P74u9cvTr1UmFl3qDtlq34qs,6044
+usaspending/queries/query_builder.py,sha256=xMo11-tpiromUsmoleIzQw0iblYBVqjHeX6zK6qWeec,48429
+usaspending/queries/recipient_query.py,sha256=trTpNs2PoS2lnZlu6uJNohodGfpQ5fEcNbh2cCeZ4rk,1964
+usaspending/queries/recipients_search.py,sha256=sucHS74_EvvxQtYHXsXwMemuQUeFbzAEyx4fM3hroRg,5283
+usaspending/queries/single_resource_base.py,sha256=eR33FGfmjvEkuVcmqdWIKhy2-AV_vltMStPveaZ3qk0,2582
+usaspending/queries/spending_search.py,sha256=yT5YRMiGwwHczEitnFD6E21ub5evpSzRU5UP_3qDqu0,9175
+usaspending/queries/sub_agency_query.py,sha256=EmA7jnMYH0eoUZlbeMWBsUJgtJWsk9OcWS_iUay9ilg,6090
+usaspending/queries/subawards_search.py,sha256=EkYR9Hp5xihNmUVF4rYaO2xAol8ng2OGR3ca1MpSrs4,6765
+usaspending/queries/transactions_search.py,sha256=BaIyNYjirel473RsVfBb7A78-HMsq9KsC22bU5ByfaA,6986
+usaspending/resources/__init__.py,sha256=DDapBVA8oWJ5OhMiVKcpvzullaQIQnXXZOsgzAce6mY,519
+usaspending/resources/agency_resource.py,sha256=sCkd3N9qq6l0KA9kzJ7YpZaglD2BAEnFiQRuGWpjIUk,4112
+usaspending/resources/award_resource.py,sha256=asQtwSJqoN9SrH10yzzedO38f0v88dG9jcTFNAJ-XN8,4099
+usaspending/resources/base_resource.py,sha256=hTW6PQzMIRJLASNbZGwRgbEzz23cE9CQryBE3uLq0pI,857
+usaspending/resources/download_resource.py,sha256=tvie9-bADoUo2CdNxBjRFppJQyu5CVo2-WhYg1bIb7k,3317
+usaspending/resources/funding_resource.py,sha256=oOrKvXYHOsdhRUxtLwsVPXzLpL1jKBUgFUc8q3hRhUI,1320
+usaspending/resources/recipients_resource.py,sha256=69_PXs_U8nff2T98OqlaYyvu4Ci5rH7VGggbXd3C1Ro,3405
+usaspending/resources/spending_resource.py,sha256=3bgx9UT1EBNwaG5y9JGNIG2KwpGNQf0P928v9kA5W2I,1485
+usaspending/resources/subawards_resource.py,sha256=9kPkMoLtl_dDXz6uUZzyNoFUBLZAQkfVsvUvV1u8xlM,2506
+usaspending/resources/transactions_resource.py,sha256=w59lgeI9-RiuIJbpeVrf3kw263LYItaIuQmmwbWOSz4,1261
+usaspending/utils/__init__.py,sha256=cNBG9a6iXmFL5o1KBkx-twze8aGNwCd_DKRvjq25I-o,162
+usaspending/utils/formatter.py,sha256=c3PjA8CVtgOaDDeJyRIYdt56EVhGEQAmXgVQAziqsL8,18887
+usaspending/utils/rate_limit.py,sha256=arrLc005aQzWNeJQ1X-i6x5MiY_WO-YVUz5rqprnr9c,4491
+usaspending/utils/retry.py,sha256=ZT4jiFOhCDhQZ7ARfTlajRQbyI_K7Ki_F21ArqDO52A,9595
+usaspending/utils/special_cases.yaml,sha256=j9U2G1X0f5WsH6N09yxkatEunFvgen1hW8YChB0odTE,1520
+usaspending_orm-0.6.0.dist-info/LICENSE,sha256=0rHeJ0XSOcGl2dUAZhbnjaXYriSegKkgY8id5eBpCWc,1060
+usaspending_orm-0.6.0.dist-info/METADATA,sha256=ROUfdvvv8t_vwgWV2KEtyLmqKkB-kWCOmuzErZt1POE,13143
+usaspending_orm-0.6.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+usaspending_orm-0.6.0.dist-info/RECORD,,

usaspending_orm-0.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any