pyopenapi-gen 0.8.3__py3-none-any.whl

pyopenapi_gen/core/loader/operations/post_processor.py

@@ -0,0 +1,60 @@
+"""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
+    """
+    assert isinstance(op, IROperation), "op must be an IROperation"
+    assert isinstance(context, ParsingContext), "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,85 @@
+"""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, Dict, Mapping, Optional
+
+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,
+) -> Optional[IRRequestBody]:
+    """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
+    """
+    assert isinstance(rb_node, Mapping), "rb_node must be a Mapping"
+    assert isinstance(raw_request_bodies, Mapping), "raw_request_bodies must be a Mapping"
+    assert isinstance(context, ParsingContext), "context must be a ParsingContext"
+    assert operation_id, "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
+    assert request_body.content == content_map, "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,121 @@
+"""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, Optional, 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
+    """
+    assert isinstance(param_node_data, Mapping), "param_node_data must be a Mapping"
+    assert isinstance(context, ParsingContext), "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: Optional[str] = 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
+    """
+    assert isinstance(node, Mapping), "node must be a Mapping"
+    assert "name" in node, "Parameter node must have a name"
+    assert isinstance(context, ParsingContext), "context must be a ParsingContext"
+
+    sch = node.get("schema")
+    param_name = node["name"]
+
+    name_for_inline_param_schema: Optional[str] = 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)}"
+
+    # 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 - for parameters, we can treat this as List[str]
+        # rather than creating complex named schemas
+        schema_ir = IRSchema(
+            name=None,
+            type="array",
+            items=IRSchema(name=None, type="string", enum=sch["items"]["enum"]),
+            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
+    assert param.name == node["name"], "Parameter name mismatch"
+    assert param.schema is not None, "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,104 @@
+"""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, Dict, 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
+    """
+    assert isinstance(code, str), "code must be a string"
+    assert isinstance(node, Mapping), "node must be a Mapping"
+    assert isinstance(context, ParsingContext), "context must be a ParsingContext"
+    assert operation_id_for_promo, "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
+    assert response.status_code == code, "Response status code mismatch"
+    assert response.content == content, "Response content mismatch"
+    assert response.stream == stream_flag, "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"]

pyopenapi_gen/core/loader/schemas/extractor.py

