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, Ruff để phân tích tĩnh, và ty để kiểm tra kiểu.

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:

Chạy generator này@aws/nx-plugin:py#project

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

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

Xây dựng lệnh của bạn6

nameBắt buộc

typeBắt buộc

applicationlibrary

directory

subDirectory

moduleName

preferInstallDependencies

true

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

Tùy chọn

Tùy chọn của generator6 tùy chọn

nameBắt buộcstring

Tên của dự án Python

typeBắt buộcenumMặc định: application

Dự án là ứng dụng hay thư viện

applicationlibrary

directorystringMặc định: packages

Thư mục cha nơi dự án được đặt.

subDirectorystring

Thư mục con mà dự án được đặt trong đó. Mặc định đây là tên dự án.

moduleNamestring

Tên module Python

preferInstallDependenciesbooleanMặc định: true

Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator cùng lúc (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

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 Module initialisation
• Thư mụctests

  • __init__.py Module initialisation
  • conftest.py Test configuration
  • test_noop.py Placeholder test
• project.json Project configuration and build targets
• pyproject.toml Packaging configuration file used by UV
• .python-version Contains the project’s Python version

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

• pyproject.toml Workspace level packaging configuration for UV
• .python-version Contains the workspace Python version
• uv.lock Lockfile for Python dependencies

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 một dependency 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 mỗi cái 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ả dependant và dependee. 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 dependency vào, nhưng phải đầy đủ tên của dự án cần phụ thuộc.

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

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 lib, my_module tương ứng với một tệp mã nguồn Python my_module.py, và my_function là một phương thức được định nghĩa trong tệp đó.

Dependencies

Để thêm dependencies vào dự án của bạn, bạn có thể chạy target add trong dự án Python của bạn, 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 dependency vào tệp pyproject.toml của dự án của bạ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 bạn 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 dependencies của nó. Các trình tạo py#lambda-function, py#api và py#mcp-server thêm điều này cho bạn. Để thêm một cách thủ công, hãy thêm các target như sau vào tệp project.json của bạn, khớp với hình dạng mà các trình tạo đó cung cấp:

project.json

{
  "targets": {
    "bundle": {
      "dependsOn": ["bundle-x86"]
    },
    "bundle-x86": {
      "cache": true,
      "inputs": ["production", "^production"],
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle-x86"],
      "options": {
        "commands": [
          "uv export --frozen --no-dev --no-editable --project {projectRoot} --package my_scope.my_library -o dist/{projectRoot}/bundle-x86/requirements.txt",
          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux_2_28 --python-version 3.14 --target dist/{projectRoot}/bundle-x86 -r dist/{projectRoot}/bundle-x86/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    }
  }
}

Cài đặt

Cài đặt các dependencies Python bằng lệnh sau:

uv sync

Xây dựng

Dự án Python của bạn được cấu hình với một 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, kiểm tra và kiểm tra kiểu cho dự án của bạn.

Kết quả xây dựng có thể được tìm thấy trong thư mục dist ở thư mục 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

Để xây dựng 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

Assembling

Dự án của bạn cũng có một target assemble, tạo ra bất cứ thứ gì mà dự án của bạn đóng góp cho một deployment (ví dụ như kết quả đã biên dịch hoặc đã bundle), mà không chạy các cổng kiểm tra lint, test hoặc type-check.

pnpm

pnpm nx assemble <project-name>

yarn

yarn nx assemble <project-name>

npm

npx nx assemble <project-name>

bun

bunx nx assemble <project-name>

Các target deploy phụ thuộc vào assemble, vì vậy việc deploy chỉ xây dựng những gì nó sắp deploy.

Sử dụng build trong pipeline của bạn

assemble được sử dụng để lặp lại nhanh hơn trong quá trình phát triển. Chạy build trong pipeline CI của bạn để đảm bảo dự án của bạn vượt qua các cổng chất lượng trước khi triển khai production.

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 tests 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 Tests for 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 khẳng định để 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 bộ 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'

Tệp Kiểm tra và Bộ nhớ đệm

Thư mục tests của dự án của bạn được loại trừ khỏi named input production trong nx.json.

Các target có đầu ra không thể chứa tệp kiểm tra - chẳng hạn như compile và bất kỳ target bundle nào - đọc production thay vì default, vì vậy việc chỉnh sửa một bài kiểm tra không làm vô hiệu hóa chúng hoặc bất kỳ tác vụ nào trong một dự án phụ thuộc vào dự án của bạn.

Việc loại trừ được giới hạn có chủ ý trong thư mục tests. Một tệp test_*.py bên trong thư mục package của bạn được coi là mã production, vì nó được đóng gói vào bản phân phối đã xây dựng của bạn, và do đó vẫn làm vô hiệu hóa bản build.

Các target test, lint, format và typecheck đọc default và do đó vẫn chạy lại khi bạn chỉnh sửa một bài kiểm tra. Lưu ý rằng typecheck cũng kiểm tra kiểu cho các bài kiểm tra của bạn, vì vậy lỗi kiểu trong một bài kiểm tra vẫn được báo cáo.

Kiểm tra Kiểu

Các dự án Python sử dụng ty để kiểm tra kiểu.

Chạy Trình Kiểm tra Kiểu

Kiểm tra kiểu 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 nó riêng biệt thông qua target typecheck:

pnpm

pnpm nx run <project-name>:typecheck

yarn

yarn nx run <project-name>:typecheck

npm

npx nx run <project-name>:typecheck

bun

bunx nx run <project-name>:typecheck

Loại bỏ Lỗi Kiểu

Để loại bỏ một chẩn đoán cụ thể cho một dòng duy nhất, thêm một comment # ty: ignore[<rule>] ở cuối dòng, ví dụ:

value: int = "not an int"  # ty: ignore[invalid-assignment]

Để cấu hình hành vi kiểm tra kiểu trên toàn dự án của bạn, thêm một phần [tool.ty] vào pyproject.toml của dự án của bạn. Tham khảo tài liệu tham khảo cấu hình ty để biết các tùy chọn có sẵn.

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 bạn, 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 của bạn:

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 bạn), bạn có thể chạy một bản 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 bản 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 của bạn:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint