jentic-openapi-validator 1.0.0a27__tar.gz → 1.0.0a28__tar.gz

{jentic_openapi_validator-1.0.0a27 → jentic_openapi_validator-1.0.0a28}/PKG-INFO

@@ -1,17 +1,17 @@
 Metadata-Version: 2.4
 Name: jentic-openapi-validator
-Version: 1.0.0a27
+Version: 1.0.0a28
 Summary: Jentic OpenAPI Validator
 Author: Jentic
 Author-email: Jentic <hello@jentic.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: jentic-openapi-parser~=1.0.0a27
+Requires-Dist: jentic-openapi-parser~=1.0.0a28
 Requires-Dist: openapi-spec-validator~=0.7.2
 Requires-Dist: lsprotocol~=2025.0.0
-Requires-Dist: jentic-openapi-validator-redocly~=1.0.0a27 ; extra == 'redocly'
-Requires-Dist: jentic-openapi-validator-spectral~=1.0.0a27 ; extra == 'spectral'
+Requires-Dist: jentic-openapi-validator-redocly~=1.0.0a28 ; extra == 'redocly'
+Requires-Dist: jentic-openapi-validator-spectral~=1.0.0a28 ; extra == 'spectral'
 Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/jentic/jentic-openapi-tools
 Provides-Extra: redocly
@@ -26,6 +26,7 @@ A Python library for validating OpenAPI documents using pluggable validator back
 
 - **Pluggable Backend Architecture**: Support for multiple validation strategies via entry points
 - **Multiple Input Formats**: Validate OpenAPI documents from file URIs, JSON/YAML strings, or Python dictionaries
+- **Parallel Execution**: Run multiple backends concurrently using `ProcessPoolExecutor` for improved performance
 - **Aggregated Results**: Collect diagnostics from all configured backends into a single result
 - **Type Safety**: Full type hints with comprehensive docstrings
 - **Extensible Design**: Easy integration of third-party validator backends
@@ -47,6 +48,12 @@ For advanced validation with Spectral:
 pip install jentic-openapi-validator-spectral
 ```
 
+For validation with Redocly:
+
+```bash
+pip install jentic-openapi-validator-redocly
+```
+
 ## Quick Start
 
 ### Basic Validation
@@ -132,6 +139,26 @@ parser = OpenAPIParser()
 validator = OpenAPIValidator(parser=parser)
 ```
 
+### Parallel Execution
+
+When using multiple backends, you can run them in parallel for improved performance:
+
+```python
+# Run backends in parallel using ProcessPoolExecutor
+validator = OpenAPIValidator(backends=["default", "openapi-spec", "spectral"])
+result = validator.validate(document, parallel=True)
+
+# Limit the number of worker processes
+result = validator.validate(document, parallel=True, max_workers=2)
+```
+
+Parallel execution uses `asyncio` with `ProcessPoolExecutor` via `run_in_executor()`, enabling true parallelism that bypasses Python's GIL. This is particularly beneficial when using multiple backends, especially I/O-bound backends like Spectral and Redocly that spawn subprocesses.
+
+**Notes:**
+- `parallel=False` by default (opt-in)
+- With a single backend, `parallel=True` has no effect (runs sequentially)
+- Diagnostics from all backends are aggregated regardless of execution mode
+
 ## Working with ValidationResult
 
 The `ValidationResult` class provides convenient methods for working with validation diagnostics:
