jentic-openapi-parser 1.0.0a19__py3-none-any.whl → 1.0.0a20__py3-none-any.whl

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

{jentic_openapi_parser-1.0.0a19.dist-info → jentic_openapi_parser-1.0.0a20.dist-info}/METADATA

@@ -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.dist-info → jentic_openapi_parser-1.0.0a20.dist-info}/RECORD

@@ -1,6 +1,7 @@
 jentic/apitools/openapi/parser/backends/base.py,sha256=0lh1z_Y0J-76PUayajiC1kD36xyl71ekFBBEbZlEM5g,825
 jentic/apitools/openapi/parser/backends/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 jentic/apitools/openapi/parser/backends/pyyaml.py,sha256=jwWwYtJNWhvfzRKMC1Zcu_HeanuPs_r-1WCdKi4skSU,1720
+jentic/apitools/openapi/parser/backends/ruamel_ast.py,sha256=tloUVBGgIvhByDw6kg3vLyagE1WXsbIPnlV5dn51irU,2043
 jentic/apitools/openapi/parser/backends/ruamel_roundtrip.py,sha256=03DJgkbf_NOBON0PnokOAG1HBATaLkHxdZtT0M9M66U,285
 jentic/apitools/openapi/parser/backends/ruamel_safe.py,sha256=0s8R9VU9kTnzUoo6ash8x7JOAyl7Z8-VNi-hvcskPnY,1954
 jentic/apitools/openapi/parser/core/__init__.py,sha256=FChrSb22a7m9LOku4KG0_Vsm4ConyEAlrFW3qLXjMAY,578
@@ -9,9 +10,9 @@ jentic/apitools/openapi/parser/core/loader.py,sha256=Q57UiWiJACeuxMdroHAAEcoU-lw
 jentic/apitools/openapi/parser/core/openapi_parser.py,sha256=GCFEZZ6g4CrqJauz7AilEAxT-v31D8TP6zsIms9jLl8,7551
 jentic/apitools/openapi/parser/core/py.typed,sha256=uEf7mrkecd7wYBi4Jxa95cHb65ZSz_tMK6UDi55KymA,33
 jentic/apitools/openapi/parser/core/serialization.py,sha256=qr9CBgZzb9GKRPTwOb_MmS0-GdHpVZLmXiHiX1n1cIM,2810
-jentic_openapi_parser-1.0.0a19.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-jentic_openapi_parser-1.0.0a19.dist-info/licenses/NOTICE,sha256=pAOGW-rGw9KNc2cuuLWZkfx0GSTV4TicbgBKZSLPMIs,168
-jentic_openapi_parser-1.0.0a19.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-jentic_openapi_parser-1.0.0a19.dist-info/entry_points.txt,sha256=60Bv8jx6Jhx_ccq1jt8DBsAv94nmri8UdjLyENAksXg,314
-jentic_openapi_parser-1.0.0a19.dist-info/METADATA,sha256=Wjf-KrAYBwf2Q_Td09b9X75C6ozjdXG_1h230Z6rXM8,8038
-jentic_openapi_parser-1.0.0a19.dist-info/RECORD,,
+jentic_openapi_parser-1.0.0a20.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+jentic_openapi_parser-1.0.0a20.dist-info/licenses/NOTICE,sha256=pAOGW-rGw9KNc2cuuLWZkfx0GSTV4TicbgBKZSLPMIs,168
+jentic_openapi_parser-1.0.0a20.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+jentic_openapi_parser-1.0.0a20.dist-info/entry_points.txt,sha256=YwgHz_vdkRaY3DQeMjiEBH_b2mBXwTfQ0H7CvdAZwpY,401
+jentic_openapi_parser-1.0.0a20.dist-info/METADATA,sha256=F61QXve_1a6ZtFePGyb2Le3L0LuGWIrUMQIVXMcRaDM,9754
+jentic_openapi_parser-1.0.0a20.dist-info/RECORD,,

{jentic_openapi_parser-1.0.0a19.dist-info → jentic_openapi_parser-1.0.0a20.dist-info}/entry_points.txt

@@ -1,5 +1,6 @@
 [jentic.apitools.openapi.parser.backends]
 pyyaml = jentic.apitools.openapi.parser.backends.pyyaml:PyYAMLParserBackend
+ruamel-ast = jentic.apitools.openapi.parser.backends.ruamel_ast:RuamelASTParserBackend
 ruamel-roundtrip = jentic.apitools.openapi.parser.backends.ruamel_roundtrip:RuamelRoundTripParserBackend
 ruamel-safe = jentic.apitools.openapi.parser.backends.ruamel_safe:RuamelSafeParserBackend