jentic-openapi-datamodels 1.0.0a20__tar.gz → 1.0.0a22__tar.gz

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jentic-openapi-datamodels
-Version: 1.0.0a20
+Version: 1.0.0a22
 Summary: Jentic OpenAPI Data Models
 Author: Jentic
 Author-email: Jentic <hello@jentic.com>
@@ -61,9 +61,64 @@ pip install jentic-openapi-datamodels
 
 ## Quick Start
 
-### Parsing OpenAPI 3.0 Documents
+### Parsing with the `datamodel-low` Parser Backend (Recommended)
 
-The main use case is parsing complete OpenAPI Documents:
+The easiest way to parse OpenAPI documents into datamodels is using the `datamodel-low` backend from `jentic-openapi-parser`. This backend automatically detects the OpenAPI version and returns the appropriate typed datamodel:
+
+```python
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.datamodel_low import DataModelLow
+from jentic.apitools.openapi.datamodels.low.v30.openapi import OpenAPI30
+from jentic.apitools.openapi.datamodels.low.v31.openapi import OpenAPI31
+
+# Create parser with datamodel-low backend
+parser = OpenAPIParser("datamodel-low")
+
+# Parse OpenAPI 3.0 document - automatically returns OpenAPI30
+doc = parser.parse("""
+openapi: 3.0.4
+info:
+  title: Pet Store API
+  version: 1.0.0
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      responses:
+        '200':
+          description: A list of pets
+""", return_type=DataModelLow)
+
+assert isinstance(doc, OpenAPI30)
+print(doc.openapi.value)  # "3.0.4"
+print(doc.info.value.title.value)  # "Pet Store API"
+
+# Parse OpenAPI 3.1 document - automatically returns OpenAPI31
+doc = parser.parse("""
+openapi: 3.1.2
+info:
+  title: Pet Store API
+  version: 1.0.0
+paths: {}
+""", return_type=DataModelLow)
+
+assert isinstance(doc, OpenAPI31)
+print(doc.openapi.value)  # "3.1.2"
+```
+
+**Benefits of `datamodel-low` backend:**
+- Automatic version detection (no manual version checking)
+- Returns strongly-typed `OpenAPI30` or `OpenAPI31` objects
+- Complete source tracking preserved
+- Single-step parsing (no need to manually call `build()`)
+
+### Manual Parsing with Builder Functions
+
+For advanced use cases or custom workflows, you can manually parse and build datamodels:
+
+#### Parsing OpenAPI 3.0 Documents
+
+The manual approach uses the `ruamel-ast` backend followed by calling the builder function:
 
 ```python
 from jentic.apitools.openapi.parser.core import OpenAPIParser
@@ -102,7 +157,7 @@ for path_key, path_item in openapi_doc.paths.value.path_items.items():
         print(f"  Summary: {operation.summary.value}")  # "List all pets"
 ```
 
-### Parsing OpenAPI 3.1 Documents with JSON Schema 2020-12
+#### Parsing OpenAPI 3.1 Documents with JSON Schema 2020-12
 
 OpenAPI 3.1 fully supports JSON Schema 2020-12, including advanced features like boolean schemas, conditional validation and vocabulary declarations:
 

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/README.md

@@ -47,9 +47,64 @@ pip install jentic-openapi-datamodels
 
 ## Quick Start
 
-### Parsing OpenAPI 3.0 Documents
+### Parsing with the `datamodel-low` Parser Backend (Recommended)
 
