markdown-script 0.4.2__cp311-abi3-win_amd64.whl

markdown_script/__init__.py

@@ -0,0 +1,74 @@
+"""markdown_script — composable LLM prompt template compiler (native Python bindings).
+
+Compile ``.mds`` templates to Markdown or structured chat messages in-process, via
+the same Rust core that powers the MDS CLI and Node.js/WASM bindings. Output is
+byte-identical across all bindings.
+
+Example
+-------
+>>> import markdown_script
+>>> r = markdown_script.compile("Hello {{name}}!", vars={"name": "Alice"})
+>>> r.kind, r.output
+('markdown', 'Hello Alice!')
+
+Errors raise :class:`MdsError`, which carries ``.code``, ``.message``, ``.help``,
+and ``.span``. Compilation is synchronous CPU work and releases the GIL, so it
+parallelises across threads; wrap a call in ``asyncio.to_thread`` for async code.
+"""
+
+from __future__ import annotations
+
+from importlib import metadata as _metadata
+
+from ._markdown_script import (
+    CheckResult,
+    CompileResult,
+    LintDiagnostic,
+    LintFileReport,
+    LintResult,
+    MdsError,
+    Message,
+    Span,
+    check,
+    check_file,
+    check_virtual,
+    compile,
+    compile_file,
+    compile_virtual,
+    lint,
+    lint_file,
+    lint_virtual,
+    scan_imports,
+)
+
+# The native exception is registered under the extension submodule `_markdown_script`.
+# Retag it (and it alone — the result classes already declare `module = "markdown_script"`)
+# to the public package so `pickle`, `repr`, and tracebacks resolve `markdown_script.MdsError`.
+MdsError.__module__ = "markdown_script"
+
+try:
+    __version__ = _metadata.version("markdown-script")
+except _metadata.PackageNotFoundError:  # pragma: no cover - source tree without an install
+    __version__ = "0.0.0"
+
+__all__ = [
+    "CheckResult",
+    "CompileResult",
+    "LintDiagnostic",
+    "LintFileReport",
+    "LintResult",
+    "MdsError",
+    "Message",
+    "Span",
+    "__version__",
+    "check",
+    "check_file",
+    "check_virtual",
+    "compile",
+    "compile_file",
+    "compile_virtual",
+    "lint",
+    "lint_file",
+    "lint_virtual",
+    "scan_imports",
+]

markdown_script/__init__.pyi

@@ -0,0 +1,49 @@
+"""Public type surface for the ``markdown_script`` package.
+
+Everything is re-exported from the native ``._markdown_script`` extension; see
+``_markdown_script.pyi`` for the full signatures.
+"""
+
+from __future__ import annotations
+
+from ._markdown_script import CheckResult as CheckResult
+from ._markdown_script import CompileResult as CompileResult
+from ._markdown_script import LintDiagnostic as LintDiagnostic
+from ._markdown_script import LintFileReport as LintFileReport
+from ._markdown_script import LintResult as LintResult
+from ._markdown_script import MdsError as MdsError
+from ._markdown_script import Message as Message
+from ._markdown_script import Span as Span
+from ._markdown_script import check as check
+from ._markdown_script import check_file as check_file
+from ._markdown_script import check_virtual as check_virtual
+from ._markdown_script import compile as compile
+from ._markdown_script import compile_file as compile_file
+from ._markdown_script import compile_virtual as compile_virtual
+from ._markdown_script import lint as lint
+from ._markdown_script import lint_file as lint_file
+from ._markdown_script import lint_virtual as lint_virtual
+from ._markdown_script import scan_imports as scan_imports
+
+__version__: str
+__all__ = [
+    "CheckResult",
+    "CompileResult",
+    "LintDiagnostic",
+    "LintFileReport",
+    "LintResult",
+    "MdsError",
+    "Message",
+    "Span",
+    "__version__",
+    "check",
+    "check_file",
+    "check_virtual",
+    "compile",
+    "compile_file",
+    "compile_virtual",
+    "lint",
+    "lint_file",
+    "lint_virtual",
+    "scan_imports",
+]

markdown_script/_markdown_script.pyi

