Đóng gói thư viện (packaging)

Tới giờ code của bạn nằm trong vài file .py. Để tái dùng và chia sẻ như dân chuyên nghiệp, ta đóng nó thành thư viện. Trước hết, phân biệt ba khái niệm hay bị lẫn:

• ▸module = MỘT file .py (vd calc.py → import calc).
• ▸package = một THƯ MỤC có __init__.py, gom nhiều module (mylib/ → import mylib.core).
• ▸distribution (“gói” phát hành) = đơn vị bạn CÀI/CHIA SẺ - wheel/sdist đăng trên PyPI.

Một điểm bẫy người mới: tên trên PyPI (để uv add) thường khác tên khi import. PyPI chuẩn hoá tên theo PEP 503; còn tên import lại dùng dấu gạch dưới. Thử ngay ở Trình khám phá đóng gói (đổi tên gói để thấy):

[project]
name = "flask-sqlalchemy"
version = "0.1.0"
description = "Thư viện ví dụ"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31",
    "rich",
]

[project.scripts]
mycli = "flask_sqlalchemy:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Một thư viện chuyên nghiệp không phải “một đống file ở gốc”. Bố cục được Python Packaging Guide khuyến nghị là src/ layout:

mylib/                      # thu muc du an (repo)
├── pyproject.toml          # "danh thiep" cua goi (metadata + build)
├── README.md
├── LICENSE
├── src/
│   └── mylib/              # PACKAGE (ten import)
│       ├── __init__.py     # public API: __all__, __version__
│       ├── core.py         # code that su
│       └── py.typed        # danh dau "goi nay co type hints"
└── tests/
    └── test_core.py        # pytest

__init__.py là mặt tiền của gói: nó quyết định ai gọi import mylib thì thấy gì. Khai báo API công khai ở đây, giấu phần còn lại:

from mylib.core import cong, Diem   # nang len cap goi

__all__ = ["cong", "Diem"]          # "API cong khai" chinh thuc
__version__ = "0.1.0"               # mot nguon su that ve phien ban

• ▸src/<package>/ giữ code; tests/ tách riêng; pyproject.toml ở gốc.
• ▸__init__.py định nghĩa public API (__all__) - phần còn lại coi như nội bộ.
• ▸Một __version__ duy nhất; tên file/module dùng chữ thường, gạch dưới.

pyproject.toml là tệp cấu hình CHUẨN (PEP 621) mô tả gói: tên, phiên bản, phụ thuộc, và build-system dùng để đóng gói. Đây là bản tối thiểu “đủ chuyên nghiệp”:

[project]
name = "mylib"                     # ten tren PyPI (se duoc chuan hoa)
version = "0.1.0"
description = "Thu vien vi du"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"
authors = [{ name = "Ban", email = "ban@example.com" }]
dependencies = [
    "requests>=2.31",              # phu thuoc luc CHAY
]

[project.optional-dependencies]
dev = ["pytest", "mypy"]           # cai khi phat trien: uv add --dev ...

[project.scripts]
mycli = "mylib:main"              # tao lenh CLI -> goi ham main()

[build-system]
requires = ["hatchling"]           # cong cu build (backend)
build-backend = "hatchling.build"

• ▸[project]: metadata + dependencies (phụ thuộc lúc chạy) + requires-python.
• ▸[project.scripts]: biến gói thành lệnh CLI - “ten = package.module:ham”.
• ▸[build-system]: backend đóng gói (hatchling phổ biến, gọn); uv đọc tệp này để build.

Một thư viện tốt không chỉ chạy được - nó dễ dùng đúng. Ba thói quen tách bạn khỏi “script tạm bợ”, và cả ba bạn đã học ở các bài trước:

def cong(a: int, b: int) -> int:
    """Cong hai so nguyen. Vi du:

    >>> cong(2, 3)
    5
    """
    return a + b

from mylib import cong

def test_cong():
    assert cong(2, 3) == 5
    assert cong(-1, 1) == 0

$ uv run pytest -q
1 passed

• ▸Type hints công khai + py.typed: API của bạn được mypy kiểm ở phía người dùng.
• ▸Test đi kèm (pytest) - như bài Unit/Integration test; chạy uv run pytest.
• ▸Semantic Versioning: MAJOR.MINOR.PATCH; đã phát hành thì KHÔNG sửa, chỉ tăng số.

Khi gói đã sẵn sàng, uv build tạo ra hai tạo phẩm trong dist/: một wheel (đã build, cài nhanh) và một sdist (nguồn). Phát hành cả hai lên PyPI:

# 1) Build -> sinh dist/mylib-0.1.0-py3-none-any.whl + mylib-0.1.0.tar.gz
uv build

# 2) Thu nghiem an toan: day len TestPyPI truoc
uv publish --publish-url https://test.pypi.org/legacy/ --token pypi-...

# 3) On roi thi phat hanh that len PyPI
uv publish --token pypi-...

# Nguoi dung cai:
uv add mylib

• ▸uv build → wheel (.whl, cài nhanh) + sdist (.tar.gz, nguồn); phát hành cả hai.
• ▸LUÔN thử TestPyPI trước, rồi mới PyPI; xác thực bằng API token (đừng dùng mật khẩu).
• ▸Mỗi phiên bản chỉ phát hành MỘT lần - sai thì tăng số, build lại, phát hành bản mới.

Mặt kia của đóng gói là dùng thư viện - của bạn và của người khác - đúng phiên bản. uv add ghi ràng buộc vào pyproject.toml và khoá phiên bản chính xác vào uv.lock để tái lập:

uv add "requests>=2.31,<3"     # rang buoc: >=2.31 va <3
uv add --dev pytest mypy        # phu thuoc phat trien
uv add --editable ../mylib      # dung goi LOCAL dang phat trien (-e)

uv lock                         # khoa phien ban chinh xac vao uv.lock
uv sync                         # dung lai dung moi truong tu lockfile

Ràng buộc phiên bản là cách bạn nói “nhận bản mới sửa lỗi, nhưng đừng nhảy bản phá vỡ tương thích”. Mở lại tab “Ràng buộc phiên bản” ở widget Bước 1 và thử ~=1.4.2:

• ▸uv add ghi ràng buộc vào pyproject; uv.lock khoá phiên bản chính xác → tái lập.
• ▸~=1.4.2 = >=1.4.2 và <1.5 (nhận bản vá, chặn bản phá vỡ); == ghim cứng một bản.
• ▸uv add --editable ../mylib (-e): dùng thư viện local, sửa nguồn là thấy ngay - hợp khi vừa viết vừa dùng.