Python API

The supported public entry points are exported from hamen_markup. Python 3.12+ is required.

from hamen_markup import MarkupError, compile_file, compile_source

result = compile_source(
    '# A [[circled]] heading\n\n:::box Key point\n==Remember this.==\n:::',
    root='.',
    filename='example.hmn',
    notes=True,
)
result.write('output/example.html')

try:
    result = compile_file('example.hmn', root='.')
except MarkupError as error:
    print(error.diagnostic.to_dict())

Compilation

compile_source(source: str, *, root='.', filename='<string>', target='web', profile='', debug=False, notes=None) -> Compilation

compile_file(source: str | Path, *, root=None, target='web', profile='', debug=False, notes=None) -> Compilation

• root confines imported documents and assets. compile_file defaults to the source's parent. Pass a broader root explicitly for a multi-file project.
• filename provides source locations and determines automatic notes mode. Set it to a real source path when relative resources should resolve beside that file.
• notes=None detects .hmn and @Notes(). True forces notes mode; False forces strict syntax.
• target accepts web or pdf. PDF compilation validates static fallbacks.
• profile selects a declared profile. debug enables diagnostic document content.
• Compilation.diagnostics contains nonfatal diagnostics. Invalid source raises MarkupError.
• Compilation.write(output) accepts .html or .htm, writes bundled assets beside it, and returns the resolved Path. It refuses to overwrite source dependencies. Files are individually replaced atomically, with the HTML entry written last; publication of the entire directory is not transactional.
• Compilation.html still contains internal asset placeholders. Use write() for a deployable export.

The internal Compilation.document tree is available for inspection, but its mutable implementation types are not part of the stable extension API. There is no arbitrary Python callback or host-code execution inside documents.

PDF

from hamen_markup import compile_file
from hamen_markup.export import export_pdf

result = compile_file('example.hmn', target='pdf')
export_pdf(result, 'output/example.pdf', timeout=90_000)

export_pdf(compilation, output, *, timeout=90000, screenshot=None) -> Path requires the PDF extra, Chromium, a PDF-target compilation, and a .pdf output filename. timeout is in milliseconds. screenshot optionally saves a PNG of the browser page surfaces. Browser errors are returned as MarkupError diagnostics. PDF accessibility tags are requested; PDF/UA certification is not claimed.

Parse without rendering

parse(source, filename='<string>', *, notes=None) returns syntax nodes and source spans. The node representation is an inspection format, not a stable serialized interchange schema. Use source files or .hmkp bundles for interchange.

Portable source bundles

from pathlib import Path
from hamen_markup.packages import pack, unpack

pack(Path('example.hmn'), Path('example.hmkp'), root=Path('.'))
entry = unpack(Path('example.hmkp'), Path('extracted'))

Bundles contain manifest.json and dependency files beneath files/. The format identifier is hamen-markup-package-1; the manifest records entry path, compiler version, byte counts, and SHA-256 digests. Extraction validates all members before writing. Destinations must be new or empty. Absolute paths, traversal, symlinks, duplicate or conflicting paths, and nonportable filenames are rejected. A bundle is limited to 10,000 members and 256 MiB uncompressed. Checksums detect damage; they do not authenticate the author.

Diagnostics

MarkupError.diagnostic exposes code, message, span, severity, and hint. A span has source, line, column, end_line, and end_column; source coordinates are one-based. Use the error code for classification and the message for display. The precise prose and span extent may improve in patch releases.

Catch OSError as well when integrating filesystem writes into an application. The CLI reports operational failures with a nonzero status.