Langkah-langkah untuk Mengatur dan Mengekalkan Pangkalan Kod Python Anda untuk Pemula

Sebab mengapa saya menulis siaran ini adalah untuk berkongsi beberapa cerapan tentang memastikan projek bersih, walaupun dengan ramai penyumbang. Ini amat penting untuk jurutera data, memandangkan sifat data yang sentiasa berubah dan permintaan pemprosesan dalam perpustakaan dan aplikasi Python.

Tajuknya mungkin kedengaran agak klik, tetapi jika anda mengikuti langkah ini, kod Python anda akan menjadi lebih mudah untuk diurus. Jika anda seorang pembangun kanan, anda mungkin tidak akan menemui sesuatu yang baharu di sini — jangan risau, saya ada meme lucu untuk anda.

Langkah 1: Kawalan Versi

Ini mungkin kelihatan remeh, tetapi saya sebenarnya mengenali orang yang menyimpan kod mereka hanya pada komputer tempatan mereka — dan malangnya kehilangannya kerana mereka tidak menyandarkannya di tempat lain. Terdapat beberapa sistem kawalan versi yang tersedia, seperti Git, yang berfungsi dengan platform seperti GitHub, GitLab dan Bitbucket. Walaupun Git adalah pilihan utama untuk kebanyakan orang, sistem kawalan versi lain seperti SVN (Subversion) dan Mercurial masih memainkan peranan penting dalam pengurusan kod.

Untuk panduan ini, saya bercadang untuk mencipta perpustakaan Python demo kecil dengan satu fungsi untuk menggambarkan pengendalian data asas. Ia tidak dimaksudkan untuk menjadi kit alat penuh tetapi berfungsi sebagai contoh mudah untuk menunjukkan amalan terbaik seperti kualiti kod, pengurusan persekitaran dan aliran kerja CI/CD.

Untuk bermula, saya telah mencipta repositori untuk perpustakaan Python demo kami, memanggilnya blog_de_toolkit. Ia terbuka, jadi jangan ragu untuk menolaknya dan gunakan kod sedia ada sebagai titik permulaan untuk projek anda sendiri. Oleh kerana dokumentasi yang baik adalah penting, saya telah memasukkan fail README kosong yang dicadangkan. Dan untuk memastikan repo kemas, saya menambah templat Python .gitignore lalai untuk mengelakkan fail yang tidak diperlukan daripada dimuat naik.

Sekarang kami mempunyai repo, kami boleh mengklonkannya.

Saya tidak akan menyelami arahan Git di sini — anda boleh menemui banyak tutorial dalam talian. Jika anda bukan peminat menggunakan terminal biasa CLI, anda juga boleh mengurus repositori dengan alatan seperti Desktop GitHub atau SourceTree, yang menyediakan antara muka yang lebih visual dan intuitif.

Secara peribadi, saya sangat seronok menggunakan Desktop GitHub. Jadi, mari kita mengklon repo kami ke komputer setempat dan membukanya dalam IDE pilihan anda.

Jom lihat apa yang kita ada setakat ini:

Tidak buruk untuk permulaan!

Langkah 2: Struktur Projek

Untuk Langkah 2, kami akan mengatur projek de_toolkit kami. Struktur yang baik memudahkan untuk mencari sesuatu dan memastikan semuanya kemas. Kami akan membuat folder untuk kod, ujian dan dokumentasi kami, menyediakan rangka kerja yang mudah dan bersih untuk dibina.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Kami mempunyai folder utama untuk semua kod berguna yang akan kami tambahkan, folder ujian untuk ujian unit masa hadapan kami dan .gitignore untuk menyimpan fail yang tidak diperlukan daripada repositori kami. Terdapat juga fail setup.py, yang merupakan persediaan asas untuk menjadikan projek itu boleh dipasang. Saya tidak akan menjelaskannya secara terperinci sekarang kerana kami akan membincangkannya kemudian dalam Langkah 8: Buat Pakej Pengedaran.

