swytchcode-runtime 0.1.0__tar.gz

swytchcode_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: swytchcode-runtime
+Version: 0.1.0
+Summary: Thin runtime wrapper around the Swytchcode CLI
+Author: Swytchcode
+License: MIT
+Project-URL: repository, https://gitlab.com/swytchcode/py-runtime
+Keywords: swytchcode,cli,runtime,exec
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# swytchcode-runtime (Python)
+
+Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
+
+**Requires:** The `swytchcode` binary must be installed and on your `PATH`.
+
+## Install
+
+```bash
+pip install swytchcode-runtime
+```
+
+Or from the repo:
+
+```bash
+pip install /path/to/runtime-libraries/python-runtime
+```
+
+## Use
+
+### JSON mode (default)
+
+```python
+from swytchcode_runtime import exec
+
+result = exec("api.account.create", {"email": "test@example.com"})
+# result is parsed JSON (any)
+```
+
+Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
+
+**Request input (args):** The second argument is the kernel **args** object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
+- **body** — Request body (dict).
+- **params** — Query/path params (e.g. `{"id": "cluster-123"}`).
+- **Authorization** — Auth header value (e.g. `"Bearer token123"`).
+- **headers** — Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
+- Other top-level keys are passed as query params.
+
+Example with body, params, and headers:
+
+```python
+exec("api.cluster.get", {
+    "params": {"id": "cluster-123"},
+    "Authorization": "Bearer token123",
+    "headers": {"X-Request-Id": "abc-123"},
+})
+```
+
+### Raw mode
+
+Get stdout as a string instead of parsing JSON:
+
+```python
+from swytchcode_runtime import exec
+
+output = exec("api.report.export", {"id": "123"}, raw=True)
+# output is the raw stdout string
+```
+
+### Options
+
+- **cwd** – Working directory for the process (default: current directory).
+- **env** – Extra environment variables (merged with `os.environ`).
+- **raw** – If `True`, use `--raw` and return stdout as a string.
+- **dry_run** – If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
+- **allow_raw** – If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
+
+This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
+
+### Error handling
+
+Failures raise `SwytchcodeError` (spawn error, non-zero exit, invalid JSON). Use the helper to narrow:
+
+```python
+from swytchcode_runtime import exec, SwytchcodeError, is_swytchcode_error
+
+try:
+    exec("api.account.create", {"email": "test@example.com"})
+except Exception as e:
+    if is_swytchcode_error(e):
+        print(e.message, e.cause)
+    raise
+```
+
+## What this library is
+
+- A thin process wrapper over the Swytchcode shell.
+- A stable call surface: `exec(canonical_id, input=None, *, cwd=..., env=..., raw=...)`.
+- A convenience for developers and IDE agents.
+
+## What this library is not
+
+- An HTTP SDK or API client.
+- A replacement for the shell. All authority stays in the Swytchcode CLI.
+
+This library **must not** and **does not**:
+
+- Read `.swytchcode/*` or parse `tooling.json`.
+- Validate schemas or add retries/timeouts.
+- Call the registry or embed auth logic.
+
+It is a pipe, not a brain.
+
+## For Cursor / IDE agents
+
+Generate code that uses this runtime instead of subprocess boilerplate.
+
+**Preferred:**
+
+```python
+from swytchcode_runtime import exec
+
+def create_account(input: dict) -> any:
+    return exec("api.account.create", input)
+```
+
+**Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.

swytchcode_runtime-0.1.0/README.md

@@ -0,0 +1,117 @@
+# swytchcode-runtime (Python)
+
+Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
+
+**Requires:** The `swytchcode` binary must be installed and on your `PATH`.
+
+## Install
+
+```bash
+pip install swytchcode-runtime
+```
+
+Or from the repo:
+
+```bash
+pip install /path/to/runtime-libraries/python-runtime
+```
+
+## Use
+
+### JSON mode (default)
+
+```python
+from swytchcode_runtime import exec
+
+result = exec("api.account.create", {"email": "test@example.com"})
+# result is parsed JSON (any)
+```
+
+Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
+
+**Request input (args):** The second argument is the kernel **args** object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
+- **body** — Request body (dict).
+- **params** — Query/path params (e.g. `{"id": "cluster-123"}`).
+- **Authorization** — Auth header value (e.g. `"Bearer token123"`).
+- **headers** — Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
+- Other top-level keys are passed as query params.
+
+Example with body, params, and headers:
+
+```python
+exec("api.cluster.get", {
+    "params": {"id": "cluster-123"},
+    "Authorization": "Bearer token123",
+    "headers": {"X-Request-Id": "abc-123"},
+})
+```
+
+### Raw mode
+
+Get stdout as a string instead of parsing JSON:
+
+```python
+from swytchcode_runtime import exec
+
+output = exec("api.report.export", {"id": "123"}, raw=True)
+# output is the raw stdout string
+```
+
+### Options
+
+- **cwd** – Working directory for the process (default: current directory).
+- **env** – Extra environment variables (merged with `os.environ`).
+- **raw** – If `True`, use `--raw` and return stdout as a string.
+- **dry_run** – If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
+- **allow_raw** – If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
+
+This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
+
+### Error handling
+
+Failures raise `SwytchcodeError` (spawn error, non-zero exit, invalid JSON). Use the helper to narrow:
+
+```python
+from swytchcode_runtime import exec, SwytchcodeError, is_swytchcode_error
+
+try:
+    exec("api.account.create", {"email": "test@example.com"})
+except Exception as e:
+    if is_swytchcode_error(e):
+        print(e.message, e.cause)
+    raise
+```
+
+## What this library is
+
+- A thin process wrapper over the Swytchcode shell.
+- A stable call surface: `exec(canonical_id, input=None, *, cwd=..., env=..., raw=...)`.
+- A convenience for developers and IDE agents.
+
+## What this library is not
+
+- An HTTP SDK or API client.
+- A replacement for the shell. All authority stays in the Swytchcode CLI.
+
+This library **must not** and **does not**:
+
+- Read `.swytchcode/*` or parse `tooling.json`.
+- Validate schemas or add retries/timeouts.
+- Call the registry or embed auth logic.
+
+It is a pipe, not a brain.
+
+## For Cursor / IDE agents
+
+Generate code that uses this runtime instead of subprocess boilerplate.
+
+**Preferred:**
+
+```python
+from swytchcode_runtime import exec
+
+def create_account(input: dict) -> any:
+    return exec("api.account.create", input)
+```
+
+**Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.

