usaspending-orm 0.6.0__py3-none-any.whl

usaspending/queries/sub_agency_query.py

@@ -0,0 +1,177 @@
+"""Sub-agency query implementation for retrieving agency sub-agencies with pagination."""
+
+from typing import TYPE_CHECKING, Optional, Dict, Any, List
+from .single_resource_base import SingleResourceBase
+from ..exceptions import ValidationError
+from ..client import USASpendingClient
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    pass
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class SubAgencyQuery(SingleResourceBase):
+    """Retrieve sub-agency data from the USAspending API.
+
+    This query class handles fetching sub-agency information including
+    transaction counts and obligations filtered by fiscal year, agency type,
+    and award type codes.
+    """
+
+    def __init__(self, client: USASpendingClient):
+        """Initialize SubAgencyQuery with client.
+
+        Args:
+            client: USASpendingClient client instance
+        """
+        super().__init__(client)
+        logger.debug("SubAgencyQuery initialized with client: %s", client)
+
+    @property
+    def _endpoint(self) -> str:
+        """Base endpoint for sub-agency retrieval."""
+        return "/agency/{toptier_code}/sub_agency/"
+
+    def _construct_endpoint(self, resource_id: str) -> str:
+        """Construct the full endpoint URL for agency sub-agency.
+
+        Args:
+            resource_id: The toptier_code for the agency
+
+        Returns:
+            Full endpoint path including /sub_agency/
+        """
+        endpoint = self._endpoint.replace("{toptier_code}", resource_id)
+        return endpoint
+
+    def find_by_id(self, toptier_code: str) -> Dict[str, Any]:
+        """Not used for sub-agency - use get_subagencies instead.
+
+        Raises:
+            NotImplementedError: This method should not be used directly
+        """
+        raise NotImplementedError(
+            "Use get_subagencies() method instead for sub-agency data"
+        )
+
+    def get_subagencies(
+        self,
+        toptier_code: str,
+        fiscal_year: Optional[int] = None,
+        agency_type: str = "awarding",
+        award_type_codes: Optional[List[str]] = None,
+        order: str = "desc",
+        sort: str = "total_obligations",
+        page: int = 1,
+        limit: int = 100,
+    ) -> Dict[str, Any]:
+        """Retrieve agency sub-agencies with optional filters and pagination.
+
+        Args:
+            toptier_code: The toptier code of an agency (3-4 digit string)
+            fiscal_year: Optional fiscal year for the data (defaults to current)
+            agency_type: "awarding" or "funding" (defaults to "awarding")
+            award_type_codes: Optional list of award type codes to filter by
+            order: Sort direction "asc" or "desc" (defaults to "desc")
+            sort: Sort field - "name", "total_obligations", "transaction_count", "new_award_count"
+            page: Page number (defaults to 1)
+            limit: Items per page, max 100 (defaults to 100)
+
+        Returns:
+            Dictionary containing:
+                - toptier_code: Agency toptier code
+                - fiscal_year: Fiscal year of data
+                - page_metadata: Pagination metadata
+                - results: List of sub-agency data
+                - messages: Any API messages
+
+        Raises:
+            ValidationError: If toptier_code is invalid or other parameters are invalid
+            APIError: If API request fails
+        """
+        # Validate toptier_code
+        if not toptier_code:
+            raise ValidationError("toptier_code is required")
+
+        toptier_code = str(toptier_code).strip()
+        if not toptier_code.isdigit() or len(toptier_code) not in [3, 4]:
+            raise ValidationError(
+                f"Invalid toptier_code: {toptier_code}. "
+                "Must be a 3-4 digit numeric string"
+            )
+
+        # Validate agency_type
+        if agency_type not in ["awarding", "funding"]:
+            raise ValidationError(
+                f"Invalid agency_type: {agency_type}. Must be 'awarding' or 'funding'"
+            )
+
+        # Validate order
+        if order not in ["asc", "desc"]:
+            raise ValidationError(f"Invalid order: {order}. Must be 'asc' or 'desc'")
+
+        # Validate sort
+        valid_sorts = [
+            "name",
+            "total_obligations",
+            "transaction_count",
+            "new_award_count",
+        ]
+        if sort not in valid_sorts:
+            raise ValidationError(
+                f"Invalid sort: {sort}. Must be one of: {', '.join(valid_sorts)}"
+            )
+
+        # Validate page
+        if page < 1:
+            raise ValidationError("page must be >= 1")
+
+        # Validate limit
+        if limit < 1 or limit > 100:
+            raise ValidationError("limit must be between 1 and 100")
+
+        logger.debug(
+            "Fetching sub-agencies for toptier_code: %s, fiscal_year: %s, "
+            "agency_type: %s, award_type_codes: %s, order: %s, sort: %s, "
+            "page: %s, limit: %s",
+            toptier_code,
+            fiscal_year,
+            agency_type,
+            award_type_codes,
+            order,
+            sort,
+            page,
+            limit,
+        )
+
+        # Build params
+        params = {
+            "agency_type": agency_type,
+            "order": order,
+            "sort": sort,
+            "page": page,
+            "limit": limit,
+        }
+
+        if fiscal_year is not None:
+            params["fiscal_year"] = fiscal_year
+
+        if award_type_codes:
+            # Convert to list if needed and filter out None/empty values
+            if isinstance(award_type_codes, (set, frozenset)):
+                award_type_codes = list(award_type_codes)
+            award_type_codes = [code for code in award_type_codes if code]
+
+            if award_type_codes:
+                # API expects award_type_codes as array parameter
+                params["award_type_codes"] = award_type_codes
+
+        # Construct endpoint
+        endpoint = self._construct_endpoint(toptier_code)
+
+        # Make API request with params
+        response = self._client._make_request("GET", endpoint, params=params)
+
+        return response

