mockarty 0.1.0__py3-none-any.whl

mockarty/__init__.py

@@ -0,0 +1,207 @@
+# Copyright (c) 2024-2026 Mockarty. All rights reserved.
+
+"""Mockarty Python SDK -- Official client for the Mockarty multi-protocol mock server.
+
+Quick start::
+
+    from mockarty import MockartyClient, MockBuilder, AssertAction
+
+    with MockartyClient(base_url="http://localhost:5770") as client:
+        mock = (
+            MockBuilder.http("/api/users/:id", "GET")
+            .id("user-get")
+            .respond(200, body={"id": "$.pathParam.id", "name": "$.fake.FirstName"})
+            .build()
+        )
+        result = client.mocks.create(mock)
+        print(f"Created mock: {result.mock.id}")
+"""
+
+from __future__ import annotations
+
+from mockarty.api.agent_tasks import AgentTaskAPI, AsyncAgentTaskAPI
+from mockarty.api.environments import AsyncEnvironmentAPI, EnvironmentAPI
+from mockarty.api.folders import AsyncFolderAPI, FolderAPI
+from mockarty.api.namespace_settings import (
+    AsyncNamespaceSettingsAPI,
+    NamespaceSettingsAPI,
+)
+from mockarty.api.proxy import AsyncProxyAPI, ProxyAPI
+from mockarty.api.stats import AsyncStatsAPI, StatsAPI
+from mockarty.api.tags import AsyncTagAPI, TagAPI
+from mockarty.api.undefined import AsyncUndefinedAPI, UndefinedAPI
+from mockarty.async_client import AsyncMockartyClient
+from mockarty.builders.mock_builder import MockBuilder, OneOfBuilder
+from mockarty.client import MockartyClient
+from mockarty.errors import (
+    MockartyAPIError,
+    MockartyConflictError,
+    MockartyConnectionError,
+    MockartyError,
+    MockartyForbiddenError,
+    MockartyNotFoundError,
+    MockartyRateLimitError,
+    MockartyServerError,
+    MockartyTimeoutError,
+    MockartyUnauthorizedError,
+)
+from mockarty.models.common import (
+    Collection,
+    ErrorResponse,
+    HealthResponse,
+    MockLogs,
+    Page,
+    PerfComparison,
+    PerfConfig,
+    PerfResult,
+    PerfTask,
+    RequestLog,
+    TestRunResult,
+)
+from mockarty.models.condition import AssertAction, Condition
+from mockarty.models.contexts import (
+    GraphQLRequestContext,
+    GrpcRequestContext,
+    HttpRequestContext,
+    KafkaRequestContext,
+    MCPRequestContext,
+    RabbitMQRequestContext,
+    SmtpRequestContext,
+    SoapRequestContext,
+    SocketRequestContext,
+    SSERequestContext,
+)
+from mockarty.models.contract import (
+    Contract,
+    ContractConfig,
+    ContractResult,
+    ContractValidationRequest,
+    ContractValidationResult,
+    ContractViolation,
+)
+from mockarty.models.folders import MockFolder
+from mockarty.models.fuzzing import FuzzingConfig, FuzzingResult, FuzzingRun
+from mockarty.models.generator import GeneratorPreview, GeneratorRequest, GeneratorResponse
+from mockarty.models.imports import ImportResult
+from mockarty.models.mock import (
+    Callback,
+    ContentResponse,
+    Extract,
+    Mock,
+    OneOf,
+    Proxy,
+    SaveMockResponse,
+)
+from mockarty.models.recorder import RecorderEntry, RecorderSession
+from mockarty.models.store import DeleteFromStoreRequest, StoreData, StoreEntry
+from mockarty.models.tags import Tag
+from mockarty.models.templates import TemplateFile
+from mockarty.models.testrun import TestRun
+from mockarty.models.undefined import UndefinedRequest
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "MockartyClient",
+    "AsyncMockartyClient",
+    # Builders
+    "MockBuilder",
+    "OneOfBuilder",
+    # Core models
+    "Mock",
+    "ContentResponse",
+    "OneOf",
+    "Proxy",
+    "Callback",
+    "Extract",
+    "SaveMockResponse",
+    # Conditions
+    "Condition",
+    "AssertAction",
+    # Protocol contexts
+    "HttpRequestContext",
+    "GrpcRequestContext",
+    "MCPRequestContext",
+    "SocketRequestContext",
+    "SoapRequestContext",
+    "GraphQLRequestContext",
+    "SSERequestContext",
+    "KafkaRequestContext",
+    "RabbitMQRequestContext",
+    "SmtpRequestContext",
+    # Common models
+    "Page",
+    "HealthResponse",
+    "ErrorResponse",
+    "RequestLog",
+    "MockLogs",
+    "Collection",
+    "TestRunResult",
+    "PerfConfig",
+    "PerfTask",
+    "PerfResult",
+    "PerfComparison",
+    # Store models
+    "StoreEntry",
+    "StoreData",
+    "DeleteFromStoreRequest",
+    # Generator models
+    "GeneratorRequest",
+    "GeneratorPreview",
+    "GeneratorResponse",
+    # Fuzzing models
+    "FuzzingConfig",
+    "FuzzingRun",
+    "FuzzingResult",
+    # Contract models
+    "Contract",
+    "ContractConfig",
+    "ContractResult",
+    "ContractValidationRequest",
+    "ContractValidationResult",
+    "ContractViolation",
+    # Recorder models
+    "RecorderSession",
+    "RecorderEntry",
+    # Template models
+    "TemplateFile",
+    # Import models
+    "ImportResult",
+    # Test run models
+    "TestRun",
+    # Tag models
+    "Tag",
+    # Folder models
+    "MockFolder",
+    # Undefined request models
+    "UndefinedRequest",
+    # API resource classes
+    "TagAPI",
+    "AsyncTagAPI",
+    "FolderAPI",
+    "AsyncFolderAPI",
+    "UndefinedAPI",
+    "AsyncUndefinedAPI",
+    "StatsAPI",
+    "AsyncStatsAPI",
+    "AgentTaskAPI",
+    "AsyncAgentTaskAPI",
+    "NamespaceSettingsAPI",
+    "AsyncNamespaceSettingsAPI",
+    "ProxyAPI",
+    "AsyncProxyAPI",
+    "EnvironmentAPI",
+    "AsyncEnvironmentAPI",
+    # Errors
+    "MockartyError",
+    "MockartyAPIError",
+    "MockartyNotFoundError",
+    "MockartyUnauthorizedError",
+    "MockartyForbiddenError",
+    "MockartyConflictError",
+    "MockartyRateLimitError",
+    "MockartyServerError",
+    "MockartyConnectionError",
+    "MockartyTimeoutError",
+]