-The main use case is parsing complete OpenAPI Documents:
+The easiest way to parse OpenAPI documents into datamodels is using the `datamodel-low` backend from `jentic-openapi-parser`. This backend automatically detects the OpenAPI version and returns the appropriate typed datamodel:
+
+```python
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.datamodel_low import DataModelLow
+from jentic.apitools.openapi.datamodels.low.v30.openapi import OpenAPI30
+from jentic.apitools.openapi.datamodels.low.v31.openapi import OpenAPI31
+
+# Create parser with datamodel-low backend
+parser = OpenAPIParser("datamodel-low")
+
+# Parse OpenAPI 3.0 document - automatically returns OpenAPI30
+doc = parser.parse("""
+openapi: 3.0.4
+info:
+  title: Pet Store API
+  version: 1.0.0
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      responses:
+        '200':
+          description: A list of pets
+""", return_type=DataModelLow)
+
+assert isinstance(doc, OpenAPI30)
+print(doc.openapi.value)  # "3.0.4"
+print(doc.info.value.title.value)  # "Pet Store API"
+
+# Parse OpenAPI 3.1 document - automatically returns OpenAPI31
+doc = parser.parse("""
+openapi: 3.1.2
+info:
+  title: Pet Store API
+  version: 1.0.0
+paths: {}
+""", return_type=DataModelLow)
+
+assert isinstance(doc, OpenAPI31)
+print(doc.openapi.value)  # "3.1.2"
+```
+
+**Benefits of `datamodel-low` backend:**
+- Automatic version detection (no manual version checking)
+- Returns strongly-typed `OpenAPI30` or `OpenAPI31` objects
+- Complete source tracking preserved
+- Single-step parsing (no need to manually call `build()`)
+
+### Manual Parsing with Builder Functions
+
+For advanced use cases or custom workflows, you can manually parse and build datamodels:
+
+#### Parsing OpenAPI 3.0 Documents
+
+The manual approach uses the `ruamel-ast` backend followed by calling the builder function:
 
 ```python
 from jentic.apitools.openapi.parser.core import OpenAPIParser
@@ -88,7 +143,7 @@ for path_key, path_item in openapi_doc.paths.value.path_items.items():
         print(f"  Summary: {operation.summary.value}")  # "List all pets"
 ```
 
-### Parsing OpenAPI 3.1 Documents with JSON Schema 2020-12
+#### Parsing OpenAPI 3.1 Documents with JSON Schema 2020-12
 
 OpenAPI 3.1 fully supports JSON Schema 2020-12, including advanced features like boolean schemas, conditional validation and vocabulary declarations:
 

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jentic-openapi-datamodels"
-version = "1.0.0-alpha.20"
+version = "1.0.0-alpha.22"
 description = "Jentic OpenAPI Data Models"
 readme = "README.md"
 authors = [{ name = "Jentic", email = "hello@jentic.com" }]

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/src/jentic/apitools/openapi/datamodels/low/fields.py

@@ -1,15 +1,16 @@
-from dataclasses import field, fields
+from dataclasses import MISSING, field, fields
+from typing import Any
 
 
 __all__ = ["fixed_field", "fixed_fields", "patterned_field", "patterned_fields"]
 
 
-def fixed_field(default=None, metadata=None):
+def fixed_field(*, default: Any = None, metadata: dict[str, Any] | None = None) -> Any:
     """Mark a field as a fixed OpenAPI specification field."""
     return field(default=default, metadata={**(metadata or {}), "fixed_field": True})
 
 
-def fixed_fields(dataclass_type):
+def fixed_fields(dataclass_type: type) -> dict[str, Any]:
     """
     Get all fixed specification fields from a dataclass.
 
@@ -22,17 +23,28 @@ def fixed_fields(dataclass_type):
     return {f.name: f for f in fields(dataclass_type) if f.metadata.get("fixed_field")}
 
 
-def patterned_field(default=None, metadata=None):
+def patterned_field(
+    *, default=MISSING, default_factory=MISSING, metadata: dict[str, Any] | None = None
+) -> Any:
     """
     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).
+
+    Args:
+        default: Default value for the field
+        default_factory: Callable that returns default value
+        metadata: Additional metadata for the field
     """
-    return field(default=default, metadata={**(metadata or {}), "patterned_field": True})
+    merged_metadata = {**(metadata or {}), "patterned_field": True}
+    if default_factory is not MISSING:
+        return field(default_factory=default_factory, metadata=merged_metadata)
+    else:
+        return field(default=default, metadata=merged_metadata)
 
 
-def patterned_fields(dataclass_type):
+def patterned_fields(dataclass_type: type) -> dict[str, Any]:
     """
     Get all patterned fields from a dataclass.
 

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/src/jentic/apitools/openapi/datamodels/low/v30/callback.py

@@ -4,6 +4,7 @@ from ruamel import yaml
 
 from ..context import Context
 from ..extractors import extract_extension_fields
+from ..fields import patterned_field
 from ..sources import KeySource, ValueSource, YAMLInvalidValue, YAMLValue
 from .path_item import PathItem
 from .path_item import build as build_path_item
