使用 Poetry 管理 Django 專案：完整指南

更新日期： 2024 年 11 月 26 日

在 Django 開發中，Poetry 是一個現代化的依賴管理工具，提供了更高效的方式來管理虛擬環境和專案依賴。

以下將逐步介紹如何使用 Poetry 初始化專案、安裝依賴、編寫 README 文件，以及簡化日常操作的實用技巧。

為什麼選擇 Poetry？

Poetry 提供以下優勢：

1. 高效依賴管理：
   • 使用 pyproject.toml 和 poetry.lock 記錄專案依賴，避免版本衝突。
2. 簡化虛擬環境操作：
   • 一鍵啟動虛擬環境，支持直接執行命令。
3. 團隊協作友好：
   • 確保專案環境的一致性，減少配置成本。

初始化 Django 專案

初始化 Poetry 專案

使用以下指令初始化專案：

poetry init -n

生成的文件：

• pyproject.toml：記錄專案名稱、作者及依賴等資訊。

[tool.poetry]
name = "my-django-project"
version = "0.1.0"
description = "A Django project managed with Poetry"
authors = ["Your Name <youremail@example.com>"]

2.2 建立虛擬環境並安裝 Django

1. 啟動虛擬環境：
   • 類似於 source venv/bin/activate。

poetry shell

1. 安裝 Django：

poetry add django

1. 安裝所有依賴：
   • 若專案中已有 pyproject.toml 或 poetry.lock 文件，該指令會根據這些文件安裝所需套件。

 poetry install

使用 Poetry 操作虛擬環境

當你關閉終端機或重新打開時，虛擬環境會斷開。

以下是常用操作方式：

再次進入虛擬環境

使用以下指令進入虛擬環境：

poetry shell

單次執行指令

如果不想長時間駐留在虛擬環境內，可以直接使用 poetry run 執行單次指令：

poetry run python manage.py runserver

• 適用於啟動伺服器、資料遷移等操作。

使用 Makefile 簡化操作（Linux 系統）

poetry run 指令較長，可以使用 Makefile 優化操作。

建立 Makefile

在專案根目錄創建 Makefile 文件，並添加以下內容：

runserver:
	poetry run python manage.py runserver

migrate:
	poetry run python manage.py makemigrations
	poetry run python manage.py migrate

使用簡化指令

• 啟動伺服器：

make runserver

• 執行資料遷移：

make migrate

編寫 README 文件

在建立專案時，建議同時編寫 README.md 文件，記錄專案的基本操作步驟及環境需求。

README.md 範例

# My Django Project

## 環境要求
- Python 3.10+
- Poetry 1.3+

## 安裝步驟
1. **複製專案**：
   ```bash
   git clone https://github.com/your-repo.git
   cd your-repo

小結

使用 Poetry 管理 Django 專案提供了以下優勢：

1. 高效的依賴管理
   • Poetry 自動處理依賴套件，無需手動維護 requirements.txt 文件，減少版本衝突的風險。
2. 靈活的虛擬環境切換
   • 提供兩種使用方式：
     • poetry shell：進入虛擬環境。
     • poetry run：直接執行單次指令，無需手動進入環境。
3. 團隊協作友好
   • 透過 pyproject.toml 和 poetry.lock 文件，確保所有團隊成員的開發環境一致，減少因版本差異導致的問題。
4. 簡化操作
   • 在 Linux 系統中，利用 Makefile 定義常用指令（如啟動伺服器、資料遷移），顯著提升日常開發效率。