Metadata-Version: 2.5
Name: loams
Version: 0.1.0a2
Summary: The Loams SDK for Python: one Loams object with namespaced modules over the unified Connect API, generated from proto/.
Project-URL: Homepage, https://loams.dev
Project-URL: Repository, https://github.com/ostrium-labs/loams
Project-URL: Issues, https://github.com/ostrium-labs/loams/issues
Project-URL: SDK plan, https://github.com/ostrium-labs/loams/blob/dev/docs/plans/2026-10-02-sdk2-languages.md
Author: Ostrium Labs
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: connect,database,grpc,loams,sdk,vector
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: connectrpc==0.12.1
Requires-Dist: protobuf==7.36.2
Provides-Extra: arrow
Requires-Dist: pyarrow>=17.0.0; extra == 'arrow'
Provides-Extra: flight
Requires-Dist: adbc-driver-flightsql>=1.0.0; extra == 'flight'
Provides-Extra: polars
Requires-Dist: polars>=1.0.0; extra == 'polars'
Description-Content-Type: text/markdown

![Loams — Your data. Your bucket.](https://raw.githubusercontent.com/ostrium-labs/loams/dev/docs/assets/loams-banner.svg)

# Loams SDK for Python

> **Preview.** `0.1.0a*` releases track the Loams preview server and may change
> between previews. pip skips prereleases unless asked: `pip install --pre loams`,
> or pin the exact version (`loams==0.1.0a2`).

One `Loams` object over one Loams instance, speaking the unified Connect API.
The module surface is generated from `proto/` by `scripts/sdk/gen.sh python`;
the runtime below it is hand-written and obeys the contract in
[`docs/sdk/runtime-contract.md`](https://github.com/ostrium-labs/loams/blob/dev/docs/sdk/runtime-contract.md).

## Install

```
pip install loams
```

Not on PyPI yet. The distribution name is reserved but publishing is blocked
until registry ownership is confirmed (D400), so for now install from a
checkout:

```
uv sync --all-extras --dev     # from sdks/python
```

The runtime dependency is [`connectrpc`](https://pypi.org/project/connectrpc/)
0.12.1 (connectrpc/connect-py), pinned in `scripts/sdk/pins.lock`. Up to 0.9.0
the same project was published as `connect-python`; the import name has always
been `connectrpc`.

## Use

```python
from loams import Loams

loams = Loams("https://acme.loams.dev", api_key="...")
print(loams.instance.version())
```

Four modules hang off the client: `loams.instance` (what this instance is),
`loams.live` (the live-sync session half, whose package is `unstable`),
`loams.tables` (the table half of the same service), and `loams.system` (the
module catalogue, feature detection and the version check).

### Auth

Pass `api_key` for a script or CI job that holds one — it does not expire, so
there is nothing to refresh. Pass `auth` for everything else: `env_token()`,
`oidc_exchange()`, or your own `TokenSource`. The two are mutually exclusive
because they answer the same question, and passing both raises.

### Protocol and encoding

`protocol` is `"connect"` (default), `"grpc"` or `"grpc-web"` — the one port
speaks all three; this picks which one this client uses. `proto_json=True`
sends the proto3 JSON mapping that `curl` sends; the default is protobuf,
which is smaller.

### Consistency

`session_consistency=False` by default: every read is then `STRONG` on its own,
which is correct but does not give read-your-writes across processes. Turn it
on (D609) to hold a session consistency token across calls.

## What is not here yet

These are refused by name rather than stubbed, so a caller finds out at the
call instead of at runtime:

- **The hybrid query builder.** Blocked on API1 Task 2. There is no
  hand-written builder here; when the proto lands, the generator emits one.
- **Bulk ingest and bulk results.** Blocked on API1 Tasks 3 and 4. They go over
  Arrow Flight SQL through ADBC, which is why the `flight`, `arrow` and
  `polars` extras already exist — the code that uses them lands with the write
  RPCs.
- **`listAll` per call.** Blocked on the same API1 tasks; paging is explicit.

## Development

```
uv sync --all-extras --dev
uv run pytest -q
uv run mypy --strict src
./scripts/sdk/gen.sh python    # regenerate the facade from proto/
```

Generated code is never hand-edited: CI regenerates and fails on a diff, so a
proto change shows up as a dependency bump rather than a silent drift.
