usaspending-orm 0.6.0__py3-none-any.whl

usaspending/queries/agencies_search.py

@@ -0,0 +1,196 @@
+"""Agencies search query implementation for funding agency/office autocomplete."""
+
+from __future__ import annotations
+from typing import Dict, Any, TYPE_CHECKING
+from ..exceptions import ValidationError
+from ..models.agency import Agency
+from ..models.subtier_agency import SubTierAgency
+from .query_builder import QueryBuilder
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..client import USASpendingClient
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class AgenciesSearch(QueryBuilder[Agency]):
+    """Search for funding agencies and offices by name using autocomplete.
+
+    This query builder uses the /v2/autocomplete/funding_agency_office/ endpoint
+    to search for agencies by name. Results can be filtered by type (toptier,
+    subtier, or office).
+    """
+
+    def __init__(self, client: USASpendingClient):
+        """Initialize AgenciesSearch with client."""
+        super().__init__(client)
+        self._search_text = ""
+        self._limit = 100  # Default limit
+        self._result_type = None  # Filter: None, 'toptier', 'subtier', 'office'
+
+    @property
+    def _endpoint(self) -> str:
+        """API endpoint for agency autocomplete."""
+        raise NotImplementedError("Subclasses must implement _endpoint")
+
+    def _build_payload(self, page: int) -> Dict[str, Any]:
+        """Build request payload."""
+        if not self._search_text:
+            raise ValidationError(
+                "search_text is required. Use search_text() method."
+            )
+
+        return {"search_text": self._search_text, "limit": self._limit}
+
+    def _execute_query(self, page: int) -> Dict[str, Any]:
+        """Execute the autocomplete query.
+
+        This endpoint doesn't support pagination, so only return results on page 1.
+        """
+        # No pagination - return empty after first page
+        if page > 1:
+            return {"results": [], "page_metadata": {"hasNext": False}}
+
+        payload = self._build_payload(1)
+        response = self._client._make_request("POST", self._endpoint, json=payload)
+
+        # The response has results as an object with three arrays
+        # We need to flatten this into a single results array for QueryBuilder
+        results_obj = response.get("results", {})
+        flat_results = []
+
+        # Add results based on filter type
+        if self._result_type is None:
+            # No filter - return all types
+            # Add toptier agencies
+            for agency in results_obj.get("toptier_agency", []):
+                flat_results.append({"type": "toptier", "data": agency})
+
+            # Add subtier agencies
+            for subtier in results_obj.get("subtier_agency", []):
+                flat_results.append({"type": "subtier", "data": subtier})
+
+            # Add offices
+            for office in results_obj.get("office", []):
+                flat_results.append({"type": "office", "data": office})
+
+        elif self._result_type == "toptier":
+            for agency in results_obj.get("toptier_agency", []):
+                flat_results.append({"type": "toptier", "data": agency})
+
+        elif self._result_type == "subtier":
+            for subtier in results_obj.get("subtier_agency", []):
+                flat_results.append({"type": "subtier", "data": subtier})
+
+        elif self._result_type == "office":
+            for office in results_obj.get("office", []):
+                flat_results.append({"type": "office", "data": office})
+
+        # Return flattened structure for QueryBuilder
+        return {
+            "results": flat_results,
+            "page_metadata": {"hasNext": False},
+            "messages": response.get("messages", []),
+        }
+
+    def _transform_result(self, result: Dict[str, Any]) -> Agency:
+        """Transform result into Agency object based on type."""
+        if not result:
+            return None
+
+        result_type = result.get("type")
+        data = result.get("data", {})
+
+        if result_type == "toptier":
+            # Direct toptier agency result
+            agency_data = {
+                "code": data.get("code"),
+                "toptier_code": data.get("code"),
+                "name": data.get("name"),
+                "abbreviation": data.get("abbreviation"),
+            }
+            return Agency(agency_data, self._client)
+
+        elif result_type == "subtier":
+            # Include subtier data
+            return SubTierAgency(data, self._client)
+
+        elif result_type == "office":
+            return SubTierAgency(data, self._client)
+
+        return None
+
+    def count(self) -> int:
+        """Get total count of matching agencies/offices.
+
+        Returns:
+            Total number of matching results
+        """
+        logger.debug(f"{self.__class__.__name__}.count() called")
+
+        if not self._search_text:
+            raise ValidationError(
+                "search_text is required. Use search_text() method."
+            )
+
+        # Execute query to get all results
+        response = self._execute_query(1)
+        results = response.get("results", [])
+
+        count = len(results)
+
+        logger.info(
+            f"{self.__class__.__name__}.count() = {count} results "
+            f"for search text '{self._search_text}'"
+        )
+        return count
+
+    def search_text(self, search_text: str) -> AgenciesSearch:
+        """Set the search text for the query.
+
+        Args:
+            search_text: Text to search for in agency names
+
+        Returns:
+            New AgenciesSearch instance with search text set
+        """
+        clone = self._clone()
+        clone._search_text = search_text
+        return clone
+
+    def toptier(self) -> AgenciesSearch:
+        """Filter to only return toptier agency matches.
+
+        Returns:
+            New AgenciesSearch instance filtered to toptier agencies
+        """
+        clone = self._clone()
+        clone._result_type = "toptier"
+        return clone
+
+    def subtier(self) -> AgenciesSearch:
+        """Filter to only return subtier agency matches.
+
+        Returns:
+            New AgenciesSearch instance filtered to subtier agencies
+        """
+        clone = self._clone()
+        clone._result_type = "subtier"
+        return clone
+
+    def office(self) -> AgenciesSearch:
+        """Filter to only return office matches.
+
+        Returns:
+            New AgenciesSearch instance filtered to offices
+        """
+        clone = self._clone()
+        clone._result_type = "office"
+        return clone
+
+    def _clone(self) -> AgenciesSearch:
+        """Create immutable copy for chaining."""
+        clone = super()._clone()
+        clone._search_text = self._search_text
+        return clone

