usaspending-orm 0.6.0__py3-none-any.whl

usaspending/resources/agency_resource.py

@@ -0,0 +1,105 @@
+"""Agency resource implementation."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional
+
+from .base_resource import BaseResource
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..models.agency import Agency
+    from ..queries.funding_agencies_search import FundingAgenciesSearch
+    from ..queries.awarding_agencies_search import AwardingAgenciesSearch
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class AgencyResource(BaseResource):
+    """Resource for agency-related operations.
+
+    Provides access to agency overview and detail endpoints.
+    """
+
+    def find_by_toptier_code(
+        self, toptier_code: str, fiscal_year: Optional[int] = None
+    ) -> "Agency":
+        """Retrieve agency overview for a specific toptier code and fiscal year.
+
+        Args:
+            toptier_code: The toptier code of an agency (3-4 digit string)
+            fiscal_year: Optional fiscal year for the data (defaults to current)
+
+        Returns:
+            Agency model instance with full details
+
+        Raises:
+            ValidationError: If toptier_code is invalid
+            APIError: If agency not found
+
+        Example:
+            >>> agency = client.agencies.find_by_toptier_code("080")  # Get NASA for current fiscal year
+            >>> print(agency.name, agency.mission)
+            >>>
+            >>> agency_2023 = client.agencies.find_by_toptier_code("080", fiscal_year=2023)  # Get NASA for FY 2023
+            >>> print(agency_2023.fiscal_year, agency_2023.def_codes)
+        """
+        logger.debug(
+            f"Retrieving agency overview for toptier_code: {toptier_code}, "
+            f"fiscal_year: {fiscal_year}"
+        )
+
+        from ..queries.agency_query import AgencyQuery
+
+        return AgencyQuery(self._client).find_by_id(toptier_code, fiscal_year)
+
+    def find_all_funding_agencies_by_name(self, name: str) -> "FundingAgenciesSearch":
+        """Search for funding agencies and offices by name.
+
+        Args:
+            name: Search text to match against agency/office names
+
+        Returns:
+            FundingAgenciesSearch query builder for iteration and filtering
+
+        Example:
+            >>> # Get all matches (agencies, subtiers, offices)
+            >>> all_results = list(client.agencies.find_all_funding_agencies_by_name("NASA"))
+            >>>
+            >>> # Get only toptier agencies
+            >>> agencies = list(client.agencies.find_all_funding_agencies_by_name("NASA").toptier())
+            >>>
+            >>> # Get only subtier agencies
+            >>> subtiers = list(client.agencies.find_all_funding_agencies_by_name("NASA").subtier())
+            >>>
+            >>> # Get only offices
+            >>> offices = list(client.agencies.find_all_funding_agencies_by_name("NASA").office())
+        """
+        from ..queries.funding_agencies_search import FundingAgenciesSearch
+
+        return FundingAgenciesSearch(self._client).search_text(name)
+
+    def find_all_awarding_agencies_by_name(self, name: str) -> "AwardingAgenciesSearch":
+        """Search for funding agencies and offices by name.
+
+        Args:
+            name: Search text to match against agency/office names
+
+        Returns:
+            AwardingAgenciesSearch query builder for iteration and filtering
+
+        Example:
+            >>> # Get all matches (agencies, subtiers, offices)
+            >>> all_results = list(client.agencies.find_all_awarding_agencies_by_name("NASA"))
+            >>>
+            >>> # Get only toptier agencies
+            >>> agencies = list(client.agencies.find_all_awarding_agencies_by_name("NASA").toptier())
+            >>>
+            >>> # Get only subtier agencies
+            >>> subtiers = list(client.agencies.find_all_awarding_agencies_by_name("NASA").subtier())
+            >>>
+            >>> # Get only offices
+            >>> offices = list(client.agencies.find_all_awarding_agencies_by_name("NASA").office())
+        """
+        from ..queries.awarding_agencies_search import AwardingAgenciesSearch
+
+        return AwardingAgenciesSearch(self._client).search_text(name)

usaspending/resources/award_resource.py

@@ -0,0 +1,119 @@
+"""Award resource implementation."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional
+
+from .base_resource import BaseResource
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..queries.awards_search import AwardsSearch
+    from ..models.award import Award
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class AwardResource(BaseResource):
+    """Resource for award-related operations.
+
+    Provides access to award search and retrieval endpoints.
+    """
+
+    def find_by_generated_id(self, generated_award_id: str) -> "Award":
+        """Retrieve a single award by the system's internally generated
+        award entry ID (e.g. "CONT_AWD_80GSFC18C0008_8000_-NONE-_-NONE-")
+
+        Args:
+            generated_award_id: Unique award identifier
+
+        Returns:
+            Award model instance
+
+        Raises:
+            : If generated_award_id is invalid
+            APIError: If award not found
+        """
+        logger.debug(f"Retrieving award by ID: {generated_award_id}")
+        from ..queries.award_query import AwardQuery
+
+        return AwardQuery(self._client).find_by_generated_id(generated_award_id)
+
+    def find_by_award_id(self, award_id: str) -> Optional["Award"]:
+        """Find an award by its PIID or FAIN unique identifier.
+        Args:
+            award_id: Unique identifier for the award (PIID or FAIN)
+
+        Returns:
+            Award model instance if found, otherwise None
+        """
+        logger.debug(f"Finding award by ID: {award_id}")
+        from ..queries.awards_search import AwardsSearch
+
+        # Get counts by award type
+        search_result = (
+            AwardsSearch(self._client).award_ids(award_id).count_awards_by_type()
+        )
+
+        # Find which type has exactly one result
+        matching_types = [
+            (award_type, count)
+            for award_type, count in search_result.items()
+            if count == 1
+        ]
+
+        if len(matching_types) != 1:
+            total_awards = sum(count for count in search_result.values() if count > 0)
+            if total_awards == 0:
+                logger.info(f"No awards found for ID {award_id}")
+            else:
+                logger.warning(
+                    f"Expected exactly one award for ID {award_id}, found {total_awards} awards across {len(matching_types)} types"
+                )
+            logger.debug(f"Search result: {search_result}")
+            return None
+
+        award_type, _ = matching_types[0]
+        logger.info(f"Found 1 award of type {award_type} for ID {award_id}")
+
+        # Map API response keys to method names
+        method_mapping = {
+            "contracts": "contracts",
+            "grants": "grants",
+            "idvs": "idvs",
+            "loans": "loans",
+            "direct_payments": "direct_payments",
+            "other": "other_assistance",
+        }
+
+        method_name = method_mapping.get(award_type)
+        if not method_name:
+            logger.error(f"Unknown award type from API: {award_type}")
+            return None
+
+        # Create search and apply the appropriate filter
+        awards_search = AwardsSearch(self._client)
+        if hasattr(awards_search, method_name):
+            logger.debug(f"Calling .{method_name}() method on AwardsSearch")
+            awards_search = getattr(awards_search, method_name)()
+            return awards_search.award_ids(award_id).first()
+        else:
+            logger.error(f"Method {method_name} not found on AwardsSearch")
+            return None
+
+    def search(self) -> AwardsSearch:
+        """Create a new award search query builder.
+
+        Returns:
+            AwardSearch query builder for chaining filters
+
+        Example:
+            >>> awards = client.awards.search()
+            ...     .agency("NASA")
+            ...     .in_state("TX")
+            ...     .fiscal_years(2023, 2024)
+            ...     .limit(10)
+        """
+        logger.debug("Creating new AwardsSearch query builder")
+        from ..queries.awards_search import AwardsSearch
+
+        return AwardsSearch(self._client)

