0
# Projects Management
1

2
Comprehensive project lifecycle management functionality for Google Cloud Platform. Projects serve as the fundamental organizational unit that contains and isolates Google Cloud resources, providing the foundation for billing, access control, and resource organization.
3

4
## Capabilities
5

6
### Project Retrieval
7

8
Retrieve detailed information about a specific project using its resource name.
9

10
```python { .api }
11
def get_project(
12
    self,
13
    request: GetProjectRequest = None,
14
    *,
15
    name: str = None,
16
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
17
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
18
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
19
) -> Project:
20
    """
21
    Retrieves a project identified by the specified resource name.
22

23
    Args:
24
        name (str): The resource name of the project to retrieve.
25
            Format: projects/{project_id}
26
        retry: Retry configuration for the request
27
        timeout: Request timeout in seconds
28
        metadata: Additional metadata to send with the request
29

30
    Returns:
31
        Project: The requested project resource
32

33
    Raises:
34
        google.api_core.exceptions.NotFound: If the project doesn't exist
35
        google.api_core.exceptions.PermissionDenied: If access is denied
36
    """
37
```
38

39
Usage example:
40

41
```python
42
from google.cloud.resourcemanager import ProjectsClient
43

44
client = ProjectsClient()
45
project = client.get_project(name="projects/my-project-id")
46
print(f"Project: {project.display_name} ({project.project_id})")
47
```
48

49
### Project Listing
50

51
List all projects accessible to the caller, optionally filtered by parent organization or folder.
52

53
```python { .api }
54
def list_projects(
55
    self,
56
    request: ListProjectsRequest = None,
57
    *,
58
    parent: str = None,
59
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
60
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
61
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
62
) -> pagers.ListProjectsPager:
63
    """
64
    Lists projects that are direct children of the specified parent resource.
65

66
    Args:
67
        parent (str): The parent resource whose projects are to be listed.
68
            Formats: organizations/{organization_id} or folders/{folder_id}
69
        retry: Retry configuration for the request
70
        timeout: Request timeout in seconds
71
        metadata: Additional metadata to send with the request
72

73
    Returns:
74
        ListProjectsPager: An iterator over projects that automatically
75
                          handles pagination
76
    """
77
```
78

79
Usage example:
80

81
```python
82
client = ProjectsClient()
83

84
# List all projects under an organization
85
for project in client.list_projects(parent="organizations/123456789"):
86
    print(f"Project: {project.project_id} - {project.display_name}")
87

88
# List all projects under a folder
89
for project in client.list_projects(parent="folders/987654321"):
90
    print(f"Project: {project.project_id} - {project.display_name}")
91
```
92

93
### Project Search
94

95
Search for projects using flexible query expressions with support for filtering and sorting.
96

97
```python { .api }
98
def search_projects(
99
    self,
100
    request: SearchProjectsRequest = None,
101
    *,
102
    query: str = None,
103
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
104
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
105
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
106
) -> pagers.SearchProjectsPager:
107
    """
108
    Search for projects using a flexible query language.
109

110
    Args:
111
        query (str): Query expression for filtering projects.
112
            Examples: 'displayName:web*', 'parent.id:123456789',
113
                     'lifecycleState:ACTIVE'
114
        retry: Retry configuration for the request
115
        timeout: Request timeout in seconds
116
        metadata: Additional metadata to send with the request
117

118
    Returns:
119
        SearchProjectsPager: An iterator over matching projects
120
    """
121
```
122

123
Usage example:
124

125
```python
126
client = ProjectsClient()
127

128
# Search for active projects with "web" in the display name
129
for project in client.search_projects(query="displayName:web* AND lifecycleState:ACTIVE"):
130
    print(f"Found: {project.project_id} - {project.display_name}")
131
```
132

133
### Project Creation
134

135
Create new projects within the Google Cloud resource hierarchy. This is a long-running operation.
136

137
```python { .api }
138
def create_project(
139
    self,
140
    request: CreateProjectRequest = None,
141
    *,
142
    project: Project = None,
143
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
144
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
145
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
146
) -> operation.Operation:
147
    """
148
    Creates a new project. This is a long-running operation.
149

150
    Args:
151
        project (Project): The project resource to create
152
        retry: Retry configuration for the request
153
        timeout: Request timeout in seconds
154
        metadata: Additional metadata to send with the request
155

156
    Returns:
157
        Operation: Long-running operation that resolves to the created Project
158
    """
159
```
160

161
Usage example:
162

