[python] restore legacy runtime compatibility

Merged
TA
3mo ago
+1272-31

The removed python-legacy generator exposed more than model
dictionaries. Kubernetes also depends on synchronous urllib3 operations
accepting async_req and _preload_content, returning a thread result or
raw response when requested, and returning (data, status, headers) from
with_http_info(). Its generic models exposed openapi_types and
attribute_map, legacy display/equality helpers, and unknown constructor
keyword rejection.

Extend the existing default-off compatibleWithPythonLegacy option rather
than reviving the removed generator. Each synchronous urllib3 operation
prepares its request once, then the current transport selects data, raw,
tuple, or thread output. Use the raw HTTPHeaderDict for tuple headers so
duplicate values remain visible.

Keep the ordinary data return annotation even when flags change the
runtime shape. Kubernetes Watch inspects that annotation to choose the
event model:
https://github.com/kubernetes-client/python/blob/6cc5456d79dd8c0ccc9e275a0811aeb025714bea/kubernetes/watch/watch.py#L36-L48

Restore the generic-model surface under the same option. Current
response deserialization still projects known wire fields before
Pydantic validation, so unknown server fields remain ignored.

Add a loopback endpoint to the existing compatibility sample and cover
normal, thread, raw, tuple, duplicate-header, unknown-response-field,
metadata, display, equality, and unknown-constructor behavior. Default
generation and async libraries remain unchanged.

Summary by cubic

Restores the legacy Python runtime behind the compatibleWithPythonLegacy option to bring back synchronous urllib3 call shapes and generic model metadata while keeping defaults unchanged. Operation compatibility applies only to the default urllib3; model compatibility applies to all libraries.

  • New Features

    • Sync urllib3 operations accept async_req and _preload_content, support integer/tuple _request_timeout, and return data, raw responses, or (data, status, headers) via with_http_info(); tuple headers preserve duplicates and non-2xx raw responses raise before returning.
    • async_req is reserved to avoid parameter collisions; only operation params named async_req are renamed (e.g., var_async_req), model field names stay unchanged.
    • Generic models expose openapi_types and attribute_map, use legacy to_str/__repr__/equality (including additional_properties), reject unknown constructor kwargs (extra="forbid"), and reject schema fields that collide with these metadata names.

  • Migration

    • Enable by setting compatibleWithPythonLegacy: true when generating with the default urllib3; other libraries are unchanged.
    • Optionally set pool_threads on ApiClient for legacy async_req calls. The modern _without_preload_content helper is omitted in this mode; use _preload_content=False instead.