[BUG] Generated python clients do not pass pyright typecheck

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator (example)?
• Have you tested with the latest master to confirm the issue still exists?
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?
• [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

pyright is a Python typechecker that shares a backend with the Pylance language server in VSCode. It is an alternative to mypy and catches some type errors that mypy does not. The Python client generation code involved mypy in a test already, but there is no test that uses pyright.

The generated clients for python do not pass pyright typechecks in the API client code. The samples checked into the repository demonstrate these type errors and I have observed them in clients generated for my own specifications.

$ pyright --version
pyright 1.1.382

$ pyright .
/Users/jason.prado/src/openapi-generator/samples/client/echo_api/python/openapi_client/api/auth_api.py
  /Users/jason.prado/src/openapi-generator/samples/client/echo_api/python/openapi_client/api/auth_api.py:97:16 - error: Type "str | Unknown | None" is not assignable to return type "str"
    Type "str | Unknown | None" is not assignable to type "str"
      "None" is not assignable to "str" (reportReturnType)
  /Users/jason.prado/src/openapi-generator/samples/client/echo_api/python/openapi_client/api/auth_api.py:160:16 - error: Type "ApiResponse[str | None] | Unknown" is not assignable to return type "ApiResponse[str]"
    Type "ApiResponse[str | None] | Unknown" is not assignable to type "ApiResponse[str]"
      "ApiResponse[str | None]" is not assignable to "ApiResponse[str]"
        Type parameter "T@ApiResponse" is invariant, but "str | None" is not the same as "str" (reportReturnType)
  /Users/jason.prado/src/openapi-generator/samples/client/echo_api/python/openapi_client/api/auth_api.py:343:16 - error: Type "str | Unknown | None" is not assignable to return type "str"
    Type "str | Unknown | None" is not assignable to type "str"
      "None" is not assignable to "str" (reportReturnType)
  /Users/jason.prado/src/openapi-generator/samples/client/echo_api/python/openapi_client/api/auth_api.py:406:16 - error: Type "ApiResponse[str | None] | Unknown" is not assignable to return type "ApiResponse[str]"
    Type "ApiResponse[str | None] | Unknown" is not assignable to type "ApiResponse[str]"
      "ApiResponse[str | None]" is not assignable to "ApiResponse[str]"
        Type parameter "T@ApiResponse" is invariant, but "str | None" is not the same as "str" (reportReturnType)

There are several other errors of a similar nature.

openapi-generator version

Main commit 423ba6739a2c5f5663d26f192907189b136e60ef from Dec 3 2024.

Steps to reproduce

$ gh repo clone OpenAPITools/openapi-generator
$ cd openapi-generator/samples/client/echo_api/python/openapi_client/api
$ nix-shell -p pyright  # or install pyright via pip, brew, etc.
$ pyright .

Suggest a fix

Add pyright alongside mypy in the Python tests after resolving the issue.

Start by running pyright on samples/client/echo_api/python/openapi_client/api as described, then inspect the generated Python client code producing the reported errors. Review .github/workflows/samples-python-client-echo-api.yaml for the existing mypy test. Done means the generated samples pass pyright and the workflow checks it alongside mypy.