# Generate Python SDKs from OpenAPI / Swagger
Source: https://speakeasy.com/docs/sdks/languages/python/methodology-python

import { Callout } from "@/mdx/components";
import { FileTree } from "nextra/components";



<Callout title="OSS Comparison" type="info">
  For a comparison between the Speakeasy Python SDK and some popular open-source
  generators, see [**this page**](/post/speakeasy-oss-python-generator).
</Callout>

## SDK Overview

Speakeasy-generated Python SDKs are designed to be best in class, providing a seamless developer experience and full type safety, alongside asynchronous support.

The core Python SDK features include:

- Fully type-annotated classes and methods with full Pydantic models and associated TypedDicts.
- Async and Sync methods for all endpoints.
- Support for streaming uploads and downloads.
- Support for Server-Sent Events (SSE) with automatic method overloads for enhanced type safety.
- Authentication support for OAuth flows and support for standard security mechanisms (HTTP Basic, application tokens, etc.).
- Optional pagination support for supported APIs.
- Optional support for retries in every operation.
- Complex number types including big integers and decimals.
- Date and date/time types using RFC3339 date formats.
- Custom type enums using strings and integers (including Open Enums).
- Union types and combined types.

### Python Package Structure

<FileTree>
  <FileTree.Folder name="src">
    <FileTree.Folder name="{Package Name}">
      <FileTree.File name="{SDK Class Name}.py" />
      <FileTree.File name="..." />
      <FileTree.Folder name="models">
        <FileTree.Folder name="shared">
          <FileTree.File name="..." />
        </FileTree.Folder>
        <FileTree.Folder name="operations">
          <FileTree.File name="..." />
        </FileTree.Folder>
        <FileTree.File name="..." />
      </FileTree.Folder>
      <FileTree.Folder name="utils">
        <FileTree.File name="..." />
      </FileTree.Folder>
    </FileTree.Folder>
  </FileTree.Folder>
  <FileTree.Folder name="docs">
    <FileTree.File name="..." />
  </FileTree.Folder>
  <FileTree.File name="setup.py" />
  <FileTree.File name="..." />
</FileTree>

By default, `uv` handles Python dependencies and packaging, but users can configure `poetry` instead via the `packageManager` option.

## Python Type Safety

Modern Python uses type hints to improve code readability and so do Speakeasy-generated Python SDKs! Speakeasy-generated Python SDKs expose type annotations for developers to perform type checks at runtime and increase type safety, we also employ Pydantic models to ensure that the data passed to and from the SDK is valid at runtime.

### The generated models

Speakeasy uses `pydantic` for all generated models to correctly serialize and deserialize objects; whether the objects are passed as query parameters, path parameters, or request bodies. Metadata based on the definitions provided by the OpenAPI document are appended to fields.

For example, this is the generated class for the [Drink](https://github.com/speakeasy-sdks/template-sdk/blob/main/openapi.yaml#L312) component from our [SpeakeasyBar template repository](https://github.com/speakeasy-sdks/template-sdk):

```python
class Drink(BaseModel):
    name: str
    r"""The name of the drink."""
    price: float
    r"""The price of one unit of the drink in US cents."""
    type: Optional[DrinkType] = None
    r"""The type of drink."""
    stock: Optional[int] = None
    r"""The number of units of the drink in stock, only available when authenticated."""
    product_code: Annotated[Optional[str], pydantic.Field(alias="productCode")] = None
    r"""The product code of the drink, only available when authenticated."""
```

Python also generates matching `TypedDict` classes for each model, which can be used to pass in dictionaries to the SDK methods without the need to import the model classes.

```python
class DrinkTypedDict(TypedDict):
    name: str
    r"""The name of the drink."""
    price: float
    r"""The price of one unit of the drink in US cents."""
    type: NotRequired[DrinkType]
    r"""The type of drink."""
    stock: NotRequired[int]
    r"""The number of units of the drink in stock, only available when authenticated."""
    product_code: NotRequired[str]
    r"""The product code of the drink, only available when authenticated."""
```

which allows methods to be called one of two ways:

```python
res = s.orders.create_order(drinks=[
    {
        "type": bar.OrderType.INGREDIENT,
        "product_code": "AC-A2DF3",
        "quantity": 138554,
    },
])
```

or

```python
res = s.orders.create_order(drinks=[
    Drink(
        type=bar.OrderType.INGREDIENT,
        product_code="AC-A2DF3",
        quantity=138554,
    ),
])
```

## Server-Sent Events (SSE) with type safety

Python SDKs automatically generate method overloads for Server-Sent Events operations when the `inferSSEOverload` configuration is enabled (default: `true`). This feature provides enhanced type safety by creating separate method signatures for streaming and non-streaming responses.

When an operation meets the following criteria, Speakeasy will generate overloaded methods:
- The operation has a required request body
- The request body contains a `stream` field (boolean type)
- The operation has exactly two responses: one `text/event-stream` and one `application/json`

```python