跳到导航
生成器Go

发布到 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
groups: 
  python-sdk:
    generators:
      - name: fern-python-sdk
        version: 5.41.10
        output:
          location: pypi
2

添加唯一的包名称

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

generators.yml
groups: 
  python-sdk:
    generators:
      - name: fern-python-sdk
        version: 5.41.10
        output:
          location: pypi
          package-name: your-package-name
3

配置 client-class-name

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

generators.yml
groups: 
  python-sdk:
    generators:
      - name: fern-python-sdk
        version: 5.41.10
        output:
          location: pypi
          package-name: your-package-name
        config:
          client_class_name: YourClientName # 必须是 PascalCase
4

添加 PyPI 元数据（可选）

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

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

generators.yml
groups: 
  python-sdk:
    generators:
      - name: fern-python-sdk
        version: 5.41.10
        output:
          location: pypi
          package-name: your-package-name
          metadata: # 发布元数据
            keywords: ["api", "sdk", "client"]
            documentation-link: "https://docs.yourcompany.com"
            homepage-link: "https://yourcompany.com"
        metadata: # 常规 SDK 元数据
          license: MIT
        config:
          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
groups: 
  python-sdk:
    generators:
      - name: fern-python-sdk
        version: 5.41.10
        output:
          location: pypi
          package-name: your-package-name
        config:
          client_class_name: YourClientName
        github: 
          repository: your-org/company-python
2

配置 PyPI 身份验证令牌

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

generators.yml
groups: 
  python-sdk:
    generators:
      - name: fern-python-sdk
        version: 5.41.10
        output:
          location: pypi
          package-name: your-package-name
          token: ${PYPI_TOKEN}
        config:
          client_class_name: YourClientName
        github: 
          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 the default branch (or the branch you specify), 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 output.github reference for more information.

generators.yml
groups: 
  python-sdk:
	generators:
	  - name: fern-python-sdk
		version: 5.41.10
		output:
		  location: npm
		  package-name: name-of-your-package
		  token: ${PYPI_TOKEN}
		config:
		  namespaceExport: YourClientName
		github: 
		  repository: your-org/your-repository
		  mode: push
		  branch: your-branch-name # mode: push 时必需

发布您的 SDK

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

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

1

将 PYPI_TOKEN 添加为 GitHub Actions 密钥

  1. 在 GitHub 上打开您的代码库，进入设置。
  2. 导航到密钥和变量 > Actions。
  3. 点击新建代码库密钥。
  4. 将密钥命名为 PYPI_TOKEN，并粘贴您的 PyPI 令牌。
  5. 点击添加密钥。
PYPI_TOKEN 密钥
2

为您的 Fern 令牌添加密钥

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

设置新工作流程

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

.github/workflows/publish.yml
name: Publish Python SDK
on:
  workflow_dispatch:
    inputs:
      version:
        description: "您想要发布的 Python SDK 版本"
        required: true
        type: string
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install Fern CLI
        run: npm install -g fern-api
      - name: Release Python SDK
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
        run: |
          fern generate --group python-sdk --version ${{ inputs.version }} --log-level debug
4

重新生成和发布您的 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 并导航到您的项目来查看您的新发布。