Skip to content

Commit 8037615

Browse files
devalogdevalog
committed
expand pydantic-config options
1 parent e24f925 commit 8037615

File tree

1 file changed

+145
-59
lines changed

1 file changed

+145
-59
lines changed

‎fern/products/sdks/overview/python/configuration.mdx‎

Lines changed: 145 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ groups:
1111
local:
1212
generators:
1313
- name: fernapi/fern-python
14-
version: 0.7.1
14+
version: <Markdown src="/snippets/version-number-python.mdx"/>
1515
config:
1616
package_name: "your_package"
1717
client:
@@ -85,56 +85,12 @@ groups:
8585
local:
8686
generators:
8787
- name: fernapi/fern-python
88-
version: 0.7.1
88+
version: <Markdown src="/snippets/version-number-python.mdx"/>
8989
config:
9090
package_name: "my_custom_package"
9191
```
9292
</ParamField>
9393

94-
<ParamField path="pydantic_config" type="SdkPydanticModelCustomConfig" default="SdkPydanticModelCustomConfig()" required={false} toc={true}>
95-
</ParamField>
96-
97-
<ParamField path="pydantic_config.include_union_utils" type="bool" default="false" required={false} toc={true}>
98-
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:
99-
100-
```
101-
types:
102-
Shape:
103-
union:
104-
circle: Circle
105-
triangle: Triangle
106-
```
107-
you will get a generated `Shape` class that has a factory and visitor:
108-
```python
109-
# Use a factory to instantiate the union
110-
Shape.factory.circle(Circle(...))
111-
112-
# Visit every case in the union
113-
shape = get_shape()
114-
shape.visit(
115-
circle: lambda circle: do_something_with_circle(circle),
116-
triangle: lambda triangle: do_something_with_triangle(triangle),
117-
)
118-
```
119-
120-
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.
121-
</ParamField>
122-
123-
<ParamField path="pydantic_config.version" type="'v1' | 'v2' | 'both' | 'v1_on_v2'" default="both" required={false} toc={true}>
124-
By default, the generator generates pydantic models that are v1 and v2 compatible. However you can override them to:
125-
- `v1`: strictly use Pydantic v1
126-
- `v2`: strictly use Pydantic v2
127-
- `both`: maintain compatibility with both versions
128-
- `v1_on_v2`: use Pydantic v1 compatibility layer on v2
129-
130-
Example:
131-
```yaml
132-
config:
133-
pydantic_config:
134-
version: v1 # or v2 or "both"
135-
```
136-
</ParamField>
137-
13894
<ParamField path="pyproject_python_version" type="string" default="^3.8" required={false} toc={true}>
13995
<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>
14096
</ParamField>
@@ -149,19 +105,6 @@ groups:
149105
<ParamField path="skip_formatting" type="bool" default="false" required={false} toc={true}>
150106
</ParamField>
151107

152-
<ParamField path="skip_validation" type="bool" default="false" required={false} toc={true}>
153-
<Warning>This is an experimental feature that should be used sparingly.</Warning>
154-
155-
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.
156-
157-
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.
158-
159-
```yaml
160-
config:
161-
skip_validation: true
162-
```
163-
</ParamField>
164-
165108
<ParamField path="timeout_in_seconds" type="number | 'infinity'" default="60" required={false} toc={true}>
166109
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.
167110
</ParamField>
@@ -207,4 +150,147 @@ groups:
207150

208151
<ParamField path="exported_class_name" type="string" default="null" required={false} toc={true}>
209152
The name of the exported client class that will be used in code snippets.
153+
</ParamField>
154+
155+
### pydantic-config
156+
157+
Configure Pydantic model generation settings for your Python SDK.
158+
159+
```yaml
160+
config:
161+
pydantic-config:
162+
frozen: true
163+
orm_mode: false
164+
smart_union: true
165+
include_union_utils: false
166+
require_optional_fields: false
167+
use_pydantic_field_aliases: false
168+
include_validators: true
169+
extra_fields: "forbid"
170+
skip_formatting: false
171+
skip_validation: false
172+
use_provided_defaults: true
173+
use_str_enums: true
174+
enum_type: "literals"
175+
wrapped_aliases: false
176+
union_naming: "v0"
177+
use_typeddict_requests: false
178+
use_inheritance_for_extended_models: true
179+
```
180+
181+
<ParamField path="frozen" type="bool" default="true">
182+
Whether Pydantic models should be frozen (immutable after creation).
183+
</ParamField>
184+
185+
<ParamField path="orm_mode" type="bool" default="false">
186+
Enable ORM mode for Pydantic models to work with ORMs like SQLAlchemy.
187+
</ParamField>
188+
189+
<ParamField path="smart_union" type="bool" default="true">
190+
Enable smart union handling in Pydantic models for better type discrimination.
191+
</ParamField>
192+
193+
<ParamField path="include_union_utils" type="bool" default="false">
194+
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:
195+
196+
```
197+
types:
198+
Shape:
199+
union:
200+
circle: Circle
201+
triangle: Triangle
202+
```
203+
you will get a generated `Shape` class that has a factory and visitor:
204+
```python
205+
# Use a factory to instantiate the union
206+
Shape.factory.circle(Circle(...))
207+
208+
# Visit every case in the union
209+
shape = get_shape()
210+
shape.visit(
211+
circle: lambda circle: do_something_with_circle(circle),
212+
triangle: lambda triangle: do_something_with_triangle(triangle),
213+
)
214+
```
215+
</ParamField>
216+
217+
<ParamField path="require_optional_fields" type="bool" default="false">
218+
Whether optional fields must be explicitly provided (cannot be omitted).
219+
</ParamField>
220+
221+
<ParamField path="use_pydantic_field_aliases" type="bool" default="false">
222+
Use Pydantic field aliases for property names that differ from wire format.
223+
</ParamField>
224+
225+
<ParamField path="include_validators" type="bool" default="false">
226+
Include custom validators in generated Pydantic models.
227+
</ParamField>
228+
229+
<ParamField path="forbid_extra_fields" type="bool" deprecated={true}>
230+
Use `extra_fields` instead.
231+
</ParamField>
232+
233+
<ParamField path="extra_fields" type="literal<'allow' | 'forbid' | 'ignore'>" default="allow">
234+
How to handle extra fields not defined in the model schema.
235+
</ParamField>
236+
237+
<ParamField path="skip_formatting" type="bool" default="false">
238+
Skip code formatting for generated Pydantic models.
239+
</ParamField>
240+
241+
<ParamField path="package_name" type="string" required={false}>
242+
Custom package name for the generated models.
243+
</ParamField>
244+
245+
<ParamField path="skip_validation" type="bool" default="false">
246+
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.
247+
248+
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.
249+
</ParamField>
250+
251+
<ParamField path="use_provided_defaults" type="bool" default="false">
252+
Leverage defaults specified in the API specification.
253+
</ParamField>
254+
255+
<ParamField path="use_typeddict_requests" type="bool" default="false">
256+
Generate TypedDicts instead of Pydantic Models for request objects.
257+
</ParamField>
258+
259+
<ParamField path="version" type="'v1' | 'v2' | 'both' | 'v1_on_v2'" default="both">
260+
By default, the generator generates pydantic models that are v1 and v2 compatible. However you can override them to:
261+
- `v1`: strictly use Pydantic v1
262+
- `v2`: strictly use Pydantic v2
263+
- `both`: maintain compatibility with both versions
264+
- `v1_on_v2`: use Pydantic v1 compatibility layer on v2
265+
266+
</ParamField>
267+
268+
<ParamField path="use_str_enums" type="bool" default="true" deprecated={true}>
269+
Use `enum_type` instead. This is equivalent to `enum_type: "literals"`.
270+
</ParamField>
271+
272+
<ParamField path="enum_type" type="'literals' | 'forward_compatible_python_enums' | 'python_enums'" default="literals">
273+
The type of enums to use in the generated models:
274+
- `literals`: Use Python Literal types, e.g. `MyEnum = Literal["foo", "bar"]`
275+
- `forward_compatible_python_enums`: Use Python Enum classes, with a `MyEnum._UNKNOWN` member for forward compatibility. `MyEnum._UNKNOWN.value` contains the raw unrecognized value.
276+
- `python_enums`: Your vanilla Python enum class, with the members defined within your API.
277+
</ParamField>
278+
279+
<ParamField path="wrapped_aliases" type="bool" default="false">
280+
Enable wrapped aliases for Pydantic models. Only supported in Pydantic V1, V1_ON_V2, or V2.
281+
</ParamField>
282+
283+
<ParamField path="union_naming" type="'v0' | 'v1'" default="v0">
284+
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`:
285+
```yaml
286+
- name: fernapi/fern-python-sdk
287+
version: 3.0.0-rc0
288+
api:
289+
settings:
290+
unions: v1
291+
```
292+
</ParamField>
293+
294+
<ParamField path="use_inheritance_for_extended_models" type="bool" default="true">
295+
Generate Pydantic models that implement inheritance when a model utilizes the Fern `extends` keyword.
210296
</ParamField>

0 commit comments

Comments
 (0)