python_packaging_example

Contoh Kemasan Python

Daftar isi

• Instruksi cara
• Latar belakang
• Tingkat tinggi
• Kemasan Proyek Python
  • Membangun paket
  • Mengunggah paket ke testpypi
  • Mengunggah paket ke pypi
  • Memperbarui paket secara manual
• Tindakan GitHub CI/CD Workflows
  • Mendirikan
  • Mengunggah ke TestPyPi melalui komit untuk master
  • Mengunggah ke PyPi melalui penandaan
• Menjalankan Pytest di Github CI/CD

---

Instruksi cara

• Untuk mengatur proyek baru dan membuat rilis, lihat rilis CI/CD dan PYPI

Latar belakang

Ini adalah contoh kerja yang menggunakan alur kerja GitHub Action CI/CD untuk menguji, membangun, dan mengunggah paket Python ke TestPyPi dan PYPI.

Saya membuat paket contoh ini dengan mengerjakan panduan ini;

• Kemasan Proyek Python
• Rilis Distribusi Paket Penerbitan Menggunakan Tindakan GitHub CI/CD Workflows
• Pytest dengan tindakan github

Sisa Readme menjelaskan untuk membuat proyek baru dengan cara yang sama.

Saat diatur;

• Tes dan Unggah ke TestPyPi terjadi ketika nomor versi paket diperbarui dan komit dibuat untuk cabang master
• Menguji dan mengunggah ke PYPI terjadi ketika komit ditandai
• Paket dapat diinstal menggunakan pip install example-package-grumbit

---

Tingkat tinggi

Pada tingkat tinggi, proses untuk menyiapkan kemasan proyek GitHub CI/CD, termasuk Pytesting, terlihat seperti ini;

1. Siapkan struktur file sesuai paket contoh ini, tetapi tinggalkan ./.github/workflows/publish-to-test-pypi.yml untuk saat ini.
2. Buat kemasan lokal bekerja
3. Dapatkan mengunggah ke TestPypi Bekerja
4. Dapatkan mengunggah ke PYPI yang bekerja
5. Tambahkan ./.github/workflows/publish-to-test-pypi.yml dan dapatkan github ci/cd berfungsi

---

Kemasan Proyek Python

Membangun paket

• Metadata paket dikonfigurasi di ./pyproject.toml
• Setelah dikonfigurasi, itu dapat dibangun dengan;

 cd < pacakges directory >
python3 -m venv .venv # Create the venv if it doesn't exist yet
source .venv/bin/activate
python3 -m pip install --upgrade pip setuptools wheel pip-tools pytest # Install the tools needed for the build tool
python3 -m pip install --upgrade build # Install the build tool itself
python3 -m build # build the package

Mengunggah paket ke testpypi

• Unggah paket untuk pengujian menggunakan;

python3 -m pip install --upgrade twine # Install the twine upload tool
python3 -m twine upload --repository testpypi dist/ * # Upload to TestPyPi
    # When prompted, the username is __token__ and the password is the TestPyPi global scope API token

• Setelah mengunggah paket, token API spesifik paket harus diatur dan disimpan di testpypi

• Periksa paket dapat diunduh dan digunakan dalam venv baru;

 cd < some new tmp directory >
python3 -m venv .venv 
source .venv/bin/activate
package_name= " example-package-grumBit "
python3 -m pip install --index-url https://test.pypi.org/simple/ --pre ${package_name}  # Check the package can be installed
python3 -c " from example_package_grumbit import example; print(example.add_one(1)) " # Check package functions

Mengunggah paket ke pypi

python3 -m twine upload dist/ * # Upload to PyPi
    # When prompted, the username is __token__ and the password is the PyPi global scope API token

• Setelah mengunggah paket, token API khusus paket harus diatur dan disimpan di PYPI

Memperbarui paket secara manual

• Setiap kali paket diperbarui, versi itu harus diperbarui di bagian [project] ./pyproject.toml, maka perlu dibangun kembali dan diunggah;

