API reference¶
Clients¶
tessera.TesseraClient
¶
A synchronous client for the Tessera API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
api_key
|
str | None
|
Your Tessera API key. Falls back to |
None
|
base_url
|
str
|
API base URL. Defaults to the production endpoint. |
DEFAULT_BASE_URL
|
timeout
|
float
|
Per-request timeout in seconds. |
30.0
|
max_retries
|
int
|
Retries for transient failures (429/5xx, network errors). |
3
|
http_client
|
Client | None
|
Inject your own |
None
|
Example
client = TesseraClient() df = client.read("gold_ohlcv_1m", "BTC", "2025-09")
close()
¶
Close the underlying HTTP connection pool.
datasets()
¶
List every dataset visible to your plan.
partitions(asset, *, coin=None, month=None)
¶
List the partitions of asset, optionally filtered by coin/month.
download_url(asset, coin, month)
¶
Mint a short-lived presigned download URL for one partition.
partition_refs(asset, coin, month)
¶
Expand (asset, coins, months) into concrete partition references.
scan(asset, coin, month, *, columns=None)
¶
Lazily scan one or more partitions into a Polars LazyFrame.
URLs are minted now but the data is read on .collect(). Because
presigned URLs expire (~15 min), collect promptly; for long-lived graphs
re-run scan to refresh.
read(asset, coin, month, *, columns=None)
¶
Eagerly read one or more partitions into a Polars DataFrame.
to_duckdb(asset, coin, month, *, connection=None, columns=None)
¶
Open one or more partitions as a DuckDB relation for SQL querying.
to_pandas(asset, coin, month, *, columns=None)
¶
Convenience escape hatch: read into a pandas DataFrame (via Polars).
tessera.AsyncTesseraClient
¶
An asyncio-native client for the Tessera API.
Mirrors :class:~tessera.TesseraClient with await. Parquet reads (which
are CPU/IO-bound and synchronous in the engines) run in a worker thread so
they never block the event loop.
Example
async with AsyncTesseraClient() as client: ... df = await client.read("gold_ohlcv_1m", "BTC", "2025-09")
aclose()
async
¶
Close the underlying HTTP connection pool.
datasets()
async
¶
List every dataset visible to your plan.
partitions(asset, *, coin=None, month=None)
async
¶
List the partitions of asset, optionally filtered by coin/month.
download_url(asset, coin, month)
async
¶
Mint a short-lived presigned download URL for one partition.
partition_refs(asset, coin, month)
¶
Expand (asset, coins, months) into concrete partition references.
scan(asset, coin, month, *, columns=None)
async
¶
Lazily scan one or more partitions into a Polars LazyFrame.
read(asset, coin, month, *, columns=None)
async
¶
Eagerly read one or more partitions into a Polars DataFrame.
to_duckdb(asset, coin, month, *, connection=None, columns=None)
async
¶
Open one or more partitions as a DuckDB relation for SQL querying.
to_pandas(asset, coin, month, *, columns=None)
async
¶
Convenience escape hatch: read into a pandas DataFrame (via Polars).
Helpers¶
tessera.MonthSpan
dataclass
¶
An inclusive range of months, e.g. MonthSpan("2025-01", "2025-09").
Pass it anywhere a month argument is accepted to expand to every month
in the range (inclusive of both endpoints).
months()
¶
Return the months in the span as a list of YYYY-MM strings.
tessera.PartitionRef
dataclass
¶
A fully-qualified reference to a single partition.
A partition is one (asset, coin, month) Parquet object, e.g.
gold_ohlcv_1m / BTC / 2025-09.
object_key
property
¶
The object-storage key layout: {asset}/coin={COIN}/month={YYYY-MM}.parquet.
Response models¶
tessera.DatasetsResponse
¶
Bases: BaseModel
tessera.PartitionsResponse
¶
Bases: BaseModel
tessera.DownloadResponse
¶
Bases: BaseModel
Errors¶
tessera.errors
¶
Exception hierarchy for the Tessera client.
All errors raised by this library subclass :class:TesseraError, so a single
except tessera.TesseraError catches everything. API errors additionally
carry the HTTP status_code and the machine-readable code returned by the
server (e.g. not_found, forbidden).
TesseraError
¶
Bases: Exception
Base class for every error raised by tessera.
ConfigurationError
¶
Bases: TesseraError
The client was misconfigured — e.g. no API key could be resolved.
MissingDependencyError
¶
Bases: TesseraError
An optional dependency (polars, duckdb, pandas) is required but absent.
NetworkError
¶
Bases: TesseraError
A network-level failure (connection/timeout) after exhausting retries.
PresignExpiredError
¶
Bases: TesseraError
A presigned download URL expired before the read completed.
Presigned URLs are short-lived (~15 minutes). Call scan/read again to
mint a fresh one; do not cache a :class:polars.LazyFrame across that window.
TesseraAPIError
¶
Bases: TesseraError
The API returned an error response.
Attributes:
| Name | Type | Description |
|---|---|---|
status_code |
HTTP status code of the response. |
|
code |
Machine-readable error code from the |
BadRequestError
¶
AuthenticationError
¶
ForbiddenError
¶
Bases: TesseraAPIError
403 — your plan does not grant access to this dataset or coin.
Upgrade at https://tesseralytics.dev to unlock Pro datasets and all coins.
NotFoundError
¶
ServiceUnavailableError
¶
InternalServerError
¶
error_from_response(status_code, body)
¶
Build the appropriate :class:TesseraAPIError from a response.
Prefers the {"error": "<code>"} body; falls back to the HTTP status.