usaspending-orm 0.6.0__py3-none-any.whl

usaspending/models/award_factory.py

@@ -0,0 +1,72 @@
+"""Factory for creating appropriate Award subclass instances."""
+
+from __future__ import annotations
+from typing import Dict, Any, Optional, TYPE_CHECKING
+
+from .award_types import get_category_for_code
+from ..exceptions import ValidationError
+
+if TYPE_CHECKING:
+    from .award import Award
+    from ..client import USASpendingClient
+
+
+def create_award(
+    data_or_id: Dict[str, Any] | str, client: Optional[USASpendingClient] = None
+) -> Award:
+    """
+    Factory function to create the appropriate Award subclass based on the award data.
+
+    Args:
+        data_or_id: Award data dictionary or unique award ID string
+        client: Optional USASpendingClient instance
+
+    Returns:
+        Appropriate Award subclass instance (Contract, Grant, IDV, Loan, or base Award)
+    """
+    # Import here to avoid circular imports
+    from .award import Award
+    from .contract import Contract
+    from .grant import Grant
+    from .idv import IDV
+    from .loan import Loan
+
+    # If it's just an ID, create base Award and let lazy loading determine type
+    if isinstance(data_or_id, str):
+        return Award(data_or_id, client)
+
+    if not isinstance(data_or_id, dict):
+        raise ValidationError("Award factory expects a dict or an award_id string")
+
+    # Determine award type from data
+    category = data_or_id.get("category", "").lower()
+    award_type = data_or_id.get("type", "")
+
+    award_class_map = {
+        "contract": Contract,
+        "idv": IDV,
+        "grant": Grant,
+        "loan": Loan,
+    }
+
+    # Determine class from category first (most reliable)
+    award_class = award_class_map.get(category)
+
+    # Fallback to type codes if category doesn't match
+    if not award_class and award_type:
+        code_category = get_category_for_code(award_type)
+        if code_category:
+            # Map config category names to award class names
+            category_map = {
+                "contracts": "contract",
+                "idvs": "idv",
+                "grants": "grant",
+                "loans": "loan",
+            }
+            mapped_category = category_map.get(code_category)
+            if mapped_category:
+                award_class = award_class_map.get(mapped_category)
+
+    # Use the determined class or default to the base Award class
+    cls = award_class or Award
+    return cls(data_or_id, client)

usaspending/models/award_types.py

@@ -0,0 +1,114 @@
+"""Award type constants and categorizations for USASpending data.
+
+This module contains all award type codes, groupings, and descriptions
+as defined by the USASpending.gov API.
+"""
+
+from __future__ import annotations
+
+# Dictionary of award type groups with their codes and descriptions
+# This is the single source of truth for award type categorization
+AWARD_TYPE_GROUPS = {
+    "contracts": {
+        "A": "BPA Call",
+        "B": "Purchase Order",
+        "C": "Delivery Order",
+        "D": "Definitive Contract",
+    },
+    "loans": {"07": "Direct Loan", "08": "Guaranteed/Insured Loan"},
+    "idvs": {
+        "IDV_A": "GWAC Government Wide Acquisition Contract",
+        "IDV_B": "IDC Multi-Agency Contract, Other Indefinite Delivery Contract",
+        "IDV_B_A": "IDC Indefinite Delivery Contract / Requirements",
+        "IDV_B_B": "IDC Indefinite Delivery Contract / Indefinite Quantity",
+        "IDV_B_C": "IDC Indefinite Delivery Contract / Definite Quantity",
+        "IDV_C": "FSS Federal Supply Schedule",
+        "IDV_D": "BOA Basic Ordering Agreement",
+        "IDV_E": "BPA Blanket Purchase Agreement",
+    },
+    "grants": {
+        "02": "Block Grant",
+        "03": "Formula Grant",
+        "04": "Project Grant",
+        "05": "Cooperative Agreement",
+    },
+    "direct_payments": {
+        "06": "Direct Payment for Specified Use",
+        "10": "Direct Payment with Unrestricted Use",
+    },
+    "other_assistance": {
+        "09": "Insurance",
+        "11": "Other Financial Assistance",
+        "-1": "Not Specified",
+    },
+}
+
+# Create a flattened map for easy description lookups
+AWARD_TYPE_DESCRIPTIONS = {
+    code: description
+    for group in AWARD_TYPE_GROUPS.values()
+    for code, description in group.items()
+}
+
+# Regenerate frozensets from this single source of truth
+CONTRACT_CODES = frozenset(AWARD_TYPE_GROUPS["contracts"].keys())
+IDV_CODES = frozenset(AWARD_TYPE_GROUPS["idvs"].keys())
+LOAN_CODES = frozenset(AWARD_TYPE_GROUPS["loans"].keys())
+GRANT_CODES = frozenset(AWARD_TYPE_GROUPS["grants"].keys())
+DIRECT_PAYMENT_CODES = frozenset(AWARD_TYPE_GROUPS["direct_payments"].keys())
+OTHER_CODES = frozenset(AWARD_TYPE_GROUPS["other_assistance"].keys())
+
+# All valid award type codes
+ALL_AWARD_CODES = (
+    CONTRACT_CODES
+    | IDV_CODES
+    | LOAN_CODES
+    | GRANT_CODES
+    | DIRECT_PAYMENT_CODES
+    | OTHER_CODES
+)
+
+
+def get_category_for_code(code: str) -> str:
+    """Get the category name for a given award type code.
+
+    Args:
+        code: Award type code (e.g., "A", "02", "IDV_A")
+
+    Returns:
+        Category name (e.g., "contracts", "grants", "idvs") or empty string if not found
+    """
+    if not isinstance(code, str):
+        return ""
+    for category_name, codes in AWARD_TYPE_GROUPS.items():
+        if code in codes:
+            return category_name
+    return ""
+
+
+def is_valid_award_type(code: str) -> bool:
+    """Check if a code is a valid award type.
+
+    Args:
+        code: Award type code to validate
+
+    Returns:
+        True if the code is valid, False otherwise
+    """
+    if not isinstance(code, str):
+        return False
+    return code in ALL_AWARD_CODES
+
+
+def get_description(code: str) -> str:
+    """Get the description for a given award type code.
+
+    Args:
+        code: Award type code
+
+    Returns:
+        Description string or empty string if not found
+    """
+    if not isinstance(code, str):
+        return ""
+    return AWARD_TYPE_DESCRIPTIONS.get(code, "")

