This release is a pre-release and may not be stable for production use.
jentic-openapi-transformer
A Python library for transforming and bundling OpenAPI documents. This package is part of the Jentic OpenAPI Tools ecosystem and provides a flexible, extensible architecture for OpenAPI document transformation with support for pluggable backends.
Features
- Pluggable Backend Architecture: Support for multiple bundling strategies via entry points
- Multiple Input Formats: Accept OpenAPI documents as file paths, URIs, or Python dictionaries
- Flexible Output Types: Return bundled documents as JSON strings or Python dictionaries
- Type Safety: Full type hints with overloaded methods for precise return types
- Extensible Design: Easy integration of third-party bundling backends
Installation
pip install jentic-openapi-transformer
Prerequisites:
- Python 3.11+
Optional Backends:
For advanced bundling with external reference resolution:
pip install jentic-openapi-transformer-redocly
Quick Start
Basic Bundling
from jentic.apitools.openapi.transformer.bundler.core import OpenAPIBundler
# Create a bundler with the default backend
bundler = OpenAPIBundler()
# Bundle from a file URI and return as dictionary
result = bundler.bundle("file:///path/to/openapi.yaml", return_type=dict)
print(result["info"]["title"])
# Bundle from a file URI and return as JSON string
json_result = bundler.bundle("file:///path/to/openapi.yaml", return_type=str)
print(json_result)
Bundle from Dictionary
# Bundle an OpenAPI document from a Python dictionary
openapi_doc = {
"openapi": "3.1.0",
"info": {"title": "My API", "version": "1.0.0"},
"paths": {
"/users": {
"get": {
"summary": "Get users",
"responses": {"200": {"description": "Success"}}
}
}
}
}
result = bundler.bundle(openapi_doc, return_type=dict)
Using Different Backends
# Use the default backend (no external reference resolution)
bundler = OpenAPIBundler("default")
result = bundler.bundle("/path/to/openapi.yaml", return_type=dict)
# Use the Redocly backend (requires jentic-openapi-transformer-redocly)
bundler = OpenAPIBundler("redocly")
result = bundler.bundle("/path/to/openapi.yaml", return_type=dict)
Configuration Options
Backend Selection
# Use default backend by name
bundler = OpenAPIBundler("default")
# Pass a backend instance directly
from jentic.apitools.openapi.transformer.bundler.backends.default import DefaultBundlerBackend
backend = DefaultBundlerBackend()
bundler = OpenAPIBundler(backend=backend)
# Pass a backend class
bundler = OpenAPIBundler(backend=DefaultBundlerBackend)
Custom Parser
from jentic.apitools.openapi.parser.core import OpenAPIParser
# Use a custom parser instance
parser = OpenAPIParser()
bundler = OpenAPIBundler(parser=parser)
Return Type Control
# Return as dictionary (typed)
dict_result: dict = bundler.bundle(document, return_type=dict)
# Return as JSON string (typed)
str_result: str = bundler.bundle(document, return_type=str)
# Return as plain (auto-detected type)
plain_result = bundler.bundle(document)
Strict Mode
# Enable strict type checking for return type
try:
result = bundler.bundle(document, return_type=dict, strict=True)
except TypeError as e:
print(f"Type mismatch: {e}")
Testing
Run the test suite:
uv run --package jentic-openapi-transformer pytest packages/jentic-openapi-transformer -v
Integration Tests
The package includes integration tests for backend discovery and bundling. Tests requiring external backends (like Redocly) will be automatically skipped if the backend package is not installed.
API Reference
OpenAPIBundler
class OpenAPIBundler:
def __init__(
self,
backend: str | BaseBundlerBackend | Type[BaseBundlerBackend] | None = None,
parser: OpenAPIParser | None = None,
) -> None
Parameters:
backend: Backend name, instance, or class. Defaults to "default"parser: Custom OpenAPIParser instance (optional)
Methods:
bundle(document: str | dict, base_url: str | None = None, *, return_type: type[T] | None = None, strict: bool = False) -> T- Bundles an OpenAPI document with specified return type
document: File path, URI, JSON/YAML string, or dictionarybase_url: Optional base URL for resolving relative referencesreturn_type: Desired output type (str, dict, or None for auto)strict: Enable strict return type validation
Available Backends
base
Abstract base class for custom bundler backends. Not for direct use.
default
Basic bundling backend without external reference resolution. Suitable for single-file OpenAPI documents.
redocly (Optional)
Advanced bundling backend using Redocly CLI with full reference resolution across multiple files.
Install: pip install jentic-openapi-transformer-redocly
1 maintainer
Metadata
1 maintainer
Release files for jentic-openapi-transformer 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-1.0.0a57.tar.gz | 12.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| jentic_openapi_transformer-1.0.0a57-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 29.6 kB
Release files / jentic_openapi_transformer-1.0.0a57.tar.gz
| Download URL | jentic_openapi_transformer-1.0.0a57.tar.gz |
|---|---|
| Size | 12.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1daa8d20ee94986f7f570122c439e82967e32c8d1f3b6888314a690b374eb570
|
|
BLAKE2b-256 checksum How to use checksums |
9596d543f1589e4dae2865ff939ffc3763f672455a7c0061fc652c2eba14e54e
|
| 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-1.0.0a57-py3-none-any.whl
| Download URL | jentic_openapi_transformer-1.0.0a57-py3-none-any.whl |
|---|---|
| Size | 17.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
42d3b2802d9dd33d7ab018ba5431dac05eb168c6c7a403faae328b9d47eff67b
|
|
BLAKE2b-256 checksum How to use checksums |
6d4847c94decf092de9e5b88ced9f97d371217a8defaf468acc596a8b00705a4
|
| 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
