jentic-openapi-datamodels 1.0.0a12__py3-none-any.whl → 1.0.0a13__py3-none-any.whl

jentic/apitools/openapi/datamodels/low/v30/tag.py

@@ -1,132 +1,101 @@
-"""
-OpenAPI 3.0.4 Tag Object model.
-
-Adds metadata to a single tag that is used by operations.
-"""
-
-from collections.abc import Mapping
-from typing import Any
-
+from dataclasses import dataclass, field, replace
+
+from ruamel import yaml
+
+from jentic.apitools.openapi.datamodels.low.context import Context
+from jentic.apitools.openapi.datamodels.low.fields import fixed_field
+from jentic.apitools.openapi.datamodels.low.model_builder import build_model
+from jentic.apitools.openapi.datamodels.low.sources import (
+    FieldSource,
+    KeySource,
+    ValueSource,
+    YAMLInvalidValue,
+    YAMLValue,
+)
 from jentic.apitools.openapi.datamodels.low.v30.external_documentation import (
     ExternalDocumentation,
 )
-from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+from jentic.apitools.openapi.datamodels.low.v30.external_documentation import (
+    build as build_external_documentation,
+)
 
 
-__all__ = ["Tag"]
+__all__ = ["Tag", "build"]
 
 
-class Tag(SpecificationObject):
+@dataclass(frozen=True, slots=True)
+class Tag:
     """
-    Represents a Tag Object from OpenAPI 3.0.4.
+    Tag Object representation for OpenAPI 3.0.
 
-    Adds metadata to a single tag that is used by the Operation Object.
-    It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.
+    Adds metadata to a single tag that is used by the Operation Object. It is not mandatory
+    to have a Tag Object per tag defined in the Operation Object instances.
 
-    Supports specification extensions (x-* fields).
+    Attributes:
+        root_node: The top-level node representing the entire Tag object in the original source file
+        name: The name of the tag. REQUIRED.
+        description: A short description for the tag. CommonMark syntax MAY be used for rich text representation.
+        external_docs: Additional external documentation for this tag.
+        extensions: Specification extensions (x-* fields)
+    """
 
