codapact 0.1.0__py3-none-any.whl

codapact/__init__.py

@@ -0,0 +1,3 @@
+"""CodaPact: contracts into callable tools."""
+
+__version__ = "0.1.0"  # x-release-please-version

codapact/__main__.py

@@ -0,0 +1,83 @@
+"""CodaPact generator entry point."""
+
+import argparse
+import sys
+
+from codapact import __version__
+from codapact.configuration import resolve_generation
+from codapact.errors import CodaError
+from codapact.net import HttpTransport
+from codapact.project import generate
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="CodaPact: contracts into callable tools")
+    parser.add_argument("--version", action="version", version=f"codapact {__version__}")
+    subparsers = parser.add_subparsers(dest="action", required=True)
+    command = subparsers.add_parser("generate", help="Generate a Python library and argparse CLI")
+    command.add_argument("source", nargs="?", help="Local OpenAPI path or HTTP(S) URL")
+    command.add_argument("--manifest", help="Local version 1 generation manifest")
+    fields = {
+        "manifest-version": ("version", int),
+        "contract-type": ("contract.type", str),
+        "output": ("output.directory", str),
+        "package": ("client.package", str),
+        "client-language": ("client.language", str),
+        "cli-style": ("cli.style", str),
+        "slug": ("cli.slug", str),
+        "cli-definition": ("cli.definition", str),
+        "runtime-config-dir": ("runtime.config_directory", str),
+        "runtime-base-url": ("runtime.defaults.base_url", str),
+        "runtime-timeout": ("runtime.defaults.timeout", float),
+        "runtime-policy-allow": ("runtime.defaults.policy.allow", str),
+        "runtime-policy-deny": ("runtime.defaults.policy.deny", str),
+    }
+    for flag, (_, kind) in fields.items():
+        aliases = ["--slug", "--prefix"] if flag == "slug" else ["--" + flag]
+        command.add_argument(*aliases, type=kind, default=argparse.SUPPRESS)
+    command.add_argument(
+        "--allow-private", action=argparse.BooleanOptionalAction, default=argparse.SUPPRESS
+    )
+    command.add_argument(
+        "--runtime-allow-private", action=argparse.BooleanOptionalAction, default=argparse.SUPPRESS
+    )
+    command.add_argument("--set", action="append", default=[], metavar="FIELD=JSON")
+    args = parser.parse_args(argv)
+    try:
+        overrides = {}
+        for flag, (path, _) in fields.items():
+            if hasattr(args, flag.replace("-", "_")):
+                value = getattr(args, flag.replace("-", "_"))
+                if flag.startswith("runtime-policy-"):
+                    import json
+
+                    try:
+                        value = json.loads(value)
+                    except ValueError:
+                        raise CodaError("policy flags require JSON arrays") from None
+                cursor = overrides
+                parts = path.split(".")
+                for part in parts[:-1]:
+                    cursor = cursor.setdefault(part, {})
+                cursor[parts[-1]] = value
+        if args.source is not None:
+            overrides.setdefault("contract", {})["source"] = args.source
+        if hasattr(args, "allow_private"):
+            overrides.setdefault("contract", {})["allow_private"] = args.allow_private
+        if hasattr(args, "runtime_allow_private"):
+            overrides.setdefault("runtime", {}).setdefault("defaults", {})["allow_private"] = (
+                args.runtime_allow_private
+            )
+        options = resolve_generation(args.manifest, overrides, args.set)
+        allow_private = options.pop("allow_private")
+        generate(**options, transport=HttpTransport(allow_private=allow_private))
+    except (CodaError, OSError) as exc:
+        message = str(exc) if isinstance(exc, CodaError) else "cannot write generated project"
+        print(f"codapact: {message}", file=sys.stderr)
+        return 2
+    print(f"Generated {options['package']} in {options['output']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codapact/cli.py

@@ -0,0 +1,117 @@
+"""Noninteractive CLI runtime shared by generated CLI styles."""
+
+import argparse
+import json
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from codapact.errors import ApiError, CodaError, PolicyError, ResponseError, TransportError
+from codapact.loading import load
+from codapact.profiles import JsonFileStore, StoredAuth, runtime_settings
+from codapact.runtime import UNSET, ClientBase, EnvironmentAuth
+
+
+def run_cli(
+    factory: Callable[..., ClientBase],
+    document: dict[str, Any],
+    definition: dict[str, Any],
+    argv: list[str] | None = None,
+    *,
+    profile: dict[str, Any] | None = None,
+) -> int:
+    parser = argparse.ArgumentParser(description="Generated CodaPact API CLI")
+    parser.add_argument("--config", help="Local JSON/YAML runtime configuration")
+    parser.add_argument("--config-dir", help="Override configuration directory")
+    parser.add_argument("--auth-file", help="Override auth.json path")
+    parser.add_argument(
+        "--no-auth-file", action="store_true", help="Disable credential file discovery"
+    )
+    parser.add_argument("--base-url")
+    parser.add_argument("--timeout", type=float)
+    parser.add_argument("--allow-private", action=argparse.BooleanOptionalAction, default=None)
+    parser.add_argument("--pretty", action="store_true", help="Indent JSON output")
+    commands = parser.add_subparsers(dest="command", required=True)
+    operations = {op["id"]: op for op in document["operations"]}
+    mapping = {}
+    for command in definition["commands"]:
+        operation = operations[command["operation"]]
+        mapping[command["name"]] = operation
+        summary = operation["summary"].encode("unicode_escape").decode("ascii")
+        child = commands.add_parser(command["name"], help=summary)
+        for index, parameter in enumerate(operation["parameters"]):
+            child.add_argument(
+                "--arg-" + parameter["name"].replace("_", "-").lower(),
+                dest=f"p{index}",
+                required=parameter["required"],
+            )
+        if operation["body"] is not None:
+            child.add_argument(
+                "--body", required=operation["body_required"], help="JSON request body"
+            )
+    args = parser.parse_args(argv)
+    try:
+        if args.config and args.config.startswith(("http://", "https://")):
+            raise CodaError("runtime configuration must be local")
+        if profile is None:
+            settings = load(args.config) if args.config else {}
+            if args.config_dir or args.auth_file or args.no_auth_file:
+                raise CodaError("configuration discovery requires a generated runtime profile")
+            client = factory(settings=settings)
+        else:
+            overrides = {
+                key: getattr(args, key)
+                for key in ("base_url", "timeout", "allow_private")
+                if getattr(args, key) is not None
+            }
+            settings, directory = runtime_settings(profile, args.config_dir, args.config, overrides)
+            if args.auth_file and args.no_auth_file:
+                raise CodaError("--auth-file and --no-auth-file conflict")
+            if args.auth_file and "://" in args.auth_file:
+                raise CodaError("auth file must be local")
+            auth = (
+                EnvironmentAuth(settings.get("auth"))
+                if args.no_auth_file
+                else StoredAuth(
+                    JsonFileStore(
+                        Path(args.auth_file) if args.auth_file else directory / "auth.json",
+                        optional=args.auth_file is None,
+                    ),
+                    EnvironmentAuth(settings.get("auth")),
+                )
+            )
+            client = factory(settings=settings, auth=auth)
+        operation = mapping[args.command]
+        parameters: dict[str, Any] = {}
+        for index, parameter in enumerate(operation["parameters"]):
+            value = getattr(args, f"p{index}")
+            if value is not None:
+                parameters[parameter["name"]] = (
+                    value if parameter["schema"]["type"] == "string" else json.loads(value)
+                )
+        body = getattr(args, "body", None)
+        result = client._execute(
+            operation["id"], parameters, json.loads(body) if body is not None else UNSET
+        )
+        print(
+            json.dumps(
+                result, indent=2 if args.pretty else None, ensure_ascii=True, allow_nan=False
+            )
+        )
+        return 0
+    except (CodaError, ValueError, OSError) as exc:
+        code = (
+            5
+            if isinstance(exc, ApiError)
+            else 3
+            if isinstance(exc, PolicyError)
+            else 4
+            if isinstance(exc, TransportError)
+            else 6
+            if isinstance(exc, ResponseError)
+            else 2
+        )
+        message = str(exc) if isinstance(exc, CodaError) else "invalid JSON input or output"
+        print(f"codapact: {message}", file=sys.stderr)
+        return code

codapact/configuration.py

@@ -0,0 +1,135 @@
+"""Data-only generation manifests, explicit overrides, and portable runtime profiles."""
+
+import json
+import re
+from copy import deepcopy
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator
+
+from codapact.errors import CodaError
+from codapact.generation import package_name
+from codapact.loading import load, parse
+from codapact.net import validate_url
+from codapact.values import default_slug, merge, slug_name
+
+GENERATION_SCHEMA = json.loads(
+    files("codapact").joinpath("schemas/generation.v1.json").read_text("utf-8")
+)
+DEFAULTS: dict[str, Any] = {
+    "version": 1,
+    "contract": {"type": "openapi", "allow_private": False},
+    "output": {"directory": "generated"},
+    "client": {"language": "python"},
+    "cli": {"style": "argparse", "definition": None},
+    "runtime": {"config_directory": None, "defaults": {}},
+}
+
+
+def local_path(value: str, base: Path) -> Path:
+    if "://" in value:
+        raise CodaError("this generation path must be local")
+    path = Path(value).expanduser()
+    return path if path.is_absolute() else base / path
+
+
+def runtime_directory(value: str | None) -> str | None:
+    """Runtime directories are portable runtime values, never build-relative paths."""
+    if value is not None and not (
+        Path(value).is_absolute() or value == "~" or value.startswith("~/")
+    ):
+        raise CodaError("runtime config directory must be absolute or start with ~/")
+    if value is not None and any(ord(character) < 32 for character in value):
+        raise CodaError("invalid runtime config directory")
+    return value
+
+
+def clean_defaults(value: dict[str, Any]) -> dict[str, Any]:
+    result = deepcopy(value)
+    if result.get("base_url") is None:
+        result.pop("base_url", None)
+    if result.get("policy", {}).get("allow", object()) is None:
+        result["policy"].pop("allow")
+    if "base_url" in result:
+        validate_url(result["base_url"], allow_query=False)
+    return result
+
+
+def resolve_generation(
+    manifest: str | None,
+    overrides: dict[str, Any],
+    settings: list[str] | None = None,
+    *,
+    cwd: Path | None = None,
+) -> dict[str, Any]:
+    base = cwd or Path.cwd()
+    document: dict[str, Any] = {}
+    if manifest is not None:
+        path = local_path(manifest, base).absolute()
+        document = load(str(path))
+        base = path.parent
+        if type(document.get("version")) is not int or document["version"] != 1:
+            raise CodaError("generation manifest requires version: 1")
+    validator = Draft202012Validator(GENERATION_SCHEMA)
+    if not validator.is_valid(document):
+        raise CodaError("invalid generation manifest; unknown keys or unsupported values")
+    result = merge(merge(DEFAULTS, document), overrides)
+    for setting in settings or []:
+        key, separator, encoded = setting.partition("=")
+        if not separator or not re.fullmatch(r"[a-z_]+(?:\.[a-z_]+)*", key):
+            raise CodaError("--set requires a dotted manifest field and JSON value")
+        try:
+            value = parse(('{"value":' + encoded + "}").encode())["value"]
+        except CodaError:
+            raise CodaError("--set value must be valid JSON data") from None
+        # parse accepts YAML; --set intentionally accepts JSON only.
+        try:
+            json.loads(encoded)
+        except ValueError:
+            raise CodaError("--set value must be valid JSON data") from None
+        cursor = result
+        parts = key.split(".")
+        for part in parts[:-1]:
+            if not isinstance(cursor.get(part), dict):
+                cursor[part] = {}
+            cursor = cursor[part]
+        cursor[parts[-1]] = value
+    if not validator.is_valid(result):
+        raise CodaError("invalid generation overrides; unknown keys or unsupported values")
+    try:
+        source = result["contract"]["source"]
+        cli = result["cli"]
+        client = result["client"]
+        slug = slug_name(cli.get("slug", default_slug(client.get("package", "api"))))
+        package = package_name(client.get("package", slug.replace("-", "_") + "_client"))
+        if source.startswith(("http://", "https://")):
+            validate_url(source)
+        elif "://" in source:
+            raise CodaError("contract source must be a local path or HTTP(S) URL")
+        else:
+            source = str(local_path(source, base))
+        definition = cli.get("definition")
+        definition = load(str(local_path(definition, base))) if definition is not None else None
+        directory = runtime_directory(result["runtime"].get("config_directory"))
+        defaults = clean_defaults(result["runtime"].get("defaults", {}))
+        return {
+            "source": source,
+            "output": local_path(result["output"]["directory"], base),
+            "package": package,
+            "source_plugin": result["contract"]["type"],
+            "targets": (client["language"], cli["style"]),
+            "cli_definition": definition,
+            "allow_private": result["contract"]["allow_private"],
+            "profile": {
+                "version": 1,
+                "slug": slug,
+                "config_directory": directory,
+                "defaults": defaults,
+            },
+        }
+    except KeyError:
+        raise CodaError(
+            "generation requires contract.source and supported output/client/CLI fields"
+        ) from None

codapact/errors.py

@@ -0,0 +1,30 @@
+"""Stable public errors with deliberately bounded diagnostics."""
+
+
+class CodaError(Exception):
+    """A safe user-facing configuration, validation, or generation error."""
+
+
+class PolicyError(CodaError):
+    """The configured client-side policy denied an operation."""
+
+
+class AuthError(PolicyError):
+    """Required credentials are unavailable or invalid."""
+
+
+class TransportError(CodaError):
+    """The bounded transport could not complete a request."""
+
+
+class ResponseError(CodaError):
+    """A response violated the operation contract."""
+
+
+class ApiError(CodaError):
+    """An HTTP error; the response body is never included in diagnostics."""
+
+    def __init__(self, status: int, operation: str) -> None:
+        self.status = status
+        self.operation = operation
+        super().__init__(f"HTTP {status} for operation {operation}")

codapact/generation.py

@@ -0,0 +1,243 @@
+"""Deterministic Python and argparse generators; contract strings stay data."""
+
+import json
+import keyword
+import re
+import sys
+from typing import Any
+
+from codapact import __version__
+from codapact.errors import CodaError
+from codapact.model import Contract
+from codapact.values import slug_name
+
+
+def package_name(name: str) -> str:
+    if (
+        not re.fullmatch(r"[a-z][a-z0-9_]{0,49}", name)
+        or keyword.iskeyword(name)
+        or name in sys.stdlib_module_names
+        or name
+        in {
+            "codapact",
+            "yaml",
+            "jsonschema",
+            "referencing",
+            "rpds",
+            "attrs",
+            "attr",
+            "jsonschema_specifications",
+            "con",
+            "prn",
+            "aux",
+            "nul",
+        }
+        or re.fullmatch(r"(?:com|lpt)[0-9]", name)
+    ):
+        raise CodaError("package must be a safe lowercase Python identifier")
+    return name
+
+
+def canonical(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, indent=2, ensure_ascii=True, allow_nan=False) + "\n"
+
+
+class TypeEmitter:
+    def __init__(self) -> None:
+        self.lines: list[str] = []
+
+    def emit(self, schema: dict[str, Any], name: str) -> str:
+        kind = schema["type"]
+        nullable = isinstance(kind, list)
+        if nullable:
+            kind = next(value for value in kind if value != "null")
+        if kind == "object":
+            properties = schema.get("properties", {})
+            if properties:
+                fields = []
+                for index, (key, value) in enumerate(sorted(properties.items())):
+                    annotation = self.emit(value, f"{name}Field{index}")
+                    if key not in schema.get("required", []):
+                        annotation = f"NotRequired[{annotation}]"
+                    fields.append(f"{key!r}: {annotation}")
+                self.lines.append(f"{name} = TypedDict({name!r}, {{{', '.join(fields)}}})")
+                result = name
+            else:
+                additional = schema.get("additionalProperties", True)
+                item = (
+                    self.emit(additional, name + "Value") if isinstance(additional, dict) else "Any"
+                )
+                result = f"dict[str, {item}]"
+        elif kind == "array":
+            result = f"list[{self.emit(schema['items'], name + 'Item')}]"
+        else:
+            result = {"string": "str", "integer": "int", "number": "float", "boolean": "bool"}[kind]
+        return result + " | None" if nullable else result
+
+
+class PythonGenerator:
+    api_version = 1
+    requires = frozenset({"json-http-v1", "ir-v1"})
+
+    def generate(self, contract: Contract, package: str) -> dict[str, str]:
+        package = package_name(package)
+        command_name = package.replace("_", "-")
+        if "codapact.cli" in contract.metadata:
+            value = contract.metadata["codapact.cli"]
+            if not isinstance(value, str):
+                raise CodaError("invalid CLI command metadata")
+            command_name = slug_name(value)
+        if "codapact.runtime" in contract.metadata:
+            from codapact.profiles import validate_profile
+
+            validate_profile(contract.metadata["codapact.runtime"])
+        emitter = TypeEmitter()
+        methods = []
+        for operation in contract.operations:
+            prefix = f"Op_{operation.id}"
+            parameters = emitter.emit(
+                {
+                    "type": "object",
+                    "properties": {
+                        parameter["name"]: parameter["schema"] for parameter in operation.parameters
+                    },
+                    "required": [p["name"] for p in operation.parameters if p["required"]],
+                },
+                prefix + "Params",
+            )
+            body = (
+                emitter.emit(operation.body, prefix + "Body")
+                if operation.body is not None
+                else "None"
+            )
+            responses = []
+            for status, schema in sorted(operation.responses.items()):
+                if status.startswith("2"):
+                    responses.append(
+                        emitter.emit(schema, prefix + "Response" + status)
+                        if schema is not None
+                        else "None"
+                    )
+            response = " | ".join(dict.fromkeys(responses))
+            parameter_arg = (
+                f"parameters: {parameters}"
+                if any(p["required"] for p in operation.parameters)
+                else f"parameters: {parameters} | None = None"
+            )
+            body_arg = (
+                f", body: {body}"
+                if operation.body_required
+                else f", body: {body} | Unset = UNSET"
+                if operation.body is not None
+                else ""
+            )
+            body_value = "body" if operation.body is not None else "UNSET"
+            methods.append(
+                f"    def {operation.id}(self, *, {parameter_arg}{body_arg}) -> {response}:\n"
+                f"        return cast({response!r}, self._execute(\n"
+                f"            {operation.id!r}, parameters, {body_value}))\n"
+            )
+        source = (
+            "from __future__ import annotations\n\n"
+            "import json\nfrom importlib.resources import files\n"
+            "from typing import Any, NotRequired, TypedDict, cast\n"
+            "from codapact.runtime import ClientBase, UNSET, Unset\n\n"
+            + "\n".join(emitter.lines)
+            + "\n\n"
+            "DOCUMENT = json.loads(\n"
+            "    files(__package__).joinpath('contract.json').read_text('utf-8'))\n\n"
+            "class Client(ClientBase):\n"
+            "    def __init__(self, **kwargs: Any) -> None:\n"
+            "        super().__init__(DOCUMENT, **kwargs)\n\n" + "\n".join(methods)
+        )
+        return {
+            f"src/{package}/client.py": source,
+            f"src/{package}/__init__.py": "from .client import Client\n\n__all__ = ['Client']\n",
+            f"src/{package}/contract.json": canonical(contract.to_dict()),
+            f"src/{package}/py.typed": "",
+            "pyproject.toml": f'''[project]
+name = "{package.replace("_", "-")}"
+version = "0.1.0"
+requires-python = ">=3.13"
+dependencies = ["codapact=={__version__}"]
+
+[project.scripts]
+{command_name} = "{package}.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.11.1,<0.13"]
+build-backend = "uv_build"
+''',
+            ".python-version": "3.13\n",
+            "README.md": (
+                "# Generated API client\n\nGenerated with CodaPact. "
+                "Install the matching CodaPact runtime first, then `uv pip install .`.\n\n"
+                f"Run `{command_name} --help` or import `{package}.Client`.\n"
+                "Runtime config accepts environment references; never embed credentials.\n"
+            ),
+        }
+
+
+class ArgparseGenerator:
+    api_version = 1
+    requires = frozenset({"json-http-v1", "ir-v1"})
+
+    def generate(self, contract: Contract, package: str) -> dict[str, str]:
+        return self.generate_with_definition(contract, package, None)
+
+    def generate_with_definition(
+        self, contract: Contract, package: str, definition: dict[str, Any] | None
+    ) -> dict[str, str]:
+        package = package_name(package)
+        definition = (
+            {
+                "version": 1,
+                "commands": [
+                    {"name": op.id.replace("_", "-"), "operation": op.id}
+                    for op in contract.operations
+                ],
+            }
+            if definition is None
+            else definition
+        )
+        try:
+            if (
+                set(definition) != {"version", "commands"}
+                or type(definition["version"]) is not int
+                or definition["version"] != 1
+            ):
+                raise CodaError("unsupported CLI definition schema")
+            names = set()
+            operations = {op.id for op in contract.operations}
+            for command in definition["commands"]:
+                if (
+                    set(command) != {"name", "operation"}
+                    or not re.fullmatch(r"[a-z][a-z0-9-]{0,79}", command["name"])
+                    or command["name"] in names
+                    or command["operation"] not in operations
+                ):
+                    raise CodaError("invalid or duplicate CLI command")
+                names.add(command["name"])
+            if {c["operation"] for c in definition["commands"]} != operations:
+                raise CodaError("CLI definition must cover every operation")
+            for operation in contract.operations:
+                flags = [p["name"].replace("_", "-").lower() for p in operation.parameters]
+                if len(set(flags)) != len(flags):
+                    raise CodaError("CLI parameter flags collide after normalization")
+        except (TypeError, KeyError, AttributeError):
+            raise CodaError("malformed CLI definition") from None
+        source = (
+            "import json\nfrom importlib.resources import files\n"
+            "from codapact.cli import run_cli\n"
+            "from .client import Client, DOCUMENT\n\n"
+            "def main(argv=None):\n"
+            "    definition = json.loads(\n"
+            "        files(__package__).joinpath('cli.json').read_text('utf-8'))\n"
+            "    return run_cli(Client, DOCUMENT, definition, argv,\n"
+            "        profile=DOCUMENT.get('metadata', {}).get('codapact.runtime'))\n\n"
+            "if __name__ == '__main__':\n    raise SystemExit(main())\n"
+        )
+        return {
+            f"src/{package}/__main__.py": source,
+            f"src/{package}/cli.json": canonical(definition),
+        }