feat(python): Create sdkgen

[danielvallance]

Go and JS generate a client package for each plugin from its spec, but Python had no such tool, so a plugin had no Python client short of copying its generated plumbing into the SDK.

sdkgen renders unikraft-cloud-plugin--api from each spec. It takes a Transport shaped like ApiClient rather than the SDK, so the two depend one way, and publish refuses changed sources under an unchanged version.

[Copilot]

Copilot review overview

🟡 Changes recommended

Generated clients currently mishandle several valid OpenAPI inputs, and the documented SDK transport does not satisfy the generated contract.

Review effort: Balanced
Findings: 6 · 4 · 3

Open (13)

• Align generated transport calls with the SDK runtime API · New
• Classify named map schemas consistently as aliases · New
• Reject operations without tags instead of omitting them · New
• Serialize numeric and boolean path parameters before encoding · New
• Reject unsupported success response media types · New
• Reject unsupported required request-body media types · New
• Fail closed when wheel fingerprints are unavailable · New
• Merge inherited path-item headers into operations · New
• Preserve required query and header parameters in signatures · New
• Serialize typed header values before insertion · New
• Include typing_extensions in the dependency summary · New
• Document the typing_extensions runtime dependency · New
• Import os in the example · New

What changed in this PR

Adds Python sdkgen tooling to generate and publish standalone plugin API clients.

Changes:

• Adds Python model, resource, transport, metadata, and package templates.
• Adds build, validation, and PyPI publication tooling with source fingerprints.
• Documents generation and generated-package usage.

File	Description
python/​tools/​sdkgen/​templates/​transport.py.tmpl	Defines the transport protocols.
python/​tools/​sdkgen/​templates/​resources.tmpl	Generates resource clients.
python/​tools/​sdkgen/​templates/​README.md.tmpl	Generates package documentation.
python/​tools/​sdkgen/​templates/​pyproject.toml.tmpl	Defines generated package metadata.
python/​tools/​sdkgen/​templates/​models.py.tmpl	Generates Pydantic wire models.
python/​tools/​sdkgen/​templates/​meta.py.tmpl	Records versions and fingerprints.
python/​tools/​sdkgen/​templates/​__init__.py.tmpl	Exports and groups generated clients.
python/​tools/​sdkgen/​static/​LICENSE.md	Supplies generated package licensing.
python/​tools/​sdkgen/​README.md	Documents the generator workflow.
python/​tools/​sdkgen/​publish-check.sh	Validates published source fingerprints.
python/​tools/​sdkgen/​Makefile	Implements generation, build, checks, and publication.
python/​tools/​sdkgen/​.gitignore	Excludes generated build output.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Generated clients can omit operations or responses, produce invalid Python, and reach publishing without validation.

Review effort: Balanced
Findings: 10 · 3

Open (13)

• Publish bypasses wheel import and type checks · New
• Normalized tag names collide in generated APIs · New
• Python keyword tags generate invalid attributes · New
• Free-form property names are not escaped · New
• Only the first successful response is generated · New
• Schema-less JSON responses discard their body · New
• Operation IDs can collide or shadow transport · New
• Generated parameter names can collide · New
• Query parameter names are not escaped · New
• Classify named map schemas consistently as aliases
• Unpinned formatter causes nondeterministic publishing · New
• Imports omit operations with secondary tags · New
• Cookie parameters are silently omitted · New

Resolved since last review (12)

• Reject unsupported required request-body media types
• Reject unsupported success response media types
• Serialize numeric and boolean path parameters before encoding
• Reject operations without tags instead of omitting them
• Align generated transport calls with the SDK runtime API
• Serialize typed header values before insertion
• Preserve required query and header parameters in signatures
• Merge inherited path-item headers into operations
• Fail closed when wheel fingerprints are unavailable
• Import os in the example
• Document the typing_extensions runtime dependency
• Include typing_extensions in the dependency summary

[Copilot]

Copilot review overview

🟡 Changes recommended

Generated methods can mishandle valid request and response shapes, while the publication fingerprints do not fully guarantee identical sources.

Review effort: Balanced
Findings: 1 · 4 · 2

Open (7)

• Handle mixed content and no-content success responses · New
• Include Ruff version in generation fingerprints · New
• Preserve required bodies when no identifier properties are found · New
• Reserve all CallOptions keys from parameter names · New
• Unpinned formatter causes nondeterministic publishing
• Define the UUID in the documented example · New
• Define imports and UUID in the generated example · New

Resolved since last review (12)

• Query parameter names are not escaped
• Generated parameter names can collide
• Operation IDs can collide or shadow transport
• Schema-less JSON responses discard their body
• Only the first successful response is generated
• Free-form property names are not escaped
• Python keyword tags generate invalid attributes
• Normalized tag names collide in generated APIs
• Publish bypasses wheel import and type checks
• Classify named map schemas consistently as aliases
• Cookie parameters are silently omitted
• Imports omit operations with secondary tags

