foundry_dev_tools.clients.compass module#
Implementation of the compass API.
- foundry_dev_tools.clients.compass.get_decoration(decoration: api_types.ResourceDecorationSetAll | None, conv: Literal[False]) api_types.ResourceDecorationSet | None[source]#
- foundry_dev_tools.clients.compass.get_decoration(decoration: api_types.ResourceDecorationSetAll | None, conv: Literal[True]) list[api_types.ResourceDecoration] | None
- foundry_dev_tools.clients.compass.get_decoration(decoration: api_types.ResourceDecorationSetAll | None, conv: Literal[True] = True) list[api_types.ResourceDecoration] | None
Parses the decoration argument used by the compass client methods.
- class foundry_dev_tools.clients.compass.CompassClient[source]#
Bases:
APIClientCompassClient class that implements methods from the ‘compass’ API.
- api_get_resource(rid, decoration=None, permissive_folders=None, additional_operations=None, **kwargs)[source]#
Gets the resource of the resource identifier.
- Parameters:
rid (str) – the identifier of the resource
decoration (set[Literal['description', 'favorite', 'branches', 'defaultBranch', 'defaultBranchWithMarkings', 'branchesCount', 'hasBranches', 'hasMultipleBranches', 'backedObjectTypes', 'path', 'longDescription', 'inTrash', 'collections', 'namedCollections', 'tags', 'namedTags', 'alias', 'collaborators', 'namedAncestors', 'markings', 'projectAccessMarkings', 'linkedItems', 'contactInformation', 'classification', 'disableInheritedPermissions', 'propagatePermissions', 'resourceLevelRoleGrantsAllowed']] | ~typing.Literal['all'] | None) – extra decoration entries in the response
permissive_folders (bool | None) – if true read permissions are not needed if not in hidden folder
additional_operations (set[str] | None) – include extra operations in result if user has the operation
**kwargs – gets passed to
APIClient.api_request()
- Return type:
- api_get_resource_by_path(path, decoration=None, permissive_folders=None, additional_operations=None, **kwargs)[source]#
Gets the resource of the path.
- Parameters:
path (str) – the path of the resource
decoration (set[Literal['description', 'favorite', 'branches', 'defaultBranch', 'defaultBranchWithMarkings', 'branchesCount', 'hasBranches', 'hasMultipleBranches', 'backedObjectTypes', 'path', 'longDescription', 'inTrash', 'collections', 'namedCollections', 'tags', 'namedTags', 'alias', 'collaborators', 'namedAncestors', 'markings', 'projectAccessMarkings', 'linkedItems', 'contactInformation', 'classification', 'disableInheritedPermissions', 'propagatePermissions', 'resourceLevelRoleGrantsAllowed']] | ~typing.Literal['all'] | None) – extra decoration entries in the response
permissive_folders (bool | None) – if true read permissions are not needed if not in hidden folder
additional_operations (set[str] | None) – include extra operations in result if user has the operation
**kwargs – gets passed to
APIClient.api_request()
- Return type:
- api_check_name(parent_folder_rid, name=None, **kwargs)[source]#
Check if parent folder contains a child resource with the given name.
- Parameters:
- Returns:
the response contains a json which is a bool, indicating whether the resource name already exists or not
- Return type:
response
- api_delete_permanently(rids, delete_options=None, user_bearer_token=None, **kwargs)[source]#
Permanently deletes a Resource.
- Parameters:
- Return type:
- api_create_folder(name, parent_id, marking_ids=None, **kwargs)[source]#
Creates an empty folder in compass.
- Parameters:
- Returns:
- which contains a json:
with keys rid and name and other properties.
- Return type:
response
- api_get_parent(rid, **kwargs)[source]#
Returns the parent of a given resource.
- Parameters:
rid (str) – The rid of the resource for which to obtain the parent
**kwargs – gets passed to
APIClient.api_request()
- Returns:
which contains a json that either holds the parent resource or None if no parent exists
- Return type:
response
- api_get_children(rid, filter=None, decoration=None, limit=None, sort=None, page_token=None, permissive_folders=None, include_operations=False, additional_operations=None)[source]#
Returns children in a given compass folder.
- Parameters:
rid (str) – resource identifier
filter (set[str] | None) – filter out resources, syntax “service.instance.type”
decoration (set[Literal['description', 'favorite', 'branches', 'defaultBranch', 'defaultBranchWithMarkings', 'branchesCount', 'hasBranches', 'hasMultipleBranches', 'backedObjectTypes', 'path', 'longDescription', 'inTrash', 'collections', 'namedCollections', 'tags', 'namedTags', 'alias', 'collaborators', 'namedAncestors', 'markings', 'projectAccessMarkings', 'linkedItems', 'contactInformation', 'classification', 'disableInheritedPermissions', 'propagatePermissions', 'resourceLevelRoleGrantsAllowed']] | ~typing.Literal['all'] | None) – extra information for the decorated resource
limit (int | None) – maximum items in a page
sort (str | None) – A space-delimited specifier of the form “[a][ b]” [a] can be “name”, “lastModified”, or “rid” [b] is optional and can be “asc” or “desc” (e.g. “rid asc”, “name”, “lastModified desc”)
page_token (str | None) – start position for request
permissive_folders (bool | None) – Allows folder access if any sub-resource is accessible, ignoring folder permissions Default is false, non-hidden folders only
include_operations (bool) – Controls inclusion of Compass GK operations Is set to false in Foundry DevTools to improve performance. Set to None for Foundry instance default
additional_operations (str | None) – Adds specific user-permitted operations to response. Requires include_perations=True
- Return type:
- get_child_objects_of_folder(rid, filter=None, decoration=None, limit=None, sort=None, permissive_folders=None, include_operations=False, additional_operations=None)[source]#
Returns children in a given compass folder (automatic pagination).
- Parameters:
rid (api_types.Rid) – resource identifier
filter (set[str] | None) – filter out resources, syntax “service.instance.type”
decoration (api_types.ResourceDecorationSetAll | None) – extra information for the decorated resource
limit (int | None) – maximum items in a page
sort (str | None) – A space-delimited specifier of the form “[a][ b]” [a] can be “name”, “lastModified”, or “rid” [b] is optional and can be “asc” or “desc” (e.g. “rid asc”, “name”, “lastModified desc”)
permissive_folders (bool | None) – Allows folder access if any sub-resource is accessible, ignoring folder permissions Default is false, non-hidden folders only
include_operations (bool) – Controls inclusion of Compass GK operations Is set to false in Foundry DevTools to improve performance. Set to None for Foundry instance default
additional_operations (str | None) – Adds specific user-permitted operations to response. Requires include_perations=True
- Return type:
Iterator[dict]
- api_move_children(folder_rid, children, roles_map=None, options=None, expected_parents=None, **kwargs)[source]#
Moves a list of resources to the given folder.
- Parameters:
folder_rid (str) – The resource identifier of the destination compass folder
children (set[str]) – A set of resource identifiers for which the resources should be moved to the destination folder
roles_map (dict[str, list[str]] | None) – Mapping that allows updating role grants on move, e.g. when moving resources between projects with different role sets. The mapping must contain an entry for any non-deleted roles in any role set that exists on the source but not on the destination, unless specifying REMOVE_ROLE_GRANTS in options. This cannot be used to map from role sets that are present at both the source and the destination
options (set[Literal['ALLOW_MOVING_TO_HIDDEN', 'REMOVE_ROLE_GRANTS', 'DECONFLICT_NAME']] | None) – Set of options to give control about the way resources should be moved
expected_parents (dict[str, str] | None) – A map from moved resource to expected current parent.
**kwargs – gets passed to
APIClient.api_request()
- Raises:
ResourcesNotFoundError – if destination folder does not exist
ForbiddenOperationOnHiddenResource – if destination or any resources to move are hidden resources
ForbiddenOperationOnServiceProjectResources – if destination or any of the resources to move are service projects or service project resources
DuplicateNameError – if a resource with the given name already exists
CircularDependencyError – if the destination is the resource itself or one of its children
UsersNamespaceOperationForbiddenError – if trying to move projects in or out of the Users namespace
CannotMoveResourcesUnderHiddenResourceError – if the destination is a hidden resource
UnexpectedParentError – if a parent is specified that does not match the resource’s current parent
- Return type:
- api_get_resources(rids, decoration=None, include_operations=False, additional_operations=None)[source]#
Returns the resources for the RIDs.
- Parameters:
decoration (set[Literal['description', 'favorite', 'branches', 'defaultBranch', 'defaultBranchWithMarkings', 'branchesCount', 'hasBranches', 'hasMultipleBranches', 'backedObjectTypes', 'path', 'longDescription', 'inTrash', 'collections', 'namedCollections', 'tags', 'namedTags', 'alias', 'collaborators', 'namedAncestors', 'markings', 'projectAccessMarkings', 'linkedItems', 'contactInformation', 'classification', 'disableInheritedPermissions', 'propagatePermissions', 'resourceLevelRoleGrantsAllowed']] | ~typing.Literal['all'] | None) – extra information to add to the result
include_operations (bool) – Controls inclusion of Compass GK operations. Is set to false in Foundry DevTools to improve performance. Set to None for Foundry instance default.
additional_operations (set[str] | None) – Adds specific user-permitted operations to response. Requires include_perations=True.
- Return type:
- api_process_marking(rid, marking_id, path_operation_type, user_bearer_token=None, **kwargs)[source]#
Process marking to add or remove from resource.
- Parameters:
rid (str) – resource identifier of the resource for which a marking is adjusted
marking_id (str) – The id of the marking to be used
path_operation_type (Literal['ADD', 'REMOVE']) – path operation type, see
api_types.PatchOperationuser_bearer_token (str | None) – bearer token, needed when dealing with service project resources
**kwargs – gets passed to
APIClient.api_request()
- Return type:
- api_add_imports(project_rid, rids, user_bearer_token=None, **kwargs)[source]#
Add reference to a project via import.
- Parameters:
- Return type:
- api_remove_imports(project_rid, rids, user_bearer_token=None, **kwargs)[source]#
Remove imported reference from a project.
- Parameters:
- Return type:
- api_get_imports(project_rid, import_filter=None, page_size=100, page_token=None, **kwargs)[source]#
Returns a list of imported resources along some dangling imports for the specified project.
- Parameters:
project_rid (str) – The resource identifier of the project for which to retrieve the imports
import_filter (Literal['EXTERNAL', 'FILE_SYSTEM'] | None) – Filter for specific imports only
page_size (int) – The number of elements to fetch in one request. It is restricted to 100 at most and defaults to this value in case it should exceed
page_token (str | None) – start position for request
**kwargs – gets passed to
APIClient.api_request()
- Returns:
Besides a nextPageToken which marks the start position for the next request but may be None the response also contains a list of imports and dangling imports
- Return type:
response
- get_imports(project_rid, import_filter=None, page_size=100)[source]#
Returns a list of imported resources for the specified project (automatic pagination).
- Parameters:
project_rid (api_types.ProjectRid) – The resource identifier of the project for which to retrieve the imports
import_filter (api_types.ImportType | None) – Filter for specific imports only
page_size (int) – The number of elements to fetch in one request. It is restricted to 100 at most and defaults to this value in case it should exceed
- Returns:
Returns an interator holding the imported resources.
- Return type:
Iterator[dict]
- get_dangling_imports(project_rid, import_filter=None, page_size=100)[source]#
Returns a list of dangling imports for the specified project (automatic pagination).
- Parameters:
project_rid (api_types.ProjectRid) – The resource identifier of the project for which to retrieve the imports
import_filter (api_types.ImportType | None) – Filter for specific imports only
page_size (int) – The number of elements to fetch in one request. It is restricted to 100 at most and defaults to this value in case it should exceed
- Returns:
Returns an interator holding the imported resources.
- Return type:
Iterator[dict]
- api_resolve_path(path, **kwargs)[source]#
Fetch all resources that are part of the path string.
- Parameters:
path (str) – path: the path of the resource
**kwargs – gets passed to
APIClient.api_request()
- Returns:
the response contains a json which is a list of resources representing the path components
- Return type:
response
- api_search_projects(query=None, decorations=None, organizations=None, tags=None, roles=None, include_home_projects=None, direct_role_grant_principal_ids=None, sort=None, page_size=100, page_token=None, **kwargs)[source]#
Returns a list of projects satisfying the search criteria.
- Parameters:
query (str | None) – search term for the project
decorations (set[Literal['description', 'favorite', 'branches', 'defaultBranch', 'defaultBranchWithMarkings', 'branchesCount', 'hasBranches', 'hasMultipleBranches', 'backedObjectTypes', 'path', 'longDescription', 'inTrash', 'collections', 'namedCollections', 'tags', 'namedTags', 'alias', 'collaborators', 'namedAncestors', 'markings', 'projectAccessMarkings', 'linkedItems', 'contactInformation', 'classification', 'disableInheritedPermissions', 'propagatePermissions', 'resourceLevelRoleGrantsAllowed']] | ~typing.Literal['all'] | None) – extra information for the decorated resource
organizations (set[str] | None) – queries only for organizations with these marking identifiers
tags (set[str] | None) – only includes projects with these tags
roles (set[str] | None) – filters for projects where the user has one of the roles
include_home_projects (bool | None) – whether to consider home projects of the user
direct_role_grant_principal_ids (dict[str, list[str]] | None) – only return projects for which the role identifiers for given principal identifiers have been granted
sort (SortSpec | None) – see
foundry_dev_tools.utils.api_types.Sort()page_size (int) – the maximum number of projects to return. Must be in the range 0 < N <= 500
page_token (str | None) – start position for request. Must be in the range 0 <= N <= 500
**kwargs – gets passed to
APIClient.api_request()
- Returns:
the response contains a json which is a dict with a list of projects and an optional nextPageToken in case all the projects could not be fetched all at once
- Return type:
response
- Raises:
ValueError – When page_token is in inappropriate format. Should be a number in the range 0 <= N <= 500.
- search_projects(query=None, decorations=None, organizations=None, tags=None, roles=None, include_home_projects=None, direct_role_grant_principal_ids=None, sort=None, page_size=100)[source]#
Returns a list of projects satisfying the search criteria (automatic pagination).
- Parameters:
query (str | None) – search term for the project
decorations (api_types.ResourceDecorationSetAll | None) – extra information for the decorated resource
organizations (set[api_types.Rid] | None) – queries only for organizations with these marking identifiers
tags (set[api_types.Rid] | None) – only includes projects with these tags
roles (set[api_types.RoleId] | None) – filters for projects where the user has one of the roles
include_home_projects (bool | None) – whether to consider home projects of the user
direct_role_grant_principal_ids (dict[str, list[api_types.RoleId]] | None) – only return projects for which the role identifiers for given principal identifiers have been granted
sort (api_types.SortSpec | None) – see
foundry_dev_tools.utils.api_types.Sort()page_size (int) – the maximum number of projects to return. Must be in the range 0 < N <= 500
- Returns:
which contains the project data as a dict
- Return type:
Iterator[dict]
- api_get_resource_roles(rids, **kwargs)[source]#
Retrieve the role grants for a set of resources.
- Parameters:
- Returns:
which consists of a json returning a mapping between resource identifier and the associated grants
- Return type:
response
- get_resource_roles(rids)[source]#
Returns a mapping between resource identifier and resource grants result.
- api_update_project_roles(project_rid, role_grant_patches=None, **kwargs)[source]#
Updates the role grants for a project resource.
- Parameters:
project_rid (str) – resource identifier, for the resource for which roles will be updated
role_grant_patches (set[RoleGrantPatch] | None) –
list of role grants that should be patched. grant_patches have the following structure [{
”patchOperation”: “ADD” | “REMOVE”, “roleGrant”: {
”role”: roleset_id, “principal”: {
”id”: multipass_id, “type”: “USER” | “GROUP” | “EVERYONE”
}
}
}]
**kwargs – gets passed to
APIClient.api_request()
- Return type:
- api_update_resource_roles(rid, grant_patches=None, disable_inherited_permissions_for_principals=None, disable_inherited_permissions=None, **kwargs)[source]#
Updates the role grants for a resource (non-project).
This endpoint cannot be used for projects or service project resources. To update roles on a project, use api_update_project_roles().
- Parameters:
rid (str) – resource identifier, for the resource for which roles will be updated
grant_patches (set[RoleGrantPatch] | None) –
list of role grants that should be patched. grant_patches have the following structure [{
”patchOperation”: “ADD” | “REMOVE”, “roleGrant”: {
”role”: roleset_id, “principal”: {
”id”: multipass_id, “type”: “USER” | “GROUP” | “EVERYONE”
}
}
}]
disable_inherited_permissions_for_principals (set[UserGroupPrincipalPatch] | None) – patch role grants for the provided inherited permissions
disable_inherited_permissions (bool | None) – disable inherited permissions
**kwargs – gets passed to
APIClient.api_request()
- Return type:
- api_get_home_folder(decoration=None, additional_operations=None, **kwargs)[source]#
Returns the resource representing the user’s home project or if it does not exist tries to create the folder.
- Parameters:
decoration (set[Literal['description', 'favorite', 'branches', 'defaultBranch', 'defaultBranchWithMarkings', 'branchesCount', 'hasBranches', 'hasMultipleBranches', 'backedObjectTypes', 'path', 'longDescription', 'inTrash', 'collections', 'namedCollections', 'tags', 'namedTags', 'alias', 'collaborators', 'namedAncestors', 'markings', 'projectAccessMarkings', 'linkedItems', 'contactInformation', 'classification', 'disableInheritedPermissions', 'propagatePermissions', 'resourceLevelRoleGrantsAllowed']] | ~typing.Literal['all'] | None) – extra decoration entries in the response
additional_operations (set[str] | None) – include extra operations in result if user has the operation
**kwargs – gets passed to
APIClient.api_request()
- Returns:
the response contains a json which is a dict representing the decorated resource. It might be None if the user cannot access its home folder or if creation is not possible.
- Return type:
response
- api_get_decorated_organization_and_project_information(rids, decoration=None, additional_operations=None, **kwargs)[source]#
Returns the associated namespace and project information for a list of rids.
At most 500 resources should be requested at once.
- Parameters:
rids (set[str]) – The rids for which to fetch namespace and project information
decoration (set[Literal['description', 'favorite', 'branches', 'defaultBranch', 'defaultBranchWithMarkings', 'branchesCount', 'hasBranches', 'hasMultipleBranches', 'backedObjectTypes', 'path', 'longDescription', 'inTrash', 'collections', 'namedCollections', 'tags', 'namedTags', 'alias', 'collaborators', 'namedAncestors', 'markings', 'projectAccessMarkings', 'linkedItems', 'contactInformation', 'classification', 'disableInheritedPermissions', 'propagatePermissions', 'resourceLevelRoleGrantsAllowed']] | ~typing.Literal['all'] | None) – extra decoration entries in the response
additional_operations (set[str] | None) – include extra operations in result if user has the operation
**kwargs – gets passed to
APIClient.api_request()
- Returns:
the response contains a json which maps a resource identifier to namespace and project information
- Return type:
response
- api_get_all_namespace_rids(include_internal_namespaces=None, **kwargs)[source]#
For a list of rids return the associated namespace and project information.
- Parameters:
include_internal_namespaces (bool | None) – When set to true, namespaces created by the Compass system will be included in the response. Default is False
**kwargs – gets passed to
APIClient.api_request()
- Returns:
the response contains a list of all namespace rids
- Return type:
response