Coverage for src/usaspending/resources/spending_resource.py: 100%

1"""Spending resource implementation.""" 

2 

3from __future__ import annotations 

4from typing import TYPE_CHECKING 

5 

6from .base_resource import BaseResource 

7from ..logging_config import USASpendingLogger 

8 

9if TYPE_CHECKING: 

10 from ..queries.spending_search import SpendingSearch 

11 

12logger = USASpendingLogger.get_logger(__name__) 

13 

14 

15class SpendingResource(BaseResource): 

16 """Resource for spending-related operations. 

17 

18 Provides access to spending by category endpoints (recipient and district). 

19 """ 

20 

21 def search(self) -> "SpendingSearch": 

22 """Create a new spending search query builder. 

23 

24 Returns: 

25 SpendingSearch query builder for chaining filters 

26 

27 Example: 

28 >>> # Search spending by recipient 

29 >>> recipient_spending = client.spending.search() 

30 ... .by_recipient() 

31 ... .for_agency("NASA") 

32 ... .for_fiscal_year(2024) 

33 ... .limit(10) 

34 

35 >>> # Search spending by district 

36 >>> district_spending = client.spending.search() 

37 ... .by_district() 

38 ... .spending_level("awards") 

39 ... .with_place_of_performance_locations(Location("USA", "TX")) 

40 ... .all() 

41 """ 

42 logger.debug("Creating new SpendingSearch query builder") 

43 from ..queries.spending_search import SpendingSearch 

44 

45 return SpendingSearch(self._client)