Apabila menyediakan struktur projek anda, mengekalkan perkara yang konsisten membuat perbezaan yang besar. Apabila projek anda berkembang, adalah idea yang baik untuk memecahkan perkara kepada modul yang lebih kecil — seperti membahagikan data_tools.py kepada csv_tools.py dan json_tools.py. Dengan cara ini, lebih mudah untuk mengurus dan mencari perkara yang anda perlukan tanpa menggali fail yang panjang.

Menambah folder dokumen/ juga merupakan langkah pintar, walaupun ia hanya bermula dengan beberapa nota. Ia akan membantu anda (dan orang lain) menjejaki cara perkara berfungsi semasa projek berkembang. Jika anda menggunakan konfigurasi seperti YAML atau JSON, folder konfigurasi/ boleh membantu memastikan keadaan sentiasa kemas. Dan jika anda merancang untuk menulis skrip untuk automasi atau ujian, folder skrip/ akan memastikannya teratur.

Pada ketika ini, kami perlu memasang beberapa perpustakaan tambahan untuk terus membina projek.

Langkah 3: Persekitaran Pembangunan

Pasti, kami hanya boleh menjalankan pemasangan pip dari baris arahan untuk memasang kebergantungan yang kami perlukan. Tetapi bagaimana jika kita menyulap berbilang projek, setiap satu memerlukan versi Python dan perpustakaan yang berbeza? Di situlah persekitaran maya masuk—mereka mengasingkan setiap kebergantungan projek, termasuk versi Python tertentu, supaya semuanya kekal serba lengkap dan bebas.

Nasib baik, terdapat beberapa alatan untuk mencipta persekitaran maya, jadi anda boleh memilih yang paling sesuai untuk anda:

• virtualenv

• venv

• konda

• pyenv

• pipenv

• puisi

Secara peribadi, saya peminat tegar pyenv, jadi itulah yang saya akan gunakan di sini. Saya telah memasangnya pada komputer riba saya kerana ia adalah pilihan saya untuk kerja dan projek peribadi.

Mari mulakan dengan memasang Python:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Jika pyenv tidak mengenali versi Python ini, cuba kemas kininya dahulu. Contohnya, jika anda menggunakan Mac dan memasang pyenv dengan Homebrew, jalankan:

pyenv install 3.12.2

Jika anda menghadapi ralat ModuleNotFoundError: Tiada modul bernama '_lzma', cuba:

brew update && brew upgrade pyenv

Seterusnya, dalam folder projek kami, mari buat persekitaran maya baharu:

brew install readline xz

Sekarang, tetapkan versi Python tempatan kepada persekitaran maya yang baru anda buat:

pyenv virtualenv 3.12.2 de_toolkit

Jika persekitaran tidak bertukar selepas menjalankan arahan pada MacOS, terdapat urutan berguna dalam talian dengan penyelesaian. Setelah semuanya disediakan dengan betul, anda seharusnya melihat de_toolkit pada permulaan baris arahan anda, seperti ini:

Sekarang, mari pasang kebergantungan kami:

pyenv local de_toolkit

Seterusnya, kami akan menyimpan semua pakej yang dipasang, bersama dengan versinya, ke dalam fail requirements.txt. Ini memudahkan untuk berkongsi kebergantungan projek atau mencipta semula persekitaran yang sama di tempat lain:

pip install setuptools wheel twine pandas 

Berikut ialah senarai pakej dipasang yang kami dapat:

Sudah tentu, anda boleh mengedit fail requirements.txt untuk menyimpan hanya perpustakaan utama dan versinya, jika anda mahu.

Langkah 4: Menguruskan Bukti kelayakan dan Rahsia

Langkah ini penting — mungkin salah satu yang paling penting. Anda mungkin pernah mendengar cerita seram tentang bukti kelayakan yang didedahkan dalam repositori GitHub atau token sensitif yang dikongsi secara tidak sengaja di khalayak ramai. Untuk mengelakkan ini, adalah penting untuk menyimpan maklumat sensitif daripada kod anda dari awal. Jika tidak, mudah untuk melupakan bahawa anda mengekodkan kata laluan pangkalan data, menolak perubahan anda dan meledak — bukti kelayakan anda kini terbuka.

