or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

budget-data-models.mdbudget-service-clients.mdindex.mdnotifications-alerts.mdrequest-response-types.md
tile.json

tessl/pypi-google-cloud-billing-budgets

Google Cloud Billing Budgets API client library for creating and managing cloud billing budgets

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/google-cloud-billing-budgets@1.17.x

To install, run

npx @tessl/cli install tessl/pypi-google-cloud-billing-budgets@1.17.0

index.mddocs/

Google Cloud Billing Budgets

A comprehensive Python client library for the Google Cloud Billing Budgets API, enabling developers to programmatically create, manage, and monitor Cloud Billing budgets. Budgets define spending plans and execute rules as spending is tracked against those plans, with support for automated notifications and threshold-based alerts.

Package Information

  • Package Name: google-cloud-billing-budgets
  • Language: Python
  • Installation: pip install google-cloud-billing-budgets
  • API Versions: v1 (stable), v1beta1 (beta)
  • Key Differences: v1 uses NotificationsRule, v1beta1 uses AllUpdatesRule

Core Imports

Default import (uses v1 stable API):

from google.cloud.billing import budgets

For specific API versions:

# Stable v1 API
from google.cloud.billing import budgets_v1

# Beta v1beta1 API  
from google.cloud.billing import budgets_v1beta1

Required for working with labels and protobuf types:

from google.protobuf import struct_pb2
from typing import MutableMapping, MutableSequence

Basic Usage

from google.cloud.billing import budgets

# Initialize the client
client = budgets.BudgetServiceClient()

# Create a budget
budget = budgets.Budget(
    display_name="My Monthly Budget",
    amount=budgets.BudgetAmount(
        specified_amount={"currency_code": "USD", "units": 1000}
    ),
    budget_filter=budgets.Filter(
        projects=["projects/my-project-id"]
    ),
    threshold_rules=[
        budgets.ThresholdRule(
            threshold_percent=0.8,
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        )
    ]
)

# Create the budget
parent = "billingAccounts/my-billing-account-id"
created_budget = client.create_budget(parent=parent, budget=budget)
print(f"Created budget: {created_budget.name}")

# List existing budgets
for budget in client.list_budgets(parent=parent):
    print(f"Budget: {budget.display_name}, Amount: {budget.amount}")

# Get a specific budget
budget_name = created_budget.name
retrieved_budget = client.get_budget(name=budget_name)
print(f"Retrieved budget: {retrieved_budget.display_name}")

# Update the budget
retrieved_budget.display_name = "Updated Budget Name"
updated_budget = client.update_budget(budget=retrieved_budget)

# Delete the budget
client.delete_budget(name=budget_name)
print("Budget deleted successfully")

Architecture

The Google Cloud Billing Budgets library follows Google's standard client library architecture:

  • Client Classes: Synchronous and asynchronous clients for API operations
  • Data Models: Protocol buffer-based message classes for budgets, filters, and rules
  • Transport Layer: Support for gRPC and REST protocols (REST in v1 only)
  • Pagination: Built-in paging support for list operations
  • Authentication: Integration with Google Cloud authentication and service accounts

The library supports both stable (v1) and beta (v1beta1) API versions, with enhanced notification features available in v1beta1.

Capabilities

Client Operations

Core client functionality for managing budgets including creation, retrieval, updates, listing, and deletion operations. Supports both synchronous and asynchronous clients with built-in pagination.

class BudgetServiceClient:
    def create_budget(self, parent: str, budget: Budget, **kwargs) -> Budget: ...
    def get_budget(self, name: str, **kwargs) -> Budget: ...
    def list_budgets(self, parent: str, **kwargs) -> ListBudgetsPager: ...
    def update_budget(self, budget: Budget, **kwargs) -> Budget: ...
    def delete_budget(self, name: str, **kwargs) -> None: ...

class BudgetServiceAsyncClient:
    async def create_budget(self, parent: str, budget: Budget, **kwargs) -> Budget: ...
    async def get_budget(self, name: str, **kwargs) -> Budget: ...
    async def list_budgets(self, parent: str, **kwargs) -> ListBudgetsAsyncPager: ...
    async def update_budget(self, budget: Budget, **kwargs) -> Budget: ...
    async def delete_budget(self, name: str, **kwargs) -> None: ...

Budget Service Clients

Budget Data Models

Core data structures for defining budgets, amounts, time periods, and filtering rules. These classes represent the fundamental budget configuration and constraints.

class Budget:
    name: str
    display_name: str
    budget_filter: Filter
    amount: BudgetAmount
    threshold_rules: List[ThresholdRule]
    notifications_rule: NotificationsRule  # v1 only
    etag: str

class BudgetAmount:
    # Union field: either specified_amount or last_period_amount
    specified_amount: Money
    last_period_amount: LastPeriodAmount

class Filter:
    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

Budget Data Models

Notification and Alerting

Configuration for budget notifications and threshold-based alerts. Supports Pub/Sub integration and Cloud Monitoring channels with different capabilities between v1 and v1beta1 APIs.

class ThresholdRule:
    threshold_percent: float
    spend_basis: Basis

class NotificationsRule:  # v1 only
    pubsub_topic: str
    schema_version: str
    monitoring_notification_channels: List[str]
    disable_default_iam_recipients: bool

class AllUpdatesRule:  # v1beta1 only
    pubsub_topic: str
    schema_version: str
    monitoring_notification_channels: List[str]
    disable_default_iam_recipients: bool
    enable_project_level_recipients: bool

Notifications and Alerts

Request and Response Types

API request and response message types for all budget operations, including specialized pagination response handling and field mask support for partial updates.

class CreateBudgetRequest:
    parent: str
    budget: Budget

class ListBudgetsRequest:
    parent: str
    scope: str
    page_size: int
    page_token: str

class ListBudgetsResponse:
    budgets: List[Budget]
    next_page_token: str

class UpdateBudgetRequest:
    budget: Budget
    update_mask: FieldMask

Request and Response Types

Common Types

class CalendarPeriod(Enum):
    CALENDAR_PERIOD_UNSPECIFIED = 0
    MONTH = 1
    QUARTER = 2
    YEAR = 3

class CustomPeriod:
    start_date: Date
    end_date: Date

class LastPeriodAmount:
    # Represents using previous period's spend as budget amount
    pass