Python Academy · บทเรียน

โครงสร้างโครงการและ pyproject.toml

Q: บทเรียน “โครงสร้างโครงการและ pyproject.toml” ฟรีหรือไม่

ใช่ — ข้อความเต็มของ “โครงสร้างโครงการและ pyproject.toml” ฟรีให้อ่านที่นี่บนเว็บ เพื่อปฏิบัติแบบโต้ตอบ (ตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7) และปลดล็อคส่วนที่เหลือของคอร์ส Python Academy ให้อัปเกรดเป็น CoddyKit PRO คอร์ส Python Academy มีบทเรียนทั้งหมด 4 บทเรียน

Q: คุณจะเรียนรู้อะไรในบทเรียน “โครงสร้างโครงการและ pyproject.toml”

จัดวางแพ็กเกจ คุณปฏิบัติ Python Academy ด้วยโค้ดที่ใช้งานได้จริงที่คุณเรียกใช้โดยตรงในเบราว์เซอร์ และติวเตอร์ AI ตลอด 24/7 ตอบคำถามของคุณขณะที่คุณไปผ่านบทเรียน

Q: คุณต้องมีประสบการณ์ก่อนที่จะเริ่มเรียน Python Academy หรือไม่

ไม่จำเป็นต้องมีประสบการณ์มาก่อน Python Academy บน CoddyKit ออกแบบมาสำหรับผู้เริ่มต้นไปจนถึงผู้เรียนขั้นสูง คุณสามารถเริ่มต้นที่นี่หรือเริ่มจากตัวแรกและเรียนด้วยความเร็วของคุณเอง นี่คือบทเรียนที่ 1 จากทั้งหมด 4 บทเรียน

Q: บทเรียน “โครงสร้างโครงการและ pyproject.toml” ใช้เวลานานแค่ไหน

บทเรียน CoddyKit ส่วนใหญ่ใช้เวลาประมาณ 5–10 นาที แต่ละบทเรียนจึงสั้นและเป็นแบบโต้ตอบ คุณสามารถก้าวหน้าอย่างต่อเนื่องและกลับมาเรียนต่อจากตรงที่เพิ่งหยุดบนเว็บและแอปได้เลย

Q: ฉันเขียนและรันโค้ดในบทเรียน Python Academy นี้ได้ไหม

ได้ บทเรียน Python Academy ทุกบทมีตัวแก้ไขโค้ดในตัว คุณจึงเขียนและรันโค้ดจริงได้เลยในเบราว์เซอร์ และได้รับข้อเสนอแนะจาก AI ในทันที — ไม่ต้องติดตั้งในเครื่องของคุณ

จัดวางแพ็กเกจ

โครงสร้างโครงการและ pyproject.toml เป็นบทเรียน Python Academy ฟรีบน CoddyKit นี่คือบทเรียนที่ 1 จากทั้งหมด 4 บทเรียน คุณสามารถอ่านบทเรียนทั้งหมดด้านล่างฟรี — จากนั้นลองปฏิบัติด้วยตัวคุณเองในเบราว์เซอร์พร้อมตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7 บทเรียนนี้เป็นส่วนหนึ่งของเส้นทางการเรียน Python Academy และความก้าวหน้าของคุณจะซิงค์ข้ามเว็บและแอป CoddyKit คอร์ส Python Academy มีบทเรียนทั้งหมด 4 บทเรียน

เหตุใดจึงควรจัดแพ็กเกจโค้ด

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

ขั้นตอนแรกคือการจัดโครงสร้างโครงการให้สะอาดและมีไฟล์กำหนดค่า

โครงสร้าง src

โครงสร้างที่แนะนำคือวางโค้ดที่นำเข้าได้ไว้ในไดเรกทอรี src/:

src/mypackage/__init__.py
src/mypackage/core.py
pyproject.toml
README.md และ tests/

โครงสร้าง src ช่วยป้องกันการนำเข้าโค้ดจากรากของโครงการโดยไม่ตั้งใจ แทนที่จะนำเข้าสำเนาที่ติดตั้งไว้

ไฟล์ init.py

__init__.py ระบุว่าไดเรกทอรีเป็นแพ็กเกจที่นำเข้าได้ และจะทำงานเมื่อมีการนำเข้าแพ็กเกจเป็นครั้งแรก นอกจากนี้ยังเป็นตำแหน่งสำหรับเปิดเผยส่วนติดต่อสาธารณะของแพ็กเกจด้วยการนำเข้าชื่อสำคัญ

แม้ __init__.py จะว่างเปล่า ก็เพียงพอที่จะทำให้เป็นแพ็กเกจได้

package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
    print(package_dir + '/' + f)
print('Importable as:', 'mypackage')

pyproject.toml คืออะไร

pyproject.toml คือไฟล์กำหนดค่ามาตรฐานเพียงไฟล์เดียว (PEP 518/621) สำหรับการจัดแพ็กเกจ Python สมัยใหม่ โดยเข้ามาแทนที่ setup.py แบบเดิมในโครงการส่วนใหญ่ และเครื่องมือสร้างจะเป็นผู้อ่านไฟล์นี้

