Budget Data Models

class Budget:
    """
    A budget is a plan that describes what you expect to spend on Cloud projects,
    plus the rules to execute as spend is tracked against that plan.

    Attributes:
        name (str): Output only. Resource name of the budget
            (billingAccounts/{billingAccountId}/budgets/{budgetId})
        display_name (str): User data for display name in UI
            (must be ≤ 60 characters)
        budget_filter (Filter): Optional. Filters that define which resources
            are used to compute actual spend against the budget amount
        amount (BudgetAmount): Required. Budgeted amount
        threshold_rules (List[ThresholdRule]): Optional. Rules that trigger
            alerts when spend exceeds specified percentages
        notifications_rule (NotificationsRule): Optional. Rules to apply to
            notifications sent based on budget spend (v1 only)
        etag (str): Optional. Etag to validate the budget's version when updating
    """
    name: str
    display_name: str  
    budget_filter: Filter
    amount: BudgetAmount
    threshold_rules: List[ThresholdRule]
    notifications_rule: NotificationsRule  # v1 only
    etag: str

class BudgetAmount:
    """
    The budgeted amount for each usage period.
    
    This is a union field - exactly one of the following must be set:
    - specified_amount: A specified amount to use as the budget
    - last_period_amount: Use the amount of last period as the budget
    """
    # Union field "budget_amount": exactly one of the following
    specified_amount: Money
    last_period_amount: LastPeriodAmount

class LastPeriodAmount:
    """
    Describes a budget amount that is based on the amount spent in the
    previous period (month, quarter, year, or custom period).
    
    This creates a dynamic budget that adjusts based on historical spending.
    """
    pass  # No additional fields - presence indicates using last period amount

class Filter:
    """
    A filter for a budget, limiting the scope of the cost to calculate.

    Attributes:
        projects (List[str]): Optional. Set of projects in the form
            projects/{project}, specifying that usage from only these
            projects should be included in the budget
        resource_ancestors (List[str]): Optional. Set of folders and
            organizations, specifying that usage from these containers
            should be included in the budget
        credit_types_treatment (CreditTypesTreatment): Optional. How to treat
            credits in budget calculations  
        credit_types (List[str]): Optional. Set of credit type display names
            to include in the budget. If credit_types_treatment is 
            INCLUDE_SPECIFIED_CREDITS, this field is required
        services (List[str]): Optional. Set of services to include in budget
        subaccounts (List[str]): Optional. Set of subaccounts to include
        labels (MutableMapping[str, struct_pb2.ListValue]): Optional. Set of key/value pairs
            for resource labels
        calendar_period (CalendarPeriod): Optional. Specifies a calendar period
        custom_period (CustomPeriod): Optional. Specifies a custom time period
    """
    projects: List[str]
    resource_ancestors: List[str] 
    credit_types_treatment: CreditTypesTreatment
    credit_types: List[str]
    services: List[str]
    subaccounts: List[str]
    labels: MutableMapping[str, struct_pb2.ListValue]
    calendar_period: CalendarPeriod
    custom_period: CustomPeriod

    class CreditTypesTreatment(Enum):
        """How to treat credits in budget calculations."""
        CREDIT_TYPES_TREATMENT_UNSPECIFIED = 0
        INCLUDE_ALL_CREDITS = 1  # Include all credit types
        EXCLUDE_ALL_CREDITS = 2  # Exclude all credit types
        INCLUDE_SPECIFIED_CREDITS = 3  # Include only specified credits

class CustomPeriod:
    """
    All date times begin at midnight UTC and end at the specified end date.

    Attributes:
        start_date (Date): Required. Start date of the budget period
        end_date (Date): Optional. End date of the budget period
    """
    start_date: Date
    end_date: Date

class CalendarPeriod(Enum):
    """
    A CalendarPeriod represents the abstract concept of a time period 
    that has a canonical start.

    Values:
        CALENDAR_PERIOD_UNSPECIFIED (0): Calendar period is unset
        MONTH (1): A month, starting on the first day of each month
        QUARTER (2): A quarter, starting on January 1, April 1, July 1, October 1
        YEAR (3): A year, starting on January 1
    """
    CALENDAR_PERIOD_UNSPECIFIED = 0
    MONTH = 1
    QUARTER = 2  
    YEAR = 3

class ThresholdRule:
    """
    ThresholdRule contains a definition of a threshold for a budget.

    Attributes:
        threshold_percent (float): Required. The percentage of the budget to
            be spent. Value must be between 0.0 and 1.0
        spend_basis (Basis): Optional. Type of basis used to calculate
            threshold spend
    """
    threshold_percent: float  # Non-negative number (0.5 = 50%)
    spend_basis: Basis

    class Basis(Enum):
        """The type of basis used to calculate threshold spend."""
        BASIS_UNSPECIFIED = 0
        CURRENT_SPEND = 1  # Use current spend as basis for comparison
        FORECASTED_SPEND = 2  # Use forecasted spend (only with calendar periods)

