ดาวน์โหลด cookie - ดาวน์โหลดซอร์สโค้ด cookie

cookie

โค้ดแหล่งที่มา AI

2024.08.19

ดาวน์โหลด

Scientific Python: Guide, Cookie, & SP-Repo-Review

คุกกี้

เทมเพลตเครื่องถ่ายเอกสาร/cookiecutter สำหรับโครงการ Python ใหม่ตามคู่มือนักพัฒนา Python Scientific อะไรทำให้สิ่งนี้แตกต่างจากเทมเพลตอื่น ๆ สำหรับแพ็คเกจ Python?

ใช้ชีวิตกับคู่มือการพัฒนาวิทยาศาสตร์-พงศาวดาร: การตัดสินใจทุกครั้งจะได้รับการบันทึกไว้อย่างชัดเจนและเครื่องมือทุกอย่างที่อธิบายไว้และทุกอย่างจะถูกเก็บไว้ในการซิงค์
แบ็กเอนด์ที่แตกต่างกันเก้ารายการให้เลือกสำหรับการสร้างแพ็คเกจ
การกำหนดเวอร์ชัน VCS เสริมสำหรับแบ็กเอนด์ส่วนใหญ่
การสร้างเทมเพลตที่ทดสอบในการกระทำของ GitHub โดยใช้ NOX
รองรับการสร้างด้วยเครื่องถ่ายเอกสาร, CookieCutter และ Cruft
รองรับการกระทำของ GitHub หากกำหนดเป้าหมาย URL github.com (ค่าเริ่มต้น) และเพิ่มการสนับสนุน Gitlab CI ทดลองเป็นอย่างอื่น
รวมแบ็กเอนด์ที่รวบรวมไว้หลายรายการโดยใช้ PyBind11 พร้อมล้อที่ผลิตสำหรับทุกแพลตฟอร์มโดยใช้ Cibuildwheel
จัดเตรียม sp-repo-review เพื่อประเมิน repos ที่มีอยู่กับแนวทางด้วยเวอร์ชัน WebAssembly ที่รวมเข้ากับคู่มือ ตรวจสอบทั้งหมดข้ามลิงค์
ปฏิบัติตามแนวทางปฏิบัติที่ดีที่สุดของ PYPA และอัปเดตเป็นประจำ

ตรวจสอบให้แน่ใจว่าคุณได้อ่านคู่มือการพัฒนาทางวิทยาศาสตร์ Python ก่อนและอาจใช้พวกเขาในโครงการหรือสองโครงการ นี่ ไม่ใช่ ตัวอย่างน้อยที่สุดหรือการสอน มันเป็นชุดของเครื่องมือที่มีประโยชน์สำหรับการเริ่มต้นโครงการใหม่โดยใช้ CookieCutter หรือสำหรับการคัดลอกในแต่ละไฟล์สำหรับโครงการที่มีอยู่ (ด้วยมือจาก {{cookiecutter.project_name}}/ )

ในระหว่างการสร้างคุณสามารถเลือกจากแบ็กเอนด์ต่อไปนี้สำหรับแพ็คเกจของคุณ:

