参考Python

发布到 PyPI

以 Markdown 格式查看

将您面向公众的 Fern Python SDK 发布到 PyPI 注册表。按照本页面的步骤操作后，您将在 PyPI 上发布一个版本化的包。

发布在 PyPI 上的版本化包

本页面假设您已具备：

  • 已初始化的 fern 文件夹、Python SDK 的 GitHub 代码库，以及 generators.yml 中的 Python 生成器组。参见 生成 SDK (Python)。

配置 SDK 包设置

您需要更新 generators.yml 文件来配置包名称、输出位置和客户端命名以用于 PyPI 发布。您的 generators.yml 应位于您的源代码库中（或本地机器上），而不是包含 Python SDK 代码的代码库中。

1

配置 output 位置

在 Python SDK 的 group 中，将输出位置从 local-file-system（默认值）更改为 pypi，以指示 Fern 应直接将您的包发布到 PyPI 注册表：

generators.yml
1groups: 
2  python-sdk:
3    generators:
4      - name: fernapi/fern-python-sdk
5        version: 5.9.1
6        output:
7          location: pypi
2

添加唯一的包名称

您的包名称在 PyPI 代码库中必须是唯一的，否则将您的 SDK 发布到 PyPI 将失败。

generators.yml
1groups: 
2  python-sdk:
3    generators:
4      - name: fernapi/fern-python-sdk
5        version: 5.9.1
6        output:
7          location: pypi
8          package-name: your-package-name
3

配置 client-class-name

client-class-name 选项控制生成的客户端的名称。这是客户使用的导入 SDK 的名称（import { your-client-name } from 'your-package-name';）。

generators.yml
1groups: 
2  python-sdk:
3    generators:
4      - name: fernapi/fern-python-sdk
5        version: 5.9.1
6        output:
7          location: pypi
8          package-name: your-package-name
9        config:
10          client_class_name: YourClientName # 必须是 PascalCase
4

添加 PyPI 元数据（可选）

您可以为您的 PyPI 包添加发布元数据，以提高可发现性并向用户提供额外信息。此元数据显示在您包的 PyPI 页面上，包括用于 PyPI 搜索和发现的 keywords、用于包文档的 documentation-link 以及用于项目主页的 homepage-link。

您还可以在单个 SDK 级别或全局为所有 SDK 添加 SDK 的常规元数据（描述、联系邮箱、作者、许可证等）。

generators.yml
1groups: 
2  python-sdk:
3    generators:
4      - name: fernapi/fern-python-sdk
5        version: 5.9.1
6        output:
7          location: pypi
8          package-name: your-package-name
9          metadata: # 发布元数据
10            keywords: ["api", "sdk", "client"]
11            documentation-link: "https://docs.yourcompany.com"
12            homepage-link: "https://yourcompany.com"
13        metadata: # 常规 SDK 元数据
14          license: MIT
15        config:
16          client_class_name: YourClientName

生成 PyPI 令牌

1

登录 PyPI

登录 PyPI 或创建新账户。

2

导航到账户设置

  1. 点击您的个人资料图片。
  2. 选择账户设置。
  3. 向下滚动到 API 令牌。
3

添加新令牌

  1. 点击 Add API Token
  2. 为您的令牌命名并将范围设置为相关项目。
  3. 点击 Create token
创建新的 API 令牌
保存您的新令牌 — 离开页面后将不会再显示。

配置 PyPI 发布

1

添加代码库位置

在 generators.yml 中添加您的 GitHub 代码库路径：

generators.yml
1groups: 
2  python-sdk:
3    generators:
4      - name: fernapi/fern-python-sdk
5        version: 5.9.1
6        output:
7          location: pypi
8          package-name: your-package-name
9        config:
10          client_class_name: YourClientName
11        github: 
12          repository: your-org/company-python
2

配置 PyPI 身份验证令牌

在 generators.yml 中添加 token: ${PYPI_TOKEN}。

generators.yml
1groups: 
2  python-sdk:
3    generators:
4      - name: fernapi/fern-python-sdk
5        version: 5.9.1
6        output:
7          location: pypi
8          package-name: your-package-name
9          token: ${PYPI_TOKEN}
10        config:
11          client_class_name: YourClientName
12        github: 
13          repository: your-org/company-python
3

选择您的发布模式