163
```python
164
from google.cloud.resourcemanager import ProjectsClient
165
from google.cloud.resourcemanager_v3.types import Project
166

167
client = ProjectsClient()
168

169
new_project = Project(
170
    project_id="my-new-project-123",
171
    display_name="My New Project",
172
    parent="organizations/123456789",
173
    labels={"environment": "development", "team": "backend"}
174
)
175

176
operation = client.create_project(project=new_project)
177
result = operation.result()  # Wait for completion
178
print(f"Created project: {result.project_id}")
179
```
180

181
### Project Updates
182

183
Update project attributes such as display name, labels, and other metadata. This is a long-running operation.
184

185
```python { .api }
186
def update_project(
187
    self,
188
    request: UpdateProjectRequest = None,
189
    *,
190
    project: Project = None,
191
    update_mask: field_mask_pb2.FieldMask = None,
192
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
193
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
194
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
195
) -> operation.Operation:
196
    """
197
    Updates the specified project. This is a long-running operation.
198

199
    Args:
200
        project (Project): The project resource with updated values
201
        update_mask (FieldMask): Fields to update. If not provided,
202
                                all mutable fields are updated
203
        retry: Retry configuration for the request
204
        timeout: Request timeout in seconds
205
        metadata: Additional metadata to send with the request
206

207
    Returns:
208
        Operation: Long-running operation that resolves to the updated Project
209
    """
210
```
211

212
Usage example:
213

214
```python
215
from google.protobuf import field_mask_pb2
216

217
client = ProjectsClient()
218

219
# Get existing project
220
project = client.get_project(name="projects/my-project-id")
221

222
# Update display name and labels
223
project.display_name = "Updated Project Name"
224
project.labels["environment"] = "production"
225

226
# Specify which fields to update
227
update_mask = field_mask_pb2.FieldMask(
228
    paths=["display_name", "labels"]
229
)
230

231
operation = client.update_project(
232
    project=project,
233
    update_mask=update_mask
234
)
235
result = operation.result()
236
print(f"Updated project: {result.display_name}")
237
```
238

239
### Project Movement
240

241
Move projects between different parent resources (organizations or folders). This is a long-running operation.
242

243
```python { .api }
244
def move_project(
245
    self,
246
    request: MoveProjectRequest = None,
247
    *,
248
    name: str = None,
249
    destination_parent: str = None,
250
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
251
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
252
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
253
) -> operation.Operation:
254
    """
255
    Moves a project to a different parent resource. This is a long-running operation.
256

257
    Args:
258
        name (str): The resource name of the project to move.
259
                   Format: projects/{project_id}
260
        destination_parent (str): The new parent resource.
261
                                Format: organizations/{org_id} or folders/{folder_id}
262
        retry: Retry configuration for the request
263
        timeout: Request timeout in seconds
264
        metadata: Additional metadata to send with the request
265

266
    Returns:
267
        Operation: Long-running operation that resolves to the moved Project
268
    """
269
```
270

271
Usage example:
272

273
```python
274
client = ProjectsClient()
275

276
operation = client.move_project(
277
    name="projects/my-project-id",
278
    destination_parent="folders/new-folder-id"
279
)
280
result = operation.result()
281
print(f"Moved project to: {result.parent}")
282
```
283

284
### Project Deletion
285

286
Mark projects for deletion. Projects are not immediately deleted but enter a pending deletion state. This is a long-running operation.
287

288
```python { .api }
289
def delete_project(
290
    self,
291
    request: DeleteProjectRequest = None,
292
    *,
293
    name: str = None,
294
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
295
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
296
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
297
) -> operation.Operation:
298
    """
299
    Marks the specified project for deletion. This is a long-running operation.
300
    
301
    The project enters DELETE_REQUESTED state and will be deleted after a
302
    retention period unless restored with undelete_project.
303

304
    Args:
305
        name (str): The resource name of the project to delete.
306
                   Format: projects/{project_id}
307
        retry: Retry configuration for the request
308
        timeout: Request timeout in seconds
309
        metadata: Additional metadata to send with the request
310

311
    Returns:
312
        Operation: Long-running operation with no return value
313
    """
314
```
315

316
### Project Restoration
317

318
Restore projects that are in the deletion pending state. This is a long-running operation.
319

320
```python { .api }
321
def undelete_project(
322
    self,
323
    request: UndeleteProjectRequest = None,
324
    *,
325
    name: str = None,
326
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
327
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
328
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
329
) -> operation.Operation:
330
    """
331
    Restores a project from the DELETE_REQUESTED state. This is a long-running operation.
332

333
    Args:
334
        name (str): The resource name of the project to restore.
335
                   Format: projects/{project_id}
336
        retry: Retry configuration for the request
337
        timeout: Request timeout in seconds
338
        metadata: Additional metadata to send with the request
339

340
    Returns:
341
        Operation: Long-running operation that resolves to the restored Project
342
    """
343
```
344

