pyproject.toml Generator: สร้าง pyproject.toml ตามมาตรฐาน PEP 621 ได้ในเบราว์เซอร์

ทุกโปรเจกต์ Python ยุคใหม่เริ่มต้นด้วยไฟล์เดียวกัน นั่นคือ pyproject.toml ไฟล์นี้ทำหน้าที่ประกาศชื่อและเวอร์ชันของแพ็กเกจ ระบุเวอร์ชัน Python ที่โปรเจกต์รองรับ ลิสต์ dependency ทั้งหมด และบอกเครื่องมือแพ็กเกจว่าจะ build โปรเจกต์ของคุณอย่างไร แต่ถึงแม้มันจะเป็นมาตรฐานทางการ การเขียนไฟล์นี้ด้วยมือก็ยังทำให้หลายคนปวดหัว เพราะชื่อฟิลด์ตาม PEP 621 ต้องระบุให้ถูกต้องเป๊ะ ไวยากรณ์ของ TOML เข้มงวด และ build backend แต่ละตัวยังเติมรูปแบบเฉพาะของตัวเองเข้ามาอีกชั้น pyproject.toml Generator ช่วยขจัดอุปสรรคเหล่านี้ได้ทั้งหมด

เครื่องมือฟรีนี้ทำงานในเบราว์เซอร์ แปลงฟอร์มสั้น ๆ ให้กลายเป็นไฟล์ pyproject.toml ที่สะอาดและเป็นไปตามมาตรฐาน คุณเลือก backend ได้จาก uv, Poetry, setuptools หรือ Hatch กรอกข้อมูล metadata ของโปรเจกต์ เพิ่ม runtime dependency และ dev dependency group แล้วดู TOML ที่ถูกต้องปรากฏขึ้นแบบเรียลไทม์ในแผงผลลัพธ์ เมื่อพอใจแล้วก็คัดลอกไปใช้และคอมมิตได้เลย ไม่ต้องสมัครบัญชี ไม่ต้องติดตั้งอะไร และไม่ต้องลองผิดลองถูกกับ build system

ในบทความนี้คุณจะได้เรียนรู้ว่าเครื่องมือนี้ทำอะไรได้บ้าง วิธีใช้งานทีละขั้นตอน ความสัมพันธ์ระหว่าง PEP 621 กับ build backend และแนวปฏิบัติที่ช่วยให้ไฟล์ config ของโปรเจกต์ Python คุณแข็งแรงในระยะยาว

ทำไมต้องใช้ pyproject.toml Generator?

• ไม่ต้องท่องจำไวยากรณ์. PEP 621 กำหนดชื่อฟิลด์และโครงสร้างตารางแบบเคร่งครัด แทนที่จะเปิดเอกสารกลับไปกลับมาเป็นครั้งที่สิบ แค่กรอกฟิลด์ที่มีป้ายกำกับไว้ แล้วให้เครื่องมือสร้าง TOML ที่ถูกต้องให้เอง
• ผลลัพธ์รองรับแต่ละ backend. uv, Poetry, setuptools และ Hatch ต่างกันคาดหวัง config รอบข้างไม่เหมือนกัน เครื่องมือจะปรับรูปแบบไฟล์ตาม backend ที่คุณเลือก ทำให้ไม่มีการผสมส่วนที่เข้ากันไม่ได้ด้วยมือ
• เห็นผลลัพธ์ทันทีระหว่างพิมพ์. ทุกครั้งที่แก้ไข ผลลัพธ์ TOML จะอัปเดตทันที ช่วยให้เห็นชัดว่าแต่ละฟิลด์แปลงเป็นบรรทัดไหนในไฟล์ ซึ่งเร็วกว่าการอ่านสเปกเยอะ
• แยก dependency อย่างเป็นระเบียบ. ฟอร์มแยกให้ชัดว่าแพ็กเกจใดจำเป็นสำหรับผู้ใช้ และแพ็กเกจใดจำเป็นเฉพาะผู้พัฒนา ผลลัพธ์คือกลุ่ม dependency ที่สะอาด ไม่ใช่ลิสต์เดียวยาวเหยียด
• ไม่ต้องติดตั้ง ไม่มีความเสี่ยง. เครื่องมือทำงานทั้งหมดในเบราว์เซอร์ของคุณ ไม่มีข้อมูลถูกอัปโหลด ไม่มีอะไรต้องติดตั้ง และสร้างไฟล์ใหม่ได้กี่ครั้งก็ได้
• คัดลอกไปคอมมิตได้ทันที. ผลลัพธ์จัดรูปแบบไว้ให้วางที่ repository root ได้เลย ไฟล์ที่ได้ลงโปรเจกต์และคอมมิตถัดไปของคุณได้ทันที

