jentic-openapi-parser 1.0.0a10__tar.gz

jentic_openapi_parser-1.0.0a10/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

jentic_openapi_parser-1.0.0a10/NOTICE

@@ -0,0 +1,4 @@
+Jentic OpenAPI Tools
+Copyright (c) 2025 Jentic
+Jentic OpenAPI Tools is licensed under Apache 2.0 license.
+Copy of the Apache 2.0 license can be found in `LICENSE` file.

jentic_openapi_parser-1.0.0a10/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: jentic-openapi-parser
+Version: 1.0.0a10
+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.0a10
+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.
+
+## Features
+
+- **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
+- **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
+
+## Installation
+
+```bash
+pip install jentic-openapi-parser
+```
+
+**Prerequisites:**
+- Python 3.11+
+
+## Quick Start
+
+### Basic Parsing
+
+```python
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+
+# Create parser with default backend (pyyaml)
+parser = OpenAPIParser()
+
+# Parse from file URI
+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"}}'
+doc = parser.parse(json_doc)
+
+# Parse from YAML string
+yaml_doc = """
+openapi: 3.1.0
+info:
+  title: My API
+  version: 1.0.0
+"""
+doc = parser.parse(yaml_doc)
+```
+
+### Parse with Type Conversion
+
+```python
+from ruamel.yaml import CommentedMap
+
+# Parse with specific return type
+parser = OpenAPIParser("ruamel-roundtrip")
+doc = parser.parse(yaml_doc, return_type=CommentedMap)
+
+# Parse with strict type checking
+doc = parser.parse(yaml_doc, return_type=CommentedMap, strict=True)
+```
+
+### Using Different Backends
+
+```python
+# Use PyYAML backend (default)
+parser = OpenAPIParser("pyyaml")
+doc = parser.parse("file:///path/to/openapi.yaml")
+
+# Use ruamel.yaml backend (safe mode)
+parser = OpenAPIParser("ruamel-safe")
+doc = parser.parse("file:///path/to/openapi.yaml")
+
+# Use ruamel.yaml roundtrip mode (preserves comments and formatting info)
+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)
+```
+
+## Configuration Options
+
+### Backend Selection
+
+```python
+# Use backend by name
+parser = OpenAPIParser("pyyaml")
+
+# Pass backend instance directly
+from jentic.apitools.openapi.parser.backends.pyyaml import PyYAMLParserBackend
+backend = PyYAMLParserBackend()
+parser = OpenAPIParser(backend=backend)
+
+# Pass backend class
+parser = OpenAPIParser(backend=PyYAMLParserBackend)
+```
+
+### Custom Configuration
+
+```python
+import logging
+
+# Configure with custom logger and timeouts
+logger = logging.getLogger(__name__)
+parser = OpenAPIParser(
+    backend="pyyaml",
+    logger=logger,
+    conn_timeout=10,  # Connection timeout in seconds
+    read_timeout=30   # Read timeout in seconds
+)
+```
+
+## Working with Return Types
+
+The parser supports flexible return type handling:
+
+```python
+from ruamel.yaml import CommentedMap
+
+parser = OpenAPIParser("ruamel-roundtrip")
+
+# Without return_type: Returns plain dict
+doc = parser.parse(yaml_doc)
+assert isinstance(doc, dict)
+
+# With return_type: Returns specified type
+doc = parser.parse(yaml_doc, return_type=CommentedMap)
+assert isinstance(doc, CommentedMap)
+
+# With strict=True: Raises error if type doesn't match
+try:
+    doc = parser.parse(yaml_doc, return_type=list, strict=True)
+except TypeConversionError:
+    print("Type mismatch!")
+```
+
+## API Reference
+
+### OpenAPIParser
+
+```python
+class OpenAPIParser:
+    def __init__(
+        self,
+        backend: str | BaseParserBackend | Type[BaseParserBackend] | None = None,
+        *,
+        logger: logging.Logger | None = None,
+        conn_timeout: int = 5,
+        read_timeout: int = 10,
+    ) -> None
+```
+
+**Parameters:**
+- `backend`: Parser backend to use. Can be:
+  - `str`: Name of a backend registered via entry points (e.g., "pyyaml", "ruamel-safe", "ruamel-roundtrip")
+  - `BaseParserBackend`: Instance of a parser backend
+  - `Type[BaseParserBackend]`: Class of a parser backend (will be instantiated)
+  - Defaults to `"pyyaml"` if `None`
+- `logger`: Custom logger instance (optional)
+- `conn_timeout`: Connection timeout in seconds for URI loading
+- `read_timeout`: Read timeout in seconds for URI loading
+
+**Methods:**
+
+- `parse(document: str) -> dict[str, Any]`
+  - Parse without type conversion, returns plain dict
+
+- `parse(document: str, *, return_type: type[T], strict: bool = False) -> T`
+  - Parse with optional type conversion
+  - `document`: File URI or text string (JSON/YAML)
+  - `return_type`: Expected return type (e.g., `dict`, `CommentedMap`)
+  - `strict`: If `True`, raises `TypeConversionError` if result doesn't match `return_type`
+  - Returns: Parsed document
+
+- `load_uri(uri: str) -> str`
+  - Load content from a URI (HTTP(S), file://, or local file path)
+
+- `list_backends() -> list[str]`
+  - Static method to list all available parser backends
+
+### JSON Serialization
+
+The parser includes enhanced JSON serialization utilities for working with OpenAPI documents:
+
+```python
+from jentic.apitools.openapi.parser.core import json_dumps
+
+# Serialize with special type support
+from datetime import datetime
+from pathlib import Path
+from uuid import UUID
+
+data = {
+    "timestamp": datetime(2025, 10, 1, 12, 0, 0),
+    "id": UUID("550e8400-e29b-41d4-a716-446655440000"),
+    "path": Path("/var/log/app.log")
+}
+
+json_str = json_dumps(data, indent=2)
+# Output:
+# {
+#   "id": "550e8400-e29b-41d4-a716-446655440000",
+#   "path": "/var/log/app.log",
+#   "timestamp": "2025-10-01T12:00:00"
+# }
+```
+
+**Supported Types:**
+- `datetime` / `date` - Serialized to ISO 8601 format
+- `UUID` - Converted to string
+- `Path` - Converted to string
+- `Decimal` - Converted to float
+- `Enum` - Serialized using enum value
+- `attrs` classes - Converted to dictionaries
+
+### Exceptions
+
+```python
+from jentic.apitools.openapi.parser.core.exceptions import (
+    OpenAPIParserError,        # Base exception
+    DocumentParseError,        # Parsing failed
+    DocumentLoadError,         # URI loading failed
+    InvalidBackendError,       # Backend initialization failed
+    BackendNotFoundError,      # Backend not found
+    TypeConversionError,       # Type conversion failed
+)
+```
+
+## Available Backends
+
+### pyyaml (Default)
+Standard PyYAML-based parser. Fast and reliable for basic parsing needs.
+
+**Accepts:** `text` (JSON/YAML strings)
+
+```python
+parser = OpenAPIParser("pyyaml")
+doc = parser.parse(content)
+```
+
+### ruamel-safe
+ruamel.yaml-based parser with safe loading. Provides better YAML 1.2 support than PyYAML.
+
+**Accepts:** `text` (JSON/YAML strings), `uri` (file paths/URLs)
+
+```python
+parser = OpenAPIParser("ruamel-safe")
+doc = parser.parse(content)
+```
+
+### ruamel-roundtrip
+ruamel.yaml roundtrip mode that preserves comments, formatting, and provides line/column information.
+
+**Accepts:** `text` (JSON/YAML strings), `uri` (file paths/URLs)
+
+```python
+from ruamel.yaml import CommentedMap
+
+parser = OpenAPIParser("ruamel-roundtrip")
+doc = parser.parse(content, return_type=CommentedMap)
+
+# Access line/column information
+print(f"Line: {doc.lc.line}, Column: {doc.lc.col}")
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+uv run --package jentic-openapi-parser pytest packages/jentic-openapi-parser -v
+```

jentic_openapi_parser-1.0.0a10/README.md

@@ -0,0 +1,273 @@
+# 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.
+
+## Features
+
+- **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
+- **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
+
+## Installation
+
+```bash
+pip install jentic-openapi-parser
+```
+
+**Prerequisites:**
+- Python 3.11+
+
+## Quick Start
+
+### Basic Parsing
+
+```python
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+
+# Create parser with default backend (pyyaml)
+parser = OpenAPIParser()
+
+# Parse from file URI
+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"}}'
+doc = parser.parse(json_doc)
+
+# Parse from YAML string
+yaml_doc = """
+openapi: 3.1.0
+info:
+  title: My API
+  version: 1.0.0
+"""
+doc = parser.parse(yaml_doc)
+```
+
+### Parse with Type Conversion
+
+```python
+from ruamel.yaml import CommentedMap
+
+# Parse with specific return type
+parser = OpenAPIParser("ruamel-roundtrip")
+doc = parser.parse(yaml_doc, return_type=CommentedMap)
+
+# Parse with strict type checking
+doc = parser.parse(yaml_doc, return_type=CommentedMap, strict=True)
+```
+
+### Using Different Backends
+
+```python
+# Use PyYAML backend (default)
+parser = OpenAPIParser("pyyaml")
+doc = parser.parse("file:///path/to/openapi.yaml")
+
+# Use ruamel.yaml backend (safe mode)
+parser = OpenAPIParser("ruamel-safe")
+doc = parser.parse("file:///path/to/openapi.yaml")
+
+# Use ruamel.yaml roundtrip mode (preserves comments and formatting info)
+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)
+```
+
+## Configuration Options
+
+### Backend Selection
+
+```python
+# Use backend by name
+parser = OpenAPIParser("pyyaml")
+
+# Pass backend instance directly
+from jentic.apitools.openapi.parser.backends.pyyaml import PyYAMLParserBackend
+backend = PyYAMLParserBackend()
+parser = OpenAPIParser(backend=backend)
+
+# Pass backend class
+parser = OpenAPIParser(backend=PyYAMLParserBackend)
+```
+
+### Custom Configuration
+
+```python
+import logging
+
+# Configure with custom logger and timeouts
+logger = logging.getLogger(__name__)
+parser = OpenAPIParser(
+    backend="pyyaml",
+    logger=logger,
+    conn_timeout=10,  # Connection timeout in seconds
+    read_timeout=30   # Read timeout in seconds
+)
+```
+
+## Working with Return Types
+
+The parser supports flexible return type handling:
+
+```python
+from ruamel.yaml import CommentedMap
+
+parser = OpenAPIParser("ruamel-roundtrip")
+
+# Without return_type: Returns plain dict
+doc = parser.parse(yaml_doc)
+assert isinstance(doc, dict)
+
+# With return_type: Returns specified type
+doc = parser.parse(yaml_doc, return_type=CommentedMap)
+assert isinstance(doc, CommentedMap)
+
+# With strict=True: Raises error if type doesn't match
+try:
+    doc = parser.parse(yaml_doc, return_type=list, strict=True)
+except TypeConversionError:
+    print("Type mismatch!")
+```
+
+## API Reference
+
+### OpenAPIParser
+
+```python
+class OpenAPIParser:
+    def __init__(
+        self,
+        backend: str | BaseParserBackend | Type[BaseParserBackend] | None = None,
+        *,
+        logger: logging.Logger | None = None,
+        conn_timeout: int = 5,
+        read_timeout: int = 10,
+    ) -> None
+```
+
+**Parameters:**
+- `backend`: Parser backend to use. Can be:
+  - `str`: Name of a backend registered via entry points (e.g., "pyyaml", "ruamel-safe", "ruamel-roundtrip")
+  - `BaseParserBackend`: Instance of a parser backend
+  - `Type[BaseParserBackend]`: Class of a parser backend (will be instantiated)
+  - Defaults to `"pyyaml"` if `None`
+- `logger`: Custom logger instance (optional)
+- `conn_timeout`: Connection timeout in seconds for URI loading
+- `read_timeout`: Read timeout in seconds for URI loading
+
+**Methods:**
+
+- `parse(document: str) -> dict[str, Any]`
+  - Parse without type conversion, returns plain dict
+
+- `parse(document: str, *, return_type: type[T], strict: bool = False) -> T`
+  - Parse with optional type conversion
+  - `document`: File URI or text string (JSON/YAML)
+  - `return_type`: Expected return type (e.g., `dict`, `CommentedMap`)
+  - `strict`: If `True`, raises `TypeConversionError` if result doesn't match `return_type`
+  - Returns: Parsed document
+
+- `load_uri(uri: str) -> str`
+  - Load content from a URI (HTTP(S), file://, or local file path)
+
+- `list_backends() -> list[str]`
+  - Static method to list all available parser backends
+
+### JSON Serialization
+
+The parser includes enhanced JSON serialization utilities for working with OpenAPI documents:
+
+```python
+from jentic.apitools.openapi.parser.core import json_dumps
+
+# Serialize with special type support
+from datetime import datetime
+from pathlib import Path
+from uuid import UUID
+
+data = {
+    "timestamp": datetime(2025, 10, 1, 12, 0, 0),
+    "id": UUID("550e8400-e29b-41d4-a716-446655440000"),
+    "path": Path("/var/log/app.log")
+}
+
+json_str = json_dumps(data, indent=2)
+# Output:
+# {
+#   "id": "550e8400-e29b-41d4-a716-446655440000",
+#   "path": "/var/log/app.log",
+#   "timestamp": "2025-10-01T12:00:00"
+# }
+```
+
+**Supported Types:**
+- `datetime` / `date` - Serialized to ISO 8601 format
+- `UUID` - Converted to string
+- `Path` - Converted to string
+- `Decimal` - Converted to float
+- `Enum` - Serialized using enum value
+- `attrs` classes - Converted to dictionaries
+
+### Exceptions
+
+```python
+from jentic.apitools.openapi.parser.core.exceptions import (
+    OpenAPIParserError,        # Base exception
+    DocumentParseError,        # Parsing failed
+    DocumentLoadError,         # URI loading failed
+    InvalidBackendError,       # Backend initialization failed
+    BackendNotFoundError,      # Backend not found
+    TypeConversionError,       # Type conversion failed
+)
+```
+
+## Available Backends
+
+### pyyaml (Default)
+Standard PyYAML-based parser. Fast and reliable for basic parsing needs.
+
+**Accepts:** `text` (JSON/YAML strings)
+
+```python
+parser = OpenAPIParser("pyyaml")
+doc = parser.parse(content)
+```
+
+### ruamel-safe
+ruamel.yaml-based parser with safe loading. Provides better YAML 1.2 support than PyYAML.
+
+**Accepts:** `text` (JSON/YAML strings), `uri` (file paths/URLs)
+
+```python
+parser = OpenAPIParser("ruamel-safe")
+doc = parser.parse(content)
+```
+
+### ruamel-roundtrip
+ruamel.yaml roundtrip mode that preserves comments, formatting, and provides line/column information.
+
+**Accepts:** `text` (JSON/YAML strings), `uri` (file paths/URLs)
+
+```python
+from ruamel.yaml import CommentedMap
+
+parser = OpenAPIParser("ruamel-roundtrip")
+doc = parser.parse(content, return_type=CommentedMap)
+
+# Access line/column information
+print(f"Line: {doc.lc.line}, Column: {doc.lc.col}")
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+uv run --package jentic-openapi-parser pytest packages/jentic-openapi-parser -v
+```

jentic_openapi_parser-1.0.0a10/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "jentic-openapi-parser"
+version = "1.0.0-alpha.10"
+description = "Jentic OpenAPI Parser"
+readme = "README.md"
+authors = [{ name = "Jentic", email = "hello@jentic.com" }]
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.11"
+dependencies = [
+    "attrs~=25.4.0",
+    "jentic-openapi-common~=1.0.0-alpha.10",
+    "pyyaml~=6.0.3",
+    "requests~=2.32.5",
+    "ruamel-yaml~=0.18.15"
+]
+
+[project.urls]
+Homepage = "https://github.com/jentic/jentic-openapi-tools"
+
+[tool.uv]
+package = true
+
+[tool.uv.build-backend]
+namespace = true
+module-name = "jentic.apitools.openapi.parser"
+module-root = "src/"
+
+[tool.uv.sources]
+jentic-openapi-common = { workspace = true }
+
+[build-system]
+requires = ["uv_build~=0.8.15"]
+build-backend = "uv_build"
+
+[project.entry-points."jentic.apitools.openapi.parser.backends"]
+base = "jentic.apitools.openapi.parser.backends.base:BaseParserBackend"
+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"
+

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/backends/base.py

@@ -0,0 +1,29 @@
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Any
+
+
+__all__ = ["BaseParserBackend"]
+
+
+class BaseParserBackend(ABC):
+    """Interface that all Parser backends must implement."""
+
+    @abstractmethod
+    def parse(self, document: str, *, logger: logging.Logger | None = None) -> Any:
+        """Parses an OpenAPI document given by URI or file path or text.
+        Returns a dict."""
+        ...
+
+    @staticmethod
+    @abstractmethod
+    def accepts() -> Sequence[str]:
+        """Return a sequence of input formats this backend can handle.
+
+        Returns:
+            Sequence of supported input formats. Common values:
+            - "uri": Accepts URI/file path references
+            - "text": Accepts string (JSON/YAML) representation
+        """
+        ...

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/backends/pyyaml.py

@@ -0,0 +1,50 @@
+import logging
+from collections.abc import Sequence
+from typing import Literal, Mapping
+
+import yaml
+
+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__ = ["PyYAMLParserBackend"]
+
+
+class PyYAMLParserBackend(BaseParserBackend):
+    def parse(self, document: str, *, logger: logging.Logger | None = None) -> dict:
+        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) -> dict:
+        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) -> dict:
+        if not isinstance(text, (bytes, str)):
+            raise TypeError(f"Unsupported document type: {type(text)!r}")
+
+        if isinstance(text, bytes):
+            text = text.decode()
+
+        data = yaml.safe_load(text)
+        logger.debug("Document successfully parsed")
+
+        if not isinstance(data, Mapping):
+            raise TypeError(f"Parsed document is not a mapping: {type(data)!r}")
+
+        return dict(data)

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/backends/ruamel_roundtrip.py