mockarty/_base_client.py

@@ -0,0 +1,122 @@
+# Copyright (c) 2024-2026 Mockarty. All rights reserved.
+
+"""Shared logic for sync and async Mockarty clients."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from mockarty.errors import (
+    MockartyAPIError,
+    MockartyConflictError,
+    MockartyConnectionError,
+    MockartyError,
+    MockartyForbiddenError,
+    MockartyNotFoundError,
+    MockartyRateLimitError,
+    MockartyServerError,
+    MockartyTimeoutError,
+    MockartyUnauthorizedError,
+)
+
+# Maps HTTP status codes to specific exception classes.
+_STATUS_EXCEPTION_MAP: dict[int, type[MockartyAPIError]] = {
+    401: MockartyUnauthorizedError,
+    403: MockartyForbiddenError,
+    404: MockartyNotFoundError,
+    409: MockartyConflictError,
+    429: MockartyRateLimitError,
+}
+
+DEFAULT_BASE_URL = "http://localhost:5770"
+DEFAULT_NAMESPACE = "sandbox"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+
+def resolve_base_url(base_url: str | None) -> str:
+    """Resolve the base URL from the argument or the environment."""
+    if base_url is not None:
+        return base_url.rstrip("/")
+    return os.environ.get("MOCKARTY_BASE_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def resolve_api_key(api_key: str | None) -> str | None:
+    """Resolve the API key from the argument or the environment."""
+    if api_key is not None:
+        return api_key
+    return os.environ.get("MOCKARTY_API_KEY")
+
+
+def build_headers(api_key: str | None, namespace: str) -> dict[str, str]:
+    """Build default headers for every request."""
+    headers: dict[str, str] = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "X-Namespace": namespace,
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Inspect an httpx response and raise the appropriate SDK exception."""
+    if response.is_success:
+        return
+
+    status = response.status_code
+    request_id = response.headers.get("X-Request-Id")
+
+    # Try to extract error message from JSON body
+    try:
+        body = response.json()
+        message = body.get("error", response.text)
+    except Exception:
+        message = response.text or f"HTTP {status}"
+
+    exc_cls = _STATUS_EXCEPTION_MAP.get(status)
+    if exc_cls is not None:
+        raise exc_cls(status_code=status, message=message, request_id=request_id)
+
+    if status >= 500:
+        raise MockartyServerError(
+            status_code=status, message=message, request_id=request_id
+        )
+
+    raise MockartyAPIError(
+        status_code=status, message=message, request_id=request_id
+    )
+
+
+def wrap_transport_error(exc: Exception) -> MockartyError:  # type: ignore[return]
+    """Convert httpx transport errors into SDK exceptions."""
+    if isinstance(exc, httpx.TimeoutException):
+        raise MockartyTimeoutError(str(exc)) from exc
+    if isinstance(exc, httpx.ConnectError):
+        raise MockartyConnectionError(str(exc)) from exc
+    if isinstance(exc, (httpx.HTTPStatusError, httpx.HTTPError)):
+        raise MockartyConnectionError(str(exc)) from exc
+    raise MockartyConnectionError(str(exc)) from exc
+
+
+def build_transport(max_retries: int) -> httpx.HTTPTransport:
+    """Build an httpx transport with retry configuration."""
+    return httpx.HTTPTransport(retries=max_retries)
+
+
+def build_async_transport(max_retries: int) -> httpx.AsyncHTTPTransport:
+    """Build an async httpx transport with retry configuration."""
+    return httpx.AsyncHTTPTransport(retries=max_retries)
+
+
+def serialize_body(obj: Any) -> Any:
+    """Serialize a Pydantic model or dict to a JSON-compatible dict."""
+    if obj is None:
+        return None
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump(by_alias=True, exclude_none=True)
+    return obj