ฟีเจอร์หลัก

สามฟีเจอร์นี้ควรดูใกล้ ๆ อีกหน่อย:

• การเลือก backend กำหนดผลลัพธ์ทั้งไฟล์. การเลือก uv แทน Poetry ไม่ใช่เรื่องผิวเผิน เพราะมันเปลี่ยนว่าเครื่องมือจะเขียน declaration ส่วน build-system และ section เฉพาะเครื่องมือแบบไหนคู่กับตาราง [project] ของคุณ
• Dev group ถูกแยกออกมาตลอด. pytest, linter และ formatter อยู่ในกลุ่มของตัวเอง ทำให้คนที่แค่อยากใช้แพ็กเกจของคุณไม่ต้องติดตั้งของเกินมา
• แผงผลลัพธ์ใช้สอนได้ด้วย. การเห็น TOML ปรากฏขึ้นระหว่างกรอกฟอร์ม เป็นหนึ่งในวิธีเร็วที่สุดที่จะเข้าใจโครงสร้าง PEP 621

วิธีใช้งาน pyproject.toml Generator

1. เลือก build backend. เลือก uv, Poetry, setuptools หรือ Hatch ที่ด้านบนของฟอร์ม ถ้ายังไม่แน่ใจ setuptools เป็นตัวเลือกคลาสสิกที่ปลอดภัย uv เหมาะกับสายงานสมัยใหม่ที่เน้นความเร็ว และ Poetry เหมาะกับทีมที่ใช้ lockfile ของ Poetry อยู่แล้ว
2. กรอก metadata ของโปรเจกต์. ใส่ชื่อแพ็กเกจ เวอร์ชัน คำอธิบายสั้น ๆ และเวอร์ชัน Python ขั้นต่ำที่โค้ดรองรับ ควรใช้ชื่อตัวพิมพ์เล็กคั่นด้วยขีดกลาง ให้ตรงกับ identity ที่คุณต้องการบน PyPI
3. เพิ่ม runtime dependency. ลิสต์แพ็กเกจที่โปรเจกต์ import จริง ๆ คือไลบรารีที่จำเป็นต่อการรันโปรแกรม ใช้ requirement string แบบเดียวกับที่คุณส่งให้ตัวติดตั้งแพ็กเกจ
4. เพิ่ม dev dependency group. วาง pytest, ruff และเครื่องมือสำหรับผู้พัฒนาลงในกลุ่ม development เพื่อให้ติดตั้งได้เมื่อต้องการ โดยไม่กลายเป็นภาระของผู้ใช้ปลายทาง
5. คัดลอก TOML ไปไว้ที่ repo root. ตรวจผลลัพธ์ คัดลอก แล้วบันทึกเป็นไฟล์ pyproject.toml ที่รากของ repository จากนั้นคอมมิต และรันคำสั่ง install ของ backend สักครั้งเพื่อยืนยันว่าทุกอย่าง resolve ได้

จากฟอร์มว่าง ๆ สู่ไฟล์ที่คอมมิตแล้ว ใช้เวลาไม่ถึงสองนาที แม้โปรเจกต์จะมี dependency หลายตัวก็ตาม

