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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jentic-openapi-parser
-Version: 1.0.0a19
+Version: 1.0.0a20
 Summary: Jentic OpenAPI Parser
 Author: Jentic
 Author-email: Jentic <hello@jentic.com>
@@ -8,7 +8,7 @@ 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.0a20
 Requires-Dist: pyyaml~=6.0.3
 Requires-Dist: requests~=2.32.5
 Requires-Dist: ruamel-yaml~=0.18.15
@@ -24,7 +24,7 @@ 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)
 - **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 +53,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 +95,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 +179,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")
   - `BaseParserBackend`: Instance of a parser backend
   - `Type[BaseParserBackend]`: Class of a parser backend (will be instantiated)
   - Defaults to `"pyyaml"` if `None`
@@ -282,6 +290,42 @@ 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
+
 ## Testing
 
 Run the test suite:

{jentic_openapi_parser-1.0.0a19 → jentic_openapi_parser-1.0.0a20}/README.md

@@ -6,7 +6,7 @@ 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)
 - **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 +35,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 +77,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 +161,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")
   - `BaseParserBackend`: Instance of a parser backend
   - `Type[BaseParserBackend]`: Class of a parser backend (will be instantiated)
   - Defaults to `"pyyaml"` if `None`
@@ -264,6 +272,42 @@ 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
+
 ## Testing
 
 Run the test suite:

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

@@ -1,6 +1,6 @@
 [project]
 name = "jentic-openapi-parser"
-version = "1.0.0-alpha.19"
+version = "1.0.0-alpha.20"
 description = "Jentic OpenAPI Parser"
 readme = "README.md"
 authors = [{ name = "Jentic", email = "hello@jentic.com" }]
@@ -9,7 +9,7 @@ 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.20",
     "pyyaml~=6.0.3",
     "requests~=2.32.5",
     "ruamel-yaml~=0.18.15"
@@ -37,4 +37,5 @@ 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"
 

jentic_openapi_parser-1.0.0a20/src/jentic/apitools/openapi/parser/backends/ruamel_ast.py

@@ -0,0 +1,56 @@
+import logging
+from collections.abc import Sequence
+from typing import Literal
+
+from ruamel.yaml import MappingNode, ScalarNode, SequenceNode
+
+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.core.loader import load_uri
+
+
+__all__ = [
+    "RuamelASTParserBackend",
+    # Re-export common YAML node types for convenience
+    "MappingNode",
+    "ScalarNode",
+    "SequenceNode",
+]
+
+
+class RuamelASTParserBackend(RuamelRoundTripParserBackend):
+    def parse(self, document: str, *, logger: logging.Logger | None = None) -> MappingNode:  # type: ignore[override]
+        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:  # type: ignore[override]
+        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]
+        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