-    Example:
-        >>> # Basic tag
-        >>> tag = Tag({
-        ...     "name": "pet",
-        ...     "description": "Everything about your Pets"
-        ... })
-        >>> tag.name
-        'pet'
-        >>> tag.description
-        'Everything about your Pets'
-
-        >>> # Tag with external docs
-        >>> tag = Tag({
-        ...     "name": "store",
-        ...     "description": "Access to Petstore orders",
-        ...     "externalDocs": {
-        ...         "description": "Find out more",
-        ...         "url": "http://example.com"
-        ...     }
-        ... })
-        >>> tag.external_docs.url
-        'http://example.com'
+    root_node: yaml.Node
+    name: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | 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) -> Tag | ValueSource[YAMLInvalidValue]:
     """
+    Build a Tag 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.
 
-    _supports_extensions: bool = True
-    _fixed_fields: frozenset[str] = frozenset({"name", "description", "externalDocs"})
-
-    def __init__(self, data: Mapping[str, Any] | None = None):
-        """
-        Initialize a Tag object.
-
-        Automatically marshals nested externalDocs data (Mapping) into ExternalDocumentation instance.
-
-        Args:
-            data: Optional mapping to initialize the object with
-        """
-        super().__init__()
-        if data:
-            for key, value in data.items():
-                # Marshal externalDocs field specifically if it's a raw Mapping
-                if (
-                    key == "externalDocs"
-                    and isinstance(value, Mapping)
-                    and not isinstance(value, ExternalDocumentation)
-                ):
-                    self[key] = ExternalDocumentation(value)
-                else:
-                    # Store as-is (already ExternalDocumentation, extension, or other)
-                    self[key] = self._copy_value(value)
-
-    @property
-    def name(self) -> str | None:
-        """
-        The name of the tag.
-
-        REQUIRED field.
-
-        Returns:
-            Tag name or None if not present
-        """
-        return self.get("name")
-
-    @name.setter
-    def name(self, value: str | None) -> None:
-        """Set the tag name."""
-        if value is None:
-            self.pop("name", None)
-        else:
-            self["name"] = value
-
-    @property
-    def description(self) -> str | None:
-        """
-        A description for the tag.
-
-        Returns:
-            Description or None if not present
-        """
-        return self.get("description")
-
-    @description.setter
-    def description(self, value: str | None) -> None:
-        """Set the description."""
-        if value is None:
-            self.pop("description", None)
-        else:
-            self["description"] = value
-
-    @property
-    def external_docs(self) -> ExternalDocumentation | None:
-        """
-        Additional external documentation for this tag.
-
-        Returns:
-            ExternalDocumentation instance or None if not present
-        """
-        return self.get("externalDocs")
-
-    @external_docs.setter
-    def external_docs(self, value: ExternalDocumentation | None) -> None:
-        """Set the external documentation."""
-        if value is None:
-            self.pop("externalDocs", None)
-        else:
-            self["externalDocs"] = value
+    Returns:
+        A Tag 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: pet\\ndescription: Everything about your Pets")
+        tag = build(root)
+        assert tag.name.value == 'pet'
+    """
+    # Initialize context once at the beginning
+    if context is None:
+        context = 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)
+
+    # Use build_model to handle most fields
+    tag = build_model(root, Tag, context=context)
+
+    # Manually handle special fields that build_model can't process (nested objects)
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "externalDocs":
+            # Handle nested ExternalDocumentation object - child builder handles invalid nodes
+            # FieldSource will auto-unwrap ValueSource if child returns it for invalid data
+            external_docs = FieldSource(
+                value=build_external_documentation(value_node, context=context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+            tag = replace(tag, external_docs=external_docs)
+            break
+
+    return tag

jentic/apitools/openapi/datamodels/low/v30/xml.py

@@ -1,134 +1,60 @@
-"""
-OpenAPI 3.0.4 XML Object model.
+from dataclasses import dataclass, field
 
-Metadata object for XML representation of properties.
-"""
+from ruamel import yaml
 
-from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+from jentic.apitools.openapi.datamodels.low.context import Context
+from jentic.apitools.openapi.datamodels.low.fields import fixed_field
+from jentic.apitools.openapi.datamodels.low.model_builder import build_model
+from jentic.apitools.openapi.datamodels.low.sources import (
+    FieldSource,
+    KeySource,
+    ValueSource,
+    YAMLInvalidValue,
+    YAMLValue,
+)
 
 
-__all__ = ["XML"]
+__all__ = ["XML", "build"]
 
 
-class XML(SpecificationObject):
+@dataclass(frozen=True, slots=True)
+class XML:
     """
-    Represents an XML Object from OpenAPI 3.0.4.
-
-    A metadata object that allows for more fine-tuned XML model definitions.
-
-    Supports specification extensions (x-* fields).
-
-    Example:
-        >>> # Basic XML element name override
-        >>> xml = XML({"name": "animal"})
-        >>> xml.name
-        'animal'
-
-        >>> # XML namespace
-        >>> xml = XML({
-        ...     "name": "Person",
-        ...     "namespace": "http://example.com/schema/person",
-        ...     "prefix": "sample"
-        ... })
-        >>> xml.namespace
-        'http://example.com/schema/person'
+    XML Object representation for OpenAPI 3.0.
+
+    Attributes:
+        root_node: The top-level node representing the entire XML object in the original source file
+        name: Name of the XML element
+        namespace: XML namespace
+        prefix: XML namespace prefix
+        attribute: Whether property is an attribute (deprecated in OpenAPI 3.2+)
+        wrapped: Whether array is wrapped
+        extensions: Specification extensions
     """
 
-    _supports_extensions: bool = True
-    _fixed_fields: frozenset[str] = frozenset(
-        {"name", "namespace", "prefix", "attribute", "wrapped"}
-    )
-
-    @property
-    def name(self) -> str | None:
-        """
-        Replaces the name of the element/attribute.
-
-        Returns:
-            Element/attribute name or None if not present
-        """
-        return self.get("name")
-
-    @name.setter
-    def name(self, value: str | None) -> None:
-        """Set the element/attribute name."""
-        if value is None:
-            self.pop("name", None)
-        else:
-            self["name"] = value
-
-    @property
-    def namespace(self) -> str | None:
-        """
-        The URI of the namespace definition.
-
-        Returns:
-            Namespace URI or None if not present
-        """
-        return self.get("namespace")
+    root_node: yaml.Node
+    name: FieldSource[str] | None = fixed_field()
+    namespace: FieldSource[str] | None = fixed_field()
+    prefix: FieldSource[str] | None = fixed_field()
+    attribute: FieldSource[bool] | None = fixed_field()
+    wrapped: FieldSource[bool] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
 
-    @namespace.setter
-    def namespace(self, value: str | None) -> None:
-        """Set the namespace URI."""
-        if value is None:
-            self.pop("namespace", None)
-        else:
-            self["namespace"] = value
 
-    @property
-    def prefix(self) -> str | None:
-        """
-        The prefix to be used for the name.
-
-        Returns:
-            Prefix or None if not present
-        """
-        return self.get("prefix")
-
-    @prefix.setter
-    def prefix(self, value: str | None) -> None:
-        """Set the prefix."""
-        if value is None:
-            self.pop("prefix", None)
-        else:
-            self["prefix"] = value
-
-    @property
-    def attribute(self) -> bool | None:
-        """
-        Declares whether the property is an XML attribute.
-
-        Returns:
-            True if the property is an XML attribute,
-            False if present and set to false,
-            or None if not present.
-        """
-        return self.get("attribute")
-
-    @attribute.setter
-    def attribute(self, value: bool | None) -> None:
-        """Set the attribute flag."""
-        if value is None:
-            self.pop("attribute", None)
-        else:
-            self["attribute"] = value
-
-    @property
-    def wrapped(self) -> bool | None:
-        """
-        For arrays, wraps the array in a containing element.
+def build(root: yaml.Node, context: Context | None = None) -> XML | ValueSource[YAMLInvalidValue]:
+    """
+    Build an XML object from a YAML node.
 
-        Only affects arrays. Returns None when not set.
+    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.
 
-        Returns:
-            True if wrapped, None if not set or not wrapped
-        """
-        return self.get("wrapped")
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
 
-    @wrapped.setter
-    def wrapped(self, value: bool | None) -> None:
-        """Set the wrapped flag."""
-        if value is None:
-            self.pop("wrapped", None)
-        else:
-            self["wrapped"] = value
+    Returns:
+        An XML 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).
+    """
+    return build_model(root, XML, context=context)

jentic_openapi_datamodels-1.0.0a13.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: jentic-openapi-datamodels
+Version: 1.0.0a13
+Summary: Jentic OpenAPI Data Models
+Author: Jentic
+Author-email: Jentic <hello@jentic.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: ruamel-yaml~=0.18.15
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/jentic/jentic-openapi-tools
+Description-Content-Type: text/markdown
+
+from semantic_release.cli.commands.version import build_distributions
+
+# jentic-openapi-datamodels
+
+Low-level and high-level data models for OpenAPI specifications.
+
+This package provides data model classes for representing OpenAPI specification objects in Python.
+
+## Features
+
+**Low-Level Architecture**
+- **Preserve Everything**: All data from source documents preserved exactly as-is, including invalid values
+- **Zero Validation**: No validation or coercion during parsing - deferred to higher layers
+- **Separation of Concerns**: Low-level model focuses on faithful representation; validation belongs elsewhere
+
+**Source Tracking**
+- **Complete Source Fidelity**: Every field tracks its exact YAML node location
+- **Precise Error Reporting**: Line and column numbers via `start_mark` and `end_mark`
+- **Metadata Preservation**: Full position tracking for accurate diagnostics
+
+**Python Integration**
+- **Python-Idiomatic Naming**: snake_case field names (e.g., `bearer_format`, `property_name`)
+- **Spec-Aligned Mapping**: Automatic YAML name mapping (e.g., `bearerFormat` ↔ `bearer_format`)
+- **Type Safety**: Full type hints with Generic types (`FieldSource[T]`, `KeySource[T]`, `ValueSource[T]`)
+
+**Extensibility**
+- **Extension Support**: Automatic extraction of OpenAPI `x-*` specification extensions
+- **Unknown Field Tracking**: Capture typos and invalid fields for validation tools
+- **Generic Builder Pattern**: Core `build_model()` function with object-specific builders for complex cases
+
+**Performance**
+- **Memory Efficient**: Immutable frozen dataclasses with `__slots__` for optimal memory usage
+- **Shared Context**: All instances share a single YAML constructor for efficiency
+
+**Version Support**
+- **OpenAPI 2.0**: Planned for future release
+- **OpenAPI 3.0.x**: Currently implemented
+- **OpenAPI 3.1.x**: Planned for future release
+- **OpenAPI 3.2.x**: Planned for future release
+
+## Installation
+
+```bash
+pip install jentic-openapi-datamodels
+```
+
+**Prerequisites:**
+- Python 3.11+
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from ruamel.yaml import YAML
+from jentic.apitools.openapi.datamodels.low.v30.security_scheme import build
+
+# Parse YAML
+yaml = YAML()
+root = yaml.compose("""
+type: http
+scheme: bearer
+bearerFormat: JWT
+""")
+
+# Build low-level model
+security_scheme = build(root)
+
+# Access via Python field names (snake_case)
+print(security_scheme.bearer_format.value)  # "JWT"
+
+# Access source location information
+print(security_scheme.bearer_format.key_node.value)  # "bearerFormat"
+print(security_scheme.bearer_format.key_node.start_mark.line)  # Line number
+```
+
+### Field Name Mapping
+
+YAML `camelCase` fields automatically map to Python `snake_case`:
+- `bearerFormat` → `bearer_format`
+- `authorizationUrl` → `authorization_url`
+- `openIdConnectUrl` → `openid_connect_url`
+
+Special cases for Python reserved keywords/special characters:
+- `$ref` → `ref`
+- `in` → `in_`
+
+### Source Tracking
+
+The package provides three immutable wrapper types for preserving source information:
+
+**FieldSource[T]** - For OpenAPI fields with key-value pairs
+- Used for: Fixed fields (`name`, `bearer_format`) and patterned fields (status codes, path items, schema properties)
+- Tracks: Both key and value nodes
+- Example: `SecurityScheme.bearer_format` is `FieldSource[str]`, response status codes are `FieldSource[Response]`
+
+**KeySource[T]** - For dictionary keys
+- Used for: keys in OpenAPI fields, `x-*` extensions and mapping dictionaries
+- Tracks: Only key node
+- Example: Keys in `Discriminator.mapping` are `KeySource[str]`
+
+**ValueSource[T]** - For dictionary values and array items
+- Used for: values in OpenAPI fields, in `x-*` extensions, mapping dictionaries and array items
+- Tracks: Only value node
+- Example: Values in `Discriminator.mapping` are `ValueSource[str]`
+
+```python
+from ruamel.yaml import YAML
+from jentic.apitools.openapi.datamodels.low.v30.security_scheme import build as build_security_scheme
+from jentic.apitools.openapi.datamodels.low.v30.discriminator import build as build_discriminator
+
+# FieldSource: Fixed specification fields
+yaml = YAML()
+root = yaml.compose("type: http\nscheme: bearer\nbearerFormat: JWT")
+security_scheme = build_security_scheme(root)
+
+field = security_scheme.bearer_format  # FieldSource[str]
+print(field.value)  # "JWT" - The actual value
+print(field.key_node)  # YAML node for "bearerFormat"
+print(field.value_node)  # YAML node for "JWT"
+
+# KeySource/ValueSource: Dictionary fields (mapping, extensions)
+root = yaml.compose("propertyName: petType\nmapping:\n  dog: Dog\n  cat: Cat")
+discriminator = build_discriminator(root)
+
+for key, value in discriminator.mapping.value.items():
+    print(key.value)  # KeySource[str]: "dog" or "cat"
+    print(key.key_node)  # YAML node for the key
+    print(value.value)  # ValueSource[str]: "Dog" or "Cat"
+    print(value.value_node)  # YAML node for the value
+```
+
+### Location Ranges
+
+Access precise location ranges within the source document using start_mark and end_mark:
+
+```python
+from ruamel.yaml import YAML
+from jentic.apitools.openapi.datamodels.low.v30.security_scheme import build as build_security_scheme
+
+yaml_content = """
+type: http
+scheme: bearer
+bearerFormat: JWT
+description: Bearer token authentication
+"""
+
+yaml = YAML()
+root = yaml.compose(yaml_content)
+security_scheme = build_security_scheme(root)
+
+# Access location information for any field
+field = security_scheme.bearer_format
+
+# Key location (e.g., "bearerFormat")
+print(f"Key start: line {field.key_node.start_mark.line}, col {field.key_node.start_mark.column}")
+print(f"Key end: line {field.key_node.end_mark.line}, col {field.key_node.end_mark.column}")
+
+# Value location (e.g., "JWT")
+print(f"Value start: line {field.value_node.start_mark.line}, col {field.value_node.start_mark.column}")
+print(f"Value end: line {field.value_node.end_mark.line}, col {field.value_node.end_mark.column}")
+
+# Full field range (from key start to value end)
+start = field.key_node.start_mark
+end = field.value_node.end_mark
+print(f"Field range: ({start.line}:{start.column}) to ({end.line}:{end.column})")
+```
+
+### Invalid Data Handling
+
+Low-level models preserve invalid data:
+
+```python
+from ruamel.yaml import YAML
+from jentic.apitools.openapi.datamodels.low.v30.security_scheme import build as build_security_scheme
+
+yaml = YAML()
+root = yaml.compose("bearerFormat: 123")  # Wrong type (should be string)
+
+security_scheme = build_security_scheme(root)
+print(security_scheme.bearer_format.value)  # 123 (preserved as-is)
+print(type(security_scheme.bearer_format.value))  # <class 'int'>
+```
+
+### Error Reporting
+
+This architecture—where the low-level model preserves data without validation and validation tools consume 
+that data—allows the low-level model to remain simple while enabling sophisticated validation tools to provide
+user-friendly error messages with exact source locations.
+
+## Testing
+
+Run the test suite:
+
+```bash
+uv run --package jentic-openapi-datamodels pytest packages/jentic-openapi-datamodels -v
+```

jentic_openapi_datamodels-1.0.0a13.dist-info/RECORD

@@ -0,0 +1,23 @@
+jentic/apitools/openapi/datamodels/low/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jentic/apitools/openapi/datamodels/low/context.py,sha256=pAuPf8GmdttXMEeuO4clAvTTxH7LMtEHdxoo1RpyK2c,555
+jentic/apitools/openapi/datamodels/low/extractors.py,sha256=ACtSbRRzICi9cjLzldcwN4GDuieT_JvW81lPZ44mq6c,4954
+jentic/apitools/openapi/datamodels/low/fields.py,sha256=g1Sta-eN4JDg_AnuJxe1MeWS3Ut81A5dw_ZIdyGrgbk,1448
+jentic/apitools/openapi/datamodels/low/model_builder.py,sha256=NwfGtJBjYK9SJkYJBkfvgV2oxmVpZB5KIV5P-bt1B4s,4683
+jentic/apitools/openapi/datamodels/low/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jentic/apitools/openapi/datamodels/low/sources.py,sha256=H4I6LSn-Ry6cJageIyhCvE0H85O7Lh94gdCIm60wj0E,2924
+jentic/apitools/openapi/datamodels/low/v30/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jentic/apitools/openapi/datamodels/low/v30/discriminator.py,sha256=GVIyNbaoMVhkfavfFhKvlFHvwcIiSDPHKVAmgV9_7pQ,2537
+jentic/apitools/openapi/datamodels/low/v30/external_documentation.py,sha256=5H2SeBkTH4MPakQPyy2NrSuPoh1n64OzeFVbfpyrh28,2448
+jentic/apitools/openapi/datamodels/low/v30/oauth_flow.py,sha256=u6VnU4pMfu-Atg2Ooslp0ladGGhfw3VEjLHgMqZHRn8,2906
+jentic/apitools/openapi/datamodels/low/v30/oauth_flows.py,sha256=gXgCmvYQ0d5v36VeGw2MqkIG20dbClfWIN7IDMq8V_c,4652
+jentic/apitools/openapi/datamodels/low/v30/reference.py,sha256=zwz09f_sgzj5a1KV0V5IwhB313Se5JYX1pr5FaJaxZU,2134
+jentic/apitools/openapi/datamodels/low/v30/schema.py,sha256=57LkSe1OuyQugtX5aM3UAy0qLgaOVyQzdbdYyQtDqBs,15188
+jentic/apitools/openapi/datamodels/low/v30/security_requirement.py,sha256=beYB2TrfflvxnVO83b2iNzVKrInupJ_59zsvM8NYj-k,4032
+jentic/apitools/openapi/datamodels/low/v30/security_scheme.py,sha256=tPOfcx0sh0w-gMMwtOxjybduRb7q-oI8PTq1SDS8ozg,4819
+jentic/apitools/openapi/datamodels/low/v30/tag.py,sha256=FenkPaMCMAXZWJkA2heWewhxB2etKA-opuas494fUhA,3831
+jentic/apitools/openapi/datamodels/low/v30/xml.py,sha256=1LjV-JsU5MqEFPV9e-zVKyJ9qt7QfwWjGN3oVLGxsnQ,2109
+jentic_openapi_datamodels-1.0.0a13.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+jentic_openapi_datamodels-1.0.0a13.dist-info/licenses/NOTICE,sha256=pAOGW-rGw9KNc2cuuLWZkfx0GSTV4TicbgBKZSLPMIs,168
+jentic_openapi_datamodels-1.0.0a13.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+jentic_openapi_datamodels-1.0.0a13.dist-info/METADATA,sha256=mV-JYCiurqc1c7SBNJ2OA4A85vhPI-NQ_iNFa3Uia1s,7439
+jentic_openapi_datamodels-1.0.0a13.dist-info/RECORD,,