Cấu trúc dự án Python chuẩn: src layout, pyproject, lệnh CLI
Tổ chức dự án Python như người đi làm: src layout, tests, pyproject.toml, project.scripts tạo lệnh, cài editable và build wheel.
Học xong bài này, bạn sẽ
- Tổ chức dự án theo src layout
- Khai báo dự án, phụ thuộc, lệnh chạy trong pyproject.toml
- Cài dự án ở chế độ editable và chạy như một lệnh
Nên học trước: Debug: breakpoint, VS Code và pdb
Nội dung bài viết
Đến giờ dự án của bạn là vài file .py nằm chung một thư mục, chạy bằng python main.py. Dự án thật cần nhiều hơn: tách mã nguồn khỏi test, khai báo thư viện phụ thuộc, có lệnh chạy riêng, cài được vào máy khác. Bài cuối chặng 6 gom mọi công cụ đã học thành một cấu trúc dự án chuẩn, thứ bạn sẽ thấy ở hầu hết dự án Python chuyên nghiệp.
1. src layout
chi-tieu/
├── .gitignore
├── .pre-commit-config.yaml
├── .python-version
├── pyproject.toml ← khai báo mọi thứ của dự án
├── uv.lock
├── README.md
├── src/
│ └── chi_tieu/ ← package (tên dùng gạch dưới)
│ ├── __init__.py
│ ├── __main__.py ← cho phép chạy: python -m chi_tieu
│ ├── cli.py ← giao diện dòng lệnh (input, print)
│ ├── luu_tru.py ← đọc ghi JSON
│ └── xu_ly.py ← logic thuần: tính tổng, báo cáo
└── tests/
├── conftest.py
├── test_xu_ly.py
└── test_luu_tru.py
Vì sao đặt package trong src/ thay vì ngay thư mục gốc? Với layout phẳng, khi chạy test từ thư mục gốc, Python import thẳng file trong thư mục hiện tại, nên test vẫn đạt dù package cài đặt bị thiếu file hay khai báo sai. Với src layout, code chỉ import được sau khi được cài vào môi trường, nên test kiểm tra đúng thứ người dùng sẽ nhận. Đây là khuyến nghị của Python Packaging User Guide, và cũng là mặc định của uv init.
Tên dự án (trên PyPI, trong pyproject.toml) thường dùng gạch ngang: chi-tieu. Tên package Python (để import) phải dùng gạch dưới: chi_tieu.
2. Chia module theo trách nhiệm
Áp dụng bài học từ dự án chặng 2 và chặng 4: tách logic thuần khỏi nhập xuất.
xu_ly.py: hàm thuần, khônginput, khôngprint, không đọc file. Dễ test nhất, nên có nhiều test nhất.luu_tru.py: đọc ghi JSON, nhận đường dẫn làm tham số (test dùngtmp_path).cli.py: lớp mỏng nối người dùng với hai module trên, chứa hàmmain().
# (minh họa) src/chi_tieu/cli.py
import argparse
from pathlib import Path
from chi_tieu.luu_tru import nap, luu # import tuyệt đối theo tên package
from chi_tieu.xu_ly import bao_cao
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="chi-tieu", description="Quản lý chi tiêu cá nhân")
parser.add_argument("--file", type=Path, default=Path.home() / ".chi_tieu.json")
args = parser.parse_args(argv)
print(bao_cao(nap(args.file)))
return 0
# (minh họa) src/chi_tieu/__main__.py
import sys
from chi_tieu.cli import main
sys.exit(main())
Trong package, import theo tên đầy đủ from chi_tieu.xu_ly import ... (import tuyệt đối). Có thể viết tương đối from .xu_ly import ..., nhưng tuyệt đối rõ ràng hơn và là lựa chọn phổ biến. argparse sẽ được học kỹ ở chặng 7.
3. pyproject.toml: một file cho mọi cấu hình
[project]
name = "chi-tieu"
version = "0.2.0"
description = "Quản lý chi tiêu cá nhân trên dòng lệnh"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []
[project.scripts]
chi-tieu = "chi_tieu.cli:main" # tên lệnh = "module:hàm"
[build-system]
requires = ["uv_build>=0.13.6,<0.14.0"]
build-backend = "uv_build"
[dependency-groups]
dev = ["pytest>=9.2", "pytest-cov", "ruff", "mypy", "pre-commit"]
[tool.pytest.ini_options]
testpaths = ["tests"]
[tool.ruff]
line-length = 100
[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP", "SIM"]
[tool.mypy]
strict = true
[project]: thông tin dự án theo chuẩn chung (PEP 621), mọi công cụ đều đọc được.[project.scripts]: khi cài, tạo một lệnhchi-tieugọi hàmmaintrongchi_tieu/cli.py. Giá trịmain()trả về trở thành mã thoát.[build-system]: công cụ đóng gói. Bài dùnguv_builddouv inittạo; các dự án khác có thể dùnghatchlinghaysetuptools, cách dùng như nhau.[tool.*]: cấu hình pytest, Ruff, mypy ở cùng một chỗ, thay cho hàng loạt filesetup.cfg,pytest.ini,.flake8của dự án cũ.
4. Cài editable và chạy như một lệnh
$ uv sync # tạo .venv, cài thư viện VÀ cài chính dự án ở chế độ editable
$ uv run chi-tieu --help
usage: chi-tieu [-h] [--file FILE]
Quản lý chi tiêu cá nhân
options:
-h, --help show this help message and exit
--file FILE
$ uv run python -m chi_tieu # chạy qua __main__.py, tương đương
$ uv run pytest # test import chi_tieu như người dùng thật
Editable nghĩa là môi trường trỏ thẳng vào thư mục src/: sửa code xong chạy lại là thấy ngay, không cần cài lại. Với pip, lệnh tương đương là pip install -e ..
5. Build và cài ở nơi khác
$ uv build
Building source distribution...
Building wheel from source distribution...
Successfully built dist\chi_tieu-0.1.0.tar.gz
Successfully built dist\chi_tieu-0.1.0-py3-none-any.whl
File .whl (wheel) là gói cài đặt chuẩn của Python. Gửi file này cho đồng nghiệp, hoặc cài vào máy chủ:
$ uv venv && uv pip install dist/chi_tieu-0.1.0-py3-none-any.whl
$ .venv/Scripts/chi-tieu (Windows: .venv\Scripts\chi-tieu.exe)
Muốn chia sẻ công khai, uv publish đưa gói lên PyPI để ai cũng pip install chi-tieu được (cần tài khoản PyPI; nên thử trước trên TestPyPI). Ứng dụng web thì thường không build wheel mà đóng gói bằng Docker (chặng 10).
6. README: mặt tiền của dự án
# chi-tieu
Quản lý chi tiêu cá nhân trên dòng lệnh: thêm khoản chi, báo cáo theo danh mục và tháng.
## Cài đặt
uv sync
## Sử dụng
uv run chi-tieu --file du_lieu.json
## Phát triển
uv run pytest # chạy test
uv run ruff check . # lint
uv run mypy src # kiểm tra kiểu
Người mới clone dự án phải chạy được trong 5 phút chỉ bằng cách đọc README. Đó là thước đo đơn giản và chính xác cho một dự án được tổ chức tốt.
Tóm tắt
- src layout:
src/ten_package/vàtests/tách biệt; test chạy trên bản đã cài. - Chia module: logic thuần, lưu trữ, giao diện; import tuyệt đối theo tên package.
pyproject.toml:[project],[project.scripts],[build-system],[dependency-groups],[tool.*].uv synccài editable;uv buildra wheel; README chạy được trong 5 phút.
Bài tập
Bài 1. Chuyển dự án chi tiêu sang src layout
Tổ chức lại dự án quản lý chi tiêu (chặng 2, đã thêm lưu JSON) theo cấu trúc ở mục 1: ba module, __main__.py, thư mục tests/ có ít nhất 5 test, lệnh chi-tieu chạy được bằng uv run chi-tieu.
Xem gợi ý
Thứ tự làm an toàn: uv init chi-tieu tạo khung; chuyển các hàm thuần (doc_ngay, doc_so_tien, tong_theo, bao_cao) vào xu_ly.py và viết test cho chúng trước; sau đó mới chuyển phần menu vào cli.py. Chạy uv run pytest, uv run ruff check . và uv run mypy src đến khi cả ba đều sạch.
Bài 2. Build và cài thử
Build wheel bằng uv build, tạo một môi trường ảo mới ở thư mục khác, cài wheel vào đó và chạy lệnh chi-tieu.
Xem đáp án
$ cd chi-tieu && uv build
$ cd .. && mkdir thu-cai && cd thu-cai
$ uv venv
$ uv pip install ../chi-tieu/dist/chi_tieu-0.2.0-py3-none-any.whl
$ .venv\Scripts\chi-tieu --help (macOS, Linux: .venv/bin/chi-tieu --help)
Nếu lệnh báo ModuleNotFoundError, kiểm tra hai chỗ: package có nằm đúng src/chi_tieu/ và có __init__.py không, và [project.scripts] có trỏ đúng chi_tieu.cli:main không. Lỗi kiểu này chỉ lộ ra khi cài thật: đúng lý do để dùng src layout.
Nguồn tham khảo: Python Packaging User Guide: src layout vs flat layout; Writing your pyproject.toml; uv: Creating projects; uv: Building and publishing a package.
Bài tập thực hành
- Chuyển dự án quản lý chi tiêu sang src layout, có tests/ và lệnh chi-tieu chạy từ terminal.
- Build gói wheel bằng uv build và cài thử vào một môi trường ảo mới.
Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.


