Skip to content
Platform Status

CLI

Python configuration options

This section details the available configuration options for the Python SDK. All configuration is managed in the gen.yaml file under the python section.

Identity and metadata

Section titled “Identity and metadata”
python:
  version: 1.2.3
  templateVersion: v2
  packageName: "openapi"
  moduleName: "openapi"
  authors: ["Author Name"]
  description: "Python Client SDK Generated by Speakeasy."
  homepage: "https://example.com"
  documentationUrl: "https://example.com/docs"
  license: "Apache-2.0"
Name
version
Required
true
Description
The current version of the SDK.
Default Value
0.0.1
templateVersion
Required
false
Description
The template version to use. Format: v1, v2, etc.
Default Value
v2
packageName
Required
true
Description
The distribution name of the PyPI package. See Python Package Metadata.
Default Value
openapi
moduleName
Required
false
Description
The name of the module to import from. Allows using a different name for imports than the package name. For example, pip install {packageName} and in code from {moduleName} import SDK. PEP 420 implicit namespace packages are supported with period (.) characters — e.g. example_cloud.api_client generates the SDK in example_cloud/api_client/ with no __init__.py in the parent. Custom code regions will be removed by updating moduleName.
Default Value
Same as packageName
authors
Required
true
Description
Authors of the published package.
Default Value
["Speakeasy"]
description
Required
false
Description
A short description of the project.
Default Value
"Python Client SDK Generated by Speakeasy."
homepage
Required
false
Description
The URL for the homepage of the project.
Default Value
null
documentationUrl
Required
false
Description
The URL for the project documentation.
Default Value
null
license
Required
false
Description
The SPDX license identifier or license text for the project.
Default Value
Apache-2.0 (new) / empty (legacy)

Different package and module names

Section titled “Different package and module names”

Configure a different name for the PyPI package and the module to import from:

python:
  packageName: "my-package" # Install with: pip install my-package
  moduleName: "my_module" # Import with: from my_module import SDK

This can be useful when the package name follows PyPI conventions (using hyphens) but the module name follows Python conventions (using underscores).

Build and tooling

Section titled “Build and tooling”
python:
  packageManager: "uv"
  additionalDependencies:
    main:
      requests: "^2.25.1"
    dev:
      pytest: "^6.2.1"
  compileCommands:
    - ["uv", "lock"]
    - ["uv", "sync", "--dev"]
    - ["uv", "run", "python", "-m", "compileall", "-q", "."]
  pytestFilterWarnings:
    - error
    - "ignore::DeprecationWarning"
  pytestTimeout: 300
Name
packageManager
Required
false
Description
The package manager to use for dependency management and packaging. Options: uv (recommended) or poetry.
Default Value
uv (new) / poetry (legacy)
additionalDependencies
Required
false
Description
Specify additional dependencies to include in the generated pyproject.toml file.
Default Value
{main: {}, dev: {}}
optionalDependencies
Required
false
Description
Define optional dependency groups (PyPI extras) in the generated pyproject.toml file. Each key becomes an extra that installs the listed packages on demand.
Default Value
{}
compileCommands
Required
false
Description
A list of commands to use for compiling the SDK, replacing the default compile pipeline. Must be an array of arrays where each inner array has the command as the first element and the rest are arguments.
Default Value
N/A
pytestFilterWarnings
Required
false
Description
When the array contains any strings, sets the global pytest filterwarnings value (filters to control Python warnings, e.g. ignoring or raising as errors). See Python warning filters.
Default Value
[]
pytestTimeout
Required
false
Description
When greater than 0, installs pytest-timeout and sets the global timeout (in seconds) before individual tests are timed out.
Default Value
0

Default compilation pipeline

When compileCommands is not set, the default pipeline runs based on the package manager (uv or poetry) and includes bytecode compilation (compileall), linting (pylint -j=0), and type checking (mypy and pyright in parallel). To reduce pylint parallelism and avoid OOM errors in CI, use compileCommands with -j=1.

Optional dependencies

Section titled “Optional dependencies”

Use optionalDependencies to declare optional dependency groups, known as extras, in the generated pyproject.toml file. Extras let end users install packages that the SDK needs only for specific functionality, keeping the default installation lightweight.

Each top-level key under optionalDependencies is the name of an extra. Each extra holds a map of package names to PEP 508 version specifiers:

python:
  optionalDependencies:
    http2:
      h2: ">=4.0.0"
    cli:
      click: ">=8.1.0"
      rich: ">=13.0.0"

This configuration generates the following [project.optional-dependencies] table:

