Unduh cookie - Unduh Kode Sumber cookie

cookie

Kode Sumber AI

2024.08.19

Unduh

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

Kue

Template mesin fotokopi/cookiecutter untuk proyek Python baru berdasarkan panduan pengembang python ilmiah. Apa yang membuat ini berbeda dari templat lain untuk paket Python?

Hidup dengan Panduan Pengembangan Ilmiah-Python: Setiap keputusan didokumentasikan dengan jelas dan setiap alat yang dijelaskan, dan semuanya disinkronkan.
Sembilan backend yang berbeda untuk dipilih untuk paket bangunan.
Versi VCS opsional untuk sebagian besar backend.
Generasi template diuji dalam tindakan github menggunakan NOX.
Mendukung generasi dengan mesin fotokopi, cookiecutter, dan cruft.
Mendukung Tindakan GitHub Jika menargetkan URL github.com (default), dan menambahkan dukungan Gitlab CI eksperimental sebaliknya.
Termasuk beberapa backend yang dikompilasi menggunakan pybind11, dengan roda diproduksi untuk semua platform menggunakan cibuildwheel.
Menyediakan sp-repo-review untuk mengevaluasi repo yang ada terhadap pedoman, dengan versi webAssembly yang terintegrasi dengan panduan ini. Semua cek terkait silang.
Mengikuti praktik terbaik PYPA dan diperbarui secara berkala.

Pastikan Anda telah membaca panduan pengembangan ilmiah-python terlebih dahulu, dan mungkin menggunakannya pada satu atau dua proyek. Ini bukan contoh atau tutorial minimal. Ini adalah kumpulan alat yang berguna untuk memulai proyek baru menggunakan cookiecutter, atau untuk menyalin dalam file individual untuk proyek yang ada (dengan tangan, dari {{cookiecutter.project_name}}/ ).

Selama generasi Anda dapat memilih dari backend berikut untuk paket Anda:

Hatch: Ini menggunakan penetasan, pembangun modern dengan inklusi file yang bagus, dapat diperpanjang melalui plugin, dan pesan kesalahan yang baik. (Direkomendasikan untuk proyek Python murni)
Flit: Sistem build PEP 621 modern dan ringan untuk proyek Python murni. Mengganti setuptools, tidak ada manifest.in, setup.py, atau setup.cfg. Kurva belajar yang rendah. Mudah untuk bootstrap ke dalam distribusi baru. Sulit untuk disertakan file yang tepat, sedikit dukungan metadata dinamis.
PDM: Solusi all-in-one yang modern dan kurang berpendapat untuk proyek pendukung proyek Python murni. Menggantikan setuptools, venv/pipenv, pip, roda, dan benang. Mendukung PEP 621.
Puisi: Solusi all-in-one untuk proyek Python murni. Menggantikan setuptools, venv/pipenv, pip, roda, dan benang. Kurva belajar yang lebih tinggi, tetapi all-in-one. Membuat beberapa asumsi default yang buruk untuk perpustakaan. Satu-satunya dengan pyproject.toml config non-standar.
Setuptools: Sistem build klasik, tetapi dengan konfigurasi standar baru.
Pybind11: Ini adalah setuptools tetapi dengan ekstensi C ++ yang ditulis dalam pybind11 dan roda yang dihasilkan oleh cibuildwheel.
Proyek Scikit-Build: SCikit-Build (CMake) juga menggunakan PyBind11, menggunakan scikit-build-core. (Direkomendasikan untuk proyek C ++)
Meson-Python: Proyek meson juga menggunakan pybind11. (Tidak ada versi VCS)
Maturin: Pembangun Pep 621 untuk ekstensi biner karat. (Tidak ada versi VCS) (direkomendasikan untuk proyek karat)

Saat ini, pilihan terbaik mungkin menetas untuk proyek Python murni, dan scikit-build (seperti scikit-build-core + Pybind11 pilihan) untuk proyek biner.

Untuk menggunakan (versi mesin fotokopi modern)

Instal copier dan copier-templates-extensions . Menggunakan PIPX, itu:

pipx install copier
pipx inject copier copier-templates-extensions

Sekarang, jalankan mesin fotokopi untuk menghasilkan proyek Anda:

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

( <pkg> adalah jalur untuk menempatkan proyek baru. Jika mesin fotokopi sudah tua, gunakan --UNSAFE bukan --trust )

Anda akan mendapatkan pengalaman CLI yang lebih baik dengan validasi jawaban. Anda juga akan mendapatkan file .copier-answers.yml , yang akan memungkinkan Anda untuk melakukan pembaruan di masa mendatang.

CATATAN: Tambahkan --vcs-ref=HEAD untuk mendapatkan versi terbaru alih-alih versi tag terakhir; Kepala selalu lulus tes (dan itulah yang digunakan Cookiecutter).

Untuk menggunakan (versi cookiecutter klasik)

Pasang cookiecutter, idealnya dengan brew install cookiecutter Jika Anda menggunakan minuman, jika tidak dengan pipx install cookiecutter (atau pipx run ke perintah di bawah ini, dan lewati instalasi). Kemudian jalankan:

cookiecutter gh:scientific-python/cookie

Jika Anda menggunakan cookiecutter 2.2.3+, Anda akan mendapatkan deskripsi yang bagus untuk opsi seperti mesin fotokopi!

Untuk menggunakan (versi cruft klasik)

