jentic-openapi-parser 1.0.0a20__tar.gz → 1.0.0a21__tar.gz

jentic_openapi_parser-1.0.0a20/README.md → jentic_openapi_parser-1.0.0a21/PKG-INFO

@@ -1,3 +1,22 @@
+Metadata-Version: 2.4
+Name: jentic-openapi-parser
+Version: 1.0.0a21
+Summary: Jentic OpenAPI Parser
+Author: Jentic
+Author-email: Jentic <hello@jentic.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: attrs~=25.4.0
+Requires-Dist: jentic-openapi-common~=1.0.0a21
+Requires-Dist: jentic-openapi-datamodels~=1.0.0a21
+Requires-Dist: pyyaml~=6.0.3
+Requires-Dist: requests~=2.32.5
+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
+
 # jentic-openapi-parser
 
 A Python library for parsing OpenAPI documents using pluggable parser backends. This package is part of the Jentic OpenAPI Tools ecosystem and provides a flexible, extensible architecture for OpenAPI document parsing with support for multiple YAML/JSON parsing libraries.
@@ -6,7 +25,8 @@ A Python library for parsing OpenAPI documents using pluggable parser backends.
 
 - **Pluggable Backend Architecture**: Support for multiple parsing strategies via entry points
 - **Multiple Input Formats**: Parse OpenAPI documents from file URIs or text strings (JSON/YAML)
-- **Multiple Parser Backends**: Choose from PyYAML, ruamel.yaml (safe/roundtrip/AST modes)
+- **Multiple Parser Backends**: Choose from PyYAML, ruamel.yaml (safe/roundtrip/AST modes), or typed datamodels
+- **Low-Level Datamodels**: Parse directly to typed `OpenAPI30`/`OpenAPI31` objects with source tracking
 - **Enhanced JSON Serialization**: Built-in support for datetime, UUID, Path, Decimal, Enum, and attrs classes
 - **Type Safety**: Full type hints with overloaded methods for precise return types
 - **Extensible Design**: Easy integration of third-party parser backends
@@ -161,7 +181,7 @@ class OpenAPIParser:
 
 **Parameters:**
 - `backend`: Parser backend to use. Can be:
-  - `str`: Name of a backend registered via entry points (e.g., "pyyaml", "ruamel-safe", "ruamel-roundtrip", "ruamel-ast")
+  - `str`: Name of a backend registered via entry points (e.g., "pyyaml", "ruamel-safe", "ruamel-roundtrip", "ruamel-ast", "datamodel-low")
   - `BaseParserBackend`: Instance of a parser backend
   - `Type[BaseParserBackend]`: Class of a parser backend (will be instantiated)
   - Defaults to `"pyyaml"` if `None`
@@ -308,6 +328,55 @@ from ruamel.yaml import MappingNode  # Alternative import
 - AST-based transformations and analysis
 - Integration with validation tools that need exact source positions
 
+### datamodel-low
+Low-level OpenAPI data model parser that automatically detects the OpenAPI version (3.0.x or 3.1.x) and returns the appropriate typed datamodel with complete source tracking.
+
+**Accepts:** `text` (JSON/YAML strings), `uri` (file paths/URLs)
+
+**Returns:** `OpenAPI30` or `OpenAPI31` data model (from `jentic-openapi-datamodels`)
+
+```python
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.datamodels.low.v30.openapi import OpenAPI30
+from jentic.apitools.openapi.datamodels.low.v31.openapi import OpenAPI31
+
+parser = OpenAPIParser("datamodel-low")
+
+# Parse OpenAPI 3.0.x document
+doc = parser.parse("file:///path/to/openapi-3.0.yaml")
+assert isinstance(doc, OpenAPI30)
+print(doc.openapi.value)  # "3.0.4"
+print(doc.info.value.title.value)  # Access with source tracking
+
+# Parse OpenAPI 3.1.x document
+doc = parser.parse("file:///path/to/openapi-3.1.yaml")
+assert isinstance(doc, OpenAPI31)
+print(doc.openapi.value)  # "3.1.2"
+
+# Access fields with source information
+print(f"Title at line {doc.info.key_node.start_mark.line}")
+```
+
+**Features:**
+- **Automatic Version Detection**: Parses `openapi` field and routes to correct builder
+- **Typed Datamodels**: Returns strongly-typed `OpenAPI30` or `OpenAPI31` objects
+- **Complete Source Tracking**: Every field preserves YAML node information
+- **Error Handling**: Clear errors for unsupported versions (2.0, 3.2+)
+
+**Supported Versions:**
+- OpenAPI 3.0.x → returns `OpenAPI30`
+- OpenAPI 3.1.x → returns `OpenAPI31`
+
+**Unsupported (raises ValueError):**
+- OpenAPI 2.0 (Swagger)
+- OpenAPI 3.2.x and above
+
+**Use Cases:**
+- Type-safe OpenAPI document manipulation
+- Building validation tools with precise error messages
+- Code generation from OpenAPI specifications
+- AST transformations with version-aware logic
+
 ## Testing
 
 Run the test suite:

jentic_openapi_parser-1.0.0a20/PKG-INFO → jentic_openapi_parser-1.0.0a21/README.md

@@ -1,21 +1,3 @@
-Metadata-Version: 2.4
-Name: jentic-openapi-parser
-Version: 1.0.0a20
-Summary: Jentic OpenAPI Parser
-Author: Jentic
-Author-email: Jentic <hello@jentic.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Requires-Dist: attrs~=25.4.0
-Requires-Dist: jentic-openapi-common~=1.0.0a20
-Requires-Dist: pyyaml~=6.0.3
-Requires-Dist: requests~=2.32.5
-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
-
 # jentic-openapi-parser
 
 A Python library for parsing OpenAPI documents using pluggable parser backends. This package is part of the Jentic OpenAPI Tools ecosystem and provides a flexible, extensible architecture for OpenAPI document parsing with support for multiple YAML/JSON parsing libraries.
@@ -24,7 +6,8 @@ A Python library for parsing OpenAPI documents using pluggable parser backends.
 
 - **Pluggable Backend Architecture**: Support for multiple parsing strategies via entry points
 - **Multiple Input Formats**: Parse OpenAPI documents from file URIs or text strings (JSON/YAML)
-- **Multiple Parser Backends**: Choose from PyYAML, ruamel.yaml (safe/roundtrip/AST modes)
+- **Multiple Parser Backends**: Choose from PyYAML, ruamel.yaml (safe/roundtrip/AST modes), or typed datamodels
+- **Low-Level Datamodels**: Parse directly to typed `OpenAPI30`/`OpenAPI31` objects with source tracking
 - **Enhanced JSON Serialization**: Built-in support for datetime, UUID, Path, Decimal, Enum, and attrs classes
 - **Type Safety**: Full type hints with overloaded methods for precise return types
 - **Extensible Design**: Easy integration of third-party parser backends
@@ -179,7 +162,7 @@ class OpenAPIParser:
 
 **Parameters:**
 - `backend`: Parser backend to use. Can be:
-  - `str`: Name of a backend registered via entry points (e.g., "pyyaml", "ruamel-safe", "ruamel-roundtrip", "ruamel-ast")
+  - `str`: Name of a backend registered via entry points (e.g., "pyyaml", "ruamel-safe", "ruamel-roundtrip", "ruamel-ast", "datamodel-low")
   - `BaseParserBackend`: Instance of a parser backend
   - `Type[BaseParserBackend]`: Class of a parser backend (will be instantiated)
   - Defaults to `"pyyaml"` if `None`
@@ -326,6 +309,55 @@ from ruamel.yaml import MappingNode  # Alternative import
 - AST-based transformations and analysis
 - Integration with validation tools that need exact source positions
 
