Python

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

yml

python:
  version: 1.2.3
  authors: ["Author Name"]
  packageName: "openapi"
  moduleName: "openapi"

Name	Required	Default Value	Description
version	true	0.0.1	The current version of the SDK.
packageName	true	openapi	The distribution name of the PyPI package. See Python Package Metadata.
moduleName	false	Same as `packageName`	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 `speakeasy.api_client`. Custom code regions will be removed by updating the ModuleName
authors	true	["Speakeasy"]	Authors of the published package. See Poetry Authors Field.

Description and URLs

yml

python:
  description: "Python Client SDK Generated by Speakeasy."
  homepage: "https://example.com"
  documentationUrl: "https://example.com/docs"

Name	Required	Default Value	Description
description	false	"Python Client SDK Generated by Speakeasy."	A short description of the project. See Poetry Description Field.
homepage	false	null	The URL for the homepage of the project.
documentationUrl	false	null	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:

yml

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

yml

python:
  additionalDependencies:
    main:
      requests: "^2.25.1"
    dev:
      pytest: "^6.2.1"

Name	Required	Default Value	Description
additionalDependencies	false	{}	Add additional dependencies to include in the generated `pyproject.toml` file.

Method and parameter management

yml

python:
  maxMethodParams: 4
  flatteningOrder: "parameters-first"
  methodArguments: "infer-optional-args"

Name	Required	Default Value	Description
flattenRequests	false	true	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	false	9999	Maximum number of parameters before an input object is generated. `0` means input objects are always used.
flatteningOrder	false	parameters-first	Determines the ordering of method arguments when flattening parameters and body fields. `parameters-first` or `body-first`
methodArguments	false	require-security-and-request	Determines how arguments for SDK methods are generated.

Security configuration

yml

python:
  envVarPrefix: "SPEAKEASY"
  flattenGlobalSecurity: true

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

Import management

yml

python:
  imports:
    option: "openapi"
    paths:
      callbacks: "models/callbacks"
      errors: "models/errors"
      operations: "models/operations"
      shared: "models/shared"
      webhooks: "models/webhooks"

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

Import paths

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

Error and response handling

yml

python:
  clientServerStatusCodesAsErrors: true
  responseFormat: "flat"
  enumFormat: "enum"

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

Pytest configuration

yml

python:
  pytestFilterWarnings:
    - error
    - "ignore::DeprecationWarning"
  pytestTimeout: 300

Name	Required	Default Value	Description
pytestFilterWarnings	false	[]	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	false	0	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.