PEP 621 และการเลือก backend

PEP 621 ทำหน้าที่มาตรฐานวิธีที่โปรเจกต์ Python อธิบายตัวเอง ก่อนหน้านี้ metadata ของแพ็กเกจกระจัดกระจายอยู่หลายที่พร้อมกัน setup.py รันโค้ด arbitrary ได้ setup.cfg เก็บ declaration สไตล์ INI และไฟล์ requirements.txt ทำซ้ำลิสต์ dependency ที่ค่อย ๆ เพี้ยนไปจากความจริง PEP 621 จึงกำหนดตาราง [project] แบบ declarative เพียงที่เดียว ครอบคลุม name, version, description, requires-python, dependencies และกลุ่ม dependency เสริม ที่เครื่องมือแพ็กเกจฝั่งไหนก็อ่านได้โดยไม่ต้องรันโค้ดของคุณ

แต่มีคำถามหนึ่งที่ PEP 621 ตั้งใจปล่อยไว้ นั่นคือใครเป็นคน build แพ็กเกจจริง ๆ งานนี้เป็นของ build backend ที่ประกาศอยู่ในตาราง [build-system] backend จะอ่าน metadata ใน [project] แล้วแปลง source tree ของคุณเป็น wheel หรือ source distribution การเลือก backend จึงแท้จริงคือการเลือกเครื่องจักรที่ห่อหุ้มสัญญานี้:

• uv คือตัวเลือกที่เน้นความเร็วเป็นอันดับแรก ถ้าคุณอยากได้การติดตั้งที่เร็วมากและเครื่องมือสมัยใหม่ตัวเดียวจัดการทั้ง environment และการแพ็กเกจ เลือก uv แล้วคง config ให้เรียบง่าย
• Poetry มาพร้อม lockfile และ dependency resolver ของตัวเอง เหมาะกับทีมที่ทำงานด้วยคำสั่งของ Poetry อยู่แล้วและอยากคง workflow นั้นไว้
• setuptools คือตัวเลือกอนุรักษ์นิยม มีประวัติยาวนานที่สุดและเข้ากันได้กว้างที่สุด จึงปลอดภัยสำหรับไลบรารีที่ต้อง build ได้ทุกสภาพแวดล้อม
• Hatch ให้ประสบการณ์ที่สะอาดและขยายได้ พร้อมระบบจัดการ environment และเวอร์ชันในตัว เป็นทางกลางที่ดีสำหรับโปรเจกต์แอปพลิเคชัน

แนวคิดง่าย ๆ ที่ช่วยให้ไม่สับสนคือ ตาราง [project] คือส่วนมาตรฐานที่พกพาข้ามเครื่องมือได้ ส่วน section เฉพาะเครื่องมือ เช่น บล็อก [tool.poetry] ของ Poetry หรือการตั้งค่าของ Hatch เป็นส่วนเสริมที่ซ้อนทับมาสำหรับ backend นั้น ๆ เครื่องมือของเราเขียนส่วนมาตรฐานให้คุณ และเติมเฉพาะ section ที่ backend ที่เลือกต้องการเท่านั้น

dependency group คือชิ้นสุดท้ายของภาพ runtime dependency จะถูกแจกจ่ายไปกับแพ็กเกจของคุณ ส่วนกลุ่มสำหรับนักพัฒนาอย่าง pytest, ruff หรือ mypy ถูกประกาศแยกต่างหาก เพื่อให้ผู้ร่วมพัฒนาติดตั้งได้โดยไม่ปนเปื้อนไปถึงการติดตั้งของผู้ใช้ปลายทาง ฟอร์มของเครื่องมือสะท้อนการแบ่งนี้ตรง ๆ และ TOML ที่ได้ก็แยกสองโลกนี้ออกจากกันชัดเจน

ตัวอย่างการใช้งานจริง

