jentic-openapi-datamodels 1.0.0a19__tar.gz → 1.0.0a21__tar.gz

{jentic_openapi_datamodels-1.0.0a19 → jentic_openapi_datamodels-1.0.0a21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jentic-openapi-datamodels
-Version: 1.0.0a19
+Version: 1.0.0a21
 Summary: Jentic OpenAPI Data Models
 Author: Jentic
 Author-email: Jentic <hello@jentic.com>
@@ -61,17 +61,73 @@ 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 ruamel.yaml import YAML
+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
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30 import build
 
 # Parse OpenAPI document
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 openapi: 3.0.4
 info:
   title: Pet Store API
@@ -83,7 +139,7 @@ paths:
       responses:
         '200':
           description: A list of pets
-""")
+""", return_type=MappingNode)
 
 # Build OpenAPI document model
 openapi_doc = build(root)
@@ -101,17 +157,18 @@ 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:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v31 import build
 
 # Parse OpenAPI 3.1 document with JSON Schema 2020-12 features
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 openapi: 3.1.2
 info:
   title: Pet Store API
@@ -133,7 +190,7 @@ paths:
                 contains:
                   type: object
                   required: [id]
-""")
+""", return_type=MappingNode)
 
 openapi_doc = build(root)
 
@@ -149,16 +206,17 @@ print(schema.contains.value.required.value[0].value)  # "id"
 You can also parse individual OpenAPI specification objects:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30.security_scheme import build as build_security_scheme
 
 # Parse a Security Scheme object
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 type: http
 scheme: bearer
 bearerFormat: JWT
-""")
+""", return_type=MappingNode)
 
 security_scheme = build_security_scheme(root)
 
@@ -173,12 +231,13 @@ print(security_scheme.bearer_format.key_node.start_mark.line)  # Line number
 You can also parse OpenAPI 3.1 Schema objects with JSON Schema 2020-12 features:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v31.schema import build as build_schema
 
 # Parse a Schema object with JSON Schema 2020-12 features
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 type: object
 properties:
   id:
@@ -199,7 +258,7 @@ if:
       const: true
 then:
   required: [support_tier]
-""")
+""", return_type=MappingNode)
 
 schema = build_schema(root)
 
@@ -255,18 +314,19 @@ The package provides three immutable wrapper types for preserving source informa
 - Example: Values in `Discriminator.mapping` are `ValueSource[str]`
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30 import build
 
 # FieldSource: Fixed specification fields in OpenAPI document
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 openapi: 3.0.4
 info:
   title: Pet Store API
   version: 1.0.0
 paths: {}
-""")
+""", return_type=MappingNode)
 openapi_doc = build(root)
 
 field = openapi_doc.info.value.title  # FieldSource[str]
@@ -276,7 +336,7 @@ print(field.value_node)  # YAML node for "Pet Store API"
 
 # KeySource/ValueSource: Dictionary fields (extensions, mapping)
 # Extensions in OpenAPI objects use KeySource/ValueSource
-root = yaml.compose("""
+root = parser.parse("""
 openapi: 3.0.4
 info:
   title: API
@@ -284,7 +344,7 @@ info:
   x-custom: value
   x-another: data
 paths: {}
-""")
+""", return_type=MappingNode)
 openapi_doc = build(root)
 
 for key, value in openapi_doc.info.value.extensions.items():
@@ -299,7 +359,8 @@ for key, value in openapi_doc.info.value.extensions.items():
 Access precise location ranges within the source document using start_mark and end_mark:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30 import build
 
 yaml_content = """
@@ -311,8 +372,8 @@ info:
 paths: {}
 """
 
-yaml = YAML()
-root = yaml.compose(yaml_content)
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse(yaml_content, return_type=MappingNode)
 openapi_doc = build(root)
 
 # Access location information for any field
@@ -337,17 +398,18 @@ print(f"Field range: ({start.line}:{start.column}) to ({end.line}:{end.column})"
 Low-level models preserve invalid data without validation:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30 import build
 
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 openapi: 3.0.4
 info:
   title: 123  # Intentionally wrong type for demonstration (should be string)
   version: 1.0.0
 paths: {}
-""")
+""", return_type=MappingNode)
 
 openapi_doc = build(root)
 print(openapi_doc.info.value.title.value)  # 123 (preserved as-is)

{jentic_openapi_datamodels-1.0.0a19 → jentic_openapi_datamodels-1.0.0a21}/README.md

@@ -47,17 +47,73 @@ 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 ruamel.yaml import YAML
+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
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30 import build
 
 # Parse OpenAPI document
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 openapi: 3.0.4
 info:
   title: Pet Store API
@@ -69,7 +125,7 @@ paths:
       responses:
         '200':
           description: A list of pets
