example_pypi_package
v0.1.0
Ini adalah contoh paket PYPI (Python Package Index) yang diatur dengan tes otomatis dan alur kerja penerbitan paket menggunakan Github Action CI/CD. Ini dibuat terutama untuk pengguna GitHub + Vs Code (Windows / Mac / Linux) yang akan menulis dan mempublikasikan paket PYPI pertama mereka. Paket ini dapat berfungsi sebagai starter / boilerplate / demo dan tutorial dapat memberi Anda penjelasan cepat dan ringkas untuk memecahkan beberapa masalah kecil namun menjengkelkan yang mungkin Anda temui, seperti kebingungan nama paket / modul, dan masalah konfigurasi tes vs kode.
Paket contoh ini diilhami oleh / berdasarkan proyek sampel resmi PYPA / sampelProject, tetapi paket ini:
master atau cabang main , dan diterbitkan saat membuat rilisPYTHONPATH , sehingga file uji tidak memiliki kesalahan serat dan dapat dijalankan dengan pytest di vs code(Klik tombol di atas untuk menggunakan paket contoh ini sebagai templat untuk repo GitHub baru Anda, ini akan menginisialisasi repositori baru dan komit saya tidak akan ada dalam riwayat git Anda)
(Jika Anda tidak menggunakan GitHub, Anda dapat mengunduh arsip paket contoh)
Banyak yang menggunakan paket dan nama modul yang sama, Anda pasti bisa melakukannya. Tetapi paket contoh ini dan nama modulnya berbeda: example_pypi_package dan examplepy .
Buka folder example_pypi_package dengan kode studio visual, ctrl + shift + f (windows / linux) atau cmd + shift + f (macOS) untuk menemukan semua kemunculan kedua nama dan menggantinya dengan paket dan nama modul Anda. Juga ingat untuk mengubah nama folder src/examplepy .
Secara sederhana dan sangat kasar, nama paket digunakan dalam pip install <PACKAGENAME> dan nama modul digunakan dalam import <MODULENAME> . Kedua nama harus terdiri dari huruf kecil dasar (AZ). Mereka mungkin memiliki garis bawah ( _ ) jika Anda benar -benar membutuhkannya. Hyphen -minus ( - ) tidak boleh digunakan.
Anda juga harus memastikan URL "https://pypi.org/project/example-pypi-package/" (ganti example-pypi-package dengan nama paket Anda, dengan semua _ - ) tidak ditempati.
Underscore ( _ ) dapat digunakan tetapi penggunaan tersebut tidak dianjurkan. Angka dapat digunakan jika namanya tidak dimulai dengan angka, tetapi penggunaan tersebut juga berkecil hati.
Nama dimulai dengan angka dan/atau berisi tanda hubung ( - ) tidak boleh digunakan: walaupun secara legal secara teknis, nama tersebut menyebabkan banyak masalah - pengguna harus menggunakan importlib untuk mengimpornya.
Jangan tertipu oleh url "pypi.org/project/example-pypi-package/" dan nama "exampy-pypi-package" di pypi.org. pypi.org dan sistem PIP mengonversi semua _ ke - dan menggunakan yang terakhir di situs web / dalam perintah pip , tetapi nama asli masih dengan _ , yang harus digunakan pengguna saat mengimpor paket.
Ada juga namespace untuk digunakan jika Anda membutuhkan sub-paket.
Membuat perubahan yang diperlukan dalam setup.py .
Nomor versi paket __version__ ada di SRC/Examplepy/__ init__.py . Anda mungkin ingin mengubahnya.
Paket contoh dirancang agar kompatibel dengan Python 3.6, 3.7, 3.8, 3.9, dan akan diuji terhadap versi -versi ini. Jika Anda perlu mengubah rentang versi, Anda harus mengubah:
classifiers , python_requires di setup.pyenvlist dalam tox.inimatrix: python: dalam .github/alur kerja/test.yml Jika Anda berencana untuk mengunggah ke testpypi yang merupakan taman bermain PYPI untuk tujuan pengujian, ubah twine upload --repository pypi dist/* menjadi twine upload --repository testpypi dist/* dalam file .github/alur kerja/rilis.yml .
Pip adalah manajer paket Python. Anda sudah memiliki PIP jika Anda menggunakan Python 3.4 dan versi yang lebih baru yang menyertakannya secara default. Baca ini untuk mengetahui cara memeriksa apakah PIP diinstal. Baca ini jika Anda perlu menginstalnya.
Visual Studio Code adalah editor kode paling populer saat ini, paket contoh kami dikonfigurasi untuk bekerja dengan VS Code.
Instal VS Code Extension "Python".
Ekstensi kode "Python" vs akan menyarankan Anda menginstal Pylint. Juga, paket contoh dikonfigurasi untuk menggunakan pytest dengan ekstensi VS Code + Python, jadi, instal Pylint dan Pytest:
pip install pylint pytest(Kemungkinan Anda akan diminta untuk menginstalnya, jika itu masalahnya, Anda tidak perlu mengetik dan menjalankan perintah)
Konten vscode.env sekarang PYTHONPATH=/;src/;${PYTHONPATH} yang bagus untuk windows. Jika Anda menggunakan Linux atau MacOS, Anda perlu mengubahnya menjadi PYTHONPATH=/:src/:${PYTHONPATH} (mengganti ; dengan : . Jika jalur tidak diatur dengan benar, Anda akan melihat kesalahan serat dalam file uji dan Pytest tidak akan dapat menjalankan tes/tes _*. File PY dengan benar.
Tutup dan buka kembali vs kode. Anda sekarang dapat mengklik ikon Lab Flask di menu kiri dan menjalankan semua tes di sana, dengan Pytest. Pytest tampaknya lebih baik daripada kerangka kerja unittest standar, ini mendukung unittest sehingga Anda dapat terus menggunakan import unittest dalam file pengujian Anda.
Paket contoh juga memiliki file .editorconfig . Anda dapat menginstal VS Code Extension "EditorConfig untuk VS Code" yang menggunakan file. Dengan konfigurasi saat ini, alat EditorConfig dapat secara otomatis menggunakan spasi (4 spasi untuk .py, 2 untuk orang lain) untuk indentasi, atur encoding UTF-8 , LF garis, trim trailing whitespace dalam file non-markdown, dll.
Dalam VS Code, Anda dapat pergi ke File -> Preferensi -> Pengaturan, ketik "Penyedia Pemformatan Python" di kotak pencarian, dan pilih salah satu dari tiga alat pemformatan kode Python (Autopep8, Black dan YAPF), Anda akan diminta untuk menginstalnya. Pintasan untuk pemformatan file kode adalah Shift + Alt + F (Windows); Shift + opsi (alt) + f (macOS); Ctrl + Shift + I (Linux).
Dalam src/ examplepy/ ( examplepy seharusnya diganti dengan nama modul Anda) folder, ganti nama modul1.py dan tulis kode Anda di dalamnya. Tambahkan lebih banyak file .py Modul jika perlu.
Dalam tes/ folder, ganti nama test_module1.py (untuk menguji _*. Py ) dan tulis kode uji unit Anda (dengan unittest) di dalamnya. Tambahkan lebih banyak tes _*. File py jika Anda perlu.
Instal TOX dan jalankan:
pip install tox
tox Dalam konfigurasi kami, TOX menjalankan pemeriksaan distribusi sumber menggunakan check-manifest (yang mengharuskan repo Anda diinisialisasi git ( git init ) dan ditambahkan ( git add . ) Setidaknya), pemeriksaan setuptools, dan uji unit menggunakan pytest. Anda tidak perlu menginstal check-manifest dan pytest, TOX akan menginstalnya di lingkungan yang terpisah.
Tes otomatis dijalankan terhadap beberapa versi Python, tetapi pada mesin Anda, Anda mungkin hanya menggunakan satu versi Python, jika itu Python 3.9, lalu jalankan:
tox -e py39 Jika Anda menambahkan lebih banyak file ke direktori root ( example_pypi_package/ ), Anda harus menambahkan file Anda ke daftar check-manifest --ignore di TOX.ini .
Instal atau tingkatkan setuptools dan wheel :
python -m pip install --user --upgrade setuptools wheel (Jika python3 adalah perintah pada mesin Anda, ubah python menjadi python3 dalam perintah di atas, atau tambahkan garis alias python=python3 ke ~/.bashrc atau ~/.bash_aliases file jika Anda menggunakan bash di linux)
dist Dari Direktori example_pypi_package , jalankan perintah berikut, untuk menghasilkan versi produksi untuk distribusi sumber (SDIST) di folder dist :
python setup.py sdist bdist_wheelSecara opsional, Anda dapat menginstal versi Dist dari paket Anda secara lokal sebelum mengunggah ke PYPI atau TestPypi:
pip install dist/example_pypi_package-0.1.0.tar.gz(Anda mungkin perlu menghapus paket yang ada terlebih dahulu:
pip uninstall example_pypi_package Mungkin ada beberapa paket yang diinstal dengan nama yang sama, jadi jalankan pip uninstall beberapa kali sampai dikatakan tidak ada lagi paket untuk dihapus.)
Daftarkan akun di PYPI, buka Pengaturan Akun § Token API, "Tambahkan Token API". Token PYPI hanya muncul sekali, salin di suatu tempat. Jika Anda melewatkannya, hapus yang lama dan tambahkan token baru.
(Daftarkan akun testpypi jika Anda mengunggah ke testpypi)
Pada halaman repo GitHub yang baru Anda buat atau yang sudah ada, klik Pengaturan -> Rahasia -> Rahasia Repositori Baru , namanya harus PYPI_API_TOKEN dan nilainya harus menjadi token PYPI Anda (yang dimulai dengan pypi- ).
Paket contoh memiliki tes dan unggahan otomatis (penerbitan) yang sudah diatur dengan tindakan github:
git push atau permintaan tarik dikirimkan pada master atau cabang main Anda, paket secara otomatis diuji terhadap versi Python yang diinginkan dengan tindakan GitHub. Setelah paket Anda diterbitkan di PYPI, kunjungi https://pypi.org/project/example-pypi-package/ ( _ - ). Salin perintah pada halaman, jalankan untuk mengunduh dan menginstal paket Anda dari PYPI. (atau test.pypi.org jika Anda menggunakannya)
Jika Anda ingin memodifikasi deskripsi / readme paket Anda di pypi.org, Anda harus menerbitkan versi baru.
Instal atau tingkatkan benang:
python -m pip install --user --upgrade twineBuat file .pypirc di direktori $ home ( ~ ) Anda, kontennya harus:
[pypi]
username = __token__
password = <PyPI token> (Gunakan [testpypi] alih -alih [pypi] jika Anda mengunggah ke testpypi)
Ganti <PyPI token> dengan token PYPI asli Anda (yang dimulai dengan pypi- ).
(Jika Anda tidak secara manual membuat $ home/.pypirc , Anda akan diminta untuk nama pengguna (yang seharusnya __token__ ) dan kata sandi (yang seharusnya menjadi token pypi Anda) saat Anda menjalankan benang)
Jalankan benang untuk mengunggah semua arsip di bawah folder Dist :
python -m twine upload --repository pypi dist/ * (Gunakan testpypi alih -alih pypi jika Anda mengunggah ke testpypi)
Setelah Anda selesai mengembangkan versi paket Anda yang lebih baru, lakukan hal -hal berikut.
Ubah nomor versi __version__ dalam src example__init __. Py .
Hapus semua versi lama di Dist .
Jalankan perintah berikut lagi untuk meregenerasi Dist :
python setup.py sdist bdist_wheelJalankan perintah berikut lagi untuk mengunggah Dist :
python -m twine upload --repository pypi dist/ * (Gunakan testpypi alih -alih pypi jika diperlukan)
BTW, jika Anda ingin mempublikasikan paket TypeScript (JavaScript) ke NPM Registry, buka contoh paket TypeScript yang siap diterbitkan di NPM untuk 2021.
