Python SDK (pymycorr)

The official Python client for accessing Mycorr table data programmatically. It uses Apache Arrow for efficient data transfer and returns data as pandas or polars DataFrames.

Installation

pip install pymycorr

⚠️ Requires Python 3.10 or higher.

Authentication

pymycorr authenticates using a personal access token. You can provide it in three ways:

Environment variable — set MYCORR_API_TOKEN in your shell:

export MYCORR_API_TOKEN="your-api-token"

.env file — create a .env file in your project directory:

MYCORR_API_TOKEN=your-api-token

Constructor parameter — pass the token directly:

from pymycorr import MyCorr

client = MyCorr(token="your-api-token")

To generate a token, see Personal Access Tokens.

⚠️ Never commit API tokens to version control. Use environment variables or a .env file that is listed in your .gitignore.

Quick Start

from pymycorr import MyCorr

# Initialize the client (reads MYCORR_API_TOKEN from env)
client = MyCorr()

# Fetch a table as a pandas DataFrame
df = client.get_table("your-table-id")
print(df.head())

# Fetch a specific version
df_v2 = client.get_table("your-table-id", version=2)

# Fetch as a polars DataFrame instead
df_polars = client.get_table("your-table-id", engine="polars")

# Get table metadata without downloading data
info = client.get_table_info("your-table-id")
print(info["schema"])

API Reference

`MyCorr(url=None, token=None, env_file=None, progress="auto")`

Creates a new client instance.

Parameter	Description
`url`	API endpoint. Defaults to the Mycorr production URL.
`token`	API token. If not provided, reads from `MYCORR_API_TOKEN` env variable.
`env_file`	Path to a `.env` file. Defaults to `.env` in the current directory.
`progress`	Progress display: `"auto"`, `True`, or `False`.

`get_table(table_id, version=None, engine="pandas", progress=None)`

Fetches table data as a DataFrame.

Parameter	Description
`table_id`	The table identifier (found in the table URL).
`version`	Version number (`int`) or alias (`"latest"`, `"stable"`). Defaults to the latest version.
`engine`	`"pandas"` (default) or `"polars"`.
`progress`	Override the client-level progress setting for this request.

`get_table_info(table_id, version=None)`

Returns table metadata and schema as a dictionary, without downloading the full dataset.

Parameter	Description
`table_id`	The table identifier.
`version`	Version number or alias. Defaults to the latest version.

Error Handling

pymycorr raises specific exceptions for different error scenarios:

Exception	Description
`TableNotFoundError`	The requested table does not exist or you don't have access.
`QuotaExceededError`	Your egress quota has been exceeded.
`TableConversionError`	Failed to convert the data to a DataFrame.
`StreamingError`	Error during data streaming.
`TableAPIError`	Base exception for all API errors.

from pymycorr import MyCorr
from pymycorr.exceptions import TableNotFoundError

client = MyCorr()

try:
    df = client.get_table("your-table-id")
except TableNotFoundError:
    print("Table not found — check the table ID and your permissions.")