Kata laluan pengekodan keras, kunci API atau bukti kelayakan pangkalan data ialah risiko keselamatan utama. Jika ini menjadikannya repo awam, mereka boleh menjejaskan keseluruhan sistem anda. Cara paling selamat untuk mengendalikan rahsia ialah dengan menyimpannya dalam pembolehubah persekitaran atau fail .env. Untuk membantu memuatkan pembolehubah ini ke dalam projek Python anda, kami akan menggunakan pustaka python-dotenv. Ia membaca pasangan nilai kunci daripada fail .env dan menjadikannya tersedia sebagai pembolehubah persekitaran dalam kod anda.

Mula-mula, pasang pustaka dengan:

pip freeze > requirements.txt

Buat fail .env dalam folder projek anda dengan kandungan berikut:

pip install python-dotenv

Sekarang, mari kita ubah suai data_tools.py untuk memuatkan rahsia ini menggunakan python-dotenv:

Apabila anda memanggil load_dotenv(), ia mencari fail .env dalam direktori semasa dan memuatkan kandungannya ke dalam persekitaran. Menggunakan os.getenv() membolehkan anda mengakses pembolehubah ini dengan selamat dalam kod anda, memastikan kelayakan diasingkan daripada kod sumber dan mengurangkan risiko pendedahan tidak sengaja.

Petua utama adalah untuk mengelak daripada menyerahkan fail .env anda kepada kawalan versi. Tambahkannya pada .giignore untuk mengelakkannya daripada ditolak secara tidak sengaja:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Jika anda menggunakan VSCode, terdapat sambungan dotenv yang berguna yang mengecam fail .env * anda secara automatik. Dan jika anda lebih suka bekerja dari terminal, anda boleh mengeksport *.env fail seperti ini:

pyenv install 3.12.2

Langkah 5: Menulis Kod

Semasa mengerjakan projek anda, cuba tulis fungsi kecil yang boleh diguna semula yang mudah difahami dan diurus. Peraturan praktikal yang baik ialah: “Jika anda menggunakannya lebih daripada dua kali, jadikan ia sebagai fungsi.”

Dalam data_tools.py kami, mari buat fungsi yang menunjukkan logik kejuruteraan data biasa—seperti memuatkan data daripada CSV dan membersihkannya:

Petua Pro: Berpegang pada snake_case

untuk fungsi dan nama pembolehubah dalam Python — ia memastikan kod anda konsisten dan mudah dibaca. Elakkan nama samar seperti x atau df2; nama yang jelas dan deskriptif menjadikan kod anda lebih mudah digunakan.

Kami menggunakan docstrings di sini untuk menerangkan fungsi fungsi, parameternya dan jenis pulangan. Ini memudahkan pembangun lain (dan diri masa depan anda) untuk memahami cara menggunakan fungsi tersebut. Terdapat beberapa konvensyen docstring yang popular, tetapi yang paling biasa termasuk PEP 257, Google Style dan NumPy Style:

Untuk fungsi yang lebih kecil, PEP 257 selalunya mencukupi, tetapi untuk projek yang lebih kompleks, gaya Google atau NumPy menawarkan lebih kejelasan dan struktur.

Taip petunjuk dalam Python, seperti file_path: str dalam contoh kami, tunjukkan jenis data yang dijangkakan untuk input dan output fungsi. Ia meningkatkan kebolehbacaan, membantu menangkap pepijat dan menjadikan kerjasama lebih mudah dengan menetapkan jangkaan yang jelas.

Berikut ialah contoh cara pembayang jenis meningkatkan tandatangan fungsi:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Dalam contoh ini, jenis petunjuk file_path: str menunjukkan bahawa hujah hendaklah rentetan, manakala -> pd.DataFrame menunjukkan bahawa fungsi mengembalikan Pandas DataFrame. Ini menjadikan gelagat fungsi mudah difahami sepintas lalu. Pembayang jenis juga berfungsi dengan baik dengan IDE dan linter, seperti PyCharm, VSCode atau mypy, menawarkan autolengkap dan amaran awal jika jenis yang tidak serasi diluluskan.

Jika fungsi boleh mengembalikan berbilang jenis atau Tiada, anda boleh menggunakan Pilihan daripada modul menaip:

pyenv install 3.12.2

Ini menunjukkan bahawa fungsi boleh mengembalikan sama ada rentetan atau Tiada. Untuk struktur data yang lebih kompleks, anda boleh menggunakan Senarai, Dict atau Tuple daripada modul menaip untuk menentukan jenis yang dijangkakan.

Langkah 6: Ujian Menulis

Menulis ujian unit ialah cara mudah untuk memastikan kod anda melakukan apa yang sepatutnya, tanpa kejutan yang tidak dijangka. Ia membantu anda menangkap pepijat lebih awal dan membuat perubahan dengan yakin, mengetahui semuanya masih berfungsi seperti yang diharapkan. Dalam Python, terdapat beberapa perpustakaan yang tersedia untuk ujian unit, masing-masing dengan kekuatan dan ekosistemnya:

• unittest

• pytest

• hidung2

• hipotesis

Untuk panduan ini, kami akan menggunakan pytest kerana ia ringkas, fleksibel dan mudah digunakan. Anda boleh memasangnya dengan:

brew update && brew upgrade pyenv

Seterusnya, buat fail bernama test_data_tools.py di dalam folder tests/. Mari tulis beberapa ujian untuk kod yang kami laksanakan sebelum ini. Berikut ialah contoh ujian untuk fungsi load_and_clean_data() kami dan logik perolehan pembolehubah persekitaran:

Dalam test_load_and_clean_data(), kami menggunakan StringIO untuk mensimulasikan fail CSV sebagai input. Ini membolehkan kami menguji tanpa memerlukan fail sebenar. Ujian itu mengesahkan bahawa fungsi itu mengalih keluar pendua dan nilai NaN dengan betul, menyemak bahawa DataFrame tidak mempunyai data yang hilang dan mengesahkan bahawa entri unik dalam lajur "nama" adalah betul.

Dalam test_get_database_url() dan test_get_api_key(), kami menggunakan monkeypatch, utiliti yang disediakan oleh pytest, untuk menetapkan sementara pembolehubah persekitaran semasa ujian. Ini memastikan fungsi mengembalikan nilai yang dijangkakan tanpa memerlukan pembolehubah persekitaran sebenar.

Untuk menjalankan semua ujian, hanya laksanakan arahan berikut:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Salah satu sebab saya suka pytest ialah fleksibilitinya. Ia melangkaui ujian unit asas dengan menawarkan ciri berkuasa seperti lekapan, ujian berparameter dan pemalam. Lekapan membolehkan anda menyediakan data ujian atau konfigurasi yang boleh digunakan semula oleh pelbagai ujian, yang memastikan kod anda KERING (Jangan Ulangi Sendiri). Ujian berparameter membolehkan anda menjalankan ujian yang sama dengan input yang berbeza, menjimatkan masa dan mengurangkan pertindihan. Dan jika anda perlu melanjutkan fungsi pytest, terdapat ekosistem pemalam yang luas untuk perkara seperti menguji apl Django, mengukur liputan kod atau mengejek permintaan HTTP.

Langkah 7: Kualiti Kod dan Cangkuk Pra-komit

Mengekalkan kualiti kod yang tinggi memastikan kod anda mudah dibaca, diselenggara dan bebas daripada pepijat biasa. Beberapa alatan boleh membantu menguatkuasakan piawaian pengekodan yang konsisten, memformat kod secara automatik dan mengesan isu yang berpotensi lebih awal. Beberapa pilihan popular termasuk pylint, serpihan8, hitam dan rahsia pengesan.

• pylint menguatkuasakan piawaian pengekodan dan menangkap ralat biasa.

