openapi-generators / openapi-generators/openapi-python-client

Model import shadows HTTP `Client` import when a schema is named `Client`

Open
#1,423 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
2k
Forks
293
Avg merge
34m
Merged PRs (30d)
1

Description

Describe the bug

When an OpenAPI spec contains a schema named Client, the generated endpoint modules import both the HTTP Client class and the Client model class under the same name. The model import silently shadows the HTTP client import, making Client in type annotations refer to the wrong class.
endpoint_module.py.jinja unconditionally emits:

from ...client import AuthenticatedClient, Client

Then endpoint.relative_imports adds model imports. When a model is also named Client, the result is:

from ...client import AuthenticatedClient, Client   # HTTP client
from ...models.client import Client                  # model — shadows the line above

This causes Client in _parse_response and _build_response type annotations to resolve to the model instead of the HTTP client class.

OpenAPI Spec File

Minimal reproduction:

openapi: "3.0.3"
info:
  title: Minimal repro
  version: "1.0"
paths:
  /api/clients/{id}:
    patch:
      operationId: update_client
      tags:
        - client
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Client"
components:
  schemas:
    Client:
      type: object
      properties:
        name:
          type: string

In the generated api/client/update_client.py, line 6 imports Client from ...client and line 10 re-imports Client from ...models.client, shadowing it.

Desktop (please complete the following information):

  • OS: macOS 15 (ARM64)
  • Python Version: 3.13
  • openapi-python-client version: 0.27.1 (also verified on 0.28.3)

Additional context

We worked around this by using custom templates.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with endpoint_module.py.jinja and the logic behind endpoint.relative_imports, then generate the minimal OpenAPI specification from the issue. Check the generated api/client/update_client.py imports and the _parse_response and _build_response annotations. Done means a schema named Client no longer causes the HTTP Client reference to be shadowed.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.