[project.optional-dependencies]
cli = [
    "click >=8.1.0",
    "rich >=13.0.0",
]
http2 = [
    "h2 >=4.0.0",
]

End users then install an extra by name:

Terminal window
pip install my-package[http2]

Extras and their packages are sorted alphabetically in the output. An extra with no packages renders as an empty list, such as http2 = []. Both the uv and poetry package managers support optionalDependencies.

Optional vs. additional dependencies

Use additionalDependencies for packages the SDK always needs, since they are installed with the base package. Use optionalDependencies for packages the SDK needs only for specific features, since they are installed only when an end user requests the matching extra.

API surface shape

Section titled “API surface shape”
python:
  maxMethodParams: 999
  flattenRequests: true
  flatteningOrder: "parameters-first"
  methodArguments: "infer-optional-args"
  flattenGlobalSecurity: true
  envVarPrefix: "SPEAKEASY"
  responseFormat: "flat"
  multipartArrayFormat: "standard"
  imports:
    option: "openapi"
    paths:
      callbacks: "models/callbacks"
      errors: "models/errors"
      operations: "models/operations"
      shared: "models/shared"
      webhooks: "models/webhooks"
Name
maxMethodParams
Required
false
Description
The maximum number of parameters a method can have before the resulting SDK endpoint is no longer "flattened" and an input object is generated instead. 0 means input objects are always used.
Default Value
999 (new) / 4 (legacy)
flattenRequests
Required
false
Description
Turn request parameters and body fields into a flat list of method arguments. Takes precedence over maxMethodParams. If there is no request body, maxMethodParams is respected.
Default Value
true (new SDKs)
flatteningOrder
Required
false
Description
When flattening parameters and body fields, determines the ordering of generated method arguments. Options: parameters-first or body-first.
Default Value
parameters-first
methodArguments
Required
false
Description
If infer-optional-args, when all parameters and the request body are optional, the argument to the function will be optional. Alternative: require-security-and-request.
Default Value
infer-optional-args
flattenGlobalSecurity
Required
false
Description
Flatten the global security configuration if there is only a single option in the spec.
Default Value
true
envVarPrefix
Required
false
Description
The environment variable prefix for security and global env variable overrides. If empty, these overrides will not be possible.
Default Value
""
responseFormat
Required
false
Description
Determines the shape of the response envelope returned from SDK methods. Options: envelope, envelope-http, or flat.
Default Value
flat
multipartArrayFormat
Required
false
Description
Format for array field names in multipart form data. legacy appends [] (e.g. files[]). standard uses the field name as-is.
Default Value
standard (new) / legacy
imports
Required
false
Description
Configuration for model import structure (paths for shared/operations/errors/callbacks/webhooks).
Default Value
{}

Import paths

Section titled “Import paths”
Component
callbacks
Default Value
models/callbacks
Description
The directory where callback models are imported from.
errors
Default Value
models/errors
Description
The directory where error models are imported from.
operations
Default Value
models/operations
Description
The directory where operation models (i.e., API endpoints) are imported from.
shared
Default Value
models/components
Description
The directory for shared components, such as reusable schemas and data models imported from the OpenAPI spec.
webhooks
Default Value
models/webhooks
Description
The directory for webhook models, if the SDK includes support for webhooks.

Async and SSE

Section titled “Async and SSE”
python:
  asyncMode: split
  useAsyncHooks: false
  sseFlatResponse: false
Name
asyncMode
Required
false
Description
Whether to generate sync and/or async methods. both generates one constructor with _async-suffixed methods. split generates FooSDK and AsyncFooSDK with no method-name suffixes.
Default Value
both
useAsyncHooks
Required
false
Description
Enable async hooks infrastructure for async SDK methods. SDK maintainers must explicitly register async hooks in asyncregistration.py. Adapters wrap sync hooks, but native async implementations are recommended.
Default Value
false
sseFlatResponse
Required
false
Description
Whether to flatten SSE (Server-Sent Events) responses by extracting the data field from wrapper models, providing direct access to event data instead of the wrapper object.
Default Value
false

The asyncMode setting provides two patterns for handling async operations:

Method-based (both, default): Every operation has two methods — a synchronous version and an asynchronous version with an _async suffix.

sdk = MyAPI(api_key="...")


# Synchronous operations
result = sdk.list_users()


# Asynchronous operations
result = await sdk.list_users_async()

Constructor-based (split): Separate constructors for synchronous and asynchronous clients. All method names are identical between sync and async versions.

