Metadata-Version: 2.3
Name: ineepy
Version: 0.3.1
Summary: A Python client library for the [ineep](https://codeberg.org/cmts/ineep) lakehouse API.
Author: cmts
Author-email: cmts <cmts@noreply.codeberg.org>
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pydantic-settings>=2.14.1
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# ineepy

[![status-badge](https://woodpecker-ineep.exe.xyz:8000/api/badges/4/status.svg)](https://woodpecker-ineep.exe.xyz:8000/repos/4)

A Python client library for the [ineep](https://codeberg.org/cmts/ineep) lakehouse API.

## Links

- **Repository:** [codeberg.org/Ineep/ineepy](https://codeberg.org/Ineep/ineepy)
- **Documentation:** [ineep.codeberg.page/ineepy/](https://ineep.codeberg.page/ineepy/)
- **Changelog:** [CHANGELOG.md](CHANGELOG.md)

## Requirements

- Python 3.14+
- [`uv`](https://docs.astral.sh/uv/)

## Installation

```bash
uv add ineepy
```

Or for development:

```bash
git clone https://codeberg.org/Ineep/ineepy
cd ineepy
uv sync
```

## Usage

### Authentication

Obtain a JWT token before creating a client:

```python
from ineepy import get_token, async_get_token

# Synchronous
token = get_token(email='user@example.com', password='secret')

# Async
token = await async_get_token(email='user@example.com', password='secret')
```

The `scope` parameter defaults to `'user'`. Use `'admin'` for administrative operations.

### Synchronous client

```python
from ineepy import Ineepy, get_token

token = get_token(email='user@example.com', password='secret')

with Ineepy(token=token) as client:
    user, etag = client.users.me()
    namespaces = client.namespaces.list()
    tables = client.tables.list(namespace_id='my-namespace')
```

### Async client

```python
from ineepy import AsyncIneepy, async_get_token

token = await async_get_token(email='user@example.com', password='secret')

async with AsyncIneepy(token=token) as client:
    user, etag = await client.users.me()
    namespaces = await client.namespaces.list()
```

### Configuration

The base URL defaults to `http://localhost:8000` and can be overridden via environment variable or constructor argument:

```bash
export INEEPY_BASE_URL=https://my-server.example.com
export INEEPY_API_VERSION=v0   # default
```

```python
client = Ineepy(base_url='https://my-server.example.com', token=token)
```

### Resources

| Resource | Access | Description |
|---|---|---|
| `users` | `client.users` | User management (list, get, create, update, delete) |
| `api_keys` | `client.api_keys` | API key management (create, list, revoke) |
| `namespaces` | `client.namespaces` | Namespace management (list, create, update, delete); `list()` with no arg returns root namespaces |
| `tables` | `client.tables` | Table schema management within namespaces |
| `data` | `client.data` | Upload, query, and explicit write modes: `append`, `overwrite`, `upsert` |

## Development

```bash
make format   # format code
make lint     # lint code
make test     # run unit tests with coverage
make test-e2e # run end-to-end tests against a live server
```

### E2E tests

E2E tests require a running ineep server and admin credentials:

```bash
cp .env.example .env
# edit .env with your credentials
make test-e2e
```

The `.env` file is gitignored. See `.env.example` for the available variables.

## Project structure

```
src/ineepy/          Main package
  _auth.py           Token acquisition (sync + async)
  _client.py         Ineepy and AsyncIneepy clients
  _config.py         Pydantic settings (env vars)
  _exceptions.py     Exception hierarchy
  _models.py         Pydantic response models
  exceptions.py      Public exceptions re-export
  helpers.py         Public helper utilities
  models.py          Public models re-export
  _resources/        Per-resource implementations
    api_keys.py
    data.py
    namespaces.py
    tables.py
    users.py
tests/
  resources/         Unit tests per resource
  e2e/               End-to-end workflow tests
scripts/             Shell scripts called by make
pyproject.toml       Project metadata and tool config
```

## License

This project is licensed under the GNU General Public License v3.0.

You are free to use, modify, and distribute this software under the terms of the GPL v3. Any derivative work must also be distributed under the same license. See the LICENSE file for the full license text.
