Discover (Alpha)

Warning

Discover is in an Alpha release. We reserve the right to modify this API without any guarantees about backwards compatibility.

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.

Asset

The Asset class contains metadata about assets such as folders and blobs.

Blob

A Blob is a binary asset from storage.

Discover

Discover is a client for interacting with assets such as Blobs and Folders.

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.


class AccessGrant(asset_name: str, user_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

user_id

The group/user to give access to

access

The role the user should have

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

is_shared

Whether access to the asset has been granted to other users

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 group or user, what role the user has and what role the user 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'
)
list_shares() → List[descarteslabs.discover.client.AccessGrant]

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',
        user_id='user1@company.com',
        access='storage/role/owner'
    ),
    AccessGrant(
        asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson',
        user_id='user2@company.com',
        access='storage/role/viewer'
    ),
    AccessGrant(
        asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson',
        user_id='user3@company.com',
        access='storage/role/viewer'
    )
]
>>> discover.folder(
...     "asset/folder/ec1fa4ec361494e0e3f80feed065fc2f"
... ).list_shares() 
[
    AccessGrant(
        asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f',
        user_id='user1@company.com',
        access='discover/role/owner'
    ),
    AccessGrant(
        asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f',
        user_id='user2@company.com',
        access='discover/role/viewer'
    ),
    AccessGrant(
        asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f',
        user_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'
)
replace_shares(user: str, from_role: str, to_role: str) → descarteslabs.discover.client.AccessGrant[source]

Replaces access grant for an asset by specifying the group or user, what role the user has and what role the user should be given.

Parameters
  • user (str) – Email of the group or user to replace access for.

  • from_role (str) – Type of access the user 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

AccessGrant

Example

>>> 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',
    user_id='colleague@company.com',
    access='storage/role/editor'
)
revoke(from_: str, 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_ (str) – Email of the group or user to remove access from.

  • as_ (str) – Type of access that should be removed from the group or user.

Example

>>> discover.blob("asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json").revoke(
...     from_="colleague@company.com",
...     as_="viewer" # or "editor"
... ) 
share(with_: str, as_: str) → descarteslabs.discover.client.AccessGrant[source]

Adds access grant for an asset by specifying who to share with and as what role.

Parameters
  • with_ (str) – Email of the group or user to give access to.

  • as_ (str) – Type of access the group or user should be given.

Returns

access_grant – Access grant that was added.

Return type

AccessGrant

Example

>>> 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",
    user_id='colleague@company.com',
    access='storage/role/viewer'
)
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 Discover(host: str = 'platform.descarteslabs.com', discover_client: descarteslabs.common.discover.client.DiscoverGrpcClient = None)[source]

Discover is a client for interacting with assets such as Blobs and Folders.

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)

List child assets of the provided asset.

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.

update_asset(asset_name, display_name, …)

Updates display name and/or description for an asset.

add_access_grant(asset_name: str, group_or_user: str, 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 (str) – Email of the group or user to give access to.

  • role (str) – Type of access the group or user should be given.

Returns

access_grant – Access grant that was added.

Return type

AccessGrant

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',
    user_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',
    user_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

Asset

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',
        user_id='user1@company.com',
        access='storage/role/owner'
    ),
    AccessGrant(
        asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json',
        user_id='user2@company.com',
        access='storage/role/viewer'
    ),
    AccessGrant(
        asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.json',
        user_id='user3@company.com',
        access='storage/role/editor'
    )
]
>>> discover.list_access_grants(
...     asset_name="asset/folder/ec1fa4ec361494e0e3f80feed065fc2f"
... ) 
[
    AccessGrant(
        asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f',
        user_id='user1@company.com',
        access='discover/role/owner'
    ),
    AccessGrant(
        asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f',
        user_id='user2@company.com',
        access='discover/role/viewer'
    ),
    AccessGrant(
        asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f',
        user_id='user3@company.com',
        access='discover/role/editor'
    )
]
list_assets(asset_name: Optional[str] = None) → List[descarteslabs.discover.client.Asset][source]

List child assets of the provided asset.

Parameters

asset_name (Optional[str]) – Asset name of the folder to list from.

Returns

List of child assets of the given asset.

Return type

List[Asset]

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'
    )
]
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

Asset

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: str, 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 (str) – Email of the group or user to remove access for.

  • role (str) – Type of access that should be removed from the group or user.

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: str, 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 (str) – Email of the group or user to replace access for.

  • role_from (str) – Type of access the group or user 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

AccessGrant

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',
    user_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',
    user_id='colleague@company.com',
    access='discover/role/viewer'
)
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

Asset

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 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 group or user, what role the user has and what role the user 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'
)
list() → List[descarteslabs.discover.client.Asset][source]

List the child assets of the Folder.

list_shares() → List[descarteslabs.discover.client.AccessGrant]

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',
        user_id='user1@company.com',
        access='storage/role/owner'
    ),
    AccessGrant(
        asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson',
        user_id='user2@company.com',
        access='storage/role/viewer'
    ),
    AccessGrant(
        asset_name='asset/blob/ec1fa4ec361494e0e3f80feed065fc2f:~/data_file.geojson',
        user_id='user3@company.com',
        access='storage/role/viewer'
    )
]
>>> discover.folder(
...     "asset/folder/ec1fa4ec361494e0e3f80feed065fc2f"
... ).list_shares() 
[
    AccessGrant(
        asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f',
        user_id='user1@company.com',
        access='discover/role/owner'
    ),
    AccessGrant(
        asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f',
        user_id='user2@company.com',
        access='discover/role/viewer'
    ),
    AccessGrant(
        asset_name='asset/folder/ec1fa4ec361494e0e3f80feed065fc2f',
        user_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'
)
replace_shares(user: str, from_role: str, to_role: str) → descarteslabs.discover.client.AccessGrant[source]

Replaces access grant for an asset by specifying the group or user, what role the user has and what role the user should be given.

Parameters
  • user (str) – Email of the group or user to replace access for.

  • from_role (str) – Type of access the user 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

AccessGrant

Example

>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").replace_shares(
...     user="colleague@company.com",
...     from_role="viewer",
...     to_role="editor"
... ) 
AccessGrant(
    asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f',
    user_id='colleague@company.com',
    access='discover/role/editor'
)
revoke(from_: str, 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_ (str) – Email of the group or user to remove access from.

  • as_ (str) – Type of access that should be removed from the group or user.

Example

>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").revoke(
...     from_="colleague@company.com",
...     as_="viewer" # or "editor"
... ) 
share(with_: str, as_: str) → descarteslabs.discover.client.AccessGrant[source]

Adds access grant for an asset by specifying who to share with and as what role.

Parameters
  • with_ (str) – Email of the group or user to give access to.

  • as_ (str) – Type of access the group or user should be given.

Returns

access_grant – Access grant that was added.

Return type

AccessGrant

Example

>>> discover.folder("asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f").share(
...     with_="colleague@company.com",
...     as_="viewer" # or "editor"
... ) 
AccessGrant(
    asset_name='asset/folder/c361494e0e3f8ec1fa4e0feed065fc2f',
    user_id='colleague@company.com',
    access='discover/role/viewer'
)
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'
)

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.