@@ -175,24 +202,28 @@ The package includes integration tests for backend discovery and validation. Tes
 class OpenAPIValidator:
     def __init__(
         self,
-        backends: list[str | BaseValidatorBackend | Type[BaseValidatorBackend]] | None = None,
+        backends: Sequence[str | BaseValidatorBackend | Type[BaseValidatorBackend]] | None = None,
         parser: OpenAPIParser | None = None,
     ) -> None
 ```
 
 **Parameters:**
-- `backends`: List of validator backends to use. Each item can be:
-  - `str`: Name of a backend registered via entry points (e.g., "openapi-spec", "spectral")
+- `backends`: Sequence of validator backends to use. Each item can be:
+  - `str`: Name of a backend registered via entry points (e.g., "default", "openapi-spec", "redocly", "spectral")
   - `BaseValidatorBackend`: Instance of a validator backend
   - `Type[BaseValidatorBackend]`: Class of a validator backend (will be instantiated)
-  - Defaults to `["openapi-spec"]` if `None`
+  - Defaults to `["default"]` if `None`
 - `parser`: Custom OpenAPIParser instance (optional)
 
 **Methods:**
 
-- `validate(document: str | dict) -> ValidationResult`
+- `validate(document: str | dict, *, base_url: str | None = None, target: str | None = None, parallel: bool = False, max_workers: int | None = None) -> ValidationResult`
   - Validates an OpenAPI document using all configured backends
   - `document`: File URI, JSON/YAML string, or dictionary
+  - `base_url`: Optional base URL for resolving relative references
+  - `target`: Optional target identifier for validation context
+  - `parallel`: If `True` and multiple backends are configured, run validation in parallel using `ProcessPoolExecutor`. Defaults to `False`.
+  - `max_workers`: Maximum number of worker processes for parallel execution. If `None`, defaults to the number of processors on the machine. Only used when `parallel=True`.
   - Returns: `ValidationResult` with aggregated diagnostics
 
 ### ValidationResult
@@ -218,7 +249,15 @@ class ValidationResult:
 ### default
 Basic validation backend that checks for required OpenAPI fields and structure. Suitable for basic document validation.
 
+### openapi-spec
+Validation backend using the `openapi-spec-validator` library for JSON Schema-based validation of OpenAPI documents. CPU-bound validation.
+
+### redocly (Optional)
+Validation backend using Redocly CLI for comprehensive OpenAPI linting and validation. I/O-bound (spawns Node.js subprocess).
+
+Install: `pip install jentic-openapi-validator-redocly`
+
 ### spectral (Optional)
-Advanced validation backend using Spectral CLI with comprehensive rule checking.
+Advanced validation backend using Spectral CLI with comprehensive rule checking. I/O-bound (spawns Node.js subprocess).
 
 Install: `pip install jentic-openapi-validator-spectral`

{jentic_openapi_validator-1.0.0a27 → jentic_openapi_validator-1.0.0a28}/README.md

@@ -6,6 +6,7 @@ A Python library for validating OpenAPI documents using pluggable validator back
 
 - **Pluggable Backend Architecture**: Support for multiple validation strategies via entry points
 - **Multiple Input Formats**: Validate OpenAPI documents from file URIs, JSON/YAML strings, or Python dictionaries
+- **Parallel Execution**: Run multiple backends concurrently using `ProcessPoolExecutor` for improved performance
 - **Aggregated Results**: Collect diagnostics from all configured backends into a single result
 - **Type Safety**: Full type hints with comprehensive docstrings
 - **Extensible Design**: Easy integration of third-party validator backends
@@ -27,6 +28,12 @@ For advanced validation with Spectral:
 pip install jentic-openapi-validator-spectral
 ```
 
+For validation with Redocly:
+
+```bash
+pip install jentic-openapi-validator-redocly
+```
+
 ## Quick Start
 
 ### Basic Validation
@@ -112,6 +119,26 @@ parser = OpenAPIParser()
 validator = OpenAPIValidator(parser=parser)
 ```
 
+### Parallel Execution
+
+When using multiple backends, you can run them in parallel for improved performance:
+
+```python
+# Run backends in parallel using ProcessPoolExecutor
+validator = OpenAPIValidator(backends=["default", "openapi-spec", "spectral"])
+result = validator.validate(document, parallel=True)
+
+# Limit the number of worker processes
+result = validator.validate(document, parallel=True, max_workers=2)
+```
+
+Parallel execution uses `asyncio` with `ProcessPoolExecutor` via `run_in_executor()`, enabling true parallelism that bypasses Python's GIL. This is particularly beneficial when using multiple backends, especially I/O-bound backends like Spectral and Redocly that spawn subprocesses.
+
+**Notes:**
+- `parallel=False` by default (opt-in)
+- With a single backend, `parallel=True` has no effect (runs sequentially)
+- Diagnostics from all backends are aggregated regardless of execution mode
+
 ## Working with ValidationResult
 
 The `ValidationResult` class provides convenient methods for working with validation diagnostics:
@@ -155,24 +182,28 @@ The package includes integration tests for backend discovery and validation. Tes
 class OpenAPIValidator:
     def __init__(
         self,
-        backends: list[str | BaseValidatorBackend | Type[BaseValidatorBackend]] | None = None,
+        backends: Sequence[str | BaseValidatorBackend | Type[BaseValidatorBackend]] | None = None,
         parser: OpenAPIParser | None = None,
     ) -> None
 ```
 
 **Parameters:**
-- `backends`: List of validator backends to use. Each item can be:
-  - `str`: Name of a backend registered via entry points (e.g., "openapi-spec", "spectral")
+- `backends`: Sequence of validator backends to use. Each item can be:
+  - `str`: Name of a backend registered via entry points (e.g., "default", "openapi-spec", "redocly", "spectral")
   - `BaseValidatorBackend`: Instance of a validator backend
   - `Type[BaseValidatorBackend]`: Class of a validator backend (will be instantiated)
-  - Defaults to `["openapi-spec"]` if `None`
+  - Defaults to `["default"]` if `None`
 - `parser`: Custom OpenAPIParser instance (optional)
 
 **Methods:**
 
