oas2mcp.utils.lookup
====================

.. py:module:: oas2mcp.utils.lookup

.. autoapi-nested-parse::

   Lookup helpers for normalized catalogs.

   Purpose:
       Provide convenient query helpers over normalized ``ApiCatalog`` objects so
       later classifiers and agents can work with targeted slices of the spec.

   Design:
       - Keep helpers deterministic and side-effect free.
       - Return ``None`` for missing singular lookups rather than raising.
       - Preserve original operation objects rather than copying them.

   .. rubric:: Examples

   .. code-block:: python

       operation = get_operation(catalog, method="GET", path="/pets/{petId}")
       tagged = list_operations_by_tag(catalog, tag="pet")



Functions
---------

.. autoapisummary::

   oas2mcp.utils.lookup.get_operation
   oas2mcp.utils.lookup.get_operation_by_id
   oas2mcp.utils.lookup.get_security_scheme
   oas2mcp.utils.lookup.list_mutating_operations
   oas2mcp.utils.lookup.list_operations_by_tag
   oas2mcp.utils.lookup.list_read_operations


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

.. py:function:: get_operation(catalog: oas2mcp.models.normalized.ApiCatalog, *, method: str, path: str) -> oas2mcp.models.normalized.ApiOperation | None

   Return one operation by HTTP method and path.

   :param catalog: The normalized API catalog.
   :param method: The HTTP method to match.
   :param path: The normalized or raw operation path.

   :returns: The matching operation if found, otherwise ``None``.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       operation = get_operation(
           catalog,
           method="GET",
           path="/pets/{petId}",
       )


.. py:function:: get_operation_by_id(catalog: oas2mcp.models.normalized.ApiCatalog, *, operation_id: str) -> oas2mcp.models.normalized.ApiOperation | None

   Return one operation by ``operationId``.

   :param catalog: The normalized API catalog.
   :param operation_id: The target ``operationId``.

   :returns: The matching operation if found, otherwise ``None``.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       operation = get_operation_by_id(
           catalog,
           operation_id="getPetById",
       )


.. py:function:: get_security_scheme(catalog: oas2mcp.models.normalized.ApiCatalog, *, name: str) -> oas2mcp.models.normalized.ApiSecurityScheme | None

   Return one security scheme by name.

   :param catalog: The normalized API catalog.
   :param name: The security scheme name.

   :returns: The matching security scheme if found, otherwise ``None``.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       scheme = get_security_scheme(catalog, name="api_key")


.. py:function:: list_mutating_operations(catalog: oas2mcp.models.normalized.ApiCatalog) -> list[oas2mcp.models.normalized.ApiOperation]

   Return all mutating operations.

   :param catalog: The normalized API catalog.

   :returns: A list of mutating operations.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       mutating = list_mutating_operations(catalog)


.. py:function:: list_operations_by_tag(catalog: oas2mcp.models.normalized.ApiCatalog, *, tag: str) -> list[oas2mcp.models.normalized.ApiOperation]

   Return all operations associated with a tag.

   :param catalog: The normalized API catalog.
   :param tag: The tag name to match.

   :returns: A list of matching operations.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       pet_operations = list_operations_by_tag(catalog, tag="pet")


.. py:function:: list_read_operations(catalog: oas2mcp.models.normalized.ApiCatalog) -> list[oas2mcp.models.normalized.ApiOperation]

   Return all non-mutating operations.

   :param catalog: The normalized API catalog.

   :returns: A list of read-oriented operations.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       reads = list_read_operations(catalog)