Metadata-Version: 2.1
Name: kanidm
Version: 1.2.0
Summary: Kanidm client library
Keywords: kanidm,idm,api
Author-Email: James Hodgkinson <james@terminaloutcomes.com>
License: MPL-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Project-URL: homepage, https://kanidm.com/
Project-URL: repository, https://github.com/kanidm/kanidm
Requires-Python: <4.0,>=3.12
Requires-Dist: toml>=0.10.2
Requires-Dist: pydantic>=2.12.5
Requires-Dist: aiohttp>=3.8.1
Requires-Dist: Authlib>=1.2.0
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: aiohttp-retry>=2.9.1
Requires-Dist: typing-extensions>=4.15.0
Provides-Extra: openapi-codegen
Requires-Dist: docker>=7.1.0; extra == "openapi-codegen"
Description-Content-Type: text/markdown

# 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/choose) 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 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"),
    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                 |
