usage-spec 1.0.0__py3-none-any.whl

usage_spec/__init__.py

@@ -0,0 +1,32 @@
+"""Usage spec core - Python implementation aligned with @usage-spec/core."""
+
+from .spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices
+from .kdl import render_kdl, validate_kdl
+from .json import render_json
+
+__all__ = [
+    "Spec",
+    "SpecArg",
+    "SpecFlag",
+    "SpecCommand",
+    "SpecChoices",
+    "render_kdl",
+    "validate_kdl",
+    "render_json",
+    "generate",
+]
+
+
+def generate(
+    spec: Spec,
+    *,
+    format: str = "kdl",
+    comment: str | None = None,
+) -> str:
+    """Generate usage spec output in the specified format."""
+    output = render_json(spec) if format == "json" else render_kdl(spec)
+
+    if comment:
+        return f"// {comment}\n{output}"
+
+    return output

usage_spec/json.py

@@ -0,0 +1,123 @@
+"""JSON renderer for usage spec, aligned with @usage-spec/core json.ts output."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .spec import Spec, SpecArg, SpecFlag, SpecCommand
+
+
+def _arg_to_json(arg: SpecArg) -> dict[str, Any]:
+    result: dict[str, Any] = {"name": arg.name}
+
+    if arg.help:
+        result["help"] = arg.help
+    if not arg.required:
+        result["required"] = False
+    if arg.var:
+        result["var"] = True
+    if arg.hide:
+        result["hide"] = True
+    if len(arg.default) == 1:
+        result["default"] = arg.default[0]
+    if len(arg.default) > 1:
+        result["default"] = arg.default
+    if arg.choices:
+        result["choices"] = arg.choices.values
+
+    return result
+
+
+def _flag_to_json(flag: SpecFlag) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+
+    name_parts: list[str] = []
+    if flag.short:
+        name_parts.append(f"-{flag.short}")
+    if flag.long:
+        name_parts.append(f"--{flag.long}")
+    result["name"] = " ".join(name_parts)
+
+    if flag.help:
+        result["help"] = flag.help
+    if flag.help_long:
+        result["help_long"] = flag.help_long
+    if flag.required:
+        result["required"] = True
+    if flag.hide:
+        result["hide"] = True
+    if flag.global_:
+        result["global"] = True
+    if flag.count:
+        result["count"] = True
+    if flag.var:
+        result["var"] = True
+    if flag.negate:
+        result["negate"] = flag.negate
+    if flag.deprecated:
+        result["deprecated"] = flag.deprecated
+    if flag.env:
+        result["env"] = flag.env
+    if len(flag.default) == 1:
+        result["default"] = flag.default[0]
+    if len(flag.default) > 1:
+        result["default"] = flag.default
+
+    if flag.arg:
+        result["arg"] = _arg_to_json(flag.arg)
+
+    return result
+
+
+def _cmd_to_json(cmd: SpecCommand) -> dict[str, Any]:
+    result: dict[str, Any] = {"name": cmd.name}
+
+    if cmd.help:
+        result["help"] = cmd.help
+    if cmd.help_long:
+        result["help_long"] = cmd.help_long
+    if cmd.hide:
+        result["hide"] = True
+    if cmd.deprecated:
+        result["deprecated"] = cmd.deprecated
+    if cmd.aliases:
+        result["aliases"] = cmd.aliases
+    if cmd.subcommand_required:
+        result["subcommand_required"] = True
+
+    if cmd.flags:
+        result["flags"] = [_flag_to_json(f) for f in cmd.flags]
+    if cmd.args:
+        result["args"] = [_arg_to_json(a) for a in cmd.args]
+    if cmd.cmds:
+        result["cmds"] = [_cmd_to_json(c) for c in cmd.cmds]
+
+    return result
+
+
+def render_json(spec: Spec) -> str:
+    """Render a Spec to JSON format string."""
+    result: dict[str, Any] = {}
+
+    if spec.name:
+        result["name"] = spec.name
+    if spec.bin:
+        result["bin"] = spec.bin
+    if spec.version:
+        result["version"] = spec.version
+    if spec.about:
+        result["about"] = spec.about
+    if spec.long:
+        result["long_about"] = spec.long
+    if spec.usage:
+        result["usage"] = spec.usage
+
+    if spec.flags:
+        result["flags"] = [_flag_to_json(f) for f in spec.flags]
+    if spec.args:
+        result["args"] = [_arg_to_json(a) for a in spec.args]
+    if spec.cmds:
+        result["cmds"] = [_cmd_to_json(c) for c in spec.cmds]
+
+    return json.dumps(result, indent=2) + "\n"

usage_spec/kdl.py

@@ -0,0 +1,247 @@
+"""KDL renderer for usage spec, aligned with @usage-spec/core kdl.ts output."""
+
+from __future__ import annotations
+
+from .spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices
+
+
+def _escape_kdl_string(value: str) -> str:
+    """Escape a string for KDL format."""
+    if not value:
+        return '""'
+    # KDL strings: if the value contains special chars, wrap in quotes
+    needs_quoting = any(c in value for c in (' ', '"', '\n', '\r', '\t', '\\', '{', '}', '#', '\0'))
+    if not needs_quoting and value not in ('true', 'false', 'null'):
+        return value
+    escaped = value.replace('\\', '\\\\').replace('"', '\\"').replace('\n', '\\n').replace('\r', '\\r').replace('\t', '\\t')
+    return f'"{escaped}"'
+
+
+def _format_bool(value: bool) -> str:
+    return "#true" if value else "#false"
+
+
+def _indent(lines: list[str], level: int) -> list[str]:
+    prefix = "    " * level
+    return [prefix + line for line in lines]
+
+
+def _render_choices(choices: SpecChoices) -> list[str]:
+    parts = " ".join(_escape_kdl_string(c) for c in choices.values)
+    return [f"choices {parts}"]
+
+
+def _render_arg(arg: SpecArg, *, is_flag_arg: bool = False, indent_level: int = 0) -> list[str]:
+    lines: list[str] = []
+
+    if is_flag_arg:
+        usage = f"<{arg.name}>"
+        line_parts = [f"arg {_escape_kdl_string(usage)}"]
+    else:
+        # Build usage string: <required> or [optional], with … for variadic
+        if arg.required:
+            usage = f"<{arg.name}>"
+        else:
+            usage = f"[{arg.name}]"
+        if arg.var:
+            usage += "\u2026"
+
+        line_parts = [f"arg {_escape_kdl_string(usage)}"]
+
+        if arg.help:
+            line_parts.append(f"help={_escape_kdl_string(arg.help)}")
+        if not arg.required:
+            line_parts.append(f"required={_format_bool(False)}")
+        if arg.var:
+            line_parts.append(f"var={_format_bool(True)}")
+        if arg.hide:
+            line_parts.append(f"hide={_format_bool(True)}")
+        if len(arg.default) == 1:
+            line_parts.append(f"default={_escape_kdl_string(arg.default[0])}")
+
+    # Check for children (choices, multiple defaults)
+    children: list[str] = []
+
+    if not is_flag_arg and len(arg.default) > 1:
+        parts = " ".join(_escape_kdl_string(d) for d in arg.default)
+        children.append(f"default {parts}")
+
+    if arg.choices:
+        children.extend(_render_choices(arg.choices))
+
+    if is_flag_arg:
+        # Flag arg: only has help and choices as children/properties
+        line_parts_flag = [f"arg {_escape_kdl_string(f'<{arg.name}>')}"]
+        if arg.help:
+            line_parts_flag.append(f"help={_escape_kdl_string(arg.help)}")
+
+        if arg.choices:
+            children_flag = _indent(_render_choices(arg.choices), 1)
+            lines.append(" ".join(line_parts_flag) + " {")
+            lines.extend(children_flag)
+            lines.append("}")
+        else:
+            lines.append(" ".join(line_parts_flag))
+        return lines
+
+    if children:
+        lines.append(" ".join(line_parts) + " {")
+        lines.extend(_indent(children, 1))
+        lines.append("}")
+    else:
+        lines.append(" ".join(line_parts))
+
+    return lines
+
+
+def _render_flag(flag: SpecFlag) -> list[str]:
+    # Build the flag name: "-s --long"
+    name_parts: list[str] = []
+    if flag.short:
+        name_parts.append(f"-{flag.short}")
+    if flag.long:
+        name_parts.append(f"--{flag.long}")
+    flag_name = " ".join(name_parts)
+
+    line_parts = [f"flag {_escape_kdl_string(flag_name)}"]
+
+    if flag.help:
+        line_parts.append(f"help={_escape_kdl_string(flag.help)}")
+    if flag.required:
+        line_parts.append(f"required={_format_bool(True)}")
+    if flag.var:
+        line_parts.append(f"var={_format_bool(True)}")
+    if flag.hide:
+        line_parts.append(f"hide={_format_bool(True)}")
+    if flag.global_:
+        line_parts.append(f"global={_format_bool(True)}")
+    if flag.count:
+        line_parts.append(f"count={_format_bool(True)}")
+    if flag.negate:
+        line_parts.append(f"negate={flag.negate}")
+    if flag.deprecated:
+        line_parts.append(f"deprecated={_escape_kdl_string(flag.deprecated)}")
+    if len(flag.default) == 1:
+        line_parts.append(f"default={_escape_kdl_string(flag.default[0])}")
+    elif flag.default_bool is not None:
+        line_parts.append(f"default={_format_bool(flag.default_bool)}")
+    if flag.env:
+        line_parts.append(f"env={_escape_kdl_string(flag.env)}")
+
+    # Check for children
+    children: list[str] = []
+
+    if flag.help_long:
+        children.append(f"long_help {_escape_kdl_string(flag.help_long)}")
+
+    if len(flag.default) > 1:
+        parts = " ".join(_escape_kdl_string(d) for d in flag.default)
+        children.append(f"default {parts}")
+
+    if flag.arg:
+        children.extend(_render_flag_arg(flag.arg))
+
+    if children:
+        return [" ".join(line_parts) + " {", *_indent(children, 1), "}"]
+    else:
+        return [" ".join(line_parts)]
+
+
+def _render_flag_arg(arg: SpecArg) -> list[str]:
+    """Render a flag's inner arg node."""
+    line_parts = [f"arg {_escape_kdl_string(f'<{arg.name}>')}"]
+
+    if arg.help:
+        line_parts.append(f"help={_escape_kdl_string(arg.help)}")
+
+    if arg.choices:
+        children = _indent(_render_choices(arg.choices), 1)
+        return [" ".join(line_parts) + " {", *children, "}"]
+    else:
+        return [" ".join(line_parts)]
+
+
+def _render_command(cmd: SpecCommand) -> list[str]:
+    line_parts = [f"cmd {_escape_kdl_string(cmd.name)}"]
+
+    if cmd.hide:
+        line_parts.append(f"hide={_format_bool(True)}")
+    if cmd.subcommand_required:
+        line_parts.append("subcommand_required=#true")
+    if cmd.help:
+        line_parts.append(f"help={_escape_kdl_string(cmd.help)}")
+    if cmd.deprecated:
+        line_parts.append(f"deprecated={_escape_kdl_string(cmd.deprecated)}")
+
+    # Check for children
+    children: list[str] = []
+
+    if cmd.aliases:
+        parts = " ".join(_escape_kdl_string(a) for a in cmd.aliases)
+        children.append(f"alias {parts}")
+
+    if cmd.help_long:
+        children.append(f"long_help {_escape_kdl_string(cmd.help_long)}")
+
+    for flag in cmd.flags:
+        children.extend(_render_flag(flag))
+
+    for arg in cmd.args:
+        children.extend(_render_arg(arg))
+
+    for sub in cmd.cmds:
+        children.extend(_render_command(sub))
+
+    if children:
+        indented = _indent(children, 1)
+        return [" ".join(line_parts) + " {", *indented, "}"]
+    else:
+        return [" ".join(line_parts)]
+
+
+def render_kdl(spec: Spec) -> str:
+    """Render a Spec to KDL format string."""
+    lines: list[str] = []
+
+    if spec.name:
+        lines.append(f"name {_escape_kdl_string(spec.name)}")
+    if spec.bin:
+        lines.append(f"bin {_escape_kdl_string(spec.bin)}")
+    if spec.version:
+        lines.append(f"version {_escape_kdl_string(spec.version)}")
+    if spec.about:
+        lines.append(f"about {_escape_kdl_string(spec.about)}")
+    if spec.long:
+        lines.append(f"long_about {_escape_kdl_string(spec.long)}")
+    if spec.usage:
+        lines.append(f"usage {_escape_kdl_string(spec.usage)}")
+
+    for flag in spec.flags:
+        lines.extend(_render_flag(flag))
+
+    for arg in spec.args:
+        lines.extend(_render_arg(arg))
+
+    for cmd in spec.cmds:
+        lines.extend(_render_command(cmd))
+
+    return "\n".join(lines) + "\n"
+
+
+def validate_kdl(kdl: str) -> None:
+    """Validate KDL output by attempting a basic structural parse.
+
+    This is a simplified validator - for full validation, use the
+    @bgotink/kdl parser via the TypeScript @usage-spec/core package.
+    """
+    if not kdl.strip():
+        return
+    # Basic bracket matching for child blocks
+    depth = 0
+    for line in kdl.split("\n"):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("//"):
+            continue
+        depth += stripped.count("{") - stripped.count("}")
+    if depth != 0:
+        raise ValueError(f"Unbalanced braces in KDL output (depth={depth})")

