Metadata-Version: 2.4
Name: pymycorr
Version: 0.2.0
Summary: Python client for fetching table data from the MyCorr API via Apache Arrow
Project-URL: Homepage, https://github.com/recons-ltd/pymycorr
Project-URL: Documentation, https://github.com/recons-ltd/pymycorr#readme
Project-URL: Repository, https://github.com/recons-ltd/pymycorr
Project-URL: Issues, https://github.com/recons-ltd/pymycorr/issues
Project-URL: Changelog, https://github.com/recons-ltd/pymycorr/blob/main/CHANGELOG.md
Author-email: Maximilian Schuberth <maxs@recons-ltd.com>
License: MIT
License-File: LICENSE
Keywords: api-client,arrow,dataframe,mycorr,pandas,polars
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: all
Requires-Dist: nest-asyncio>=1.5.0; extra == 'all'
Requires-Dist: polars>=0.20.0; extra == 'all'
Provides-Extra: jupyter
Requires-Dist: nest-asyncio>=1.5.0; extra == 'jupyter'
Provides-Extra: polars
Requires-Dist: polars>=0.20.0; extra == 'polars'
Description-Content-Type: text/markdown

# pymycorr

[![PyPI version](https://img.shields.io/pypi/v/pymycorr)](https://pypi.org/project/pymycorr/)
[![CI](https://img.shields.io/github/actions/workflow/status/sambaclab/mycorr-python/ci.yml?branch=main&label=CI)](https://github.com/sambaclab/mycorr-python/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue)](https://github.com/sambaclab/mycorr-python/blob/main/pyproject.toml)
[![License](https://img.shields.io/github/license/sambaclab/mycorr-python)](https://github.com/sambaclab/mycorr-python/blob/main/LICENSE)

Python client for fetching table data from the [MyCorr](https://alpha.mycorr.app) API using Apache Arrow for efficient data transfer.

> **Note:** The production API is coming soon. Set `MYCORR_API_URL` to your endpoint if you have early access.

## Installation

```bash
pip install pymycorr
```

## Configuration

Set your API token and (optionally) the API URL as environment variables:

```bash
export MYCORR_API_TOKEN="your-api-token"
```

Or create a `.env` file in your project root:

```
MYCORR_API_TOKEN=your-api-token
```

The client automatically loads from environment variables and `.env` files.

## Quick Start

```python
from pymycorr import MyCorr

# Initialize client (loads token from MYCORR_API_TOKEN env var or .env file)
client = MyCorr()

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

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

# Fetch using version alias
df = client.get_table("table-id", version="stable")

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

### Progress Display

Progress is shown automatically in interactive environments (terminals and notebooks). You can control this behavior:

```python
# Always show progress
client = MyCorr(progress=True)

# Never show progress
client = MyCorr(progress=False)

# Override per-request
df = client.get_table("table-id", progress=False)
```

## API Reference

### MyCorr

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

Initialize the client.

- `url`: API base URL (optional). Falls back to `MYCORR_API_URL` env var, then default.
- `token`: Authentication token (Bearer token from MyCorr UI). Falls back to `MYCORR_API_TOKEN` env var or `.env` file.
- `env_file`: Path to custom `.env` file (optional).
- `progress`: Show download progress. `True` always shows, `False` never shows, `"auto"` (default) shows in interactive environments.

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

Fetch table data as a DataFrame.

- `table_id`: Unique identifier for the table.
- `version`: Version number (int) or alias (str like `"latest"`, `"stable"`).
- `engine`: `"pandas"` (default) or `"polars"`.
- `progress`: Override client's progress setting for this request.
- Returns: pandas or polars DataFrame.

#### `get_table_info(table_id, version=None)`

Get table schema and metadata.

- `table_id`: Unique identifier for the table.
- `version`: Version number (int) or alias (str).
- Returns: Dictionary with table metadata including schema.

## Exceptions

- `TableAPIError`: Base exception for API errors.
- `TableNotFoundError`: Table not found (404).
- `QuotaExceededError`: Egress quota exceeded (429).
- `TableConversionError`: Failed to convert Arrow data to DataFrame.
- `StreamingError`: Error during data streaming or IPC parsing.

## Development

See [.env.example](.env.example) for environment variable configuration. For local development:

1. Copy `.env.example` to `.env`
2. Set `MYCORR_API_URL` to your local/dev base URL (no path segments)
3. SSL verification is automatically disabled for `localhost` and `127.0.0.1` URLs

## License

MIT License - see [LICENSE](LICENSE) for details.