vs ./pyproject.toml
python3 -m build # build the package
python3 -m twine check dist/ * # check the package can be uploaded
python3 -m twine upload --repository testpypi dist/ * # test uploading using TestPyPi
python3 -m twine upload dist/ * # Upload to PyPi

---

Tindakan GitHub CI/CD Workflows

Mendirikan

• Jika proyek belum disinkronkan ke Github, jalankan;

 cd " <the project's directory> "
repo_name= " <the new repo's name> "
gh repo create " ${repo_name} " --private
git init
git add --all
git commit -m " init "
git branch -M master
git remote add origin [email protected]:grumBit/ ${repo_name} .git
git push -u origin master

• Jika cabang default bukan master , ubah di github, atau ubah .github/workflows/publish-to-test-pypi.yml .

• Tambahkan token API testpypi dan pypi ke repo

• Buka repo di GitHub menggunakan gh browse . Di browser, klik Settings -> Secrets -> Actions . Kemudian tambahkan dua rahasia baru yang disebut PYPI_API_TOKEN dan TEST_PYPI_API_TOKEN , dengan token API dibuat setelah mengunggah paket di atas

• Buat dan konfigurasikan .github/alur kerja/publish-to-test-pypi.yml Definisi alur kerja

  • NB: Contoh Paket ini publish-to-test-pypi.yml sudah memiliki bagian yang diperlukan untuk pengujian otomatis (lihat di bawah)

Mengunggah ke TestPyPi melalui komit untuk master

• Setiap kali komit dibuat untuk cabang master , GitHub CI/CD akan berjalan.
  • NB: Agar kemasannya berhasil, versi harus diperbarui di ./pyproject.toml.
• Semua komitmen untuk dikuasai akan diunggah ke TestPyPi

Mengunggah ke PyPi melalui penandaan

• Menempatkan tag pada komit dan mendorongnya akan menyebabkan GitHub CI/CD berjalan dan membuat rilis PYPI.

• Gunakan yang berikut untuk menandai komit terakhir (yaitu HEAD ) dengan versi yang saat ini dikonfigurasi di ./pyproject.toml ;

version_tag=v $( cat ./pyproject.toml | egrep " ^version " | cut -d ' " ' -f2 )
version_tag_info= " Some release info "
git tag -a " ${version_tag} " -m " ${version_tag_info} "
git push --tag

• Gunakan yang berikut untuk menandai komit sebelumnya;

version_tag= " vX.X.X "
version_tag_info= " Some release info "
commit_sha= " 16fb0fd "
git tag -a " ${version_tag} " " ${commit_sha} " -m " ${version_tag_info} "
git push --tag

---

Menjalankan Pytest di Github CI/CD

• Langkah -langkah alur kerja dalam panduan GitHub CI/CD tidak termasuk menjalankan Pytests. Untuk mendapatkan Pytest untuk menjalankan dependensi paket yang perlu diinstal dan kemudian dijalankan Pytest sebelum langkah build menggunakan langkah -langkah tambahan ini;

    - name : Install requirements
      run : >-
        python -m
        pip install
        --requirement requirements.txt
    - name : Run tests
      run : >-
        python -m
        pytest

• Sesuai struktur direktori dalam Panduan Proyek Pengemasan, saya melakukan tes dalam hierarki terpisah ke sumbernya. Ini berarti __init__.py perlu ditambahkan ke src/ dan tests/ direktori seperti ini;
  • NB: Saya tidak 100% yakin tentang penataan ini. Ini mengikuti panduan ini dan berarti kode uji tidak dikemas, namun, saya pikir itu kurang nyaman daripada menanamkan test/ folder di dalam src/ Tree. ./pyproject.toml dapat dikonfigurasi sehingga test/ folder tertanam dikecualikan, tetapi saya sudah menggunakan "standar" untuk saat ini.

packaging_tutorial/
├── src/
│   ├── __init__.py
│   └── example_package_grumbit/
│       ├── __init__.py
│       └── example.py
└── tests/
    ├── __init__.py
    └── example_package_grumbit/
        ├── __init__.py
        └── test_example.py