ineepy 0.1.0__tar.gz

ineepy-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.3
+Name: ineepy
+Version: 0.1.0
+Summary: Add your description here
+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
+
+- [Documentation](https://ineep.codeberg.page/ineepy/)
+- [Repository](https://codeberg.org/Ineep/ineepy)
+- [Changelog](./CHANGELOG.md)
+
+## Requirements
+
+- Python 3.14+
+- [`uv`](https://docs.astral.sh/uv/)
+
+## Installation
+
+```bash
+uv add ineepy
+```
+
+Or for development:
+
+```bash
+git clone <repo-url>
+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=v1   # 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, deactivate) |
+| `api_keys` | `client.api_keys` | API key management (create, list, revoke) |
+| `namespaces` | `client.namespaces` | Namespace management (list, get, create, update, delete) |
+| `tables` | `client.tables` | Table schema management within namespaces |
+| `data` | `client.data` | Data upload, download, update, query, and job polling |
+
+## 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
+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.

ineepy-0.1.0/README.md

@@ -0,0 +1,139 @@
+# 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
+
+- [Documentation](https://ineep.codeberg.page/ineepy/)
+- [Repository](https://codeberg.org/Ineep/ineepy)
+- [Changelog](./CHANGELOG.md)
+
+## Requirements
+
+- Python 3.14+
+- [`uv`](https://docs.astral.sh/uv/)
+
+## Installation
+
+```bash
+uv add ineepy
+```
+
+Or for development:
+
+```bash
+git clone <repo-url>
+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=v1   # 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, deactivate) |
+| `api_keys` | `client.api_keys` | API key management (create, list, revoke) |
+| `namespaces` | `client.namespaces` | Namespace management (list, get, create, update, delete) |
+| `tables` | `client.tables` | Table schema management within namespaces |
+| `data` | `client.data` | Data upload, download, update, query, and job polling |
+
+## 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
+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.

ineepy-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "ineepy"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "cmts", email = "cmts@noreply.codeberg.org" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.4",
+    "pydantic-settings>=2.14.1",
+]
+
+[project.scripts]
+ineepy = "ineepy:main"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "marimo>=0.23.6",
+    "mkdocstrings-python>=2.0.3",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "pytest-httpx>=0.36.2",
+    "ruff>=0.15.5",
+    "zensical>=0.0.42",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ['.']
+asyncio_mode = 'auto'
+markers = [
+    "e2e: end-to-end tests requiring a live server (exclude with -m 'not e2e')",
+]
+
+[tool.coverage.run]
+source = ['ineepy']
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+
+[tool.ruff]
+line-length = 79
+src = ["src"]
+extend-exclude = ["tests"]
+
+[tool.ruff.lint]
+preview = true
+select = ["F", "E", "W", "N", "PL", "PT", "I001"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "E501",       # long decorative comment lines in test files
+    "F401",       # unused imports (test fixtures may import for re-export)
+    "PLC0415",    # imports inside test functions (inline json imports)
+    "PLC1901",    # empty string comparisons in assertions
+    "PLC2701",    # private module imports (expected in tests)
+    "PLR0913",    # too many args (test helper signatures)
+    "PLR0917",    # too many positional args in test calls
+    "PLR2004",    # magic values in assertions
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["ineepy"]
+force-sort-within-sections = true
+
+[tool.ruff.format]
+preview = true
+quote-style = "single"

ineepy-0.1.0/src/ineepy/__init__.py

@@ -0,0 +1,4 @@
+from ineepy._auth import async_get_token, get_token
+from ineepy._client import AsyncIneepy, Ineepy
+
+__all__ = ['Ineepy', 'AsyncIneepy', 'get_token', 'async_get_token']

ineepy-0.1.0/src/ineepy/_auth.py

@@ -0,0 +1,143 @@
+"""JWT auth: acquire and persist scoped access tokens via get_token()."""
+
+from collections.abc import Sequence
+from json import JSONDecodeError
+from pathlib import Path
+
+import httpx
+
+from ineepy._config import CONFIG_FILENAME, load_settings, write_config
+from ineepy._exceptions import ForbiddenError, ValidationError
+
+_AUTH_MAP: dict[int, type[ValidationError | ForbiddenError]] = {
+    400: ValidationError,
+    401: ValidationError,
+    403: ForbiddenError,
+    422: ValidationError,
+}
+
+
+def _raise_auth(response: httpx.Response) -> None:
+    if response.is_error:
+        exc_class = _AUTH_MAP.get(response.status_code, ValidationError)
+        try:
+            detail = response.json().get('detail', '')
+        except Exception:
+            detail = ''
+        raise exc_class(response.status_code, detail)
+
+
+def get_token(  # noqa: PLR0913
+    email: str,
+    password: str,
+    scopes: Sequence[str] = ['user'],
+    *,
+    base_url: str | None = None,
+    api_path: str | None = None,
+    config_file: Path | None = None,
+    save_token: bool = True,
+) -> str | None:
+    """Obtain a JWT access token via email/password credentials.
+
+    Configuration is resolved from three sources in priority order
+    (highest to lowest): code-level arguments → ``ineepy.toml`` in the
+    current directory → ``INEEPY_*`` environment variables.
+
+    Args:
+        email: User email address.
+        password: User password.
+        scopes: Requested scopes. Defaults to ``['user']``.
+        base_url: API base URL. Defaults to config/env ``INEEPY_BASE_URL``
+            (default ``https://ineep-lakehouse-prod.exe.xyz``).
+        api_path: API path prefix. Defaults to config/env ``INEEPY_API_PATH``
+            (default ``/api/v0``).
+        config_file: Path to the TOML config file. Defaults to
+            ``ineepy.toml`` in the current working directory.
+        save_token: When ``True`` (default), writes ``base_url``,
+            ``api_path``, and ``token`` to the config file and returns
+            ``None``. When ``False``, skips writing and returns the token
+            string.
+
+    Returns:
+        ``None`` when saved to config (``save_token=True``);
+            the ``access_token`` string otherwise.
+
+    """
+    cfg_path = config_file or Path.cwd() / CONFIG_FILENAME
+    s = load_settings(cfg_path)
+    eff_base_url = base_url or s.base_url
+    eff_api_path = api_path or s.api_path
+    url = f'{eff_base_url}{eff_api_path}/auth/token'
+    _scopes = scopes if scopes is not None else ['user']
+    data = {
+        'username': email,
+        'password': password,
+        'scope': ' '.join(_scopes),
+    }
+    with httpx.Client() as client:
+        response = client.post(url, data=data)
+    _raise_auth(response)
+    try:
+        token = response.json()['access_token']
+    except JSONDecodeError, KeyError:
+        raise ValidationError(
+            response.status_code, 'Failed to extract access token'
+        )
+    if save_token:
+        write_config(
+            cfg_path,
+            {
+                'base_url': eff_base_url,
+                'api_path': eff_api_path,
+                'token': token,
+            },
+        )
+        return None
+    return token
+
+
+async def async_get_token(  # noqa: PLR0913
+    email: str,
+    password: str,
+    scopes: Sequence[str] = ['user'],
+    *,
+    base_url: str | None = None,
+    api_path: str | None = None,
+    config_file: Path | None = None,
+    save_token: bool = True,
+) -> str | None:
+    """Async version of :func:`get_token`."""
+    cfg_path = config_file or Path.cwd() / CONFIG_FILENAME
+    s = load_settings(cfg_path)
+    eff_base_url = base_url or s.base_url
+    eff_api_path = api_path or s.api_path
+    url = f'{eff_base_url}{eff_api_path}/auth/token'
+    _scopes = scopes if scopes is not None else ['user']
+    data = {
+        'username': email,
+        'password': password,
+        'scope': ' '.join(_scopes),
+    }
+    async with httpx.AsyncClient() as client:
+        response = await client.post(url, data=data)
+    _raise_auth(response)
+    try:
+        token = response.json()['access_token']
+    except JSONDecodeError, KeyError:
+        raise ValidationError(
+            response.status_code, 'Failed to extract access token'
+        )
+    if save_token:
+        write_config(
+            cfg_path,
+            {
+                'base_url': eff_base_url,
+                'api_path': eff_api_path,
+                'token': token,
+            },
+        )
+        return None
+    return token
+
+
+async_get_token.__doc__ = get_token.__doc__

ineepy-0.1.0/src/ineepy/_client.py

@@ -0,0 +1,143 @@
+"""Sync and async client (Ineepy, AsyncIneepy) for the ineep lakehouse."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import TracebackType
+
+import httpx
+
+from ineepy._config import CONFIG_FILENAME, load_settings
+from ineepy._resources.api_keys import APIKeysResource, AsyncAPIKeysResource
+from ineepy._resources.data import AsyncDataResource, DataResource
+from ineepy._resources.namespaces import (
+    AsyncNamespacesResource,
+    NamespacesResource,
+)
+from ineepy._resources.tables import AsyncTablesResource, TablesResource
+from ineepy._resources.users import AsyncUsersResource, UsersResource
+
+
+class Ineepy:
+    """Synchronous client for the **ineep lakehouse API**.
+
+    Configuration is resolved from three sources in priority order
+    (highest to lowest): code-level arguments → ``ineepy.toml`` in the
+    current directory → ``INEEPY_*`` environment variables.
+
+    Can be used as a context manager (preferred) or manually closed.
+
+    Args:
+        token: Bearer token. Defaults to config/env ``INEEPY_TOKEN``.
+            Obtain one with :func:`~ineepy.get_token`.
+        base_url: API base URL. Defaults to config/env ``INEEPY_BASE_URL``
+            (default ``https://ineep-lakehouse-prod.exe.xyz``).
+        api_path: API path prefix. Defaults to config/env ``INEEPY_API_PATH``
+            (default ``/api/v0``).
+        config_file: Path to the TOML config file. Defaults to
+            ``ineepy.toml`` in the current working directory.
+
+    Example::
+
+        # After calling get_token(...) once, the token is saved to
+        # ineepy.toml and the client loads it automatically:
+        with Ineepy() as client:
+            user, etag = client.users.get('me')
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str | None = None,
+        api_path: str | None = None,
+        config_file: Path | None = None,
+        _skip_health_check: bool = False,
+    ) -> None:
+        s = load_settings(config_file or Path.cwd() / CONFIG_FILENAME)
+        _base = (base_url or s.base_url).rstrip('/')
+        _path = (api_path or s.api_path).rstrip('/')
+        self._health_url = f'{_base}/health'
+        self._http = httpx.Client(
+            base_url=f'{_base}{_path}/',
+            headers={'Authorization': f'Bearer {token or s.token}'},
+        )
+        self.users = UsersResource(self._http)
+        self.api_keys = APIKeysResource(self._http)
+        self.namespaces = NamespacesResource(self._http)
+        self.tables = TablesResource(self._http)
+        self.data = DataResource(self._http)
+        if not _skip_health_check:
+            self._check_health()
+
+    def _check_health(self) -> None:
+        r = self._http.get(self._health_url)
+        r.raise_for_status()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> Ineepy:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncIneepy:
+    """Async version of :class:`~ineepy.Ineepy`."""
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str | None = None,
+        api_path: str | None = None,
+        config_file: Path | None = None,
+        _skip_health_check: bool = False,
+    ) -> None:
+        s = load_settings(config_file or Path.cwd() / CONFIG_FILENAME)
+        _base = (base_url or s.base_url).rstrip('/')
+        _path = (api_path or s.api_path).rstrip('/')
+        self._health_url = f'{_base}/health'
+        self._http = httpx.AsyncClient(
+            base_url=f'{_base}{_path}/',
+            headers={'Authorization': f'Bearer {token or s.token}'},
+        )
+        self.users = AsyncUsersResource(self._http)
+        self.api_keys = AsyncAPIKeysResource(self._http)
+        self.namespaces = AsyncNamespacesResource(self._http)
+        self.tables = AsyncTablesResource(self._http)
+        self.data = AsyncDataResource(self._http)
+        self._skip_health_check = _skip_health_check
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP client."""
+        await self._http.aclose()
+
+    async def _acheck_health(self) -> None:
+        r = await self._http.get(self._health_url)
+        r.raise_for_status()
+
+    async def __aenter__(self) -> AsyncIneepy:
+        if not self._skip_health_check:
+            await self._acheck_health()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+
+AsyncIneepy.__doc__ = Ineepy.__doc__
+AsyncIneepy.aclose.__doc__ = Ineepy.close.__doc__