• flake8 menggabungkan alatan untuk mengesan pelanggaran gaya dan ralat logik.

• hitam ialah pemformat pendapat yang memastikan kod anda mengikut piawaian PEP8.

• kesan-rahsia mengimbas kod anda untuk mengelakkan rahsia berkod keras daripada terdedah.

Anda boleh memasang alatan ini dengan:

pyenv install 3.12.2

Sebagai contoh, jalankan pylint pada fail atau direktori tertentu:

brew update && brew upgrade pyenv

Anda akan mendapat laporan dengan amaran dan cadangan untuk menambah baik kod anda. Untuk mengabaikan amaran tertentu, anda boleh menggunakan:

brew install readline xz

Anda juga boleh menggunakan flake8 untuk mencari isu gaya dan ralat logik:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Untuk memformat kod anda secara automatik, jalankan hitam:

pyenv install 3.12.2

Daripada menjalankan alatan ini secara manual setiap kali anda membuat perubahan, anda boleh mengautomasikan proses dengan cangkuk prakomit. Cangkuk prakomit berjalan secara automatik sebelum setiap komit, menyekat komit jika mana-mana alat gagal.

Mula-mula, pasang pakej pra-komit:

brew update && brew upgrade pyenv

Seterusnya, buat fail .pre-commit-config.yaml dalam direktori projek anda dengan kandungan berikut (di sini saya menggunakan semua pra-komit asas kegemaran saya):

Aktifkan cangkuk prakomit dalam repositori tempatan anda:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Kini, setiap kali anda cuba membuat komitmen, alatan ini akan berjalan secara automatik. Jika mana-mana alat gagal, komit akan disekat sehingga isu itu diselesaikan. Anda juga boleh menjalankan semua cangkuk secara manual merentasi pangkalan kod anda:

pyenv install 3.12.2

Langkah 8: Buat Pakej Pengedaran

Sekarang kami telah membina projek kami, menulis beberapa kod, menambah ujian dan menyediakan cangkuk prakomit, langkah seterusnya ialah memikirkan cara orang lain (atau masa depan kami) boleh menggunakannya dengan mudah. Pembungkusan projek menjadikannya mungkin. Ia membolehkan kami menggabungkan semuanya dengan kemas supaya ia boleh dipasang dan digunakan tanpa menyalin fail secara manual.

Untuk berkongsi projek anda, anda perlu menstruktur pakej dengan betul, menulis README yang bermakna, mencipta skrip permulaan dan menjana pakej pengedaran. README yang baik biasanya merangkumi nama projek dan penerangan ringkas tentang perkara yang dilakukannya, arahan pemasangan, contoh penggunaan, arahan pembangunan untuk menyediakan persekitaran dan garis panduan untuk menyumbang. Anda boleh mendapatkan contoh README.md yang mudah untuk projek blog_de_toolkit kami dalam repositori.

Di teras mana-mana pakej Python ialah fail setup.py. Fail ini adalah tempat kami mentakrifkan metadata dan konfigurasi yang diperlukan untuk membungkus dan memasang projek kami. Ia termasuk nama, versi dan penerangan projek, yang menjadikannya boleh dikenal pasti. long_description dibaca daripada fail README untuk memberi pengguna lebih banyak konteks tentang projek apabila mereka melihatnya pada PyPI. Kami menyatakan pergantungan dalam senarai install_requires supaya ia dipasang secara automatik bersama-sama dengan pakej. Bahagian entry_points mentakrifkan entri antara muka baris perintah (CLI), jadi pengguna boleh menjalankan alat dari terminal mereka. Kami menggunakan find_packages() untuk memasukkan semua submodul dalam pakej, dan bahagian pengelas menyediakan metadata, seperti versi Python dan lesen yang digunakan oleh projek. Akhir sekali, medan python_requires memastikan pakej dipasang hanya pada versi Python yang serasi.. Berikut ialah konfigurasi setup.py untuk projek blog_de_toolkit kami:

Setelah setup.py dikonfigurasikan, anda boleh membina pakej pengedaran. Mulakan dengan memasang alatan yang diperlukan dengan:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Kemudian bina pakej:

pyenv install 3.12.2

Arahan ini mencipta dua fail pengedaran:

• sdist: Arkib sumber (mis., .tar.gz)

• bdist_wheel: Pakej terbina (mis., .whl)

Fail ini akan terletak dalam direktori dist/. Untuk menguji pakej, pasangkannya secara setempat dengan:

brew update && brew upgrade pyenv

Anda juga boleh menguji arahan CLI dengan menjalankan:

brew install readline xz

nya hendaklah mencetak URL pangkalan data, kunci API dan data yang dibersihkan daripada sample_data.csv.

Jika anda ingin berkongsi pakej secara terbuka, anda boleh memuat naiknya ke PyPI. Mula-mula, pasang Twine:

pyenv virtualenv 3.12.2 de_toolkit

Kemudian muat naik pakej:

pyenv local de_toolkit

Anda akan digesa untuk memasukkan bukti kelayakan PyPI anda. Setelah dimuat naik, orang lain boleh memasang pakej anda terus daripada PyPI dengan:

pip install setuptools wheel twine pandas 

Langkah 10: Melindungi Cawangan Utama

Apabila projek anda berkembang, lebih ramai orang akan bekerja pada asas kod yang sama, selalunya pada masa yang sama. Tanpa perlindungan yang sewajarnya, kesilapan, kod yang belum diuji atau gabungan yang tidak disengajakan mudah menyelinap masuk dan mengacaukan keadaan. Untuk memastikan perkara berjalan lancar dan mengekalkan standard yang tinggi, melindungi cawangan utama menjadi penting. Dalam langkah ini, kami akan melihat cara menyediakan peraturan perlindungan cawangan dan berkongsi beberapa petua untuk menjalankan semakan kod yang lancar mengenai permintaan tarik.

Peraturan perlindungan cawangan pastikan tiada sesiapa boleh menolak terus ke cawangan utama tanpa lulus ujian atau mendapatkan semakan kod. Ini menghalang ciri yang belum selesai, pepijat atau kod buruk daripada menyelinap masuk dan memecahkan projek. Ia juga menggalakkan kerja berpasukan dengan memerlukan permintaan tarik, memberi peluang kepada orang lain untuk memberikan maklum balas. Selain itu, semakan automatik — seperti ujian dan linter — pastikan kod itu kukuh sebelum digabungkan.

Menyediakan peraturan perlindungan cawangan pada GitHub agak mudah. Pergi ke Tetapan repositori anda dan klik Cawangan di bawah bahagian "Kod dan automasi". Cari Peraturan perlindungan cawangan dan klik Tambah peraturan perlindungan cawangan. Masukkan utama dalam medan nama cawangan, dan kini tiba masanya untuk mengubah suai beberapa tetapan.

Anda boleh menetapkan peraturan perlindungan cawangan untuk memerlukan semakan permintaan tarik, memastikan seseorang menyemak kod sebelum ia digabungkan. Semakan status memastikan ujian lulus dan linter berjalan lancar, dan memastikan cawangan dikemas kini dengan perubahan terkini membantu mengelakkan konflik. Jika perlu, anda boleh menyekat siapa yang boleh menolak ke cawangan atau memerlukan komitmen yang ditandatangani untuk keselamatan tambahan. Setelah semuanya ditetapkan, klik Buat, dan begitu sahaja — tiada lagi tolakan langsung atau ujian yang dilangkau.

Apabila permintaan tarik anda siap untuk disemak, adalah idea yang baik untuk memudahkan perkara untuk pengulas anda. Mulakan dengan penerangan yang jelas tentang perkara yang dilakukan oleh perubahan anda dan sebab ia diperlukan. Gunakan mesej komitmen yang bermakna yang menggambarkan perkara yang telah dikemas kini. Jika perubahan adalah kecil dan tertumpu, proses semakan menjadi lebih lancar dan pantas. Jangan lupa untuk membalas ulasan dengan sopan dan membuat susulan pada perubahan yang diminta — ini menunjukkan bahawa anda menghargai maklum balas dan membantu memastikan kerjasama itu positif.

