openapi-first/docs/mcp/modules/openapi_first.client.json

{
  "module": "openapi_first.client",
  "content": {
    "path": "openapi_first.client",
    "docstring": "# Summary\n\nOpenAPI-first HTTP client for contract-driven services.\n\nThis module provides `OpenAPIClient`, a thin, strict HTTP client that\nderives all callable operations directly from an OpenAPI 3.x specification.\n\nIt is the client counterpart to `OpenAPIFirstApp`.\n\nNotes:\n    **Core Principles:**\n\n        - The OpenAPI specification is the single source of truth\n        - Each operationId becomes a callable Python method\n        - No implicit schema mutation or inference\n        - No code generation step\n        - Minimal abstraction over httpx\n\n    **Responsibilities:**\n\n        - Parses an OpenAPI 3.x specification\n        - Dynamically creates one callable per operationId\n        - Enforces presence of servers, paths, and operationId\n        - Formats path parameters safely\n        - Handles JSON request bodies explicitly\n        - Returns raw `httpx.Response` objects\n\n    **Constraints:**\n\n        - This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.",
    "objects": {
      "OpenAPIFirstError": {
        "name": "OpenAPIFirstError",
        "kind": "class",
        "path": "openapi_first.client.OpenAPIFirstError",
        "signature": null,
        "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nNotes:\n    **Responsibilities:**\n\n        - This exception exists to allow callers, test suites, and CI\n          pipelines to catch and distinguish OpenAPI contract violations\n          from unrelated runtime errors.\n        - All exceptions raised by the OpenAPI-first core should inherit\n          from this type."
      },
      "OpenAPIClientError": {
        "name": "OpenAPIClientError",
        "kind": "class",
        "path": "openapi_first.client.OpenAPIClientError",
        "signature": null,
        "docstring": "Raised when an OpenAPI client operation fails."
      },
      "OpenAPIClient": {
        "name": "OpenAPIClient",
        "kind": "class",
        "path": "openapi_first.client.OpenAPIClient",
        "signature": "OpenAPIClient(spec: dict[str, Any], base_url: str | None = None, client: httpx.Client | None = None)",
        "docstring": "OpenAPI-first HTTP client (`httpx`-based).\n\nArgs:\n    spec (dict[str, Any]):\n        Parsed OpenAPI 3.x specification.\n    base_url (str | None):\n        Base URL of the target service. If omitted, the first entry in the\n        OpenAPI `servers` list is used.\n    client (httpx.Client | None):\n        Optional preconfigured httpx client instance.\n\nRaises:\n    OpenAPIClientError:\n        If no servers are defined, spec has no paths, operationIds are\n        missing/duplicate, or required parameters are missing.\n\nNotes:\n    **Responsibilities:**\n\n        - This client derives all callable methods directly from an\n          OpenAPI 3.x specification. Each `operationId` becomes a method\n          on the client instance.\n\n    **Guarantees:**\n\n        - One callable per `operationId`.\n        - Explicit parameters (path, query, headers, body).\n        - No implicit schema inference or mutation.\n        - Returns raw `httpx.Response` objects.\n        - No response validation or deserialization.\n\nExample:\n    ```python\n    from openapi_first import loader, client\n\n    spec = loader.load_openapi(\"openapi.yaml\")\n\n    api = client.OpenAPIClient(\n        spec=spec,\n        base_url=\"http://localhost:8000\",\n    )\n\n    # Call operationId: getUser\n    response = api.getUser(\n        path_params={\"user_id\": 123}\n    )\n\n    print(response.status_code)\n    print(response.json())\n    ```",
        "members": {
          "spec": {
            "name": "spec",
            "kind": "attribute",
            "path": "openapi_first.client.OpenAPIClient.spec",
            "signature": null,
            "docstring": null
          },
          "base_url": {
            "name": "base_url",
            "kind": "attribute",
            "path": "openapi_first.client.OpenAPIClient.base_url",
            "signature": null,
            "docstring": null
          },
          "client": {
            "name": "client",
            "kind": "attribute",
            "path": "openapi_first.client.OpenAPIClient.client",
            "signature": null,
            "docstring": null
          },
          "operations": {
            "name": "operations",
            "kind": "function",
            "path": "openapi_first.client.OpenAPIClient.operations",
            "signature": "operations() -> dict[str, Callable[..., httpx.Response]]",
            "docstring": null
          }
        }
      }
    }
  }
}