jmd-format — Python Reference Implementation

Python reference implementation of the JMD specification (v0.3.5). Includes a C-accelerated parser and serializer, plus lossless XML↔JMD conversion.

Installation

Install the latest version directly from GitHub:

pip install git+https://github.com/ostermeyer/jmd-impl.git

Or pin a specific release:

pip install git+https://github.com/ostermeyer/jmd-impl.git@v0.9.1

Pre-built wheels for Linux, macOS, and Windows are attached to each GitHub Release and can be installed directly:

pip install https://github.com/ostermeyer/jmd-impl/releases/download/v0.9.1/jmd_format-0.9.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

The C extensions are built automatically during installation if a C compiler is available. If not, the pure-Python fallback is used transparently.

Quick Start

from jmd import parse, serialize

data = parse("""
# Order
id: 42
status: pending

## customer
name: Anna Müller
email: anna@example.com
""")

print(data)
# {'id': 42, 'status': 'pending', 'customer': {'name': 'Anna Müller', 'email': 'anna@example.com'}}

print(serialize(data, label="Order"))

Document Modes

from jmd import (
    JMDDeleteParser,
    JMDParser,
    JMDQueryParser,
    JMDSchemaParser,
    jmd_mode,
    parse_error,
)

# Detect mode without full parse
mode = jmd_mode(source)   # 'data' | 'query' | 'schema' | 'delete'

# Query by Example (#?)
query = JMDQueryParser().parse("#? Order\nstatus: pending")

# Schema (#!) — canonical structural parser; values remain raw strings
schema = JMDParser().parse("#! Order\nid: integer readonly\nstatus: string")

# Optional legacy type-expression dialect
typed_schema = JMDSchemaParser().parse(
    "#! Order\nid: integer readonly\nstatus: string"
)

# Delete (#-)
delete = JMDDeleteParser().parse("#- Order\nid: 42")

# Error (# Error)
error = parse_error("# Error\nstatus: 404\ncode: not_found\nmessage: Not found")

Streaming

Use jmd_stream() when the complete source is already available:

from jmd import jmd_stream

for event in jmd_stream(source):
    print(event)

For incremental input, consume the events returned by every process_line() call. finish() emits only events still pending at end of input:

from jmd import JMDStreamParser

parser = JMDStreamParser()
for line in source_lines:
    for event in parser.process_line(line):
        print(event)
for event in parser.finish():
    print(event)

Canonical multiline fields emit FIELD_START followed by one FIELD_CONTENT event per blockquote line. The stream_events() and to_lines() async adapters preserve the same incremental behavior.

XML Mapping

Lossless conversion between data XML and JMD (requires lxml):

from jmd.xml import xml_to_jmd, jmd_to_xml

jmd_source = xml_to_jmd(xml_bytes_or_str)  # XML → JMD string
xml_output  = jmd_to_xml(jmd_source)        # JMD → XML bytes

Targets data XML — OOXML (WordprocessingML, DrawingML, SpreadsheetML), SOAP, XBRL, XRechnung, and similar formats. Mixed-content XML (ODF, XHTML) is out of scope.

See the JMD over XML companion specification for the full mapping rules.

C Extensions

Build manually if needed:

python build_ext.py build_ext --inplace

Specification

See jmd-spec for the full format specification, benchmark results, and design documentation.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

The JMD format specification is licensed separately under CC BY 4.0.