Optionally set the mode to control how Fern handles SDK publishing:

  • mode: release (default): Fern generates code, commits to main, and tags a release automatically
  • mode: pull-request (recommended): Fern generates code and creates a PR for you to review before release
  • mode: push: Fern generates code and pushes to a branch you specify for you to review before release

You can also configure other settings, like the reviewers or license. Refer to the full github (generators.yml) reference for more information.

generators.yml
1groups: 
2  python-sdk:
3	generators:
4	  - name: fernapi/fern-python-sdk
5		version: 5.9.1
6		output:
7		  location: npm
8		  package-name: name-of-your-package
9		  token: ${PYPI_TOKEN}
10		config:
11		  namespaceExport: YourClientName
12		github: 
13		  repository: your-org/your-repository
14		  mode: push
15		  branch: your-branch-name # mode: push 时必需

发布您的 SDK

决定您希望如何将 SDK 发布到 PyPI。您可以使用 GitHub 工作流程进行自动化发布，或直接通过 CLI 发布。

通过 GitHub Actions 设置发布工作流程，这样您可以直接从源代码库触发新的 SDK 发布。

1

设置身份验证

在 GitHub 中打开您的 Fern 代码库。点击代码库中的设置选项卡。然后，在安全部分下，打开密钥和变量 > Actions。

添加 GitHub 代码库密钥

您也可以使用 URL https://github.com/<your-repo>/settings/secrets/actions。

2

为您的 PyPI 令牌添加密钥

  1. 选择新建代码库密钥。
  2. 将密钥命名为 PYPI_TOKEN。
  3. 添加您在上面生成的相应令牌。
  4. 点击添加密钥。
PYPI_TOKEN 密钥
3

为您的 Fern 令牌添加密钥

  1. 选择新建代码库密钥。
  2. 将密钥命名为 FERN_TOKEN。
  3. 添加您的 Fern 令牌。如果您还没有，请通过运行 fern token 生成一个。默认情况下，fern_token 为 fern.config.json 中列出的组织生成。
  4. 点击添加密钥。
4

设置新工作流程

设置一个可以从 GitHub UI 手动触发的 CI 工作流程。在您的代码库中，导航到 Actions。选择新建工作流程，然后自己设置工作流程。添加类似于这样的工作流程：

.github/workflows/publish.yml
1name: Publish Python SDK
2
3on:
4  workflow_dispatch:
5    inputs:
6      version:
7        description: "您想要发布的 Python SDK 版本"
8        required: true
9        type: string
10
11jobs:
12  release:
13    runs-on: ubuntu-latest
14    steps:
15      - name: Checkout repo
16        uses: actions/checkout@v4
17
18      - name: Install Fern CLI
19        run: npm install -g fern-api
20
21      - name: Release Python SDK
22        env:
23          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
24          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
25        run: |
26          fern generate --group python-sdk --version ${{ inputs.version }} --log-level debug
5

重新生成和发布您的 SDK

导航到 Actions 选项卡，选择您刚创建的工作流程，指定版本号，然后点击运行工作流程。这将重新生成您的 SDK。

运行 Python 发布工作流程

The rest of the release process depends on your chosen mode:

  • Release mode (default): If you didn’t specify a mode or set mode: release, no further action is required. Fern automatically tags the new release with your specified version number and initiates the publishing workflow in your SDK repository.

  • Pull request or push mode: If you set mode: pull-request or mode: push, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (pull-request) or branch (push), then tag a new release to initiate the publishing workflow in your SDK repository.

工作流程完成后，您可以通过登录 PyPI 并导航到您的项目来查看您的新发布。

1

设置 PyPI 环境变量

在您的本地机器上设置 PYPI_TOKEN 环境变量：

$export PYPI_TOKEN=your-actual-pypi-token
2

重新生成和发布您的 SDK

重新生成您的 SDK，指定版本：

$fern generate --group python-sdk --version <version>

The rest of the release process depends on your chosen mode:

  • Release mode (default): If you didn’t specify a mode or set mode: release, no further action is required. Fern automatically tags the new release with your specified version number and initiates the publishing workflow in your SDK repository.

  • Pull request or push mode: If you set mode: pull-request or mode: push, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (pull-request) or branch (push), then tag a new release to initiate the publishing workflow in your SDK repository.

工作流程完成后，您可以通过登录 PyPI 并导航到您的项目来查看您的新发布。