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/
# ข้อมูลลับ
.envREADME.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-dotenvfrom 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