swytchcode_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "swytchcode-runtime"
+version = "0.1.0"
+description = "Thin runtime wrapper around the Swytchcode CLI"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["swytchcode", "cli", "runtime", "exec"]
+authors = [{ name = "Swytchcode" }]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+repository = "https://gitlab.com/swytchcode/py-runtime"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["swytchcode_runtime*"]

swytchcode_runtime-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

swytchcode_runtime-0.1.0/swytchcode_runtime/__init__.py

@@ -0,0 +1,6 @@
+"""Thin runtime wrapper around the Swytchcode CLI."""
+
+from .errors import SwytchcodeError, is_swytchcode_error
+from .exec import exec_ as exec
+
+__all__ = ["exec", "SwytchcodeError", "is_swytchcode_error"]

swytchcode_runtime-0.1.0/swytchcode_runtime/errors.py

@@ -0,0 +1,22 @@
+"""Errors raised by the Swytchcode runtime."""
+
+from typing import Any
+
+
+class SwytchcodeError(Exception):
+    """Raised when exec() fails: spawn error, non-zero exit, or invalid JSON output."""
+
+    def __init__(self, message: str, cause: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.cause = cause
+
+    def __str__(self) -> str:
+        if self.cause is not None:
+            return f"{self.message}: {self.cause}"
+        return self.message
+
+
+def is_swytchcode_error(exc: BaseException) -> bool:
+    """Return True if exc is a SwytchcodeError."""
+    return isinstance(exc, SwytchcodeError)

swytchcode_runtime-0.1.0/swytchcode_runtime/exec.py

@@ -0,0 +1,97 @@
+"""Run swytchcode exec with optional JSON input on stdin."""
+
+import json
+import os
+import subprocess
+from typing import Any
+
+from .errors import SwytchcodeError
+
+
+def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
+    canonical_id: str,
+    input: Any = None,
+    *,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+    raw: bool = False,
+    dry_run: bool = False,
+    allow_raw: bool = False,
+) -> Any:
+    """
+    Run swytchcode exec <canonical_id> with optional JSON args on stdin.
+
+    Returns parsed JSON (default) or raw stdout as str when raw=True.
+    The swytchcode binary must be on PATH.
+
+    The input argument is the kernel args object sent on stdin. Use this shape so the
+    kernel builds the request correctly: body (request body), params (query/path params),
+    Authorization (auth header value), headers (map of header name to value); other
+    top-level keys are passed as query params.
+
+    Args:
+        canonical_id: Swytchcode canonical command ID (e.g. "api.account.create").
+        input: Optional args object; serialized as JSON to stdin. Keys: body, params,
+            Authorization, headers, and any other as query params. None for no stdin.
+        cwd: Working directory for the process. Defaults to current directory.
+        env: Extra environment variables merged with os.environ.
+        raw: If True, use --raw and return stdout as a string.
+        dry_run: If True, pass --dry-run; request details are output instead of calling the server.
+        allow_raw: If True, pass --allow-raw; required for executing raw methods (kernel default is disabled).
+
+    Returns:
+        Parsed result (any) or raw string when raw is True.
+
+    Raises:
+        SwytchcodeError: When the process fails, exits non-zero, or stdout is invalid JSON.
+    """
+    canonical_id = canonical_id.strip()
+    if not canonical_id:
+        raise SwytchcodeError("canonical_id must be a non-empty string")
+
+    flag = "--raw" if raw else "--json"
+    cmd = ["swytchcode", "exec", canonical_id, flag]
+    if dry_run:
+        cmd.append("--dry-run")
+    if allow_raw:
+        cmd.append("--allow-raw")
+
+    run_env = os.environ.copy()
+    if env:
+        run_env.update(env)
+
+    stdin_payload: bytes | None = None
+    if input is not None:
+        stdin_payload = json.dumps(input).encode("utf-8")
+
+    try:
+        result = subprocess.run(
+            cmd,
+            input=stdin_payload,
+            capture_output=True,
+            cwd=cwd or os.getcwd(),
+            env=run_env,
+            timeout=None,
+        )
+    except FileNotFoundError as e:
+        raise SwytchcodeError("Failed to spawn swytchcode", e) from e
+    except OSError as e:
+        raise SwytchcodeError("Failed to run swytchcode", e) from e
+
+    stderr = result.stderr.decode("utf-8", errors="replace").strip()
+    stdout = result.stdout.decode("utf-8", errors="replace")
+
+    if result.returncode != 0:
+        msg = stderr or "swytchcode exec failed"
+        raise SwytchcodeError(msg, result.returncode)
+
+    if raw:
+        return stdout
+
+    if not stdout.strip():
+        return None
+
+    try:
+        return json.loads(stdout)
+    except json.JSONDecodeError as e:
+        raise SwytchcodeError("Invalid JSON output from swytchcode", stdout) from e