usaspending/queries/agency_award_summary.py

@@ -0,0 +1,134 @@
+"""Agency award summary query implementation for retrieving award aggregations."""
+
+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 AgencyAwardSummary(SingleResourceBase):
+    """Retrieve agency award summary data from the USAspending API.
+
+    This query class handles fetching aggregated award information including
+    transaction counts and obligations filtered by fiscal year, agency type,
+    and award type codes.
+    """
+
+    def __init__(self, client: USASpendingClient):
+        """Initialize AgencyAwardSummary with client.
+
+        Args:
+            client: USASpendingClient client instance
+        """
+        super().__init__(client)
+        logger.debug("AgencyAwardSummary initialized with client: %s", client)
+
+    @property
+    def _endpoint(self) -> str:
+        """Base endpoint for agency award summary retrieval."""
+        return "/agency/"
+
+    def _construct_endpoint(self, resource_id: str) -> str:
+        """Construct the full endpoint URL for agency award summary.
+
+        Args:
+            resource_id: The toptier_code for the agency
+
+        Returns:
+            Full endpoint path including /awards/
+        """
+        return f"{self._endpoint}{resource_id}/awards/"
+
+    def find_by_id(self, toptier_code: str) -> Dict[str, Any]:
+        """Not used for award summary - use get_awards_summary instead.
+
+        Raises:
+            NotImplementedError: This method should not be used directly
+        """
+        raise NotImplementedError(
+            "Use get_awards_summary() method instead for award summary data"
+        )
+
+    def get_awards_summary(
+        self,
+        toptier_code: str,
+        fiscal_year: Optional[int] = None,
+        agency_type: str = "awarding",
+        award_type_codes: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Retrieve agency award summary with optional filters.
+
+        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
+
+        Returns:
+            Dictionary containing:
+                - toptier_code: Agency toptier code
+                - fiscal_year: Fiscal year of data
+                - latest_action_date: Latest transaction date
+                - transaction_count: Number of transactions
+                - obligations: Total obligations amount
+                - messages: Any API messages
+
+        Raises:
+            ValidationError: If toptier_code is invalid or agency_type is 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'"
+            )
+
+        logger.debug(
+            "Fetching award summary for toptier_code: %s, fiscal_year: %s, "
+            "agency_type: %s, award_type_codes: %s",
+            toptier_code,
+            fiscal_year,
+            agency_type,
+            award_type_codes,
+        )
+
+        # Build params
+        params = {"agency_type": agency_type}
+
+        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/agency_query.py