usaspending/models/base_model.py

@@ -0,0 +1,214 @@
+# usaspending/models/base_model.py
+from typing import Optional, Dict, Any, List, Set, TYPE_CHECKING
+from weakref import ref
+
+if TYPE_CHECKING:
+    from ..client import USASpendingClient
+
+from ..exceptions import ValidationError, DetachedInstanceError
+
+
+class BaseModel:
+    """Base class for all models with fundamental behaviors."""
+
+    def __init__(self, data: Dict[str, Any]):
+        self._data = data or {}
+
+    @staticmethod
+    def validate_init_data(
+        data_or_id: Any,
+        model_name: str,
+        id_field: Optional[str] = None,
+        allow_string_id: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Validate and normalize initialization data for models.
+
+        Args:
+            data_or_id: Input data (dict, string, or other type)
+            model_name: Name of the model for error messages
+            id_field: Field name for ID when string is provided
+            allow_string_id: Whether to accept string as ID
+
+        Returns:
+            Normalized dictionary of data
+
+        Raises:
+            ValidationError: If data is invalid
+        """
+        if data_or_id is None:
+            raise ValidationError(
+                f"{model_name} data cannot be None. This may indicate an API or caching issue."
+            )
+
+        if isinstance(data_or_id, dict):
+            # Return a copy to avoid modifying the original
+            return data_or_id.copy()
+
+        if isinstance(data_or_id, str):
+            if not allow_string_id:
+                raise ValidationError(f"{model_name} expects dict, got str")
+
+            if not id_field:
+                raise ValidationError(f"{model_name} expects dict, got str")
+
+            if not data_or_id.strip():
+                raise ValidationError(f"{model_name} ID cannot be empty or whitespace")
+
+            return {id_field: data_or_id}
+
+        # Invalid type
+        type_name = type(data_or_id).__name__
+        if allow_string_id:
+            raise ValidationError(
+                f"{model_name} expects dict or string, got {type_name}"
+            )
+        else:
+            raise ValidationError(f"{model_name} expects dict, got {type_name}")
+
+    @property
+    def raw(self) -> Dict[str, Any]:
+        """Get raw data dictionary."""
+        return self._data
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return self._data
+
+    def get_value(self, keys: List[str], default: Any = None) -> Any:
+        """Return the first non-None value from the given keys."""
+        if not isinstance(keys, list):
+            keys = [keys]
+
+        if not isinstance(self._data, dict):
+            raise TypeError("Empty object data")
+        for key in keys:
+            if key in self._data:
+                value = self._data[key]
+                if value is not None:  # Check for non-None instead of truthiness
+                    return value
+        return default
+
+
+class ClientAwareModel(BaseModel):
+    """Base class for all models that need API client access."""
+
+    def __init__(self, data: Dict[str, Any], client: "USASpendingClient"):
+        super().__init__(data)
+        self._client_ref = ref(client)  # Weak reference prevents circular refs
+
+    @property
+    def _client(self) -> "USASpendingClient":
+        """Get client instance if still alive and usable.
+
+        Returns:
+            USASpendingClient: The client instance.
+
+        Raises:
+            DetachedInstanceError: If the client has been closed or garbage collected.
+        """
+        client = self._client_ref() if self._client_ref else None
+
+        if client is None:
+            raise DetachedInstanceError(
+                f"Cannot access {self.__class__.__name__} properties: "
+                "the USASpendingClient has been garbage collected. "
+                "Ensure the client remains in scope, or access all needed data "
+                "within the 'with USASpendingClient()' context block."
+            )
+
+        if hasattr(client, "_closed") and client._closed:
+            raise DetachedInstanceError(
+                f"Cannot access {self.__class__.__name__} properties: "
+                "the USASpendingClient session is closed. "
+                "Access all lazy-loaded properties within the 'with' block, "
+                "or use explicit cleanup (client.close()) only after you're done with the models."
+            )
+
+        return client
+
+    def reattach(
+        self,
+        client: "USASpendingClient",
+        recursive: bool = False,
+        _visited: Optional[Set[int]] = None,
+    ) -> None:
+        """Reattach this model to a new client session.
+
+        This method updates the model's client reference to point to a new
+        USASpendingClient, allowing you to use objects created in one session
+        within a different session context.
+
+        Args:
+            client: The new USASpendingClient to attach to.
+            recursive: If True, recursively reattach nested LazyRecord objects
+                      (e.g., award.recipient, award.awarding_agency). Default False.
+            _visited: Internal parameter for cycle detection. Do not pass manually.
+
+        Example:
+            >>> # Create objects in one session
+            >>> with USASpendingClient() as client:
+            ...     award = client.awards.find_by_award_id("123")
+            ...     # Session closes here
+            ...
+            >>> # Later, reattach to a new session
+            >>> with USASpendingClient() as new_client:
+            ...     award.reattach(new_client)
+            ...     print(award.subaward_count)  # Now works!
+            ...
+            >>> # Recursive reattach for nested objects
+            >>> with USASpendingClient() as new_client:
+            ...     award.reattach(new_client, recursive=True)
+            ...     # Now award.recipient and award.awarding_agency also reattached
+            ...     print(award.recipient.name)
+
+        Note:
+            QueryBuilder properties (like award.transactions) are not affected
+            by reattach. They create new query builders when accessed, which
+            automatically use the reattached client.
+
+        Raises:
+            DetachedInstanceError: If the provided client is closed.
+        """
+        # Validate that the new client is usable
+        if hasattr(client, "_closed") and client._closed:
+            raise DetachedInstanceError(
+                f"Cannot reattach {self.__class__.__name__} to a closed client. "
+                "Ensure the client is active (within a 'with' block or before close())."
+            )
+
+        # Update this model's client reference
+        self._client_ref = ref(client)
+
+        # Handle recursive reattachment if requested
+        if recursive:
+            # Import here to avoid circular dependency
+            from .lazy_record import LazyRecord
+
+            # Initialize visited set for cycle detection
+            if _visited is None:
+                _visited = set()
+
+            # Prevent infinite recursion on circular references
+            obj_id = id(self)
+            if obj_id in _visited:
+                return
+            _visited.add(obj_id)
+
+            # Find and reattach all LazyRecord properties
+            for attr_name in dir(self):
+                # Skip private attributes and methods
+                if attr_name.startswith("_"):
+                    continue
+
+                try:
+                    attr = getattr(self, attr_name)
+
+                    # Recursively reattach LazyRecord instances
+                    if isinstance(attr, LazyRecord):
+                        attr.reattach(client, recursive=True, _visited=_visited)
+
+                except (AttributeError, Exception):
+                    # Skip properties that raise errors during access
+                    # (e.g., properties that require API calls, methods, etc.)
+                    pass

usaspending/models/contract.py

@@ -0,0 +1,147 @@
+"""Contract award model for USASpending data."""
+
+from __future__ import annotations
+from typing import Dict, Any, Optional, TYPE_CHECKING
+from functools import cached_property
+from decimal import Decimal
+
+from .award import Award
+from ..utils.formatter import to_decimal
+
+if TYPE_CHECKING:
+    from ..queries.subawards_search import SubAwardsSearch
+
+
+class Contract(Award):
+    """Contract award type including definitive contracts and purchase orders."""
+
+    TYPE_FIELDS = [
+        "piid",
+        "base_exercised_options",
+        "base_and_all_options",
+        "contract_award_type",
+        "naics_code",
+        "naics_description",
+        "naics_hierarchy",
+        "psc_code",
+        "psc_description",
+        "psc_hierarchy",
+        "latest_transaction_contract_data",
+    ]
+
+    SEARCH_FIELDS = Award.SEARCH_FIELDS + [
+        "Start Date",
+        "End Date",
+        "Award Amount",
+        "Total Outlays",
+        "Contract Award Type",
+        "NAICS",
+        "PSC",
+    ]
+
+    @property
+    def piid(self) -> Optional[str]:
+        """
+        Procurement Instrument Identifier - A unique identifier assigned to a federal
+        contract, purchase order, basic ordering agreement, basic agreement, and
+        blanket purchase agreement. It is used to track the contract, and any
+        modifications or transactions related to it. After October 2017, it is
+        between 13 and 17 digits, both letters and numbers.
+        """
+        return self._lazy_get("piid")
+
+    @property
+    def base_exercised_options(self) -> Optional[Decimal]:
+        """The sum of the base_exercised_options_val from associated transactions"""
+        return to_decimal(self._lazy_get("base_exercised_options", default=None))
+
+    @property
+    def base_and_all_options(self) -> Optional[Decimal]:
+        """The sum of the base_and_all_options_value from associated transactions"""
+        return to_decimal(self._lazy_get("base_and_all_options", default=None))
+
+    @property
+    def contract_award_type(self) -> Optional[str]:
+        """Contract award type description."""
+        return self.type_description
+
+    @property
+    def naics_code(self) -> Optional[str]:
+        """NAICS industry classification code."""
+        naics_data = self._lazy_get("naics", "NAICS")
+        if isinstance(naics_data, dict):
+            return naics_data.get("code")
+        if self.naics_hierarchy and isinstance(
+            self.naics_hierarchy.get("base_code"), dict
+        ):
+            return self.naics_hierarchy["base_code"].get("code")
+        if self.latest_transaction_contract_data:
+            return self.latest_transaction_contract_data.get("naics")
+        return None
+
+    @property
+    def naics_description(self) -> Optional[str]:
+        """NAICS industry classification description."""
+        naics_data = self._lazy_get("naics", "NAICS")
+        if isinstance(naics_data, dict):
+            return naics_data.get("description")
+        if self.naics_hierarchy and isinstance(
+            self.naics_hierarchy.get("base_code"), dict
+        ):
+            return self.naics_hierarchy["base_code"].get("description")
+        if self.latest_transaction_contract_data:
+            return self.latest_transaction_contract_data.get("naics_description")
+        return None
+
+    @property
+    def psc_code(self) -> Optional[str]:
+        """Product/Service Code (PSC) for contracts."""
+        psc_data = self._lazy_get("psc", "PSC")
+        if isinstance(psc_data, dict):
+            return psc_data.get("code")
+        if self.psc_hierarchy and isinstance(self.psc_hierarchy.get("base_code"), dict):
+            return self.psc_hierarchy["base_code"].get("code")
+        return None
+
+    @property
+    def psc_description(self) -> Optional[str]:
+        """Product/Service Code (PSC) description."""
+        psc_data = self._lazy_get("psc", "PSC")
+        if isinstance(psc_data, dict):
+            return psc_data.get("description")
+        if self.psc_hierarchy and isinstance(self.psc_hierarchy.get("base_code"), dict):
+            return self.psc_hierarchy["base_code"].get("description")
+        return None
+
+    @cached_property
+    def psc_hierarchy(self) -> Optional[Dict[str, Any]]:
+        """Product/Service Code (PSC) hierarchy information."""
+        return self._lazy_get("psc_hierarchy")
+
+    @cached_property
+    def naics_hierarchy(self) -> Optional[Dict[str, Any]]:
+        """North American Industry Classification System (NAICS) hierarchy."""
+        return self._lazy_get("naics_hierarchy")
+
+    @cached_property
+    def latest_transaction_contract_data(self) -> Optional[Dict[str, Any]]:
+        """Latest contract transaction data with procurement-specific details."""
+        return self._lazy_get("latest_transaction_contract_data")
+
+    @property
+    def subawards(self) -> "SubAwardsSearch":
+        """Get subawards query builder for this contract award with appropriate award type filters.
+
+        Returns a SubAwardsSearch object that can be further filtered and chained.
+        Automatically applies contract award type filters.
+
+        Examples:
+            >>> contract.subawards.count()  # Get count without loading all data
+            >>> contract.subawards.limit(10).all()  # Get first 10 subawards
+            >>> list(contract.subawards)  # Iterate through all subawards
+        """
+        from .award_types import CONTRACT_CODES
+
+        return self._client.subawards.award_id(
+            self.generated_unique_award_id
+        ).award_type_codes(*CONTRACT_CODES)

usaspending/models/district_spending.py

@@ -0,0 +1,70 @@
+"""District spending model for USASpending spending by district data."""
+
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+from .spending import Spending
+
+if TYPE_CHECKING:
+    from ..client import USASpendingClient
+
+
+class DistrictSpending(Spending):
+    """Model for spending by congressional district data.
+
+    Represents spending data grouped by congressional district with
+    district-specific parsing and display logic.
+    """
+
+    def __init__(self, data: dict, client: Optional["USASpendingClient"] = None):
+        """Initialize DistrictSpending model.
+
+        Args:
+            data: Raw district spending data from API
+            client: USASpendingClient client instance
+        """
+        super().__init__(data, client)
+
+    @property
+    def district_code(self) -> Optional[str]:
+        """Congressional district code."""
+        return self.code
+
+    @property
+    def state_code(self) -> Optional[str]:
+        """Extract state code from district name if available.
+
+        District names typically follow format like 'TX-12' or 'MS-MULTIPLE DISTRICTS'.
+        """
+        if self.name:
+            # Names like "TX-12" or "MS-MULTIPLE DISTRICTS"
+            parts = self.name.split("-", 1)
+            if len(parts) >= 2:
+                return parts[0]
+        return None
+
+    @property
+    def district_number(self) -> Optional[str]:
+        """Extract district number from district name if available.
+
+        Returns the numeric part or special designation like 'MULTIPLE DISTRICTS'.
+        """
+        if self.name:
+            # Names like "TX-12" or "MS-MULTIPLE DISTRICTS"
+            parts = self.name.split("-", 1)
+            if len(parts) >= 2:
+                return parts[1]
+        return None
+
+    @property
+    def is_multiple_districts(self) -> bool:
+        """Check if this represents multiple districts in a state."""
+        district_num = self.district_number
+        return district_num is not None and "MULTIPLE" in district_num.upper()
+
+    def __repr__(self) -> str:
+        """String representation of DistrictSpending."""
+        name = self.name or "Unknown District"
+        amount = self.amount or 0
+        return f"<DistrictSpending {name}: ${amount:,.2f}>"

usaspending/models/download.py

@@ -0,0 +1,74 @@
+# src/usaspending/models/download.py
+
+from __future__ import annotations
+from typing import Optional, Literal
+from enum import Enum
+
+from ..utils.formatter import to_float, to_int
+from .base_model import BaseModel
+
+AwardType = Literal["contract", "assistance", "idv"]
+FileFormat = Literal["csv", "tsv", "pstxt"]
+
+
+class DownloadState(Enum):
+    """Enumeration for download job states."""
+
+    PENDING = "pending"  # Custom state before first API check
+    READY = "ready"
+    RUNNING = "running"
+    FINISHED = "finished"
+    FAILED = "failed"
+    UNKNOWN = "unknown"  # Custom state if API returns unexpected value
+
+
+class DownloadStatus(BaseModel):
+    """Represents the status details of a download job returned by the API."""
+
+    @property
+    def file_name(self) -> Optional[str]:
+        return self.get_value("file_name")
+
+    @property
+    def message(self) -> Optional[str]:
+        """A human readable error message if the status is failed, otherwise null."""
+        return self.get_value("message")
+
+    @property
+    def seconds_elapsed(self) -> Optional[float]:
+        """Time taken to generate the file or time taken so far."""
+        return to_float(self.get_value("seconds_elapsed"))
+
+    @property
+    def api_status(self) -> DownloadState:
+        """Current state of the request from the API."""
+        status_str = self.get_value("status")
+        if status_str:
+            try:
+                return DownloadState(status_str)
+            except ValueError:
+                return DownloadState.UNKNOWN
+        return DownloadState.UNKNOWN
+
+    @property
+    def total_columns(self) -> Optional[int]:
+        return to_int(self.get_value("total_columns"))
+
+    @property
+    def total_rows(self) -> Optional[int]:
+        return to_int(self.get_value("total_rows"))
+
+    @property
+    def total_size_kb(self) -> Optional[float]:
+        """Estimated file size in kilobytes."""
+        return to_float(self.get_value("total_size"))
+
+    @property
+    def file_url(self) -> Optional[str]:
+        """The URL for the file (relative path)."""
+        return self.get_value("file_url")
+
+    def __repr__(self) -> str:
+        return (
+            f"<DownloadStatus status='{self.api_status.value}' file='{self.file_name}'>"
+        )