@@ -33,7 +34,7 @@ class Callback:
     """
 
     root_node: yaml.Node
-    path_items: dict[KeySource[str], PathItem] = field(default_factory=dict)
+    path_items: dict[KeySource[str], PathItem] = patterned_field(default_factory=dict)
     extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
 
 
@@ -86,7 +87,7 @@ def build(
     extension_properties = {k.value for k in extensions.keys()}
 
     # Process each field to determine if it's an expression (not an extension)
-    path_items: dict[KeySource[str], PathItem | ValueSource[YAMLInvalidValue]] = {}
+    path_items = {}
 
     for key_node, value_node in root.value:
         expression = context.yaml_constructor.construct_yaml_str(key_node)
@@ -99,7 +100,7 @@ def build(
     # Create and return the Callback object with collected data
     return Callback(
         root_node=root,
-        path_items=path_items,  # type: ignore[arg-type]
+        path_items=path_items,
         extensions=extensions,
     )
 

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/src/jentic/apitools/openapi/datamodels/low/v30/paths.py

@@ -4,6 +4,7 @@ from ruamel import yaml
 
 from ..context import Context
 from ..extractors import extract_extension_fields
+from ..fields import patterned_field
 from ..sources import KeySource, ValueSource, YAMLInvalidValue, YAMLValue
 from .path_item import PathItem
 from .path_item import build as build_path_item
@@ -33,7 +34,7 @@ class Paths:
     """
 
     root_node: yaml.Node
-    paths: dict[KeySource[str], PathItem] = field(default_factory=dict)
+    paths: dict[KeySource[str], PathItem] = patterned_field(default_factory=dict)
     extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
 
 

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/src/jentic/apitools/openapi/datamodels/low/v30/responses.py

@@ -6,7 +6,7 @@ from ruamel import yaml
 
 from ..context import Context
 from ..extractors import extract_extension_fields
-from ..fields import fixed_field
+from ..fields import fixed_field, patterned_field
 from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
 from .reference import Reference
 from .response import Response, build_response_or_reference
@@ -34,7 +34,7 @@ class Responses:
 
     root_node: yaml.Node
     default: FieldSource[Response | Reference] | None = fixed_field()
-    responses: dict[KeySource[str], Response | Reference] = field(default_factory=dict)
+    responses: dict[KeySource[str], Response | Reference] = patterned_field(default_factory=dict)
     extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
 
 

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/src/jentic/apitools/openapi/datamodels/low/v30/security_requirement.py

@@ -33,8 +33,8 @@ class SecurityRequirement:
     """
 
     root_node: yaml.Node
-    requirements: ValueSource[dict[KeySource[str], ValueSource[list[ValueSource[str]]]]] | None = (
-        patterned_field()
+    requirements: dict[KeySource[str], ValueSource[list[ValueSource[str]]]] = patterned_field(
+        default_factory=dict
     )
 
 
@@ -61,7 +61,7 @@ def build(
         yaml = YAML()
         root = yaml.compose("api_key: []")
         security_req = build(root)
-        assert security_req.requirements is not None
+        assert len(security_req.requirements) > 0
     """
     context = context or Context()
 