# Import these types from Google's protobuf libraries:
from google.type import money_pb2, date_pb2
from google.protobuf import field_mask_pb2, struct_pb2
from typing import MutableMapping, MutableSequence

class Money:  # From google.type.money_pb2
    """
    Represents an amount of money with its currency type.

    Attributes:
        currency_code (str): The three-letter currency code defined in ISO 4217
        units (int): The whole units of the amount
        nanos (int): Number of nano (10^-9) units of the amount
    """
    currency_code: str  # e.g., "USD", "EUR"
    units: int
    nanos: int

class Date:  # From google.type.date_pb2
    """
    Represents a whole or partial calendar date.

    Attributes:
        year (int): Year of the date (1-9999, or 0 for unknown)
        month (int): Month of the year (1-12, or 0 for unknown)
        day (int): Day of the month (1-31, or 0 for unknown)
    """
    year: int
    month: int
    day: int

class FieldMask:  # From google.protobuf.field_mask_pb2
    """
    A field mask to specify the fields to be updated.

    Attributes:
        paths (List[str]): The set of field mask paths
    """
    paths: List[str]

from google.cloud.billing import budgets
from google.type import money_pb2, date_pb2

# Create a monthly budget for $1000
budget = budgets.Budget(
    display_name="Monthly Project Budget",
    amount=budgets.BudgetAmount(
        specified_amount=money_pb2.Money(
            currency_code="USD",
            units=1000,
            nanos=0
        )
    ),
    budget_filter=budgets.Filter(
        projects=["projects/my-project-id"],
        calendar_period=budgets.CalendarPeriod.MONTH,
        credit_types_treatment=budgets.Filter.CreditTypesTreatment.EXCLUDE_ALL_CREDITS
    ),
    threshold_rules=[
        budgets.ThresholdRule(
            threshold_percent=0.8,  # 80%
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        ),
        budgets.ThresholdRule(
            threshold_percent=1.0,  # 100%
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        )
    ]
)

from google.cloud.billing import budgets
from google.type import date_pb2, money_pb2
from google.protobuf import struct_pb2

# Create a budget for a specific quarter
budget = budgets.Budget(
    display_name="Q1 2024 Budget",
    amount=budgets.BudgetAmount(
        specified_amount=money_pb2.Money(
            currency_code="USD",
            units=5000
        )
    ),
    budget_filter=budgets.Filter(
        projects=["projects/project-1", "projects/project-2"],
        custom_period=budgets.CustomPeriod(
            start_date=date_pb2.Date(year=2024, month=1, day=1),
            end_date=date_pb2.Date(year=2024, month=3, day=31)
        ),
        services=["services/compute.googleapis.com"],
        labels={
            "environment": struct_pb2.ListValue(values=[
                struct_pb2.Value(string_value="production"),
                struct_pb2.Value(string_value="staging")
            ]),
            "team": struct_pb2.ListValue(values=[
                struct_pb2.Value(string_value="backend")
            ])
        }
    ),
    threshold_rules=[
        budgets.ThresholdRule(
            threshold_percent=0.5,  # 50%
            spend_basis=budgets.ThresholdRule.Basis.FORECASTED_SPEND
        )
    ]
)

from google.cloud.billing import budgets

# Create a budget that uses last month's spend as the budget amount
budget = budgets.Budget(
    display_name="Dynamic Monthly Budget",
    amount=budgets.BudgetAmount(
        last_period_amount=budgets.LastPeriodAmount()
    ),
    budget_filter=budgets.Filter(
        resource_ancestors=["organizations/123456789"],
        calendar_period=budgets.CalendarPeriod.MONTH,
        credit_types_treatment=budgets.Filter.CreditTypesTreatment.INCLUDE_ALL_CREDITS
    ),
    threshold_rules=[
        budgets.ThresholdRule(
            threshold_percent=0.9,  # 90%
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        )
    ]
)

from google.cloud.billing import budgets
from google.protobuf import field_mask_pb2

# Update only the display name and threshold rules
budget.display_name = "Updated Budget Name"
budget.threshold_rules = [
    budgets.ThresholdRule(
        threshold_percent=0.75,  # 75%
        spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
    )
]

# Create field mask to specify which fields to update
update_mask = field_mask_pb2.FieldMask(
    paths=["display_name", "threshold_rules"]
)

# Update the budget
client = budgets.BudgetServiceClient()
updated_budget = client.update_budget(
    budget=budget,
    update_mask=update_mask
)