# Python Configuration Options
Source: https://speakeasy.com/docs/speakeasy-reference/generation/python-config

import { Table, Callout } from "@/mdx/components";



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"
  packageManager: "uv" # or "poetry" to switch to poetry
```

<Table
  data={[
    {
      name: "version",
      required: "true",
      default: "0.0.1",
      description: "The current version of the SDK.",
    },
    {
      name: "packageName",
      required: "true",
      default: "openapi",
      description:
        "The distribution name of the PyPI package. See [Python Package Metadata](https://packaging.python.org/en/latest/specifications/name-normalization/).",
    },
    {
      name: "moduleName",
      required: "false",
      default: "Same as `packageName`",
      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 `speakeasy.api_client`. [Custom code](/docs/customize/code/code-regions/overview) regions will be removed by updating the ModuleName",
    },
    {
      name: "authors",
      required: "true",
      default: '["Speakeasy"]',
      description:
        "Authors of the published package.",
    },
    {
      name: "packageManager",
      required: "false",
      default: "uv",
      description:
        "The package manager to use for dependency management and packaging. Valid options: 'uv' or 'poetry'. Defaults to 'uv' for better performance.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Description and URLs

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

<Table
  data={[
    {
      name: "description",
      required: "false",
      default: '"Python Client SDK Generated by Speakeasy."',
      description:
        "A short description of the project.",
    },
    {
      name: "homepage",
      required: "false",
      default: "null",
      description: "The URL for the homepage of the project.",
    },
    {
      name: "documentationUrl",
      required: "false",
      default: "null",
      description: "The URL for the project documentation.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## 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"
```

<Table
  data={[
    {
      name: "additionalDependencies",
      required: "false",
      default: "{}",
      description:
        "Add additional dependencies to include in the generated `pyproject.toml` file.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Method and parameter management

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

<Table
  data={[
    {
      name: "flattenRequests",
      required: "false",
      default: "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.",
    },
    {
      name: "[maxMethodParams](/docs/customize/methods)",
      required: "false",
      default: "9999",
      description:
        "Maximum number of parameters before an input object is generated. `0` means input objects are always used.",
    },
    {
      name: "flatteningOrder",
      required: "false",
      default: "parameters-first",
      description:
        "Determines the ordering of method arguments when flattening parameters and body fields. `parameters-first` or `body-first`",
    },
    {
      name: "methodArguments",
      required: "false",
      default: "require-security-and-request",
      description: "Determines how arguments for SDK methods are generated.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Security configuration

```yml
python:
  envVarPrefix: "SPEAKEASY"
  flattenGlobalSecurity: true
```

<Table
  data={[
    {
      name: "[flattenGlobalSecurity](/docs/customize/authentication/overview)",
      required: "false",
      default: "true",
      description:
        "Enables inline security credentials during SDK instantiation.",
    },
    {
      name: "envVarPrefix",
      required: "false",
      default: '""',
      description:
        "Sets a prefix for environment variables that allows users to configure global parameters and security.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Import management

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

<Table
  data={[
    {
      field: "option",
      required: "false",
      default: '"openapi"',
      description:
        'Defines the type of import strategy. Typically set to `"openapi"`, indicating that the structure is based on the OpenAPI document.',
    },
    {
      field: "paths",
      required: "false",
      default: "{}",
      description:
        "Customizes where different parts of the SDK (e.g., callbacks, errors, and operations) will be imported from.",
    },
  ]}
  columns={[
    { key: "field", header: "Field" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

### Import paths

<Table
  data={[
    {
      component: "callbacks",
      default: "models/callbacks",
      description: "The directory where callback models will be imported from.",
    },
    {
      component: "errors",
      default: "models/errors",
      description: "The directory where error models will be imported from.",
    },
    {
      component: "operations",
      default: "models/operations",
      description:
        "The directory where operation models (i.e., API endpoints) will be imported from.",
    },
    {
      component: "shared",
      default: "models/components",
      description:
        "The directory for shared components, such as reusable schemas, and data models imported from the OpenAPI spec.",
    },
    {
      component: "webhooks",
      default: "models/webhooks",
      description:
        "The directory for webhook models, if the SDK includes support for webhooks.",
    },
  ]}
  columns={[
    { key: "component", header: "Component" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Error and response handling

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

<Table
  data={[
    {
      name: "clientServerStatusCodesAsErrors",
      required: "false",
      default: "true",
      description: "Whether to treat 4XX and 5XX status codes as errors.",
    },
    {
      name: "[responseFormat](/docs/customize/responses/responses)",
      required: "false",
      default: "flat",
      description:
        "Defines how responses are structured. Options: `envelope`, `envelope-http`, or `flat`.",
    },
    {
      name: "enumFormat",
      required: "false",
      default: "enum",
      description:
        "Determines how enums are generated. Options: `enum` (Python enums) or `union` (union types).",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>
## Async method configuration

```yml
python:
  asyncMode: split  # or "both" (default)
```

<Table
  data={[
    {
      name: "asyncMode",
      required: "false",
      default: "both",
      description:
        "Controls how asynchronous methods are generated. `both` (default) uses method-based approach with `_async` suffixes. `split` uses constructor-based approach with separate `AsyncMyAPI` classes.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

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.

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