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
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
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:
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
Name
additionalDependencies
Required
false
Default Value
{}
Description
Add additional dependencies to include in the generated
file.
Method and parameter management
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.
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
Name
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
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
Name
clientServerStatusCodesAsErrors
Required
false
Default Value
true
Description
Whether to treat 4XX and 5XX status codes as errors.
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
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.
Constructor-based (split): Separate constructors for synchronous and asynchronous clients. All method names are identical between sync and async versions.
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
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
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
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