pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/core/loader/operations/parser.py

@@ -0,0 +1,161 @@
+"""Operation parsers for OpenAPI IR transformation.
+
+Provides the main parse_operations function to transform OpenAPI paths into IR operations.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from typing import Any, List, Mapping, cast
+
+from pyopenapi_gen import HTTPMethod, IROperation, IRParameter, IRRequestBody, IRResponse
+from pyopenapi_gen.core.loader.operations.post_processor import post_process_operation
+from pyopenapi_gen.core.loader.operations.request_body import parse_request_body
+from pyopenapi_gen.core.loader.parameters import parse_parameter, resolve_parameter_node_if_ref
+from pyopenapi_gen.core.loader.responses import parse_response
+from pyopenapi_gen.core.parsing.context import ParsingContext
+from pyopenapi_gen.core.utils import NameSanitizer
+
+logger = logging.getLogger(__name__)
+
+
+def parse_operations(
+    paths: Mapping[str, Any],
+    raw_parameters: Mapping[str, Any],
+    raw_responses: Mapping[str, Any],
+    raw_request_bodies: Mapping[str, Any],
+    context: ParsingContext,
+) -> List[IROperation]:
+    """Iterate paths to build IROperation list.
+
+    Contracts:
+        Preconditions:
+            - paths is a valid paths object from OpenAPI spec
+            - raw_parameters, raw_responses, raw_request_bodies are component mappings
+            - context is properly initialized with schemas
+        Postconditions:
+            - Returns a list of IROperation objects
+            - All operations have correct path, method, parameters, responses, etc.
+            - All referenced schemas are properly stored in context
+    """
+    if not isinstance(paths, Mapping):
+        raise TypeError("paths must be a Mapping")
+    if not isinstance(raw_parameters, Mapping):
+        raise TypeError("raw_parameters must be a Mapping")
+    if not isinstance(raw_responses, Mapping):
+        raise TypeError("raw_responses must be a Mapping")
+    if not isinstance(raw_request_bodies, Mapping):
+        raise TypeError("raw_request_bodies must be a Mapping")
+    if not isinstance(context, ParsingContext):
+        raise TypeError("context must be a ParsingContext")
+
+    ops: List[IROperation] = []
+
+    for path, item in paths.items():
+        if not isinstance(item, Mapping):
+            continue
+        entry = cast(Mapping[str, Any], item)
+
+        base_params_nodes = cast(List[Mapping[str, Any]], entry.get("parameters", []))
+
+        for method, on in entry.items():
+            try:
+                if method in {
+                    "parameters",
+                    "summary",
+                    "description",
+                    "servers",
+                    "$ref",
+                }:
+                    continue
+                mu = method.upper()
+                if mu not in HTTPMethod.__members__:
+                    continue
+
+                node_op = cast(Mapping[str, Any], on)
+
+                # Get operation_id for this specific operation
+                if "operationId" in node_op:
+                    operation_id = node_op["operationId"]
+                else:
+                    operation_id = NameSanitizer.sanitize_method_name(f"{mu}_{path}".strip("/"))
+
+                # Parse base parameters (path-level) with operation_id context
+                base_params: List[IRParameter] = []
+                for p_node_data_raw in base_params_nodes:
+                    resolved_p_node_data = resolve_parameter_node_if_ref(p_node_data_raw, context)
+                    base_params.append(
+                        parse_parameter(resolved_p_node_data, context, operation_id_for_promo=operation_id)
+                    )
+
+                # Parse operation-specific parameters
+                params: List[IRParameter] = list(base_params)  # Start with copies of path-level params
+                for p_param_node_raw in cast(List[Mapping[str, Any]], node_op.get("parameters", [])):
+                    resolved_p_param_node = resolve_parameter_node_if_ref(p_param_node_raw, context)
+                    params.append(parse_parameter(resolved_p_param_node, context, operation_id_for_promo=operation_id))
+
+                # Parse request body
+                rb: IRRequestBody | None = None
+                if "requestBody" in node_op:
+                    rb = parse_request_body(
+                        cast(Mapping[str, Any], node_op["requestBody"]),
+                        raw_request_bodies,
+                        context,
+                        operation_id,
+                    )
+
+                # Parse responses
+                resps: List[IRResponse] = []
+                for sc, rn_node in cast(Mapping[str, Any], node_op.get("responses", {})).items():
+                    if (
+                        isinstance(rn_node, Mapping)
+                        and "$ref" in rn_node
+                        and isinstance(rn_node.get("$ref"), str)
+                        and rn_node["$ref"].startswith("#/components/responses/")
+                    ):
+                        ref_name = rn_node["$ref"].split("/")[-1]
+                        resp_node_resolved = raw_responses.get(ref_name, {}) or rn_node
+                    elif (
+                        isinstance(rn_node, Mapping)
+                        and "$ref" in rn_node
+                        and isinstance(rn_node.get("$ref"), str)
+                        and rn_node["$ref"].startswith("#/components/schemas/")
+                    ):
+                        # Handle direct schema references in responses
+                        # Convert schema reference to a response with content
+                        resp_node_resolved = {
+                            "description": f"Response with {rn_node['$ref'].split('/')[-1]} schema",
+                            "content": {"application/json": {"schema": {"$ref": rn_node["$ref"]}}},
+                        }
+                    else:
+                        resp_node_resolved = rn_node
+                    resps.append(parse_response(sc, resp_node_resolved, context, operation_id_for_promo=operation_id))
+
+                op = IROperation(
+                    operation_id=operation_id,
+                    method=HTTPMethod[mu],
+                    path=path,
+                    summary=node_op.get("summary"),
+                    description=node_op.get("description"),
+                    parameters=params,
+                    request_body=rb,
+                    responses=resps,
+                    tags=list(node_op.get("tags", [])),
+                )
+            except Exception as e:
+                warnings.warn(
+                    f"Skipping operation parsing for {method.upper()} {path}: {e}",
+                    UserWarning,
+                )
+                continue
+            else:
+                # Post-process the parsed operation to fill in schema names
+                post_process_operation(op, context)
+                ops.append(op)
+
+    # Post-condition check
+    if not all(isinstance(op, IROperation) for op in ops):
+        raise TypeError("All items must be IROperation objects")
+
+    return ops

pyopenapi_gen/core/loader/operations/post_processor.py

@@ -0,0 +1,62 @@
+"""Operation post-processing utilities.
+
+Provides functions to finalize and enhance parsed operations.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pyopenapi_gen import IROperation
+from pyopenapi_gen.core.parsing.context import ParsingContext
+from pyopenapi_gen.core.utils import NameSanitizer
+
+logger = logging.getLogger(__name__)
+
+
+def post_process_operation(op: IROperation, context: ParsingContext) -> None:
+    """Post-process an operation to finalize schema names and register them.
+
+    Contracts:
+        Preconditions:
+            - op is a valid IROperation
+            - context is properly initialized
+        Postconditions:
+            - All request body and response schemas are properly named and registered
+    """
+    if not isinstance(op, IROperation):
+        raise TypeError("op must be an IROperation")
+    if not isinstance(context, ParsingContext):
+        raise TypeError("context must be a ParsingContext")
+
+    # Handle request body schemas
+    if op.request_body:
+        for _, sch_val in op.request_body.content.items():
+            if not sch_val.name:
+                generated_rb_name = NameSanitizer.sanitize_class_name(op.operation_id + "Request")
+                sch_val.name = generated_rb_name
+                context.parsed_schemas[generated_rb_name] = sch_val
+            elif sch_val.name not in context.parsed_schemas:
+                context.parsed_schemas[sch_val.name] = sch_val
+
+    # Handle response schemas
+    for resp_val in op.responses:
+        for _, sch_resp_val in resp_val.content.items():
+            if sch_resp_val.name is None:
+                if getattr(sch_resp_val, "_from_unresolved_ref", False):
+                    continue
+                is_streaming = getattr(resp_val, "stream", False)
+                if is_streaming:
+                    continue
+
+                should_synthesize_name = False
+                if sch_resp_val.type == "object" and (sch_resp_val.properties or sch_resp_val.additional_properties):
+                    should_synthesize_name = True
+
+                if should_synthesize_name:
+                    generated_name = NameSanitizer.sanitize_class_name(op.operation_id + "Response")
+                    sch_resp_val.name = generated_name
+                    context.parsed_schemas[generated_name] = sch_resp_val
+
+            elif sch_resp_val.name and sch_resp_val.name not in context.parsed_schemas:
+                context.parsed_schemas[sch_resp_val.name] = sch_resp_val

