months.py•3.89 kB
"""Month management tools for YNAB API."""
from typing import Annotated, Any
import ynab
from auth import get_api_client, get_api_configuration
def get_budget_months(
budget_id: Annotated[
str,
"The ID of the budget to query. Use 'last-used' for the most recently "
"accessed budget, or provide a specific budget ID.",
] = "last-used",
last_knowledge_of_server: Annotated[
int | None,
"The starting server knowledge for delta requests. If provided, only "
"entities that have changed since this value will be included. Use None "
"for full data.",
] = None,
) -> dict[str, Any]:
"""Get all budget months for a budget.
Retrieves a list of all budget months, which you can use to discover available
months for historical analysis or to select a specific month for detailed queries.
Each month includes summary information like income, budgeted amounts, and activity.
Args:
budget_id: The ID of the budget to query. Use 'last-used' for the most
recently accessed budget, or provide a specific budget ID.
last_knowledge_of_server: The starting server knowledge for delta requests.
If provided, only entities that have changed since this value will be
included. Use None for full data.
Returns:
dict[str, Any]: List of budget months with summary data and server knowledge
for efficient delta synchronization.
Raises:
Exception: If the API call fails.
"""
configuration = get_api_configuration()
with get_api_client(configuration) as api_client:
api_instance = ynab.MonthsApi(api_client)
try:
api_response = api_instance.get_budget_months(
budget_id, last_knowledge_of_server=last_knowledge_of_server
)
return api_response.data.model_dump() # type: ignore[attr-defined]
except Exception as e:
msg = f"Error fetching budget months: {e!s}"
raise Exception(msg) from e
def get_budget_month(
month: Annotated[
str,
"The budget month in ISO format YYYY-MM-DD (e.g., '2024-12-01') or "
"'current' for the current month.",
],
budget_id: Annotated[
str,
"The ID of the budget to query. Use 'last-used' for the most recently "
"accessed budget, or provide a specific budget ID.",
] = "last-used",
) -> dict[str, Any]:
"""Get detailed data for a single budget month.
Returns comprehensive budget month information including all categories, category
groups, income, budgeted amounts, activity, and available balances. Use this when
you need a complete picture of a specific month's budget state, including all
category details.
Args:
month: The budget month in ISO format YYYY-MM-DD (e.g., '2024-12-01') or
'current' for the current month.
budget_id: The ID of the budget to query. Use 'last-used' for the most
recently accessed budget, or provide a specific budget ID.
Returns:
dict[str, Any]: Budget month data with all categories, category groups, and
month-level summary information.
Raises:
Exception: If the API call fails or month not found.
"""
configuration = get_api_configuration()
with get_api_client(configuration) as api_client:
api_instance = ynab.MonthsApi(api_client)
try:
api_response = api_instance.get_budget_month(
budget_id, month # type: ignore[arg-type]
)
month_data = api_response.data.month # type: ignore[attr-defined]
return month_data.model_dump() # type: ignore[attr-defined]
except Exception as e:
msg = f"Error fetching budget month: {e!s}"
raise Exception(msg) from e