Hatch: สิ่งนี้ใช้การฟักตัวผู้สร้างที่ทันสมัยพร้อมการรวมไฟล์ที่ดีขยายได้ผ่านปลั๊กอินและข้อความแสดงข้อผิดพลาดที่ดี (แนะนำสำหรับโครงการ Pure Python)
Flit: ระบบสร้าง PEP 621 ที่ทันสมัยและมีน้ำหนักเบาสำหรับโครงการ Python บริสุทธิ์ แทนที่ setuptools ไม่มี manifest.in, setup.py หรือ setup.cfg เส้นโค้งการเรียนรู้ต่ำ ง่ายต่อการบูตในการแจกแจงใหม่ ยากที่จะได้รับไฟล์ที่ถูกต้องรองรับข้อมูลเมตาดาต้าแบบไดนามิกเล็ก ๆ น้อย ๆ
PDM: โซลูชันที่ทันสมัยและมีความคิดเห็นน้อยลงสำหรับโครงการ Python บริสุทธิ์ที่สนับสนุนมาตรฐาน แทนที่ setuptools, venv/pipenv, pip, ล้อและเส้นใหญ่ รองรับ PEP 621
บทกวี: โซลูชัน all-in-one สำหรับโครงการ Python บริสุทธิ์ แทนที่ setuptools, venv/pipenv, pip, ล้อและเส้นใหญ่ เส้นโค้งการเรียนรู้ที่สูงขึ้น แต่เป็นแบบทั้งหมด ทำให้สมมติฐานเริ่มต้นที่ไม่ดีสำหรับไลบรารี คนเดียวที่มี pyproject.toml config ที่ไม่ได้มาตรฐาน
Setuptools: ระบบบิลด์แบบคลาสสิก แต่ด้วยการกำหนดค่ามาตรฐานใหม่
pybind11: นี่คือ setuptools แต่มีส่วนขยาย C ++ ที่เขียนใน pybind11 และล้อที่สร้างโดย cibuildwheel
Scikit-Build: โครงการ Scikit-Build (CMake) ใช้ PyBind11 โดยใช้ Scikit-Build-Core (แนะนำสำหรับโครงการ C ++)
Meson-Python: โครงการ Meson ยังใช้ pybind11 (ไม่มีเวอร์ชัน VCS)
Maturin: A Pep 621 Builder สำหรับส่วนขยายไบนารีสนิม (ไม่มีเวอร์ชัน VCS) (แนะนำสำหรับโครงการสนิม)

ปัจจุบันตัวเลือกที่ดีที่สุดคือการฟักสำหรับโครงการ Pyr Python และ Scikit-Build (เช่นตัวเลือก Scikit-Build-Core + Pybind11) สำหรับโครงการไบนารี

ใช้ (รุ่นเครื่องถ่ายเอกสารสมัยใหม่)

ติดตั้ง copier และ copier-templates-extensions ใช้ pipx นั่นคือ:

pipx install copier
pipx inject copier copier-templates-extensions

ตอนนี้เรียกใช้เครื่องถ่ายเอกสารเพื่อสร้างโครงการของคุณ:

copier copy gh:scientific-python/cookie < pkg > --trust

( <pkg> เป็นเส้นทางที่จะวางโครงการใหม่หากเครื่องถ่ายเอกสารเก่าใช้ --UNSAFE ใช้ความปลอดภัยแทน --trust )

คุณจะได้รับประสบการณ์ CLI ที่ดีกว่าด้วยการตรวจสอบคำตอบ นอกจากนี้คุณยังจะได้รับไฟล์ .copier-answers.yml ซึ่งจะช่วยให้คุณสามารถทำการอัปเดตในอนาคต

หมายเหตุ: เพิ่ม --vcs-ref=HEAD เพื่อรับเวอร์ชันล่าสุดแทนที่จะเป็นเวอร์ชันที่ติดแท็กล่าสุด หัวผ่านการทดสอบเสมอ (และเป็นสิ่งที่ Cookiecutter ใช้)

ใช้ (เวอร์ชัน cookiecutter คลาสสิก)

ติดตั้ง CookieCutter โดยใช้กับ brew install cookiecutter ถ้าคุณใช้ Brew มิฉะนั้นจะติดตั้ง pipx install cookiecutter (หรือ pipx pipx run ไปยังคำสั่งด้านล่างและข้ามการติดตั้ง) จากนั้นเรียกใช้:

cookiecutter gh:scientific-python/cookie

หากคุณใช้ CookieCutter 2.2.3+ คุณจะได้รับคำอธิบายที่ดีสำหรับตัวเลือกเช่นเครื่องถ่ายเอกสาร!

ใช้ (เวอร์ชัน cruft คลาสสิก)

นอกจากนี้คุณยังสามารถใช้ Cruft ซึ่งเพิ่มความสามารถในการอัปเดตโครงการ CookieCutter ติดตั้งด้วย pipx install cruft (หรือ pipx run ไปยังคำสั่งด้านล่างและข้ามการติดตั้ง) จากนั้นเรียกใช้:

