folders

client.folders

TileDB folders.

This module contains functions that operate on a teamspace; adding, removing, retrieving, or listing folders. It also contains functions operating on a folder; adding, removing, or listing asset contents; or updating folder properties.

Model classes associated with these functions are also exported from this module.

Classes

Name	Description
FoldersError	Raised when a folder CRUD operation fails.

FoldersError

client.folders.FoldersError()

Raised when a folder CRUD operation fails.

Functions

Name	Description
create_folder	Create a new folder in a teamspace.
get_folder	Retrieve the representation of a TileDB folder.
list_folder_contents	Retrieve a list of assets in the folder.

create_folder

client.folders.create_folder(
    path,
    *,
    teamspace=None,
    description=None,
    parents=False,
    exist_ok=False,
)

Create a new folder in a teamspace.

Optionally, parents of the new folder can also be created.

Parameters

Name	Type	Description	Default
path	str	The TileDB path at which the folder is to be created. May be a path relative to a teamspace or an absolute “tiledb” URI.	required
teamspace	Teamspace or str	The teamspace to which the folder will be registered, specified by object or id. If not provided, the path parameter is queried for a teamspace id.	None
description	str	Description of the folder to create.	None
parents	bool	If True, parents will be created as needed. If False, a FoldersError will be raised if a parent is missing.	False
exist_ok	bool	If False, a FoldersError will be raised if the folder already exists.	False

Returns

Name	Type	Description
	Folder

Raises

Name	Type	Description
	FoldersError:	If the folder creation request failed.

Examples

>>> folder1 = folders.create_folder(
...     "folder1",
...     teamspace="teamspace",
...     description="Folder One",
... )

A folder can be created within an existing folder.

>>> folder2 = folders.create_folder(
...     "folder1/folder2",
...     teamspace="teamspace",
...     description="Folder Two",
... )

An absolute “tiledb” URI may be used as the destination path without a teamspace argument.

>>> folder3 = folders.create_folder(
...     "tiledb://workspace/teamspace/folder1/folder3",
...     description="Folder Two",
... )

get_folder

client.folders.get_folder(folder, *, teamspace=None)

Retrieve the representation of a TileDB folder.

The folder may be identified by asset id, path relative to a teamspace, or object representation (Folder or Asset instance).

Parameters

Name	Type	Description	Default
folder	Asset, Folder, or str	The object representation, name, or path of an existing folder.	required
teamspace	Teamspace or str	The representation or string identifier of the folder’s teamspace. If the folder parameter is a Folder instance, the teamspace will be obtained from it.	None

Returns

Name	Type	Description
	Folder

Raises

Name	Type	Description
	FolderError	If the folder cannot be retrieved.

Examples

>>> folder1 = get_folder("folder1", teamspace="teamspace")
>>> folder2 = get_folder("folder1/folder2", teamspace="teamspace")

list_folder_contents

client.folders.list_folder_contents(folder, *, teamspace=None)

Retrieve a list of assets in the folder.

The folder may be identified by asset id, path relative to a teamspace, or object representation (Folder or Asset instance).

Parameters

Name	Type	Description	Default
folder	Asset, Folder, or str	The representation or string identifier of an existing folder.	required
teamspace	Teamspace or str	The representation or string identifier of the folder’s teamspace. If the folder parameter is a Folder instance, the teamspace will be obtained from it.	None

Returns

Name	Type	Description
	list of Assets.

Raises

Name	Type	Description
	FolderError	If the folder’s cannot be listed.

Examples

>>> assets = folders.list_folder_contents(
...     "folder1",
...     teamspace="teamspace"
... )
>>> [asset.name for asset in assets]
["folder2"]