This release is a pre-release and may not be stable for production use.
jentic-openapi-transformer-redocly
A Python library that provides OpenAPI document bundling functionality using Redocly CLI. This package is part of the Jentic OpenAPI Tools ecosystem and implements the transformer backend pattern for bundling OpenAPI documents by resolving external references.
Features
- Multiple Input Formats: Support for file paths, URIs, and Python dictionaries
- External Reference Resolution: Automatically resolves
$refreferences across multiple files - Robust Error Handling: Comprehensive error reporting with detailed messages
- Timeout Configuration: Configurable timeout for long-running bundling operations
- Type Safety: Full type hints and comprehensive documentation
Installation
pip install jentic-openapi-transformer-redocly
Prerequisites:
- Node.js and npm (for Redocly CLI)
- Python 3.11+
The Redocly CLI will be automatically downloaded via npx on first use, or you can install it globally:
npm install -g @redocly/cli@2.31.2
Quick Start
Basic Usage
from jentic.apitools.openapi.transformer.bundler.backends.redocly import RedoclyBundlerBackend
# Create a bundler instance
bundler = RedoclyBundlerBackend()
# Bundle an OpenAPI document from a file path
result = bundler.bundle("/path/to/your/openapi.yaml")
print(result) # Bundled OpenAPI document as JSON string
Using with Dictionary Input
# Bundle an OpenAPI document from a Python dictionary
openapi_dict = {
"openapi": "3.0.3",
"info": {"title": "My API", "version": "1.0.0"},
"paths": {
"/users": {
"get": {
"responses": {"200": {"description": "Success"}}
}
}
}
}
result = bundler.bundle(openapi_dict)
parsed_result = json.loads(result)
Custom Configuration
# Custom Redocly CLI path and timeout
bundler = RedoclyBundlerBackend(
redocly_path="redocly", # Use global redocly installation
timeout=60.0 # 60 second timeout
)
result = bundler.bundle("https://petstore3.swagger.io/api/v3/openapi.json")
Advanced Usage
Error Handling
The bundler provides detailed error reporting for various failure scenarios:
from jentic.apitools.openapi.transformer.bundler.backends.redocly import RedoclyBundlerBackend
from jentic.apitools.openapi.common.subproc import SubprocessExecutionError
bundler = RedoclyBundlerBackend()
try:
result = bundler.bundle("/path/to/openapi.yaml")
except TypeError as e:
print(f"Unsupported document type: {e}")
except SubprocessExecutionError as e:
print(f"Redocly CLI execution failed: {e}")
except RuntimeError as e:
print(f"Bundling failed: {e}")
Supported Input Formats
The bundler accepts the following input formats (returned by accepts() method):
"uri": File paths or URIs pointing to OpenAPI documents"dict": Python dictionaries containing OpenAPI document data
Testing
Integration Tests
The integration tests require Redocly CLI to be available. They will be automatically skipped if Redocly is not installed.
Run the integration test:
uv run --package jentic-openapi-transformer-redocly pytest packages/jentic-openapi-transformer-redocly -v
API Reference
RedoclyBundler
class RedoclyBundlerBackend(BaseBundlerBackend):
def __init__(
self,
redocly_path: str = "npx --yes @redocly/cli@2.31.2",
timeout: float = 600.0,
allowed_base_dir: str | Path | None = None,
) -> None
Parameters:
redocly_path: Path to Redocly CLI executabletimeout: Maximum execution time in secondsallowed_base_dir: Optional base directory for path security validation. When set, all document paths are validated to be within this directory, providing defense against path traversal attacks. WhenNone(default), only file extension validation is performed (no base directory containment check). Recommended for web services or untrusted input (optional)
Methods:
accepts() -> list[str]: Returns supported document format identifiersbundle(document: str | dict, base_url: str | None = None) -> str: Bundles an OpenAPI document
Exceptions:
TypeError: Document type is not supportedRuntimeError: Redocly execution fails or produces invalid outputSubprocessExecutionError: Redocly times out or fails to startPathTraversalError: Document path attempts to escape allowed_base_dir (only whenallowed_base_diris set)InvalidExtensionError: Document path has disallowed file extension (always checked for filesystem paths)
1 maintainer
Metadata
1 maintainer
Release files for jentic-openapi-transformer-redocly 1.0.0a57
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| jentic_openapi_transformer_redocly-1.0.0a57.tar.gz | 8.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| jentic_openapi_transformer_redocly-1.0.0a57-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 20.6 kB
Release files / jentic_openapi_transformer_redocly-1.0.0a57.tar.gz
| Download URL | jentic_openapi_transformer_redocly-1.0.0a57.tar.gz |
|---|---|
| Size | 8.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
42cc0c5606bd04707c3aa7e7f473a9dd4d08086839e3f350c8023507886b87a0
|
|
BLAKE2b-256 checksum How to use checksums |
0eb67b2f7905311667f7dfbf99c3709256644ec9fb696502a794818920b7a8f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 10, 2026.
Transparency logRelease files / jentic_openapi_transformer_redocly-1.0.0a57-py3-none-any.whl
| Download URL | jentic_openapi_transformer_redocly-1.0.0a57-py3-none-any.whl |
|---|---|
| Size | 12.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36bdc7ce643bd66e110bcf21fff7bec7460f0e862c19ee172ca88a5dcf921aff
|
|
BLAKE2b-256 checksum How to use checksums |
3f5938591fd5e0dc11ab7bcda6363912dc5eb8ef04375bdd06ea9a323412868d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 10, 2026.
Transparency log
