跳转到内容

Python 项目

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

您可以通过两种方式生成新的 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 源代码添加到 <模块名称> 目录中。

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

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

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

    要为项目添加依赖,可以运行项目的 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 packages/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"]
    },
    },
    }

    项目已配置 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 文档

    测试会在项目构建时自动执行,也可通过 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 参数可自动修复:

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

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

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