Python Client

Constructors

These are functions for constructing a client object.

tiled.client.from_uri(uri[, ...])	Connect to a Node on a local or remote server.
tiled.client.from_profile(name[, ...])	Build a Node based a 'profile' (a named configuration).

Client Node

The Node interface extends the collections.abc.Mapping (i.e. read-only dict) interface, so it supports these standard “magic methods”:

• __getitem__ (lookup by key with [])

• __iter__ (iteration, use in for-loops for example)

• __len__ (has a length, can be passed to len)

as well as:

tiled.client.node.Node.get(k[,d])
tiled.client.node.Node.keys()
tiled.client.node.Node.items()
tiled.client.node.Node.values()

The views returned by .keys(), .items(), and .values() support efficient random access—e.g.

node.values()[3]
node.values()[-1]
node.values()[:3]

and several convenience methods:

tiled.iterviews.ValuesView.first()	Get the first value.
tiled.iterviews.ValuesView.last()	Get the last value.
tiled.iterviews.ValuesView.head([n])	Get the first N values.
tiled.iterviews.ValuesView.tail([n])	Get the last N values.

Likewise for .keys() and .items().

Beyond the Mapping interface, Node adds the following attributes

tiled.client.node.Node.metadata	Metadata about this data source.
tiled.client.node.Node.references	References (links) to related context, metadata, or data.
tiled.client.node.Node.sorting	The current sorting of this Node
tiled.client.node.Node.uri	Direct link to this entry
tiled.client.node.Node.specs	List of specifications describing the structure of the metadata and/or data.

It adds these methods, which return a new Node instance.

tiled.client.node.Node.search(query)	Make a Node with a subset of this Node's entries, filtered by query.
tiled.client.node.Node.sort(*sorting)	Make a Node with the same entries but sorted according to sorting.

It adds these methods for downloading and refreshing cached data.

tiled.client.node.Node.download()	Access all the data in this Node.
tiled.client.node.Node.refresh([force])	Refresh cached data for this node.

It adds this method, which returns the unique metadata keys, structure_families, and specs of its children along with their counts.

tiled.client.node.Node.distinct(*metadata_keys)

Get the unique values and optionally counts of metadata_keys, structure_families, and specs in this Node's entries

Structure Clients

For each structure family (“array”, “dataframe”, etc.) there is a client object that understand how to request and decode chunks/partitions of data for this structure.

In fact, there can be more than one client for a given structure family. Tiled currently includes two clients for each structure family:

• A client that reads the data into dask-backed objects (dask array, dask DataFrame, xarray objects backed by dask arrays)

• A client that reads the data into in-memory structures (numpy array, pandas DataFrame, xarray objects backed by numpy arrays)

Base

tiled.client.base.BaseClient(context, *, ...)
tiled.client.base.BaseClient.formats	List formats that the server can export this data as.
tiled.client.base.BaseClient.metadata	Metadata about this data source.
tiled.client.base.BaseClient.uri	Direct link to this entry
tiled.client.base.BaseClient.item	JSON payload describing this item.
tiled.client.base.BaseClient.login([...])	Depending on the server's authentication method, this will prompt for username/password:
tiled.client.base.BaseClient.logout()	Log out.
tiled.client.base.BaseClient.new_variation([...])	This is intended primarily for internal use and use by subclasses.
tiled.client.base.BaseClient.specs	List of specifications describing the structure of the metadata and/or data.
tiled.client.base.BaseStructureClient.download()	Download all data into the cache.
tiled.client.base.BaseStructureClient.refresh([force])	Refresh cached data for this node.
tiled.client.base.BaseStructureClient.structure()	Return a dataclass describing the structure of the data.

Array

tiled.client.array.DaskArrayClient(*args, ...)	Client-side wrapper around an array-like that returns dask arrays
tiled.client.array.DaskArrayClient.read_block(block)	Access the data for one block of this chunked (dask) array.
tiled.client.array.DaskArrayClient.read([slice])	Acess the entire array or a slice.
tiled.client.array.DaskArrayClient.export(...)	Download data in some format and write to a file.

tiled.client.array.ArrayClient(*args, item, ...)	Client-side wrapper around an array-like that returns in-memory arrays
tiled.client.array.ArrayClient.read_block(block)	Access the data for one block of this chunked array.
tiled.client.array.ArrayClient.read([slice])	Acess the entire array or a slice.
tiled.client.array.DaskArrayClient.export(...)	Download data in some format and write to a file.

Sparse Array

tiled.client.sparse.SparseClient(*args[, ...])
tiled.client.sparse.SparseClient.read([slice])
tiled.client.sparse.SparseClient.export(...)	Download data in some format and write to a file.

DataFrame

tiled.client.dataframe.DaskDataFrameClient(*args)	Client-side wrapper around an dataframe-like that returns dask dataframes
tiled.client.dataframe.DaskDataFrameClient.read_partition(...)	Access one partition in a partitioned (dask) dataframe.
tiled.client.dataframe.DaskDataFrameClient.read([...])	Access the entire DataFrame.
tiled.client.dataframe.DaskDataFrameClient.export(...)	Download data in some format and write to a file.

tiled.client.dataframe.DataFrameClient(*args)	Client-side wrapper around a dataframe-like that returns in-memory dataframes
tiled.client.dataframe.DataFrameClient.read_partition(...)	Access one partition of the DataFrame.
tiled.client.dataframe.DataFrameClient.read([...])	Access the entire DataFrame.
tiled.client.dataframe.DaskDataFrameClient.export(...)	Download data in some format and write to a file.

Xarray Dataset

tiled.client.xarray.DaskDatasetClient(...[, ...])
tiled.client.xarray.DaskDatasetClient.read([...])

tiled.client.xarray.DatasetClient(context, ...)
tiled.client.xarray.DatasetClient.read([...])

Cache

The module tiled.client.cache includes objects inspired by https://github.com/dask/cachey/

We opted for an independent implementation because reusing cachey would have required:

• An invasive subclass that could be a bit fragile

• And also composition in order to get the public API we want

• Carrying around some complexity/features that we do not use here

The original cachey license (which, like Tiled’s, is 3-clause BSD) is included in the same source directory as the tiled.client.cache module. (Cachey itself is used in the server, where the use case is a better fit.)

tiled.client.cache.Cache(capacity, *, ...[, ...])	A client-side cache of data from the server.
tiled.client.cache.Cache.in_memory(capacity, *)	An in-memory cache of data from the server
tiled.client.cache.Cache.on_disk(path[, ...])	An on-disk cache of data from the server
tiled.client.cache.download(*entries)	Download a local cache for Tiled so access is fast and can work offline.
tiled.client.cache.Scorer(halflife)	Object to track scores of cache

Context

tiled.client.context.Context(uri, *[, ...])	Wrap an httpx.Client with an optional cache and authentication functionality.
tiled.client.context.Context.from_any_uri(uri, *)	Accept a URI to a specific node.
tiled.client.context.Context.from_app(app, *)	Construct a Context around a FastAPI app.
tiled.client.context.Context.authenticate([...])	See login.
tiled.client.context.Context.offline
tiled.client.context.Context.force_auth_refresh()	Execute refresh flow.
tiled.client.context.Context.login([...])	Depending on the server's authentication method, this will prompt for username/password:
tiled.client.context.Context.logout()	Log out of the current session (if any).
tiled.client.context.Context.tokens	A view of the current access and refresh tokens.