jentic-openapi-datamodels 1.0.0a18__py3-none-any.whl → 1.0.0a20__py3-none-any.whl

jentic/apitools/openapi/datamodels/low/v31/oauth_flows.py

@@ -0,0 +1,108 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from ruamel import yaml
+
+from ..context import Context
+from ..extractors import extract_extension_fields
+from ..fields import fixed_field, fixed_fields
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .oauth_flow import OAuthFlow
+from .oauth_flow import build as build_oauth_flow
+
+
+__all__ = ["OAuthFlows", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthFlows:
+    """
+    OAuth Flows Object representation for OpenAPI 3.1.
+
+    A container for the list of possible OAuth 2.0 authorization flows.
+    Used within Security Scheme Objects when type is set to "oauth2".
+
+    Attributes:
+        root_node: The top-level node representing the entire OAuth Flows object in the original source file
+        implicit: Configuration for the OAuth Implicit flow
+        password: Configuration for the OAuth Resource Owner Password flow
+        client_credentials: Configuration for the OAuth Client Credentials flow (application flow)
+        authorization_code: Configuration for the OAuth Authorization Code flow (three-legged OAuth)
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    implicit: FieldSource[OAuthFlow] | None = fixed_field()
+    password: FieldSource[OAuthFlow] | None = fixed_field()
+    client_credentials: FieldSource[OAuthFlow] | None = fixed_field(
+        metadata={"yaml_name": "clientCredentials"}
+    )
+    authorization_code: FieldSource[OAuthFlow] | None = fixed_field(
+        metadata={"yaml_name": "authorizationCode"}
+    )
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> OAuthFlows | ValueSource[YAMLInvalidValue]:
+    """
+    Build an OAuthFlows object from a YAML node.
+
+    Preserves all source data as-is, regardless of type. This is a low-level/plumbing
+    model that provides complete source fidelity for inspection and validation.
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        An OAuthFlows object if the node is valid, or a ValueSource containing
+        the invalid data if the root is not a MappingNode (preserving the invalid data
+        and its source location for validation).
+
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose("implicit:\\n  authorizationUrl: https://example.com/auth\\n  scopes: {}")
+        flows = build(root)
+        assert flows.implicit.value.authorization_url.value == 'https://example.com/auth'
+    """
+    context = context or Context()
+
+    if not isinstance(root, yaml.MappingNode):
+        # Preserve invalid root data instead of returning None
+        value = context.yaml_constructor.construct_object(root, deep=True)
+        return ValueSource(value=value, value_node=root)
+
+    # Get fixed specification fields for this dataclass type
+    _fixed_fields = fixed_fields(OAuthFlows)
+
+    # Build YAML name to Python field name mapping
+    yaml_to_field = {
+        field.metadata.get("yaml_name", fname): fname for fname, field in _fixed_fields.items()
+    }
+
+    # Extract field values in a single pass
+    field_values: dict[str, Any] = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Map YAML key to Python field name
+        field_name = yaml_to_field.get(key)
+        if field_name:
+            # Build OAuthFlow for this field - child builder handles invalid nodes
+            # FieldSource will auto-unwrap ValueSource if child returns it for invalid data
+            oauth_flow = build_oauth_flow(value_node, context=context)
+            field_values[field_name] = FieldSource(
+                value=oauth_flow, key_node=key_node, value_node=value_node
+            )
+
+    return OAuthFlows(
+        root_node=root,
+        implicit=field_values.get("implicit"),
+        password=field_values.get("password"),
+        client_credentials=field_values.get("client_credentials"),
+        authorization_code=field_values.get("authorization_code"),
+        extensions=extract_extension_fields(root, context),
+    )

jentic/apitools/openapi/datamodels/low/v31/openapi.py

@@ -0,0 +1,168 @@
+from dataclasses import dataclass, field, replace
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_field_source, build_model
+from .components import Components
+from .components import build as build_components
+from .external_documentation import ExternalDocumentation
+from .info import Info
+from .info import build as build_info
+from .path_item import PathItem
+from .paths import Paths
+from .paths import build as build_paths
+from .security_requirement import SecurityRequirement
+from .server import Server
+from .tag import Tag
+from .tag import build as build_tag
+
+
+__all__ = ["OpenAPI31", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAPI31:
+    """
+    OpenAPI Object representation for OpenAPI 3.1.
+
+    This is the root document object of the OpenAPI document.
+
+    Note: This class uses full duplication (not inheritance from OpenAPI30) to enable precise
+    version detection via isinstance() checks. This is critical for validators and converters
+    that need to distinguish between OpenAPI 3.0 and 3.1 specifications, as the two versions
+    have different validation rules (e.g., paths is required in 3.0 but optional in 3.1).
+
+    Attributes:
+        root_node: The top-level node representing the entire OpenAPI object in the original source file
+        openapi: REQUIRED. The version number of the OpenAPI Specification that the document uses.
+                 Must match the specification version (e.g., "3.1.0", "3.1.1", "3.1.2").
+        info: REQUIRED. Provides metadata about the API (title, version, description, etc.)
+        json_schema_dialect: The default value for the $schema keyword within Schema Objects in this OAS document.
+        servers: An array of Server Objects providing connectivity information to target servers
+        paths: The available paths and operations for the API. In OpenAPI 3.1, this is no longer strictly
+               required if components or webhooks are present.
+        webhooks: The incoming webhooks that MAY be received as part of this API and that the API consumer
+                  MAY choose to implement. A map of PathItem Objects.
+        components: An element to hold reusable objects for different aspects of the OAS
+        security: A declaration of which security mechanisms can be used across the API
+        tags: A list of tags used by the specification with additional metadata
+        external_docs: Additional external documentation
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    openapi: FieldSource[str] | None = fixed_field()
+    info: FieldSource[Info] | None = fixed_field()
+    json_schema_dialect: FieldSource[str] | None = fixed_field(
+        metadata={"yaml_name": "jsonSchemaDialect"}
+    )
+    servers: FieldSource[list["Server"]] | None = fixed_field()
+    paths: FieldSource[Paths] | None = fixed_field()
+    webhooks: FieldSource[dict[KeySource[str], "PathItem"]] | None = fixed_field()
+    components: FieldSource[Components] | None = fixed_field()
+    security: FieldSource[list["SecurityRequirement"]] | None = fixed_field()
+    tags: FieldSource[list[Tag]] | None = fixed_field()
+    external_docs: FieldSource["ExternalDocumentation"] | None = fixed_field(
+        metadata={"yaml_name": "externalDocs"}
+    )
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> OpenAPI31 | ValueSource[YAMLInvalidValue]:
+    """
+    Build an OpenAPI 3.1 object from a YAML node.
+
+    Preserves all source data as-is, regardless of type. This is a low-level/plumbing
+    model that provides complete source fidelity for inspection and validation.
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        An OpenAPI31 object if the node is valid, or a ValueSource containing
+        the invalid data if the root is not a MappingNode (preserving the invalid data
+        and its source location for validation).
+
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose('''
+        openapi: 3.1.2
+        info:
+          title: Sample API
+          version: 1.0.0
+        paths:
+          /users:
+            get:
+              responses:
+                '200':
+                  description: Success
+        webhooks:
+          newPet:
+            post:
+              requestBody:
+                description: Pet to add
+        ''')
+        openapi_doc = build(root)
+        assert openapi_doc.openapi.value == '3.1.2'
+        assert openapi_doc.info.value.title.value == 'Sample API'
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    openapi_obj = build_model(root, OpenAPI31, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(openapi_obj, OpenAPI31):
+        return openapi_obj
+
+    # Manually handle nested complex fields and list fields with custom builders
+    replacements = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "info":
+            # Handle info field - Info object
+            replacements["info"] = FieldSource(
+                value=build_info(value_node, context), key_node=key_node, value_node=value_node
+            )
+
+        elif key == "paths":
+            # Handle paths field - Paths object
+            replacements["paths"] = FieldSource(
+                value=build_paths(value_node, context), key_node=key_node, value_node=value_node
+            )
+
+        elif key == "components":
+            # Handle components field - Components object
+            replacements["components"] = FieldSource(
+                value=build_components(value_node, context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+
+        elif key == "tags":
+            # Handle tags field - array of Tag objects
+            if isinstance(value_node, yaml.SequenceNode):
+                tags_list = []
+                for tag_node in value_node.value:
+                    tag_obj = build_tag(tag_node, context)
+                    tags_list.append(tag_obj)
+                replacements["tags"] = FieldSource(
+                    value=tags_list, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a sequence - preserve as-is for validation
+                replacements["tags"] = build_field_source(key_node, value_node, context)
+
+    # Apply all replacements at once
+    if replacements:
+        openapi_obj = replace(openapi_obj, **replacements)
+
+    return openapi_obj

jentic/apitools/openapi/datamodels/low/v31/operation.py

@@ -0,0 +1,133 @@
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+from .external_documentation import ExternalDocumentation
+from .parameter import Parameter
+from .reference import Reference
+from .request_body import RequestBody, build_request_body_or_reference
+from .responses import Responses
+from .responses import build as build_responses
+from .security_requirement import SecurityRequirement
+from .server import Server
+
+
+if TYPE_CHECKING:
+    from .callback import Callback
+
+
+__all__ = ["Operation", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Operation:
+    """
+    Operation Object representation for OpenAPI 3.1.
+
+    Describes a single API operation on a path.
+
+    Attributes:
+        root_node: The top-level node representing the entire Operation object in the original source file
+        tags: List of tags for API documentation control
+        summary: Short summary of what the operation does
+        description: Verbose explanation of the operation behavior (may contain CommonMark syntax)
+        external_docs: Additional external documentation for this operation
+        operation_id: Unique string used to identify the operation
+        parameters: List of parameters that are applicable for this operation
+        request_body: Request body applicable for this operation
+        responses: REQUIRED. The list of possible responses as they are returned from executing this operation
+        callbacks: Map of possible out-of-band callbacks related to the parent operation
+        deprecated: Declares this operation to be deprecated
+        security: Declaration of which security mechanisms can be used for this operation
+        servers: Alternative server array to service this operation
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    tags: FieldSource[list[ValueSource[str]]] | None = fixed_field()
+    summary: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+    external_docs: FieldSource["ExternalDocumentation"] | None = fixed_field(
+        metadata={"yaml_name": "externalDocs"}
+    )
+    operation_id: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "operationId"})
+    parameters: FieldSource[list["Parameter | Reference"]] | None = fixed_field()
+    request_body: FieldSource[RequestBody | Reference] | None = fixed_field(
+        metadata={"yaml_name": "requestBody"}
+    )
+    responses: FieldSource[Responses] | None = fixed_field()
+    callbacks: FieldSource[dict[KeySource[str], "Callback | Reference"]] | None = fixed_field()
+    deprecated: FieldSource[bool] | None = fixed_field()
+    security: FieldSource[list["SecurityRequirement"]] | None = fixed_field()
+    servers: FieldSource[list["Server"]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Operation | ValueSource[YAMLInvalidValue]:
+    """
+    Build an Operation object from a YAML node.
+
+    Preserves all source data as-is, regardless of type. This is a low-level/plumbing
+    model that provides complete source fidelity for inspection and validation.
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        An Operation object if the node is valid, or a ValueSource containing
+        the invalid data if the root is not a MappingNode (preserving the invalid data
+        and its source location for validation).
+
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose('''
+        summary: List users
+        operationId: listUsers
+        responses:
+          '200':
+            description: successful operation
+        ''')
+        operation = build(root)
+        assert operation.summary.value == 'List users'
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    operation = build_model(root, Operation, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(operation, Operation):
+        return operation
+
+    # Manually handle nested complex fields
+    replacements = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "requestBody":
+            # Handle requestBody field - RequestBody or Reference
+            request_body_or_reference = build_request_body_or_reference(value_node, context)
+            replacements["request_body"] = FieldSource(
+                value=request_body_or_reference, key_node=key_node, value_node=value_node
+            )
+        elif key == "responses":
+            # Handle responses field - Responses object
+            responses_obj = build_responses(value_node, context)
+            replacements["responses"] = FieldSource(
+                value=responses_obj, key_node=key_node, value_node=value_node
+            )
+
+    # Apply all replacements at once
+    if replacements:
+        operation = replace(operation, **replacements)
+
+    return operation

jentic/apitools/openapi/datamodels/low/v31/parameter.py

@@ -0,0 +1,123 @@
+from dataclasses import dataclass, field
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+from .example import Example
+from .media_type import MediaType
+from .reference import Reference
+from .reference import build as build_reference
+from .schema import BooleanJSONSchema, Schema
+
+
+__all__ = ["Parameter", "build", "build_parameter_or_reference"]
+
+
+@dataclass(frozen=True, slots=True)
+class Parameter:
+    """
+    Parameter Object representation for OpenAPI 3.1.
+
+    Describes a single operation parameter. A unique parameter is defined by a combination
+    of a name and location (in).
+
+    Attributes:
+        root_node: The top-level node representing the entire Parameter object in the original source file
+        name: The name of the parameter (case-sensitive)
+        in_: The location of the parameter. Possible values are "query", "header", "path", or "cookie"
+        description: A brief description of the parameter (may contain CommonMark syntax)
+        required: Determines whether this parameter is mandatory. For path parameters, must be true.
+                 Default is false for other parameter types.
+        deprecated: Specifies that a parameter is deprecated and should be transitioned out of usage
+        allow_empty_value: Sets the ability to pass empty-valued parameters (valid only for query parameters)
+        style: Describes how the parameter value will be serialized (default depends on 'in' value)
+        explode: When true, parameter values of type array or object generate separate parameters
+        allow_reserved: Determines whether reserved characters are allowed without percent-encoding
+        schema: The schema defining the type used for the parameter
+        example: Example of the parameter's potential value
+        examples: Examples of the parameter's potential value (map of Example objects or References)
+        content: A map containing the representations for the parameter (must contain only one entry)
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    name: FieldSource[str] | None = fixed_field()
+    in_: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "in"})
+    description: FieldSource[str] | None = fixed_field()
+    required: FieldSource[bool] | None = fixed_field()
+    deprecated: FieldSource[bool] | None = fixed_field()
+    allow_empty_value: FieldSource[bool] | None = fixed_field(
+        metadata={"yaml_name": "allowEmptyValue"}
+    )
+    style: FieldSource[str] | None = fixed_field()
+    explode: FieldSource[bool] | None = fixed_field()
+    allow_reserved: FieldSource[bool] | None = fixed_field(metadata={"yaml_name": "allowReserved"})
+    schema: FieldSource["Schema | BooleanJSONSchema"] | None = fixed_field()
+    example: FieldSource[YAMLValue] | None = fixed_field()
+    examples: FieldSource[dict[KeySource[str], "Example | Reference"]] | None = fixed_field()
+    content: FieldSource[dict[KeySource[str], "MediaType"]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Parameter | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Parameter object from a YAML node.
+
+    Preserves all source data as-is, regardless of type. This is a low-level/plumbing
+    model that provides complete source fidelity for inspection and validation.
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        A Parameter object if the node is valid, or a ValueSource containing
+        the invalid data if the root is not a MappingNode (preserving the invalid data
+        and its source location for validation).
+
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose('''
+        name: userId
+        in: path
+        required: true
+        schema:
+          type: integer
+        ''')
+        parameter = build(root)
+        assert parameter.name.value == 'userId'
+    """
+    return build_model(root, Parameter, context=context)
+
+
+def build_parameter_or_reference(
+    node: yaml.Node, context: Context
+) -> Parameter | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either a Parameter or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a Parameter object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A Parameter, Reference, or ValueSource if the node is invalid
+    """
+    # Check if it's a reference (has $ref key)
+    if isinstance(node, yaml.MappingNode):
+        for key_node, _ in node.value:
+            key = context.yaml_constructor.construct_yaml_str(key_node)
+            if key == "$ref":
+                return build_reference(node, context)
+
+    # Otherwise, try to build as Parameter
+    return build(node, context)

jentic/apitools/openapi/datamodels/low/v31/path_item.py

@@ -0,0 +1,125 @@
+from dataclasses import dataclass, field, replace
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+from .operation import Operation
+from .operation import build as build_operation
+from .parameter import Parameter
+from .reference import Reference
+from .server import Server
+
+
+__all__ = ["PathItem", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class PathItem:
+    """
+    Path Item Object representation for OpenAPI 3.1.
+
+    Describes the operations available on a single path. A Path Item may be empty,
+    due to ACL constraints.
+
+    Attributes:
+        root_node: The top-level node representing the entire Path Item object in the original source file
+        ref: Allows referencing an external definition of this path item
+        summary: Optional string summary intended to apply to all operations in this path
+        description: Optional string description (may contain CommonMark syntax)
+        get: Definition of a GET operation on this path
+        put: Definition of a PUT operation on this path
+        post: Definition of a POST operation on this path
+        delete: Definition of a DELETE operation on this path
+        options: Definition of an OPTIONS operation on this path
+        head: Definition of a HEAD operation on this path
+        patch: Definition of a PATCH operation on this path
+        trace: Definition of a TRACE operation on this path
+        servers: Alternative server array to service all operations in this path
+        parameters: List of parameters that are applicable for all operations in this path
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    ref: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "$ref"})
+    summary: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+    get: FieldSource[Operation] | None = fixed_field()
+    put: FieldSource[Operation] | None = fixed_field()
+    post: FieldSource[Operation] | None = fixed_field()
+    delete: FieldSource[Operation] | None = fixed_field()
+    options: FieldSource[Operation] | None = fixed_field()
+    head: FieldSource[Operation] | None = fixed_field()
+    patch: FieldSource[Operation] | None = fixed_field()
+    trace: FieldSource[Operation] | None = fixed_field()
+    servers: FieldSource[list["Server"]] | None = fixed_field()
+    parameters: FieldSource[list["Parameter | Reference"]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> PathItem | ValueSource[YAMLInvalidValue]:
+    """
+    Build a PathItem object from a YAML node.
+
+    Preserves all source data as-is, regardless of type. This is a low-level/plumbing
+    model that provides complete source fidelity for inspection and validation.
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        A PathItem object if the node is valid, or a ValueSource containing
+        the invalid data if the root is not a MappingNode (preserving the invalid data
+        and its source location for validation).
+
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose('''
+        summary: User operations
+        get:
+          summary: List users
+          responses:
+            '200':
+              description: successful operation
+        post:
+          summary: Create user
+          responses:
+            '201':
+              description: user created
+        ''')
+        path_item = build(root)
+        assert path_item.get is not None
+        assert path_item.post is not None
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    path_item = build_model(root, PathItem, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(path_item, PathItem):
+        return path_item
+
+    # Manually handle nested complex fields
+    replacements = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Handle HTTP method operation fields
+        if key in ("get", "put", "post", "delete", "options", "head", "patch", "trace"):
+            operation_obj = build_operation(value_node, context)
+            replacements[key] = FieldSource(
+                value=operation_obj, key_node=key_node, value_node=value_node
+            )
+
+    # Apply all replacements at once
+    if replacements:
+        path_item = replace(path_item, **replacements)
+
+    return path_item