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

Phase 1: Investigation

• Evaluate the most promising alternatives (at minimum TypeSpec, openapi-python-client, and Kiota) against the DiracX codebase:
  • Generate a client from the current DiracX OpenAPI spec with each tool. For TypeSpec specifically, test whether the openapi3-to-typespec converter produces clean, repeatable output from the DiracX OpenAPI spec without manual fixups.
  • Assess the quality of the generated code (type safety, async support, error handling).
  • Assess compatibility with the extension system (layered _patch.py patching, custom importer).
  • Identify the full scope of changes needed in _patch.py files, _client_importer.py, diracx-api, and diracx-cli.
  • Evaluate impact on downstream consumers / extensions.
• Document findings and make a recommendation.

Phase 2: Migration

• Replace the client generation pipeline in diracx-testing/src/diracx/testing/client_generation.py.
• Regenerate the client under diracx-client/src/diracx/client/_generated/.
• Update or rewrite _patch.py files to work with the new generated client.
• Update or replace the custom importer (diracx-client/src/diracx/_client_importer.py) if needed.
• Update diracx-api and diracx-cli for any client API surface changes.
• Update the gubbins extension example to use the new generation pipeline.
• Remove azure.core dependency (if the chosen tool does not require it).
• Update Renovate configuration (renovate.json) to track the new tool's dependencies.
• Update CI workflow (.github/workflows/main.yml, "Run autorest" step).
• Ensure all existing tests pass with the new client.

[aldbr]

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