ไฟล์นี้ใช้รูปแบบ TOML ซึ่งประกอบด้วยส่วนที่อยู่ในวงเล็บเหลี่ยมและบรรทัดในรูปแบบคีย์ = ค่า

ตาราง build-system

ตาราง [build-system] บอกเครื่องมือว่าต้องสร้างแพ็กเกจของคุณอย่างไร ตัวเลือกที่ใช้กันทั่วไปคือ:

requires = ['setuptools', 'wheel']
build-backend = 'setuptools.build_meta'

แบ็กเอนด์อื่น ๆ ได้แก่ Hatchling และ Flit แต่แนวคิดก็เหมือนกัน

ตาราง project

ตาราง [project] เก็บข้อมูลเมตา ได้แก่ name, version, description, authors, readme, requires-python และ dependencies ข้อมูลเหล่านี้คือสิ่งที่ผู้ใช้เห็นบน PyPI

ให้มองตารางนี้เป็นบัตรประจำตัวของแพ็กเกจ

project = {
    'name': 'mytool',
    'version': '0.1.0',
    'requires-python': '>=3.9',
    'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
    print(k, '=', v)

กฎการตั้งชื่อ

ชื่อแพ็กเกจต้องไม่ซ้ำกับชื่ออื่นบน PyPI และต้องเป็นไปตามกฎการทำให้ชื่อเป็นมาตรฐาน กล่าวคือไม่คำนึงถึงตัวพิมพ์เล็กใหญ่ และถือว่ายัติภังค์กับขีดล่างเหมือนกัน ตรวจสอบชื่อว่าว่างอยู่ก่อนตัดสินใจใช้ เพื่อหลีกเลี่ยงการชนกันตอนอัปโหลด

name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)

การประกาศสิ่งที่ต้องพึ่งพา

ระบุสิ่งที่ต้องพึ่งพาขณะทำงานไว้ใต้ dependencies พร้อมข้อกำหนดรุ่น เช่น 'requests>=2.28,<3' ส่วนส่วนเสริมที่เป็นตัวเลือกให้ระบุไว้ใต้ [project.optional-dependencies] และติดตั้งได้ด้วย pip install mytool[dev]

กำหนดข้อจำกัดให้ผ่อนปรนเท่าที่ปลอดภัย เพื่อให้แพ็กเกจของคุณทำงานร่วมกับแพ็กเกจอื่นได้

จุดเริ่มต้น

หากต้องการจัดส่งเครื่องมือบรรทัดคำสั่ง ให้เพิ่มรายการ [project.scripts] เช่น mytool = 'mypackage.cli:main' หลังติดตั้งแล้ว การพิมพ์ mytool จะเรียกใช้ฟังก์ชันนั้น วิธีนี้เป็นวิธีที่อินเทอร์เฟซบรรทัดคำสั่งอย่าง black หรือ pytest ใช้เปิดเผยคำสั่งของตน

การรวมไฟล์ที่ไม่ใช่โค้ด

ไฟล์ข้อมูล เช่น แม่แบบและ JSON จะไม่ถูกรวมโดยอัตโนมัติ ให้กำหนดข้อมูลแพ็กเกจในแบ็กเอนด์สำหรับสร้างแพ็กเกจ เพื่อให้ไฟล์ต่าง ๆ ถูกจัดส่งอยู่ภายในไฟล์แพ็กเกจ การลืมตั้งค่านี้เป็นสาเหตุที่พบบ่อยของข้อผิดพลาดประเภททำงานได้ในเครื่องแต่พังเมื่อติดตั้ง

การติดตั้งแบบแก้ไขได้สำหรับการพัฒนา

ระหว่างการพัฒนา ให้ติดตั้งแพ็กเกจในโหมดแก้ไขได้ด้วย pip install -e . การเปลี่ยนแปลงในซอร์สจะมีผลทันทีโดยไม่ต้องติดตั้งใหม่ วิธีนี้ต้องอาศัย pyproject.toml ที่กำหนดไว้อย่างถูกต้อง จึงเป็นอีกเหตุผลหนึ่งที่ควรตั้งค่าไฟล์นี้ตั้งแต่เนิ่น ๆ

การติดตั้งแบบแก้ไขได้ช่วยให้ได้รับผลตอบกลับเร็วที่สุดระหว่างปรับปรุงแพ็กเกจ

ตรวจสอบอย่างรวดเร็ว

ทดสอบความรู้เกี่ยวกับโครงสร้างโครงการ

สรุปทบทวน

คุณได้จัดโครงสร้างแพ็กเกจแล้ว:

ใช้โครงสร้าง src โดยมี __init__.py เป็นตัวระบุแพ็กเกจ
pyproject.toml คือไฟล์กำหนดค่ามาตรฐาน ซึ่งประกอบด้วย [build-system] และ [project]
ประกาศ name, version, requires-python และ dependencies
เพิ่มจุดเริ่มต้น [project.scripts] สำหรับอินเทอร์เฟซบรรทัดคำสั่ง และกำหนดข้อมูลแพ็กเกจ

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

บทเรียน “โครงสร้างโครงการและ pyproject.toml” ฟรีหรือไม่