Jika anda yang menyemak permintaan tarik, tugas anda melangkaui hanya mencari kesilapan — ini tentang menambah baik kod dan menyokong rakan sepasukan anda. Mulakan dengan membaca huraian permintaan tarik untuk memahami perkara yang cuba dicapai oleh perubahan. Fokus pada memberi maklum balas yang membina — cadangkan alternatif jika perlu dan terangkan sebab ia mungkin berfungsi dengan lebih baik. Mengiktiraf kerja yang baik dengan ringkas "Nice refactor ?!" juga membantu mencipta pengalaman ulasan yang positif. Pantau ujian untuk memastikan ujian itu ada, relevan dan lulus. Dan jika ada sesuatu yang tidak jelas, tanya soalan dan bukannya membuat andaian. Pada penghujung hari, ulasan adalah tentang kerja berpasukan — bekerjasama untuk menjadikan projek itu lebih baik bersama-sama.

Menggunakan templat ulasan boleh membantu menjadikan proses lebih lancar dengan memastikan semua orang fokus pada perkara yang penting. Berikut ialah contoh templat semakan permintaan tarik:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Menambah templat seperti ini pada garis panduan penyumbang anda atau memautkannya dalam repositori memudahkan pengulas untuk terus berada di landasan yang betul. Ia juga memastikan perkara yang konsisten merentas ulasan, membantu pasukan mengekalkan asas kod yang bersih dan teratur.

Langkah 11: Tindakan GitHub untuk CI/CD

Berdasarkan kepentingan memastikan cawangan utama anda dilindungi, adalah penting juga untuk memastikan setiap perubahan kod diuji, disemak dan disahkan dengan betul sebelum menggabungkan atau menggunakannya. Di sinilah Integrasi Berterusan (CI) dan Penghantaran/Pengeluaran Berterusan (CD) dimainkan. CI/CD mengautomasikan proses menjalankan ujian, melakukan semakan kod dan melaksanakan perubahan, memberikan maklum balas pantas kepada pembangun dan mengurangkan peluang pepijat memasuki pengeluaran.

GitHub Actions ialah alat automasi yang disepadukan terus ke dalam GitHub. Ia membolehkan anda membuat aliran kerja yang bertindak balas kepada peristiwa dalam repositori anda, seperti permintaan tolak atau tarik. Dalam Tindakan GitHub, kami boleh mengautomasikan beberapa tugas utama untuk mengekalkan asas kod yang sihat. Contohnya:

• Menjalankan ujian apabila kod ditolak atau permintaan tarik dibuat, memastikan perubahan baharu tidak melanggar apa-apa.

• Menyemak gaya kod dan linting untuk menguatkuasakan standard pengekodan yang konsisten.

• Menggunakan cangkuk prakomit untuk memformat kod dan menangkap isu kecil seperti ruang mengekor.

• Menjana dokumentasi atau bahkan menggunakan kod apabila semua semakan lulus.

Mari sediakan aliran kerja GitHub Actions yang menjalankan ujian unit kami dan menggunakan linter prakomit (seperti hitam) apabila permintaan tolak atau tarik berlaku pada cawangan utama.

Mula-mula, buat fail aliran kerja:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

Ini kandungan untuk ci.yml:

Aliran kerja ini mengautomasikan ujian dan linting apabila kod ditolak atau permintaan tarik dibuka pada cawangan utama. Ia memastikan semua semakan kualiti diluluskan sebelum kod digabungkan. Tindakan/tindakan checkout mengklon repositori ke dalam pelari, dan kami menggunakan actions/setup-python untuk mengkonfigurasi Python 3.12 untuk aliran kerja. Ketergantungan dipasang daripada requirements.txt menggunakan pip. Selepas itu, semua ujian dijalankan dengan pytest, dan cangkuk prakomit memastikan kod mengikut garis panduan pemformatan dan gaya. Jika mana-mana ujian atau semakan gagal, aliran kerja berhenti untuk mengelakkan kod rosak daripada digabungkan.