+### datamodel-low
+Low-level OpenAPI data model parser that automatically detects the OpenAPI version (3.0.x or 3.1.x) and returns the appropriate typed datamodel with complete source tracking.
+
+**Accepts:** `text` (JSON/YAML strings), `uri` (file paths/URLs)
+
+**Returns:** `OpenAPI30` or `OpenAPI31` data model (from `jentic-openapi-datamodels`)
+
+```python
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.datamodels.low.v30.openapi import OpenAPI30
+from jentic.apitools.openapi.datamodels.low.v31.openapi import OpenAPI31
+
+parser = OpenAPIParser("datamodel-low")
+
+# Parse OpenAPI 3.0.x document
+doc = parser.parse("file:///path/to/openapi-3.0.yaml")
+assert isinstance(doc, OpenAPI30)
+print(doc.openapi.value)  # "3.0.4"
+print(doc.info.value.title.value)  # Access with source tracking
+
+# Parse OpenAPI 3.1.x document
+doc = parser.parse("file:///path/to/openapi-3.1.yaml")
+assert isinstance(doc, OpenAPI31)
+print(doc.openapi.value)  # "3.1.2"
+
+# Access fields with source information
+print(f"Title at line {doc.info.key_node.start_mark.line}")
+```
+
+**Features:**
+- **Automatic Version Detection**: Parses `openapi` field and routes to correct builder
+- **Typed Datamodels**: Returns strongly-typed `OpenAPI30` or `OpenAPI31` objects
+- **Complete Source Tracking**: Every field preserves YAML node information
+- **Error Handling**: Clear errors for unsupported versions (2.0, 3.2+)
+
+**Supported Versions:**
+- OpenAPI 3.0.x → returns `OpenAPI30`
+- OpenAPI 3.1.x → returns `OpenAPI31`
+
+**Unsupported (raises ValueError):**
+- OpenAPI 2.0 (Swagger)
+- OpenAPI 3.2.x and above
+
+**Use Cases:**
+- Type-safe OpenAPI document manipulation
+- Building validation tools with precise error messages
+- Code generation from OpenAPI specifications
+- AST transformations with version-aware logic
+
 ## Testing
 
 Run the test suite:

{jentic_openapi_parser-1.0.0a20 → jentic_openapi_parser-1.0.0a21}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jentic-openapi-parser"
-version = "1.0.0-alpha.20"
+version = "1.0.0-alpha.21"
 description = "Jentic OpenAPI Parser"
 readme = "README.md"
 authors = [{ name = "Jentic", email = "hello@jentic.com" }]
