Python Configuration

Additional modules or classes to export from the package’s __init__.py file. This allows you to customize what’s available when users import your package.

Each object should specify which file to import from and what to import:

1
config:
2
  additional_init_exports:
3
    - from: core.oauth_flow
4
      imports:
5
        - validate_token
6
    - from: utils.helpers
7
      imports:
8
        - format_currency
9
        - PhoneValidator

This enables users to access your custom functions directly:

1
from my_package import validate_token, format_currency, PhoneValidator

The module path to import from, using Python dot notation. Omit the .py extension and replace path separators with dots.

For example, if you want to import from the file core/oauth_flow.py, specify that as - from: core.oauth_flow.

List of class names, function names, or other objects to import from the specified file.

The chunk size to use (if any) when processing a response bytes stream within iter_bytes or aiter_bytes results in: for chunk in response.iter_bytes(chunk_size=<default_bytes_stream_chunk_size>):

When enabled, excludes type definitions from being exported in the package’s __init__.py file, reducing the public API surface.

If you want to add custom dependencies to your generated SDK, you can specify them using this configuration. For example, to add a dependency on boto3, your config would look like:

1
config:
2
  extra_dependencies:
3
    boto3: 1.28.15

Specify additional development dependencies to include in the generated SDK’s setup configuration. These are dependencies used for development and testing but not required by end users.

Define optional dependency groups that users can install with your package using pip extras (e.g., pip install your-package[extra-name]).

When enabled, generates a flatter package structure by reducing nested directories and modules.

Whether to follow redirects by default in HTTP requests.

Feature flag that improves imports in the Python SDK by removing nested resources directory

Whether or not to include legacy wire tests in the generated SDK

When enabled, generates utility methods for working with union types, including factory methods and visitor patterns.

If true, treats path parameters as named parameters in endpoint functions.

Feature flag that removes the usage of request objects, and instead uses parameters in function signatures where possible.

Specifies the Python package name that users will import your generated client from.

For example, setting package_name: "my_custom_package" enables users to use my_custom_package import Client to import your client:

1
default-group: local
2
groups:
3
  local:
4
    generators:
5
      - name: fernapi/fern-python
6
        version: 4.26.2
7
        config:
8
          package_name: "my_custom_package"

Path to a custom pyproject.toml template file to use instead of the default generated one.

Feature flag that enables generation of Python websocket clients.

When enabled, skips code formatting (like black) on the generated Python code.

By default, the generator generates a client that times out after 60 seconds. You can customize this value by providing a different number or setting to infinity to get rid of timeouts.

When enabled, includes the API name as part of the package structure and naming.

Whether to generate Pydantic models that implement inheritance when a model utilizes the Fern extends keyword.

Whether or not to generate TypedDicts instead of Pydantic Models for request objects.

Whether or not to generate TypedDicts instead of Pydantic Models for file upload request objects. Note that this flag was only introduced due to an oversight in the use_typeddict_requests flag implementation; it should be removed in the future.

The filename for the generated client file.

The name of the generated client class.

The filename of the exported client which will be used in code snippets.

The name of the exported client class that will be used in code snippets.

The type of enums to use in the generated models:

• literals: Use Python Literal types, e.g. MyEnum = Literal["foo", "bar"]
• forward_compatible_python_enums: Use Python Enum classes, with a MyEnum._UNKNOWN member for forward compatibility. MyEnum._UNKNOWN.value contains the raw unrecognized value.
• python_enums: Your vanilla Python enum class, with the members defined within your API.

How to handle extra fields not defined in the model schema.

Whether Pydantic models should be frozen (immutable after creation).

When enabled, the generator will output a Pydantic __root__ class that will contain utilities to visit the union. For example, for the following union type:

types:
Shape:
  union:
    circle: Circle
    triangle: Triangle

you will get a generated Shape class that has a factory and visitor:

1
# Use a factory to instantiate the union
2
Shape.factory.circle(Circle(...))
3
4
# Visit every case in the union
5
shape = get_shape()
6
shape.visit(
7
  circle: lambda circle: do_something_with_circle(circle),
8
  triangle: lambda triangle: do_something_with_triangle(triangle),
9
)

Include custom validators in generated Pydantic models.

Enable ORM mode for Pydantic models to work with ORMs like SQLAlchemy.

Custom package name for the generated models.

Whether optional fields must be explicitly provided (cannot be omitted).

Skip code formatting for generated Pydantic models.

When enabled, disables Pydantic validation for API responses. This ensures that Pydantic does not immediately fail if the model being returned from an API does not exactly match the Pydantic model.

This is meant to add flexibility should your SDK fall behind your API, but should be used sparingly, as the type-hinting for users will still reflect the Pydantic model exactly.

Enable smart union handling in Pydantic models for better type discrimination.

Control union naming strategy. If you are dealing with discriminated union members that already have the discriminant property on them (and they’re only used in one union), you should prefer the global API config within your generators.yml:

1
- name: fernapi/fern-python-sdk
2
  version: 3.0.0-rc0
3
  api:
4
    settings:
5
      unions: v1

Use Pydantic field aliases for property names that differ from wire format.

Leverage defaults specified in the API specification.

Generate TypedDicts instead of Pydantic Models for request objects.

By default, the generator generates pydantic models that are v1 and v2 compatible. However you can override them to:

• v1: strictly use Pydantic v1
• v2: strictly use Pydantic v2
• both: maintain compatibility with both versions
• v1_on_v2: use Pydantic v1 compatibility layer on v2

Enable wrapped aliases for Pydantic models. Only supported in Pydantic V1, V1_ON_V2, or V2.

Generate Pydantic models that implement inheritance when a model utilizes the Fern extends keyword.