Coverage for src/usaspending/queries/__init__.py: 100%

1"""Query builders for USASpending API operations. 

2 

3This module provides query builders for constructing complex API requests 

4with filtering, pagination, and result transformation capabilities. 

5 

6Base Classes: 

7 QueryBuilder: Abstract base class for chainable query operations 

8  

9Award Queries: 

10 AwardQuery: Single award retrieval operations 

11 AwardsSearch: Complex award search with filtering and chaining 

12  

13Agency Queries: 

14 AgencyQuery: Single agency retrieval operations 

15 AgencyAwardSummary: Agency award summary data retrieval 

16  

17Recipient Queries: 

18 SpendingByRecipientsSearch: Recipient search with filtering and chaining 

19 

20Example: 

21 >>> from usaspending.client import USASpending 

22 >>> client = USASpending() 

23 >>>  

24 >>> # Single award retrieval 

25 >>> award = client.awards.find_by_generated_id("CONT_AWD_123") 

26 >>>  

27 >>> # Complex award search 

28 >>> awards = client.awards.search()\\ 

29 ... .for_agency("NASA")\\ 

30 ... .in_state("TX")\\ 

31 ... .fiscal_years(2023, 2024)\\ 

32 ... .limit(50) 

33 >>>  

34 >>> for award in awards: 

35 ... print(f"{award.recipient_name}: ${award.amount:,.2f}") 

36""" 

37 

38# Import custom exceptions to make them available package-wide 

39from ..exceptions import ( 

40 USASpendingError, 

41 APIError, 

42 HTTPError, 

43 ValidationError, 

44 RateLimitError, 

45 ConfigurationError, 

46) 

47 

48from .query_builder import QueryBuilder 

49from .award_query import AwardQuery 

50from .awards_search import AwardsSearch 

51from .agency_query import AgencyQuery 

52from .funding_agencies_search import FundingAgenciesSearch 

53from .awarding_agencies_search import AwardingAgenciesSearch 

54from .agency_award_summary import AgencyAwardSummary 

55from .sub_agency_query import SubAgencyQuery 

56from .transactions_search import TransactionsSearch 

57from .funding_search import FundingSearch 

58from .spending_search import SpendingSearch 

59from .subawards_search import SubAwardsSearch 

60 

61__all__ = [ 

62 # Core query classes 

63 "QueryBuilder", 

64 "AwardQuery", 

65 "AwardsSearch", 

66 "AgencyQuery", 

67 "FundingAgenciesSearch", 

68 "AwardingAgenciesSearch", 

69 "AgencyAwardSummary", 

70 "SubAgencyQuery", 

71 "TransactionsSearch", 

72 "FundingSearch", 

73 "SpendingSearch", 

74 "SubAwardsSearch", 

75 "USASpendingError", 

76 "APIError", 

77 "HTTPError", 

78 "ValidationError", 

79 "RateLimitError", 

80 "ConfigurationError", 

81]