@@ -70,7 +70,7 @@ def build(
         value = context.yaml_constructor.construct_object(root, deep=True)
         return ValueSource(value=value, value_node=root)
 
-    requirements_dict: dict[KeySource[str], ValueSource[list[ValueSource[str]]]] = {}
+    requirements = {}
 
     for key_node, value_node in root.value:
         key = context.yaml_constructor.construct_yaml_str(key_node)
@@ -88,19 +88,17 @@ def build(
                 item_value = context.yaml_constructor.construct_object(item_node, deep=True)
                 scope_list.append(ValueSource(value=item_value, value_node=item_node))
 
-            requirements_dict[KeySource(value=key, key_node=key_node)] = ValueSource(
+            requirements[KeySource(value=key, key_node=key_node)] = ValueSource(
                 value=scope_list, value_node=value_node
             )
         else:
             # Not a sequence - preserve as-is for validation to catch
             value = context.yaml_constructor.construct_object(value_node, deep=True)
-            requirements_dict[KeySource(value=key, key_node=key_node)] = ValueSource(
+            requirements[KeySource(value=key, key_node=key_node)] = ValueSource(
                 value=value, value_node=value_node
             )
 
     return SecurityRequirement(
         root_node=root,
-        requirements=(
-            ValueSource(value=requirements_dict, value_node=root) if requirements_dict else None
-        ),
+        requirements=requirements,
     )

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/src/jentic/apitools/openapi/datamodels/low/v31/callback.py

@@ -4,6 +4,7 @@ from ruamel import yaml
 
 from ..context import Context
 from ..extractors import extract_extension_fields
+from ..fields import patterned_field
 from ..sources import KeySource, ValueSource, YAMLInvalidValue, YAMLValue
 from .path_item import PathItem
 from .path_item import build as build_path_item
@@ -33,7 +34,7 @@ class Callback:
     """
 
     root_node: yaml.Node
-    path_items: dict[KeySource[str], PathItem] = field(default_factory=dict)
+    path_items: dict[KeySource[str], PathItem] = patterned_field(default_factory=dict)
     extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
 
 
@@ -86,7 +87,7 @@ def build(
     extension_properties = {k.value for k in extensions.keys()}
 
     # Process each field to determine if it's an expression (not an extension)
-    path_items: dict[KeySource[str], PathItem | ValueSource[YAMLInvalidValue]] = {}
+    path_items = {}
 
     for key_node, value_node in root.value:
         expression = context.yaml_constructor.construct_yaml_str(key_node)
@@ -99,7 +100,7 @@ def build(
     # Create and return the Callback object with collected data
     return Callback(
         root_node=root,
-        path_items=path_items,  # type: ignore[arg-type]
+        path_items=path_items,
         extensions=extensions,
     )
 

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/src/jentic/apitools/openapi/datamodels/low/v31/paths.py

@@ -4,6 +4,7 @@ from ruamel import yaml
 
 from ..context import Context
 from ..extractors import extract_extension_fields
+from ..fields import patterned_field
 from ..sources import KeySource, ValueSource, YAMLInvalidValue, YAMLValue
 from .path_item import PathItem
 from .path_item import build as build_path_item
@@ -33,7 +34,7 @@ class Paths:
     """
 
     root_node: yaml.Node
-    paths: dict[KeySource[str], PathItem] = field(default_factory=dict)
+    paths: dict[KeySource[str], PathItem] = patterned_field(default_factory=dict)
     extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
 
 

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/src/jentic/apitools/openapi/datamodels/low/v31/responses.py

@@ -6,7 +6,7 @@ from ruamel import yaml
 
 from ..context import Context
 from ..extractors import extract_extension_fields
-from ..fields import fixed_field
+from ..fields import fixed_field, patterned_field
 from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
 from .reference import Reference
 from .response import Response, build_response_or_reference
@@ -34,7 +34,7 @@ class Responses:
 
     root_node: yaml.Node
     default: FieldSource[Response | Reference] | None = fixed_field()
-    responses: dict[KeySource[str], Response | Reference] = field(default_factory=dict)
+    responses: dict[KeySource[str], Response | Reference] = patterned_field(default_factory=dict)
     extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
 
 

{jentic_openapi_datamodels-1.0.0a20 → jentic_openapi_datamodels-1.0.0a22}/src/jentic/apitools/openapi/datamodels/low/v31/security_requirement.py

@@ -33,8 +33,8 @@ class SecurityRequirement:
     """
 
     root_node: yaml.Node
-    requirements: ValueSource[dict[KeySource[str], ValueSource[list[ValueSource[str]]]]] | None = (
-        patterned_field()
+    requirements: dict[KeySource[str], ValueSource[list[ValueSource[str]]]] = patterned_field(
+        default_factory=dict
     )
 
 
@@ -61,7 +61,7 @@ def build(
         yaml = YAML()
         root = yaml.compose("api_key: []")
         security_req = build(root)
-        assert security_req.requirements is not None
+        assert len(security_req.requirements) > 0
     """
     context = context or Context()
 
@@ -70,7 +70,7 @@ def build(
         value = context.yaml_constructor.construct_object(root, deep=True)
         return ValueSource(value=value, value_node=root)
 
-    requirements_dict: dict[KeySource[str], ValueSource[list[ValueSource[str]]]] = {}
+    requirements = {}
 
     for key_node, value_node in root.value:
         key = context.yaml_constructor.construct_yaml_str(key_node)
@@ -88,19 +88,17 @@ def build(
                 item_value = context.yaml_constructor.construct_object(item_node, deep=True)
                 scope_list.append(ValueSource(value=item_value, value_node=item_node))
 
-            requirements_dict[KeySource(value=key, key_node=key_node)] = ValueSource(
+            requirements[KeySource(value=key, key_node=key_node)] = ValueSource(
                 value=scope_list, value_node=value_node
             )
         else:
             # Not a sequence - preserve as-is for validation to catch
             value = context.yaml_constructor.construct_object(value_node, deep=True)
-            requirements_dict[KeySource(value=key, key_node=key_node)] = ValueSource(
+            requirements[KeySource(value=key, key_node=key_node)] = ValueSource(
                 value=value, value_node=value_node
             )
 
     return SecurityRequirement(
         root_node=root,
-        requirements=(
-            ValueSource(value=requirements_dict, value_node=root) if requirements_dict else None
-        ),
+        requirements=requirements,
     )