usaspending/queries/subawards_search.py

@@ -0,0 +1,196 @@
+"""Subawards search query builder for USASpending data."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, TYPE_CHECKING, Optional
+
+from ..exceptions import ValidationError
+from ..models.subaward import SubAward
+from .awards_search import AwardsSearch
+from ..logging_config import USASpendingLogger
+from ..models.award_types import get_category_for_code
+
+if TYPE_CHECKING:
+    from ..client import USASpendingClient
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class SubAwardsSearch(AwardsSearch):
+    """
+    Builds and executes a subawards search query, allowing for complex
+    filtering on subaward data. This class extends AwardsSearch to reuse
+    filter logic while specializing for subawards.
+    """
+
+    def __init__(self, client: "USASpendingClient"):
+        """
+        Initializes the SubAwardsSearch query builder.
+
+        Args:
+            client: The USASpending client instance.
+        """
+        super().__init__(client)
+        self._award_id: Optional[str] = None
+
+    def _clone(self) -> SubAwardsSearch:
+        """Creates an immutable copy of the query builder."""
+        clone = SubAwardsSearch(self._client)
+        clone._filter_objects = self._filter_objects.copy()
+        clone._page_size = self._page_size
+        clone._total_limit = self._total_limit
+        clone._max_pages = self._max_pages
+        clone._order_by = self._order_by
+        clone._order_direction = self._order_direction
+        clone._award_id = self._award_id
+        return clone
+
+    def _build_payload(self, page: int) -> Dict[str, Any]:
+        """
+        Constructs the final API request payload for subawards.
+
+        Overrides parent to always include subawards=true and spending_level=subawards.
+        """
+        payload = super()._build_payload(page)
+
+        # Always search for subawards
+        payload["subawards"] = True
+        payload["spending_level"] = "subawards"
+
+        # If filtering by specific award, add to filters
+        if self._award_id:
+            if "filters" not in payload:
+                payload["filters"] = {}
+            payload["filters"]["award_unique_id"] = self._award_id
+
+        return payload
+
+    def _transform_result(self, result: Dict[str, Any]) -> SubAward:
+        """Transforms a single API result item into a SubAward model."""
+        return SubAward(result, self._client)
+
+    def _get_fields(self) -> list[str]:
+        """
+        Determines the list of fields to request based on award type filters.
+
+        Returns different field sets depending on the award type codes:
+        - Contracts: Contract subaward fields
+        - Grants/Assistance: Grant subaward fields
+        """
+        # Get award type codes from filters
+        award_types = self._get_award_type_codes()
+
+        # Determine if we're dealing with contracts or grants
+        is_contract = False
+        is_grant = False
+
+        # Check each award type code to determine categories
+        for award_type in award_types:
+            category = get_category_for_code(award_type)
+            if category == "contracts":
+                is_contract = True
+            elif category == "grants":
+                is_grant = True
+
+        # Return appropriate field set
+        if is_contract and not is_grant:
+            return SubAward.CONTRACT_SUBAWARD_FIELDS.copy()
+        elif is_grant and not is_contract:
+            return SubAward.GRANT_SUBAWARD_FIELDS.copy()
+        else:
+            # If both or neither, return union of both field sets
+            fields = set(SubAward.CONTRACT_SUBAWARD_FIELDS)
+            fields.update(SubAward.GRANT_SUBAWARD_FIELDS)
+            return list(fields)
+
+    def count(self) -> int:
+        """
+        Get the total count of subawards.
+
+        If filtering by a specific award, uses the efficient count endpoint.
+        Otherwise falls back to parent implementation.
+        """
+        logger.debug(f"{self.__class__.__name__}.count() called")
+
+        # If we have an award_id filter, use the efficient count endpoint
+        if self._award_id:
+            endpoint = f"/awards/count/subaward/{self._award_id}/"
+
+            from ..logging_config import log_query_execution
+
+            log_query_execution(logger, "SubAwardsSearch.count", [], endpoint)
+
+            # Send the request to the count endpoint
+            response = self._client._make_request("GET", endpoint)
+
+            # Extract count from response
+            total = response.get("subawards", 0)
+
+            logger.info(
+                f"{self.__class__.__name__}.count() = {total} subawards for award {self._award_id}"
+            )
+            return total
+
+        # Fall back to parent implementation for general subaward counting
+        # This is inefficient, but it's the only way to get the count
+        # without a dedicated endpoint for subaward searches.
+        # The parent's count() method will iterate through all pages.
+        # return super().count()
+        # For now, let's just iterate and count
+        count = 0
+        for _ in self:
+            count += 1
+        return count
+
+    def count_awards_by_type(self) -> Dict[str, int]:
+        """
+        Override parent method to use subawards-specific count endpoint.
+
+        Returns:
+            A dictionary mapping award type categories to their subaward counts.
+        """
+        endpoint = "/search/spending_by_award_count/"
+        final_filters = self._aggregate_filters()
+
+        payload = {
+            "filters": final_filters,
+            "subawards": True,  # Always count subawards
+            "spending_level": "subawards",
+        }
+
+        from ..logging_config import log_query_execution
+
+        log_query_execution(
+            logger,
+            "SubAwardsSearch.count_awards_by_type",
+            self._filter_objects,
+            endpoint,
+        )
+
+        # Send the request to the count endpoint
+        response = self._client._make_request("POST", endpoint, json=payload)
+
+        # Extract and return aggregations
+        return response.get("aggregations", {})
+
+    def award_id(self, award_id: str) -> SubAwardsSearch:
+        """
+        Filter subawards for a specific prime award.
+
+        Args:
+            award_id: The unique generated award identifier.
+
+        Returns:
+            A new SubAwardsSearch instance with the award filter applied.
+
+        Example:
+            >>> subawards = client.subawards.award_id("CONT_AWD_123...")
+            >>> for sub in subawards:
+            ...     print(f"{sub.sub_awardee_name}: ${sub.sub_award_amount:,.2f}")
+        """
+        if not award_id:
+            raise ValidationError("award_id cannot be empty")
+
+        clone = self._clone()
+        clone._award_id = str(award_id).strip()
+        return clone

usaspending/queries/transactions_search.py

@@ -0,0 +1,213 @@
+"""Transactions search query builder for USASpending data."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, TYPE_CHECKING, Iterator
+from datetime import datetime
+
+from ..exceptions import ValidationError
+from ..models.transaction import Transaction
+from .query_builder import QueryBuilder
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..client import USASpendingClient
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class TransactionsSearch(QueryBuilder["Transaction"]):
+    """
+    Builds and executes a transactions search query, allowing for filtering
+    on transaction data. This class follows a fluent interface pattern.
+    """
+
+    def __init__(self, client: "USASpendingClient"):
+        """
+        Initializes the TransactionsSearch query builder.
+
+        Args:
+            client: The USASpending client instance.
+        """
+        super().__init__(client)
+        self._award_id: str = None
+        # Client-side filters (not supported by API)
+        self._client_filters = {}
+
+    @property
+    def _endpoint(self) -> str:
+        """The API endpoint for this query."""
+        return "/transactions/"
+
+    def _clone(self) -> TransactionsSearch:
+        """Creates an immutable copy of the query builder."""
+        clone = super()._clone()
+        clone._filter_objects = self._filter_objects.copy()
+        clone._award_id = self._award_id
+        clone._client_filters = self._client_filters.copy()
+        return clone
+
+    def _build_payload(self, page: int) -> Dict[str, Any]:
+        """Constructs the final API request payload from the filter objects."""
+
+        if not self._award_id:
+            raise ValidationError(
+                "An award_id is required. Use the .award_id() method."
+            )
+
+        payload = {
+            "award_id": self._award_id,
+            "limit": self._get_effective_page_size(),
+            "page": page,
+        }
+
+        # Add any additional filters if they exist
+        final_filters = self._aggregate_filters()
+        if final_filters:
+            payload.update(final_filters)
+
+        return payload
+
+    def _transform_result(self, result: Dict[str, Any]) -> Transaction:
+        """Transforms a single API result item into a Transaction model."""
+        return Transaction(result)
+
+    def count(self) -> int:
+        """Counts the number of transactions per a given award id."""
+        logger.debug(f"{self.__class__.__name__}.count() called")
+
+        # If we have client-side filters, we need to fetch all results and count
+        if self._client_filters:
+            logger.debug(
+                "Client-side filters present, counting by iterating all results"
+            )
+            count = 0
+            for _ in self:
+                count += 1
+            return count
+
+        # No client-side filters, use the efficient API count endpoint
+        endpoint = f"/awards/count/transaction/{self._award_id}/"
+
+        from ..logging_config import log_query_execution
+
+        log_query_execution(logger, "TransactionsSearch.count", [], endpoint)
+
+        # Send the request to the count endpoint
+        response = self._client._make_request("GET", endpoint)
+
+        # Extract count from the appropriate category
+        total = response.get("transactions", 0)
+
+        logger.info(
+            f"{self.__class__.__name__}.count() = {total} transactions for award {self._award_id}"
+        )
+        return total
+
+    # ==========================================================================
+    # Filter Methods
+    # ==========================================================================
+
+    def award_id(self, award_id: str) -> TransactionsSearch:
+        """
+        Filter transactions for a specific award.
+
+        Args:
+            award_id: The unique award identifier.
+
+        Returns:
+            A new `TransactionsSearch` instance with the award filter applied.
+        """
+        if not award_id:
+            raise ValidationError("award_id cannot be empty")
+
+        clone = self._clone()
+        clone._award_id = str(award_id).strip()
+        return clone
+
+    def since(self, date: str) -> "TransactionsSearch":
+        """
+        Filter transactions to those on or after the specified date.
+
+        Note: This filter is applied client-side as the API endpoint
+        doesn't support date filtering for transactions.
+
+        Args:
+            date: Date string in YYYY-MM-DD format
+
+        Returns:
+            A new TransactionsSearch instance with the date filter applied
+
+        Example:
+            >>> transactions = award.transactions.since("2024-01-01").all()
+        """
+        # Validate date format
+        try:
+            datetime.strptime(date, "%Y-%m-%d")
+        except ValueError:
+            raise ValidationError("Date must be in YYYY-MM-DD format")
+
+        clone = self._clone()
+        clone._client_filters["since_date"] = date
+        return clone
+
+    def until(self, date: str) -> "TransactionsSearch":
+        """
+        Filter transactions to those on or before the specified date.
+
+        Note: This filter is applied client-side as the API endpoint
+        doesn't support date filtering for transactions.
+
+        Args:
+            date: Date string in YYYY-MM-DD format
+
+        Returns:
+            A new TransactionsSearch instance with the date filter applied
+
+        Example:
+            >>> transactions = award.transactions.until("2024-12-31").all()
+        """
+        # Validate date format
+        try:
+            datetime.strptime(date, "%Y-%m-%d")
+        except ValueError:
+            raise ValidationError("Date must be in YYYY-MM-DD format")
+
+        clone = self._clone()
+        clone._client_filters["until_date"] = date
+        return clone
+
+    def _apply_client_filters(self, transaction: Transaction) -> bool:
+        """
+        Apply client-side filters to a transaction.
+
+        Args:
+            transaction: The transaction to filter
+
+        Returns:
+            True if transaction passes all filters, False otherwise
+        """
+        # Apply date filters
+        if "since_date" in self._client_filters:
+            since_date = datetime.strptime(
+                self._client_filters["since_date"], "%Y-%m-%d"
+            ).date()
+            if transaction.action_date and transaction.action_date.date() < since_date:
+                return False
+
+        if "until_date" in self._client_filters:
+            until_date = datetime.strptime(
+                self._client_filters["until_date"], "%Y-%m-%d"
+            ).date()
+            if transaction.action_date and transaction.action_date.date() > until_date:
+                return False
+
+        return True
+
+    def __iter__(self) -> Iterator[Transaction]:
+        """
+        Override iteration to apply client-side filters.
+        """
+        for transaction in super().__iter__():
+            if self._apply_client_filters(transaction):
+                yield transaction

usaspending/resources/__init__.py

@@ -0,0 +1,17 @@
+from .award_resource import AwardResource
+from .agency_resource import AgencyResource
+from .recipients_resource import RecipientsResource
+from .transactions_resource import TransactionsResource
+from .spending_resource import SpendingResource
+from .funding_resource import FundingResource
+from .download_resource import DownloadResource
+
+__all__ = [
+    "AwardResource",
+    "AgencyResource",
+    "RecipientsResource",
+    "TransactionsResource",
+    "SpendingResource",
+    "FundingResource",
+    "DownloadResource",
+]