jots-py

Pure-Python parser for Jot Syntax.

The normative specification lives at jotsyntax.org. This package is a from-scratch Python implementation of the spec — no Rust, no FFI, no compiled extension. For a faster parser backed by the Rust implementation (jots-rs), see the sibling PyO3 bindings (jots-rs-py); both expose the same jots.parse() API.

Install

pip install jots

Usage

import jots

result = jots.parse("..meeting ::work::q2 ??buy milk")
# {
#   "tags": ["meeting"],
#   "categories": ["work::q2"],
#   "todos": [{"importance": 0, "action": "buy", "description": "milk", ...}],
#   "diagnostics": [],
#   ...
# }

Optional config flags (see SPEC §2.2) are passed via the config keyword:

jots.parse(text, config={"parse_hashtags_as_tags": True, "emit_loc": False})

category_root (SPEC §9.1) requires every category path to start with the given segment; a path that does not — ::title when the root is cat — is ordinary text, free-standing or as an annotation suffix. Rooted paths are emitted unchanged, root included:

jots.parse("::cat::dh ::title --42::title", config={"category_root": "cat"})
# categories == ["cat::dh"]; references[0]["category"] is None

Iota Syntaxis (Unicode variant)

The Iota Syntaxis variant widens the identifier and filename character classes to Unicode XID_Start/XID_Continue: jots.parse(text, unicode=True). The sibling iotas distribution in this repo wraps jots with the variant preset.

Status

Tracks Jot Syntax 1.0 RC1 (2026-03-18). Current scope is the parser only (Part II of the spec); the processor (Part III) will live in a future jotr-py repo.

Conformance is verified against the shared vector suite in jots-tests — the same suite used by jots-rs and jots-rs-py.