# Synchronous client
sync_sdk = MyAPI(api_key="...")
result = sync_sdk.list_users()


# Asynchronous client
async_sdk = AsyncMyAPI(api_key="...")
result = await async_sdk.list_users()

The constructor-based pattern eliminates method name duplication and provides clearer IDE suggestions.

Breaking change

Switching to asyncMode: split is a breaking change. Existing SDK consumers will need to update their code to use the new constructor pattern.

Errors

Section titled “Errors”
python:
  clientServerStatusCodesAsErrors: true
  defaultErrorName: ""
  baseErrorName: "APIError"
Name
clientServerStatusCodesAsErrors
Required
false
Description
Whether to treat 4xx and 5xx status codes as errors.
Default Value
true
defaultErrorName
Required
false
Description
The name of the default exception raised when an API error occurs.
Default Value
empty (new) / SDKError (legacy)
baseErrorName
Required
false
Description
The name of the base error class used for HTTP error responses.
Default Value
null

Enums and unions

Section titled “Enums and unions”
python:
  enumFormat: "union"
  forwardCompatibleEnumsByDefault: true
  forwardCompatibleUnionsByDefault: "tagged-only"
  inferUnionDiscriminators: true
  preApplyUnionDiscriminators: true
Name
enumFormat
Required
false
Description
Determines the format to express enums in Python. Options: union or enum.
Default Value
union (new) / enum (legacy)
forwardCompatibleEnumsByDefault
Required
false
Description
When true, any enum used in a response is automatically open/forward-compatible — unknown values are tolerated. Single-value enums are not auto-opened. Individual enums can be controlled with x-speakeasy-unknown-values: allow/disallow.
Default Value
true (new SDKs)
forwardCompatibleUnionsByDefault
Required
false
Description
Controls forward compatibility for discriminated unions in responses. tagged-only makes discriminated unions open to unknown discriminator values. false disables. Individual unions can be controlled with x-speakeasy-unknown-values: allow/disallow.
Default Value
tagged-only (new) / false (legacy)
inferUnionDiscriminators
Required
false
Description
Infer union discriminators for oneOfs missing explicit OpenAPI discriminator mapping.
Default Value
true
preApplyUnionDiscriminators
Required
false
Description
When true, discriminator values are applied as const fields onto union member types when those types are consistently used with the same discriminator value. Simplifies type structure and enables Annotated[Union[...], Field(discriminator='...')] syntax.
Default Value
true (new SDKs)

Models and miscellaneous

Section titled “Models and miscellaneous”
python:
  inputModelSuffix: "input"
  outputModelSuffix: "output"
  constFieldCasing: "normal"
  allowedRedefinedBuiltins:
    - id
    - object
    - input
    - dir
  enableCustomCodeRegions: false
Name
inputModelSuffix
Required
false
Description
Suffix added to models with writeOnly fields that are generated as input models.
Default Value
input
outputModelSuffix
Required
false
Description
Suffix added to models with readOnly fields that are generated as output models.
Default Value
output
constFieldCasing
Required
false
Description
Casing convention for const fields in generated models. upper uses SCREAMING_SNAKE_CASE, normal uses snake_case.
Default Value
normal (new) / upper (legacy)
allowedRedefinedBuiltins
Required
false
Description
List of names allowed to shadow builtins via SDK method parameters.
Default Value
["id", "object", "input", "dir"] (new) / ["id", "object", "dir"] (legacy)
enableCustomCodeRegions
Required
false
Description
Allow custom code to be inserted into the generated SDK.
Default Value
false

Fixes

Section titled “Fixes”

Fixes to apply to the generated SDK. Generally true for new SDKs but may be false for backward compatibility with existing SDKs.

python:
  fixes:
    responseRequiredSep2024: true
    asyncPaginationSep2025: true
    conflictResistantModelImportsFeb2026: true
Name
responseRequiredSep2024
Required
false
Description
Enables fixes introduced in September 2024 for response required field handling. For existing SDKs, setting to true is recommended but may be a breaking change.
Default Value
true (new SDKs)
asyncPaginationSep2025
Required
false
Description
Disabling not recommended. Enables changes introduced in September 2025 to fix async pagination methods to return async next() functions instead of synchronous ones, preventing blocking fetches after the initial API call. For existing SDKs, setting to true is recommended but will be a breaking change.
Default Value
true (new SDKs)
conflictResistantModelImportsFeb2026
Required
false
Description
Enables conflict-resistant model imports introduced in February 2026. For existing SDKs, setting to true is recommended but may be a breaking change.
Default Value
true (new SDKs)