usaspending/resources/base_resource.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..client import USASpendingClient
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class BaseResource:
+    """Base class for API resources.
+
+    Resources provide structured gateways to USASpending API endpoints
+    and return appropriate query builders or model instances.
+    """
+
+    def __init__(self, client: USASpendingClient):
+        """Initialize resource with client reference.
+
+        Args:
+            client: USASpendingClient client instance
+        """
+        self._client: USASpendingClient = client
+        logger.debug(f"Initialized {self.__class__.__name__} resource")
+
+    @property
+    def client(self) -> USASpendingClient:
+        """Get client instance."""
+        return self._client

usaspending/resources/download_resource.py

@@ -0,0 +1,102 @@
+# src/usaspending/resources/download_resource.py
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional
+
+from .base_resource import BaseResource
+from ..logging_config import USASpendingLogger
+
+# Import the manager and type aliases
+from ..download.manager import DownloadManager, FileFormat
+from ..download.job import DownloadJob
+from ..models.download import DownloadStatus
+
+if TYPE_CHECKING:
+    from ..client import USASpendingClient
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class DownloadResource(BaseResource):
+    """Resource for award data download operations."""
+
+    def __init__(self, client: USASpendingClient):
+        super().__init__(client)
+        self._manager = DownloadManager(client)
+
+    def contract(
+        self,
+        award_id: str,
+        file_format: FileFormat = "csv",
+        destination_dir: Optional[str] = None,
+    ) -> DownloadJob:
+        """
+        Queue a download job for contract award data.
+
+        Args:
+            award_id: The unique award identifier (e.g., CONT_AWD_...).
+            file_format: Format of the file (csv, tsv, pstxt).
+            destination_dir: Directory where the file will be saved (defaults to CWD).
+
+        Returns:
+            A DownloadJob object. Use job.wait_for_completion() to block until finished.
+        """
+        return self._manager.queue_download(
+            "contract", award_id, file_format, destination_dir
+        )
+
+    def assistance(
+        self,
+        award_id: str,
+        file_format: FileFormat = "csv",
+        destination_dir: Optional[str] = None,
+    ) -> DownloadJob:
+        """
+        Queue a download job for assistance award data.
+
+        Args:
+            award_id: The unique award identifier (e.g., ASST_NON_...).
+            file_format: Format of the file (csv, tsv, pstxt).
+            destination_dir: Directory where the file will be saved (defaults to CWD).
+
+        Returns:
+            A DownloadJob object. Use job.wait_for_completion() to block until finished.
+        """
+        return self._manager.queue_download(
+            "assistance", award_id, file_format, destination_dir
+        )
+
+    def idv(
+        self,
+        award_id: str,
+        file_format: FileFormat = "csv",
+        destination_dir: Optional[str] = None,
+    ) -> DownloadJob:
+        """
+        Queue a download job for IDV (Indefinite Delivery Vehicle) award data.
+
+        Args:
+            award_id: The unique award identifier (e.g., IDV_...).
+            file_format: Format of the file (csv, tsv, pstxt).
+            destination_dir: Directory where the file will be saved (defaults to CWD).
+
+        Returns:
+            A DownloadJob object. Use job.wait_for_completion() to block until finished.
+        """
+        return self._manager.queue_download(
+            "idv", award_id, file_format, destination_dir
+        )
+
+    def status(self, file_name: str) -> DownloadStatus:
+        """
+        Check the status of a specific download job directly via the API.
+
+        Note: Using DownloadJob.refresh_status() is generally preferred.
+
+        Args:
+            file_name: The name of the file returned by the download request.
+
+        Returns:
+            The DownloadStatus model representation.
+        """
+        return self._manager.check_status(file_name)