@@ -0,0 +1,9 @@
+from jentic.apitools.openapi.parser.backends.ruamel_safe import RuamelSafeParserBackend
+
+
+__all__ = ["RuamelRoundTripParserBackend"]
+
+
+class RuamelRoundTripParserBackend(RuamelSafeParserBackend):
+    def __init__(self, pure: bool = True):
+        super().__init__(typ="rt", pure=pure)

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/backends/ruamel_safe.py

@@ -0,0 +1,54 @@
+import logging
+from collections.abc import Sequence
+from typing import Literal, Mapping
+
+from ruamel.yaml import YAML, CommentedMap
+
+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__ = ["RuamelSafeParserBackend"]
+
+
+class RuamelSafeParserBackend(BaseParserBackend):
+    def __init__(self, typ: str = "safe", 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) -> CommentedMap:
+        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) -> CommentedMap:
+        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) -> CommentedMap:
+        if not isinstance(text, (bytes, str)):
+            raise TypeError(f"Unsupported document type: {type(text)!r}")
+
+        if isinstance(text, bytes):
+            text = text.decode()
+
+        data: CommentedMap = self.yaml.load(text)
+        logger.debug("YAML document successfully parsed")
+
+        if not isinstance(data, Mapping):
+            raise TypeError(f"Parsed YAML document is not a mapping: {type(data)!r}")
+
+        return data

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/core/__init__.py