เริ่มต้นสร้างแพ็กเกจ SDK ใหม่

คุณกำลังห่อ API ภายในองค์กรให้เป็นไลบรารี client ที่นำกลับมาใช้ซ้ำได้ กรอกฟอร์มด้วยชื่อ SDK เวอร์ชันเริ่มต้น 0.1.0 runtime dependency เช่น HTTP client และ dev group ที่มี pytest จากนั้นคัดลอก TOML คอมมิต แล้ว CI ของคุณก็ build และติดตั้งแพ็กเกจได้ทันที เมื่อ SDK พร้อมใช้ ไฟล์เดียวกันนี้ก็คือสิ่งที่คุณเผยแพร่สู่ PyPI

ย้ายจาก setup.py มาที่ pyproject.toml

โปรเจกต์รุ่นเก่ามักมี setup.py ที่กอดกับ keyword argument เป็นสิบคำ บวกกับ requirements.txt ที่เพี้ยนจากความเป็นจริงไปนานแล้ว ใช้เครื่องมือสร้าง pyproject.toml แบบ declarative แล้วย้ายฟิลด์ทีละส่วน คือ name และ version จาก setup(), install_requires ไปไว้ใน dependencies และ test extras ไปไว้ใน dev group เมื่อ build ผ่านแล้วก็ลบ setup.py ทิ้ง เหลือทุกอย่างในไฟล์มาตรฐานเดียว

แพ็กเกจเครื่องมือใน monorepo

ใน monorepo เครื่องมือภายในที่ใช้ร่วมกันก็ควรได้รับวินัยด้านการแพ็กเกจเทียบเท่าไลบรารีสาธารณะ สร้าง pyproject.toml ขนาดเล็กให้แต่ละแพ็กเกจเครื่องมือ โดยเลือก backend เดียวกันทั้ง repository ใช้ metadata ที่สอดคล้องกัน และมี dev group บรรทุกเครื่องมือ linter ที่ใช้ร่วมกัน ไฟล์ที่เป็นรูปแบบเดียวกันช่วยให้การติดตั้งข้ามแพ็กเกจและ CI matrix ดูแลง่ายขึ้นมาก

ใช้สอนการแพ็กเกจ Python ตามมาตรฐาน

ผู้สอนและ bootcamp ใช้ฟอร์มนี้เป็นสาธิตสดได้เลย พิมพ์ชื่อโปรเจกต์ เพิ่ม dependency หนึ่งตัว แล้วชี้ให้ผู้เรียนดูว่าบรรทัด TOML ไหนปรากฏขึ้นบ้าง ผู้เรียนจะเข้าใจความเชื่อมโยงระหว่างแนวคิด metadata กับไวยากรณ์ของไฟล์ ก่อนที่จะต้องไปเจ็บปวดกับ build ที่พังจริง

แนวทางปฏิบัติที่ดี

• ตั้ง requires-python อย่างตรงไปตรงมา. ประกาศเวอร์ชัน Python เก่าที่สุดที่คุณทดสอบจริง ไม่ใช่เวอร์ชันใหม่ที่คุณชอบ ประกาศต่ำเกินไปทำให้ผู้ใช้บน interpreter เก่าติดหล่ม ประกาศสูงเกินไปทำให้การติดตั้งล้มเหลว
• คง runtime dependency ให้น้อยที่สุด. ทุก runtime dependency คือความเสี่ยงด้าน supply chain และความขัดแย้งของเวอร์ชัน ถ้าแพ็กเกจใดจำเป็นแค่สำหรับ test หรือ docs มันควรอยู่ใน dev group
• คอมมิตไฟล์ อย่าสร้างมันใน CI. pyproject.toml คือ source code ควรรีวิวใน pull request เหมือนโค้ดอื่น เพื่อให้การเปลี่ยน dependency ได้คนตรวจตา
• รัน build หลังแก้ทุกครั้ง. คำสั่ง build ของ backend เป็นการยืนยันที่แท้จริงเท่านั้นว่า TOML parse ได้และ metadata สมบูรณ์
• ใช้ชื่อและเวอร์ชันอย่างสม่ำเสมอ. ให้ชื่อแพ็กเกจตรงกับ identity ที่คุณเผยแพร่ และยึด semantic versioning เพื่อให้เครื่องมือปลายทางคาดเดาการอัปเกรดได้
• สร้างใหม่แทนการแก้มือเมื่อโครงสร้างเปลี่ยน. เมื่อสลับ backend หรือเพิ่มกลุ่มใหม่ การสร้างไฟล์ใหม่ช่วยรักษาโครงสร้างให้สม่ำเสมอ ดีกว่าการสะสมการแก้ไขด้วยมือ

