> This page is for SDK, version Current (default).
> For other versions, use one of these documentation indexes:
> - Current (default): https://buildwithfern.com/learn/sdks/current/llms.txt
> - Legacy: https://buildwithfern.com/learn/sdks/legacy/llms.txt

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Python 配置

> Fern Python SDK 的配置选项。

您可以在 `generators.yml` 中自定义 Python SDK 生成器的行为：

**`generators.yml`**

```yaml {6-15} title="generators.yml"
groups:
  python-sdk:
    generators:
      - name: fern-python
        version: 5.41.10
        config:
          package_name: "your_package"
          client_class_name: "YourClient" 
          additional_init_exports:
            - from: file_with_custom_function
              imports:
                - custom_function
          pydantic_config:
            skip_validation: true
          environment_class_name: "AcmeEnvironment"
```

**`additional_init_exports`** `array of objects` — default: null

要从包的 `__init__.py` 文件中导出的其他模块或类。这允许您自定义用户导入包时可用的内容。

每个对象都应指定要从哪个文件导入以及要导入的内容：

```yaml
config:
  additional_init_exports:
    - from: core.oauth_flow
      imports:
        - validate_token
    - from: utils.helpers
      imports:
        - format_currency
        - PhoneValidator
```

这使用户能够直接访问您的自定义函数：

```python
from my_package import validate_token, format_currency, PhoneValidator
```

---

**`additional_init_exports[].from`** `string` — required

要导入的模块路径，使用 Python 点记法。省略 `.py` 扩展名并用点替换路径分隔符。

例如，如果您要从文件 `core/oauth_flow.py` 导入，请将其指定为 `- from: core.oauth_flow`。

---

**`additional_init_exports[].imports`** `array of strings` — required

要从指定文件导入的类名、函数名或其他对象的列表。

---

**`client_class_name`** `string` — default: null

生成的客户端类的名称。必须是 PascalCase。例如，设置 `client_class_name: "Acme"` 会生成用户可以使用 `from your_package import Acme` 导入的客户端。

---

**`default_bytes_stream_chunk_size`** `number` — default: null

在 `iter_bytes` 或 `aiter_bytes` 结果中处理响应字节流时使用的块大小（如果有）：`for chunk in response.iter_bytes(chunk_size=<default_bytes_stream_chunk_size>):`

---

**`enable_wire_tests`** `bool` — default: false