cruft create gh:scientific-python/cookie

การโพสต์รุ่น

ตรวจสอบไฟล์การตั้งค่าคีย์, pyproject.toml และ setup.cfg และ setup.py (ตัวอย่าง pybind11) อัปเดต README.md นอกจากนี้ยังอัปเดตและเพิ่มเอกสารลงใน docs/

มีตัวอย่างไม่กี่ตัวอย่างและรุ่นงูหลามขั้นต่ำ 3.9 อย่าลังเลที่จะเปลี่ยนเป็นสิ่งที่คุณต้องการ/ต้องการ นอกจากนี้ยังมีโครงสร้างพื้นฐานพื้นฐานที่มีตัวอย่างการพิมพ์เล็ก ๆ

ส่วนประกอบที่มีอยู่:

การกระทำของ GitHub เรียกใช้การทดสอบสำหรับรุ่นเอง
- ใช้ NOX เพื่อให้สามารถตรวจสอบการพัฒนาคุกกี้ได้ในพื้นที่
การดำเนินการของ GitHub
- แบ็กเอนด์ C ++ รวมถึง cibuildwheel สำหรับการสร้างล้อ
- ใช้การปรับใช้ผู้เผยแพร่ PYPI ที่เชื่อถือได้
Inderbot ช่วยให้การดำเนินการทันสมัยเป็นระยะ ๆ ผ่านคำขอดึงที่มีประโยชน์
การจัดรูปแบบที่จัดการโดย pre-commit
- ไม่มีเหตุผลที่จะไม่เข้มงวดในโครงการใหม่ ลบสิ่งที่คุณไม่ต้องการ
- รวมถึงการพิมพ์ mypy - แบบคงที่
- รวมถึง Ruff - การจัดรูปแบบมาตรฐาน, ผ้าสำลีและ autofixes
  - แทนที่ flake8, isort, pyupgrade, yesqa, pycln และปลั๊กอินหลายสิบตัว
- รวมถึงการตรวจสอบการสะกดคำ
สามารถใช้เป้าหมาย Pylint NOx เพื่อเรียกใช้ Pylint ซึ่งรวมคำอธิบายประกอบ GHA แบบบูรณาการ
โฟลเดอร์สฟิ [docs] ซ์ที่พร้อมแล้ว
โฟลเดอร์ทดสอบและ pytest [test] พิเศษ
noxfile รวมอยู่ในเป้าหมายทั่วไปบางประการ

สำหรับนักพัฒนา:

คุณสามารถทดสอบในพื้นที่ด้วย NOX:

# See all commands
nox -l

# Run a specific check
nox -s "lint(scikit-build)"

# Run a noxfile command on the project noxfile
nox -s "nox(hatch)" -- docs

หากคุณไม่มี nox ในเครื่องคุณสามารถใช้ PIPX เช่น pipx run nox แทน

โครงการอื่น ๆ ที่คล้ายกัน

Hypermodern-Python เป็นอีกโครงการหนึ่งที่ควรค่าแก่การตรวจสอบด้วยความคล้ายคลึงกันมากมายเช่นเอกสารที่ยอดเยี่ยมสำหรับแต่ละคุณสมบัติและเครื่องมือเดียวกันมากมายที่ใช้ มันมีชุดคุณสมบัติที่แตกต่างกันเล็กน้อยและให้ความสำคัญกับการกระทำของ GitHub - คู่มือส่วนใหญ่ของเราสามารถปรับให้เข้ากับระบบ CI ที่แตกต่างกันได้อย่างง่ายดายหากคุณไม่ต้องการใช้ GHA นอกจากนี้ยังบังคับให้ใช้บทกวี (แทนที่จะมีการเลือกแบ็กเอนด์) และไม่สนับสนุนโครงการที่รวบรวม ในปัจจุบันมันทิ้งการพัฒนาทั้งหมดในสภาพแวดล้อมที่ใช้ร่วมกันทำให้เกิดการแก้ปัญหาที่ยาวนานและโอกาสสูงของความขัดแย้ง นอกจากนี้ยังไม่ได้ใช้คอมมิวนิสต์ล่วงหน้าในแบบที่ตั้งใจจะใช้ นอกจากนี้ยังมีรหัสที่กำหนดเองเล็กน้อย

