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


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:

, etc.

Default Value

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,

and in code

. PEP 420 implicit namespace packages are supported with period (

) characters — e.g.

generates the SDK in

with no

in the parent. Custom code regions will be removed by updating

Default Value

Same as

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

(new) / empty (legacy)

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

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


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:

(recommended) or

Default Value

(new) /

(legacy)

additionalDependencies

Required

false

Description

Specify additional dependencies to include in the generated

file.

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

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

and sets the global timeout (in seconds) before individual tests are timed out.

Default Value

Name	Required	Default Value	Description
packageManager	false	(new) / (legacy)	The package manager to use for dependency management and packaging. Options: (recommended) or .
additionalDependencies	false		Specify additional dependencies to include in the generated file.
compileCommands	false	N/A	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.
pytestFilterWarnings	false		When the array contains any strings, sets the global pytest value (filters to control Python warnings, e.g. ignoring or raising as errors). See Python warning filters .
pytestTimeout	false	0	When greater than 0, installs and sets the global timeout (in seconds) before individual tests are timed out.

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.

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.

means input objects are always used.

Default Value

(new) /

(legacy)

flattenRequests

Required

false

Description

Turn request parameters and body fields into a flat list of method arguments. Takes precedence over

. If there is no request body,

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:

Default Value

parameters-first

methodArguments

Required

false

Description

, when all parameters and the request body are optional, the argument to the function will be optional. Alternative:

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:

, or

Default Value

flat

multipartArrayFormat

Required

false

Description

Format for array field names in multipart form data.

appends

(e.g.

uses the field name as-is.

Default Value

(new) /

imports

Required

false

Description

Configuration for model import structure (paths for

Default Value

{}

Name	Required	Default Value	Description
maxMethodParams	false	(new) / (legacy)	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. means input objects are always used.
flattenRequests	false	true (new SDKs)	Turn request parameters and body fields into a flat list of method arguments. Takes precedence over . If there is no request body, is respected.
flatteningOrder	false	parameters-first	When flattening parameters and body fields, determines the ordering of generated method arguments. Options: or .
methodArguments	false	infer-optional-args	If , when all parameters and the request body are optional, the argument to the function will be optional. Alternative: .
flattenGlobalSecurity	false	true	Flatten the global security configuration if there is only a single option in the spec.
envVarPrefix	false	""	The environment variable prefix for security and global env variable overrides. If empty, these overrides will not be possible.
responseFormat	false	flat	Determines the shape of the response envelope returned from SDK methods. Options: , , or .
multipartArrayFormat	false	(new) /	Format for array field names in multipart form data. appends (e.g. ). uses the field name as-is.
imports	false	{}	Configuration for model import structure (paths for / / / / ).

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.

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

Async and SSE


python:
  asyncMode: split
  useAsyncHooks: false
  sseFlatResponse: false

Name

asyncMode

Required

false

Description

Whether to generate sync and/or async methods.

generates one constructor with

-suffixed methods.

generates

and

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

. 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

field from wrapper models, providing direct access to event data instead of the wrapper object.

Default Value

false

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

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


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) /

(legacy)

baseErrorName

Required

false

Description

The name of the base error class used for HTTP error responses.

Default Value

null

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

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:

Default Value

(new) /

(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

Default Value

true (new SDKs)

forwardCompatibleUnionsByDefault

Required

false

Description

Controls forward compatibility for discriminated unions in responses.

makes discriminated unions open to unknown discriminator values.

disables. Individual unions can be controlled with

Default Value

(new) /

(legacy)

inferUnionDiscriminators

Required

false

Description

Infer union discriminators for

s 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

syntax.

Default Value

true (new SDKs)

Name	Required	Default Value	Description
enumFormat	false	(new) / (legacy)	Determines the format to express enums in Python. Options: or .
forwardCompatibleEnumsByDefault	false	true (new SDKs)	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 .
forwardCompatibleUnionsByDefault	false	(new) / (legacy)	Controls forward compatibility for discriminated unions in responses. makes discriminated unions open to unknown discriminator values. disables. Individual unions can be controlled with .
inferUnionDiscriminators	false	true	Infer union discriminators for s missing explicit OpenAPI discriminator mapping.
preApplyUnionDiscriminators	false	true (new SDKs)	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 syntax.

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.

uses

Default Value

(new) /

(legacy)

allowedRedefinedBuiltins

Required

false

Description

List of names allowed to shadow builtins via SDK method parameters.

Default Value

(new) /

(legacy)

enableCustomCodeRegions

Required

false

Description

Allow custom code to be inserted into the generated SDK.

Default Value

false

Name	Required	Default Value	Description
inputModelSuffix	false	input	Suffix added to models with writeOnly fields that are generated as input models.
outputModelSuffix	false	output	Suffix added to models with readOnly fields that are generated as output models.
constFieldCasing	false	(new) / (legacy)	Casing convention for const fields in generated models. uses , uses .
allowedRedefinedBuiltins	false	(new) / (legacy)	List of names allowed to shadow builtins via SDK method parameters.
enableCustomCodeRegions	false	false	Allow custom code to be inserted into the generated SDK.

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

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)

Name	Required	Default Value	Description
responseRequiredSep2024	false	true (new SDKs)	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.
asyncPaginationSep2025	false	true (new SDKs)	Disabling not recommended. Enables changes introduced in September 2025 to fix async pagination methods to return async 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.
conflictResistantModelImportsFeb2026	false	true (new SDKs)	Enables conflict-resistant model imports introduced in February 2026. For existing SDKs, setting to true is recommended but may be a breaking change.

Last updated on April 24, 2026