usaspending/resources/funding_resource.py

@@ -0,0 +1,41 @@
+"""Funding resource implementation."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from .base_resource import BaseResource
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..queries.funding_search import FundingSearch
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class FundingResource(BaseResource):
+    """Resource for funding-related operations.
+
+    Provides access to federal account funding data for awards.
+    """
+
+    def award_id(self, award_id: str) -> "FundingSearch":
+        """Create a funding search query for a specific award.
+
+        Args:
+            award_id: Unique award identifier
+
+        Returns:
+            FundingSearch query builder for chaining filters
+
+        Example:
+            >>> funding = client.funding.award_id("CONT_AWD_123")
+            ...     .order_by("fiscal_date", "asc")
+            ...     .limit(50)
+            >>> for record in funding:
+            ...     print(f"{record.reporting_fiscal_year}-{record.reporting_fiscal_month}: "
+            ...           f"${record.transaction_obligated_amount:,.2f}")
+        """
+        logger.debug(f"Creating funding search for award: {award_id}")
+        from ..queries.funding_search import FundingSearch
+
+        return FundingSearch(self._client).award_id(award_id)

usaspending/resources/recipients_resource.py

@@ -0,0 +1,104 @@
+"""Recipient resource implementation."""
+
+from __future__ import annotations
+from typing import Optional, TYPE_CHECKING
+
+from .base_resource import BaseResource
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..queries.recipients_search import RecipientsSearch
+    from ..models.recipient import Recipient
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class RecipientsResource(BaseResource):
+    """Resource for recipient-related operations.
+
+    Provides access to recipient search and retrieval endpoints.
+    """
+
+    def find_by_recipient_id(self, recipient_id: str) -> Optional["Recipient"]:
+        """Retrieve a single recipient by ID.
+
+        Args:
+            recipient_id: Unique recipient identifier
+
+        Returns:
+            Recipient model instance
+
+        Raises:
+            ValidationError: If recipient_id is invalid
+            APIError: If recipient not found
+        """
+        logger.debug(f"Retrieving recipient by ID: {recipient_id}")
+        from ..queries.recipient_query import RecipientQuery
+
+        return RecipientQuery(self._client).find_by_id(recipient_id)
+
+    def search(self) -> "RecipientsSearch":
+        """Create a new recipient search query builder.
+
+        Returns:
+            RecipientsSearch query builder for recipient searches
+
+        Example:
+            >>> recipients = client.recipients.search()
+            ...     .keyword("california")
+            ...     .award_type("contracts")
+            ...     .order_by("amount", "desc")
+            ...     .limit(10)
+        """
+        logger.debug(
+            "Creating new RecipientsSearch query builder for recipient searches"
+        )
+        from ..queries.recipients_search import RecipientsSearch
+
+        return RecipientsSearch(self._client)
+
+    def find_by_duns(self, duns: str) -> Optional["Recipient"]:
+        """Retrieve a single recipient by DUNS number.
+
+        Args:
+            duns: Unique DUNS identifier
+
+        Returns:
+            Recipient model instance or None if not found
+
+        Raises:
+            ValidationError: If duns is invalid
+        """
+        logger.debug(f"Searching recipient by DUNS: {duns}")
+        from ..queries.recipients_search import RecipientsSearch
+
+        recipients = RecipientsSearch(self._client).keyword(duns).limit(4)
+        # Return the parent recipient if available, otherwise first result
+        for r in recipients:
+            if "-P" in r.recipient_id:
+                return r
+        # Return first result if no parent found (avoids hanging len() call)
+        return recipients.first()
+
+    def find_by_uei(self, uei: str) -> Optional["Recipient"]:
+        """Retrieve a single recipient by UEI number.
+
+        Args:
+            uei: Unique Entity Identifier
+
+        Returns:
+            Recipient model instance or None if not found
+
+        Raises:
+            ValidationError: If uei is invalid
+        """
+        logger.debug(f"Searching recipient by UEI: {uei}")
+        from ..queries.recipients_search import RecipientsSearch
+
+        recipients = RecipientsSearch(self._client).keyword(uei).limit(4)
+        # Return the parent recipient if available, otherwise first result
+        for r in recipients:
+            if "-P" in r.recipient_id:
+                return r
+        # Return first result if no parent found (avoids hanging len() call)
+        return recipients.first()

usaspending/resources/spending_resource.py

@@ -0,0 +1,45 @@
+"""Spending resource implementation."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from .base_resource import BaseResource
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..queries.spending_search import SpendingSearch
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class SpendingResource(BaseResource):
+    """Resource for spending-related operations.
+
+    Provides access to spending by category endpoints (recipient and district).
+    """
+
+    def search(self) -> "SpendingSearch":
+        """Create a new spending search query builder.
+
+        Returns:
+            SpendingSearch query builder for chaining filters
+
+        Example:
+            >>> # Search spending by recipient
+            >>> recipient_spending = client.spending.search()
+            ...     .by_recipient()
+            ...     .agency("National Aeronautics and Space Administration")
+            ...     .fiscal_year(2024)
+            ...     .limit(10)
+
+            >>> # Search spending by district
+            >>> district_spending = client.spending.search()
+            ...     .by_district()
+            ...     .spending_level("awards")
+            ...     .place_of_performance_locations({"country_code": "USA", "state_code": "TX"))
+            ...     .all()
+        """
+        logger.debug("Creating new SpendingSearch query builder")
+        from ..queries.spending_search import SpendingSearch
+
+        return SpendingSearch(self._client)

