Skip to content

Add documentation for Python configuration options #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 3, 2025
Merged

Add documentation for Python configuration options #17

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e1588db
fill out config file for python sdk
devalog Jul 3, 2025
245e249
add client example
devalog Jul 3, 2025
0132b36
fix code example
devalog Jul 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 147 additions & 2 deletions fern/products/sdks/overview/python/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,151 @@ title: Python Configuration
description: Configuration options for the Fern Python SDK.
---

# Python Configuration
You can customize the behavior of the Python SDK generator in `generators.yml`:

Discover how to configure the Fern Python SDK for your project.
```yml {7-8}
default-group: local
groups:
local:
generators:
- name: fernapi/fern-python
version: 0.6.6
config:
include_validators: true
Copy link
Member

@dsinghvi dsinghvi Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you show can example of using the client.name property since that is the most used config!

Copy link
Collaborator Author

@devalog devalog Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes! would that look like this?

config:
  client:
    filename: "my_custom_client.py"
    class_name: "MyClient"
    exported_filename: "my_client.py"
    exported_class_name: "APIClient"

and actually, the subfields for the client option aren't documented on this page. something to add?

```

## SDK Configuration Options

<ParamField path="extra_dependencies" type="object" default="{}" required={false}>
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:
```
config:
extra_dependencies:
boto3: 1.28.15
```
</ParamField>

<ParamField path="extra_dev_dependencies" type="object" default="{}" required={false}>
</ParamField>

<ParamField path="extras" type="object" default="{}" required={false}>
</ParamField>

<ParamField path="skip_formatting" type="bool" default="false" required={false}>
</ParamField>

<ParamField path="client" type="ClientConfiguration" default="ClientConfiguration()" required={false}>
</ParamField>

<ParamField path="include_union_utils" type="bool" default="false" required={false}>
</ParamField>

<ParamField path="use_api_name_in_package" type="bool" default="false" required={false}>
</ParamField>

<ParamField path="package_name" type="string" default="null" required={false}>
</ParamField>

<ParamField path="timeout_in_seconds" type="number | 'infinity'" default="60" required={false}>
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.
</ParamField>

<ParamField path="flat_layout" type="bool" default="false" required={false}>
</ParamField>

<ParamField path="pydantic_config" type="SdkPydanticModelCustomConfig" default="SdkPydanticModelCustomConfig()" required={false}>
</ParamField>

<ParamField path="pydantic_config.include_union_utils" type="bool" default="false" required={false}>
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:
```python
# Use a factory to instantiate the union
Shape.factory.circle(Circle(...))

# Visit every case in the union
shape = get_shape()
shape.visit(
circle: lambda circle: do_something_with_circle(circle),
triangle: lambda triangle: do_something_with_triangle(triangle),
)
```

When enabled, the python generator will not run Black formatting in the generated code. Black is slow so this can potentially speed up code generation quite a bit.
</ParamField>

<ParamField path="pydantic_config.version" type="'v1' | 'v2' | 'both' | 'v1_on_v2'" default="both" required={false}>
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

Example:
```yaml
config:
pydantic_config:
version: v1 # or v2 or "both"
```
</ParamField>

<ParamField path="additional_init_exports" type="array" default="null" required={false}>
</ParamField>

<ParamField path="exclude_types_from_init_exports" type="bool" default="false" required={false}>
</ParamField>

<ParamField path="improved_imports" type="bool" default="true" required={false}>
Feature flag that improves imports in the Python SDK by removing nested `resources` directory
</ParamField>

<ParamField path="follow_redirects_by_default" type="bool" default="true" required={false}>
Whether to follow redirects by default in HTTP requests.
</ParamField>

<ParamField path="inline_request_params" type="bool" default="true" required={false}>
Feature flag that removes the usage of request objects, and instead uses parameters in function signatures where possible.
</ParamField>

<ParamField path="inline_path_params" type="bool" default="false" required={false}>
If true, treats path parameters as named parameters in endpoint functions.
</ParamField>

<ParamField path="should_generate_websocket_clients" type="bool" default="false" required={false}>
Feature flag that enables generation of Python websocket clients.
</ParamField>

<ParamField path="pyproject_python_version" type="string" default="^3.8" required={false}>
<Warning>This changes your declared python dependency, which is not meant to be done often if at all. This is a last resort if any dependencies force you to change your version requirements.</Warning>
</ParamField>

<ParamField path="use_typeddict_requests" type="bool" default="false" required={false}>
Whether or not to generate `TypedDicts` instead of Pydantic Models for request objects.
</ParamField>

<ParamField path="use_typeddict_requests_for_file_upload" type="bool" default="false" required={false}>
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.
</ParamField>

<ParamField path="use_inheritance_for_extended_models" type="bool" default="true" required={false}>
Whether to generate Pydantic models that implement inheritance when a model utilizes the Fern `extends` keyword.
</ParamField>

<ParamField path="pyproject_toml" type="string" default="null" required={false}>
</ParamField>

<ParamField path="default_bytes_stream_chunk_size" type="number" default="null" required={false}>
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>):`
</ParamField>

<ParamField path="include_legacy_wire_tests" type="bool" default="false" required={false}>
Whether or not to include legacy wire tests in the generated SDK
</ParamField>