Packaging & pyproject.toml

Python package คือไดเรกทอรีของโมดูลที่สามารถติดตั้ง กำหนดเวอร์ชัน และแชร์ได้ การทำ Packaging จะเปลี่ยนโค้ดในเครื่องของคุณให้เป็นสิ่งที่ทุกคนสามารถติดตั้งได้ด้วย pip install mypackage การเข้าใจ Packaging เป็นสิ่งจำเป็นทันทีที่โปรเจกต์ของคุณเติบโตเกินกว่าสคริปต์ไฟล์เดียว หรือเมื่อคุณต้องการแชร์งานกับเพื่อนร่วมทีมหรือสาธารณะ

โครงสร้าง Package

การใช้ src-layout แบบเรียบร้อยจะแยกซอร์สโค้ดออกจากการทดสอบและ tooling ป้องกันการ import โค้ดที่ยังไม่ได้ติดตั้งโดยบังเอิญ

flowchart TD
  root["mypackage/"] --> src["src/"]
  src --> pkg["mypackage/"]
  pkg --> init["__init__.py"]
  pkg --> core["core.py"]
  pkg --> utils["utils.py"]
  root --> tests["tests/"]
  tests --> conftest["conftest.py"]
  tests --> testcore["test_core.py"]
  root --> pyproj["pyproject.toml"]
  root --> readme["README.md"]

Clean src-layout package structure

pyproject.toml

pyproject.toml คือแหล่งข้อมูลหลักสำหรับ package ของคุณ ตาราง [build-system] ระบุ build backend และ [project] ประกาศ metadata ทั้งหมดที่ pip และ PyPI ต้องการ

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

[project]
name = "mypackage"
version = "0.1.0"
description = "A short description of mypackage"
readme = "README.md"
requires-python = ">=3.11"
license = { text = "MIT" }
authors = [
    { name = "Your Name", email = "[email protected]" }
]
dependencies = [
    "httpx>=0.27",
]

[project.optional-dependencies]
dev = [
    "pytest>=8",
    "mypy>=1.10",
]

[project.urls]
Homepage = "https://github.com/yourname/mypackage"

ไฟล์ซอร์สโค้ด

Public API จะถูก re-export จาก __init__.py เพื่อให้ import surface สะอาดเรียบร้อย

from mypackage.core import greet

__all__ = ["greet"]

Business logic อยู่ในโมดูลเฉพาะ เช่น core.py

def greet(name: str) -> str:
    """Return a greeting string."""
    return f"Hello, {name}!"

Editable install, การ Build และการเผยแพร่

ในระหว่างการพัฒนา คุณต้องการให้การเปลี่ยนแปลงโค้ดมีผลทันทีโดยไม่ต้องติดตั้งใหม่ Flag -e ช่วยให้ทำแบบนั้นได้ เมื่อพร้อมแจกจ่าย build จะสร้าง artifact และ twine จะอัปโหลดขึ้น

# editable install — changes to src/ take effect immediately
pip install -e ".[dev]"

# build source distribution + wheel
python -m build

# publish to PyPI (requires a PyPI account + token)
twine upload dist/*

# for practice, use TestPyPI first:
twine upload --repository testpypi dist/*