Installation

Requirements

• Python 3.10 or newer (the wheels are built against the stable ABI, abi3).

• For the PKCS#11/HSM signing path at runtime: a PKCS#11 module (for example SoftHSM2 or kryoptic). The module is loaded with dlopen at runtime, so it is not needed to install or import pygamlastan, only to use a token.

From a wheel

uv pip install pygamlastan

Prebuilt manylinux, macOS, and Windows wheels include the compiled extension and PEP 561 type information, so no Rust toolchain is required.

Tip

HSM / PKCS#11 deployments

If you will use the PKCS#11/HSM signing path in production, prefer building the wheel in - or against - your target environment rather than relying on the generic prebuilt wheel. The compiled extension links the host C and crypto stack, and your PKCS#11 module is loaded at runtime from that same host; building where the token tooling and system libraries live (maturin build --release on the target host, or a container matching production) avoids glibc/loader and provider-ABI mismatches and lets you validate signing against the real module before shipping. See Signing, verification, and encryption.

From source

Building from source needs a Rust toolchain (1.75+) and maturin. The project uses uv:

uv venv
uv pip install --python .venv/bin/python maturin
VIRTUAL_ENV=$PWD/.venv .venv/bin/maturin develop --uv
.venv/bin/python -m pytest

Type checking

The package ships py.typed and a .pyi stub per submodule, so mypy and pyright pick up types automatically with no extra configuration:

from pygamlastan import core
nid = core.NameId("alice", format=core.NAMEID_TRANSIENT)
reveal_type(nid.value)  # str