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:

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

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

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.
type Bắt buộc	application | library	application	Dự án là ứng dụng hay thư viện
moduleName	string	-	Tên module Python
preferInstallDependencies	boolean	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ó. 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-manylinux_2_28 --python `uv python pin` --target dist/packages/my_library/bundle -r dist/packages/my_library/bundle/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    },
  },
}

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

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 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'

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