# Kanidm

A Python module for interacting with Kanidm.

Currently in very very very early beta, please [log an issue](https://github.com/kanidm/kanidm/issues/new) for
feature requests and bugs.

## Installation

```bash
python -m pip install kanidm
```

## Documentation

Documentation can be generated by [cloning the repository](https://github.com/kanidm/kanidm) and running
`make docs/pykanidm/build`. The documentation will appear in `./pykanidm/site`. You'll need make and the
[uv](https://pypi.org/project/uv/) package installed.

## Testing

Set up your dev environment using `uv` - `python -m pip install uv && uv sync`.

Pytest it used for testing, if you don't have a live server to test against and config set up, use
`uv run pytest -m 'not network'`.

### OpenAPI client generation

The OpenAPI spec is served by the running Kanidm server. To generate/update the OpenAPI-based client package:

```bash
uv run kanidm_openapi_codegen
```

You can also point it at a local spec file or override the URL:

```bash
uv run kanidm_openapi_codegen --spec-file /path/to/openapi.json
uv run kanidm_openapi_codegen --spec-url https://localhost:8443/docs/v1/openapi.json
```

Programmatic code generation lives in `kanidm.openapi_codegen`, which is behind the optional feature `openapi_codegen`:

```bash
python -m pip install "kanidm[openapi_codegen]"
```

Programmatic use is also supported:

```python
from pathlib import Path
from kanidm.openapi_codegen import generate_openapi_client

generate_openapi_client(
    spec_url="https://localhost:8443/docs/v1/openapi.json",
    verify_tls=True,
    ca_file=Path("/tmp/kanidm/ca.pem"),
    # season to taste
    output=Path("pykanidm/kanidm_openapi_client"), 
)
```

The generated client is packaged as `kanidm_openapi_client`.

`KanidmClient` now initializes an OpenAPI client by default at startup as `client.openapi_client`:

```python
from kanidm import KanidmClient

client = KanidmClient(uri="https://localhost:8443")
openapi_client = client.openapi_client
```

You can still build one explicitly from config helpers in `kanidm.openapi` if needed.

#### OpenAPI structure

- `kanidm_openapi_client/` contains the generated OpenAPI client (API classes, models, and transport).
- `kanidm/openapi.py` provides helpers to build an OpenAPI `ApiClient` from a `KanidmClient`/`KanidmClientConfig`.
- The generated package is included in the build via `tool.pdm.build.includes`.

### OpenAPI spec tests

Networked OpenAPI tests are marked `openapi` and include both spec validation and generated-client GET calls. Run them
with:

```bash
IDM_ADMIN_PASS=... uv run pytest -m openapi
```

OpenAPI tests regenerate `kanidm_openapi_client` once per pytest session before running marked tests. This uses
`kanidm.openapi_codegen` and requires Docker to be available.

Optional environment overrides:

- `KANIDM_CA_PATH` (default: `/tmp/kanidm/ca.pem` if present)
- `KANIDM_OPENAPI_URL` (default: `https://localhost:8443`)
- `IDM_ADMIN_PASS` (required for auth'd OpenAPI tests; matches `scripts/setup_dev_environment.sh`)
- `KANIDM_INSECURE` (`true`/`false`, default: `false`) disables TLS verification for tests

Note: tests always verify TLS unless `KANIDM_INSECURE=true`. Provide a CA via `KANIDM_CA_PATH` (or use the default
`/tmp/kanidm/ca.pem`) so the server cert validates.

## Changelog

| Version | Date       | Notes                                                               |
| ------- | ---------- | ------------------------------------------------------------------- |
| 0.0.1   | 2022-08-16 | Initial release                                                     |
| 0.0.2   | 2022-08-16 | Updated license, including test code in package                     |
| 0.0.3   | 2022-08-17 | Updated test suite to allow skipping of network tests               |
| 1.2.0   | 2025-05-13 | Replaced poetry with uv for packaging                               |
| 1.3.0   | 2026-02-19 | Major rewrite to use openapi-generated codebase, based on 1.9.0 API |
