jentic-openapi-datamodels 1.0.0a12__tar.gz → 1.0.0a13__tar.gz

jentic_openapi_datamodels-1.0.0a13/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,197 @@
+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.0a12 → jentic_openapi_datamodels-1.0.0a13}/pyproject.toml

@@ -1,13 +1,15 @@
 [project]
 name = "jentic-openapi-datamodels"
-version = "1.0.0-alpha.12"
+version = "1.0.0-alpha.13"
 description = "Jentic OpenAPI Data Models"
 readme = "README.md"
 authors = [{ name = "Jentic", email = "hello@jentic.com" }]
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 requires-python = ">=3.11"
-dependencies = []
+dependencies = [
+    "ruamel-yaml~=0.18.15"
+]
 
 [project.urls]
 Homepage = "https://github.com/jentic/jentic-openapi-tools"

jentic_openapi_datamodels-1.0.0a13/src/jentic/apitools/openapi/datamodels/low/context.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass, field
+
+from ruamel.yaml import YAML
+from ruamel.yaml.constructor import RoundTripConstructor
+
+
+__all__ = ["Context"]
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    """
+    Context for parsing OpenAPI documents.
+
+    Contains configuration and dependencies used during parsing operations.
+
+    Attributes:
+        yaml_constructor: The YAML constructor used to deserialize YAML nodes into Python objects
+    """
+
+    yaml_constructor: RoundTripConstructor = field(default=YAML(typ="rt", pure=True).constructor)

jentic_openapi_datamodels-1.0.0a13/src/jentic/apitools/openapi/datamodels/low/extractors.py

@@ -0,0 +1,126 @@
+from ruamel import yaml
+
+from jentic.apitools.openapi.datamodels.low.context import Context
+from jentic.apitools.openapi.datamodels.low.fields import fixed_fields
+from jentic.apitools.openapi.datamodels.low.sources import KeySource, ValueSource, YAMLValue
+
+
+__all__ = ["extract_extension_fields", "extract_unknown_fields"]
+
+
+def extract_extension_fields(
+    node: yaml.MappingNode, context: Context | None = None
+) -> dict[KeySource[str], ValueSource[YAMLValue]]:
+    """
+    Extract OpenAPI specification extension fields from a YAML mapping node.
+
+    Specification extension fields are any fields that start with "x-" and allow
+    users to add custom properties to OpenAPI definitions.
+
+    Args:
+        node: The YAML mapping node to extract extension fields from
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        A dictionary mapping extension field names to their values, or empty dict if no extension fields found
+
+    Example:
+        Given YAML like:
+            name: id
+            x-custom: value
+            x-internal: true
+
+        Returns:
+            {
+                KeySource(value="x-custom", key_node=...): ValueSource(value="value", value_node=...),
+                KeySource(value="x-internal", key_node=...): ValueSource(value=True, value_node=...)
+            }
+    """
+    if not isinstance(node, yaml.MappingNode):
+        return {}
+
+    if context is None:
+        context = Context()
+
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = {}
+
+    for key_node, value_node in node.value:
+        # Construct the key as a Python object (should be a string)
+        py_key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Check if it's an extension (starts with "x-")
+        if isinstance(py_key, str) and py_key.startswith("x-"):
+            # Construct the actual Python value from the YAML node
+            py_value = context.yaml_constructor.construct_object(value_node, deep=True)
+
+            key_ref = KeySource[str](value=py_key, key_node=key_node)
+            value_ref = ValueSource[YAMLValue](value=py_value, value_node=value_node)
+            extensions[key_ref] = value_ref
+
+    return extensions
+
+
+def extract_unknown_fields(
+    node: yaml.MappingNode, dataclass_type: type, context: Context | None = None
+) -> dict[KeySource[str], ValueSource[YAMLValue]]:
+    """
+    Extract unknown fields from a YAML mapping node.
+
+    Unknown fields are fields that are not part of the OpenAPI specification
+    (not fixed fields of the dataclass) and are not extensions (don't start with "x-").
+    These are typically typos or fields from a different specification version.
+
+    Args:
+        node: The YAML mapping node to extract unknown fields from
+        dataclass_type: The dataclass type to get valid field names from
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        A dictionary mapping unknown field names to their values, or empty dict if no unknown fields found
+
+    Example:
+        Given YAML like:
+            name: id
+            namspace: http://example.com  # typo - should be "namespace"
+            customField: value             # unknown field
+            x-custom: value                # extension - not unknown
+
+        With dataclass_type=XML (which has fixed fields: name, namespace, prefix, attribute, wrapped)
+        Returns:
+            {
+                KeySource(value="namspace", key_node=...): ValueSource(value="http://example.com", value_node=...),
+                KeySource(value="customField", key_node=...): ValueSource(value="value", value_node=...)
+            }
+    """
+    if not isinstance(node, yaml.MappingNode):
+        return {}
+
+    if context is None:
+        context = Context()
+
+    # Get valid YAML field names from the dataclass (considering yaml_name metadata)
+    _fixed_fields = fixed_fields(dataclass_type)
+    yaml_field_names = {
+        field.metadata.get("yaml_name", fname) for fname, field in _fixed_fields.items()
+    }
+
+    unknown_fields: dict[KeySource[str], ValueSource[YAMLValue]] = {}
+
+    for key_node, value_node in node.value:
+        # Construct the key as a Python object (should be a string)
+        py_key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Check if it's an unknown field (not in valid YAML field names and not an extension)
+        if (
+            isinstance(py_key, str)
+            and py_key not in yaml_field_names
+            and not py_key.startswith("x-")
+        ):
+            # Construct the actual Python value from the YAML node
+            py_value = context.yaml_constructor.construct_object(value_node, deep=True)
+
+            key_ref = KeySource[str](value=py_key, key_node=key_node)
+            value_ref = ValueSource[YAMLValue](value=py_value, value_node=value_node)
+            unknown_fields[key_ref] = value_ref
+
+    return unknown_fields

jentic_openapi_datamodels-1.0.0a13/src/jentic/apitools/openapi/datamodels/low/fields.py

@@ -0,0 +1,45 @@
+from dataclasses import field, fields
+
+
+__all__ = ["fixed_field", "fixed_fields", "patterned_field", "patterned_fields"]
+
+
+def fixed_field(default=None, metadata=None):
+    """Mark a field as a fixed OpenAPI specification field."""
+    return field(default=default, metadata={**(metadata or {}), "fixed_field": True})
+
+
+def fixed_fields(dataclass_type):
+    """
+    Get all fixed specification fields from a dataclass.
+
+    Args:
+        dataclass_type: The dataclass type to inspect
+
+    Returns:
+        A dictionary mapping field names to field objects for all fields marked with fixed_field()
+    """
+    return {f.name: f for f in fields(dataclass_type) if f.metadata.get("fixed_field")}
+
+
+def patterned_field(default=None, metadata=None):
+    """
+    Mark a field as containing OpenAPI patterned fields.
+
+    Patterned fields have dynamic names that follow a specific pattern (e.g., security scheme names,
+    path patterns, callback expressions, HTTP status codes).
+    """
+    return field(default=default, metadata={**(metadata or {}), "patterned_field": True})
+
+
+def patterned_fields(dataclass_type):
+    """
+    Get all patterned fields from a dataclass.
+
+    Args:
+        dataclass_type: The dataclass type to inspect
+
+    Returns:
+        A dictionary mapping field names to field objects for all fields marked with patterned_field()
+    """
+    return {f.name: f for f in fields(dataclass_type) if f.metadata.get("patterned_field")}