@@ -0,0 +1,27 @@
+from .exceptions import (
+    BackendNotFoundError,
+    DocumentLoadError,
+    DocumentParseError,
+    InvalidBackendError,
+    OpenAPIParserError,
+    TypeConversionError,
+)
+from .loader import load_uri
+from .openapi_parser import OpenAPIParser
+from .serialization import json_dumps
+
+
+__all__ = [
+    "OpenAPIParser",
+    # URI utilities
+    "load_uri",
+    # Serialization
+    "json_dumps",
+    # Parser exceptions
+    "OpenAPIParserError",
+    "DocumentParseError",
+    "DocumentLoadError",
+    "TypeConversionError",
+    "InvalidBackendError",
+    "BackendNotFoundError",
+]

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/core/exceptions.py

@@ -0,0 +1,29 @@
+"""
+OpenAPI Parser exceptions.
+
+This module defines all custom exceptions used by the OpenAPI parser.
+"""
+
+
+class OpenAPIParserError(Exception):
+    """Base exception for OpenAPI parser errors."""
+
+
+class InvalidBackendError(OpenAPIParserError):
+    """Raised when an invalid backend is provided."""
+
+
+class BackendNotFoundError(InvalidBackendError):
+    """Raised when a named backend cannot be found."""
+
+
+class DocumentParseError(OpenAPIParserError):
+    """Raised when parsing fails."""
+
+
+class DocumentLoadError(OpenAPIParserError):
+    """Raised when document loading fails."""
+
+
+class TypeConversionError(OpenAPIParserError):
+    """Raised when type conversion fails in strict mode."""

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/core/loader.py