启用时，生成[模拟服务器（wire）测试](/learn/zh/sdks/deep-dives/testing#mock-server-tests)来验证 SDK 是否按预期发送和接收 HTTP 请求。

---

**`exclude_types_from_init_exports`** `boolean` — default: false

启用时，从包的 `__init__.py` 文件的导出中排除类型定义，减少公共 API 表面。

---

**`environment_class_name`** `string` — default: \{ClientName}Environment

自定义生成的环境类/枚举的名称。默认情况下，环境类名为 `{ClientName}Environment`（例如，对于名为 `Acme` 的客户端，名称为 `AcmeEnvironment`）。

---

**`extra_dependencies`** `object` — default: \{}

> **企业功能**
>
> 此功能仅适用于[企业计划](https://buildwithfern.com/pricing)。如需开始使用，请联系 [support@buildwithfern.com](mailto:support@buildwithfern.com)。

如果您想向生成的 SDK 添加自定义依赖项，可以使用此配置指定它们。例如，要添加对 boto3 的依赖，您的配置如下所示：

```yaml
config:
  extra_dependencies:
    boto3: 1.28.15
```

---

**`extra_dev_dependencies`** `object` — default: \{}

> **企业功能**
>
> 此功能仅适用于[企业计划](https://buildwithfern.com/pricing)。如需开始使用，请联系 [support@buildwithfern.com](mailto:support@buildwithfern.com)。

指定要包含在生成的 SDK 设置配置中的其他开发依赖项。这些是用于开发和测试的依赖项，但不是最终用户所必需的。

---

**`extras`** `object` — default: \{}

定义用户可以使用 pip extras 与您的包一起安装的可选依赖组（例如，`pip install your-package[extra-name]`）。

自定义 extras 在生成时与内置的 [`aiohttp` extra](/learn/zh/sdks/generators/python/aiohttp-support) 合并，因此声明您自己的 extras 不会覆盖它。

---

**`flat_layout`** `bool` — default: false

启用时，通过减少嵌套目录和模块来生成更扁平的包结构。

---

**`follow_redirects_by_default`** `bool` — default: true

是否在 HTTP 请求中默认跟随重定向。

---

**`improved_imports`** `bool` — default: true

通过删除嵌套的 `resources` 目录来改进 Python SDK 中导入的功能标志

---

**`import_paths`** `array of strings` — default: null

加载 SDK 包时自动导入的文件路径。这对于运行自定义设置代码非常有用，例如 Sentry 集成、日志配置或遥测钩子，而无需修改生成的代码。

每个条目都是相对于包根目录的模块名称（省略 `.py` 扩展名）。SDK 将在包初始化时尝试导入每个模块；缺失的文件将被跳过。

```yaml
config:
  import_paths:
    - sentry_integration
    - custom_logging
```

> **Note**
>
> `import_paths` 中列出的文件也必须添加到 `.fernignore`，这样它们就不会在生成期间被覆盖。

---

**`include_legacy_wire_tests`** `bool` — default: false

是否在生成的 SDK 中包含传统 wire 测试

---

**`include_union_utils`** `bool` — default: false

启用时，生成用于处理联合类型的实用方法，包括工厂方法和访问者模式。

---

**`inline_path_params`** `bool` — default: false

如果为 true，则将路径参数视为端点函数中的命名参数。

---

**`inline_request_params`** `bool` — default: true

删除请求对象的使用，改为在可能的情况下在函数签名中使用参数的功能标志。

---

**`lazy_import`** `bool` — default: true

启用客户端导入的延迟加载。启用时，模块和类仅在首次访问时导入，而不是在包初始化时导入。这减少了使用大型 API 的一小部分时的内存占用，但代价是首次访问客户端时的延迟损失。

设置为 `false` 以恢复立即加载行为。

---

**`package_name`** `string` — default: null

指定用户将从中导入生成的客户端的 Python 包名称。

例如，设置 `package_name: "my_custom_package"` 使用户能够使用 `my_custom_package import Client` 来导入您的客户端。

---

**`pyproject_python_version`** `string` — default: ^3.8

> **Warning**
>
> 这会更改您声明的 python 依赖项，通常不应该经常这样做。这是在任何依赖项强制您更改版本要求时的最后手段。

---

**`pyproject_toml`** `string` — default: null

允许通过向配置添加 `pyproject_toml` 块来为包的 `pyproject.toml` 指定任意配置，您在此块中包含的任何内容都将按原样添加到 `pyproject.toml` 文件中。配置示例为：

```yaml
config:
  pyproject_toml: |
    [tool.covcheck.group.unit.coverage]
    branch = 26.0
    line = 62.0
    [tool.covcheck.group.service.coverage]
    branch = 30.0
    line = 67.0
```

---

**`should_generate_websocket_clients`** `bool` — default: false

启用 Python WebSocket 客户端生成的功能标志。

---

**`skip_formatting`** `bool` — default: false

启用时，跳过对生成的 Python 代码进行代码格式化（如 black）。

---

**`timeout_in_seconds`** `number | 'infinity'` — default: 60

默认情况下，生成器生成一个在 60 秒后超时的客户端。您可以通过提供不同的数字或设置为 `infinity` 来自定义此值以取消超时。

---

**`use_api_name_in_package`** `bool` — default: false

启用时，将 API 名称作为包结构和命名的一部分。

---

**`use_inheritance_for_extended_models`** `bool` — default: true

当模型使用 Fern `extends` 关键字时，是否生成实现继承的 Pydantic 模型。

---

**`use_typeddict_requests`** `bool` — default: false

是否为请求对象生成 `TypedDicts` 而不是 Pydantic 模型。

---

**`use_typeddict_requests_for_file_upload`** `bool` — default: false

是否为文件上传请求对象生成 TypedDicts 而不是 Pydantic 模型。请注意，此标志仅因为 `use_typeddict_requests` 标志实现中的疏忽而引入；将来应该删除它。

---

### client

`client` 块为生成的客户端类和文件结构提供高级配置。对于大多数用例，顶级 `client_class_name` 选项就足够了。当您需要自定义文件名或具有不同的内部和导出类名时，请使用 `client` 块。

```yaml
config:
  client:
    filename: "my_client.py"
    class_name: "MyClient"
    exported_filename: "my_client.py"
    exported_class_name: "MyClient"
```

**`client.filename`** `string` — default: client.py

生成的客户端文件的文件名。

---

**`client.class_name`** `string` — default: null

生成的客户端类的名称。对于大多数用例，请改用顶级 `client_class_name` 选项。

---

**`client.exported_filename`** `string` — default: client.py

将在代码片段中使用的导出客户端的文件名。

---

**`client.exported_class_name`** `string` — default: null

将在代码片段中使用的导出客户端类的名称。

---

### pydantic_config

为您的 Python SDK 配置 Pydantic 模型生成设置。

```yaml
config:
  pydantic_config:
    enum_type: "literals"
    extra_fields: "forbid"
    frozen: true
    include_union_utils: false
    include_validators: true
    orm_mode: false
    positional_single_property_constructors: 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
```

**`enum_type`** `'literals' | 'forward_compatible_python_enums' | 'python_enums'` — default: literals

在生成的模型中使用的枚举类型：

* `literals`: 使用 Python Literal 类型，例如 `MyEnum = Literal["foo", "bar"]`
* `forward_compatible_python_enums`: 使用 Python Enum 类，带有 `MyEnum._UNKNOWN` 成员以实现前向兼容性。`MyEnum._UNKNOWN.value` 包含原始的未识别值。
* `python_enums`: 您的常规 Python 枚举类，在 API 中定义成员。

---

**`extra_fields`** `literal<'allow' | 'forbid' | 'ignore'>` — default: allow

如何处理模型模式中未定义的额外字段。

---

**`frozen`** `bool` — default: true

Pydantic 模型是否应该被冻结（创建后不可变）。

---

**`include_union_utils`** `bool` — default: false

启用时，生成器将输出包含访问联合实用程序的 Pydantic `__root__` 类。例如，对于以下联合类型：

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

您将获得一个具有工厂和访问者的生成 `Shape` 类：

```python
# 使用工厂实例化联合
Shape.factory.circle(Circle(...))

# 访问联合中的每个案例
shape = get_shape()
shape.visit(
  circle: lambda circle: do_something_with_circle(circle),
  triangle: lambda triangle: do_something_with_triangle(triangle),
)
```

---

**`include_validators`** `bool` — default: false

在生成的 Pydantic 模型中包含自定义验证器。

---

**`orm_mode`** `bool` — default: false

启用 Pydantic 模型的 ORM 模式以与 SQLAlchemy 等 ORM 一起工作。

---

**`positional_single_property_constructors`** `bool` — default: false

启用时，为具有单个必需字段的模型生成自定义 `__init__` 方法，允许位置参数构造而不需要关键字参数。

```python
# 没有 positional_single_property_constructors（默认）
wrapper = Wrapper(value="my_value")

# 启用 positional_single_property_constructors
wrapper = Wrapper("my_value")
```

> **Warning**
>
> 启用此选项可能会导致向后兼容性问题。如果模型稍后添加另一个必需字段，将不再生成位置 `__init__`，导致使用位置参数的现有代码出现运行时故障。使用关键字参数以获得长期稳定性。

---

**`package_name`** `string`

生成的模型的自定义包名称。

---

**`require_optional_fields`** `bool` — default: false

可选字段是否必须显式提供（不能省略）。

---

**`skip_formatting`** `bool` — default: false

跳过生成的 Pydantic 模型的代码格式化。

---

**`skip_validation`** `bool` — default: false

启用时，禁用 API 响应的 Pydantic 验证。这确保如果从 API 返回的模型与 Pydantic 模型不完全匹配，Pydantic 不会立即失败。

这旨在增加灵活性，以防您的 SDK 落后于您的 API，但应谨慎使用，因为用户的类型提示仍将完全反映 Pydantic 模型。

---

**`smart_union`** `bool` — default: true

在 Pydantic 模型中启用智能联合处理以获得更好的类型判别。

---

**`union_naming`** `'v0' | 'v1'` — default: v0

控制联合命名策略。如果您正在处理已经具有判别属性的判别联合成员（并且它们仅在一个联合中使用），您应该在 `generators.yml` 中优先选择全局 API 配置：

```yaml
- name: fern-python-sdk
  version: 3.0.0-rc0
  api:
    settings:
      unions: v1
```

---

**`use_pydantic_field_aliases`** `bool` — default: false

对于与线格式不同的属性名称使用 Pydantic 字段别名。

---

**`use_provided_defaults`** `bool` — default: false

利用 API 规范中指定的默认值。

---

**`use_typeddict_requests`** `bool` — default: false

为请求对象生成 TypedDicts 而不是 Pydantic 模型。

---

**`version`** `'v1' | 'v2' | 'both' | 'v1_on_v2'` — default: both

默认情况下，生成器生成与 pydantic v1 和 v2 兼容的 pydantic 模型。但是您可以将其覆盖为：

* `v1`: 严格使用 Pydantic v1
* `v2`: 严格使用 Pydantic v2
* `both`: 保持与两个版本的兼容性
* `v1_on_v2`: 在 v2 上使用 Pydantic v1 兼容性层

---

**`wrapped_aliases`** `bool` — default: false

为 Pydantic 模型启用包装别名。仅在 Pydantic V1、V1_ON_V2 或 V2 中支持。

---

**`use_inheritance_for_extended_models`** `bool` — default: true

当模型使用 Fern `extends` 关键字时生成实现继承的 Pydantic 模型。

---