Anda juga dapat menggunakan Cruft, yang menambahkan pembaruan kemampuan untuk proyek cookiecutter. Pasang dengan pipx install cruft (atau Prepend pipx run ke perintah di bawah ini, dan lewati instalasi). Kemudian jalankan:

cruft create gh:scientific-python/cookie

Generasi pos

Periksa file pengaturan kunci, pyproject.toml , dan mungkin setup.cfg dan setup.py (contoh pybind11). Perbarui README.md . Perbarui juga dan tambahkan dokumen ke docs/ .

Ada beberapa contoh dependensi dan versi python minimum 3.9, jangan ragu untuk mengubahnya menjadi apa pun yang sebenarnya Anda butuhkan/inginkan. Ada juga struktur Backports dasar dengan contoh pengetikan kecil.

Komponen yang terkandung:

Tindakan GitHub menjalankan pengujian untuk generasi itu sendiri
- Menggunakan NOX sehingga pengembangan cookie dapat diperiksa secara lokal
Tindakan GitHub Deploy
- Backend C ++ termasuk roda cibuild untuk build roda
- Menggunakan PYPI Penerbit Penerbit Tepercaya
Dependabot menjaga tindakan terkini secara berkala, melalui permintaan tarik yang bermanfaat
Pemformatan ditangani oleh pra-komit
- Tidak ada alasan untuk tidak ketat pada proyek baru; Hapus apa yang tidak Anda inginkan.
- Termasuk mypy - pengetikan statis
- Termasuk ruff - pemformatan standar, linting dan otomatis
  - Menggantikan flake8, isort, pyupgrade, yesqa, pycln, dan puluhan plugin
- Termasuk pemeriksaan ejaan
Target Pylint Nox dapat digunakan untuk menjalankan Pylint, yang mengintegrasikan anotasi GHA
Folder Dokumen Sphinx siap-ready dan [docs] tambahan
Folder tes dan pytest [test] ekstra
Noxfile disertakan dengan beberapa target umum

Untuk pengembang:

Anda dapat menguji secara lokal dengan 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

Jika Anda tidak memiliki nox secara lokal, Anda dapat menggunakan PIPX, seperti pipx run nox sebagai gantinya.

Proyek serupa lainnya

Hypermodern-Python adalah proyek lain yang layak untuk dicoba dengan banyak kesamaan, seperti dokumentasi hebat untuk setiap fitur dan banyak alat yang sama yang digunakan. Ini memiliki serangkaian fitur yang sedikit berbeda, dan memiliki fokus yang lebih kuat pada tindakan GitHub - sebagian besar panduan kami dapat disesuaikan dengan sistem CI yang berbeda dengan cukup mudah jika Anda tidak ingin menggunakan GHA. Ini juga memaksa penggunaan puisi (alih -alih memiliki pilihan backend), dan tidak mendukung proyek yang dikompilasi. Saat ini membuang semua dependensi pembangunan ke dalam lingkungan bersama, menyebabkan waktu pemecahan yang lama dan peluang konflik yang tinggi. Ini juga tidak menggunakan pra-berkomitmen seperti yang dimaksudkan untuk digunakan. Ini juga memiliki sedikit kode khusus.

Sejarah

Banyak panduan, cookiecutter, dan repo-review dimulai sebagai bagian dari Scikit-hep. Proyek-proyek ini digabungkan, digeneralisasi, dan dikombinasikan dengan panduan NSLS-II selama KTT Pengembang Ilmiah-Python 2023.

SP-Repo-Review

sp-repo-review memberikan cek berdasarkan panduan pengembangan ilmiah-python di ilmiah-python/cookie untuk repo-review.

Alat ini dapat memeriksa gaya repositori. Gunakan seperti ini:

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

Ini akan menghasilkan daftar hasil - tanda -tanda hijau berarti aturan ini diikuti, Red X berarti aturannya tidak. Tanda peringatan kuning berarti bahwa cek itu dilewati karena cek yang diperlukan sebelumnya gagal. Beberapa cek akan gagal, tidak apa -apa - tujuannya adalah membawa semua masalah yang mungkin menjadi perhatian Anda, bukan untuk memaksa kepatuhan dengan cek sewenang -wenang. Akhirnya mungkin ada cara untuk menandai cek seperti yang diabaikan.

Misalnya, GH101 mengharapkan semua file tindakan Anda memiliki name: bidang. Jika Anda senang dengan nama berbasis file yang Anda lihat di CI, Anda harus merasa bebas untuk mengabaikan cek ini (cukup abaikan secara visual untuk saat ini, cara untuk menentukan cek yang diabaikan kemungkinan akan ditambahkan pada akhirnya).

Semua cek disebutkan setidaknya dalam beberapa cara dalam panduan pengembangan ilmiah-python. Anda harus membacanya terlebih dahulu - jika Anda tidak berusaha mengikutinya, beberapa cek mungkin tidak berfungsi. Misalnya, pedoman yang menentukan konfigurasi pytest ditempatkan di pyproject.toml . Jika Anda menempatkannya di tempat lain, maka semua cek Pytest akan dilewati.

Ini awalnya dikembangkan untuk scikit-hep sebelum pindah ke python ilmiah.

Cara lain untuk digunakan

Anda juga dapat menggunakan tindakan github:

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

Atau pra-komit:

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

Jika Anda menggunakan additional_dependencies untuk menambahkan lebih banyak plugin, seperti validate-pyproject , Anda juga harus menyertakan "repo-review[cli]" untuk memastikan persyaratan CLI disertakan.