345
Usage example:
346

347
```python
348
client = ProjectsClient()
349

350
# Delete a project
351
delete_op = client.delete_project(name="projects/my-project-id")
352
delete_op.result()  # Wait for completion
353

354
# Later, restore the project
355
restore_op = client.undelete_project(name="projects/my-project-id")
356
restored_project = restore_op.result()
357
print(f"Restored project: {restored_project.project_id}")
358
```
359

360
### IAM Policy Management
361

362
Manage IAM (Identity and Access Management) policies for projects, controlling who has access and what permissions they have.
363

364
```python { .api }
365
def get_iam_policy(
366
    self,
367
    request: iam_policy_pb2.GetIamPolicyRequest = None,
368
    *,
369
    resource: str = None,
370
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
371
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
372
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
373
) -> policy_pb2.Policy:
374
    """
375
    Gets the IAM access control policy for a project.
376

377
    Args:
378
        resource (str): Resource name of the project.
379
                       Format: projects/{project_id}
380

381
    Returns:
382
        Policy: The IAM policy for the project
383
    """
384

385
def set_iam_policy(
386
    self,
387
    request: iam_policy_pb2.SetIamPolicyRequest = None,
388
    *,
389
    resource: str = None,
390
    policy: policy_pb2.Policy = None,
391
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
392
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
393
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
394
) -> policy_pb2.Policy:
395
    """
396
    Sets the IAM access control policy for a project.
397

398
    Args:
399
        resource (str): Resource name of the project
400
        policy (Policy): The new IAM policy
401

402
    Returns:
403
        Policy: The updated IAM policy
404
    """
405

406
def test_iam_permissions(
407
    self,
408
    request: iam_policy_pb2.TestIamPermissionsRequest = None,
409
    *,
410
    resource: str = None,
411
    permissions: MutableSequence[str] = None,
412
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
413
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
414
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
415
) -> iam_policy_pb2.TestIamPermissionsResponse:
416
    """
417
    Tests the specified permissions against the IAM policy for a project.
418

419
    Args:
420
        resource (str): Resource name of the project
421
        permissions (Sequence[str]): List of permissions to test
422

423
    Returns:
424
        TestIamPermissionsResponse: Results of the permission test
425
    """
426
```
427

428
## Types
429

430
```python { .api }
431
class Project:
432
    name: str  # Resource name: projects/{project_id}
433
    project_id: str  # Unique project identifier
434
    display_name: str  # Human-readable project name
435
    parent: str  # Parent resource: organizations/{id} or folders/{id}
436
    state: Project.State  # Current lifecycle state
437
    labels: MutableMapping[str, str]  # User-defined key-value labels
438
    create_time: timestamp_pb2.Timestamp  # Creation timestamp
439
    update_time: timestamp_pb2.Timestamp  # Last update timestamp
440
    delete_time: timestamp_pb2.Timestamp  # Deletion timestamp (if deleted)
441
    etag: str  # Entity tag for optimistic concurrency
442

443
    class State(proto.Enum):
444
        STATE_UNSPECIFIED = 0
445
        ACTIVE = 1
446
        DELETE_REQUESTED = 2
447

448
# Request/Response types
449
class GetProjectRequest:
450
    name: str
451

452
class ListProjectsRequest:
453
    parent: str
454
    page_token: str
455
    page_size: int
456
    show_deleted: bool
457

458
class ListProjectsResponse:
459
    projects: MutableSequence[Project]
460
    next_page_token: str
461

462
class SearchProjectsRequest:
463
    query: str
464
    page_token: str
465
    page_size: int
466

467
class SearchProjectsResponse:
468
    projects: MutableSequence[Project]
469
    next_page_token: str
470

471
class CreateProjectRequest:
472
    project: Project
473

474
class UpdateProjectRequest:
475
    project: Project
476
    update_mask: field_mask_pb2.FieldMask
477

478
class MoveProjectRequest:
479
    name: str
480
    destination_parent: str
481

482
class DeleteProjectRequest:
483
    name: str
484

485
class UndeleteProjectRequest:
486
    name: str
487

488
# Metadata types for long-running operations
489
class CreateProjectMetadata:
490
    create_time: timestamp_pb2.Timestamp
491
    gettable: bool
492
    ready: bool
493

494
class UpdateProjectMetadata:
495
    # Empty metadata message
496

497
class MoveProjectMetadata:
498
    # Empty metadata message
499

500
class DeleteProjectMetadata:
501
    # Empty metadata message
502

503
class UndeleteProjectMetadata:
504
    # Empty metadata message
505
```