mockarty/api/__init__.py

@@ -0,0 +1,73 @@
+# Copyright (c) 2024-2026 Mockarty. All rights reserved.
+
+"""API resource classes for Mockarty client."""
+
+from mockarty.api.agent_tasks import AgentTaskAPI, AsyncAgentTaskAPI
+from mockarty.api.collections import AsyncCollectionAPI, CollectionAPI
+from mockarty.api.contracts import AsyncContractAPI, ContractAPI
+from mockarty.api.environments import AsyncEnvironmentAPI, EnvironmentAPI
+from mockarty.api.folders import AsyncFolderAPI, FolderAPI
+from mockarty.api.fuzzing import AsyncFuzzingAPI, FuzzingAPI
+from mockarty.api.generator import AsyncGeneratorAPI, GeneratorAPI
+from mockarty.api.health import AsyncHealthAPI, HealthAPI
+from mockarty.api.imports import AsyncImportAPI, ImportAPI
+from mockarty.api.mocks import AsyncMockAPI, MockAPI
+from mockarty.api.namespace_settings import (
+    AsyncNamespaceSettingsAPI,
+    NamespaceSettingsAPI,
+)
+from mockarty.api.namespaces import AsyncNamespaceAPI, NamespaceAPI
+from mockarty.api.perf import AsyncPerfAPI, PerfAPI
+from mockarty.api.proxy import AsyncProxyAPI, ProxyAPI
+from mockarty.api.recorder import AsyncRecorderAPI, RecorderAPI
+from mockarty.api.stats import AsyncStatsAPI, StatsAPI
+from mockarty.api.stores import AsyncStoreAPI, StoreAPI
+from mockarty.api.tags import AsyncTagAPI, TagAPI
+from mockarty.api.templates import AsyncTemplateAPI, TemplateAPI
+from mockarty.api.testruns import AsyncTestRunAPI, TestRunAPI
+from mockarty.api.undefined import AsyncUndefinedAPI, UndefinedAPI
+
+__all__ = [
+    "AgentTaskAPI",
+    "AsyncAgentTaskAPI",
+    "AsyncCollectionAPI",
+    "AsyncContractAPI",
+    "AsyncEnvironmentAPI",
+    "AsyncFolderAPI",
+    "AsyncFuzzingAPI",
+    "AsyncGeneratorAPI",
+    "AsyncHealthAPI",
+    "AsyncImportAPI",
+    "AsyncMockAPI",
+    "AsyncNamespaceAPI",
+    "AsyncNamespaceSettingsAPI",
+    "AsyncPerfAPI",
+    "AsyncProxyAPI",
+    "AsyncRecorderAPI",
+    "AsyncStatsAPI",
+    "AsyncStoreAPI",
+    "AsyncTagAPI",
+    "AsyncTemplateAPI",
+    "AsyncTestRunAPI",
+    "AsyncUndefinedAPI",
+    "CollectionAPI",
+    "ContractAPI",
+    "EnvironmentAPI",
+    "FolderAPI",
+    "FuzzingAPI",
+    "GeneratorAPI",
+    "HealthAPI",
+    "ImportAPI",
+    "MockAPI",
+    "NamespaceAPI",
+    "NamespaceSettingsAPI",
+    "PerfAPI",
+    "ProxyAPI",
+    "RecorderAPI",
+    "StatsAPI",
+    "StoreAPI",
+    "TagAPI",
+    "TemplateAPI",
+    "TestRunAPI",
+    "UndefinedAPI",
+]