usage_spec/spec.py

@@ -0,0 +1,67 @@
+"""Usage spec type definitions, aligned with @usage-spec/core TypeScript types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SpecChoices:
+    values: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SpecArg:
+    name: str = ""
+    help: str = ""
+    required: bool = True
+    var: bool = False
+    hide: bool = False
+    default: list[str] = field(default_factory=list)
+    choices: SpecChoices | None = None
+
+
+@dataclass
+class SpecFlag:
+    short: str = ""
+    long: str = ""
+    help: str = ""
+    help_long: str = ""
+    required: bool = False
+    hide: bool = False
+    global_: bool = False
+    count: bool = False
+    var: bool = False
+    negate: str = ""
+    deprecated: str = ""
+    default: list[str] = field(default_factory=list)
+    default_bool: bool | None = None
+    env: str = ""
+    arg: SpecArg | None = None
+
+
+@dataclass
+class SpecCommand:
+    name: str = ""
+    help: str = ""
+    help_long: str = ""
+    hide: bool = False
+    deprecated: str = ""
+    aliases: list[str] = field(default_factory=list)
+    subcommand_required: bool = False
+    flags: list[SpecFlag] = field(default_factory=list)
+    args: list[SpecArg] = field(default_factory=list)
+    cmds: list[SpecCommand] = field(default_factory=list)
+
+
+@dataclass
+class Spec:
+    name: str = ""
+    bin: str = ""
+    version: str = ""
+    about: str = ""
+    long: str = ""
+    usage: str = ""
+    flags: list[SpecFlag] = field(default_factory=list)
+    args: list[SpecArg] = field(default_factory=list)
+    cmds: list[SpecCommand] = field(default_factory=list)

usage_spec-1.0.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: usage-spec
+Version: 1.0.0
+Summary: Core types and rendering for usage spec
+License-Expression: MIT
+Keywords: cli,kdl,spec,usage
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# usage-spec
+
+Core types and rendering for [usage spec](https://usage.jdx.dev).
+
+## Install
+
+```sh
+pip install usage-spec
+```
+
+## API
+
+### Types
+
+```python
+@dataclass
+class Spec:
+    name: str
+    bin: str
+    version: str
+    about: str
+    long: str
+    usage: str
+    flags: list[SpecFlag]
+    args: list[SpecArg]
+    cmds: list[SpecCommand]
+```
+
+### Functions
+
+```python
+from usage_spec import generate, render_kdl, render_json, validate_kdl
+
+# Render Spec as KDL string
+render_kdl(spec: Spec) -> str
+
+# Render Spec as JSON string
+render_json(spec: Spec) -> str
+
+# Generate spec output with optional format and comment
+generate(spec: Spec, format: str = "kdl", comment: str | None = None) -> str
+
+# Validate KDL string by basic structural check
+validate_kdl(kdl: str) -> None
+```
+
+## License
+
+MIT

usage_spec-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+usage_spec/__init__.py,sha256=8lxB83JURrWanWgMs8tpBqs3ZTXWBBSfMZX8dhHIVJM,705
+usage_spec/json.py,sha256=P52RghAuK72fOi8G12FcyaouW05fUMrABPA5-Qn7UGI,3293
+usage_spec/kdl.py,sha256=tvQgiReAq3zl3pIxN7mVpIF7avUp6UlnK8aATx9CTxc,8032
+usage_spec/spec.py,sha256=mVZQBLPtWDuteOTFWY8oJeIkq3DZHd2HoIP-bq6jzS0,1604
+usage_spec-1.0.0.dist-info/METADATA,sha256=lv_yp0Ck38YjP55zIOEF58f4ZS1ySS4Ppsx7hjxxR3k,1492
+usage_spec-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+usage_spec-1.0.0.dist-info/RECORD,,

usage_spec-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any