跳转到内容
@aws/nx-plugin
Blog

Python 项目

Python 项目生成器可用于创建配置了最佳实践的现代 Python 库或应用程序，使用 UV 进行管理，包含单一锁文件和位于 UV 工作区中的虚拟环境，使用 pytest 运行测试，以及 Ruff 进行静态分析。

使用方式

生成 Python 项目

您可以通过两种方式生成新的 Python 项目：

  1. 安装 Nx Console VSCode Plugin 如果您尚未安装
  2. 在VSCode中打开Nx控制台
  3. 点击 Generate (UI) 在"Common Nx Commands"部分
  4. 搜索 @aws/nx-plugin - py#project
  5. 填写必需参数
    • 点击 Generate

    选项

    参数 类型 默认值 描述
    name 必需 string - The name of the Python project
    directory string packages Parent directory where the project is placed.
    projectType 必需 string application Project type
    moduleName string - Python module name

    生成器输出

    生成器将在 <directory>/<name> 目录下创建以下项目结构：

    • 文件夹<模块名称>
      • __init__.py 模块初始化文件
      • hello.py Python 示例源文件
    • 文件夹tests
      • __init__.py 模块初始化文件
      • conftest.py 测试配置
      • test_hello.py 示例测试
    • project.json 项目配置和构建目标
    • pyproject.toml UV 使用的包管理配置文件
    • .python-version 包含项目的 Python 版本

    您可能还会注意到工作区根目录中创建/更新了以下文件：

    • pyproject.toml UV 的工作区级包管理配置
    • .python-version 包含工作区 Python 版本
    • uv.lock Python 依赖锁文件

    编写 Python 源代码

    在 <模块名称> 目录中添加您的 Python 源代码。

    在其他项目中导入库代码

    由于已配置 UV 工作区，您可以从工作区中的任何其他 Python 项目引用您的 Python 项目：

    packages/my_other_project/my_other_project/main.py
    from "my_library.hello" import say_hello

    上述代码中，my_library 是模块名称，hello 对应 Python 源文件 hello.py，say_hello 是 hello.py 中定义的方法

    依赖管理

    要为项目添加依赖，可以在 Python 项目中运行 add 目标，例如：

    Terminal window
    pnpm nx run my_scope.my_library:add some-pip-package

    这会将依赖添加到项目的 pyproject.toml 文件，并更新根目录的 uv.lock。

    运行时代码

    当将 Python 项目作为运行时代码使用时（例如作为 AWS lambda 函数的处理程序），需要将源代码及其所有依赖打包。可以通过在 project.json 文件中添加如下目标实现：

    project.json
    {
      ...
      "targets": {
        ...
        "bundle": {
          "cache": true,
          "executor": "nx:run-commands",
          "outputs": ["{workspaceRoot}/dist/packages/my_library/bundle"],
          "options": {
            "commands": [
              "uv export --frozen --no-dev --no-editable --project my_library -o dist/packages/my_library/bundle/requirements.txt",
              "uv pip install -n --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux2014 --python `uv python pin` --target dist/packages/my_library/bundle -r dist/packages/my_library/bundle/requirements.txt"
            ],
            "parallel": false
          },
          "dependsOn": ["compile"]
        },
      },
    }

    构建

    Python 项目配置了 build 目标（定义于 project.json），可通过以下命令运行：

    Terminal window
    pnpm nx run <project-name>:build

    其中 <project-name> 是项目的全限定名称。

    build 目标将执行编译、代码检查及测试。

    构建输出位于工作区根目录的 dist 文件夹中，具体路径为 dist/packages/<my-library>/build

    测试

    项目使用 pytest 进行测试。

    编写测试

    测试应位于项目的 test 目录中，文件名以 test_ 开头，例如：

    • 文件夹my_library
      • hello.py
    • 文件夹test
      • test_hello.py hello.py 的测试

    测试方法应以 test_ 开头，并通过断言验证预期结果，例如：

    test/test_hello.py
    from my_library.hello import say_hello
    

    def test_say_hello():
      assert say_hello("Darth Vader") == "Hello, Darth Vader!"

    有关编写测试的更多细节，请参考 pytest 文档。

    运行测试

    测试会在项目 build 目标中自动运行，但也可单独运行 test 目标：

    Terminal window
    pnpm nx run <project-name>:test

    可以使用 -k 标志运行单个测试或测试套件，指定测试文件或方法名称：

    Terminal window
    pnpm nx run <project-name>:test -k 'test_say_hello'

    代码检查

    Python 项目使用 Ruff 进行代码检查。

    运行检查器

    要检查项目代码，可运行 lint 目标：

    Terminal window
    pnpm nx run <project-name>:lint

    修复检查问题

    大多数代码检查或格式问题可以自动修复。通过添加 --configuration=fix 参数可让 Ruff 自动修复问题：

    Terminal window
    pnpm nx run <project-name>:lint --configuration=fix

    若要修复工作区中所有包的检查问题，可运行：

    Terminal window
    pnpm nx run-many --target lint --all --configuration=fix