mockarty/api/_base.py

@@ -0,0 +1,75 @@
+# Copyright (c) 2024-2026 Mockarty. All rights reserved.
+
+"""Base classes for sync and async API resources."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from mockarty._base_client import raise_for_status, serialize_body, wrap_transport_error
+
+
+class SyncAPIBase:
+    """Base class for synchronous API resource groups."""
+
+    def __init__(self, client: httpx.Client, namespace: str) -> None:
+        self._client = client
+        self._namespace = namespace
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Execute an HTTP request and raise on errors."""
+        kwargs: dict[str, Any] = {"params": params}
+        if json is not None:
+            kwargs["json"] = serialize_body(json)
+        if headers:
+            kwargs["headers"] = headers
+
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except Exception as exc:
+            wrap_transport_error(exc)
+
+        raise_for_status(response)
+        return response
+
+
+class AsyncAPIBase:
+    """Base class for asynchronous API resource groups."""
+
+    def __init__(self, client: httpx.AsyncClient, namespace: str) -> None:
+        self._client = client
+        self._namespace = namespace
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Execute an async HTTP request and raise on errors."""
+        kwargs: dict[str, Any] = {"params": params}
+        if json is not None:
+            kwargs["json"] = serialize_body(json)
+        if headers:
+            kwargs["headers"] = headers
+
+        try:
+            response = await self._client.request(method, path, **kwargs)
+        except Exception as exc:
+            wrap_transport_error(exc)
+
+        raise_for_status(response)
+        return response

mockarty/api/agent_tasks.py

@@ -0,0 +1,105 @@
+# Copyright (c) 2024-2026 Mockarty. All rights reserved.
+
+"""Agent tasks API resource for AI-assisted mock generation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mockarty.api._base import AsyncAPIBase, SyncAPIBase
+
+
+class AgentTaskAPI(SyncAPIBase):
+    """Synchronous Agent Task API resource."""
+
+    def list(self) -> list[dict[str, Any]]:
+        """List all agent tasks."""
+        resp = self._request("GET", "/api/v1/agent-tasks")
+        data = resp.json()
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict):
+            return data.get("items") or data.get("tasks") or []
+        return []
+
+    def get(self, task_id: str) -> dict[str, Any]:
+        """Get an agent task by ID."""
+        resp = self._request("GET", f"/api/v1/agent-tasks/{task_id}")
+        return resp.json()
+
+    def submit(self, task: dict[str, Any]) -> dict[str, Any]:
+        """Submit a new agent task."""
+        resp = self._request("POST", "/api/v1/agent-tasks", json=task)
+        return resp.json()
+
+    def cancel(self, task_id: str) -> None:
+        """Cancel a running agent task."""
+        self._request("POST", f"/api/v1/agent-tasks/{task_id}/cancel")
+
+    def delete(self, task_id: str) -> None:
+        """Delete an agent task."""
+        self._request("DELETE", f"/api/v1/agent-tasks/{task_id}")
+
+    def clear_all(self) -> None:
+        """Delete all agent tasks."""
+        self._request("DELETE", "/api/v1/agent-tasks")
+
+    def rerun(self, task_id: str) -> dict[str, Any]:
+        """Re-run a completed agent task."""
+        resp = self._request("POST", f"/api/v1/agent-tasks/{task_id}/rerun")
+        return resp.json()
+
+    def export(self, task_id: str) -> bytes:
+        """Export an agent task result as raw bytes."""
+        resp = self._request("GET", f"/api/v1/agent-tasks/{task_id}/export")
+        return resp.content
+
+
+class AsyncAgentTaskAPI(AsyncAPIBase):
+    """Asynchronous Agent Task API resource."""
+
+    async def list(self) -> list[dict[str, Any]]:
+        """List all agent tasks."""
+        resp = await self._request("GET", "/api/v1/agent-tasks")
+        data = resp.json()
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict):
+            return data.get("items") or data.get("tasks") or []
+        return []
+
+    async def get(self, task_id: str) -> dict[str, Any]:
+        """Get an agent task by ID."""
+        resp = await self._request("GET", f"/api/v1/agent-tasks/{task_id}")
+        return resp.json()
+
+    async def submit(self, task: dict[str, Any]) -> dict[str, Any]:
+        """Submit a new agent task."""
+        resp = await self._request("POST", "/api/v1/agent-tasks", json=task)
+        return resp.json()
+
+    async def cancel(self, task_id: str) -> None:
+        """Cancel a running agent task."""
+        await self._request("POST", f"/api/v1/agent-tasks/{task_id}/cancel")
+
+    async def delete(self, task_id: str) -> None:
+        """Delete an agent task."""
+        await self._request("DELETE", f"/api/v1/agent-tasks/{task_id}")
+
+    async def clear_all(self) -> None:
+        """Delete all agent tasks."""
+        await self._request("DELETE", "/api/v1/agent-tasks")
+
+    async def rerun(self, task_id: str) -> dict[str, Any]:
+        """Re-run a completed agent task."""
+        resp = await self._request(
+            "POST", f"/api/v1/agent-tasks/{task_id}/rerun"
+        )
+        return resp.json()
+
+    async def export(self, task_id: str) -> bytes:
+        """Export an agent task result as raw bytes."""
+        resp = await self._request(
+            "GET", f"/api/v1/agent-tasks/{task_id}/export"
+        )
+        return resp.content

