Skip to content

docs: Document how to disable Pydantic validation in Python SDKs #344

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
Aug 4, 2025
Merged

docs: Document how to disable Pydantic validation in Python SDKs #344

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e24f925
Documentation updates from Promptless
promptless[bot] Aug 4, 2025
8037615
expand pydantic-config options
devalog Aug 4, 2025
992e215
alphabetize options within pydantic section
devalog Aug 4, 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
187 changes: 140 additions & 47 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 @@ -5,17 +5,19 @@ description: Configuration options for the Fern Python SDK.

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

```yaml {7-10}
```yaml {7-12}
default-group: local
groups:
local:
generators:
- name: fernapi/fern-python
version: 0.7.1
version: <Markdown src="/snippets/version-number-python.mdx"/>
config:
package_name: "your_package"
client:
class_name: "YourClient"
pydantic-config:
skip_validation: true
```

## SDK Configuration Options
Expand Down Expand Up @@ -85,56 +87,12 @@ groups:
local:
generators:
- name: fernapi/fern-python
version: 0.7.1
version: <Markdown src="/snippets/version-number-python.mdx"/>
config:
package_name: "my_custom_package"
```
</ParamField>

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

<ParamField path="pydantic_config.include_union_utils" type="bool" default="false" required={false} toc={true}>
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} toc={true}>
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="pyproject_python_version" type="string" default="^3.8" required={false} toc={true}>
<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>
Expand Down Expand Up @@ -194,4 +152,139 @@ groups:

<ParamField path="exported_class_name" type="string" default="null" required={false} toc={true}>
The name of the exported client class that will be used in code snippets.
</ParamField>

### pydantic-config

Configure Pydantic model generation settings for your Python SDK.

```yaml
config:
pydantic-config:
enum_type: "literals"
extra_fields: "forbid"
frozen: true
include_union_utils: false
include_validators: true
orm_mode: false
require_optional_fields: false
skip_formatting: false
skip_validation: true
smart_union: true
union_naming: "v0"
use_inheritance_for_extended_models: true
use_pydantic_field_aliases: false
use_provided_defaults: true
use_str_enums: true
use_typeddict_requests: false
wrapped_aliases: false
```

<ParamField path="enum_type" type="'literals' | 'forward_compatible_python_enums' | 'python_enums'" default="literals" toc={true}>
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.
</ParamField>

<ParamField path="extra_fields" type="literal<'allow' | 'forbid' | 'ignore'>" default="allow" toc={true}>
How to handle extra fields not defined in the model schema.
</ParamField>

<ParamField path="frozen" type="bool" default="true" toc={true}>
Whether Pydantic models should be frozen (immutable after creation).
</ParamField>

<ParamField path="include_union_utils" type="bool" default="false" toc={true}>
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),
)
```
</ParamField>

<ParamField path="include_validators" type="bool" default="false" toc={true}>
Include custom validators in generated Pydantic models.
</ParamField>

<ParamField path="orm_mode" type="bool" default="false" toc={true}>
Enable ORM mode for Pydantic models to work with ORMs like SQLAlchemy.
</ParamField>

<ParamField path="package_name" type="string" required={false} toc={true}>
Custom package name for the generated models.
</ParamField>

<ParamField path="require_optional_fields" type="bool" default="false" toc={true}>
Whether optional fields must be explicitly provided (cannot be omitted).
</ParamField>

<ParamField path="skip_formatting" type="bool" default="false" toc={true}>
Skip code formatting for generated Pydantic models.
</ParamField>

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

<ParamField path="smart_union" type="bool" default="true" toc={true}>
Enable smart union handling in Pydantic models for better type discrimination.
</ParamField>

<ParamField path="union_naming" type="'v0' | 'v1'" default="v0" toc={true}>
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`:
```yaml
- name: fernapi/fern-python-sdk
version: 3.0.0-rc0
api:
settings:
unions: v1
```
</ParamField>

<ParamField path="use_pydantic_field_aliases" type="bool" default="false" toc={true}>
Use Pydantic field aliases for property names that differ from wire format.
</ParamField>

<ParamField path="use_provided_defaults" type="bool" default="false" toc={true}>
Leverage defaults specified in the API specification.
</ParamField>

<ParamField path="use_typeddict_requests" type="bool" default="false" toc={true}>
Generate TypedDicts instead of Pydantic Models for request objects.
</ParamField>

<ParamField path="version" type="'v1' | 'v2' | 'both' | 'v1_on_v2'" default="both" toc={true}>
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

</ParamField>

<ParamField path="wrapped_aliases" type="bool" default="false" toc={true}>
Enable wrapped aliases for Pydantic models. Only supported in Pydantic V1, V1_ON_V2, or V2.
</ParamField>

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