-""")
+""", return_type=MappingNode)
 
 # Build OpenAPI document model
 openapi_doc = build(root)
@@ -87,17 +143,18 @@ 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:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v31 import build
 
 # Parse OpenAPI 3.1 document with JSON Schema 2020-12 features
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 openapi: 3.1.2
 info:
   title: Pet Store API
@@ -119,7 +176,7 @@ paths:
                 contains:
                   type: object
                   required: [id]
-""")
+""", return_type=MappingNode)
 
 openapi_doc = build(root)
 
@@ -135,16 +192,17 @@ print(schema.contains.value.required.value[0].value)  # "id"
 You can also parse individual OpenAPI specification objects:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30.security_scheme import build as build_security_scheme
 
 # Parse a Security Scheme object
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 type: http
 scheme: bearer
 bearerFormat: JWT
-""")
+""", return_type=MappingNode)
 
 security_scheme = build_security_scheme(root)
 
@@ -159,12 +217,13 @@ print(security_scheme.bearer_format.key_node.start_mark.line)  # Line number
 You can also parse OpenAPI 3.1 Schema objects with JSON Schema 2020-12 features:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v31.schema import build as build_schema
 
 # Parse a Schema object with JSON Schema 2020-12 features
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 type: object
 properties:
   id:
@@ -185,7 +244,7 @@ if:
       const: true
 then:
   required: [support_tier]
-""")
+""", return_type=MappingNode)
 
 schema = build_schema(root)
 
@@ -241,18 +300,19 @@ The package provides three immutable wrapper types for preserving source informa
 - Example: Values in `Discriminator.mapping` are `ValueSource[str]`
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30 import build
 
 # FieldSource: Fixed specification fields in OpenAPI document
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 openapi: 3.0.4
 info:
   title: Pet Store API
   version: 1.0.0
 paths: {}
-""")
+""", return_type=MappingNode)
 openapi_doc = build(root)
 
 field = openapi_doc.info.value.title  # FieldSource[str]
@@ -262,7 +322,7 @@ print(field.value_node)  # YAML node for "Pet Store API"
 
 # KeySource/ValueSource: Dictionary fields (extensions, mapping)
 # Extensions in OpenAPI objects use KeySource/ValueSource
-root = yaml.compose("""
+root = parser.parse("""
 openapi: 3.0.4
 info:
   title: API
@@ -270,7 +330,7 @@ info:
   x-custom: value
   x-another: data
 paths: {}
-""")
+""", return_type=MappingNode)
 openapi_doc = build(root)
 
 for key, value in openapi_doc.info.value.extensions.items():
@@ -285,7 +345,8 @@ for key, value in openapi_doc.info.value.extensions.items():
 Access precise location ranges within the source document using start_mark and end_mark:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30 import build
 
 yaml_content = """
@@ -297,8 +358,8 @@ info:
 paths: {}
 """
 
-yaml = YAML()
-root = yaml.compose(yaml_content)
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse(yaml_content, return_type=MappingNode)
 openapi_doc = build(root)
 
 # Access location information for any field
@@ -323,17 +384,18 @@ print(f"Field range: ({start.line}:{start.column}) to ({end.line}:{end.column})"
 Low-level models preserve invalid data without validation:
 
 ```python
-from ruamel.yaml import YAML
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
 from jentic.apitools.openapi.datamodels.low.v30 import build
 
-yaml = YAML()
-root = yaml.compose("""
+parser = OpenAPIParser("ruamel-ast")
+root = parser.parse("""
 openapi: 3.0.4
 info:
   title: 123  # Intentionally wrong type for demonstration (should be string)
   version: 1.0.0
 paths: {}
-""")
+""", return_type=MappingNode)
 
 openapi_doc = build(root)
 print(openapi_doc.info.value.title.value)  # 123 (preserved as-is)

{jentic_openapi_datamodels-1.0.0a19 → jentic_openapi_datamodels-1.0.0a21}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jentic-openapi-datamodels"
-version = "1.0.0-alpha.19"
+version = "1.0.0-alpha.21"
 description = "Jentic OpenAPI Data Models"
 readme = "README.md"
 authors = [{ name = "Jentic", email = "hello@jentic.com" }]
@@ -11,12 +11,20 @@ dependencies = [
     "ruamel-yaml~=0.18.15"
 ]
 
+[dependency-groups]
+dev = [
+    "jentic-openapi-parser",
+]
+
 [project.urls]
 Homepage = "https://github.com/jentic/jentic-openapi-tools"
 
 [tool.uv]
 package = true
 
+[tool.uv.sources]
+jentic-openapi-parser = { workspace = true }
+
 [tool.uv.build-backend]
 namespace = true
 module-name = "jentic.apitools.openapi.datamodels"