swytchcode_runtime-0.1.0/swytchcode_runtime.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: swytchcode-runtime
+Version: 0.1.0
+Summary: Thin runtime wrapper around the Swytchcode CLI
+Author: Swytchcode
+License: MIT
+Project-URL: repository, https://gitlab.com/swytchcode/py-runtime
+Keywords: swytchcode,cli,runtime,exec
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# swytchcode-runtime (Python)
+
+Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
+
+**Requires:** The `swytchcode` binary must be installed and on your `PATH`.
+
+## Install
+
+```bash
+pip install swytchcode-runtime
+```
+
+Or from the repo:
+
+```bash
+pip install /path/to/runtime-libraries/python-runtime
+```
+
+## Use
+
+### JSON mode (default)
+
+```python
+from swytchcode_runtime import exec
+
+result = exec("api.account.create", {"email": "test@example.com"})
+# result is parsed JSON (any)
+```
+
+Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
+
+**Request input (args):** The second argument is the kernel **args** object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
+- **body** — Request body (dict).
+- **params** — Query/path params (e.g. `{"id": "cluster-123"}`).
+- **Authorization** — Auth header value (e.g. `"Bearer token123"`).
+- **headers** — Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
+- Other top-level keys are passed as query params.
+
+Example with body, params, and headers:
+
+```python
+exec("api.cluster.get", {
+    "params": {"id": "cluster-123"},
+    "Authorization": "Bearer token123",
+    "headers": {"X-Request-Id": "abc-123"},
+})
+```
+
+### Raw mode
+
+Get stdout as a string instead of parsing JSON:
+
+```python
+from swytchcode_runtime import exec
+
+output = exec("api.report.export", {"id": "123"}, raw=True)
+# output is the raw stdout string
+```
+
+### Options
+
+- **cwd** – Working directory for the process (default: current directory).
+- **env** – Extra environment variables (merged with `os.environ`).
+- **raw** – If `True`, use `--raw` and return stdout as a string.
+- **dry_run** – If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
+- **allow_raw** – If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
+
+This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
+
+### Error handling
+
+Failures raise `SwytchcodeError` (spawn error, non-zero exit, invalid JSON). Use the helper to narrow:
+
+```python
+from swytchcode_runtime import exec, SwytchcodeError, is_swytchcode_error
+
+try:
+    exec("api.account.create", {"email": "test@example.com"})
+except Exception as e:
+    if is_swytchcode_error(e):
+        print(e.message, e.cause)
+    raise
+```
+
+## What this library is
+
+- A thin process wrapper over the Swytchcode shell.
+- A stable call surface: `exec(canonical_id, input=None, *, cwd=..., env=..., raw=...)`.
+- A convenience for developers and IDE agents.
+
+## What this library is not
+
+- An HTTP SDK or API client.
+- A replacement for the shell. All authority stays in the Swytchcode CLI.
+
+This library **must not** and **does not**:
+
+- Read `.swytchcode/*` or parse `tooling.json`.
+- Validate schemas or add retries/timeouts.
+- Call the registry or embed auth logic.
+
+It is a pipe, not a brain.
+
+## For Cursor / IDE agents
+
+Generate code that uses this runtime instead of subprocess boilerplate.
+
+**Preferred:**
+
+```python
+from swytchcode_runtime import exec
+
+def create_account(input: dict) -> any:
+    return exec("api.account.create", input)
+```
+
+**Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.

swytchcode_runtime-0.1.0/swytchcode_runtime.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+swytchcode_runtime/__init__.py
+swytchcode_runtime/errors.py
+swytchcode_runtime/exec.py
+swytchcode_runtime.egg-info/PKG-INFO
+swytchcode_runtime.egg-info/SOURCES.txt
+swytchcode_runtime.egg-info/dependency_links.txt
+swytchcode_runtime.egg-info/top_level.txt

swytchcode_runtime-0.1.0/swytchcode_runtime.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

swytchcode_runtime-0.1.0/swytchcode_runtime.egg-info/top_level.txt

@@ -0,0 +1 @@
+swytchcode_runtime