CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-google-cloud-resource-manager

Google Cloud Resource Manager API client library for managing projects, folders, organizations, and tags in Google Cloud Platform

—

Pending
Overview
Eval results
Files

folders.mddocs/

Folders Management

Hierarchical organization and management of folders within Google Cloud organizations. Folders provide an intermediate grouping layer between organizations and projects, enabling flexible resource organization and inheritance of IAM policies and organization policies.

Capabilities

Folder Retrieval

Retrieve detailed information about a specific folder using its resource name.

def get_folder(
    self,
    request: GetFolderRequest = None,
    *,
    name: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> Folder:
    """
    Retrieves a folder identified by the specified resource name.

    Args:
        name (str): The resource name of the folder to retrieve.
            Format: folders/{folder_id}
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        Folder: The requested folder resource

    Raises:
        google.api_core.exceptions.NotFound: If the folder doesn't exist
        google.api_core.exceptions.PermissionDenied: If access is denied
    """

Usage example:

from google.cloud.resourcemanager import FoldersClient

client = FoldersClient()
folder = client.get_folder(name="folders/123456789")
print(f"Folder: {folder.display_name} (Parent: {folder.parent})")

Folder Listing

List all folders under a specified parent resource (organization or another folder).

def list_folders(
    self,
    request: ListFoldersRequest = None,
    *,
    parent: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> pagers.ListFoldersPager:
    """
    Lists folders that are direct children of the specified parent resource.

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

    Returns:
        ListFoldersPager: An iterator over folders that automatically
                         handles pagination
    """

Usage example:

client = FoldersClient()

# List all folders under an organization
for folder in client.list_folders(parent="organizations/123456789"):
    print(f"Folder: {folder.display_name} ({folder.name})")

# List all folders under another folder
for folder in client.list_folders(parent="folders/parent-folder-id"):
    print(f"Sub-folder: {folder.display_name}")

Folder Search

Search for folders using flexible query expressions with support for filtering and sorting.

def search_folders(
    self,
    request: SearchFoldersRequest = None,
    *,
    query: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> pagers.SearchFoldersPager:
    """
    Search for folders using a flexible query language.

    Args:
        query (str): Query expression for filtering folders.
            Examples: 'displayName:dev*', 'parent.id:123456789',
                     'lifecycleState:ACTIVE'
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        SearchFoldersPager: An iterator over matching folders
    """

Usage example:

client = FoldersClient()

# Search for active folders with "dev" in the display name
for folder in client.search_folders(query="displayName:dev* AND lifecycleState:ACTIVE"):
    print(f"Found: {folder.display_name} ({folder.name})")

Folder Creation

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

def create_folder(
    self,
    request: CreateFolderRequest = None,
    *,
    folder: Folder = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> operation.Operation:
    """
    Creates a new folder. This is a long-running operation.

    Args:
        folder (Folder): The folder resource to create
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        Operation: Long-running operation that resolves to the created Folder
    """

Usage example:

from google.cloud.resourcemanager import FoldersClient
from google.cloud.resourcemanager_v3.types import Folder

client = FoldersClient()

new_folder = Folder(
    display_name="Development Team",
    parent="organizations/123456789"
)

operation = client.create_folder(folder=new_folder)
result = operation.result()  # Wait for completion
print(f"Created folder: {result.display_name} ({result.name})")

Folder Updates

Update folder attributes such as display name. This is a long-running operation.

def update_folder(
    self,
    request: UpdateFolderRequest = None,
    *,
    folder: Folder = None,
    update_mask: field_mask_pb2.FieldMask = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> operation.Operation:
    """
    Updates the specified folder. This is a long-running operation.

    Args:
        folder (Folder): The folder resource with updated values
        update_mask (FieldMask): Fields to update. If not provided,
                               all mutable fields are updated
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        Operation: Long-running operation that resolves to the updated Folder
    """

Usage example:

from google.protobuf import field_mask_pb2

client = FoldersClient()

# Get existing folder
folder = client.get_folder(name="folders/123456789")

# Update display name
folder.display_name = "Updated Development Team"

# Specify which fields to update
update_mask = field_mask_pb2.FieldMask(paths=["display_name"])

operation = client.update_folder(
    folder=folder,
    update_mask=update_mask
)
result = operation.result()
print(f"Updated folder: {result.display_name}")

Folder Movement

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

def move_folder(
    self,
    request: MoveFolderRequest = None,
    *,
    name: str = None,
    destination_parent: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> operation.Operation:
    """
    Moves a folder to a different parent resource. This is a long-running operation.

    Args:
        name (str): The resource name of the folder to move.
                   Format: folders/{folder_id}
        destination_parent (str): The new parent resource.
                                Format: organizations/{org_id} or folders/{folder_id}
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        Operation: Long-running operation that resolves to the moved Folder
    """

Usage example:

client = FoldersClient()

operation = client.move_folder(
    name="folders/source-folder-id",
    destination_parent="folders/destination-folder-id"
)
result = operation.result()
print(f"Moved folder to: {result.parent}")

Folder Deletion

Mark folders for deletion. Folders are not immediately deleted but enter a pending deletion state. This is a long-running operation.

def delete_folder(
    self,
    request: DeleteFolderRequest = None,
    *,
    name: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> operation.Operation:
    """
    Marks the specified folder for deletion. This is a long-running operation.
    
    The folder enters DELETE_REQUESTED state and will be deleted after a
    retention period unless restored with undelete_folder.

    Args:
        name (str): The resource name of the folder to delete.
                   Format: folders/{folder_id}
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        Operation: Long-running operation with no return value
    """

Folder Restoration

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

def undelete_folder(
    self,
    request: UndeleteFolderRequest = None,
    *,
    name: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> operation.Operation:
    """
    Restores a folder from the DELETE_REQUESTED state. This is a long-running operation.

    Args:
        name (str): The resource name of the folder to restore.
                   Format: folders/{folder_id}
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        Operation: Long-running operation that resolves to the restored Folder
    """

Usage example:

client = FoldersClient()

# Delete a folder
delete_op = client.delete_folder(name="folders/123456789")
delete_op.result()  # Wait for completion

# Later, restore the folder
restore_op = client.undelete_folder(name="folders/123456789")
restored_folder = restore_op.result()
print(f"Restored folder: {restored_folder.display_name}")

IAM Policy Management

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

def get_iam_policy(
    self,
    request: iam_policy_pb2.GetIamPolicyRequest = None,
    *,
    resource: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> policy_pb2.Policy:
    """
    Gets the IAM access control policy for a folder.

    Args:
        resource (str): Resource name of the folder.
                       Format: folders/{folder_id}

    Returns:
        Policy: The IAM policy for the folder
    """

def set_iam_policy(
    self,
    request: iam_policy_pb2.SetIamPolicyRequest = None,
    *,
    resource: str = None,
    policy: policy_pb2.Policy = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> policy_pb2.Policy:
    """
    Sets the IAM access control policy for a folder.

    Args:
        resource (str): Resource name of the folder
        policy (Policy): The new IAM policy

    Returns:
        Policy: The updated IAM policy
    """

def test_iam_permissions(
    self,
    request: iam_policy_pb2.TestIamPermissionsRequest = None,
    *,
    resource: str = None,
    permissions: MutableSequence[str] = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> iam_policy_pb2.TestIamPermissionsResponse:
    """
    Tests the specified permissions against the IAM policy for a folder.

    Args:
        resource (str): Resource name of the folder
        permissions (Sequence[str]): List of permissions to test

    Returns:
        TestIamPermissionsResponse: Results of the permission test
    """

Types

class Folder:
    name: str  # Resource name: folders/{folder_id}
    parent: str  # Parent resource: organizations/{id} or folders/{id}
    display_name: str  # Human-readable folder name
    state: Folder.State  # Current lifecycle state
    create_time: timestamp_pb2.Timestamp  # Creation timestamp
    update_time: timestamp_pb2.Timestamp  # Last update timestamp
    delete_time: timestamp_pb2.Timestamp  # Deletion timestamp (if deleted)
    etag: str  # Entity tag for optimistic concurrency

    class State(proto.Enum):
        STATE_UNSPECIFIED = 0
        ACTIVE = 1
        DELETE_REQUESTED = 2

# Request/Response types
class GetFolderRequest:
    name: str

class ListFoldersRequest:
    parent: str
    page_token: str
    page_size: int
    show_deleted: bool

class ListFoldersResponse:
    folders: MutableSequence[Folder]
    next_page_token: str

class SearchFoldersRequest:
    query: str
    page_token: str
    page_size: int

class SearchFoldersResponse:
    folders: MutableSequence[Folder]
    next_page_token: str

class CreateFolderRequest:
    folder: Folder

class UpdateFolderRequest:
    folder: Folder
    update_mask: field_mask_pb2.FieldMask

class MoveFolderRequest:
    name: str
    destination_parent: str

class DeleteFolderRequest:
    name: str

class UndeleteFolderRequest:
    name: str

# Metadata types for long-running operations
class CreateFolderMetadata:
    display_name: str
    parent: str

class UpdateFolderMetadata:
    # Empty metadata message

class MoveFolderMetadata:
    # Empty metadata message

class DeleteFolderMetadata:
    # Empty metadata message

class UndeleteFolderMetadata:
    # Empty metadata message

Install with Tessl CLI

npx tessl i tessl/pypi-google-cloud-resource-manager

docs

folders.md

index.md

organizations.md

projects.md

tag-bindings.md

tag-holds.md

tag-keys.md

tag-values.md

tile.json