Discover¶
Warning
The Discover client is in an Alpha release. Descartes Labs reserves the right to modify this API without any guarantees about backwards compatibility.
Discover |
Discover is a client for interacting with assets such as Blobs and Folders. |
Asset |
The Asset class contains metadata about assets such as folders and blobs. |
Blob |
A Blob is a binary asset from storage. |
Folder |
A Folder is a container for other assets such as Blobs and Folders. |
SymLink |
SymLinks are used to represent pointers or shortcuts to other assets. |
AssetType |
The types of assets that discover supports. |
AssetListFilter |
AssetListFilter represents a filter that will be applied to list_assets it can either be a string in the form of a urlencoded query string or it can be a dictionary. |
AccessGrant |
The AccessGrant class contains metadata about access grants such as what asset the access grant is for, who to give access to, and what kind of access should be granted. |
UserEmail |
The given string is interpreted as a user email |
Organization |
The given string is interpreted as an organization |
-
class
Discover
(host=None, port=None, auth=None, certificate=None, default_retry=None, default_metadata=None, use_insecure_channel=False)[source]¶ Discover is a client for interacting with assets such as Blobs and Folders.
Parameters: - host (str, optional) – The backend host to connect to. Defaults to the correct value. Only override when debugging.
- port (int, optional) – The backend port to connect to. Defaults to the correct value. Only override when debugging.
- auth (Auth, optional) – The authentication instance to use. Defaults to
Auth.get_default_auth()
. - certificate (bytes, optional) – The certificate to use when connecting to the backend service.
- default_retry (Retry, int, optional) – The retry instance or number of times to retry a connection before giving up. Default is to retry 5 times for retryable status codes.
- default_metadata (tuple, optional) – Metadata (headers) to send to every RPC when called. The default is empty.
- use_insecure_channel (bool, optional) – If set, an insecure channel will be used. Default is secure; only use insecure when debugging.
Methods:
add_access_grant
(asset_name, group_or_user, role)Adds access grant for specified asset, group/user and role. blob
(asset_name)Constructs a Blob
request builder.create_folder
(display_name[, description, …])Creates a folder asset. delete_asset
(asset_name)Deletes an asset. folder
(asset_name)Constructs a Folder
request builder.get_asset
(asset_name)Gets an asset. list_access_grants
(asset_name)Lists access grants for specified asset. list_assets
([asset_name, filters])List child assets of the provided asset. list_org_users
([search])List the users in your organization. move_asset
(asset_name, new_parent_asset_name)Move an asset into a different folder, or into the root of your workspace. remove_access_grant
(asset_name, …)Removes access grant for specified asset, group/user and role. replace_access_grant
(asset_name, …)Replaces access grant for specified asset, group/user and role. table
(asset_name)Constructs a Table
request builder.update_asset
(asset_name[, display_name, …])Updates display name and/or description for an asset. -
add_access_grant
(asset_name: str, group_or_user: Union[str, descarteslabs.discover.client.UserEmail, descarteslabs.discover.client.Organization], role: str) → descarteslabs.discover.client.AccessGrant[source]¶ Adds access grant for specified asset, group/user and role.
Parameters: - asset_name (str) – Path of the file or folder to give access to.
- group_or_user (ShareTarget) –
UserEmail
orOrganization
to grant access for. If just a plain string is passed, it is assumed to be an email address. Acceptable ShareTarget formats: “foo@bar.com”, UserEmail(”foo@bar.com”) or Organization(“foobar”) - role (str) – Type of access the share target should be granted.
Returns: access_grant – Access grant that was added.
Return type: Examples
>>> discover.add_access_grant( ... asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json" ... group_or_user="colleague@company.com", ... role="viewer" # or "editor" ... ) AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', target_id='colleague@company.com', access='storage/role/viewer' )
>>> discover.add_access_grant( ... asset_name="asset/folder/ec1fa4ec361494e0e3f80feed065fc2f" ... group_or_user="colleague@company.com", ... role="editor" # or "viewer" ... ) AccessGrant( asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f', target_id='colleague@company.com', access='discover/role/editor' )
-
blob
(asset_name: str) → descarteslabs.discover.client.Blob[source]¶ Constructs a
Blob
request builder. This is a helper that simplifies construction of Discover requests that involve storage assets (ie. “blobs”).Parameters: asset_name (str) – Asset ID of the blob. Returns: blob – A Discover request builder for requests involving storage assets. Return type: Blob
-
create_folder
(display_name: str, description: Optional[str] = None, parent_asset_name: Optional[str] = None) → descarteslabs.discover.client.Asset[source]¶ Creates a folder asset.
Parameters: - display_name (str) – Display name for the folder.
- description (Optional[str]) – Optional description of the folder.
- parent_asset_name (Optional[str]) – Optionally create a folder inside another folder. If left blank, folder creation defaults to the caller’s namespace.
Returns: asset – The created folder asset.
Return type: Example
>>> discover.create_folder( ... display_name="Geospatial Data", ... description="This folder contains several remote sensing datasets", # optional ... parent_asset_name="asset/folder/86c100d9ffa3c95f5c9236aa9a59d1dc" # optional ... ) Asset( asset_name='asset/folder/d95f5c9286c100d9ffa336aa9a59d1dc', display_name='Geospatial Data', is_shared=False, sym_link=None, description='This folder contains several remote sensing datasets', parent_asset_name='asset/folder/86c100d9ffa3c95f5c9236aa9a59d1dc' )
-
delete_asset
(asset_name: str) → descarteslabs.discover.client.Asset[source]¶ Deletes an asset.
Parameters: asset_name (str) – The name of the asset Examples
>>> discover.delete_asset( ... asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json" ... )
>>> discover.delete_asset( ... asset_name="asset/folder/dd9ffa336aa9a59d1d95f5c9286c100c" ... )
-
folder
(asset_name: str) → descarteslabs.discover.client.Folder[source]¶ Constructs a
Folder
request builder. This is a helper that simplifies construction of Discover requests that involve Discover assets (ie. “folders”).Parameters: asset_name (str) – Asset ID of the folder. Returns: folder – A Discover request builder for requests involving Discover assets. Return type: Folder
-
get_asset
(asset_name: str) → descarteslabs.discover.client.Asset[source]¶ Gets an asset.
Parameters: asset_name (str) – Path of the file or folder to fetch. Returns: asset – Asset that only contains the asset name, display name and description. Return type: Asset Examples
>>> discover.get_asset( ... asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json" ... ) Asset( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', display_name='data_file.json', is_shared=True, sym_link=None, description='', parent_asset_name='asset/namespace/f276fc038b3f49b4eed8c89338cac25a47a73397' )
>>> discover.get_asset( ... asset_name="asset/folder/dd9ffa336aa9a59d1d95f5c9286c100c" ... ) Asset( asset_name='asset/folder/dd9ffa336aa9a59d1d95f5c9286c100c', display_name='My Folder', is_shared=False, sym_link=None, description='', parent_asset_name='asset/namespace/f276fc038b3f49b4eed8c89338cac25a47a73397' )
-
list_access_grants
(asset_name: str) → List[descarteslabs.discover.client.AccessGrant][source]¶ Lists access grants for specified asset.
Parameters: asset_name (str) – Path of the file or folder to list access grants for. Returns: access_grants – List of access grants. Return type: List[AccessGrant] Examples
>>> discover.list_access_grants( ... asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json" ... ) [ AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', target_id='user1@company.com', access='storage/role/owner' ), AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', target_id='user2@company.com', access='storage/role/viewer' ), AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', target_id='user3@company.com', access='storage/role/editor' ) ]
>>> discover.list_access_grants( ... asset_name="asset/folder/ec1fa4ec361494e0e3f80feed065fc2f" ... ) [ AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='user1@company.com', access='discover/role/owner' ), AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='user2@company.com', access='discover/role/viewer' ), AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='user3@company.com', access='discover/role/editor' ) ]
-
list_assets
(asset_name: Union[str, descarteslabs.discover.client.Organization, None] = None, filters: Union[str, descarteslabs.discover.client.AssetListFilter, None] = None) → List[descarteslabs.discover.client.Asset][source]¶ List child assets of the provided asset.
Parameters: - asset_name (Optional[Union[str, Organization]]) – Asset name of the folder or namespace to list from.
- filters (Optional[Union[str, AssetListFilter]]) –
Field names and associated values to find assets matching the specified terms.
Filters can be an encoded URL query string or an AssetListFilter object. Filters support the following fields: type: If supplied, can be one or more supported AssetTypes. name: If supplied, should be a string to find assets with the same display name. Wildcards supported by the name field: * - Matches zero or more of any character between it and the next character in the filter. Ex. name=Test* will find assets that start with Test which could include Test 1 and Test 2. Ex. name=Te*.jpg will find assets like Test1.jpg, Test Image.jpg, and Testing 123.jpg ? - Matches any one character. Ex. name=Test?.jpg will find assets like Test1.jpg but not Test10.jpg Raw filter string examples: type=blob&name=Test* : This filter will find Assets with a type of blob starting with the name Test. type=blob&type=vector : This filter will find Assets with a type of blob or vector. type=blob,vector : This syntax is an alternative to the above which is supported for types.
Returns: List of child assets of the given asset.
Return type: Examples
Calling .list_assets() with no arguments returns a list of all assets in the root of your workspace.
>>> discover.list_assets() [ Asset( asset_name='asset/folder/7278f8fa89cb28507d1b6543243a6f91', display_name='A Great Folder', is_shared=False, sym_link=None, description="There is important data in here", parent_asset_name='asset/namespace/eed8c8b3f49b49338cf276fc038ac25a47a73397' ), Asset( asset_name='asset/sym_link/b58507d1b7278f8fa89c6543143a6f91', display_name="Data Folder", is_shared=True, sym_link=SymLink( target_asset_name='asset/folder/2ab1e07c2ee5b0f3cd58e97ec9fcc3f6' ), description='', parent_asset_name='asset/namespace/eed8c8b3f49b49338cf276fc038ac25a47a73397' ), Asset( asset_name='asset/blob/8f8fa89c6543143a6b58507d1b727f91:~/australia.geojson', display_name='australia.geojson', is_shared=True, sym_link=None, description='', parent_asset_name='asset/namespace/eed8c8b3f49b49338cf276fc038ac25a47a73397' ) ]
>>> discover.list_assets(asset_name="asset/folder/7578f8fa89cb58507d1b6543143a6f91") [ Asset( asset_name='asset/folder/b585077278f8fa89cd1b6543143a6f91', display_name='A Great Folder', is_shared=False, sym_link=None, description="There is important data in here", parent_asset_name='asset/folder/7578f8fa89cb58507d1b6543143a6f91' ), Asset( asset_name='asset/folder/b585077278f8fa89cd1b6543143a6f91', display_name='Another Great Folder', is_shared=False, sym_link=None, description="There is important data in here too", parent_asset_name='asset/folder/7578f8fa89cb58507d1b6543143a6f91' ) ]
>>> discover.list_assets(Organization("descarteslabs")) [ Asset( asset_name='asset/folder/b585077278f8fa89cd1b6543143a6f91', display_name='A Great Folder', is_shared=False, sym_link=None, description="There is important data in here", parent_asset_name='asset/namespace/org:descarteslabs' ), Asset( asset_name='asset/folder/b585077278f8fa89cd1b6543143a6f91', display_name='Another Great Folder', is_shared=False, sym_link=None, description="There is important data in here too", parent_asset_name='asset/namespace/org:descarteslabs' ) ]
Calling .list_assets() with a set of filters to find assets that are of type blob.
>>> discover.list_assets(filters="type=blob,vector&name=australia*") [ Asset( asset_name='asset/blob/8f8fa89c6543143a6b58507d1b727f91:~/australia.geojson', display_name='australia.geojson', is_shared=True, sym_link=None, description='', parent_asset_name='asset/namespace/eed8c8b3f49b49338cf276fc038ac25a47a73397' ), Asset( asset_name='asset/blob/3a68f8fa89c654314b58507d1b727f91:~/australia.txt', display_name='australia.txt', is_shared=True, sym_link=None, description='', parent_asset_name='asset/namespace/eed8c8b3f49b49338cf276fc038ac25a47a73397' ) ]
>>> discover.list_assets(filters={ "type": "blob" }) [ Asset( asset_name='asset/blob/8f8fa89c6543143a6b58507d1b727f91:~/australia.geojson', display_name='australia.geojson', is_shared=True, sym_link=None, description='', parent_asset_name='asset/namespace/eed8c8b3f49b49338cf276fc038ac25a47a73397' ) ]
Calling .list_assets() with a set of filters using wildcards to find assets that contain “tra” in their display name.
>>> discover.list_assets(filters={ "name": "*tra*" }) [ Asset( asset_name='asset/blob/8f8fa89c6543143a6b58507d1b727f91:~/australia.geojson', display_name='australia.geojson', is_shared=True, sym_link=None, description='', parent_asset_name='asset/namespace/eed8c8b3f49b49338cf276fc038ac25a47a73397' ) ], [ Asset( asset_name='asset/blob/89c6548f3143a6b58507d8fa1b727f91:~/parks-and-trails.geojson', display_name='parks-and-trails.geojson', is_shared=False, sym_link=None, description='', parent_asset_name='asset/namespace/eed8c8b3f49b49338cf276fc038ac25a47a73397' ) ]
-
list_org_users
(search=None)[source]¶ List the users in your organization.
If you’re part of an organization, this will list all the users in your organization. If you provide a search string, only those users matching the search string in their email or name using a case-insensitive match, will be returned.
Parameters: search (str, optional) – A search string that will be matched using a case-insensitive match against each user’s email and name, and only the matched entries will be returned. Returns: A list containing a dictionary for each user with two entries: - email: the email of the user;
- name: the name of the user.
The list will be empty if you’re not part of an organization or if no matches are found.
Return type: list(dict) Raises: AuthError – If you don’t have proper authorization.
-
move_asset
(asset_name: str, new_parent_asset_name: Optional[str]) → descarteslabs.discover.client.Asset[source]¶ Move an asset into a different folder, or into the root of your workspace.
Parameters: - asset_name (str) – Asset name of the file or folder to move.
- new_parent_asset_name (str (optional)) – Asset name of the new parent asset. If this None, the asset will be moved into the root of your workspace.
Returns: asset – Asset that was moved.
Return type: Examples
>>> discover.move_asset("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json") Asset( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', display_name='data_file.json', is_shared=True, sym_link=None, description='moving this file to my root', parent_asset_name='asset/namespace/f276fc038b3f49b4eed8c89338cac25a47a73397' )
>>> discover.move_asset( ... asset_name="asset/folder/ec1fa4ec361494e0e3f80feed065fc2f", ... new_parent_asset_name="asset/folder/dd9ffa336aa9a59d1d95f5c9286c100c" ... ) Asset( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', display_name='My Folder', is_shared=True, sym_link=None, description='moving this folder into another folder', parent_asset_name='asset/folder/dd9ffa336aa9a59d1d95f5c9286c100c' )
-
remove_access_grant
(asset_name: str, group_or_user: Union[str, descarteslabs.discover.client.UserEmail, descarteslabs.discover.client.Organization], role: str)[source]¶ Removes access grant for specified asset, group/user and role.
Parameters: - asset_name (str) – Path of the file or folder to remove access from.
- group_or_user (ShareTarget) –
UserEmail
orOrganization
to revoke access from. If just a plain string is passed, it is assumed to be an email address. Acceptable ShareTarget formats: “foo@bar.com”, UserEmail(”foo@bar.com”) or Organization(“foobar”) - role (str) – Type of access that should be revoked from the share target.
Examples
>>> discover.remove_access_grant( ... asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json", ... group_or_user="colleague@company.com", ... role="editor" # or "viewer" ... )
>>> discover.remove_access_grant( ... asset_name="asset/folder/ec1fa4ec361494e0e3f80feed065fc2f", ... group_or_user="colleague@company.com", ... role="editor" # or "viewer" ... )
-
replace_access_grant
(asset_name: str, group_or_user: Union[str, descarteslabs.discover.client.UserEmail, descarteslabs.discover.client.Organization], role_from: str, role_to: str) → descarteslabs.discover.client.AccessGrant[source]¶ Replaces access grant for specified asset, group/user and role.
Parameters: - asset_name (str) – Path of the file or folder to replace access to.
- group_or_user (ShareTarget) –
UserEmail
orOrganization
to replace access for. If just a plain string is passed, it is assumed to be an email address. Acceptable ShareTarget formats: “foo@bar.com”, UserEmail(”foo@bar.com”) or Organization(“foobar”) - role_from (str) – Type of access the share target currently has.
- role_to (str) – Type of access that should replace the current role.
Returns: access_grant – Access grant that the previous access grant was replaced with.
Return type: Examples
>>> discover.replace_access_grant( ... asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json", ... group_or_user="colleague@company.com", ... role_from="viewer", ... role_to="editor" ... ) AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', target_id='colleague@company.com', access='storage/role/editor' )
>>> discover.replace_access_grant( ... asset_name="asset/folder/ec1fa4ec361494e0e3f80feed065fc2f", ... group_or_user="colleague@company.com", ... role_from="editor", ... role_to="viewer" ... ) AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='colleague@company.com', access='discover/role/viewer' )
-
table
(asset_name: str) → descarteslabs.discover.client.Table[source]¶ Constructs a
Table
request builder. This is a helper that simplifies construction of Discover requests that involve Table assets.Parameters: asset_name (str) – Asset ID of the table. Returns: table – A Discover request builder for requests involving Table assets. Return type: Table
-
update_asset
(asset_name, display_name: Optional[str] = None, description: Optional[str] = None) → descarteslabs.discover.client.Asset[source]¶ Updates display name and/or description for an asset.
Parameters: - asset_name (str) – Path of the file or folder to update.
- display_name (str (optional)) – New display name for the asset.
- description (str (optional)) – New description for the asset.
Returns: asset – Asset that contains updated asset information (asset_name, display_name, description).
Return type: Examples
>>> discover.update_asset( ... asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json", ... display_name="A Great JSON", # optional ... description="This is the greatest json ever." # optional ... ) Asset( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', display_name='A Great JSON', is_shared=False, sym_link=None, description='This is the greatest json ever.', parent_asset_name='asset/namespace/f276fc038b3f49b4eed8c89338cac25a47a73397' )
>>> discover.update_asset( ... asset_name="asset/folder/dd9ffa336aa9a59d1d95f5c9286c100c", ... display_name="A Great Folder", # optional ... description="This is the greatest folder ever." # optional ... ) Asset( asset_name='asset/folder/dd9ffa336aa9a59d1d95f5c9286c100c', display_name='A Great Folder', is_shared=False, sym_link=None, description='This is the greatest folder ever.', parent_asset_name='asset/namespace/f276fc038b3f49b4eed8c89338cac25a47a73397' )
-
class
Asset
(asset_name: str, display_name: str, is_shared: bool = False, sym_link: Optional[descarteslabs.discover.client.SymLink] = None, description: Optional[str] = None, parent_asset_name: Optional[str] = None)[source]¶ The Asset class contains metadata about assets such as folders and blobs.
-
asset_name
¶ The name of the asset
-
display_name
¶ The display name of the asset
Whether access to the asset has been granted to other users
-
sym_link
(optional)¶ If asset is a symlink, this field will be non-empty and will contain metadata about the underlying asset that the link points to. If asset is not a symlink, this will be None.
-
description
(optional)¶ The description of the asset
-
parent_asset_name
(optional)¶ The name of the parent asset
-
-
class
Blob
(discover: descarteslabs.discover.client.Discover, asset_name: str)[source]¶ A Blob is a binary asset from storage.
Methods:
get
()Gets an asset. list_shares
()Lists access grants for an asset. move
([to])Move an asset into a different folder, or into the root of your workspace if no to
is provided.replace_shares
(user, from_role, to_role)Replaces access grant for an asset by specifying the share target, what role the target has and what role the target should be given. revoke
(from_, as_)Removes access grant for an asset by specifying who to revoke from and what role is being removed. share
(with_, as_)Adds access grant for an asset by specifying who to share with and as what role. update
([display_name, description])Updates display name and description for an asset. -
get
() → descarteslabs.discover.client.Asset¶ Gets an asset.
Returns: asset – Asset that has display name and description. Return type: Asset Examples
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/australia.geojson").get() Asset( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/australia.geojson', display_name='australia.geojson', is_shared=True, sym_link=None, description='', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
>>> discover.folder("asset/folder/ec1fa4ec361494e0e3f80feed065fc2f").get() Asset( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', display_name='Remote Sensing Dataset', is_shared=False, sym_link=None, description='awesome satellite imagery', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
Lists access grants for an asset.
Returns: access_grants – List of access grants for the asset. Return type: List[AccessGrant] Examples
>>> discover.blob( ... "asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson" ... ).list_shares() [ AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson', target_id='user1@company.com', access='storage/role/owner' ), AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson', target_id='user2@company.com', access='storage/role/viewer' ), AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson', target_id='user3@company.com', access='storage/role/viewer' ) ]
>>> discover.folder( ... "asset/folder/ec1fa4ec361494e0e3f80feed065fc2f" ... ).list_shares() [ AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='user1@company.com', access='discover/role/owner' ), AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='user2@company.com', access='discover/role/viewer' ), AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='user3@company.com', access='discover/role/viewer' ) ]
-
move
(to: Optional[Folder] = None) → descarteslabs.discover.client.Asset¶ Move an asset into a different folder, or into the root of your workspace if no
to
is provided.Parameters: to (Folder (optional)) – The new parent. If this isn’t provided, the asset will be moved into the root of your workspace. Examples
Calling .move() with no arguments moves the specified asset to the root of your workspace.
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").move() Asset( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', display_name='My Data File', is_shared=True, sym_link=None, description='some geospatial data', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").move( ... to="asset/folder/ec1fa4ec361494e0e3f80feed065fc2f" ... ) Asset( asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f', display_name='NASA Earth Data', is_shared=True, sym_link=None, description='NASA DC, GPS satellites, SMAP, JASON, METEOSAT, ALOS', parent_asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f' )
Replaces access grant for an asset by specifying the share target, what role the target has and what role the target should be given.
Parameters: - user (ShareTarget) –
UserEmail
orOrganization
to replace access for. If just a plain string is passed, it is assumed to be an email address. Acceptable ShareTarget formats: “foo@bar.com”, UserEmail(”foo@bar.com”) or Organization(“foobar”) - from_role (str) – Type of access the share target currently has.
- to_role (str) – Type of access that should replace the current role.
Returns: access_grant – Access grant that the previous access grant was replaced with.
Return type: Examples
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").replace_shares( ... user="colleague@company.com", ... from_role="viewer", ... to_role="editor" ... ) AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', target_id='colleague@company.com', access='storage/role/editor' )
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").replace_shares( ... user=UserEmail("colleague@company.com"), ... from_role="viewer", ... to_role="editor" ... ) AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', target_id='colleague@company.com', access='storage/role/editor' )
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").replace_shares( ... user=Organization("myorg"), ... from_role="viewer", ... to_role="editor" ... ) AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', target_id='myorg', access='storage/role/editor' )
- user (ShareTarget) –
-
revoke
(from_: Union[str, descarteslabs.discover.client.UserEmail, descarteslabs.discover.client.Organization], as_: str)[source]¶ Removes access grant for an asset by specifying who to revoke from and what role is being removed. If the role does not exist, revoke does nothing.
Parameters: - from_ (ShareTarget) –
UserEmail
orOrganization
to revoke access from. If just a plain string is passed, it is assumed to be an email address. Acceptable ShareTarget formats: “foo@bar.com”, UserEmail(”foo@bar.com”) or Organization(“foobar”) - as_ (str) – Type of access that should be revoked from the share target.
Examples
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").revoke( ... from_="colleague@company.com", ... as_="viewer" # or "editor" ... )
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").revoke( ... from_=UserEmail("colleague@company.com"), ... as_="viewer" # or "editor" ... )
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").revoke( ... from_=Organization("colleague@company.com"), ... as_="viewer" # or "editor" ... )
- from_ (ShareTarget) –
Adds access grant for an asset by specifying who to share with and as what role.
Parameters: - with_ (ShareTarget) –
UserEmail
orOrganization
to give access to. If just a plain string is passed, it is assumed to be an email address. Acceptable ShareTarget formats: “foo@bar.com”, UserEmail(”foo@bar.com”) or Organization(“foobar”) - as_ (str) – Type of access the share target should be granted.
Returns: access_grant – Access grant that was added.
Return type: Examples
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").share( ... with_="colleague@company.com", ... as_="viewer" # or "editor" ... ) AccessGrant( asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json", target_id='colleague@company.com', access='storage/role/viewer' )
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").share( ... with_=UserEmail("colleague@company.com"), ... as_="viewer" # or "editor" ... ) AccessGrant( asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json", target_id='colleague@company.com', access='storage/role/viewer' )
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").share( ... with_=Organization("myorg"), ... as_="viewer" # or "editor" ... ) AccessGrant( asset_name="asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json", target_id='myorg', access='storage/role/viewer' )
- with_ (ShareTarget) –
-
update
(display_name: Optional[str] = None, description: Optional[str] = None) → descarteslabs.discover.client.Asset¶ Updates display name and description for an asset.
Parameters: - display_name (str (optional)) – New display name for asset.
- description (str (optional)) – New description for asset.
Examples
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/australia.geojson").update( ... display_name="australia.geojson", ... description="" ... ) Asset( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/australia.geojson', display_name='australia.geojson', is_shared=False, sym_link=None, description='', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
>>> discover.folder("asset/folder/ec1fa4ec361494e0e3f80feed065fc2f").update( ... display_name="Remote Sensing", ... description="NASA Earth Observation" ... ) Asset( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', display_name='Remote Sensing', is_shared=False, sym_link=None, description='NASA Earth Observation', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
-
-
class
Folder
(discover: descarteslabs.discover.client.Discover, asset_name: str)[source]¶ A Folder is a container for other assets such as Blobs and Folders.
Methods:
get
()Gets an asset. list
()List the child assets of the Folder. list_shares
()Lists access grants for an asset. move
([to])Move an asset into a different folder, or into the root of your workspace if no to
is provided.replace_shares
(user, from_role, to_role)Replaces access grant for an asset by specifying the share target, what role the target has and what role the target should be given. revoke
(from_, as_)Removes access grant for an asset by specifying who to revoke from and what role is being removed. share
(with_, as_)Adds access grant for an asset by specifying who to share with and as what role. update
([display_name, description])Updates display name and description for an asset. -
get
() → descarteslabs.discover.client.Asset¶ Gets an asset.
Returns: asset – Asset that has display name and description. Return type: Asset Examples
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/australia.geojson").get() Asset( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/australia.geojson', display_name='australia.geojson', is_shared=True, sym_link=None, description='', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
>>> discover.folder("asset/folder/ec1fa4ec361494e0e3f80feed065fc2f").get() Asset( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', display_name='Remote Sensing Dataset', is_shared=False, sym_link=None, description='awesome satellite imagery', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
Lists access grants for an asset.
Returns: access_grants – List of access grants for the asset. Return type: List[AccessGrant] Examples
>>> discover.blob( ... "asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson" ... ).list_shares() [ AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson', target_id='user1@company.com', access='storage/role/owner' ), AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson', target_id='user2@company.com', access='storage/role/viewer' ), AccessGrant( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson', target_id='user3@company.com', access='storage/role/viewer' ) ]
>>> discover.folder( ... "asset/folder/ec1fa4ec361494e0e3f80feed065fc2f" ... ).list_shares() [ AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='user1@company.com', access='discover/role/owner' ), AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='user2@company.com', access='discover/role/viewer' ), AccessGrant( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', target_id='user3@company.com', access='discover/role/viewer' ) ]
-
move
(to: Optional[Folder] = None) → descarteslabs.discover.client.Asset¶ Move an asset into a different folder, or into the root of your workspace if no
to
is provided.Parameters: to (Folder (optional)) – The new parent. If this isn’t provided, the asset will be moved into the root of your workspace. Examples
Calling .move() with no arguments moves the specified asset to the root of your workspace.
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").move() Asset( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json', display_name='My Data File', is_shared=True, sym_link=None, description='some geospatial data', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").move( ... to="asset/folder/ec1fa4ec361494e0e3f80feed065fc2f" ... ) Asset( asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f', display_name='NASA Earth Data', is_shared=True, sym_link=None, description='NASA DC, GPS satellites, SMAP, JASON, METEOSAT, ALOS', parent_asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f' )
Replaces access grant for an asset by specifying the share target, what role the target has and what role the target should be given.
Parameters: - user (ShareTarget) –
UserEmail
orOrganization
to replace access for. If just a plain string is passed, it is assumed to be an email address. Acceptable ShareTarget formats: “foo@bar.com”, UserEmail(”foo@bar.com”) or Organization(“foobar”) - from_role (str) – Type of access the share target currently has.
- to_role (str) – Type of access that should replace the current role.
Returns: access_grant – Access grant that the previous access grant was replaced with.
Return type: Examples
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").replace_shares( ... user="colleague@company.com", ... from_role="viewer", ... to_role="editor" ... ) AccessGrant( asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f', target_id='colleague@company.com', access='discover/role/editor' )
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").replace_shares( ... user=UserEmail("colleague@company.com"), ... from_role="viewer", ... to_role="editor" ... ) AccessGrant( asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f', target_id='colleague@company.com', access='discover/role/editor' )
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").replace_shares( ... user=Organization("myorg"), ... from_role="viewer", ... to_role="editor" ... ) AccessGrant( asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f', target_id='myorg', access='discover/role/editor' )
- user (ShareTarget) –
-
revoke
(from_: Union[str, descarteslabs.discover.client.UserEmail, descarteslabs.discover.client.Organization], as_: str)[source]¶ Removes access grant for an asset by specifying who to revoke from and what role is being removed. If the role does not exist, revoke does nothing.
Parameters: - from_ (ShareTarget) –
UserEmail
orOrganization
to revoke access from. If just a plain string is passed, it is assumed to be an email address. Acceptable ShareTarget formats: “foo@bar.com”, UserEmail(”foo@bar.com”) or Organization(“foobar”) - as_ (str) – Type of access that should be revoked from the share target.
Examples
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").revoke( ... from_="colleague@company.com", ... as_="viewer" # or "editor" ... )
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").revoke( ... from_=UserEmail("colleague@company.com"), ... as_="viewer" # or "editor" ... )
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").revoke( ... from_=Organization("myorg"), ... as_="viewer" # or "editor" ... )
- from_ (ShareTarget) –
Adds access grant for an asset by specifying who to share with and as what role.
Parameters: - with_ (ShareTarget) –
UserEmail
orOrganization
to give access to. If just a plain string is passed, it is assumed to be an email address. Acceptable ShareTarget formats: “foo@bar.com”, UserEmail(”foo@bar.com”) or Organization(“foobar”) - as_ (str) – Type of access the share target should be granted.
Returns: access_grant – Access grant that was added.
Return type: Examples
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").share( ... with_="colleague@company.com", ... as_="viewer" # or "editor" ... ) AccessGrant( asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f', target_id='colleague@company.com', access='discover/role/viewer' )
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").share( ... with_=UserEmail("colleague@company.com"), ... as_="viewer" # or "editor" ... ) AccessGrant( asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f', target_id='colleague@company.com', access='discover/role/viewer' )
>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").share( ... with_=Organization("myorg"), ... as_="viewer" # or "editor" ... ) AccessGrant( asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f', target_id='myorg', access='discover/role/viewer' )
- with_ (ShareTarget) –
-
update
(display_name: Optional[str] = None, description: Optional[str] = None) → descarteslabs.discover.client.Asset¶ Updates display name and description for an asset.
Parameters: - display_name (str (optional)) – New display name for asset.
- description (str (optional)) – New description for asset.
Examples
>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/australia.geojson").update( ... display_name="australia.geojson", ... description="" ... ) Asset( asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/australia.geojson', display_name='australia.geojson', is_shared=False, sym_link=None, description='', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
>>> discover.folder("asset/folder/ec1fa4ec361494e0e3f80feed065fc2f").update( ... display_name="Remote Sensing", ... description="NASA Earth Observation" ... ) Asset( asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f', display_name='Remote Sensing', is_shared=False, sym_link=None, description='NASA Earth Observation', parent_asset_name='asset/namespace/4ec36180feed065fc2f494e0e3fec1fa' )
-
-
class
SymLink
(target_asset_name: str, target_asset_display_name: str)[source]¶ SymLinks are used to represent pointers or shortcuts to other assets. This class contains metadata that is useful for interacting with the underlying asset.
-
target_asset_name
¶ Underlying asset that the symlink is pointing to.
-
target_asset_display_name
¶ The display name of the underlying asset.
-
-
class
AssetType
[source]¶ The types of assets that discover supports.
Attributes:
BLOB
FOLDER
NAMESPACE
STS_MODEL
SYM_LINK
TABLE
-
BLOB
= 'blob'¶
-
FOLDER
= 'folder'¶
-
NAMESPACE
= 'namespace'¶
-
STS_MODEL
= 'sts_model'¶
-
SYM_LINK
= 'sym_link'¶
-
TABLE
= 'vector'¶
-
-
class
AssetListFilter
(**kwargs)[source]¶ AssetListFilter represents a filter that will be applied to list_assets it can either be a string in the form of a urlencoded query string or it can be a dictionary.
Examples: { type: “blob”, name: “Some Name*” } { type: [“blob”, “folder”], name: “Some Name*” }
Methods:
clear
()copy
()fromkeys
(iterable[, value])get
(k[,d])items
()keys
()pop
(k[,d])If key is not found, d is returned if given, otherwise KeyError is raised. popitem
()as a 2-tuple; but raise KeyError if D is empty. setdefault
(k[,d])update
([E, ]**F)If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v values
()-
clear
() → None. Remove all items from D.¶
-
copy
()¶
-
classmethod
fromkeys
(iterable, value=None)¶
-
get
(k[, d]) → D[k] if k in D, else d. d defaults to None.¶
-
items
() → a set-like object providing a view on D's items¶
-
keys
() → a set-like object providing a view on D's keys¶
-
pop
(k[, d]) → v, remove specified key and return the corresponding value.¶ If key is not found, d is returned if given, otherwise KeyError is raised.
-
popitem
() → (k, v), remove and return some (key, value) pair¶ as a 2-tuple; but raise KeyError if D is empty.
-
setdefault
(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶
-
update
([E, ]**F) → None. Update D from mapping/iterable E and F.¶ If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v
-
values
() → an object providing a view on D's values¶
-
-
class
AccessGrant
(asset_name: str, target_id: str, access: str)[source]¶ The AccessGrant class contains metadata about access grants such as what asset the access grant is for, who to give access to, and what kind of access should be granted.
-
asset_name
¶ The asset the access grant is for
-
target_id
¶ The user or organization to give access to
-
access
¶ The role the share target should have
-
-
class
UserEmail
(email)[source]¶ The given string is interpreted as a user email
Parameters: email (str) – The user email to use.
-
class
Organization
(org)[source]¶ The given string is interpreted as an organization
Parameters: org (str) – The name of the organization to use. You can only share with your own organization (visit https://iam.descarteslabs.com to see your organization’s name). An organization name is always all lowercase and only contains ascii characters, the -
character and/or the_
character.