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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jentic-openapi-parser
-Version: 1.0.0a19
+Version: 1.0.0a21
 Summary: Jentic OpenAPI Parser
 Author: Jentic
 Author-email: Jentic <hello@jentic.com>
@@ -8,7 +8,8 @@ License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: attrs~=25.4.0
-Requires-Dist: jentic-openapi-common~=1.0.0a19
+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
@@ -24,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, or ruamel.yaml roundtrip 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
@@ -53,12 +55,12 @@ doc = parser.parse("file:///path/to/openapi.yaml")
 print(doc["info"]["title"])
 
 # Parse from JSON string
-json_doc = '{"openapi":"3.1.0","info":{"title":"My API","version":"1.0.0"}}'
+json_doc = '{"openapi":"3.1.2","info":{"title":"My API","version":"1.0.0"}}'
 doc = parser.parse(json_doc)
 
 # Parse from YAML string
 yaml_doc = """
-openapi: 3.1.0
+openapi: 3.1.2
 info:
   title: My API
   version: 1.0.0
@@ -95,6 +97,14 @@ parser = OpenAPIParser("ruamel-roundtrip")
 doc = parser.parse("file:///path/to/openapi.yaml", return_type=CommentedMap)
 # Access line/column information
 print(doc.lc.line, doc.lc.col)
+
+# Use ruamel.yaml AST mode (returns YAML nodes with source tracking)
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
+parser = OpenAPIParser("ruamel-ast")
+node = parser.parse("file:///path/to/openapi.yaml", return_type=MappingNode)
+# Access precise line/column for any node
+for key_node, value_node in node.value:
+    print(f"{key_node.value} at line {key_node.start_mark.line}")
 ```
 
 ## Configuration Options
@@ -171,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")
+  - `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`
@@ -282,6 +292,91 @@ doc = parser.parse(content, return_type=CommentedMap)
 print(f"Line: {doc.lc.line}, Column: {doc.lc.col}")
 ```
 
+### ruamel-ast
+ruamel.yaml AST mode that returns YAML nodes with complete source location tracking. Ideal for building low-level data models with precise error reporting.
+
+**Accepts:** `text` (JSON/YAML strings), `uri` (file paths/URLs)
+
+**Returns:** `yaml.MappingNode` (YAML AST) instead of dictionaries
+
+```python
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
+
+parser = OpenAPIParser("ruamel-ast")
+node = parser.parse(content, return_type=MappingNode)
+
+# Access YAML nodes with source information
+assert isinstance(node, MappingNode)
+
+# Get precise line/column information for any node
+for key_node, value_node in node.value:
+    print(f"Key: {key_node.value}")
+    print(f"  Line: {key_node.start_mark.line}, Column: {key_node.start_mark.column}")
+
+# Perfect for building low-level datamodels with source tracking
+# Works seamlessly with jentic-openapi-datamodels
+```
+
+**Note:** You can also import directly from `ruamel.yaml` if preferred:
+```python
+from ruamel.yaml import MappingNode  # Alternative import
+```
+
+**Use Cases:**
+- Building low-level data models that preserve source locations
+- Implementing precise error reporting with line/column numbers
+- 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.0a19 → jentic_openapi_parser-1.0.0a21}/README.md

@@ -6,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, or ruamel.yaml roundtrip 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
@@ -35,12 +36,12 @@ doc = parser.parse("file:///path/to/openapi.yaml")
 print(doc["info"]["title"])
 
 # Parse from JSON string
-json_doc = '{"openapi":"3.1.0","info":{"title":"My API","version":"1.0.0"}}'
+json_doc = '{"openapi":"3.1.2","info":{"title":"My API","version":"1.0.0"}}'
 doc = parser.parse(json_doc)
 
 # Parse from YAML string
 yaml_doc = """
-openapi: 3.1.0
+openapi: 3.1.2
 info:
   title: My API
   version: 1.0.0
@@ -77,6 +78,14 @@ parser = OpenAPIParser("ruamel-roundtrip")
 doc = parser.parse("file:///path/to/openapi.yaml", return_type=CommentedMap)
 # Access line/column information
 print(doc.lc.line, doc.lc.col)
+
+# Use ruamel.yaml AST mode (returns YAML nodes with source tracking)
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
+parser = OpenAPIParser("ruamel-ast")
+node = parser.parse("file:///path/to/openapi.yaml", return_type=MappingNode)
+# Access precise line/column for any node
+for key_node, value_node in node.value:
+    print(f"{key_node.value} at line {key_node.start_mark.line}")
 ```
 
 ## Configuration Options
@@ -153,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")
+  - `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`
@@ -264,6 +273,91 @@ doc = parser.parse(content, return_type=CommentedMap)
 print(f"Line: {doc.lc.line}, Column: {doc.lc.col}")
 ```
 
+### ruamel-ast
+ruamel.yaml AST mode that returns YAML nodes with complete source location tracking. Ideal for building low-level data models with precise error reporting.
+
+**Accepts:** `text` (JSON/YAML strings), `uri` (file paths/URLs)
+
+**Returns:** `yaml.MappingNode` (YAML AST) instead of dictionaries
+
+```python
+from jentic.apitools.openapi.parser.backends.ruamel_ast import MappingNode
+
+parser = OpenAPIParser("ruamel-ast")
+node = parser.parse(content, return_type=MappingNode)
+
+# Access YAML nodes with source information
+assert isinstance(node, MappingNode)
+
+# Get precise line/column information for any node
+for key_node, value_node in node.value:
+    print(f"Key: {key_node.value}")
+    print(f"  Line: {key_node.start_mark.line}, Column: {key_node.start_mark.column}")
+
+# Perfect for building low-level datamodels with source tracking
+# Works seamlessly with jentic-openapi-datamodels
+```
+
+**Note:** You can also import directly from `ruamel.yaml` if preferred:
+```python
+from ruamel.yaml import MappingNode  # Alternative import
+```
+
+**Use Cases:**
+- Building low-level data models that preserve source locations
+- Implementing precise error reporting with line/column numbers
+- 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.0a19 → jentic_openapi_parser-1.0.0a21}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jentic-openapi-parser"
-version = "1.0.0-alpha.19"
+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.19",
+    "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"]
@@ -37,4 +39,6 @@ build-backend = "uv_build"
 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.0a21/src/jentic/apitools/openapi/parser/backends/ruamel_ast.py

@@ -0,0 +1,58 @@
+import logging
+from collections.abc import Sequence
+from typing import Literal
+
+from ruamel.yaml import YAML, MappingNode
+
+from jentic.apitools.openapi.common.uri import is_uri_like
+from jentic.apitools.openapi.parser.backends.base import BaseParserBackend
+from jentic.apitools.openapi.parser.core.loader import load_uri
+
+
+__all__ = [
+    "RuamelASTParserBackend",
+    # Re-export Mapping YAML node type for convenience
+    "MappingNode",
+]
+
+
+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)
+        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) -> 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:
+        if not isinstance(text, (bytes, str)):
+            raise TypeError(f"Unsupported document type: {type(text)!r}")
+
+        if isinstance(text, bytes):
+            text = text.decode()
+
+        node: MappingNode = self.yaml.compose(text)
+        logger.debug("YAML document successfully parsed")
+
+        if not isinstance(node, MappingNode):
+            raise TypeError(f"Parsed YAML document is not a mapping: {type(node)!r}")
+
+        return node

{jentic_openapi_parser-1.0.0a19 → 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.0a19 → 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):