0
# Google Cloud Billing Budgets
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-billing-budgets
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-billing-budgets`
9
- **API Versions**: v1 (stable), v1beta1 (beta)
10
- **Key Differences**: v1 uses `NotificationsRule`, v1beta1 uses `AllUpdatesRule`
11

12
## Core Imports
13

14
Default import (uses v1 stable API):
15

16
```python
17
from google.cloud.billing import budgets
18
```
19

20
For specific API versions:
21

22
```python
23
# Stable v1 API
24
from google.cloud.billing import budgets_v1
25

26
# Beta v1beta1 API  
27
from google.cloud.billing import budgets_v1beta1
28
```
29

30
Required for working with labels and protobuf types:
31
```python
32
from google.protobuf import struct_pb2
33
from typing import MutableMapping, MutableSequence
34
```
35

36
## Basic Usage
37

38
```python
39
from google.cloud.billing import budgets
40

41
# Initialize the client
42
client = budgets.BudgetServiceClient()
43

44
# Create a budget
45
budget = budgets.Budget(
46
    display_name="My Monthly Budget",
47
    amount=budgets.BudgetAmount(
48
        specified_amount={"currency_code": "USD", "units": 1000}
49
    ),
50
    budget_filter=budgets.Filter(
51
        projects=["projects/my-project-id"]
52
    ),
53
    threshold_rules=[
54
        budgets.ThresholdRule(
55
            threshold_percent=0.8,
56
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
57
        )
58
    ]
59
)
60

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

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

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

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

79
# Delete the budget
80
client.delete_budget(name=budget_name)
81
print("Budget deleted successfully")
82
```
83

84
## Architecture
85

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

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

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

96
## Capabilities
97

98
### Client Operations
99

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

102
```python { .api }
103
class BudgetServiceClient:
104
    def create_budget(self, parent: str, budget: Budget, **kwargs) -> Budget: ...
105
    def get_budget(self, name: str, **kwargs) -> Budget: ...
106
    def list_budgets(self, parent: str, **kwargs) -> ListBudgetsPager: ...
107
    def update_budget(self, budget: Budget, **kwargs) -> Budget: ...
108
    def delete_budget(self, name: str, **kwargs) -> None: ...
109

110
class BudgetServiceAsyncClient:
111
    async def create_budget(self, parent: str, budget: Budget, **kwargs) -> Budget: ...
112
    async def get_budget(self, name: str, **kwargs) -> Budget: ...
113
    async def list_budgets(self, parent: str, **kwargs) -> ListBudgetsAsyncPager: ...
114
    async def update_budget(self, budget: Budget, **kwargs) -> Budget: ...
115
    async def delete_budget(self, name: str, **kwargs) -> None: ...
116
```
117

118
[Budget Service Clients](./budget-service-clients.md)
119

120
### Budget Data Models
121

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

124
```python { .api }
125
class Budget:
126
    name: str
127
    display_name: str
128
    budget_filter: Filter
129
    amount: BudgetAmount
130
    threshold_rules: List[ThresholdRule]
131
    notifications_rule: NotificationsRule  # v1 only
132
    etag: str
133

134
class BudgetAmount:
135
    # Union field: either specified_amount or last_period_amount
136
    specified_amount: Money
137
    last_period_amount: LastPeriodAmount
138

139
class Filter:
140
    projects: List[str]
141
    resource_ancestors: List[str]
142
    credit_types_treatment: CreditTypesTreatment
143
    credit_types: List[str]
144
    services: List[str]
145
    subaccounts: List[str]
146
    labels: MutableMapping[str, struct_pb2.ListValue]
147
    calendar_period: CalendarPeriod
148
    custom_period: CustomPeriod
149
```
150

151
[Budget Data Models](./budget-data-models.md)
152

153
### Notification and Alerting
154

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

157
```python { .api }
158
class ThresholdRule:
159
    threshold_percent: float
160
    spend_basis: Basis
161

162
class NotificationsRule:  # v1 only
163
    pubsub_topic: str
164
    schema_version: str
165
    monitoring_notification_channels: List[str]
166
    disable_default_iam_recipients: bool
167

168
class AllUpdatesRule:  # v1beta1 only
169
    pubsub_topic: str
170
    schema_version: str
171
    monitoring_notification_channels: List[str]
172
    disable_default_iam_recipients: bool
173
    enable_project_level_recipients: bool
174
```
175

176
[Notifications and Alerts](./notifications-alerts.md)
177

178
### Request and Response Types
179

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

182
```python { .api }
183
class CreateBudgetRequest:
184
    parent: str
185
    budget: Budget
186

187
class ListBudgetsRequest:
188
    parent: str
189
    scope: str
190
    page_size: int
191
    page_token: str
192

193
class ListBudgetsResponse:
194
    budgets: List[Budget]
195
    next_page_token: str
196

197
class UpdateBudgetRequest:
198
    budget: Budget
199
    update_mask: FieldMask
200
```
201

202
[Request and Response Types](./request-response-types.md)
203

204
## Common Types
205

206
```python { .api }
207
class CalendarPeriod(Enum):
208
    CALENDAR_PERIOD_UNSPECIFIED = 0
209
    MONTH = 1
210
    QUARTER = 2
211
    YEAR = 3
212

213
class CustomPeriod:
214
    start_date: Date
215
    end_date: Date
216

217
class LastPeriodAmount:
218
    # Represents using previous period's spend as budget amount
219
    pass
220
```