mockarty/api/collections.py

@@ -0,0 +1,86 @@
+# Copyright (c) 2024-2026 Mockarty. All rights reserved.
+
+"""Collection (API Tester) API resource."""
+
+from __future__ import annotations
+
+from mockarty.api._base import AsyncAPIBase, SyncAPIBase
+from mockarty.models.common import Collection, TestRunResult
+
+
+class CollectionAPI(SyncAPIBase):
+    """Synchronous Collection API resource."""
+
+    def list(self) -> list[Collection]:
+        """List all test collections."""
+        resp = self._request("GET", "/api/v1/api-tester/collections")
+        data = resp.json()
+        if isinstance(data, list):
+            return [Collection.model_validate(c) for c in data]
+        if isinstance(data, dict):
+            items = data.get("items") or data.get("collections") or []
+            return [Collection.model_validate(c) for c in items]
+        return []
+
+    def get(self, collection_id: str) -> Collection:
+        """Get a single collection by ID."""
+        resp = self._request("GET", f"/api/v1/api-tester/collections/{collection_id}")
+        return Collection.model_validate(resp.json())
+
+    def execute(self, collection_id: str) -> TestRunResult:
+        """Execute all tests in a collection."""
+        resp = self._request("POST", f"/api/v1/api-tester/collections/{collection_id}/run")
+        return TestRunResult.model_validate(resp.json())
+
+    def execute_multiple(self, ids: list[str]) -> TestRunResult:
+        """Execute tests from multiple collections."""
+        resp = self._request(
+            "POST", "/api/v1/api-tester/collections/run-multiple", json={"collectionIds": ids}
+        )
+        return TestRunResult.model_validate(resp.json())
+
+    def export(self, collection_id: str) -> bytes:
+        """Export a collection as a downloadable archive."""
+        resp = self._request("GET", f"/api/v1/api-tester/collections/{collection_id}/export")
+        return resp.content
+
+
+class AsyncCollectionAPI(AsyncAPIBase):
+    """Asynchronous Collection API resource."""
+
+    async def list(self) -> list[Collection]:
+        """List all test collections."""
+        resp = await self._request("GET", "/api/v1/api-tester/collections")
+        data = resp.json()
+        if isinstance(data, list):
+            return [Collection.model_validate(c) for c in data]
+        if isinstance(data, dict):
+            items = data.get("items") or data.get("collections") or []
+            return [Collection.model_validate(c) for c in items]
+        return []
+
+    async def get(self, collection_id: str) -> Collection:
+        """Get a single collection by ID."""
+        resp = await self._request("GET", f"/api/v1/api-tester/collections/{collection_id}")
+        return Collection.model_validate(resp.json())
+
+    async def execute(self, collection_id: str) -> TestRunResult:
+        """Execute all tests in a collection."""
+        resp = await self._request(
+            "POST", f"/api/v1/api-tester/collections/{collection_id}/run"
+        )
+        return TestRunResult.model_validate(resp.json())
+
+    async def execute_multiple(self, ids: list[str]) -> TestRunResult:
+        """Execute tests from multiple collections."""
+        resp = await self._request(
+            "POST", "/api/v1/api-tester/collections/run-multiple", json={"collectionIds": ids}
+        )
+        return TestRunResult.model_validate(resp.json())
+
+    async def export(self, collection_id: str) -> bytes:
+        """Export a collection as a downloadable archive."""
+        resp = await self._request(
+            "GET", f"/api/v1/api-tester/collections/{collection_id}/export"
+        )
+        return resp.content