files

client.files

TileDB File Assets

The functions of this module allow a TileDB File to be downloaded to a local filesystem, or uploaded from a local filesystem to TileDB so that it becomes a catalog asset.

Classes

Name	Description
FileUploaderError	When file upload fails.
FilesError	Raised when a file transfer operation fails.

FileUploaderError

client.files.FileUploaderError()

When file upload fails.

FilesError

client.files.FilesError()

Raised when a file transfer operation fails.

Functions

Name	Description
download_file	Download a file from a teamspace.
upload_file	Upload a file to a teamspace.
upload_tree	Recursively upload an entire directory tree to a path.

download_file

client.files.download_file(path, file, *, teamspace)

Download a file from a teamspace.

Parameters

Name	Type	Description	Default
path	str	The path of the file to be downloaded.	required
file	BinaryIO or str	The file to be written.	required
teamspace	Teamspace or str	The teamspace to which the downloaded file belongs.	required

Returns

Name	Type	Description
	None

Raises

Name	Type	Description
	FilesError:	If the file download failed.

Examples

>>> files.download_file(
...     "teamspace",
...     "README.md",
...     open("README.md", "wb"),
... )

Notes

The current implementation makes a copy of the file in memory before writing to the output file.

upload_file

client.files.upload_file(file, path, *, teamspace=None, content_type=None)

Upload a file to a teamspace.

Parameters

Name	Type	Description	Default
file	BinaryIO, PathLike, or Buffer	The file to be uploaded.	required
path	str or object	The TileDB path at which the file is to be registered. May be a path relative to a teamspace, a Folder or Asset instance, or an absolute “tiledb” URI. If the path to a folder is provided, the basename of the file will be appended to form a full asset path.	required
teamspace	Teamspace or str	The teamspace to which the file will be registered, specified by object or id. If not provided, the path parameter is queried for a teamspace id.	None
content_type	Optional[str]	The content type of the uploaded file.	None

Raises

Name	Type	Description
	FilesError:	If the file upload failed.

Examples

>>> folder = folders.create_folder(
...     "files",
...     teamspace="teamspace",
...     exists_ok=True,
... )
>>> upload_file(
...     open("README.md", "rb"),
...     "files",
...     teamspace="teamspace",
...     content_type="text/markdown",
... )

This creates a file asset at path “files/README.md” in the teamspace named “teamspace”. The file’s basename has been used to construct the full path.

If you like, you can pass a Folder or Asset object instead of a path string and get the same result.

>>> upload_file(
...     open("README.md", "rb"),
...     folder,
...     teamspace="teamspace",
...     content_type="text/markdown",
... )

If you like, you can pass a Folder or Asset object instead of a path string and get the same result.

>>> register_udf(get_tiledb_version, folder)

A file can also be registered to a specific absolute “tiledb” URI that specifies a different name.

>>> files.upload_file(
...     open("README.md", "rb"),
...     "tiledb://workspace/teamspace/files/index.md",
...     content_type="text/markdown",
... )

upload_tree

client.files.upload_tree(source, path, *, teamspace=None)

Recursively upload an entire directory tree to a path.

This function has the same semantics of pathlib.Path.copy() or shutil.copytree(). All intermediate folders needed to contain path will also be created by default.

Parameters

Name	Type	Description	Default
source	PathLike	The directory tree to be uploaded.	required
path	str or object	The TileDB path at which the directory tree is to be registered. May be a path relative to a teamspace, a Folder or Asset instance, or an absolute “tiledb” URI.	required
teamspace	Teamspace or str	The teamspace to which the file will be registered, specified by object or id. If not provided, the path parameter is queried for a teamspace id.	None

Raises

Name	Type	Description
	FilesError:	If the directory tree upload failed.

Examples

>>> upload_tree(
...     "local/files",
...     "/folder1/uploaded_files",
...     teamspace="teamspace",
... )

Say local/files is a directory that contains one file and one subdirectory with one file.

local/files
├── a.bin
└── b
    └── b.bin

The recursive upload creates

/folder1/uploaded_files
├── a.bin
└── b
    └── b.bin

in the teamspace named “teamspace” in TileDB.