Python 配置

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

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

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

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

1
from my_package import validate_token, format_currency, PhoneValidator

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

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

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

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

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

启用时，生成模拟服务器（wire）测试来验证 SDK 是否按预期发送和接收 HTTP 请求。

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

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

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

1
config:
2
  extra_dependencies:
3
    boto3: 1.28.15

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

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

自定义 extras 在生成时与内置的 aiohttp extra 合并，因此声明您自己的 extras 不会覆盖它。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1
# 使用工厂实例化联合
2
Shape.factory.circle(Circle(...))
3
4
# 访问联合中的每个案例
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
)

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

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

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

1
# 没有 positional_single_property_constructors（默认）
2
wrapper = Wrapper(value="my_value")
3
4
# 启用 positional_single_property_constructors
5
wrapper = Wrapper("my_value")

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

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

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

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

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

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

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

1
- name: fernapi/fern-python-sdk
2
  version: 3.0.0-rc0
3
  api:
4
    settings:
5
      unions: v1

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

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

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

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

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

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

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