Python Client

Constructors

These are functions for constructing a client object.

Standard constructors

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).

Special constructors

These are typically used for development and debugging only.

tiled.client.from_tree(tree, *[, ...])

Connect to a Node directly, running the app in this same process.

tiled.client.from_config(config, *[, ...])

Build Nodes directly, running the app in this same process.

tiled.client.from_context(context[, ...])

Advanced: Connect to a Node using a custom instance of httpx.Client or httpx.AsyncClient.

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 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()

It adds the following attributes

tiled.client.node.Node.metadata

Metadata about this data source.

tiled.client.node.Node.sorting

The current sorting of this Node

tiled.client.node.Node.path

Sequence of entry names from the root Tree to this entry

tiled.client.node.Node.uri

Direct link to this entry

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.

Finally, it adds attributes that provide efficient positional-based lookup, as in tree.values_indexer[500:600].

tiled.client.node.Node.keys_indexer

tiled.client.node.Node.items_indexer

tiled.client.node.Node.values_indexer

Finally, it exposes these methods, which are used internally and may be useful in advanced applications.

tiled.client.node.Node.client_for_item(item, ...)

Create an instance of the appropriate client class for an item.

tiled.client.node.Node.new_variation(*[, ...])

Create a copy of this Node, optionally varying some parameters.

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.metadata

Metadata about this data source.

tiled.client.base.BaseClient.path

Sequence of entry names from the root Tree to this entry

tiled.client.base.BaseClient.uri

Direct link to this entry

tiled.client.base.BaseClient.username

tiled.client.base.BaseClient.item

JSON payload describing this item.

tiled.client.base.BaseClient.new_variation([...])

This is intended primarily for internal use and use by subclasses.

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.DaskArrayClient.formats

List formats that the server can export this data as.

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.

tiled.client.array.DaskArrayClient.formats

List formats that the server can export this data as.

DataFrame

tiled.client.dataframe.DaskDataFrameClient(*args)

Client-side wrapper around an array-like that returns dask arrays

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 Structures

Variable

tiled.client.xarray.DaskVariableClient(*args)

tiled.client.xarray.DaskVariableClient.read_block(block)

Read a block (optional sub-sliced) of array data from this Variable.

tiled.client.xarray.DaskVariableClient.read([slice])

tiled.client.xarray.VariableClient(*args[, ...])

tiled.client.xarray.VariableClient.read_block(block)

Read a block (optional sub-sliced) of array data from this Variable.

tiled.client.xarray.VariableClient.read([slice])

DataArray

tiled.client.xarray.DaskDataArrayClient(*args)

tiled.client.xarray.DaskDataArrayClient.coords

A dict mapping coord names to Variables.

tiled.client.xarray.DaskDataArrayClient.read_block(block)

Read a block (optional sub-sliced) of array data from this DataArray's Variable.

tiled.client.xarray.DaskDataArrayClient.read([slice])

tiled.client.xarray.DataArrayClient(*args[, ...])

tiled.client.xarray.DataArrayClient.coords

A dict mapping coord names to Variables.

tiled.client.xarray.DataArrayClient.read_block(block)

Read a block (optional sub-sliced) of array data from this DataArray's Variable.

tiled.client.xarray.DataArrayClient.read([slice])

Dataset

tiled.client.xarray.DaskDatasetClient(*args)

tiled.client.xarray.DaskDatasetClient.coords

tiled.client.xarray.DaskDatasetClient.data_vars

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

tiled.client.xarray.DatasetClient(*args[, ...])

tiled.client.xarray.DatasetClient.data_vars

tiled.client.xarray.DatasetClient.coords

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(client, *[, ...])

Wrap an httpx.Client with an optional cache and authentication functionality.

tiled.client.context.Context.offline

tiled.client.context.Context.authenticate()

Authenticate.

tiled.client.context.Context.reauthenticate([...])

Refresh authentication.

tiled.client.context.Context.logout()

Clear the access token and the cached refresh token.

tiled.client.context.Context.tokens

A view of the current access and refresh tokens.

tiled.client.context.Context.get_json(path)

tiled.client.context.Context.get_content(path)

tiled.client.context.Context.base_url

tiled.client.context.Context.path_parts

tiled.client.context.logout_all([...])

Logout of a all sessions.

tiled.client.context.sessions([token_directory])

List all sessions.