Autorest is deprecated and will be retired on July 1, 2026

[aldbr]

Description

https://github.com/DIRACGrid/diracx/actions/runs/23001190117/job/66785848787?pr=826#step:5:320

⚠️ AutoRest is deprecated and will be retired on July 1, 2026. Please migrate to TypeSpec: https://typespec.io/ — details: https://github.com/Azure/autorest/issues/5175

DiracX uses AutoRest to auto-generate the Python client (diracx-client) from the FastAPI-generated OpenAPI spec. A replacement must be selected and migrated to, ideally before the retirement date.

Current Situation

• The client generation pipeline is defined in diracx-testing/src/diracx/testing/client_generation.py and invoked via pixi run -e diracx-generate-client generate-client.
• The generated code lives in diracx-client/src/diracx/client/_generated/ (and similarly for the gubbins extension example).
• The generated client depends on azure.core for HTTP transport, pipeline policies, serialization, and error handling, despite DiracX not being an Azure service.
• Customizations are applied via _patch.py files and the custom importer in diracx-client/src/diracx/_client_importer.py, which supports layered patching for extensions.
• Renovate is configured to track AutoRest and @autorest/* plugin versions (renovate.json).

Open Source Alternatives

TypeSpec (Microsoft)

• License: MIT
• Approach: API-first IDL — you define your API in TypeSpec, then emit OpenAPI specs and client SDKs.
• Python support: Preview (@typespec/http-client-python v0.17.0). Has its own Python client emitter that generates Azure SDK-style clients (same pattern as AutoRest), which would minimize migration effort for _patch.py files and call sites.
• Fit for DiracX: Uncertain — needs investigation. TypeSpec is designed as the source of truth for API definitions, which conflicts with DiracX's FastAPI-first workflow. However, TypeSpec provides an openapi3-to-typespec converter that could potentially be used as a repeatable pipeline step: FastAPI → OpenAPI → TypeSpec → Python client. This converter is intended as a one-time migration tool, so it may lose information, require manual fixups, or produce non-deterministic output when run repeatedly against evolving specs. Whether this is viable needs to be tested against the actual DiracX OpenAPI spec.
• Trade-offs: If the conversion pipeline works reliably, this could be the lowest-effort migration path since the generated client follows the same Azure SDK patterns as AutoRest. If it doesn't, the alternative is redefining the API in TypeSpec IDL and keeping it in sync with FastAPI routers manually — a significant maintenance burden.

openapi-python-client

• License: MIT
• Approach: Consumes OpenAPI 3.x specs directly and generates a typed Python client.
• Python support: Mature (v0.28.3). Generates modern Python using httpx for HTTP and attrs for models. Full async support via .sync() / .asyncio() patterns. No vendor-specific dependencies.
• Fit for DiracX: Strong. Directly fits the FastAPI → OpenAPI → client workflow. Removes the azure.core dependency. Written in Python with Jinja2 templates, making customization straightforward.
• Trade-offs: Different client API surface from AutoRest — all _patch.py files, the custom importer, and call sites would need to be reworked.

Kiota (Microsoft)

• License: MIT
• Approach: Consumes OpenAPI specs directly and generates clients in multiple languages.
• Python support: Active. Uses httpx under the hood but requires microsoft-kiota-abstractions, microsoft-kiota-http, and serialization packages at runtime.
• Fit for DiracX: Moderate. Fits the workflow (consumes OpenAPI), but trades the azure.core dependency for microsoft-kiota-* dependencies. Uses a fluent request builder pattern that differs significantly from the current client surface.
• Trade-offs: Still depends on Microsoft runtime libraries. More verbose generated code than openapi-python-client.

OpenAPI Generator (Community)

• License: Apache 2.0
• Approach: Consumes OpenAPI 2.x/3.x specs. Largest ecosystem with generators for 50+ languages.
• Python support: Multiple generators available. Default Python output uses urllib3, code quality is considered less idiomatic than dedicated Python tools. Limited async support (open issue #18407).
• Fit for DiracX: Weak. The lack of native async support is a significant gap. Java-based toolchain makes Python-specific customization harder.

Definition of Done

• Evaluate the most promising alternatives (at minimum TypeSpec, openapi-python-client, and Kiota) against the DiracX codebase:
• Document findings and make a recommendation.
• Once we all agree on the replacing tool, migrate

[aldbr]

Note: we should be able to use openapi > 2 with the new solution

[chrisburr]

Another option we could consider is to have our own code generator. A lot of the complexity of the generic solutions for this come from supporting arbitrary OpenAPI specs and correctly generating models. With our own code generator we would only need to support our own OpenAPI file, models are already available on the client from diracx-core.

This would also avoid the need to do any patching of the client.