pyopenapi_gen/core/loader/operations/request_body.py

@@ -0,0 +1,90 @@
+"""Request body parsers for OpenAPI IR transformation.
+
+Provides functions to parse and transform OpenAPI request bodies into IR format.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Mapping
+
+from pyopenapi_gen import IRRequestBody, IRSchema
+from pyopenapi_gen.core.parsing.context import ParsingContext
+from pyopenapi_gen.core.parsing.schema_parser import _parse_schema
+
+logger = logging.getLogger(__name__)
+
+
+def parse_request_body(
+    rb_node: Mapping[str, Any],
+    raw_request_bodies: Mapping[str, Any],
+    context: ParsingContext,
+    operation_id: str,
+) -> IRRequestBody | None:
+    """Parse a request body node into an IRRequestBody.
+
+    Contracts:
+        Preconditions:
+            - rb_node is a valid request body node
+            - raw_request_bodies contains component request bodies
+            - context is properly initialized
+            - operation_id is provided for naming
+        Postconditions:
+            - Returns a properly populated IRRequestBody or None if invalid
+            - All content media types are properly mapped to schemas
+    """
+    if not isinstance(rb_node, Mapping):
+        raise TypeError("rb_node must be a Mapping")
+    if not isinstance(raw_request_bodies, Mapping):
+        raise TypeError("raw_request_bodies must be a Mapping")
+    if not isinstance(context, ParsingContext):
+        raise TypeError("context must be a ParsingContext")
+    if not operation_id:
+        raise ValueError("operation_id must be provided")
+
+    # Handle $ref in request body
+    if (
+        "$ref" in rb_node
+        and isinstance(rb_node.get("$ref"), str)
+        and rb_node["$ref"].startswith("#/components/requestBodies/")
+    ):
+        ref_name = rb_node["$ref"].split("/")[-1]
+        resolved_rb_node = raw_request_bodies.get(ref_name, {}) or rb_node
+    else:
+        resolved_rb_node = rb_node
+
+    required_flag = bool(resolved_rb_node.get("required", False))
+    desc = resolved_rb_node.get("description")
+    content_map: dict[str, IRSchema] = {}
+
+    parent_promo_name_for_req_body = f"{operation_id}RequestBody"
+
+    for mt, media in resolved_rb_node.get("content", {}).items():
+        media_schema_node = media.get("schema")
+        if (
+            isinstance(media_schema_node, Mapping)
+            and "$ref" not in media_schema_node
+            and (
+                media_schema_node.get("type") == "object"
+                or "properties" in media_schema_node
+                or "allOf" in media_schema_node
+                or "anyOf" in media_schema_node
+                or "oneOf" in media_schema_node
+            )
+        ):
+            content_map[mt] = _parse_schema(
+                parent_promo_name_for_req_body, media_schema_node, context, allow_self_reference=False
+            )
+        else:
+            content_map[mt] = _parse_schema(None, media_schema_node, context, allow_self_reference=False)
+
+    if not content_map:
+        return None
+
+    request_body = IRRequestBody(required=required_flag, content=content_map, description=desc)
+
+    # Post-condition check
+    if request_body.content != content_map:
+        raise RuntimeError("Request body content mismatch")
+
+    return request_body

pyopenapi_gen/core/loader/parameters/__init__.py

@@ -0,0 +1,10 @@
+"""Parameter parsing utilities.
+
+Functions to extract and transform parameters from raw OpenAPI specifications.
+"""
+
+from __future__ import annotations
+
+from .parser import parse_parameter, resolve_parameter_node_if_ref
+
+__all__ = ["parse_parameter", "resolve_parameter_node_if_ref"]

pyopenapi_gen/core/loader/parameters/parser.py

@@ -0,0 +1,186 @@
+"""Parameter parsers for OpenAPI IR transformation.
+
+Provides functions to parse and transform OpenAPI parameters into IR format.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Mapping, cast
+
+from pyopenapi_gen import IRParameter, IRSchema
+from pyopenapi_gen.core.parsing.context import ParsingContext
+from pyopenapi_gen.core.parsing.schema_parser import _parse_schema
+from pyopenapi_gen.core.utils import NameSanitizer
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_parameter_node_if_ref(param_node_data: Mapping[str, Any], context: ParsingContext) -> Mapping[str, Any]:
+    """Resolve a parameter node if it's a reference.
+
+    Contracts:
+        Preconditions:
+            - param_node_data is a valid parameter node mapping
+            - context contains the required components information
+        Postconditions:
+            - Returns the resolved parameter node or the original if not a ref
+            - If a reference, the parameter is looked up in components
+    """
+    if not isinstance(param_node_data, Mapping):
+        raise TypeError("param_node_data must be a Mapping")
+    if not isinstance(context, ParsingContext):
+        raise TypeError("context must be a ParsingContext")
+
+    if "$ref" in param_node_data and isinstance(param_node_data.get("$ref"), str):
+        ref_path = param_node_data["$ref"]
+        if ref_path.startswith("#/components/parameters/"):
+            param_name = ref_path.split("/")[-1]
+            # Access raw_spec_components from the context
+            resolved_node = context.raw_spec_components.get("parameters", {}).get(param_name)
+            if resolved_node:
+                logger.debug(f"Resolved parameter $ref '{ref_path}' to '{param_name}'")
+                return cast(Mapping[str, Any], resolved_node)
+            else:
+                logger.warning(f"Could not resolve parameter $ref '{ref_path}'")
+                return param_node_data  # Return original ref node if resolution fails
+
+    return param_node_data  # Not a ref or not a component parameter ref
+
+
+def parse_parameter(
+    node: Mapping[str, Any],
+    context: ParsingContext,
+    operation_id_for_promo: str | None = None,
+) -> IRParameter:
+    """Convert an OpenAPI parameter node into IRParameter.
+
+    Contracts:
+        Preconditions:
+            - node is a valid parameter node with required fields
+            - context is properly initialized
+            - If node has a schema, it is a valid schema definition
+        Postconditions:
+            - Returns a properly populated IRParameter
+            - Complex parameter schemas are given appropriate names
+    """
+    if not isinstance(node, Mapping):
+        raise TypeError("node must be a Mapping")
+    if "name" not in node:
+        raise ValueError("Parameter node must have a name")
+    if not isinstance(context, ParsingContext):
+        raise TypeError("context must be a ParsingContext")
+
+    sch = node.get("schema")
+    param_name = node["name"]
+
+    name_for_inline_param_schema: str | None = None
+    if (
+        sch
+        and isinstance(sch, Mapping)
+        and "$ref" not in sch
+        and (sch.get("type") == "object" or "properties" in sch or "allOf" in sch or "anyOf" in sch or "oneOf" in sch)
+    ):
+        base_param_promo_name = f"{operation_id_for_promo}Param" if operation_id_for_promo else ""
+        name_for_inline_param_schema = f"{base_param_promo_name}{NameSanitizer.sanitize_class_name(param_name)}"
+
+    # General rule: if a parameter is defined inline but a components parameter exists with the
+    # same name and location, prefer the components schema (often richer: arrays/enums/refs).
+    try:
+        if isinstance(context, ParsingContext):
+            components_params = context.raw_spec_components.get("parameters", {})
+            if isinstance(components_params, Mapping):
+                for comp_key, comp_param in components_params.items():
+                    if not isinstance(comp_param, Mapping):
+                        continue
+                    if comp_param.get("name") == param_name and comp_param.get("in") == node.get("in"):
+                        comp_schema = comp_param.get("schema")
+                        if isinstance(comp_schema, Mapping):
+                            # Prefer component schema if inline is missing or clearly less specific
+                            inline_is_specific = isinstance(sch, Mapping) and (
+                                sch.get("type") in {"array", "object"} or "$ref" in sch or "enum" in sch
+                            )
+                            if not inline_is_specific:
+                                sch = comp_schema
+                        break
+    except Exception as e:
+        # Log unexpected structure but continue with inline schema
+        logger.debug(f"Could not check component parameter for '{param_name}': {e}. Using inline schema.")
+
+    # For parameters, we want to avoid creating complex schemas for simple enum arrays
+    # Check if this is a simple enum array and handle it specially
+    if (
+        sch
+        and isinstance(sch, Mapping)
+        and sch.get("type") == "array"
+        and "items" in sch
+        and isinstance(sch["items"], Mapping)
+        and sch["items"].get("type") == "string"
+        and "enum" in sch["items"]
+        and "$ref" not in sch["items"]
+    ):
+        # This is an array of string enums - create a proper enum schema for the items
+        # Give it a name based on the parameter and operation
+        enum_name = None
+        if operation_id_for_promo and param_name:
+            # Create a name for this inline enum when we have operation context
+            enum_name = f"{operation_id_for_promo}Param{NameSanitizer.sanitize_class_name(param_name)}Item"
+        elif param_name:
+            # For component parameters without operation context, use just the parameter name
+            enum_name = f"{NameSanitizer.sanitize_class_name(param_name)}Item"
+
+        if enum_name:
+            items_schema = IRSchema(
+                name=enum_name,
+                type="string",
+                enum=sch["items"]["enum"],
+                generation_name=enum_name,  # Mark it as promoted
+                final_module_stem=NameSanitizer.sanitize_module_name(enum_name),  # Set module stem for imports
+            )
+
+            # Register this inline enum schema so it gets generated as a model file
+            if isinstance(context, ParsingContext) and enum_name not in context.parsed_schemas:
+                context.parsed_schemas[enum_name] = items_schema
+                logger.debug(
+                    f"Registered enum schema '{enum_name}' for array parameter '{param_name}' with values {sch['items']['enum'][:3]}..."
+                )
+
+            logger.debug(
+                f"Created enum schema '{enum_name}' for array parameter '{param_name}' with values {sch['items']['enum'][:3]}..."
+            )
+        else:
+            # Fallback if we don't have enough info to create a good name
+            items_schema = IRSchema(name=None, type="string", enum=sch["items"]["enum"])
+            logger.warning(
+                f"Could not create proper enum name for parameter array items with values {sch['items']['enum'][:3]}... "
+                f"This will generate a warning during type resolution."
+            )
+
+        schema_ir = IRSchema(
+            name=None,
+            type="array",
+            items=items_schema,
+            description=sch.get("description"),
+        )
+    else:
+        schema_ir = (
+            _parse_schema(name_for_inline_param_schema, sch, context, allow_self_reference=False)
+            if sch
+            else IRSchema(name=None)
+        )
+
+    param = IRParameter(
+        name=node["name"],
+        param_in=node.get("in", "query"),
+        required=bool(node.get("required", False)),
+        schema=schema_ir,
+        description=node.get("description"),
+    )
+
+    # Post-condition check
+    if param.name != node["name"]:
+        raise RuntimeError("Parameter name mismatch")
+    if param.schema is None:
+        raise RuntimeError("Parameter schema must be created")
+
+    return param

