Python 项目

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

使用方法

生成 Python 项目

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

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#project

yarn

yarn nx g @aws/nx-plugin:py#project

npm

npx nx g @aws/nx-plugin:py#project

bun

bunx nx g @aws/nx-plugin:py#project

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:py#project --dry-run

yarn

yarn nx g @aws/nx-plugin:py#project --dry-run

npm

npx nx g @aws/nx-plugin:py#project --dry-run

bun

bunx nx g @aws/nx-plugin:py#project --dry-run

选项

参数	类型	默认值	描述
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> 目录中创建以下项目结构：

• 文件夹<module-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 源代码

在 <module-name> 目录中添加您的 Python 源代码。

在其他项目中导入库代码

使用 add 目标为 Python 项目添加依赖。

假设我们创建了两个 Python 项目 my_app 和 my_lib。它们的完全限定项目名称分别为 my_scope.my_app 和 my_scope.my_lib，默认模块名分别为 my_scope_my_app 和 my_scope_my_lib。

要让 my_app 依赖 my_lib，可以运行以下命令：

pnpm

pnpm nx run my_scope.my_app:add my_scope.my_lib

yarn

yarn nx run my_scope.my_app:add my_scope.my_lib

npm

npx nx run my_scope.my_app:add my_scope.my_lib

bun

bunx nx run my_scope.my_app:add my_scope.my_lib

注意

我们使用完全限定的项目名称来指定依赖方和被依赖方。对于要添加依赖的项目可以使用简写语法，但被依赖的项目必须使用完全限定名称。

然后即可导入库代码：

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.hello import say_hello

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

依赖管理

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

pnpm

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

yarn

yarn nx run my_scope.my_library:add some-pip-package

npm

npx nx run my_scope.my_library:add some-pip-package

bun

bunx 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 packages/my_library --package my_scope.my_library -o dist/packages/my_library/bundle/requirements.txt",
          "uv pip install -n --no-deps --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 中），可通过以下命令运行：

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx nx run <project-name>:build

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

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

构建输出位于工作区根目录的 dist 文件夹中，在对应包的目录下，例如 dist/packages/<my-library>/build

测试

项目使用 pytest 进行测试。

编写测试

测试应写在项目的 test 目录中，使用 test_ 前缀的 Python 文件，例如：

• 文件夹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 目标单独运行：

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

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

pnpm

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

yarn

yarn nx run <project-name>:test -k 'test_say_hello'

npm

npx nx run <project-name>:test -k 'test_say_hello'

bun

bunx nx run <project-name>:test -k 'test_say_hello'

代码检查

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

运行检查

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

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

修复问题

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

pnpm

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

yarn

yarn nx run <project-name>:lint --configuration=fix

npm

npx nx run <project-name>:lint --configuration=fix

bun

bunx nx run <project-name>:lint --configuration=fix

如果要修复工作区中所有包的代码问题，可以运行：

pnpm

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

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix