usaspending-orm 0.6.0__py3-none-any.whl

usaspending/__init__.py

@@ -0,0 +1,144 @@
+"""USASpending Python Wrapper - Simplified access to federal award data.
+
+An opinionated Python client for the USAspending.gov API that simplifies
+access to federal spending data through intuitive interfaces and smart defaults.
+"""
+
+from __future__ import annotations
+
+# Version information
+try:
+    from importlib.metadata import version
+
+    __version__ = version("usaspending")
+except ImportError:
+    # Fallback for development/editable installs
+    __version__ = "2"
+
+__author__ = "Casey Dreier"
+__email__ = "casey.dreier@planetary.org"
+
+# Core client and configuration
+from .client import USASpendingClient
+from .config import config
+
+# Exception classes for error handling
+from .exceptions import (
+    USASpendingError,
+    APIError,
+    HTTPError,
+    RateLimitError,
+    ValidationError,
+    ConfigurationError,
+    DownloadError,
+)
+
+# Model classes
+from .models import (
+    Award,
+    Contract,
+    Grant,
+    IDV,
+    Loan,
+    Transaction,
+    Recipient,
+    Agency,
+    SubTierAgency,
+    Location,
+    PeriodOfPerformance,
+    SubAward,
+    Funding,
+    Spending,
+    RecipientSpending,
+    DistrictSpending,
+    StateSpending,
+)
+
+# Query builder classes
+from .queries import (
+    AwardsSearch,
+    AgenciesSearch,
+    FundingAgenciesSearch,
+    AwardingAgenciesSearch,
+    RecipientsSearch,
+    TransactionsSearch,
+    SpendingSearch,
+    FundingSearch,
+    SubAwardsSearch,
+)
+
+# Filter classes for building queries
+from .queries.filters import (
+    AgencyType,
+    AgencyTier,
+    LocationScope,
+    AwardDateType,
+    LocationSpec,
+    AgencyFilter,
+    AwardAmountFilter,
+    KeywordsFilter,
+    LocationFilter,
+    LocationScopeFilter,
+    TimePeriodFilter,
+    TreasuryAccountComponentsFilter,
+)
+
+# Public API exports
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    "__email__",
+    # Core
+    "USASpendingClient",
+    "config",
+    # Exceptions
+    "USASpendingError",
+    "APIError",
+    "HTTPError",
+    "RateLimitError",
+    "ValidationError",
+    "ConfigurationError",
+    "DownloadError",
+    # Models
+    "Award",
+    "Contract",
+    "Grant",
+    "IDV",
+    "Loan",
+    "Transaction",
+    "Recipient",
+    "Agency",
+    "SubTierAgency",
+    "Location",
+    "PeriodOfPerformance",
+    "SubAward",
+    "Funding",
+    "Spending",
+    "RecipientSpending",
+    "DistrictSpending",
+    "StateSpending",
+    # Query builders
+    "AwardsSearch",
+    "AgenciesSearch",
+    "FundingAgenciesSearch",
+    "AwardingAgenciesSearch",
+    "RecipientsSearch",
+    "TransactionsSearch",
+    "SpendingSearch",
+    "FundingSearch",
+    "SubAwardsSearch",
+    # Filters
+    "AgencyType",
+    "AgencyTier",
+    "LocationScope",
+    "AwardDateType",
+    "LocationSpec",
+    "AgencyFilter",
+    "AwardAmountFilter",
+    "KeywordsFilter",
+    "LocationFilter",
+    "LocationScopeFilter",
+    "TimePeriodFilter",
+    "TreasuryAccountComponentsFilter",
+]

usaspending/cli/__init__.py

@@ -0,0 +1,2 @@
+# src/usaspending/cli/__init__.py
+"""Command Line Interface tools for USASpending API client."""

usaspending/cli/download_award.py

@@ -0,0 +1,113 @@
+# src/usaspending/cli/download_award.py
+
+import argparse
+import sys
+import os
+from typing import List
+
+# Helper to ensure the package root is in sys.path if running the script directly during development
+if __name__ == "__main__":
+    # Adjust path relative to the script location (src/usaspending/cli)
+    project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+    if project_root not in sys.path:
+        sys.path.insert(0, project_root)
+
+# Import necessary components from the library
+from usaspending.exceptions import DownloadError
+from usaspending import USASpendingClient
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Download detailed award data from USASpending.gov.",
+        epilog="This CLI tool queues a download job, waits for completion, downloads the zip file, and extracts the contents.",
+    )
+
+    parser.add_argument(
+        "award_id", help="The unique award identifier (e.g., PIIN/FAIN/etc.)"
+    )
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        help="The directory to save and extract the files (defaults to current directory).",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=["csv", "tsv", "pstxt"],
+        default="csv",
+        help="The format of the files (default: csv).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=1800,
+        help="Maximum time in seconds to wait (default: 1800s/30min).",
+    )
+    parser.add_argument(
+        "--poll-interval",
+        type=int,
+        default=30,
+        help="Interval in seconds between status checks (default: 30s).",
+    )
+    parser.add_argument(
+        "--no-cleanup", action="store_true", help="Keep the zip file after extraction."
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose debug logging."
+    )
+
+    args = parser.parse_args()
+
+    # Configure logging (CLI scripts can configure logging since they are applications)
+    import logging
+
+    log_level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    logger = logging.getLogger("usaspending.cli.download")
+
+    try:
+        # Initialize client (assuming default configuration handling)
+        client = USASpendingClient()
+
+        # Get award data
+        award = client.awards.find_by_award_id(args.award_id)
+
+        logger.info("--- Starting USASpending Award Download CLI ---")
+        logger.info(
+            f"Parameters: Award ID={args.award_id}, Type={award.category}, Format={args.format}"
+        )
+
+        job = award.download(file_format=args.format, destination_dir=args.output_dir)
+
+        logger.info(f"Job successfully queued. Tracking File: {job.file_name}")
+
+        # 2. Wait for completion (blocking operation)
+        extracted_files: List[str] = job.wait_for_completion(
+            timeout=args.timeout,
+            poll_interval=args.poll_interval,
+            cleanup_zip=not args.no_cleanup,
+        )
+
+        logger.info("--- Download and Extraction Complete ---")
+        # Determine the final extraction path
+        extract_subdir_name = os.path.splitext(job.file_name)[0]
+        final_path = os.path.join(job.destination_dir, extract_subdir_name)
+        logger.info(f"Data extracted to: {os.path.abspath(final_path)}")
+        logger.info(f"Total files extracted: {len(extracted_files)}")
+
+    except DownloadError as e:
+        logger.error(f"Download failed. Status: {e.status}. Message: {e}")
+        sys.exit(1)
+    except KeyboardInterrupt:
+        logger.warning("Download interrupted by user.")
+        sys.exit(1)
+    except Exception as e:
+        logger.exception(f"An unexpected error occurred: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()