-- `validate(document: str | dict) -> ValidationResult`
+- `validate(document: str | dict, *, base_url: str | None = None, target: str | None = None, parallel: bool = False, max_workers: int | None = None) -> ValidationResult`
   - Validates an OpenAPI document using all configured backends
   - `document`: File URI, JSON/YAML string, or dictionary
+  - `base_url`: Optional base URL for resolving relative references
+  - `target`: Optional target identifier for validation context
+  - `parallel`: If `True` and multiple backends are configured, run validation in parallel using `ProcessPoolExecutor`. Defaults to `False`.
+  - `max_workers`: Maximum number of worker processes for parallel execution. If `None`, defaults to the number of processors on the machine. Only used when `parallel=True`.
   - Returns: `ValidationResult` with aggregated diagnostics
 
 ### ValidationResult
@@ -198,7 +229,15 @@ class ValidationResult:
 ### default
 Basic validation backend that checks for required OpenAPI fields and structure. Suitable for basic document validation.
 
+### openapi-spec
+Validation backend using the `openapi-spec-validator` library for JSON Schema-based validation of OpenAPI documents. CPU-bound validation.
+
+### redocly (Optional)
+Validation backend using Redocly CLI for comprehensive OpenAPI linting and validation. I/O-bound (spawns Node.js subprocess).
+
+Install: `pip install jentic-openapi-validator-redocly`
+
 ### spectral (Optional)
-Advanced validation backend using Spectral CLI with comprehensive rule checking.
+Advanced validation backend using Spectral CLI with comprehensive rule checking. I/O-bound (spawns Node.js subprocess).
 
 Install: `pip install jentic-openapi-validator-spectral`

{jentic_openapi_validator-1.0.0a27 → jentic_openapi_validator-1.0.0a28}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jentic-openapi-validator"
-version = "1.0.0-alpha.27"
+version = "1.0.0-alpha.28"
 description = "Jentic OpenAPI Validator"
 readme = "README.md"
 authors = [{ name = "Jentic", email = "hello@jentic.com" }]
@@ -8,14 +8,14 @@ license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 requires-python = ">=3.11"
 dependencies = [
-  "jentic-openapi-parser~=1.0.0-alpha.27",
+  "jentic-openapi-parser~=1.0.0-alpha.28",
   "openapi-spec-validator~=0.7.2",
   "lsprotocol~=2025.0.0"
 ]
 
 [project.optional-dependencies]
-spectral = ["jentic-openapi-validator-spectral~=1.0.0-alpha.27"]
-redocly = ["jentic-openapi-validator-redocly~=1.0.0-alpha.27"]
+spectral = ["jentic-openapi-validator-spectral~=1.0.0-alpha.28"]
+redocly = ["jentic-openapi-validator-redocly~=1.0.0-alpha.28"]
 
 [project.urls]
 Homepage = "https://github.com/jentic/jentic-openapi-tools"

{jentic_openapi_validator-1.0.0a27 → jentic_openapi_validator-1.0.0a28}/src/jentic/apitools/openapi/validator/core/openapi_validator.py

@@ -1,6 +1,9 @@
+import asyncio
 import importlib.metadata
 import json
 import warnings
+from collections.abc import Sequence
+from concurrent.futures import ProcessPoolExecutor
 from typing import Type
 
 from jentic.apitools.openapi.parser.core import OpenAPIParser
@@ -40,7 +43,7 @@ class OpenAPIValidator:
 
     def __init__(
         self,
-        backends: list[str | BaseValidatorBackend | Type[BaseValidatorBackend]] | None = None,
+        backends: Sequence[str | BaseValidatorBackend | Type[BaseValidatorBackend]] | None = None,
         parser: OpenAPIParser | None = None,
     ):
         """
@@ -78,7 +81,13 @@ class OpenAPIValidator:
                 raise TypeError("Invalid backend type: must be name or backend class/instance")
 
     def validate(
-        self, document: str | dict, *, base_url: str | None = None, target: str | None = None
+        self,
+        document: str | dict,
+        *,
+        base_url: str | None = None,
+        target: str | None = None,
+        parallel: bool = False,
+        max_workers: int | None = None,
     ) -> ValidationResult:
         """
         Validate an OpenAPI document using all configured backends.
@@ -94,6 +103,11 @@ class OpenAPIValidator:
                 - Python dictionary
             base_url: Optional base URL for resolving relative references in the document
             target: Optional target identifier for validation context
+            parallel: If True and multiple backends are configured, run validation
+                in parallel using ProcessPoolExecutor. Defaults to False.
+            max_workers: Maximum number of worker processes for parallel execution.
+                If None, defaults to the number of processors on the machine.
+                Only used when parallel=True.
 
         Returns:
             ValidationResult containing aggregated diagnostics from all backends.
