Python จัดโครงสร้างโปรเจกต์



พอโปรเจกต์โตเกินหนึ่งไฟล์ การจัดวางไฟล์ให้เป็นระเบียบช่วยให้หาของเจอ ทำงานเป็นทีมได้ และเอาไปติดตั้ง/แจกจ่ายง่าย บทนี้แนะนำโครงสร้างมาตรฐานที่ชุมชน Python ใช้กัน

โครงสร้างขั้นต่ำ: สคริปต์เดียว

my-script/
├── main.py
├── requirements.txt
└── README.md

เหมาะกับเครื่องมือเล็ก ๆ หรือสคริปต์ทำงานเฉพาะกิจ

โครงสร้างโปรเจกต์ขนาดกลาง

weather-app/
├── weather_app/          ← โค้ดของโปรแกรม (package)
│   ├── __init__.py
│   ├── __main__.py       ← จุดเริ่มโปรแกรม (python -m weather_app)
│   ├── api.py
│   ├── models.py
│   └── utils.py
├── tests/                ← เทสต์
│   ├── test_api.py
│   └── test_utils.py
├── pyproject.toml        ← ข้อมูลโปรเจกต์ + dependency
├── README.md
├── .gitignore
└── .venv/                ← virtual environment (ไม่ commit)

หลักคือ แยกโค้ดโปรแกรม (package) ออกจากไฟล์รอบ ๆ และแยก tests ออกมาต่างหาก

pyproject.toml: ไฟล์ตั้งค่ากลาง

ปัจจุบัน pyproject.toml เป็นไฟล์มาตรฐานสำหรับข้อมูลโปรเจกต์ dependency (ไลบรารีที่โปรเจกต์ต้องใช้) และตั้งค่าเครื่องมือ

[project]
name = "weather-app"
version = "0.1.0"
description = "แอปดูพยากรณ์อากาศ"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.28",
    "rich>=13.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff",
    "mypy",
]

[project.scripts]
weather = "weather_app.__main__:main"     # สร้างคำสั่ง weather ในเทอร์มินัล

[tool.ruff]
line-length = 88

[tool.pytest.ini_options]
testpaths = ["tests"]

ติดตั้งโปรเจกต์ในโหมดพัฒนา (แก้โค้ดแล้วมีผลทันทีไม่ต้องติดตั้งใหม่) — พิมพ์ใน เทอร์มินัล ที่ activate venv แล้ว ไม่ใช่ใน Python shell

pip install -e ".[dev]"

__main__.py: จุดเริ่มโปรแกรม

# weather_app/__main__.py
from weather_app.api import get_forecast


def main():
    city = input("เมือง: ")
    forecast = get_forecast(city)
    print(forecast)


if __name__ == "__main__":
    main()

รันด้วย python -m weather_app หรือถ้าตั้ง [project.scripts] ไว้ ก็พิมพ์ weather ได้เลย

การ import ภายในโปรเจกต์

จาก api.py เรียกใช้ utils.py ในแพ็กเกจเดียวกัน

# weather_app/api.py
from weather_app.utils import format_temp     # absolute import (แนะนำ)
# หรือ
from .utils import format_temp                # relative import

ใช้ absolute import (from weather_app.utils import ...) จะชัดเจนกว่าและ refactor ง่ายกว่า

แยกความรับผิดชอบเป็นไฟล์

ไฟล์ควรมีอะไร
models.pyคลาส/dataclass ที่แทนข้อมูล
api.py / client.pyโค้ดคุยกับบริการภายนอก
services.py / core.pyตรรกะทางธุรกิจหลัก
utils.py / helpers.pyฟังก์ชันช่วยเล็ก ๆ ทั่วไป
config.pyการอ่านค่าตั้งค่า/ตัวแปรสภาพแวดล้อม
cli.py / __main__.pyการรับ argument และเริ่มโปรแกรม

หลักคือ ไฟล์หนึ่งควรมีเหตุผลเดียวที่จะต้องแก้

.gitignore

# virtual environment
.venv/
venv/

# Python
__pycache__/
*.pyc
*.egg-info/
build/
dist/

# เครื่องมือ
.pytest_cache/
.mypy_cache/
.ruff_cache/
.coverage

# editor
.vscode/
.idea/

# ข้อมูลลับ
.env

README.md

อย่างน้อยควรมี

  • โปรเจกต์นี้ทำอะไร
  • วิธีติดตั้ง (สร้าง venv, pip install -r requirements.txt)
  • วิธีรัน
  • วิธีรันเทสต์

config กับข้อมูลลับ

อย่าใส่ API key / รหัสผ่านในโค้ด เก็บใน environment variable หรือไฟล์ .env (ที่อยู่ใน .gitignore)

# config.py
import os

API_KEY = os.environ.get("WEATHER_API_KEY")
if not API_KEY:
    raise RuntimeError("ตั้งค่า WEATHER_API_KEY ก่อน")

ไลบรารี python-dotenv ช่วยโหลด .env เข้ามาเป็น environment variable ตอนพัฒนา

pip install python-dotenv
from dotenv import load_dotenv
load_dotenv()   # โหลดค่าจาก .env

ตัวอย่างโครงสร้างโปรเจกต์เต็ม

expense-tracker/
├── expense_tracker/
│   ├── __init__.py
│   ├── __main__.py
│   ├── models.py           # dataclass Expense
│   ├── storage.py          # อ่าน/เขียน JSON
│   ├── reports.py          # สรุปยอด จัดกลุ่ม
│   └── cli.py              # เมนูโต้ตอบ
├── tests/
│   ├── test_models.py
│   ├── test_storage.py
│   └── test_reports.py
├── data/
│   └── .gitkeep
├── pyproject.toml
├── README.md
└── .gitignore

การไหลของโค้ด: cli.py รับคำสั่งจากผู้ใช้ → เรียก reports.py/storage.py → ที่ทำงานกับ models.py แต่ละไฟล์เทสต์ได้แยกกัน

เช็คความเข้าใจก่อนข้ามบท

  • อธิบายหน้าที่ของไฟล์หลัก เช่น pyproject.toml, README.md, .gitignore, __main__.py ได้
  • แยกโค้ดตามความรับผิดชอบ แทนการรวมทุกอย่างไว้ไฟล์เดียวได้
  • ลองร่างโครงสร้างโปรเจกต์เล็ก ๆ ของตัวเองพร้อมระบุว่าแต่ละไฟล์ทำหน้าที่อะไร

สรุป

  • แยกโค้ดโปรแกรม (package) ออกจาก tests, config, docs
  • pyproject.toml เก็บข้อมูลโปรเจกต์ + dependency + ตั้งค่าเครื่องมือ
  • ใช้ absolute import ภายในโปรเจกต์, python -m package เป็นจุดเริ่ม
  • แต่ละไฟล์มีความรับผิดชอบเดียว; ข้อมูลลับอยู่ใน .env ไม่ใช่ในโค้ด

บทถัดไปว่าด้วยการใช้ Git กับโปรเจกต์ Python