@@ -0,0 +1,276 @@
+"""Type stubs for the native ``markdown_script._markdown_script`` extension module.
+
+The runtime objects are implemented in Rust (PyO3). These stubs describe the public
+surface for ``mypy``/``pyright``. Result classes are frozen — their attributes are
+read-only properties, so they are declared with ``@property``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from os import PathLike
+from typing import Any, Literal, final
+
+# `str | os.PathLike[str]` — accepted for `path` and `base_path`.
+_StrPath = str | PathLike[str]
+# A `vars` mapping: string keys to JSON-compatible values.
+_Vars = Mapping[str, Any]
+
+@final
+class Span:
+    """A source span attached to an :class:`MdsError` (frozen, unhashable)."""
+
+    @property
+    def offset(self) -> int: ...
+    @property
+    def length(self) -> int: ...
+    @property
+    def line(self) -> int | None: ...
+    @property
+    def column(self) -> int | None: ...
+    def __new__(
+        cls,
+        offset: int,
+        length: int,
+        line: int | None = ...,
+        column: int | None = ...,
+    ) -> Span: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    def to_json(self) -> str: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    __hash__: None  # type: ignore[assignment]
+
+@final
+class Message:
+    """A single chat message from a `@message`-bearing template (frozen)."""
+
+    @property
+    def role(self) -> str: ...
+    @property
+    def content(self) -> str: ...
+    def __new__(cls, role: str, content: str) -> Message: ...
+    def to_dict(self) -> dict[str, str]: ...
+    def to_json(self) -> str: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    __hash__: None  # type: ignore[assignment]
+
+@final
+class CheckResult:
+    """The result of :func:`check`, :func:`check_file`, or :func:`check_virtual`."""
+
+    @property
+    def warnings(self) -> list[str]: ...
+    def __new__(cls, warnings: list[str]) -> CheckResult: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    def to_json(self) -> str: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    __hash__: None  # type: ignore[assignment]
+
+@final
+class CompileResult:
+    """The result of :func:`compile`, :func:`compile_file`, or :func:`compile_virtual`.
+
+    ``kind`` is ``"markdown"`` or ``"messages"``. On a ``markdown`` result
+    ``messages`` is ``None``; on a ``messages`` result ``output`` is ``None``.
+
+    ``source_map`` is a Source Map v3 ``dict`` when ``source_map=True`` was passed
+    to the compile function and the result is Markdown; otherwise ``None``.
+    The wire key in ``to_dict()`` / ``to_json()`` is ``"sourceMap"`` (camelCase).
+
+    **``to_dict()`` vs ``to_json()`` asymmetry**: ``to_dict()`` always includes
+    the ``"sourceMap"`` key (``None`` when no map was generated) for
+    Python-idiomatic always-present attribute access. ``to_json()`` omits the key
+    when absent — that is the canonical wire format shared with Node.js and WASM.
+    """
+
+    @property
+    def kind(self) -> Literal["markdown", "messages"]: ...
+    @property
+    def output(self) -> str | None: ...
+    @property
+    def messages(self) -> list[Message] | None: ...
+    @property
+    def warnings(self) -> list[str]: ...
+    @property
+    def dependencies(self) -> list[str]: ...
+    @property
+    def source_map(self) -> dict[str, Any] | None: ...
+    def __new__(cls, canonical: Mapping[str, Any]) -> CompileResult: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    def to_json(self) -> str: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    __hash__: None  # type: ignore[assignment]
+
+@final
+class LintDiagnostic:
+    """A single lint finding within a :class:`LintFileReport` (frozen, unhashable).
+
+    Attributes map directly to the canonical wire-format diagnostic object.
+    ``help`` is ``None`` when the rule emits no hint; ``span`` is ``None`` for
+    rules that do not attach a source offset. Both attributes are always present.
+    """
+
+    @property
+    def rule(self) -> str: ...
+    @property
+    def severity(self) -> str: ...
+    @property
+    def message(self) -> str: ...
+    @property
+    def help(self) -> str | None: ...
+    @property
+    def fixable(self) -> bool: ...
+    @property
+    def span(self) -> Span | None: ...
+    @property
+    def fix_edits(self) -> list[dict[str, Any]] | None: ...
+    def __new__(
+        cls,
+        rule: str,
+        severity: str,
+        message: str,
+        help: str | None = ...,
+        fixable: bool = ...,
+        span: Span | None = ...,
+        fix_edits_json: str | None = ...,
+    ) -> LintDiagnostic: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    def to_json(self) -> str: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    __hash__: None  # type: ignore[assignment]
+
+@final
+class LintFileReport:
+    """Per-file findings group from :attr:`LintResult.files` (frozen, unhashable).
+
+    ``file`` is the path key for this file's diagnostics; ``diagnostics`` is a
+    typed list of :class:`LintDiagnostic` objects with fully-typed attributes.
+    """
+
+    @property
+    def file(self) -> str: ...
+    @property
+    def diagnostics(self) -> list[LintDiagnostic]: ...
+    def __new__(
+        cls,
+        file: str,
+        diagnostics: list[LintDiagnostic],
+    ) -> LintFileReport: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    def to_json(self) -> str: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    __hash__: None  # type: ignore[assignment]
+
+@final
+class LintResult:
+    """The result of :func:`lint`, :func:`lint_file`, or :func:`lint_virtual`.
+
+    Core JSON shape: ``{"files":[...],"truncated":false,"version":1}``.
+    When non-fatal warnings occur (e.g. unknown rule names),
+    ``"lint_warnings"`` also appears in alphabetical key order between
+    ``"files"`` and ``"truncated"``. Keys are in BTreeMap (alphabetical)
+    order. The CLI surface writes warnings to stderr rather than including
+    them in its JSON stdout.
+
+    ``files`` is a list of typed :class:`LintFileReport` objects. Each report
+    exposes ``.file`` (str) and ``.diagnostics`` (list[:class:`LintDiagnostic`]).
+    """
+
+    @property
+    def version(self) -> int: ...
+    @property
+    def truncated(self) -> bool: ...
+    @property
+    def files(self) -> list[LintFileReport]: ...
+    @property
+    def lint_warnings(self) -> list[str]:
+        """Non-fatal warnings raised while configuring the lint run.
+
+        An unknown rule name in the ``rules`` mapping produces one entry here:
+        the rule is not enforced (it does not exist) but the call still
+        succeeds. Empty in the common case.
+        """
+    def __new__(cls, canonical: Mapping[str, Any]) -> LintResult: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    def to_json(self) -> str: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    __hash__: None  # type: ignore[assignment]
+
+class MdsError(Exception):
+    """Raised for every MDS compilation failure.
+
+    ``str(err) == err.message``.
+    """
+
+    code: str
+    message: str
+    help: str | None
+    span: Span | None
+
+def compile(
+    source: str,
+    *,
+    vars: _Vars | None = ...,
+    base_path: _StrPath | None = ...,
+    source_map: bool = ...,
+    sources_content: bool = ...,
+) -> CompileResult: ...
+def compile_file(
+    path: _StrPath,
+    *,
+    vars: _Vars | None = ...,
+    source_map: bool = ...,
+    sources_content: bool = ...,
+) -> CompileResult: ...
+def compile_virtual(
+    modules: Mapping[str, str],
+    entry: str,
+    *,
+    vars: _Vars | None = ...,
+    source_map: bool = ...,
+    sources_content: bool = ...,
+) -> CompileResult: ...
+def check(
+    source: str,
+    *,
+    vars: _Vars | None = ...,
+    base_path: _StrPath | None = ...,
+    source_map: None = ...,
+    sources_content: None = ...,
+) -> CheckResult:
+    """Validate without rendering.
+
+    ``source_map`` and ``sources_content`` are present in the signature so that
+    passing them raises ``MdsError(code="mds::invalid_options")`` rather than a
+    bare ``TypeError``. Callers should never pass these — use :func:`compile` for
+    source-map generation.
+    """
+    ...
+def check_file(path: _StrPath, *, vars: _Vars | None = ...) -> CheckResult: ...
+def check_virtual(
+    modules: Mapping[str, str],
+    entry: str,
+    *,
+    vars: _Vars | None = ...,
+) -> CheckResult: ...
+def scan_imports(source: str, /) -> list[str]: ...
+def lint(
+    source: str,
+    *,
+    vars: _Vars | None = ...,
+    base_path: _StrPath | None = ...,
+    rules: Mapping[str, str] | None = ...,
+) -> LintResult: ...
+def lint_file(
+    path: _StrPath,
+    *,
+    vars: _Vars | None = ...,
+    rules: Mapping[str, str] | None = ...,
+) -> LintResult: ...
+def lint_virtual(
+    modules: Mapping[str, str],
+    entry: str,
+    *,
+    vars: _Vars | None = ...,
+    rules: Mapping[str, str] | None = ...,
+) -> LintResult: ...

markdown_script-0.4.2.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: markdown-script
+Version: 0.4.2
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Typing :: Typed
+License-File: LICENSE
+Summary: Composable LLM prompt template compiler — native Python bindings for MDS (Markdown Script)
+Keywords: markdown,template,llm,prompt,compiler
+Author: Dean Sharon
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/dean0x/mdscript
+Project-URL: Issues, https://github.com/dean0x/mdscript/issues
+Project-URL: Repository, https://github.com/dean0x/mdscript
+
+# markdown-script
+
+Native **Python bindings** for [MDS (Markdown Script)](https://github.com/dean0x/mdscript) —
+a composable LLM prompt-template compiler. Compile `.mds` templates to Markdown or
+structured chat messages in-process, backed by the same Rust core as the MDS CLI and
+the Node.js / WASM bindings. Output is byte-identical across every binding.
+
+```bash
+pip install markdown-script
+```
+
+> **Not yet on PyPI** — the `markdown-script` name registration and PyPI publishing are
+> tracked in [#292] (rename + registration) and [#132] (wheel matrix + PyPI publishing
+> pipeline). For now, build from source: `pip install ./crates/mds-python` (or `maturin
+> build -m crates/mds-python/Cargo.toml` to produce a wheel), with a Rust toolchain and
+> `python3` on `PATH`. Once published, wheels ship as `cp311-abi3` (CPython 3.11+, one
+> wheel per platform).
+
+[#292]: https://github.com/dean0x/mdscript/issues/292
+[#132]: https://github.com/dean0x/mdscript/issues/132
+
+## Quick start
+
+```python
+import markdown_script
+
+# Markdown template
+r = markdown_script.compile("Hello {{name}}!", vars={"name": "Alice"})
+assert r.kind == "markdown"
+assert r.output == "Hello Alice!"
+
+# @message template → structured messages
+r = markdown_script.compile("@message user:\nHi\n@end\n")
+assert r.kind == "messages"
+assert r.messages[0].role == "user"
+assert r.output is None            # inactive payload is None
+
+# Validate without rendering
+markdown_script.check("Hello {{name}}!", vars={"name": "Bob"})
+
+# Compile a file (dependencies come back as absolute paths)
+r = markdown_script.compile_file("prompts/agent.mds")
+print(r.dependencies)
+```
+
+## API
+
+All compile/check functions return a typed, picklable result. Keyword arguments are
+keyword-only; `scan_imports` takes its argument positionally.
+
+| Function | Signature |
+|----------|-----------|
+| `compile` | `compile(source, *, vars=None, base_path=None, source_map=False, sources_content=False) -> CompileResult` |
+| `compile_file` | `compile_file(path, *, vars=None, source_map=False, sources_content=False) -> CompileResult` |
+| `compile_virtual` | `compile_virtual(modules, entry, *, vars=None, source_map=False, sources_content=False) -> CompileResult` |
+| `check` | `check(source, *, vars=None, base_path=None) -> CheckResult` |
+| `check_file` | `check_file(path, *, vars=None) -> CheckResult` |
+| `check_virtual` | `check_virtual(modules, entry, *, vars=None) -> CheckResult` |
+| `scan_imports` | `scan_imports(source, /) -> list[str]` |
+| `lint` | `lint(source, *, vars=None, base_path=None, rules=None) -> LintResult` |
+| `lint_file` | `lint_file(path, *, vars=None, rules=None) -> LintResult` |
+| `lint_virtual` | `lint_virtual(modules, entry, *, vars=None, rules=None) -> LintResult` |
+
+- `path` / `base_path` accept `str` or `os.PathLike`.
+- `vars` is a mapping of string keys to JSON-compatible values; a non-mapping raises
+  `MdsError(code="mds::invalid_options")`.
+- `compile_virtual` / `check_virtual` / `lint_virtual` resolve imports against an in-memory
+  map; `entry` must be a key in `modules`.
+- `source_map=True` generates a Source Map v3 document; `result.source_map` is a `dict`.
+  For string-source compiles `sources[0]` is `"input.mds"`. `sources_content=True` embeds
+  the original source text in `sourcesContent[]` (requires `source_map=True`).
+  ⚠ Privacy: `sources_content=True` embeds the full template source in the map.
+- `rules` is a mapping of rule name → severity string (`"off"`, `"info"`, `"warn"`, `"error"`).
+  Unknown severity values raise `MdsError(code="mds::invalid_options")`; unknown rule names
+  emit a warning and lint continues — the unknown name has no effect, but a non-empty
+  `result.lint_warnings` list signals the problem so callers can surface it.
+  `LintResult` exposes `.version`, `.truncated`, `.lint_warnings`, `.to_dict()`, `.to_json()`, and `.files`
+  — a `list[LintFileReport]`. Each `LintFileReport` has `.file` (`str`) and `.diagnostics`
+  (`list[LintDiagnostic]`). `LintDiagnostic` carries `.rule`, `.severity`, `.message`,
+  `.help` (`str | None`), `.fixable` (`bool`), `.fix_edits` (`list[dict] | None`), and `.span` (`Span | None`).
+  `LintFileReport` and `LintDiagnostic` are frozen, picklable, and comparable by value.
+  **`files[].file` key:** `lint()` sets this to `"input.mds"` (string-source); `lint_file()` sets it to
+  the file's path; `lint_virtual()` sets it to the caller-supplied entry key. The CLI additionally
+  relabels stdin input as `"<stdin>"` — this asymmetry does not apply to the Python binding.
+
+### Result objects
+
+`CompileResult` exposes `.kind` (`"markdown"` | `"messages"`), `.output` (`str | None`),
+`.messages` (`list[Message] | None`), `.warnings`, `.dependencies`, and `.source_map`
+(`dict | None`). `CheckResult` exposes `.warnings`. Both offer `.to_dict()` and `.to_json()`.
+
+> **`to_dict()` vs `to_json()` asymmetry (source maps):** `CompileResult.to_dict()` always
+> includes `"sourceMap": None` when no source map was generated — Python-idiomatic
+> always-present. `to_json()` omits the key when absent, matching the canonical wire format
+> shared with the CLI, napi, and WASM surfaces for byte-identical cross-surface parity.
+
+Results are frozen, comparable by value, intentionally unhashable, and picklable.
+
+### Errors
+
+Every failure raises `markdown_script.MdsError` (a subclass of `Exception`):
+
+```python
+try:
+    markdown_script.compile("Hello {{undefined}}!")
+except markdown_script.MdsError as e:
+    print(e.code)          # "mds::undefined_var"
+    print(str(e))          # == e.message
+    print(e.help)          # hint, or None
+    if e.span:
+        print(e.span.line, e.span.column)   # 1-indexed
+```
+
+## Concurrency
+
+Compilation is synchronous, stateless CPU work and **releases the GIL**, so calls
+parallelise across threads. For `asyncio`, offload with `asyncio.to_thread(markdown_script.compile, src)`.
+The extension is also free-threading (`cp314t`) ready — result classes are frozen and
+the module declares `gil_used = false` — though a free-threaded wheel is not yet shipped.
+
+## License
+
+MIT © the MDS authors.
+

markdown_script-0.4.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+markdown_script/__init__.py,sha256=9hXho1NkWZ039Sg0seAXmtNs6dTNP0J4dY29rz3ZZow,2039
+markdown_script/__init__.pyi,sha256=J2k2waz3MFBPrUNXtMdePSv_6Vup2lSooalPynwdqCs,1645
+markdown_script/_markdown_script.pyd,sha256=BxfsFdX_2wUeaEbcKGN1d51sWwbWHvfmDEUj673e-nQ,1495552
+markdown_script/_markdown_script.pyi,sha256=s-X23m6Wugfj1D8DFaigLfZzLgeHwzH4oPitRm_t2Ls,9090
+markdown_script/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_script-0.4.2.dist-info/METADATA,sha256=7OJ6El0Sz97H63DfXEjzZGMKCwiWvinu38NBL7KLivg,7305
+markdown_script-0.4.2.dist-info/WHEEL,sha256=RBTVKNPkFN9rJmwGU7ihNrh3V0g9JbkE0zuZYATRViM,96
+markdown_script-0.4.2.dist-info/licenses/LICENSE,sha256=8HfEydh7mCgn17GknkD786w-6uQlxqgdzaNjW5YPIyo,1089
+markdown_script-0.4.2.dist-info/sboms/mds-python.cyclonedx.json,sha256=ahmg0qGgRNeHpVyF2EytrLy-C8rjTR6Aor4vMvhFW-0,55657
+markdown_script-0.4.2.dist-info/RECORD,,

markdown_script-0.4.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.13.3)
+Root-Is-Purelib: false
+Tag: cp311-abi3-win_amd64

markdown_script-0.4.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dean Sharon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.