Dự án Python

Trình tạo dự án Python có thể được sử dụng để tạo một thư viện hoặc ứng dụng Python hiện đại được cấu hình với các phương pháp hay nhất, được quản lý bằng UV, một lockfile và môi trường ảo duy nhất trong UV workspace, pytest để chạy các bài kiểm tra, và Ruff để phân tích tĩnh.

Cách sử dụng

Tạo một Dự án Python

Bạn có thể tạo một dự án Python mới theo hai cách:

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - py#project
5. Điền các tham số bắt buộc
6. Nhấp 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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
name Bắt buộc	string	-	Tên của dự án Python
directory	string	packages	Thư mục cha nơi dự án được đặt.
subDirectory	string	-	Thư mục con mà dự án được đặt trong đó. Mặc định đây là tên dự án.
projectType Bắt buộc	string	application	Dự án là ứng dụng hay thư viện
moduleName	string	-	Tên module Python

Kết quả của Trình tạo

Trình tạo sẽ tạo cấu trúc dự án sau trong thư mục <directory>/<name>:

• Thư mục<module-name>

  • __init__.py Khởi tạo module
• Thư mụctests

  • __init__.py Khởi tạo module
  • conftest.py Cấu hình kiểm tra
  • test_noop.py Bài kiểm tra placeholder
• project.json Cấu hình dự án và các target build
• pyproject.toml Tệp cấu hình đóng gói được sử dụng bởi UV
• .python-version Chứa phiên bản Python của dự án

Bạn cũng có thể nhận thấy các tệp sau được tạo/cập nhật trong thư mục gốc của workspace:

• pyproject.toml Cấu hình đóng gói cấp workspace cho UV
• .python-version Chứa phiên bản Python của workspace
• uv.lock Lockfile cho các phụ thuộc Python

Viết Mã nguồn Python

Thêm mã nguồn Python của bạn vào thư mục <module-name>.

Import Mã Thư viện của bạn trong Các Dự án Khác

Sử dụng target add để thêm phụ thuộc vào một dự án Python.

Giả sử chúng ta đã tạo hai dự án python, my_app và my_lib. Chúng sẽ có tên dự án đầy đủ là my_scope.my_app và my_scope.my_lib, và theo mặc định sẽ có tên module là my_scope_my_app và my_scope_my_lib.

Để my_app phụ thuộc vào my_lib, chúng ta có thể chạy lệnh sau:

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

Tên đầy đủ

Chúng ta sử dụng tên dự án đầy đủ cho cả dự án phụ thuộc và dự án được phụ thuộc. Chúng ta có thể sử dụng cú pháp viết tắt cho dự án mà chúng ta muốn thêm phụ thuộc, nhưng phải viết đầy đủ tên của dự án cần phụ thuộc vào.

Sau đó bạn có thể import mã thư viện của mình:

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.my_module import my_function

Ở trên, my_scope_my_lib là tên module cho thư viện, my_module tương ứng với tệp nguồn Python my_module.py, và my_function là một phương thức được định nghĩa trong tệp đó.

Phụ thuộc

Để thêm phụ thuộc vào dự án của bạn, bạn có thể chạy target add trong dự án Python của mình, ví dụ:

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

Điều này sẽ thêm phụ thuộc vào tệp pyproject.toml của dự án và cập nhật uv.lock ở thư mục gốc.

Mã Runtime

Khi bạn sử dụng dự án Python của mình làm mã runtime (ví dụ như handler cho một hàm AWS lambda), bạn sẽ cần tạo một bundle của mã nguồn và tất cả các phụ thuộc của nó. Bạn có thể đạt được điều này bằng cách thêm một target như sau vào tệp project.json của bạn:

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"]
    },
  },
}

Build

Dự án Python của bạn được cấu hình với target build (được định nghĩa trong project.json), mà bạn có thể chạy thông qua:

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Trong đó <project-name> là tên đầy đủ của dự án của bạn.

Target build sẽ biên dịch, lint và kiểm tra dự án của bạn.

Kết quả build có thể được tìm thấy trong thư mục dist gốc trong workspace của bạn, bên trong một thư mục cho package và target của bạn, ví dụ dist/packages/<my-library>/build

Để build tất cả các dự án trong workspace của bạn, chạy:

pnpm

pnpm nx run-many --target build

yarn

yarn nx run-many --target build

npm

npx nx run-many --target build

bun

bunx nx run-many --target build

Hoặc sử dụng lệnh viết tắt:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Kiểm tra

pytest được cấu hình để kiểm tra dự án của bạn.

Viết Các Bài Kiểm tra

Các bài kiểm tra nên được viết trong thư mục test trong dự án của bạn, trong các tệp python có tiền tố test_, ví dụ:

• Thư mụcmy_library

  • my_module.py
• Thư mụctests

  • test_my_module.py Các bài kiểm tra cho my_module.py

Các bài kiểm tra là các phương thức bắt đầu bằng test_ và thực hiện các assertion để xác minh kỳ vọng, ví dụ:

tests/test_my_module.py

from my_library.my_module import say_hello

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

Để biết thêm chi tiết về cách viết các bài kiểm tra, vui lòng tham khảo tài liệu pytest.

Chạy Các Bài Kiểm tra

Các bài kiểm tra sẽ chạy như một phần của target build cho dự án của bạn, nhưng bạn cũng có thể chạy chúng riêng biệt bằng cách chạy target test:

pnpm

pnpm nx test <project-name>

yarn

yarn nx test <project-name>

npm

npx nx test <project-name>

bun

bunx nx test <project-name>

Bạn có thể chạy một bài kiểm tra riêng lẻ hoặc một nhóm bài kiểm tra bằng cách sử dụng cờ -k, chỉ định tên của tệp kiểm tra hoặc phương thức:

pnpm

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

yarn

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

npm

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

bun

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

Linting

Các dự án Python sử dụng Ruff để linting.

Chạy Linter

Để gọi linter để kiểm tra dự án của bạn, bạn có thể chạy target lint.

pnpm

pnpm nx lint <project-name>

yarn

yarn nx lint <project-name>

npm

npx nx lint <project-name>

bun

bunx nx lint <project-name>

Sửa Các Vấn đề Lint

Phần lớn các vấn đề linting hoặc formatting có thể được sửa tự động. Bạn có thể yêu cầu Ruff sửa các vấn đề lint bằng cách chạy với tham số --configuration=fix.

pnpm

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

yarn

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

npm

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

bun

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

Tương tự, nếu bạn muốn sửa tất cả các vấn đề lint trong tất cả các package trong workspace của mình, bạn có thể chạy:

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

Lệnh viết tắt

Điều này có một lệnh viết tắt từ thư mục gốc của workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Bỏ qua Các Vấn đề Lint

Để tránh các vấn đề linting làm chậm bạn trong quá trình phát triển (đặc biệt nếu bạn có các vấn đề không thể tự động sửa trong dự án của mình), bạn có thể chạy build với cấu hình skip-lint:

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

Điều này vẫn sẽ chạy Ruff như một phần của build, nhưng target lint sẽ luôn được coi là thành công.

Lệnh viết tắt

Điều này có một lệnh viết tắt từ thư mục gốc của workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint