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 name of the generated client class. Must be PascalCase. For example, setting client_class_name: "Acme" generates a client that users import as from your_package import Acme.

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>):

The default number of retries for failed requests in the generated SDK. Set to 0 to disable retries by default. SDK users can still override this per-request via request options.

When enabled, generates mock server (wire) tests to verify that the SDK sends and receives HTTP requests as expected.

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

Customize the name of the generated environment class/enum. By default, the environment class is named {ClientName}Environment (e.g., AcmeEnvironment for a client named Acme).

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]).

Custom extras are merged with the built-in aiohttp extra at generation time, so declaring your own extras won’t clobber it.

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

Paths to files that are automatically imported when the SDK package is loaded. This is useful for running custom setup code, such as Sentry integration, logging configuration, or telemetry hooks without modifying generated code.

Each entry is a module name relative to the package root (omit the .py extension). The SDK will attempt to import each module at package initialization time; missing files are skipped.

1
config:
2
  import_paths:
3
    - sentry_integration
4
    - custom_logging

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.

Enables lazy loading of client imports. When enabled, modules and classes are imported only when first accessed rather than at package initialization. This reduces memory footprint when using a small portion of a large API, at the cost of a latency penalty when first accessing a client.

Set to false to restore eager loading behavior.

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.

Controls how the offset parameter is interpreted for auto-paginated endpoints.

• item-index: The offset counts individual items (e.g., offset 20 skips the first 20 items).
• page-index: The offset counts pages (e.g., offset 3 skips to page 3).

When enabled, the generated SDK omits the X-Fern-Language, X-Fern-SDK-Name, and X-Fern-SDK-Version headers from HTTP requests.

Allow specifying arbitrary configuration to your packages pyproject.toml by adding a pyproject_toml block to your configuration whatever you include in this block will be added as-is to the pyproject.toml file. The config, as an example is:

1
config:
2
  pyproject_toml: |
3
    [tool.covcheck.group.unit.coverage]
4
    branch = 26.0
5
    line = 62.0
6
    [tool.covcheck.group.service.coverage]
7
    branch = 30.0
8
    line = 67.0

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. For most use cases, use the top-level client_class_name option instead.

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.

When enabled, generates a custom __init__ method for models with a single required field, allowing positional argument construction instead of requiring keyword arguments.

1
# Without positional_single_property_constructors (default)
2
wrapper = Wrapper(value="my_value")
3
4
# With positional_single_property_constructors enabled
5
wrapper = Wrapper("my_value")

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.