ไม่ว่าคุณจะเริ่มไลบรารีใหม่คืนนี้ หรือกำลังจะปลดระวาง setup.py รุ่นเก่าในที่สุด pyproject.toml Generator พาคุณจากฟอร์มว่าง ๆ สู่ไฟล์โปรเจกต์ที่เป็นมาตรฐานและคอมมิตแล้วภายในสองสามนาที เลือก backend กรอก metadata แล้วปล่อยให้ผลลัพธ์ TOML แบบเรียลไทม์จัดการเรื่องจัดรูปแบบแทนคุณ

เครื่องมือที่เกี่ยวข้องที่คุณอาจสนใจ:

• package.json Generator — สร้างไฟล์ package.json สำหรับโปรเจกต์ JavaScript ด้วยรูปแบบฟอร์มแบบเดียวกัน
• YAML Formatter — จัดระเบียบและตรวจสอบไฟล์ config YAML ควบคู่กับงาน TOML ของคุณ
• GitHub Actions Workflow Generator — สร้าง CI workflow สำหรับ build และเผยแพร่แพ็กเกจ Python ของคุณ

ขอให้สนุกกับการแพ็กเกจ Python!

คำถามที่พบบ่อย

ถ: pyproject.toml Generator ใช้ฟรีจริงหรือเปล่า? ตอบ: ใช่ครับ เครื่องมือทำงานทั้งหมดในเบราว์เซอร์ ไม่ต้องสมัครบัญชี ไม่จำกัดจำนวนครั้ง และไม่มีข้อมูลใดออกจากเครื่องของคุณ

ถ: ควรเลือก backend ไหนดี ระหว่าง uv, Poetry, setuptools หรือ Hatch? ตอบ: setuptools ปลอดภัยที่สุดสำหรับไลบรารีทั่วไป uv เหมาะที่สุดถ้าต้องการ workflow สมัยใหม่ที่เร็วที่สุด Poetry เข้ากับทีมที่ใช้ lockfile ของ Poetry อยู่แล้ว และ Hatch เป็นทางกลางที่สะอาดดีสำหรับแอปพลิเคชัน เครื่องมือจะปรับผลลัพธ์ตามตัวที่คุณเลือกโดยอัตโนมัติ

ถ: runtime dependency กับ dev dependency group ต่างกันอย่างไร? ตอบ: runtime dependency คือแพ็กเกจที่จำเป็นต่อการทำงานของแพ็กเกจคุณเมื่อผู้ใช้ปลายทางติดตั้ง ส่วน dev group เก็บเครื่องมือของผู้พัฒนาอย่าง pytest หรือ ruff ซึ่งติดตั้งแยกต่างหากและไม่กลายเป็น requirement ของแพ็กเกจคุณ

ถ: ควรวางไฟล์ที่สร้างแล้วไว้ตรงไหน? ตอบ: ไว้ที่รากของ repository โดยตั้งชื่อไฟล์ว่า pyproject.toml พอดี เครื่องมือ build จะมองหาไฟล์นี้ที่ตำแหน่งนั้น ถ้าวางไว้ในโฟลเดอร์ย่อย backend จะไม่นำไปใช้