apizit-linking 0.3.0__py3-none-any.whl

apizit_linking/__init__.py

@@ -0,0 +1,81 @@
+"""Declarative Python-to-HTTP binding engine for APIZIT."""
+
+from apizit_linking.compiler import (
+    compile_linking_file,
+    compile_routes,
+    discover_linking_file,
+    load_linking_file,
+    resolve_linking_target,
+    validate_definition,
+)
+from apizit_linking.errors import (
+    FunctionLoadError,
+    InvalidParameterError,
+    InvocationBindingError,
+    LinkingConfigurationError,
+    LinkingError,
+    LinkingRequestError,
+    ParameterNotFoundError,
+    ParameterResolutionError,
+)
+from apizit_linking.models import (
+    AUTO_SOURCE_ORDER,
+    LINKING_FILENAMES,
+    SUPPORTED_SOURCES,
+    CompilationResult,
+    CompiledRoute,
+    Diagnostic,
+    LoadedDefinition,
+    ParameterDefinition,
+    ParameterSource,
+    RouteDefinition,
+    SignatureParameter,
+    route_from_runtime_dict,
+)
+from apizit_linking.runtime import (
+    RequestContext,
+    call_function,
+    convert_parameter,
+    invoke_function,
+    load_function,
+    load_functions,
+    resolve_arguments,
+)
+
+__all__ = [
+    "AUTO_SOURCE_ORDER",
+    "LINKING_FILENAMES",
+    "SUPPORTED_SOURCES",
+    "CompilationResult",
+    "CompiledRoute",
+    "Diagnostic",
+    "FunctionLoadError",
+    "InvalidParameterError",
+    "InvocationBindingError",
+    "LinkingConfigurationError",
+    "LinkingError",
+    "LinkingRequestError",
+    "LoadedDefinition",
+    "ParameterDefinition",
+    "ParameterNotFoundError",
+    "ParameterResolutionError",
+    "ParameterSource",
+    "RequestContext",
+    "RouteDefinition",
+    "SignatureParameter",
+    "compile_linking_file",
+    "compile_routes",
+    "call_function",
+    "convert_parameter",
+    "discover_linking_file",
+    "invoke_function",
+    "load_function",
+    "load_functions",
+    "load_linking_file",
+    "resolve_arguments",
+    "resolve_linking_target",
+    "route_from_runtime_dict",
+    "validate_definition",
+]
+
+__version__ = "0.3.0"

apizit_linking/cli.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import argparse
+import ipaddress
+import json
+import sys
+from typing import Sequence
+
+from apizit_linking.compiler import compile_linking_file, resolve_linking_target
+from apizit_linking.errors import LinkingError
+from apizit_linking.models import CompilationResult
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="apizit-linking",
+        description="Validate or preview an APIZIT declarative linking project.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    validate = subparsers.add_parser("validate", help="Validate and compile a linking definition.")
+    validate.add_argument(
+        "target",
+        nargs="?",
+        default=".",
+        help="Project directory or apizit_linking YAML/JSON file.",
+    )
+    validate.add_argument(
+        "--project-root",
+        help="Project root used to resolve module:function references.",
+    )
+    validate.add_argument("--json", action="store_true", help="Emit a machine-readable result.")
+
+    preview = subparsers.add_parser(
+        "preview",
+        help="Run a local development server for a Linking project.",
+    )
+    preview.add_argument(
+        "target",
+        nargs="?",
+        default=".",
+        help="Project directory or apizit_linking YAML/JSON file.",
+    )
+    preview.add_argument(
+        "--project-root",
+        help="Project root used to resolve module:function references.",
+    )
+    preview.add_argument("--host", default="127.0.0.1", help="Interface to bind.")
+    preview.add_argument("--port", type=_valid_port, default=8000, help="TCP port to bind.")
+    preview.add_argument(
+        "--allow-network",
+        action="store_true",
+        help="Allow binding to a non-loopback interface.",
+    )
+    return parser
+
+
+def run(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    linking_file, project_root = resolve_linking_target(args.target, args.project_root)
+    result = compile_linking_file(linking_file, project_root)
+    if args.command == "validate":
+        return _run_validate(result, as_json=args.json)
+    if args.command == "preview":
+        return _run_preview(
+            result, host=args.host, port=args.port, allow_network=args.allow_network
+        )
+    return 2
+
+
+def _run_validate(result: CompilationResult, *, as_json: bool) -> int:
+    payload = {
+        "valid": result.is_valid,
+        "file": str(result.linking_file),
+        "project_root": str(result.project_root),
+        "version": result.version,
+        "routes": [route.definition.to_runtime_dict() for route in result.routes],
+        "diagnostics": [diagnostic.to_dict() for diagnostic in result.diagnostics],
+    }
+    if as_json:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+    else:
+        state = "valid" if result.is_valid else "invalid"
+        print(f"APIZIT linking definition is {state}: {result.linking_file}")
+        print(f"Compiled routes: {len(result.routes)}")
+        for diagnostic in result.diagnostics:
+            print(diagnostic.format())
+    return 0 if result.is_valid else 1
+
+
+def _run_preview(
+    result: CompilationResult,
+    *,
+    host: str,
+    port: int,
+    allow_network: bool,
+) -> int:
+    if not result.is_valid:
+        print(
+            f"Cannot start preview: invalid linking definition: {result.linking_file}",
+            file=sys.stderr,
+        )
+        for diagnostic in result.diagnostics:
+            print(diagnostic.format(), file=sys.stderr)
+        return 1
+    if not allow_network and not _is_loopback_host(host):
+        print(
+            f"Refusing to expose the preview server on {host!r}. "
+            "Pass --allow-network to bind outside the local machine.",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        from apizit_linking.preview import run_preview
+    except ModuleNotFoundError as error:
+        missing_root = (error.name or "").partition(".")[0]
+        if missing_root not in {"fastapi", "multipart", "starlette", "uvicorn"}:
+            raise
+        print(
+            'Preview dependencies are not installed. Run: pip install "apizit-linking[preview]"',
+            file=sys.stderr,
+        )
+        return 2
+
+    for diagnostic in result.warnings:
+        print(diagnostic.format(), file=sys.stderr)
+    try:
+        run_preview(result, host=host, port=port)
+    except LinkingError as error:
+        print(f"Could not start preview: {error}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 0
+    return 0
+
+
+def _valid_port(value: str) -> int:
+    try:
+        port = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("port must be an integer") from error
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError("port must be between 1 and 65535")
+    return port
+
+
+def _is_loopback_host(host: str) -> bool:
+    normalized = host.strip().lower()
+    if normalized == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(normalized).is_loopback
+    except ValueError:
+        return False
+
+
+def main() -> None:
+    raise SystemExit(run())
+
+
+if __name__ == "__main__":
+    main()