@@ -0,0 +1,102 @@
+"""Agency query implementation for retrieving single agency details."""
+
+from typing import TYPE_CHECKING, Optional, Dict, Any
+from .single_resource_base import SingleResourceBase
+from ..exceptions import ValidationError
+from ..client import USASpendingClient
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..models.agency import Agency
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class AgencyQuery(SingleResourceBase):
+    """Retrieve a single agency from the USAspending API.
+
+    This query class handles fetching agency overview information for a
+    specific fiscal year using the agency's toptier code.
+    """
+
+    def __init__(self, client: USASpendingClient):
+        """Initialize AgencyQuery with client.
+
+        Args:
+            client: USASpendingClient client instance
+        """
+        super().__init__(client)
+        logger.debug("AgencyQuery initialized with client: %s", client)
+
+    @property
+    def _endpoint(self) -> str:
+        """Base endpoint for single agency retrieval."""
+        return "/agency/"
+
+    def find_by_id(
+        self, toptier_code: str, fiscal_year: Optional[int] = None
+    ) -> "Agency":
+        """Retrieve agency by toptier code and optional 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
+        """
+        if not toptier_code:
+            raise ValidationError("toptier_code is required")
+
+        # Validate toptier_code format (3-4 digit numeric string)
+        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"
+            )
+
+        logger.debug(
+            "Fetching agency with toptier_code: %s, fiscal_year: %s",
+            toptier_code,
+            fiscal_year,
+        )
+
+        # Make API request with optional fiscal_year parameter
+        response = self._get_resource_with_params(toptier_code, fiscal_year)
+
+        # Create model instance
+        from ..models.agency import Agency
+
+        return Agency(response, client=self._client)
+
+    def _get_resource_with_params(
+        self, toptier_code: str, fiscal_year: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """Retrieve agency with optional query parameters.
+
+        Args:
+            toptier_code: The agency's toptier code
+            fiscal_year: Optional fiscal year parameter
+
+        Returns:
+            API response dictionary
+        """
+        # Construct endpoint
+        endpoint = self._construct_endpoint(toptier_code)
+
+        # Build params dict if fiscal_year provided
+        params = {}
+        if fiscal_year is not None:
+            params["fiscal_year"] = fiscal_year
+
+        # Make API request with params
+        response = self._client._make_request(
+            "GET", endpoint, params=params if params else None
+        )
+
+        return response

usaspending/queries/award_query.py

@@ -0,0 +1,40 @@
+from typing import TYPE_CHECKING
+from .single_resource_base import SingleResourceBase
+from ..exceptions import ValidationError
+from ..client import USASpendingClient
+from ..logging_config import USASpendingLogger
+
+if TYPE_CHECKING:
+    from ..models.award import Award
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class AwardQuery(SingleResourceBase):
+    """Retrieve a single-award from the USAspending API."""
+
+    def __init__(self, client: USASpendingClient):
+        super().__init__(client)
+        logger.debug("AwardQuery initialized with client: %s", client)
+
+    @property
+    def _endpoint(self) -> str:
+        """Base endpoint for single award retrieval."""
+        return "/awards/"
+
+    def find_by_id(self, award_id: str) -> "Award":
+        """Filter by unique award identifier."""
+        return self.find_by_generated_id(award_id)
+
+    def find_by_generated_id(self, award_id: str) -> "Award":
+        """Filter by USASpending's internally generated unique award identifier."""
+        if not award_id:
+            raise ValidationError("award_id is required")
+
+        # Make API request
+        response = self._get_resource(award_id)
+
+        # Create model instance using factory
+        from ..models.award_factory import create_award
+
+        return create_award(response, client=self._client)

usaspending/queries/awarding_agencies_search.py

@@ -0,0 +1,16 @@
+"""Agencies search query implementation for awarding agency/office autocomplete."""
+
+from __future__ import annotations
+from .agencies_search import AgenciesSearch
+from ..logging_config import USASpendingLogger
+
+logger = USASpendingLogger.get_logger(__name__)
+
+
+class AwardingAgenciesSearch(AgenciesSearch):
+    """Search for awarding agencies and offices by name."""
+
+    @property
+    def _endpoint(self) -> str:
+        """API endpoint for agency autocomplete."""
+        return "/autocomplete/awarding_agency_office/"