Hướng dẫn cài đặt Poetry cho ứng dụng Django

Mục lục

1. Yêu cầu trước khi bắt đầu
2. Cài đặt Poetry
3. Cấu hình PATH
4. Thiết lập môi trường ảo trong dự án
5. Chuyển đổi hoặc khởi tạo Poetry trong dự án Django
6. Thêm Django và các gói cần thiết
7. Tạo môi trường ảo và cài đặt các phụ thuộc
8. Sử dụng môi trường ảo Poetry để chạy lệnh Django
9. Chỉ định phiên bản Python cụ thể (nếu cần)
10. Ghi chú về cam kết và quy trình làm việc
11. Triển khai và CI
12. Nâng cấp Poetry

1. Yêu cầu trước khi bắt đầu

Trước khi cài đặt Poetry, hãy chắc chắn rằng bạn đã cài đặt Python phiên bản 3.9 trở lên. Kiểm tra phiên bản Python của bạn bằng lệnh sau:

python3 --version

Nếu phiên bản của bạn không tương thích, hãy cài đặt phiên bản mới hơn từ trang chính thức của Python.

2. Cài đặt Poetry

Có hai cách an toàn để cài đặt Poetry:

Lựa chọn A — Sử dụng pipx (khuyến nghị)

Lựa chọn này sẽ giúp cô lập Poetry và dễ dàng nâng cấp hơn:

python -m pip install --user pipx
python -m pipx ensurepath  # khởi động lại shell nếu cần
pipx install poetry

Lưu ý: pipx giúp cài đặt các công cụ CLI vào các môi trường tách biệt, rất phù hợp cho các công cụ như Poetry.

Lựa chọn B — Sử dụng script cài đặt chính thức

Script này hoạt động trên Linux, macOS và Windows PowerShell:

Trên Unix / WSL / macOS:

curl -sSL https://install.python-poetry.org | python3 -

Trên Windows PowerShell:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

Sau khi cài đặt, hãy xác nhận rằng Poetry đã được cài đặt thành công:

poetry --version

3. Cấu hình PATH

Nếu lệnh poetry --version không hoạt động, hãy kiểm tra thư mục bin mà installer đã in ra (ví dụ: ~/.local/bin trên Unix hoặc %APPDATA%\Python\Scripts trên Windows). Bạn cần thêm thư mục này vào PATH của mình.

4. Thiết lập môi trường ảo trong dự án

Để mỗi dự án có môi trường ảo riêng trong thư mục dự án, bạn có thể cấu hình Poetry như sau:

poetry config virtualenvs.in-project true

Điều này sẽ khiến Poetry tạo thư mục .venv/ trong thư mục gốc của dự án khi bạn chạy lệnh poetry install. Đừng quên thêm .venv/ vào .gitignore:

echo ".venv/" >> .gitignore

5. Chuyển đổi hoặc khởi tạo Poetry trong dự án Django

Nếu bạn đã có dự án:

Từ thư mục gốc của dự án:

cd /path/to/your-django-project
poetry init

Lệnh poetry init sẽ khởi động một trình hướng dẫn tương tác để tạo file pyproject.toml. Nếu bạn muốn bỏ qua trình hướng dẫn:

poetry init --no-interaction

Nếu bạn đang bắt đầu một dự án mới:

mkdir mysite && cd mysite
poetry new --src mysite          # tùy chọn: tạo cấu trúc gói
poetry init --no-interaction

6. Thêm Django và các gói cần thiết

Cài đặt Django vào môi trường do Poetry quản lý:

poetry add django

Thêm các công cụ phát triển (ví dụ):

poetry add --group dev pytest pytest-django black isort

Nếu bạn có file requirements.txt, bạn có thể thêm từng gói một:

poetry add package1 package2

Hoặc, bạn có thể nhập chúng cùng một lúc trên Unix:

xargs -n1 poetry add < requirements.txt

Poetry sẽ tự động cập nhật pyproject.toml và poetry.lock.

7. Tạo môi trường ảo và cài đặt các phụ thuộc

Bây giờ, hãy cài đặt tất cả và tạo môi trường ảo:

poetry install

Nếu bạn chỉ muốn cài đặt các phụ thuộc (không cài đặt gói dự án ở chế độ có thể chỉnh sửa), hãy sử dụng:

poetry install --no-root

8. Sử dụng môi trường ảo Poetry để chạy lệnh Django

Có hai cách để chạy lệnh Django:

• Chạy một lệnh trong môi trường ảo của Poetry:

poetry run python manage.py migrate
poetry run python manage.py runserver

• Hoặc mở một shell trong môi trường ảo:

poetry shell
python manage.py runserver
# thoát khi hoàn thành
exit

9. Chỉ định phiên bản Python cụ thể (nếu cần)

Nếu Poetry chọn sai phiên bản Python, bạn có thể chỉ định rõ ràng phiên bản bạn muốn:

poetry env use /usr/bin/python3.11
# hoặc
poetry env use python3.11

10. Ghi chú về cam kết và quy trình làm việc

• Cam kết pyproject.toml và poetry.lock vào git (chúng thay thế requirements.txt).
• Thêm .venv/ vào .gitignore nếu sử dụng môi trường ảo trong thư mục dự án.
• Sử dụng poetry add / poetry remove để thay đổi các phụ thuộc; cam kết poetry.lock sau khi thay đổi.
• Để cập nhật file lock mà không thay đổi phiên bản, sử dụng poetry lock --no-update. Để cập nhật phụ thuộc, sử dụng poetry update package-name.

11. Triển khai và CI

Nhiều hệ thống PaaS/CI yêu cầu một file requirements.txt. Bạn có thể xuất một file từ Poetry khi cần:

poetry export --without-hashes --format=requirements.txt --output=requirements.txt

12. Nâng cấp Poetry

• Nếu bạn đã cài đặt bằng pipx: pipx upgrade poetry
• Nếu bạn sử dụng installer chính thức: poetry self update

Các mẹo và lỗi thường gặp

• Nếu poetry không được tìm thấy sau khi cài đặt, hãy thêm thư mục bin đã in ra vào PATH.
• Nếu các lệnh Django không được tìm thấy, hãy sử dụng poetry run hoặc poetry shell để sử dụng django-admin / python trong môi trường ảo.
• Nên sử dụng poetry add thay vì chỉnh sửa file pyproject.toml bằng tay để giữ cho file lock luôn nhất quán.