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

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/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/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/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):

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

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

@@ -1,17 +1,19 @@
 jentic/apitools/openapi/parser/backends/base.py,sha256=0lh1z_Y0J-76PUayajiC1kD36xyl71ekFBBEbZlEM5g,825
+jentic/apitools/openapi/parser/backends/datamodel_low.py,sha256=Ahr-IBnB7VyXYmoMjn1546foZC8VAOOgaKfcQAHf6Dg,4193
 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_roundtrip.py,sha256=03DJgkbf_NOBON0PnokOAG1HBATaLkHxdZtT0M9M66U,285
-jentic/apitools/openapi/parser/backends/ruamel_safe.py,sha256=0s8R9VU9kTnzUoo6ash8x7JOAyl7Z8-VNi-hvcskPnY,1954
+jentic/apitools/openapi/parser/backends/ruamel_ast.py,sha256=aMCKLHxsEJ4FWwMZN7oSHz31kg-130HWGqttDFsW4w8,2024
+jentic/apitools/openapi/parser/backends/ruamel_roundtrip.py,sha256=gGSPsK_xTaZgLZoKl5a8iDIwsjwnj1Y3xisBxcpZMNA,400
+jentic/apitools/openapi/parser/backends/ruamel_safe.py,sha256=9WNBgcU9wotBWIYOgA_12cEx6_0ZtmCdS03ypejhpKk,2031
 jentic/apitools/openapi/parser/core/__init__.py,sha256=FChrSb22a7m9LOku4KG0_Vsm4ConyEAlrFW3qLXjMAY,578
 jentic/apitools/openapi/parser/core/exceptions.py,sha256=wtH_kRvn3b3TsM4HEkTKLCdIQVEfsN-dEct8oVlnGrM,693
 jentic/apitools/openapi/parser/core/loader.py,sha256=Q57UiWiJACeuxMdroHAAEcoU-lwvxiRBcdz106N2VVQ,1462
 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.0a21.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+jentic_openapi_parser-1.0.0a21.dist-info/licenses/NOTICE,sha256=pAOGW-rGw9KNc2cuuLWZkfx0GSTV4TicbgBKZSLPMIs,168
+jentic_openapi_parser-1.0.0a21.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+jentic_openapi_parser-1.0.0a21.dist-info/entry_points.txt,sha256=eMCrbxAvCRJRKUU4ZwsD-soLKoDomhzrJ19ayMyeXNo,497
+jentic_openapi_parser-1.0.0a21.dist-info/METADATA,sha256=wdF9u8LKJvZ1rsVgkbJWeJXtG4escW6bprhlmupT3-M,11772
+jentic_openapi_parser-1.0.0a21.dist-info/RECORD,,

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

@@ -1,5 +1,7 @@
 [jentic.apitools.openapi.parser.backends]
+datamodel-low = jentic.apitools.openapi.parser.backends.datamodel_low:DataModelLowParserBackend
 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