oas2mcp.loaders.openapi
=======================

.. py:module:: oas2mcp.loaders.openapi

.. autoapi-nested-parse::

   OpenAPI loading helpers.

   Purpose:
       Load OpenAPI specifications from URLs, local files, or raw text into plain
       Python dictionaries.

   Design:
       - Avoid runtime dependence on LangChain's ``OpenAPISpec`` parser for now.
       - Parse JSON first, then fall back to YAML.
       - Return plain dictionaries so the normalization layer can remain stable.
       - Provide backward-compatible helper names during the transition away from
         LangChain's ``OpenAPISpec`` path.

   .. rubric:: Examples

   .. code-block:: python

       from oas2mcp.loaders.openapi import load_openapi_spec_dict_from_url

       spec_dict = load_openapi_spec_dict_from_url(
           "https://petstore3.swagger.io/api/v3/openapi.json",
       )
       print(spec_dict["openapi"])



Functions
---------

.. autoapisummary::

   oas2mcp.loaders.openapi.dump_openapi_spec
   oas2mcp.loaders.openapi.load_openapi_spec
   oas2mcp.loaders.openapi.load_openapi_spec_dict
   oas2mcp.loaders.openapi.load_openapi_spec_dict_from_file
   oas2mcp.loaders.openapi.load_openapi_spec_dict_from_text
   oas2mcp.loaders.openapi.load_openapi_spec_dict_from_url
   oas2mcp.loaders.openapi.load_openapi_spec_from_file
   oas2mcp.loaders.openapi.load_openapi_spec_from_text
   oas2mcp.loaders.openapi.load_openapi_spec_from_url
   oas2mcp.loaders.openapi.normalize_api_description_dict


Module Contents
---------------

.. py:function:: dump_openapi_spec(spec: Any) -> dict[str, Any]

   Convert a spec-like object into a plain dictionary.

   :param spec: A plain dictionary or model-like object.

   :returns: A plain dictionary representation of the spec.

   :raises TypeError: If ``spec`` cannot be converted into a dictionary.

   .. rubric:: Examples

   .. code-block:: python

       data = dump_openapi_spec({"openapi": "3.1.0"})
       assert data["openapi"] == "3.1.0"


.. py:function:: load_openapi_spec(source: str | pathlib.Path, *, timeout: float = 30.0, encoding: str = 'utf-8') -> dict[str, Any]

   Backward-compatible alias for generic spec loading.


.. py:function:: load_openapi_spec_dict(source: str | pathlib.Path, *, timeout: float = 30.0, encoding: str = 'utf-8') -> dict[str, Any]

   Load an OpenAPI-compatible specification from a URL, file, or raw text.

   :param source: URL, local file path, ``file://`` URI, or raw JSON/YAML text.
   :param timeout: Request timeout used for URL loading.
   :param encoding: Text encoding used when reading local files.

   :returns: The parsed specification as a plain dictionary.

   :raises FileNotFoundError: If the source looks like a local file but is missing.
   :raises ValueError: If the source cannot be parsed as JSON or YAML.

   .. rubric:: Examples

   .. code-block:: python

       spec_dict = load_openapi_spec_dict("openapi.yaml")
       spec_dict = load_openapi_spec_dict("https://example.com/openapi.json")


.. py:function:: load_openapi_spec_dict_from_file(path: str | pathlib.Path, *, encoding: str = 'utf-8') -> dict[str, Any]

   Load an OpenAPI specification dictionary from a local file.

   :param path: The file path to the OpenAPI specification.
   :param encoding: Text encoding used when reading the file.

   :returns: The parsed OpenAPI specification as a plain dictionary.

   :raises FileNotFoundError: If the file does not exist.
   :raises ValueError: If the file is empty or cannot be parsed.

   .. rubric:: Examples

   .. code-block:: python

       spec_dict = load_openapi_spec_dict_from_file("openapi.json")


.. py:function:: load_openapi_spec_dict_from_text(text: str) -> dict[str, Any]

   Load an OpenAPI specification dictionary from raw text.

   :param text: Raw JSON or YAML OpenAPI text.

   :returns: The parsed OpenAPI specification as a plain dictionary.

   :raises ValueError: If the text is empty or cannot be parsed into a dictionary.

   .. rubric:: Examples

   .. code-block:: python

       spec_dict = load_openapi_spec_dict_from_text(
           '{"openapi":"3.1.0","info":{"title":"A","version":"1"},"paths":{}}'
       )


.. py:function:: load_openapi_spec_dict_from_url(url: str, *, timeout: float = 30.0) -> dict[str, Any]

   Load an OpenAPI specification dictionary from a URL.

   :param url: The URL of the OpenAPI specification.
   :param timeout: Request timeout in seconds.

   :returns: The parsed OpenAPI specification as a plain dictionary.

   :raises httpx.HTTPError: If the request fails.
   :raises ValueError: If the response body is empty or cannot be parsed.

   .. rubric:: Examples

   .. code-block:: python

       spec_dict = load_openapi_spec_dict_from_url(
           "https://petstore3.swagger.io/api/v3/openapi.json",
       )


.. py:function:: load_openapi_spec_from_file(path: str | pathlib.Path, *, encoding: str = 'utf-8') -> dict[str, Any]

   Backward-compatible alias for file-based spec loading.


.. py:function:: load_openapi_spec_from_text(text: str) -> dict[str, Any]

   Backward-compatible alias for text-based spec loading.


.. py:function:: load_openapi_spec_from_url(url: str, *, timeout: float = 30.0) -> dict[str, Any]

   Backward-compatible alias for URL-based spec loading.


.. py:function:: normalize_api_description_dict(data: dict[str, Any]) -> dict[str, Any]

   Normalize common API-description variants into an OpenAPI-style mapping.

   :param data: Parsed JSON/YAML API description.

   :returns: A dictionary shaped like an OpenAPI document.

   :raises ValueError: If the document is not an OpenAPI-style mapping.