@@ -103,7 +117,6 @@ class OpenAPIValidator:
             TypeError: If document is not a str or dict
         """
 
-        diagnostics: list[JenticDiagnostic] = []
         document_is_uri: bool = False
         document_text: str = ""
         document_dict: dict | None = None
@@ -135,21 +148,35 @@ class OpenAPIValidator:
             )
 
         # Run validation through all backends
-        for backend in self.backends:
-            accepted = backend.accepts()
-            backend_document = None
-
-            # Determine which format to pass to this backend
-            if document_is_uri and "uri" in accepted:
-                backend_document = document
-            elif "dict" in accepted and document_dict is not None:
-                backend_document = document_dict
-            elif "text" in accepted:
-                backend_document = document_text
-
-            if backend_document is not None:
-                result = backend.validate(backend_document, base_url=base_url, target=target)
-                diagnostics.extend(result.diagnostics)
+        if parallel and len(self.backends) > 1:
+            # Parallel execution using asyncio with ProcessPoolExecutor
+            diagnostics = asyncio.run(
+                _validate_parallel(
+                    self.backends,
+                    document,
+                    document_dict,
+                    document_text,
+                    document_is_uri,
+                    base_url,
+                    target,
+                    max_workers,
+                )
+            )
+        else:
+            # Sequential execution (default)
+            diagnostics: list[JenticDiagnostic] = []
+            for backend in self.backends:
+                diagnostics.extend(
+                    _validate_single_backend(
+                        backend,
+                        document,
+                        document_dict,
+                        document_text,
+                        document_is_uri,
+                        base_url,
+                        target,
+                    )
+                )
 
         return ValidationResult(diagnostics=diagnostics)
 
@@ -189,3 +216,101 @@ class OpenAPIValidator:
             ['default', 'spectral']
         """
         return list(_VALIDATOR_BACKENDS.keys())
+
+
+def _validate_single_backend(
+    backend: BaseValidatorBackend,
+    document: str | dict,
+    document_dict: dict | None,
+    document_text: str,
+    document_is_uri: bool,
+    base_url: str | None,
+    target: str | None,
+) -> list[JenticDiagnostic]:
+    """
+    Validate document with a single backend.
+
+    This is a module-level function (not a method) to ensure it's picklable
+    for use with ProcessPoolExecutor.
+
+    Args:
+        backend: The validator backend to use
+        document: The original document (URI or text)
+        document_dict: Parsed document as dict (if available)
+        document_text: Document as text string
+        document_is_uri: Whether document is a URI
+        base_url: Optional base URL for resolving references
+        target: Optional target identifier
+
+    Returns:
+        List of diagnostics from the backend
+    """
+    accepted = backend.accepts()
+    backend_document: str | dict | None = None
+
+    if document_is_uri and "uri" in accepted:
+        backend_document = document
+    elif "dict" in accepted and document_dict is not None:
+        backend_document = document_dict
+    elif "text" in accepted:
+        backend_document = document_text
+
+    if backend_document is not None:
+        result = backend.validate(backend_document, base_url=base_url, target=target)
+        return list(result.diagnostics)
+    return []
+
+
+async def _validate_parallel(
+    backends: Sequence[BaseValidatorBackend],
+    document: str | dict,
+    document_dict: dict | None,
+    document_text: str,
+    document_is_uri: bool,
+    base_url: str | None,
+    target: str | None,
+    max_workers: int | None,
+) -> list[JenticDiagnostic]:
+    """
+    Run validators in parallel using ProcessPoolExecutor.
+
+    This module-level async function uses asyncio's run_in_executor to dispatch
+    each backend validation to a separate process, enabling true parallelism
+    for CPU-bound validators.
+
+    Args:
+        backends: List of validator backends to run
+        document: The original document (URI or text)
+        document_dict: Parsed document as dict (if available)
+        document_text: Document as text string
+        document_is_uri: Whether document is a URI
+        base_url: Optional base URL for resolving references
+        target: Optional target identifier
+        max_workers: Maximum number of worker processes
+
+    Returns:
+        Aggregated list of diagnostics from all backends
+    """
+    loop = asyncio.get_running_loop()
+
+    with ProcessPoolExecutor(max_workers=max_workers) as executor:
+        tasks = [
+            loop.run_in_executor(
+                executor,
+                _validate_single_backend,
+                backend,
+                document,
+                document_dict,
+                document_text,
+                document_is_uri,
+                base_url,
+                target,
+            )
+            for backend in backends
+        ]
+        results = await asyncio.gather(*tasks)
+
+    diagnostics: list[JenticDiagnostic] = []
+    for result in results:
+        diagnostics.extend(result)
+    return diagnostics