nullspace-sdk 0.1.0__py3-none-any.whl

nullspace/__init__.py

@@ -0,0 +1,354 @@
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("nullspace-sdk")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+from .sandbox import Sandbox, AsyncSandbox, SandboxPaginator, AsyncSandboxPaginator
+from .git import GitHttpsAuth
+from .snapshot import Snapshot, AsyncSnapshot
+from .template import (
+    CommandReadinessProbe,
+    HttpReadinessProbe,
+    PortReadinessProbe,
+    Template,
+    TemplateBuild,
+    TemplateBuildStatusSnapshot,
+    TimeoutReadinessProbe,
+    default_build_logger,
+    wait_for_file,
+    wait_for_port,
+    wait_for_process,
+    wait_for_timeout,
+    wait_for_url,
+)
+from .monitor import Monitor, AsyncMonitor
+from .lifecycle import (
+    Lifecycle,
+    AsyncLifecycle,
+    LifecycleSubscription,
+    AsyncLifecycleSubscription,
+)
+from .code_interpreter import CodeInterpreter, AsyncCodeInterpreter
+from .volume import Volume, AsyncVolume
+from .types import (
+    SandboxInfo,
+    SandboxHostInfo,
+    SandboxConfig,
+    SandboxStatus,
+    SandboxListState,
+    SandboxTimeoutAction,
+    SandboxQuery,
+    SandboxState,
+    VolumeStatus,
+    VolumeInfo,
+    VolumeMount,
+    VolumeAttachment,
+    TemplateInfo,
+    TemplateTagInfo,
+    TemplateNameClaim,
+    TemplateAliasInfo,
+    TemplateVisibility,
+    TemplateNamespaceInfo,
+    TemplateNamespaceKind,
+    LogEntry,
+    LogEntryEnd,
+    LogEntryStart,
+    TemplateBuildCacheKind,
+    TemplateBuildCacheReason,
+    TemplateBuildCacheStatus,
+    TemplateBuildLogEntry,
+    TemplateBuildLogKind,
+    TemplateBuildLogLevel,
+    TemplateBuildStatus,
+    TemplateFailureDetail,
+    TemplateFailurePhase,
+    UploadKind,
+    UploadSourceKind,
+    UploadConflictPolicy,
+    UploadArchiveFormat,
+    UploadChecksumAlgorithm,
+    UploadSessionStatus,
+    UploadFailureReason,
+    UploadFailureDetail,
+    UploadLimits,
+    UploadSessionInfo,
+    CompleteUploadResponse,
+    VolumeUploadLimits,
+    VolumeUploadSessionInfo,
+    VolumeCompleteUploadResponse,
+    UploadTransport,
+    UploadResult,
+    DownloadResult,
+    UploadProgressPhase,
+    UploadProgress,
+    AsyncBackgroundCommand,
+    BackgroundCommand,
+    CommandResult,
+    GitBranches,
+    CommandLogs,
+    FileInfo,
+    BatchWriteFailure,
+    FileEvent,
+    UploadUrl,
+    SearchMatch,
+    VolumeReplaceResult,
+    ProcessInfo,
+    SnapshotInfo,
+    SandboxMetrics,
+    LifecycleAudience,
+    LifecycleStatus,
+    LifecycleOperation,
+    LifecycleActorKind,
+    LifecycleEvent,
+    LifecycleEventListResponse,
+    LifecycleWebhookDeliveryAttemptInfo,
+    LifecycleWebhookDeliveryDetail,
+    LifecycleWebhookDeliveryInfo,
+    LifecycleWebhookDeliveryStatus,
+    LifecycleWebhookInfo,
+    LifecycleStreamError,
+    MonitorSnapshotEvent,
+    MonitorUpdateEvent,
+    MonitorMetricsEvent,
+    MonitorProcessesEvent,
+    MonitorErrorEvent,
+    DisplayVirtualScreen,
+    DisplayMonitor,
+    DisplayInfo,
+    DisplayEntry,
+    WindowInfo,
+    DesktopCaptureCapabilities,
+    DesktopInputCapabilities,
+    DesktopDisplayCapabilities,
+    DesktopWindowCapabilities,
+    DesktopLaunchCapabilities,
+    DesktopOpenCapabilities,
+    DesktopClipboardCapabilities,
+    DesktopClipboardData,
+    DesktopStreamingCapabilities,
+    DesktopRecordingCapabilities,
+    DesktopCapabilities,
+    DesktopStreamInfo,
+    ManagedDesktopStreamInfo,
+    RecordingInfo,
+    PtySessionInfo,
+    PtyResult,
+    Execution,
+    CodeArtifact,
+    Result,
+    Chart,
+    BarChart,
+    LineChart,
+    PieChart,
+    ScatterChart,
+    BoxAndWhiskerChart,
+    BarChartElement,
+    LineChartElement,
+    PieChartElement,
+    ScatterChartElement,
+    BoxAndWhiskerChartElement,
+    Logs,
+    ExecutionError,
+    OutputMessage,
+    CodeContext,
+    CodeRun,
+    serialize_results,
+)
+from .errors import (
+    AuthError,
+    BuildError,
+    FileUploadError,
+    UploadChecksumError,
+    UploadConflictError,
+    UploadExpiredError,
+    UploadLimitError,
+    UploadPathError,
+    UploadStateError,
+    SandboxError,
+    TimeoutError,
+    NotFoundError,
+    PermissionError,
+    ConflictError,
+    QuotaExceededError,
+    RateLimitError,
+    NotImplementedError,
+    GitError,
+    BatchWriteError,
+)
+
+__all__ = [
+    "__version__",
+    "Sandbox",
+    "AsyncSandbox",
+    "GitHttpsAuth",
+    "Volume",
+    "AsyncVolume",
+    "Snapshot",
+    "AsyncSnapshot",
+    "Template",
+    "TemplateBuild",
+    "TemplateBuildStatusSnapshot",
+    "CommandReadinessProbe",
+    "HttpReadinessProbe",
+    "PortReadinessProbe",
+    "TimeoutReadinessProbe",
+    "default_build_logger",
+    "wait_for_file",
+    "wait_for_port",
+    "wait_for_process",
+    "wait_for_timeout",
+    "wait_for_url",
+    "Monitor",
+    "AsyncMonitor",
+    "Lifecycle",
+    "AsyncLifecycle",
+    "LifecycleSubscription",
+    "AsyncLifecycleSubscription",
+    "CodeInterpreter",
+    "AsyncCodeInterpreter",
+    "SandboxInfo",
+    "SandboxHostInfo",
+    "SandboxConfig",
+    "SandboxStatus",
+    "SandboxListState",
+    "SandboxTimeoutAction",
+    "SandboxQuery",
+    "SandboxState",
+    "SandboxPaginator",
+    "AsyncSandboxPaginator",
+    "VolumeStatus",
+    "VolumeInfo",
+    "VolumeMount",
+    "VolumeAttachment",
+    "TemplateInfo",
+    "TemplateTagInfo",
+    "TemplateNameClaim",
+    "TemplateAliasInfo",
+    "TemplateVisibility",
+    "TemplateNamespaceInfo",
+    "TemplateNamespaceKind",
+    "LogEntry",
+    "LogEntryEnd",
+    "LogEntryStart",
+    "TemplateBuildCacheKind",
+    "TemplateBuildCacheReason",
+    "TemplateBuildCacheStatus",
+    "TemplateBuildLogEntry",
+    "TemplateBuildLogKind",
+    "TemplateBuildLogLevel",
+    "TemplateBuildStatus",
+    "TemplateFailureDetail",
+    "TemplateFailurePhase",
+    "UploadKind",
+    "UploadSourceKind",
+    "UploadConflictPolicy",
+    "UploadArchiveFormat",
+    "UploadChecksumAlgorithm",
+    "UploadSessionStatus",
+    "UploadFailureReason",
+    "UploadFailureDetail",
+    "UploadLimits",
+    "UploadSessionInfo",
+    "CompleteUploadResponse",
+    "VolumeUploadLimits",
+    "VolumeUploadSessionInfo",
+    "VolumeCompleteUploadResponse",
+    "UploadTransport",
+    "UploadResult",
+    "DownloadResult",
+    "UploadProgressPhase",
+    "UploadProgress",
+    "AsyncBackgroundCommand",
+    "BackgroundCommand",
+    "CommandResult",
+    "GitBranches",
+    "CommandLogs",
+    "FileInfo",
+    "BatchWriteFailure",
+    "FileEvent",
+    "UploadUrl",
+    "SearchMatch",
+    "VolumeReplaceResult",
+    "ProcessInfo",
+    "SnapshotInfo",
+    "SandboxMetrics",
+    "LifecycleAudience",
+    "LifecycleStatus",
+    "LifecycleOperation",
+    "LifecycleActorKind",
+    "LifecycleEvent",
+    "LifecycleEventListResponse",
+    "LifecycleWebhookDeliveryAttemptInfo",
+    "LifecycleWebhookDeliveryDetail",
+    "LifecycleWebhookDeliveryInfo",
+    "LifecycleWebhookDeliveryStatus",
+    "LifecycleWebhookInfo",
+    "LifecycleStreamError",
+    "MonitorSnapshotEvent",
+    "MonitorUpdateEvent",
+    "MonitorMetricsEvent",
+    "MonitorProcessesEvent",
+    "MonitorErrorEvent",
+    "DisplayVirtualScreen",
+    "DisplayMonitor",
+    "DisplayInfo",
+    "DisplayEntry",
+    "WindowInfo",
+    "DesktopCaptureCapabilities",
+    "DesktopInputCapabilities",
+    "DesktopDisplayCapabilities",
+    "DesktopWindowCapabilities",
+    "DesktopLaunchCapabilities",
+    "DesktopOpenCapabilities",
+    "DesktopClipboardCapabilities",
+    "DesktopClipboardData",
+    "DesktopStreamingCapabilities",
+    "DesktopRecordingCapabilities",
+    "DesktopCapabilities",
+    "DesktopStreamInfo",
+    "ManagedDesktopStreamInfo",
+    "RecordingInfo",
+    "PtySessionInfo",
+    "PtyResult",
+    "Execution",
+    "CodeArtifact",
+    "Result",
+    "Chart",
+    "BarChart",
+    "LineChart",
+    "PieChart",
+    "ScatterChart",
+    "BoxAndWhiskerChart",
+    "BarChartElement",
+    "LineChartElement",
+    "PieChartElement",
+    "ScatterChartElement",
+    "BoxAndWhiskerChartElement",
+    "Logs",
+    "ExecutionError",
+    "OutputMessage",
+    "CodeContext",
+    "CodeRun",
+    "serialize_results",
+    "AuthError",
+    "BuildError",
+    "FileUploadError",
+    "UploadLimitError",
+    "UploadChecksumError",
+    "UploadConflictError",
+    "UploadExpiredError",
+    "UploadPathError",
+    "UploadStateError",
+    "SandboxError",
+    "TimeoutError",
+    "NotFoundError",
+    "PermissionError",
+    "ConflictError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "NotImplementedError",
+    "GitError",
+    "BatchWriteError",
+]

