⭐ Python Developer · Chặng 6Bài 6/6Bài học~60 phút

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.

Cấu trúc dự án Python chuẩn: src layout, pyproject, lệnh CLI

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
  1. 1. src layout
  2. 2. Chia module theo trách nhiệm
  3. 3. pyproject.toml: một file cho mọi cấu hình
  4. 4. Cài editable và chạy như một lệnh
  5. 5. Build và cài ở nơi khác
  6. 6. README: mặt tiền của dự án
  7. Tóm tắt
  8. Bài tập

Đế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ông input, không print, 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ùng tmp_path).
  • cli.py: lớp mỏng nối người dùng với hai module trên, chứa hàm main().
# (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ệnh chi-tieu gọi hàm main trong chi_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ùng uv_build do uv init tạo; các dự án khác có thể dùng hatchling hay setuptools, 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 file setup.cfg, pytest.ini, .flake8 củ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 sync cài editable; uv build ra 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

  1. Chuyển dự án quản lý chi tiêu sang src layout, có tests/ và lệnh chi-tieu chạy từ terminal.
  2. 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.

Bài tiếp theo
Ban biên tập HocFree

Chúng tôi viết những bài hướng dẫn dễ hiểu, thực tế để ai cũng có thể tự học lập trình và AI, hoàn toàn miễn phí.