@@ -0,0 +1,184 @@
+"""Schema extractors for OpenAPI IR transformation.
+
+Provides functions to extract and transform schemas from raw OpenAPI specs.
+"""
+
+from __future__ import annotations
+
+import copy
+import logging
+from typing import Any, Dict, Mapping
+
+from pyopenapi_gen import 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 build_schemas(raw_schemas: Dict[str, Mapping[str, Any]], raw_components: Mapping[str, Any]) -> ParsingContext:
+    """Build all named schemas up front, populating a ParsingContext.
+
+    Contracts:
+        Preconditions:
+            - raw_schemas is a valid dict containing schema definitions
+            - raw_components is a valid mapping containing component definitions
+        Postconditions:
+            - A ParsingContext is returned with all schemas parsed
+            - All schemas in raw_schemas are populated in context.parsed_schemas
+    """
+    assert isinstance(raw_schemas, dict), "raw_schemas must be a dict"
+    assert isinstance(raw_components, Mapping), "raw_components must be a Mapping"
+
+    context = ParsingContext(raw_spec_schemas=raw_schemas, raw_spec_components=raw_components)
+
+    # Build initial IR for all schemas found in components
+    for n, nd in raw_schemas.items():
+        if n not in context.parsed_schemas:
+            _parse_schema(n, nd, context, allow_self_reference=True)
+
+    # Post-condition check
+    assert all(n in context.parsed_schemas for n in raw_schemas), "Not all schemas were parsed"
+
+    return context
+
+
+def extract_inline_array_items(schemas: Dict[str, IRSchema]) -> Dict[str, IRSchema]:
+    """Extract inline array item schemas as unique named schemas and update references.
+
+    Contracts:
+        Preconditions:
+            - schemas is a dict of IRSchema objects
+        Postconditions:
+            - Returns an updated schemas dict with extracted array item types
+            - All array item schemas have proper names
+            - No duplicate schema names are created
+    """
+    assert isinstance(schemas, dict), "schemas must be a dict"
+    assert all(isinstance(s, IRSchema) for s in schemas.values()), "all values must be IRSchema objects"
+
+    # Store original schema count for post-condition validation
+    original_schema_count = len(schemas)
+    original_schemas = set(schemas.keys())
+
+    new_item_schemas = {}
+    for schema_name, schema in list(schemas.items()):
+        # Check properties for array types
+        for prop_name, prop_schema in list(schema.properties.items()):
+            if prop_schema.type == "array" and prop_schema.items and not prop_schema.items.name:
+                # Only extract complex item schemas (objects and arrays), not simple primitives or references
+                items_schema = prop_schema.items
+                is_complex_item = (
+                    items_schema.type == "object"
+                    or items_schema.type == "array"
+                    or items_schema.properties
+                    or items_schema.any_of
+                    or items_schema.one_of
+                    or items_schema.all_of
+                )
+
+                if is_complex_item:
+                    # Generate a descriptive name for the item schema using content-aware naming
+                    # For arrays of complex objects, use the pattern: {Parent}{Property}Item
+                    # For arrays in response wrappers (like "data" fields), consider the content type
+                    if prop_name.lower() in ["data", "items", "results", "content"]:
+                        # For generic wrapper properties, try to derive name from the item type or parent
+                        if items_schema.type == "object" and schema_name.endswith("Response"):
+                            # Pattern: MessageBatchResponse.data -> MessageItem
+                            base_name = schema_name.replace("Response", "").replace("List", "")
+                            item_schema_name = f"{base_name}Item"
+                        else:
+                            # Fallback to standard pattern
+                            item_schema_name = (
+                                f"{NameSanitizer.sanitize_class_name(schema_name)}"
+                                f"{NameSanitizer.sanitize_class_name(prop_name)}Item"
+                            )
+                    else:
+                        # Standard pattern for named properties
+                        item_schema_name = (
+                            f"{NameSanitizer.sanitize_class_name(schema_name)}"
+                            f"{NameSanitizer.sanitize_class_name(prop_name)}Item"
+                        )
+
+                    base_item_name = item_schema_name
+                    i = 1
+                    while item_schema_name in schemas or item_schema_name in new_item_schemas:
+                        item_schema_name = f"{base_item_name}{i}"
+                        i += 1
+
+                    # Create a copy of the item schema with a name
+                    items_copy = copy.deepcopy(prop_schema.items)
+                    items_copy.name = item_schema_name
+                    new_item_schemas[item_schema_name] = items_copy
+
+                    # Update the original array schema to reference the named item schema
+                    prop_schema.items.name = item_schema_name
+
+    # Update the schemas dict with the new item schemas
+    schemas.update(new_item_schemas)
+
+    # Post-condition checks
+    assert len(schemas) >= original_schema_count, "Schemas count should not decrease"
+    assert original_schemas.issubset(set(schemas.keys())), "Original schemas should still be present"
+
+    return schemas
+
+
+def extract_inline_enums(schemas: Dict[str, IRSchema]) -> Dict[str, IRSchema]:
+    """Extract inline property enums as unique schemas and update property references.
+
+    Contracts:
+        Preconditions:
+            - schemas is a dict of IRSchema objects
+        Postconditions:
+            - Returns an updated schemas dict with extracted enum types and array item types
+            - All property schemas with enums have proper names
+            - All array item schemas have proper names
+            - No duplicate schema names are created
+    """
+    assert isinstance(schemas, dict), "schemas must be a dict"
+    assert all(isinstance(s, IRSchema) for s in schemas.values()), "all values must be IRSchema objects"
+
+    # Store original schema count for post-condition validation
+    original_schema_count = len(schemas)
+    original_schemas = set(schemas.keys())
+
+    # First extract array item schemas so they can have enums extracted in the next step
+    schemas = extract_inline_array_items(schemas)
+
+    new_enums = {}
+    for schema_name, schema in list(schemas.items()):
+        for prop_name, prop_schema in list(schema.properties.items()):
+            if prop_schema.enum and not prop_schema.name:
+                enum_name = (
+                    f"{NameSanitizer.sanitize_class_name(schema_name)}"
+                    f"{NameSanitizer.sanitize_class_name(prop_name)}Enum"
+                )
+                base_enum_name = enum_name
+                i = 1
+                while enum_name in schemas or enum_name in new_enums:
+                    enum_name = f"{base_enum_name}{i}"
+                    i += 1
+
+                enum_schema = IRSchema(
+                    name=enum_name,
+                    type=prop_schema.type,
+                    enum=copy.deepcopy(prop_schema.enum),
+                    description=prop_schema.description or f"Enum for {schema_name}.{prop_name}",
+                )
+                new_enums[enum_name] = enum_schema
+
+                # Update the original property to reference the extracted enum
+                prop_schema.name = enum_name
+                prop_schema.type = enum_name  # Make the property reference the enum by name
+                prop_schema.enum = None  # Clear the inline enum since it's now extracted
+
+    # Update the schemas dict with the new enums
+    schemas.update(new_enums)
+
+    # Post-condition checks
+    assert len(schemas) >= original_schema_count, "Schemas count should not decrease"
+    assert original_schemas.issubset(set(schemas.keys())), "Original schemas should still be present"
+
+    return schemas

