The Wiki package exposes programmatic APIs for CI pipelines, tests, application code, and agent automation. The wiki command (Wiki CLI) remains the primary user surface; programmatic callers can use either the in-process Python library or the type-safe TypeScript SDK shipped by the npm package.

See Design Philosophies for the CLI vs library split. The Python engine remains the source of truth; the TypeScript SDK is a thin binding over the Python CLI, not a second implementation.

Python library

The Wiki package (wazootech-wiki on PyPI) exposes a library-first Python API. Python calls return typed results and raise domain exceptions instead of printing or exiting. Semver applies to symbols in wiki.__all__ (listed below); other wiki.* modules are internal unless documented on this page.

Generated reference docs are available at Python API Reference.

Install and imports

pip install wazootech-wiki

Import stable symbols from the top-level package:

from wiki import Wiki, AuditReport, BuildResult

Symbols listed in wiki.__all__ are semver-stable. Other modules (wiki.site, wiki.graph, …) are internal unless documented here.

The package ships a PEP 561 marker (py.typed).

Wiki session

Wiki wraps a loaded Config and graph lifecycle:

from pathlib import Path
from wiki import Wiki

w = Wiki.load("wiki.yml")
# or override inputs (same as --wiki-inputs):
w = Wiki.load("wiki.yml", wiki_inputs=["docs/wiki"])

report = w.check()
if not report.ok:
    for issue in report.errors:
        print(issue.code, issue.path, issue.message)

# File-scoped check (SHACL + JSON Schema per file; no full-wiki-only rules):
report = w.check([Path("docs/wiki/Some_Page.md")])

lint_report = w.lint()
preflight = w.preflight()  # lint merged with check — same as wiki build preflight

graph = w.graph(infer=True, reload=False)

Runtime overrides (global -b / --url-style):

w = w.with_runtime(base_url="/wiki", url_style="dir")

Validation reports

Validation operations (Wiki.check and Wiki.lint) return an AuditReport:

Each Issue has a stable machine-readable code (aligned with config rule keys such as broken_links, shacl_violation, frontmatter_schema) and a human message for CLI-style output.

from pathlib import Path
from wiki import Wiki

w = Wiki.load("wiki.yml")
report = w.check()
strict = report.apply_strict()  # promote warnings to errors
errors, warnings = report.messages()
merged = report.merge(other_report)

Build

Invoke builds directly on the Wiki instance using CLI-aligned arguments:

from pathlib import Path
from wiki import Wiki

w = Wiki.load("wiki.yml")
result = w.build(
    output_dir=Path("_site"),
    render=False,
    no_check=False,
    verbose=False,
)
if not result.ok:
    # preflight AuditReport on result.preflight when lint/check failed
    ...
print(result.page_count, result.written_paths)

BuildError is raised when the output directory overlaps wiki inputs or config root.

Link, render, export, format, and query

Wiki instances expose direct, option-free methods for executing wiki operations matching the CLI parameters:

# Run on the whole wiki with clean OOP methods:
link_report = w.link(check=True)
render_report = w.render(check=True)
export_result = w.export(format="turtle", mode="expanded")
fmt_report = w.format(check=True)

# Run a SPARQL query directly:
query_res = w.query("SELECT ?s WHERE { ?s ?p ?o }")

# Start local server:
w.serve(port=8080)

# Or target specific files:
from pathlib import Path
fmt_report = w.format([Path("docs/wiki/Some_Page.md")])

Scaffold

Init logic is available as a static helper:

from pathlib import Path
from wiki import Wiki, InitOptions

options = InitOptions(...)  # see wiki.schemas.init
result = Wiki.init(Path.cwd(), options, git=False)
print(result.written_paths)

Interactive wiki init still owns prompts, --git, and preflight guards in the CLI.

TypeScript SDK

The npm package ships a type-safe TypeScript SDK for Node projects. It uses the same private Python environment as the npm wiki command and shells out to the Python CLI with safe argv arrays.

npm install wazootech-wiki

ESM usage:

import { Wiki } from "wazootech-wiki";

const wiki = Wiki.load({ config: "docs/wiki.yml" });

await wiki.check({ strict: true });

const results = await wiki.query({
  query: "SELECT ?s WHERE { ?s ?p ?o }",
  format: "json",
});

CommonJS usage:

const { Wiki } = require("wazootech-wiki");

The SDK exposes methods that mirror the CLI surface: check, lint, fmt, render, build, export, link, query, serve, init, and upgrade. Options use TypeScript-friendly camelCase names and map to the corresponding CLI flags.

Most report-producing methods return a WikiCommandResult containing ok, exitCode, stdout, stderr, and the executed command argv. JSON-capable commands can parse structured output: query({ format: "json" }) returns parsed JSON by default, and export({ format: "dict" }) or export({ format: "json-ld" }) includes parsed data.

Generated reference docs are available at TypeScript API Reference.

Because the SDK is a thin binding, updates to src/wiki/cli.py subcommands or flags must be reflected in npm/src/wiki.ts, npm/src/types.ts, and npm/test-wiki-api.js in the same change.

Layout slot contract

Page layouts substitute %wiki.*% slots. build_layout_context validates a typed LayoutContext (internal schema in wiki.schemas.layout) before markup and slot substitution. The contract boundary for tests and downstream layout tools is wiki.site.layout_tokens.build_layout_token_map. Contract tests assert the context key tree, markup paths, and that every supported slot is produced by that map. See Wiki Configuration.

Exceptions

CLI parity

Library operations mirror subcommands documented under Wiki CLI. The CLI adds silence-on-success, --strict, pipe formats, and exit codes. For agent workflows that shell out, prefer skills/wiki/scripts/audit.sh; for in-process CI, prefer Wiki and typed reports.

Related

• Wiki CLI — command reference
• Wiki Configuration — config semantics
• Design Philosophies — silent success, composable stdout