@@ -0,0 +1,45 @@
+"""Document loading utilities for OpenAPI parser."""
+
+import logging
+
+import requests
+
+from jentic.apitools.openapi.common.uri import is_file_uri, is_http_https_url, resolve_to_absolute
+
+from .exceptions import DocumentLoadError
+
+
+__all__ = ["load_uri"]
+
+
+def load_uri(
+    uri: str, conn_timeout: int, read_timeout: int, logger: logging.Logger | None = None
+) -> str:
+    logger = logger or logging.getLogger(__name__)
+    resolved_uri = resolve_to_absolute(uri)
+    content = ""
+
+    try:
+        if is_http_https_url(resolved_uri):
+            logger.info("Loading URI %s", resolved_uri)
+            resp = requests.get(resolved_uri, timeout=(conn_timeout, read_timeout))
+            logger.info(
+                "Load of URI %s completed, status: %s, content length: %s",
+                resolved_uri,
+                resp.status_code,
+                len(resp.content),
+            )
+            content = resp.text
+        elif is_file_uri(resolved_uri):
+            logger.info("Loading local file %s", resolved_uri)
+            with open(resolved_uri, "r", encoding="utf-8") as f:
+                content = f.read()
+        else:
+            # Treat as local file path
+            logger.info("Loading local file %s", resolved_uri)
+            with open(resolved_uri, "r", encoding="utf-8") as f:
+                content = f.read()
+    except Exception as e:
+        raise DocumentLoadError(f"Failed to load URI '{uri}': {e}") from e
+
+    return content

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/core/openapi_parser.py