usaspending/resources/subawards_resource.py

@@ -0,0 +1,68 @@
+"""Subawards resource implementation."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from .base_resource import BaseResource
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..queries.subawards_search import SubAwardsSearch
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class SubAwardsResource(BaseResource):
+    """Resource for subaward-related operations.
+
+    Provides access to subaward search and retrieval endpoints. Subawards
+    represent the secondary distribution of federal funds from prime recipients
+    to subrecipients who carry out portions of the federal program.
+
+    The resource supports searching for both contract subawards (subcontracts)
+    and grant subawards, with filtering by time periods, award types, agencies,
+    and recipients. Results include detailed information about the prime award,
+    subrecipient, and the subaward transaction itself.
+
+    Note: Subaward reporting is required for subawards of $30,000 or more under
+    the Federal Funding Accountability and Transparency Act (FFATA).
+    """
+
+    def search(self) -> "SubAwardsSearch":
+        """Create a subawards search query builder.
+
+        Returns:
+            SubAwardsSearch query builder for chaining filters
+
+        Example:
+            >>> subawards = client.subawards.search()
+            ...     .award_type_codes("A", "B", "C")
+            ...     .time_period("2024-01-01", "2024-12-31")
+            ...     .limit(50)
+            >>> for sub in subawards:
+            ...     print(f"{sub.sub_awardee_name}: ${sub.sub_award_amount:,.2f}")
+        """
+        logger.debug("Creating subawards search query builder")
+        from ..queries.subawards_search import SubAwardsSearch
+
+        return SubAwardsSearch(self._client)
+
+    def award_id(self, award_id: str) -> "SubAwardsSearch":
+        """Create a subawards search query for a specific award.
+
+        This is a convenience method that chains search().award_id(award_id).
+
+        Args:
+            award_id: Unique award identifier
+
+        Returns:
+            SubAwardsSearch query builder for chaining filters
+
+        Example:
+            >>> subawards = client.subawards.award_id("CONT_AWD_123...")
+            ...     .limit(50)
+            >>> for sub in subawards:
+            ...     print(f"{sub.sub_award_date}: {sub.sub_awardee_name}")
+        """
+        logger.debug(f"Creating subawards search for award: {award_id}")
+        return self.search().award_id(award_id)

usaspending/resources/transactions_resource.py

@@ -0,0 +1,39 @@
+"""Transactions resource implementation."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from .base_resource import BaseResource
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..queries.transactions_search import TransactionsSearch
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class TransactionsResource(BaseResource):
+    """Resource for transaction-related operations.
+
+    Provides access to transaction search and retrieval endpoints.
+    """
+
+    def award_id(self, award_id: str) -> "TransactionsSearch":
+        """Create a transactions search query for a specific award.
+
+        Args:
+            award_id: Unique award identifier
+
+        Returns:
+            TransactionsSearch query builder for chaining filters
+
+        Example:
+            >>> transactions = client.transactions.award_id("CONT_AWD_123")
+            ...     .limit(50)
+            >>> for txn in transactions:
+            ...     print(f"{txn.action_date}: ${txn.federal_action_obligation:,.2f}")
+        """
+        logger.debug(f"Creating transactions search for award: {award_id}")
+        from ..queries.transactions_search import TransactionsSearch
+
+        return TransactionsSearch(self._client).award_id(award_id)

usaspending/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Utility modules for USASpending API client."""
+
+from .rate_limit import RateLimiter
+from .retry import RetryHandler
+
+__all__ = ["RateLimiter", "RetryHandler"]