nullspace/_cli_schema.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ._exit_codes import EXIT_CODE_DESCRIPTIONS
+
+SCHEMA_VERSION = "v1"
+
+
+def build_cli_schema(root: click.Command, *, root_name: str = "nullspace") -> dict[str, Any]:
+    """Return the versioned machine-readable schema for a Click command tree."""
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "program": root_name,
+        "output_versions": ["v1"],
+        "commands": {
+            entry["id"]: entry
+            for entry in _iter_command_entries(root, root_name=root_name)
+            if entry["id"]
+        },
+        "exit_codes": [
+            {"code": code, "description": description}
+            for code, description in sorted(EXIT_CODE_DESCRIPTIONS.items())
+        ],
+        "error_envelope": {
+            "type": "object",
+            "required": ["error"],
+            "properties": {
+                "error": {
+                    "type": "object",
+                    "required": ["code", "message", "doc_url"],
+                    "properties": {
+                        "code": {"type": "string"},
+                        "message": {"type": "string"},
+                        "hint": {"type": ["string", "null"]},
+                        "doc_url": {"type": "string"},
+                        "request_id": {"type": ["string", "null"]},
+                        "retryable": {"type": ["boolean", "null"]},
+                    },
+                }
+            },
+        },
+    }
+
+
+def command_schema(
+    root: click.Command,
+    command_path: list[str] | tuple[str, ...],
+    *,
+    root_name: str = "nullspace",
+) -> dict[str, Any]:
+    """Return a single command entry selected by command path."""
+    command = _resolve_command(root, command_path)
+    path = list(command_path)
+    return _command_entry(command, path=path, root_name=root_name)
+
+
+def command_ids(root: click.Command) -> list[str]:
+    return [entry["id"] for entry in _iter_command_entries(root, root_name="nullspace") if entry["id"]]
+
+
+def _iter_command_entries(
+    command: click.Command,
+    *,
+    root_name: str,
+    path: list[str] | None = None,
+) -> list[dict[str, Any]]:
+    path = path or []
+    entries = [_command_entry(command, path=path, root_name=root_name)]
+    if isinstance(command, click.Group):
+        for name, child in sorted(command.commands.items()):
+            if getattr(child, "hidden", False):
+                continue
+            entries.extend(
+                _iter_command_entries(
+                    child,
+                    root_name=root_name,
+                    path=[*path, name],
+                )
+            )
+    return entries
+
+
+def _command_entry(command: click.Command, *, path: list[str], root_name: str) -> dict[str, Any]:
+    params = [_param_entry(param) for param in command.params]
+    return {
+        "id": ".".join(path),
+        "name": path[-1] if path else root_name,
+        "kind": "group" if isinstance(command, click.Group) else "command",
+        "path": path,
+        "full_path": " ".join([root_name, *path]),
+        "summary": _first_sentence(command.short_help or command.help or ""),
+        "help": command.help or "",
+        "examples": [],
+        "params": params,
+        "flags": [param for param in params if param["kind"] == "option"],
+        "arguments": [param for param in params if param["kind"] == "argument"],
+        "error_codes": _default_error_codes(path),
+        "output": {
+            "version": "v1",
+            "success": "command-specific JSON when --json is supported; otherwise human text",
+            "failure": "error_envelope",
+        },
+        "json_schema": _input_json_schema(params),
+    }
+
+
+def _resolve_command(root: click.Command, command_path: list[str] | tuple[str, ...]) -> click.Command:
+    current = root
+    for part in command_path:
+        if not isinstance(current, click.Group):
+            raise click.UsageError(f"{' '.join(command_path)!r} is not a command group")
+        next_command = current.commands.get(part)
+        if next_command is None:
+            raise click.UsageError(f"unknown command path: {' '.join(command_path)}")
+        current = next_command
+    return current
+
+
+def _param_entry(param: click.Parameter) -> dict[str, Any]:
+    if isinstance(param, click.Option):
+        names = [*param.opts, *param.secondary_opts]
+        return {
+            "kind": "option",
+            "name": param.name,
+            "flags": names,
+            "primary_flag": param.opts[0] if param.opts else None,
+            "type": _click_type_name(param.type),
+            "json_schema": _param_json_schema(param),
+            "default": _json_default(param.default),
+            "required": param.required,
+            "multiple": bool(param.multiple),
+            "is_flag": bool(param.is_flag),
+            "description": param.help or "",
+        }
+    return {
+        "kind": "argument",
+        "name": param.name,
+        "type": _click_type_name(param.type),
+        "json_schema": _param_json_schema(param),
+        "default": None,
+        "required": param.required,
+        "multiple": bool(getattr(param, "nargs", 1) == -1),
+        "description": "",
+    }
+
+
+def _input_json_schema(params: list[dict[str, Any]]) -> dict[str, Any]:
+    properties = {}
+    required = []
+    for param in params:
+        properties[param["name"]] = param["json_schema"]
+        if param["required"]:
+            required.append(param["name"])
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def _param_json_schema(param: click.Parameter) -> dict[str, Any]:
+    schema = _type_json_schema(param.type)
+    if isinstance(param, click.Option) and param.is_flag:
+        schema = {"type": "boolean"}
+    if getattr(param, "multiple", False) or getattr(param, "nargs", 1) == -1:
+        schema = {"type": "array", "items": schema}
+    return schema
+
+
+def _type_json_schema(param_type: click.ParamType) -> dict[str, Any]:
+    if isinstance(param_type, click.Choice):
+        return {"type": "string", "enum": list(param_type.choices)}
+    if isinstance(param_type, click.IntRange):
+        schema: dict[str, Any] = {"type": "integer"}
+        if param_type.min is not None:
+            schema["minimum"] = param_type.min
+        if param_type.max is not None:
+            schema["maximum"] = param_type.max
+        return schema
+    if isinstance(param_type, click.types.FloatRange):
+        schema = {"type": "number"}
+        if param_type.min is not None:
+            schema["minimum"] = param_type.min
+        if param_type.max is not None:
+            schema["maximum"] = param_type.max
+        return schema
+    name = _click_type_name(param_type)
+    if name in {"integer", "int"}:
+        return {"type": "integer"}
+    if name in {"float"}:
+        return {"type": "number"}
+    if name in {"boolean", "bool"}:
+        return {"type": "boolean"}
+    return {"type": "string"}
+
+
+def _click_type_name(param_type: click.ParamType) -> str:
+    return getattr(param_type, "name", None) or param_type.__class__.__name__.lower()
+
+
+def _json_default(value: Any) -> Any:
+    if callable(value):
+        return None
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, tuple):
+        return [_json_default(item) for item in value]
+    if isinstance(value, list):
+        return [_json_default(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _json_default(item) for key, item in value.items()}
+    return None
+
+
+def _first_sentence(value: str) -> str:
+    return " ".join(value.strip().split())
+
+
+def _default_error_codes(path: list[str]) -> list[str]:
+    codes = ["invalid_request", "missing_api_key", "unauthorized", "rate_limit_exceeded"]
+    if path:
+        resource = path[0].replace("-", "_")
+        codes.append(f"{resource}_not_found")
+    return list(dict.fromkeys(codes))

nullspace/_config.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+DEFAULT_BASE_URL = "http://localhost:3000"
+
+
+def resolve_api_key(explicit: str | None = None) -> str | None:
+    if explicit is not None:
+        return explicit.strip()
+    return (
+        _env_value("NULLSPACE_API_KEY")
+        or _project_env().get("NULLSPACE_API_KEY")
+        or _config_value("api_key")
+    )
+
+
+def resolve_base_url(explicit: str | None = None) -> str:
+    if explicit is not None:
+        return explicit.strip() or DEFAULT_BASE_URL
+    return (
+        _env_value("NULLSPACE_API_URL")
+        or _env_value("NULLSPACE_BASE_URL")
+        or _project_env().get("NULLSPACE_API_URL")
+        or _project_env().get("NULLSPACE_BASE_URL")
+        or _config_value("base_url")
+        or _config_value("api_url")
+        or DEFAULT_BASE_URL
+    )
+
+
+def _env_value(name: str) -> str | None:
+    value = os.environ.get(name)
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+def _project_env() -> dict[str, str]:
+    path = Path.cwd() / ".env"
+    if not path.is_file():
+        return {}
+    values: dict[str, str] = {}
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            key = key.strip()
+            value = value.strip().strip("'\"")
+            if key:
+                values[key] = value
+    except OSError:
+        return {}
+    return values
+
+
+def _config_value(name: str) -> str | None:
+    for path in _config_paths():
+        value = _read_config_value(path, name)
+        if value:
+            return value
+    return None
+
+
+def _config_paths() -> list[Path]:
+    home = Path(os.path.expanduser("~"))
+    xdg = Path(os.environ.get("XDG_CONFIG_HOME", home / ".config"))
+    return [
+        xdg / "nullspace" / "config.json",
+        home / ".nullspace" / "config.json",
+    ]
+
+
+def _read_config_value(path: Path, name: str) -> str | None:
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    value = data.get(name)
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    return value or None