[Copilot]

Copilot review overview

🟡 Changes recommended

Model generation and artifact fingerprinting contain correctness and reproducibility gaps.

Review effort: Balanced
Findings: 1 · 3

Open (4)

• Validate schemas combining properties with unions · New
• Make formatter failures fatal · New
• Include Ruff version in generation fingerprints
• Unpinned formatter causes nondeterministic publishing

Resolved since last review (5)

• Handle mixed content and no-content success responses
• Reserve all CallOptions keys from parameter names
• Preserve required bodies when no identifier properties are found
• Define imports and UUID in the generated example
• Define the UUID in the documented example

[Copilot]

Copilot review overview

🟡 Changes recommended

Valid schema names and alias dependencies can currently produce unusable generated packages.

Review effort: Balanced
Findings: 4

Open (4)

• Missing container class causes generated API class name collisions · New
• model_config property collides with generated Pydantic configuration · New
• Alphabetical alias ordering causes NameError for forward dependencies · New
• Allowing dunder operation IDs can overwrite the generated constructor · New

Resolved since last review (4)

• Validate schemas combining properties with unions
• Make formatter failures fatal
• Include Ruff version in generation fingerprints
• Unpinned formatter causes nondeterministic publishing

[Copilot]

Copilot review overview

🟡 Changes recommended

Valid OpenAPI inputs can currently be omitted or generate invalid Python models.

Review effort: Balanced
Findings: 2 · 2

Open (4)

• Schema-less query parameters cause a template nil-pointer failure · New
• HEAD operations are omitted by the pinned openapi-gen version · New
• Leading-underscore properties are incorrectly treated as private fields · New
• Nested date-time schemas are incorrectly typed as strings · New

Resolved since last review (4)

• Allowing dunder operation IDs can overwrite the generated constructor
• Alphabetical alias ordering causes NameError for forward dependencies
• model_config property collides with generated Pydantic configuration
• Missing container class causes generated API class name collisions

[Copilot]

Copilot review overview

🟡 Changes recommended

Generated clients omit some HTTP methods and accept schema shapes that violate emitted model and transport contracts.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Handle all model_ field names with safe attributes and aliases · New
• Support non-class response schemas in decoder contracts · New
• Reject or serialize non-scalar query parameter shapes · New

Resolved since last review (4)

• HEAD operations are omitted by the pinned openapi-gen version
• Schema-less query parameters cause a template nil-pointer failure
• Nested date-time schemas are incorrectly typed as strings
• Leading-underscore properties are incorrectly treated as private fields

[Copilot]

Copilot review overview

🔵 Needs a closer look

The configured generator silently omits HEAD operations that the templates explicitly support.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Escape OpenAPI tags before embedding them in Python docstrings
• Generate typed mappings for schemas without an explicit type

[Copilot]

Copilot review overview

🟡 Changes recommended

Inline enum imports and type-less map schemas currently produce incorrect generated typing.

Review effort: Balanced
Findings: 1

Open (1)

• Import Literal for inline enum type annotations · New

[Copilot]

Copilot review overview

🟡 Changes recommended

Nullable parameters can generate unserializable calls, and nullable response annotations conflict with the transport protocol.

Review effort: Balanced
Findings: 2

Open (2)

• Reject nullable query parameters without null representation · New
• Reject nullable success schemas or widen transport typing · New

Resolved since last review (1)

• Import Literal for inline enum type annotations

[Copilot]

Copilot review overview

🟡 Changes recommended

Fingerprinting can miss tree moves, and interrupted PyPI publication cannot be retried safely.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Partial publishes can permanently skip missing artifacts · New
• Tree hashes omit source prefixes, missing cross-tree moves · New

Resolved since last review (2)

• Reject nullable success schemas or widen transport typing
• Reject nullable query parameters without null representation

[Copilot]

Copilot review overview

🟡 Changes recommended

OpenAPI version values can currently inject shell commands during Make expansion.

Review effort: Balanced
Findings: 1

Open (1)

• Validate OpenAPI version before shell interpolation to prevent command injection · New

Resolved since last review (2)

• Partial publishes can permanently skip missing artifacts
• Tree hashes omit source prefixes, missing cross-tree moves

[Copilot]

Copilot review overview

🔵 Needs a closer look

The large generator and publishing pipeline depends on an external SDK transport change and lacks repository-local integration fixtures for final validation.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Validate OpenAPI version before shell interpolation to prevent command injection

[aabedraba]

Read the documented parts on this PR. Seems very well tested against the final SDK layer, and the flow is similar to the TS counterpart. 👍

I recommend using a skill to map the different parts of the SDK, so that it saves you time with the LLMs: https://github.com/unikraft-cloud/js-sdk/blob/prod-staging/.agents/skills/js-sdk-map/SKILL.md

Reviewed-by: Abdallah Abedraba abdallah@unikraft.com
Approved-by: Abdallah Abedraba abdallah@unikraft.com