Skip to main content

ktav (Python)

PyPI CI License: MIT OR Apache-2.0 Playground

Python bindings for Ktav — a plain configuration format. JSON-shape, no quotes, no commas, dotted keys. Powered by Rust under the hood.

Languages: English · Русский · 简体中文

Playground: convert JSON / YAML / TOML / INI ⇄ Ktav in your browser at ktav-lang.github.io.

Specification: this package implements Ktav. The format is versioned and maintained independently of this package — see ktav-lang/spec for the formal document.


Install

pip install ktav

Wheels are published for every major platform and every supported Python version:

  • Linux (manylinux + musllinux) — x86_64, aarch64
  • macOSx86_64, arm64 (Apple Silicon)
  • Windowsx64, arm64

Python 3.9+ is required. The wheels target the stable ABI (abi3-py39), so a single wheel per platform serves every supported CPython release.

If no prebuilt wheel matches your platform, pip falls back to the source distribution and compiles it locally — you need a Rust toolchain (rustup) and the Python development headers.

Quick start

Parse — read typed fields straight off the dict

import ktav

src = """
service: web
port: 8080
ratio: 0.75
tls: true
tags: [
    prod
    eu-west-1
]
db.host: primary.internal
db.timeout: 30
"""

cfg = ktav.loads(src)

service: str = cfg["service"]
port: int = cfg["port"]
ratio: float = cfg["ratio"]
tls: bool = cfg["tls"]
tags: list[str] = cfg["tags"]
db_host: str = cfg["db"]["host"]
db_timeout: int = cfg["db"]["timeout"]

Walk — dispatch on the runtime type

for k, v in cfg.items():
    if v is None:
        kind = "null"
    elif isinstance(v, bool):
        kind = f"bool={v}"  # bool first — True is also an int!
    elif isinstance(v, int):
        kind = f"int={v}"
    elif isinstance(v, float):
        kind = f"float={v}"
    elif isinstance(v, str):
        kind = f"str={v!r}"
    elif isinstance(v, list):
        kind = f"array({len(v)})"
    elif isinstance(v, dict):
        kind = f"object({len(v)})"
    print(f"{k} -> {kind}")

Build & render — construct a document in code

doc = {
    "name": "frontend",
    "port": 8443,
    "tls": True,
    "ratio": 0.95,
    "upstreams": [
        {"host": "a.example", "port": 1080},
        {"host": "b.example", "port": 1080},
    ],
    "notes": None,
}
text = ktav.dumps(doc)
# name: frontend
# port: 8443
# tls: true
# ratio: 0.95
# upstreams: [
#     { host: a.example  port: 1080 }
#     { host: b.example  port: 1080 }
# ]
# notes: null

A complete runnable version lives in examples/basic.py.

Four entry points mirror the standard library json module:

Function Purpose
ktav.loads(s) Parse a Ktav string (or UTF-8 bytes).
ktav.dumps(obj) Serialise a native Python value.
ktav.load(fp) Parse from a file-like object.
ktav.dump(obj, fp) Serialise to a file-like object.

load / dump accept both text-mode and binary-mode files.

For validation at trust boundaries, ktav.loads_strict(s) applies the specification's canonical-scalar rules and raises KtavDecodeError for a lossy scalar spelling. Canonical writer forms such as 1e-3 and 1e10 are accepted and produce the same native values as loads.

Type mapping

Ktav Python
null None
true / false bool
bare integer int
bare decimal float
other scalar str
[ ... ] list
{ ... } dict

Ktav types numbers by lexical form — a bare port: 8080 is an int, ratio: 0.5 a float, and anything that isn't a bare number stays a str. Force a numeric-looking value to stay a string with :: (zip:: 01007).

dict preserves insertion order (Python 3.7+ guarantee), matching the ordered-object semantics of Ktav.

Serialisation is the inverse:

  • Python int → bare integer (including arbitrary-precision bigints).
  • Python float → bare decimal (decimal point always present; NaN / ±Infinity are rejected — Ktav does not represent them).
  • Python tuple is accepted as an array, for symmetry with list.
  • Non-str keys in a dict raise KtavEncodeError.

Key escaping

Since spec 0.6.4 a literal . or : inside a key segment is written with a backslash:

a\.b: v        # key is the single segment "a.b" -> {"a.b": "v"}
a\:b: v        # key contains a colon            -> {"a:b": "v"}
x.y\.z: v      # split on the first dot only     -> {"x": {"y.z": "v"}}

A literal backslash in a key is \\.

Errors

import ktav

try:
    ktav.loads("x: [")