ประวัติศาสตร์

คู่มือมากมาย CookieCutter และ Repo-Review เริ่มต้นจากการเป็นส่วนหนึ่งของ Scikit-Hep โครงการเหล่านี้ถูกรวมเข้าด้วยกันและรวมกับคู่มือ NSLS-II ในระหว่างการประชุมสุดยอดนักพัฒนาวิทยาศาสตร์-Python ในปี 2566

SP-Repo-Review

sp-repo-review ให้การตรวจสอบตามคู่มือการพัฒนาทางวิทยาศาสตร์-Python ที่ Scientific-Python/Cookie สำหรับ Repo-Review

เครื่องมือนี้สามารถตรวจสอบสไตล์ของที่เก็บ ใช้เช่นนี้:

pipx run ' sp-repo-review[cli] ' < path to repository >

สิ่งนี้จะสร้างรายการผลลัพธ์ - เครื่องหมายเช็คมาร์กสีเขียวหมายความว่ามีการปฏิบัติตามกฎนี้ความหมายของ Red X หมายถึงกฎไม่ใช่ ป้ายเตือนสีเหลืองหมายความว่าเช็คถูกข้ามเนื่องจากการตรวจสอบที่ต้องการก่อนหน้านี้ล้มเหลว การตรวจสอบบางอย่างจะล้มเหลวไม่เป็นไร - เป้าหมายคือการนำปัญหาที่เป็นไปได้ทั้งหมดมาสู่ความสนใจของคุณไม่ใช่เพื่อบังคับให้ปฏิบัติตามการตรวจสอบโดยพลการ ในที่สุดอาจมีวิธีการตรวจสอบการตรวจสอบที่ถูกละเว้น

ตัวอย่างเช่น GH101 คาดว่าไฟล์การกระทำทั้งหมดของคุณจะมี name: ฟิลด์ หากคุณมีความสุขกับชื่อที่ใช้ไฟล์ที่คุณเห็นใน CI คุณควรรู้สึกอิสระที่จะเพิกเฉยต่อการตรวจสอบนี้ (เพียงแค่มองไม่เห็นมันในขณะนี้วิธีการระบุการตรวจสอบที่ถูกละเว้นจะถูกเพิ่มในที่สุด)

การตรวจสอบทั้งหมดมีการกล่าวถึงอย่างน้อยในบางวิธีในคู่มือการพัฒนาวิทยาศาสตร์-Python คุณควรอ่านก่อน - หากคุณไม่ได้พยายามติดตามพวกเขาการตรวจสอบบางอย่างอาจไม่ทำงาน ตัวอย่างเช่นแนวทางระบุการกำหนดค่า pytest จะถูกวางไว้ใน pyproject.toml หากคุณวางไว้ที่อื่นการตรวจสอบ pytest ทั้งหมดจะถูกข้าม

สิ่งนี้ได้รับการพัฒนา แต่เดิมสำหรับ Scikit-Hep ก่อนที่จะย้ายไปที่ Scientific Python

วิธีอื่น ๆ ในการใช้งาน

คุณยังสามารถใช้การกระทำของ GitHub:

- uses : scientific-python/cookie@<version>

หรือล่วงหน้า:

- repo : https://github.com/scientific-python/cookie
  rev : <version>
  hooks :
    - id : sp-repo-review

หากคุณใช้ additional_dependencies เพื่อเพิ่มปลั๊กอินมากขึ้นเช่น validate-pyproject คุณควรรวม "repo-review[cli]" เพื่อให้แน่ใจว่าข้อกำหนดของ CLI จะรวมอยู่ด้วย