Speakeasy Logo
Skip to Content
DocumentationSpeakeasyGeneration ConfigPython Configuration

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.

Version and general configuration

python:
  version: 1.2.3
  authors: ["Author Name"]
  packageName: "openapi"
  moduleName: "openapi"
  packageManager: "uv" # or "poetry" to switch to poetry
Name
version
Required
true
Default Value
0.0.1
Description
The current version of the SDK.
packageName
Required
true
Default Value
openapi
Description
The distribution name of the PyPI package. See Python Package Metadata .
moduleName
Required
false
Default Value
Same as
Description
The name of the module users will import from. Allows using a different name for imports than the package name. PEP 420 implicit namespace packages are supported with period (.) characters, such as
. Custom code regions will be removed by updating the ModuleName
authors
Required
true
Default Value
["Speakeasy"]
Description
Authors of the published package.
packageManager
Required
false
Default Value
uv
Description
The package manager to use for dependency management and packaging. Valid options: 'uv' or 'poetry'. Defaults to 'uv' for better performance.

Description and URLs

python:
  description: "Python Client SDK Generated by Speakeasy."
  homepage: "https://example.com"
  documentationUrl: "https://example.com/docs"
Name
description
Required
false
Default Value
"Python Client SDK Generated by Speakeasy."
Description
A short description of the project.
homepage
Required
false
Default Value
null
Description
The URL for the homepage of the project.
documentationUrl
Required
false
Default Value
null
Description
The URL for the project documentation.

Different package and module names

You can configure a different name for the PyPI package and the module users will import from:

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

This can be useful when you want the package name to follow PyPI conventions (using hyphens) but the module name to follow Python conventions (using underscores).

Additional dependencies

python:
  additionalDependencies:
    main:
      requests: "^2.25.1"
    dev:
      pytest: "^6.2.1"
Name
additionalDependencies
Required
false
Default Value
{}
Description
Add additional dependencies to include in the generated
file.

Method and parameter management

python:
  maxMethodParams: 4
  flatteningOrder: "parameters-first"
  methodArguments: "infer-optional-args"
Name
flattenRequests
Required
false
Default Value
true
Description
Turn request parameters and body fields into a flat list of method arguments. This takes precedence over maxMethodParams. If there is no request body then maxMethodParams will be respected.
maxMethodParams
Required
false
Default Value
9999
Description
Maximum number of parameters before an input object is generated.
means input objects are always used.
flatteningOrder
Required
false
Default Value
parameters-first
Description
Determines the ordering of method arguments when flattening parameters and body fields.
or
methodArguments
Required
false
Default Value
require-security-and-request
Description
Determines how arguments for SDK methods are generated.

Security configuration

python:
  envVarPrefix: "SPEAKEASY"
  flattenGlobalSecurity: true
Name
flattenGlobalSecurity
Required
false
Default Value
true
Description
Enables inline security credentials during SDK instantiation.
envVarPrefix
Required
false
Default Value
""
Description
Sets a prefix for environment variables that allows users to configure global parameters and security.

Import management

python:
  imports:
    option: "openapi"
    paths:
      callbacks: "models/callbacks"
      errors: "models/errors"
      operations: "models/operations"
      shared: "models/shared"
      webhooks: "models/webhooks"
Field
option
Required
false
Default Value
"openapi"
Description
Defines the type of import strategy. Typically set to
, indicating that the structure is based on the OpenAPI document.
paths
Required
false
Default Value
{}
Description
Customizes where different parts of the SDK (e.g., callbacks, errors, and operations) will be imported from.

Import paths

Component
callbacks
Default Value
models/callbacks
Description
The directory where callback models will be imported from.
errors
Default Value
models/errors
Description
The directory where error models will be imported from.
operations
Default Value
models/operations
Description
The directory where operation models (i.e., API endpoints) will be 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.

Error and response handling

python:
  clientServerStatusCodesAsErrors: true
  responseFormat: "flat"
  enumFormat: "enum"
Name
clientServerStatusCodesAsErrors
Required
false
Default Value
true
Description
Whether to treat 4XX and 5XX status codes as errors.
responseFormat
Required
false
Default Value
flat
Description
Defines how responses are structured. Options:
,
, or
.
enumFormat
Required
false
Default Value
enum
Description
Determines how enums are generated. Options:
(Python enums) or
(union types).

Async method configuration

python:
  asyncMode: split  # or "both" (default)
Name
asyncMode
Required
false
Default Value
both
Description
Controls how asynchronous methods are generated.
(default) uses method-based approach with
suffixes.
uses constructor-based approach with separate
classes.

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 users will need to update their code to use the new constructor pattern.

Server-sent events configuration

python:
  sseFlatResponse: true
Name
sseFlatResponse
Required
false
Default Value
true
Description
When enabled, hoists the
field content to the top level for server-sent events, eliminating the need to destructure data from yielded items. Consumers can directly access the data without additional parsing.

Pytest configuration

python:
  pytestFilterWarnings:
    - error
    - "ignore::DeprecationWarning"
  pytestTimeout: 300
Name
pytestFilterWarnings
Required
false
Default Value
[]
Description
Global pytest filterwarnings configuration value, which are filters to control Python warnings. Use to ignore warnings or raise warnings as errors. Additional reference: https://docs.python.org/3/library/warnings.html#warning-filter 
pytestTimeout
Required
false
Default Value
0
Description
When value is greater than 0, installs pytest-timeout and sets the global pytest-timeout configuration value, which is the number of seconds before individual tests are timed out.

Fix flags

python:
  fixFlags:
    asyncPaginationSep2025: true
Name
asyncPaginationSep2025
Required
false
Default Value
true for new SDKs, false for existing SDKs
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. Defaults to true for new SDKs. For existing SDKs, setting true is recommended, but will be a breaking change.

Last updated on