except ktav.KtavDecodeError as e:
    print("decode:", e)

try:
    ktav.dumps({"v": float("nan")})
except ktav.KtavEncodeError as e:
    print("encode:", e)

# Catching the base class catches either.
try:
    ktav.loads("a: 1\na: 2")
except ktav.KtavError:
    ...
Exception Raised by Base
KtavError (base) Exception
KtavDecodeError loads / load KtavError
KtavEncodeError dumps / dump KtavError

Philosophy

Ktav is intentionally small. Its five design principles (from spec/CONTRIBUTING.md):

  1. Locality — a line's meaning does not depend on another line.
  2. One sentence — any new rule fits in one sentence of the spec.
  3. No whitespace sensitivity (line breaks aside).
  4. No magic types — the format never decides "8080" means a number.
  5. Explicit over clever:: is verbose on purpose.

The Python bindings honour this: they add no schema inference, no auto-casting, no defaulting. If you want typing, you do it at the boundary with your own tool — pydantic, dataclasses, attrs — against the native Python structures this library returns.

Other Ktav implementations

  • spec — specification + conformance suite
  • rust — reference Rust crate (cargo add ktav); these Python bindings are a thin PyO3 wrapper around it
  • csharp — C# / .NET (dotnet add package Ktav)
  • golang — Go (go get github.com/ktav-lang/golang)
  • java — Java / JVM (io.github.ktav-lang:ktav on Maven Central)
  • js — JS / TS (npm install @ktav-lang/ktav)
  • php — PHP (composer require ktav-lang/ktav)

Versioning

This package follows Semantic Versioning with the pre-1.0 convention that a MINOR bump is breaking. The package version and the ktav crate version move together. ktav.__spec_version__ reports the Ktav format version this binding supports.

Development

See CONTRIBUTING.md for the dev setup, test layout, and the contribution workflow.

Support the project

The author has many ideas that could be broadly useful to IT worldwide — not limited to Ktav. Realizing them requires funding. If you'd like to help, please reach out at phpcraftdream@gmail.com.

License

MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ktav-0.6.4.tar.gz (58.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

ktav-0.6.4-cp39-abi3-win_arm64.whl (205.7 kB view details)

Uploaded CPython 3.9+Windows ARM64

ktav-0.6.4-cp39-abi3-win_amd64.whl (213.0 kB view details)

Uploaded CPython 3.9+Windows x86-64

ktav-0.6.4-cp39-abi3-musllinux_1_2_x86_64.whl (511.7 kB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ x86-64

ktav-0.6.4-cp39-abi3-musllinux_1_2_aarch64.whl (464.9 kB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ ARM64

ktav-0.6.4-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (299.5 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

ktav-0.6.4-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (285.9 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

ktav-0.6.4-cp39-abi3-macosx_11_0_arm64.whl (277.4 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

ktav-0.6.4-cp39-abi3-macosx_10_12_x86_64.whl (291.2 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file ktav-0.6.4.tar.gz.

File metadata

  • Download URL: ktav-0.6.4.tar.gz
  • Upload date:
  • Size: 58.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ktav-0.6.4.tar.gz
Algorithm Hash digest
SHA256 47a3b597ca8e31a44d82870b84ef88498f86f5ee11c9c4449034ca286c11d4c0
MD5 3a9a71b28e41cfa0642a8488461734b8
BLAKE2b-256 2f5d0561826066fa5e862d4d48cd4615cae2547328d90a0e3b41bc91adebb7d9

See more details on using hashes here.

Provenance

The following attestation bundles were made for ktav-0.6.4.tar.gz:

Publisher: release.yml on ktav-lang/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ktav-0.6.4-cp39-abi3-win_arm64.whl.

File metadata

  • Download URL: ktav-0.6.4-cp39-abi3-win_arm64.whl
  • Upload date:
  • Size: 205.7 kB
  • Tags: CPython 3.9+, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ktav-0.6.4-cp39-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 d3f5b67110f4e3c2ac452c69bbb886341a304629c41d2dcddb40433257f2c2c8
MD5 682aa5fb64e7d68f4687e9ef307a93cd
BLAKE2b-256 c02bd3b867082b6f46ec8066f99b4f3d665e7bcb0d0ad78d3d640d9f6faec3bc

See more details on using hashes here.

Provenance

The following attestation bundles were made for ktav-0.6.4-cp39-abi3-win_arm64.whl:

Publisher: release.yml on ktav-lang/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ktav-0.6.4-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: ktav-0.6.4-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 213.0 kB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ktav-0.6.4-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 ea51c06b746282e5b6817684e349434ba382335623c0f7845f62831b10db5f47
MD5 4a012addb638f0c7cffbfa67c8ba3feb
BLAKE2b-256 b9fb5e300f957d760d94ab7d91ec3e7cc697e9b4d419e8b7ba5a36e1fc029910

See more details on using hashes here.

Provenance

The following attestation bundles were made for ktav-0.6.4-cp39-abi3-win_amd64.whl:

Publisher: release.yml on ktav-lang/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ktav-0.6.4-cp39-abi3-musllinux_1_2_x86_64.whl.

File metadata

  • Download URL: ktav-0.6.4-cp39-abi3-musllinux_1_2_x86_64.whl
  • Upload date:
  • Size: 511.7 kB
  • Tags: CPython 3.9+, musllinux: musl 1.2+ x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ktav-0.6.4-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 ad7c394e57b1fcf0a6bdf1c64222fce676158c33b1f55977c9d184f8ab0c2ca3
MD5 6e5048931e5cd3c3b8c38bc4408be79c
BLAKE2b-256 42beb9750ebedcc3c0ed5958dcd7e528fdfc52cf37318d3a879ed5f0abdc6950

See more details on using hashes here.

Provenance

The following attestation bundles were made for ktav-0.6.4-cp39-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on ktav-lang/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ktav-0.6.4-cp39-abi3-musllinux_1_2_aarch64.whl.

File metadata

  • Download URL: ktav-0.6.4-cp39-abi3-musllinux_1_2_aarch64.whl
  • Upload date:
  • Size: 464.9 kB
  • Tags: CPython 3.9+, musllinux: musl 1.2+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ktav-0.6.4-cp39-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 09b42a6e1e34ded01cd8a1cf3c021efa364fde32aec83042f9ca33847cb08241
MD5 b31e647b1c3ec5360208be9660af4456
BLAKE2b-256 95b938b0a525854fa99bc7d07c0313f81311bbf0ad62097e44e811f99a3247cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for ktav-0.6.4-cp39-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on ktav-lang/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ktav-0.6.4-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for ktav-0.6.4-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b4f7a4e95566fafc02dbbcdbb8100602e07ef6e83e72d06437c802821859a59a
MD5 ff4c47c1f93a5b3a6d896fb8ae99207c
BLAKE2b-256 7202d4edc2fadd2ec9966cbb87f57bd3448d5de7992b7b19ce880e15045ad803

See more details on using hashes here.

Provenance

The following attestation bundles were made for ktav-0.6.4-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on ktav-lang/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ktav-0.6.4-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for ktav-0.6.4-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 3ddeaed168d2e63eca80d58a551b82f889279f7f4ac1cfb078c4e68c1a9b7ab1
MD5 0f61c1289cc9c806f9436aec1d3d53c2
BLAKE2b-256 7104bce06887426933bd8b295c23376fbb4200f1ba89b10ebe2705cbf804e8c7

See more details on using hashes here.

Provenance

The following attestation bundles were made for ktav-0.6.4-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on ktav-lang/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ktav-0.6.4-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

  • Download URL: ktav-0.6.4-cp39-abi3-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 277.4 kB
  • Tags: CPython 3.9+, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ktav-0.6.4-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2e8ebbccc5b8aa604da5c204e8e6bc9d8515423d77145529a77cc3128150823e
MD5 88a7e10239153dba9cd64e306bffe6bb
BLAKE2b-256 afbb3a945e9d62a5643d3450eed7304cde776f43f857940ef88269ce0f706f79

See more details on using hashes here.

Provenance

The following attestation bundles were made for ktav-0.6.4-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on ktav-lang/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ktav-0.6.4-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

  • Download URL: ktav-0.6.4-cp39-abi3-macosx_10_12_x86_64.whl
  • Upload date:
  • Size: 291.2 kB
  • Tags: CPython 3.9+, macOS 10.12+ x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ktav-0.6.4-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 54ba4d98ffee41e98a5c83691fe7c2ba62a8fcdd7ce4a8decf363eeaf74299ae
MD5 a62c92bc8087d986e8fa4db3eee5ac3f
BLAKE2b-256 685793bf7e2c004633b957988fb127199702cfb9992c3dfde7019a05ea434f66

See more details on using hashes here.

Provenance

The following attestation bundles were made for ktav-0.6.4-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on ktav-lang/python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.6.4 This release

9 files

0.6.1

9 files

0.6.0

9 files

0.5.0

9 files

0.3.1

9 files

0.3.0

9 files

0.2.0

9 files

0.1.2

9 files

0.1.1

9 files

0.1.0

9 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page