@@ -9,7 +9,8 @@ license-files = ["LICENSE", "NOTICE"]
 requires-python = ">=3.11"
 dependencies = [
     "attrs~=25.4.0",
-    "jentic-openapi-common~=1.0.0-alpha.20",
+    "jentic-openapi-common~=1.0.0-alpha.21",
+    "jentic-openapi-datamodels~=1.0.0-alpha.21",
     "pyyaml~=6.0.3",
     "requests~=2.32.5",
     "ruamel-yaml~=0.18.15"
@@ -28,6 +29,7 @@ module-root = "src/"
 
 [tool.uv.sources]
 jentic-openapi-common = { workspace = true }
+jentic-openapi-datamodels = { workspace = true }
 
 [build-system]
 requires = ["uv_build~=0.8.15"]
@@ -38,4 +40,5 @@ pyyaml = "jentic.apitools.openapi.parser.backends.pyyaml:PyYAMLParserBackend"
 ruamel-safe = "jentic.apitools.openapi.parser.backends.ruamel_safe:RuamelSafeParserBackend"
 ruamel-roundtrip = "jentic.apitools.openapi.parser.backends.ruamel_roundtrip:RuamelRoundTripParserBackend"
 ruamel-ast = "jentic.apitools.openapi.parser.backends.ruamel_ast:RuamelASTParserBackend"
+datamodel-low = "jentic.apitools.openapi.parser.backends.datamodel_low:DataModelLowParserBackend"
 

jentic_openapi_parser-1.0.0a21/src/jentic/apitools/openapi/parser/backends/datamodel_low.py

@@ -0,0 +1,102 @@
+import logging
+from collections.abc import Sequence
+from typing import Literal, TypeAlias
+
+from ruamel.yaml import Node
+
+from jentic.apitools.openapi.common.uri import is_uri_like
+from jentic.apitools.openapi.common.version_detection import is_openapi_30, is_openapi_31
+from jentic.apitools.openapi.datamodels.low.sources import ValueSource
+from jentic.apitools.openapi.datamodels.low.v30 import build as build_v30
+from jentic.apitools.openapi.datamodels.low.v30.openapi import OpenAPI30
+from jentic.apitools.openapi.datamodels.low.v31 import build as build_v31
+from jentic.apitools.openapi.datamodels.low.v31.openapi import OpenAPI31
+from jentic.apitools.openapi.parser.backends.base import BaseParserBackend
+from jentic.apitools.openapi.parser.backends.ruamel_ast import RuamelASTParserBackend
+from jentic.apitools.openapi.parser.core.loader import load_uri
+
+
+# Type alias for the datamodel-low return type
+DataModelLow: TypeAlias = OpenAPI30 | OpenAPI31 | ValueSource
+
+
+__all__ = ["DataModelLowParserBackend", "DataModelLow"]
+
+
+class DataModelLowParserBackend(BaseParserBackend):
+    """Parser backend that returns low-level OpenAPI datamodels.
+
+    This backend uses the RuamelASTParserBackend to parse YAML documents into
+    AST nodes, then automatically detects the OpenAPI version and builds the
+    appropriate low-level data model (OpenAPI 3.0 or 3.1).
+
+    The returned datamodels preserve all source location information from the
+    original YAML document, enabling precise error reporting and validation.
+
+    Supported versions:
+    - OpenAPI 3.0.x → returns OpenAPI30 data model
+    - OpenAPI 3.1.x → returns OpenAPI31 data model
+
+    Unsupported versions (raises ValueError):
+    - OpenAPI 2.0 (Swagger)
+    - OpenAPI 3.2.x (not yet released/supported)
+    - Any other version
+    """
+
+    def __init__(self, pure: bool = True):
+        """Initialize the datamodel-low parser backend.
+
+        Args:
+            pure: Whether to use pure Python YAML implementation (default: True).
+                  Set to False to use libyaml if available for better performance.
+        """
+        self._ast_backend = RuamelASTParserBackend(pure=pure)
+
+    def parse(self, document: str, *, logger: logging.Logger | None = None) -> DataModelLow:
+        """Parse an OpenAPI document and return the appropriate data model.
+
+        Args:
+            document: URI/path to OpenAPI document, or YAML/JSON string
+            logger: Optional logger for diagnostic messages
+
+        Returns:
+            OpenAPI30 or OpenAPI31 data model depending on document version,
+            or ValueSource if the document is invalid
+
+        Raises:
+            ValueError: If OpenAPI version is unsupported (2.0, 3.2, etc.)
+        """
+        logger = logger or logging.getLogger(__name__)
+
+        if is_uri_like(document):
+            return self._parse_uri(document, logger)
+        return self._parse_text(document, logger)
+
+    @staticmethod
+    def accepts() -> Sequence[Literal["uri", "text"]]:
+        """Return supported input formats.
+
+        Returns:
+            Sequence of supported document format identifiers:
+            - "uri": File path or URI pointing to OpenAPI Document
+            - "text": String (JSON/YAML) representation
+        """
+        return ["uri", "text"]
+
+    def _parse_uri(self, uri: str, logger: logging.Logger) -> DataModelLow:
+        """Parse an OpenAPI document from a URI."""
+        logger.debug("Starting download of %s", uri)
+        return self._parse_text(load_uri(uri, 5, 10, logger), logger)
+
+    def _parse_text(self, text: str, logger: logging.Logger) -> DataModelLow:
+        """Parse an OpenAPI document from text."""
+        if is_openapi_30(text):
+            logger.debug("Building OpenAPI 3.0.x data model")
+            ast_node: Node = self._ast_backend.parse(text, logger=logger)
+            return build_v30(ast_node)
+        elif is_openapi_31(text):
+            logger.debug("Building OpenAPI 3.1.x data model")
+            ast_node: Node = self._ast_backend.parse(text, logger=logger)
+            return build_v31(ast_node)
+        else:
+            raise ValueError("Unsupported OpenAPI version. Supported versions: 3.0.x, 3.1.x")

{jentic_openapi_parser-1.0.0a20 → jentic_openapi_parser-1.0.0a21}/src/jentic/apitools/openapi/parser/backends/ruamel_ast.py

@@ -2,24 +2,26 @@ import logging
 from collections.abc import Sequence
 from typing import Literal
 
-from ruamel.yaml import MappingNode, ScalarNode, SequenceNode
+from ruamel.yaml import YAML, MappingNode
 
 from jentic.apitools.openapi.common.uri import is_uri_like
-from jentic.apitools.openapi.parser.backends.ruamel_roundtrip import RuamelRoundTripParserBackend
+from jentic.apitools.openapi.parser.backends.base import BaseParserBackend
 from jentic.apitools.openapi.parser.core.loader import load_uri
 
 
 __all__ = [
     "RuamelASTParserBackend",
-    # Re-export common YAML node types for convenience
+    # Re-export Mapping YAML node type for convenience
     "MappingNode",
-    "ScalarNode",
-    "SequenceNode",
 ]
 
 
-class RuamelASTParserBackend(RuamelRoundTripParserBackend):
-    def parse(self, document: str, *, logger: logging.Logger | None = None) -> MappingNode:  # type: ignore[override]
+class RuamelASTParserBackend(BaseParserBackend):
+    def __init__(self, typ: str = "rt", pure: bool = True):
+        self.yaml = YAML(typ=typ, pure=pure)
+        self.yaml.default_flow_style = False
+
+    def parse(self, document: str, *, logger: logging.Logger | None = None) -> MappingNode:
         logger = logger or logging.getLogger(__name__)
         if is_uri_like(document):
             return self._parse_uri(document, logger)
@@ -36,11 +38,11 @@ class RuamelASTParserBackend(RuamelRoundTripParserBackend):
         """
         return ["uri", "text"]
 
-    def _parse_uri(self, uri: str, logger: logging.Logger) -> MappingNode:  # type: ignore[override]
+    def _parse_uri(self, uri: str, logger: logging.Logger) -> MappingNode:
         logger.debug("Starting download of %s", uri)
         return self._parse_text(load_uri(uri, 5, 10, logger), logger)
 
-    def _parse_text(self, text: str, logger: logging.Logger) -> MappingNode:  # type: ignore[override]
+    def _parse_text(self, text: str, logger: logging.Logger) -> MappingNode:
         if not isinstance(text, (bytes, str)):
             raise TypeError(f"Unsupported document type: {type(text)!r}")
 

{jentic_openapi_parser-1.0.0a20 → jentic_openapi_parser-1.0.0a21}/src/jentic/apitools/openapi/parser/backends/ruamel_roundtrip.py

@@ -1,7 +1,13 @@
+from ruamel.yaml import CommentedMap
+
 from jentic.apitools.openapi.parser.backends.ruamel_safe import RuamelSafeParserBackend
 
 
-__all__ = ["RuamelRoundTripParserBackend"]
+__all__ = [
+    "RuamelRoundTripParserBackend",
+    # Re-export CommentedMap type for convenience
+    "CommentedMap",
+]
 
 
 class RuamelRoundTripParserBackend(RuamelSafeParserBackend):

{jentic_openapi_parser-1.0.0a20 → jentic_openapi_parser-1.0.0a21}/src/jentic/apitools/openapi/parser/backends/ruamel_safe.py

@@ -9,7 +9,11 @@ from jentic.apitools.openapi.parser.backends.base import BaseParserBackend
 from jentic.apitools.openapi.parser.core.loader import load_uri
 
 
-__all__ = ["RuamelSafeParserBackend"]
+__all__ = [
+    "RuamelSafeParserBackend",
+    # Re-export CommentedMap type for convenience
+    "CommentedMap",
+]
 
 
 class RuamelSafeParserBackend(BaseParserBackend):