pyopenapi_gen/core/pagination.py

@@ -0,0 +1,64 @@
+"""
+Pagination utilities for handling paginated API endpoints.
+
+This module provides functions for working with paginated API responses,
+turning them into convenient async iterators that automatically handle
+fetching subsequent pages.
+"""
+
+from typing import Any, AsyncIterator, Awaitable, Callable, Dict
+
+
+def paginate_by_next(
+    fetch_page: Callable[..., Awaitable[Dict[str, Any]]],
+    items_key: str = "items",
+    next_key: str = "next",
+    **params: Any,
+) -> AsyncIterator[Any]:
+    """
+    Create an async iterator that yields items from paginated API responses.
+
+    This function creates a paginator that automatically handles fetching
+    subsequent pages of results by using a "next page token" pattern. It calls
+    the provided `fetch_page` function repeatedly with the given parameters,
+    updating the next token parameter between calls.
+
+    Args:
+        fetch_page: Async function to fetch a page of results
+        items_key: The key in the response dict where items are located (default: "items")
+        next_key: The key in the response dict for the next page token (default: "next")
+        **params: Initial parameters to pass to fetch_page
+
+    Returns:
+        An AsyncIterator that yields individual items from all pages
+
+    Example:
+        ```python
+        async def fetch_users_page(page_token=None, limit=100):
+            url = f"/users?limit={limit}"
+            if page_token:
+                url += f"&page_token={page_token}"
+            return await http_client.get(url)
+
+        async for user in paginate_by_next(fetch_users_page,
+                                          items_key="users",
+                                          next_key="page_token",
+                                          limit=50):
+            print(user["name"])
+        ```
+    """
+
+    async def _paginate() -> AsyncIterator[Any]:
+        while True:
+            result = await fetch_page(**params)
+            # result is expected to be a dict
+            # (assumed since fetch_page is typed to return Dict[str, Any])
+            items = result.get(items_key, [])
+            for item in items:
+                yield item
+            token = result.get(next_key)
+            if not token:
+                break
+            params[next_key] = token
+
+    return _paginate()

pyopenapi_gen/core/parsing/__init__.py

@@ -0,0 +1,13 @@
+# Initialize the parsing module
+
+# Expose the main schema parsing entry point if desired,
+# otherwise, it remains internal (_parse_schema).
+# from .schema_parser import _parse_schema as parse_openapi_schema_node
+
+# Other parsers can be imported here if they need to be part of the public API
+# of this sub-package, though most are internal helpers for _parse_schema.
+from typing import List
+
+__all__: List[str] = [
+    # "parse_openapi_schema_node", # Example if we were to expose it
+]

pyopenapi_gen/core/parsing/common/__init__.py

@@ -0,0 +1 @@
+# common parsing utilities