pyopenapi_gen/core/loader/responses/__init__.py

@@ -0,0 +1,10 @@
+"""Response parsing utilities.
+
+Functions to extract and transform responses from raw OpenAPI specifications.
+"""
+
+from __future__ import annotations
+
+from .parser import parse_response
+
+__all__ = ["parse_response"]

pyopenapi_gen/core/loader/responses/parser.py

@@ -0,0 +1,111 @@
+"""Response parsers for OpenAPI IR transformation.
+
+Provides functions to parse and transform OpenAPI responses into IR format.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Mapping
+
+from pyopenapi_gen import IRResponse, IRSchema
+from pyopenapi_gen.core.parsing.context import ParsingContext
+from pyopenapi_gen.core.parsing.schema_parser import _parse_schema
+
+logger = logging.getLogger(__name__)
+
+
+def parse_response(
+    code: str,
+    node: Mapping[str, Any],
+    context: ParsingContext,
+    operation_id_for_promo: str,
+) -> IRResponse:
+    """Convert an OpenAPI response node into IRResponse.
+
+    Contracts:
+        Preconditions:
+            - code is a valid HTTP status code as string
+            - node is a valid response node
+            - context is properly initialized
+            - operation_id_for_promo is provided for naming inline schemas
+        Postconditions:
+            - Returns a properly populated IRResponse
+            - All content media types are properly mapped to schemas
+            - Stream flags are correctly set based on media types
+    """
+    if not isinstance(code, str):
+        raise TypeError("code must be a string")
+    if not isinstance(node, Mapping):
+        raise TypeError("node must be a Mapping")
+    if not isinstance(context, ParsingContext):
+        raise TypeError("context must be a ParsingContext")
+    if not operation_id_for_promo:
+        raise ValueError("operation_id_for_promo must be provided")
+
+    content: dict[str, IRSchema] = {}
+    STREAM_FORMATS = {
+        "application/octet-stream": "octet-stream",
+        "text/event-stream": "event-stream",
+        "application/x-ndjson": "ndjson",
+        "application/json-seq": "json-seq",
+        "multipart/mixed": "multipart-mixed",
+    }
+    stream_flag = False
+    stream_format = None
+
+    # Construct a base name for promoting inline schemas within this response
+    parent_promo_name_for_resp_body = f"{operation_id_for_promo}{code}Response"
+
+    for mt, mn in node.get("content", {}).items():
+        if isinstance(mn, Mapping) and "$ref" in mn and mn["$ref"].startswith("#/components/schemas/"):
+            content[mt] = _parse_schema(None, mn, context, allow_self_reference=False)
+        elif isinstance(mn, Mapping) and "schema" in mn:
+            media_schema_node = mn["schema"]
+            if (
+                isinstance(media_schema_node, Mapping)
+                and "$ref" not in media_schema_node
+                and (
+                    media_schema_node.get("type") == "object"
+                    or "properties" in media_schema_node
+                    or "allOf" in media_schema_node
+                    or "anyOf" in media_schema_node
+                    or "oneOf" in media_schema_node
+                )
+            ):
+                content[mt] = _parse_schema(
+                    parent_promo_name_for_resp_body, media_schema_node, context, allow_self_reference=False
+                )
+            else:
+                content[mt] = _parse_schema(None, media_schema_node, context, allow_self_reference=False)
+        else:
+            content[mt] = IRSchema(name=None, _from_unresolved_ref=True)
+
+        fmt = STREAM_FORMATS.get(mt.lower())
+        if fmt:
+            stream_flag = True
+            stream_format = fmt
+
+    if not stream_flag:
+        for mt_val, schema_val in content.items():
+            if getattr(schema_val, "format", None) == "binary":
+                stream_flag = True
+                stream_format = "octet-stream"
+
+    response = IRResponse(
+        status_code=code,
+        description=node.get("description"),
+        content=content,
+        stream=stream_flag,
+        stream_format=stream_format,
+    )
+
+    # Post-condition checks
+    if response.status_code != code:
+        raise RuntimeError("Response status code mismatch")
+    if response.content != content:
+        raise RuntimeError("Response content mismatch")
+    if response.stream != stream_flag:
+        raise RuntimeError("Response stream flag mismatch")
+
+    return response

pyopenapi_gen/core/loader/schemas/__init__.py

@@ -0,0 +1,11 @@
+"""Schema parsing and transformation utilities.
+
+Functions to extract schemas from raw OpenAPI specifications and convert them
+into IR format.
+"""
+
+from __future__ import annotations
+
+from .extractor import build_schemas, extract_inline_enums
+
+__all__ = ["extract_inline_enums", "build_schemas"]