@@ -0,0 +1,206 @@
+import importlib.metadata
+import logging
+import warnings
+from typing import Any, Mapping, Optional, Sequence, Type, TypeVar, cast, overload
+
+from jentic.apitools.openapi.common.uri import is_uri_like
+from jentic.apitools.openapi.parser.backends.base import BaseParserBackend
+
+from .exceptions import (
+    BackendNotFoundError,
+    DocumentParseError,
+    InvalidBackendError,
+    OpenAPIParserError,
+    TypeConversionError,
+)
+from .loader import load_uri
+
+
+__all__ = ["OpenAPIParser"]
+
+
+# Cache entry points at module level for performance
+try:
+    _PARSER_BACKENDS = {
+        ep.name: ep
+        for ep in importlib.metadata.entry_points(group="jentic.apitools.openapi.parser.backends")
+    }
+except Exception as e:
+    warnings.warn(f"Failed to load parser backend entry points: {e}", RuntimeWarning)
+    _PARSER_BACKENDS = {}
+
+T = TypeVar("T")
+
+
+class OpenAPIParser:
+    """
+    Provides a parser for OpenAPI specifications using customizable backends.
+
+    This class is designed to facilitate the parsing of OpenAPI documents.
+    It supports one backend at a time and can be extended through backends.
+
+    Attributes:
+        backend: Backend used by the parser implementing the BaseParserBackend interface.
+        logger: Logger instance.
+        conn_timeout: Connection timeout in seconds.
+        read_timeout: Read timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        backend: str | BaseParserBackend | Type[BaseParserBackend] | None = None,
+        *,
+        logger: logging.Logger | None = None,
+        conn_timeout: int = 5,
+        read_timeout: int = 10,
+    ):
+        logger = logger or logging.getLogger(__name__)
+        backend = backend if backend else "pyyaml"
+        self.backend: BaseParserBackend
+        self.logger = logger
+        self.conn_timeout = conn_timeout
+        self.read_timeout = read_timeout
+
+        if isinstance(backend, str):
+            try:
+                if backend in _PARSER_BACKENDS:
+                    try:
+                        logger.debug(f"using parser backend '{backend}'")
+                        backend_class = _PARSER_BACKENDS[backend].load()  # loads the class
+                        self.backend = backend_class()
+                    except Exception as e:
+                        raise InvalidBackendError(
+                            f"Failed to load parser backend '{backend}': {e}"
+                        ) from e
+                else:
+                    logger.error(f"No parser backend named '{backend}' found")
+                    raise BackendNotFoundError(f"No parser backend named '{backend}' found")
+            except OpenAPIParserError:
+                raise
+            except Exception as e:
+                raise InvalidBackendError(f"Error initializing backend '{backend}': {e}") from e
+
+        elif isinstance(backend, BaseParserBackend):
+            logger.debug(f"using parser backend '{type[backend]}'")
+            self.backend = backend
+        elif isinstance(backend, type) and issubclass(backend, BaseParserBackend):
+            try:
+                # class (not instance) is passed
+                self.backend = backend()
+                logger.debug(f"using parser backend '{type[backend]}'")
+            except Exception as e:
+                raise InvalidBackendError(
+                    f"Failed to instantiate backend class '{backend.__name__}': {e}"
+                ) from e
+
+        else:
+            logger.error("Invalid backend type: must be name or backend class/instance")
+            raise InvalidBackendError(
+                "Invalid backend type: must be a backend name (str), "
+                "BaseParserBackend instance, or BaseParserBackend class"
+            )
+
+    @overload
+    def parse(self, document: str) -> dict[str, Any]: ...
+
+    @overload
+    def parse(self, document: str, *, return_type: type[T], strict: bool = False) -> T: ...
+
+    def parse(
+        self, document: str, *, return_type: type[T] | None = None, strict: bool = False
+    ) -> Any:
+        try:
+            raw = self._parse(document)
+        except OpenAPIParserError:
+            raise
+        except Exception as e:
+            raise DocumentParseError(f"Unexpected error during parsing: {e}") from e
+
+        if return_type is None:
+            return self._to_plain(raw)
+
+        if strict:
+            if not isinstance(raw, return_type):
+                msg = f"Expected {getattr(return_type, '__name__', return_type)}, got {type(raw).__name__}"
+                self.logger.error(msg)
+                raise TypeConversionError(msg)
+        return cast(T, raw)
+
+    def _parse(self, document: str) -> Any:
+        document_is_uri = is_uri_like(document)
+        backend_document: str | None = None
+
+        self.logger.debug(f"parsing a '{'uri' if document_is_uri else 'text'}'")
+
+        if document_is_uri and "uri" in self.backend.accepts():
+            backend_document = document  # Delegate loading to backend
+        elif document_is_uri and "text" in self.backend.accepts():
+            backend_document = self.load_uri(document)
+        elif not document_is_uri and "text" in self.backend.accepts():
+            backend_document = document
+
+        if backend_document is None:
+            accepted_formats = ", ".join(self.backend.accepts())
+            document_type = "URI" if document_is_uri else "text"
+            raise DocumentParseError(
+                f"Backend '{type(self.backend).__name__}' does not accept {document_type} format. "
+                f"Accepted formats: {accepted_formats}"
+            )
+
+        try:
+            parse_result = self.backend.parse(backend_document, logger=self.logger)
+        except Exception as e:
+            # Log the original error and wrap it
+            msg = f"Failed to parse document with backend '{type(self.backend).__name__}': {e}"
+            self.logger.error(msg)
+            raise DocumentParseError(msg) from e
+
+        if parse_result is None:
+            msg = "No valid document found"
+            self.logger.error(msg)
+            raise DocumentParseError(msg)
+
+        return parse_result
+
+    def has_non_uri_backend(self) -> bool:
+        """Check if any backend accepts 'text' but not 'uri'."""
+        accepted = self.backend.accepts()
+        return "text" in accepted and "uri" not in accepted
+
+    def _to_plain(self, value: Any) -> Any:
+        # Mapping
+        if isinstance(value, Mapping):
+            return {k: self._to_plain(v) for k, v in value.items()}
+
+        # Sequence but NOT str/bytes
+        if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+            return [self._to_plain(x) for x in value]
+
+        # Scalar
+        return value
+
+    @staticmethod
+    def is_uri_like(s: Optional[str]) -> bool:
+        return is_uri_like(s)
+
+    def load_uri(self, uri: str) -> str:
+        return load_uri(uri, self.conn_timeout, self.read_timeout, self.logger)
+
+    @staticmethod
+    def list_backends() -> list[str]:
+        """
+        List all available parser backends registered via entry points.
+
+        This static method discovers and returns the names of all parser backends
+        that have been registered in the 'jentic.apitools.openapi.parser.backends'
+        entry point group.
+
+        Returns:
+            List of backend names that can be used when initializing OpenAPIParser.
+
+        Example:
+            >>> backends = OpenAPIParser.list_backends()
+            >>> print(backends)
+            ['pyyaml', 'ruamel']
+        """
+        return list(_PARSER_BACKENDS.keys())

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/core/py.typed

@@ -0,0 +1,2 @@
+# marker file for type checkers
+

jentic_openapi_parser-1.0.0a10/src/jentic/apitools/openapi/parser/core/serialization.py

@@ -0,0 +1,88 @@
+import json
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from typing import Any, cast
+from uuid import UUID
+
+import attrs
+
+
+__all__ = ["json_dumps", "CustomEncoder"]
+
+
+class CustomEncoder(json.JSONEncoder):
+    """JSON encoder with extended type support for OpenAPI documents.
+
+    Extends the standard json.JSONEncoder to handle additional Python types
+    commonly found in OpenAPI documents and related data structures.
+
+    Supported types:
+        - datetime/date: Serialized using ISO 8601 format
+        - UUID: Converted to string representation
+        - Path: Converted to string representation
+        - Decimal: Converted to float
+        - Enum: Serialized using the enum value
+        - attrs classes: Converted to dictionaries using attrs.asdict()
+    """
+
+    def default(self, o):
+        """Serialize special types not handled by the default JSON encoder.
+
+        Args:
+            o: Object to serialize
+
+        Returns:
+            JSON-serializable representation of the object
+
+        Raises:
+            TypeError: If the object type is not supported
+        """
+        if isinstance(o, (datetime, date)):
+            return o.isoformat()
+        if isinstance(o, (UUID, Path)):
+            return str(o)
+        if isinstance(o, Decimal):
+            return float(o)
+        if isinstance(o, Enum):
+            return o.value
+        if attrs.has(o):
+            return attrs.asdict(cast(Any, o))
+        return super().default(o)
+
+
+def json_dumps(
+    data: Any, indent: int | None = None, *, cls: type[json.JSONEncoder] = CustomEncoder
+) -> str:
+    """Serialize data to a JSON string with extended type support.
+
+    This function provides JSON serialization with automatic handling of
+    datetime, Path, UUID, Decimal, Enum, and attrs-decorated classes.
+    The output is UTF-8 compatible with sorted keys for consistency.
+
+    Args:
+        data: The data to serialize (dict, list, or any JSON-compatible type)
+        indent: Number of spaces for indentation. None for compact output.
+        cls: Custom JSON encoder class. Defaults to CustomEncoder.
+
+    Returns:
+        A JSON string representation of the data
+
+    Raises:
+        TypeError: If the data contains unsupported types
+
+    Example:
+        >>> from datetime import datetime
+        >>> data = {"timestamp": datetime.now(), "count": 42}
+        >>> json_str = json_dumps(data, indent=2)
+    """
+    return json.dumps(
+        data,
+        indent=indent,
+        ensure_ascii=False,
+        allow_nan=False,
+        sort_keys=True,
+        separators=(",", ":") if indent is None else (",", ": "),
+        cls=cls,
+    )