Add enum, additionalProperties, validation, auth generation, and per-call config support

[phalt]

Change summary

This PR delivers the first two releases of the feature roadmap (committed as PLAN.md): three generator-robustness features, plus two headline features for authentication and multi-tenant use.

1. Non-string enum support: Integer, float, and mixed-type enums now generate correctly instead of crashing with AttributeError. Integer enums use enum.IntEnum, others use enum.Enum with synthesized VALUE_ member names. Negative numbers and decimals are sanitized appropriately, and colliding names are deduplicated with numeric suffixes.

2. Typed additionalProperties (map types): Object schemas with schema-valued additionalProperties now generate typed dictionaries (dict[str, ValueType]). Pure map schemas (no properties of their own) generate a new DictResponse base class that provides dict-like access while validating values. Free-form objects (additionalProperties: true or absent) retain the existing dict[str, typing.Any] behavior.

3. clientele validate CLI command: A new pre-flight validation command walks OpenAPI specs and reports errors (unresolvable $refs) and warnings (constructs that degrade, like cookie parameters, multipart bodies, or unsupported security schemes). Exits with status 1 on errors to gate CI, status 0 on warnings or clean specs.

4. Auth config generation from securitySchemes: The generator now reads components.securitySchemes and renders typed credential fields on the generated Config — bearer_token for HTTP bearer, basic_username/basic_password for HTTP basic, and api_key for header API keys. Credentials inject the right header when set (never overriding explicit headers), and environment variable / .env support comes free via pydantic-settings. Unsupported schemes (oauth2, openIdConnect, query/cookie API keys) get an explanatory comment in config.py plus warnings from generation and validate.

5. Per-call config overrides (closes OpenAPI client generator factory mode #233): Decorated functions and the direct request/arequest methods accept a reserved config keyword argument that overrides the client-wide configuration for a single call — base URL, headers, logger, and HTTP backend. The client-wide config is never mutated, so concurrent calls against different hosts (multi-tenant APIs, e.g. OCPI) are safe, and each override config lazily creates and caches its own HTTP backend/connection pool. Works in already-generated clients without regeneration.

Note: the branch has been merged with main's 2.3.0 restructure — the new test files live under the reorganized layout (tests/generators/, tests/api/) and the moved SchemasGenerator/request_context paths are used throughout.

Implementation details

• Enums: Modified generate_enum_properties() in clientele/generators/shared/schemas.py to accept a list of values instead of a dict, synthesize member names based on type, and emit the correct base class. Added _enum_member_name() and _enum_base_class() helpers.
• additionalProperties: Extended get_type() in clientele/generators/shared/utils.py to detect and type schema-valued additionalProperties (carried through cicerone_compat and 3.1 normalization). Added DictResponse base class in clientele/schemas.py with dict-like methods (__getitem__, keys(), items(), etc.). Pure map schemas emit DictResponse subclasses via the shared root-model template.
• Validation: New SpecValidator class in clientele/generators/validation.py walks the spec tree, checks $ref resolution, and reports unsupported constructs. Integrated into CLI via the new validate command, which also handles unparseable files gracefully.
• Auth generation: New clientele/generators/shared/security.py classifies security schemes (shared by generator and validator). config_py.jinja2 renders credential fields and a model_post_init that injects headers via setdefault. Basic-auth fields deliberately avoid username/password names so pydantic-settings' case-insensitive env matching cannot pick up the OS $USERNAME variable.
• Per-call config: A reserved config kwarg in _prepare_call, following the exact pattern of the existing reserved query/headers kwargs, carried on PreparedCall (clientele/api/request_context.py) and resolved in all four execution paths (sync, async, both streaming variants) plus direct requests. Functions that declare their own config parameter keep it as a normal argument.

Related issue(s)

• Closes OpenAPI client generator factory mode #233 (per-call config overrides / multi-tenant clients)
• Implements PLAN.md items 1–5 (Releases A and B)

Pull request tasks

The following have been completed for this task:

• Code changes
• Tests written (test-first for every feature)
  • tests/generators/test_enum_generation.py — all enum variants, pydantic round-trips, name collisions
  • tests/generators/test_additional_properties.py — map type generation, validation, response_map compatibility
  • tests/generators/test_validation.py — every finding type plus CLI exit codes
  • tests/generators/test_auth_generation.py — per-scheme generation, header injection, env vars, end-to-end via FakeHTTPBackend
  • tests/api/test_config_override.py — tenant routing, non-mutation, async, streaming, lazy backend caching, collision guard
• Documentation changes for new or changed features
  • docs/openapi-cli.md — validate command, generated enums and map types
  • docs/api-authentication.md — rewritten to lead with generated auth support
  • docs/api-configuration.md — new "Per-call configuration" section
• Pre-review preparation
  • make test — full suite passes (662 tests, post-merge with main's 2.3.0 restructure)
  • make format — code formatted
  • make ty — type checking passes
  • make generate-test-clients — test clients regenerated with new enum/map support
• Changelog updated (docs/CHANGELOG.md, folded into the 2.3.0 UNRELEASED section)
• Merged with main — conflicts from the 2.3.0 project restructure resolved

Code examples

Enum generation:

# Input: {"type": "integer", "enum": [1, 2, 3]}
class StatusCode(enum.IntEnum):
    VALUE_1 = 1
    VALUE_2 = 2
    VALUE_3 = 3

# Input: {"type": "string", "enum": ["red", "green"]}
class Colour(str, enum.Enum):
    RED = "red"
    GREEN = "green"

Map types:

# Property with typed map
class Report(pydantic.BaseModel):
    scores: typing.Optional[dict[str, int]] = None

# Pure map schema
class ScoreMap(DictResponse[int]):
    pass

scores = ScoreMap.model_validate({"alice": 3, "bob": 5})
scores["alice"]  # 3

Generated auth config:

# Input: {"bearerAuth": {"type": "http", "scheme": "bearer"}}
class Config(clientele_api.BaseConfig):
    base_url: str = "https://api.example.com"
    bearer_token: str = ""  # sends "Authorization: Bearer <token>" when set

Per-call config override:

party_a = BaseConfig(base_url="https://party-a.example.com", headers={"Authorization": "Bearer <token-a>"})
party_b = BaseConfig(base_url="https://party-b.example.com", headers={"Authorization": "Bearer <token-b>"})

user_a = get_user(user_id=1, config=party_a)
user_b = get_user(user_id=1, config=party_b)  # safe concurrently, no global mutation

https://claude.ai/code/session_012ZEd8QZGvbqKabxchwhGkE