Mari kita uji. Mula-mula, buat cawangan baharu daripada utama dan buat beberapa perubahan.

Dalam kes saya, saya mengemas kini fail README. Serahkan perubahan anda dan buka permintaan tarik ke dalam cawangan utama.

Kini anda akan melihat bahawa semakan diperlukan dan Tindakan GitHub (GA) sedang menjalankan semua semakannya. Walaupun penggabungan disekat oleh peraturan perlindungan cawangan, saya masih boleh “Gabung tanpa menunggu keperluan untuk dipenuhi” kerana kebenaran saya membenarkan memintas perlindungan.

Anda boleh menjejaki hasil aliran kerja GitHub Actions anda dalam tab Tindakan.

Berikut ialah contoh bagaimana langkah pytest kelihatan semasa larian:

Langkah 12: Versi Semantik (SemVer)

Menjejaki versi projek anda secara manual boleh menjadi tidak kemas, terutamanya apabila ia berkembang. Di situlah versi semantik (SemVer) masuk — ia mengikuti corak MAJOR.MINOR.PATCH untuk menyampaikan perkara yang telah berubah dalam setiap keluaran. Mengautomatikkan versi dengan python-semantic-release menjadikannya lebih mudah. Ia menganalisis mesej komit anda, menaikkan versi berdasarkan jenis perubahan, keluaran teg, dan juga boleh menerbitkan pakej anda ke PyPI jika anda mahu. Ini menghilangkan tekaan daripada pengurusan versi dan memastikan konsistensi.

Untuk versi lancar, anda boleh menyepadukan python-semantic-release terus ke dalam GitHub Actions. Dokumentasi rasmi menyediakan aliran kerja yang mengautomasikan bonggol dan keluaran versi apabila anda menolak ke cawangan utama. Dengan persediaan ini, proses keluaran menjadi lancar dan lepas tangan, jadi anda boleh menumpukan pada menulis kod tanpa perlu risau tentang mengurus versi secara manual.

Contoh Aliran Kerja Biasa — python-semantic-release

Untuk membuat ini berfungsi, mesej komit anda perlu mengikut piawaian komitmen konvensional. Setiap jenis komitmen menentukan sama ada versi akan menaik taraf PATCH, MINOR atau MAJOR tahap:

• pembetulan: Mencetuskan bonggol versi PATCH (cth., 1.0.0 → 1.0.1).

• feat: Mencetuskan bonjolan versi MINOR (mis., 1.0.0 → 1.1.0).

• PERUBAHAN MEMECAHKAN: atau ! dalam mesej komit mencetuskan bonggol versi UTAMA (cth., 1.0.0 → 2.0.0).

Dengan mengikuti konvensyen mudah ini, anda akan sentiasa tahu apa yang diharapkan dengan setiap versi baharu.

Kesimpulan

Kami telah merangkumi segala-galanya daripada mengatur projek anda dan mengurus rahsia untuk menulis ujian, mengautomasikan aliran kerja dan mengendalikan keluaran dengan versi semantik. Dengan alatan dan proses yang betul, membina projek yang boleh dipercayai dan boleh diselenggara menjadi lebih lancar — malah menyeronokkan.

Kuncinya adalah untuk kekal konsisten, mengautomasikan di mana anda boleh dan terus menambah baik semasa anda pergi. Setiap langkah kecil membuat perbezaan besar dari masa ke masa. Kini giliran anda — pergi bina, uji dan nikmati prosesnya! Cuba gunakan langkah ini pada projek anda yang seterusnya — dan jangan ragu untuk berkongsi pengalaman anda dalam ulasan!

Atas ialah kandungan terperinci Langkah-langkah untuk Mengatur dan Mengekalkan Pangkalan Kod Python Anda untuk Pemula. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!