Útmutató az első Python programunk elkészítéséhez

Egy Python modul létrehozása többet igényel, mint csupán kódírást. A modern fejlesztés megfelelő eszközöket, szabványosított munkafolyamatokat és automatizálást követel meg. Ebben az útmutatóban végigvezetjük egy robusztus Python projekt beállításán, beleértve a tesztelést, a kódminőség-ellenőrzést (linting), a CI/CD folyamatokat és a PyPI-re történő publikálást. Akár egy segédkönyvtárat, akár egy teljes körű alkalmazást fejleszt, ezek a gyakorlatok egyszerűsítik a munkafolyamatát és biztosítják a karbantarthatóságot.

Röviden és tömören

Ez a cikk végigvezeti a Python fejlesztőket a professzionális modulok létrehozásán azáltal, hogy bemutatja az olyan alapvető lépéseket, mint a projektstruktúra beállítása a kulcsfájlokkal, a fejlesztési feladatok automatizálása, egységtesztek írása a pytest használatával, és a csomag biztonságos publikálása a PyPI-re a GitHub Actions segítségével. Ezen legjobb gyakorlatok követésével a fejlesztők robusztus és megosztható Python könyvtárakat/modulokat hozhatnak létre.

A fejlesztői környezet beállítása

Mielőtt belemerülne a modul létrehozásába, győződjön meg arról, hogy a Python telepítve van a fejlesztői gépén. Íme egy rövid útmutató a főbb operációs rendszerekhez:

Navigáljon a hivatalos Python weboldalra: https://www.python.org/downloads/ (új ablakban nyílik meg)
Töltse le a Python 3.13.3 legújabb stabil verzióját.

Windows

Futtassa a telepítőt, és ügyeljen arra, hogy a telepítés során bejelölje az Add Python to PATH opciót. Ez lehetővé teszi a Python parancsok futtatását a parancssorból. A telepítés után ellenőrizze a telepítést a PowerShell/CMD-ben a python --version paranccsal.

A Chocolatey telepítése

A Chocolatey leegyszerűsíti a Python fejlesztői környezet beállítását Windows rendszeren azáltal, hogy kényelmes módot kínál a lényeges fejlesztői eszközök telepítésére.

A Chocolatey telepítéséhez nyissa meg a PowerShellt rendszergazdaként, és futtassa a megadott telepítési parancsot.

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('http://internal/odata/repo/ChocolateyInstall.ps1'))

A Make telepítése Windows rendszeren

A make segédprogram egyszerű, automatizált telepítése és kezelése érdekében Windows rendszeren a Chocolatey segítségével telepítjük a make-et.

choco install make

Linux

Debian/Ubuntu

sudo apt update
sudo apt install python3 python3-pip

Fedora/CentOS/RHEL

sudo dnf install python3 python3-pip

Arch Linux

sudo pacman -S python python-pip

macOS

A macOS rendszeren a Python előre telepítve van, de gyakran egy régebbi verzió. Javasolt egy újabb verzió telepítése a hivatalos telepítő vagy egy csomagkezelő, például a Homebrew segítségével:

A hivatalos telepítő használatával: Lépjen a https://www.python.org/downloads/macos/ (új ablakban nyílik meg) oldalra, és töltse le a legújabb stabil verziót. Futtassa a telepítőt.

A Homebrew használatával (ha telepítve van)

brew update
brew install python@3

Előfordulhat, hogy módosítania kell a PATH környezeti változót, hogy a Homebrew által telepített Python élvezzen prioritást.

Alapvető fejlesztői eszközök

Telepítse ezeket globálisan vagy egy virtuális környezetben:

pip install setuptools wheel flake8 pytest black pylint

Kulcsfontosságú csomagok a modulfejlesztéshez

Egy professzionális Python modul létrehozásához számos alapvető csomagra lesz szüksége:

setuptools: Ez egy széles körben használt könyvtár Python projektek csomagolásához. Biztosítja a csomag és annak metaadatainak definiálásához szükséges eszközöket. Ön már megadta ezt a build backendként a pyproject.toml fájlban.
pytest: Egy hatékony és rugalmas tesztelési keretrendszer Pythonhoz. Leegyszerűsíti a tesztek írását és futtatását. Az Ön Makefile fájlja már használja a pytest-et.
typing-extensions: Ez a csomag új típusjegyzetek visszaportjait biztosítja régebbi Python verziókhoz. Az Ön pyproject.toml fájlja helyesen tartalmazza feltételes függőségként.
flake8: A PyFlakes, a pycodestyle és a McCabe köré épülő wrapper, amely a kód minőségének ellenőrzésére (linting) és annak biztosítására szolgál, hogy az megfeleljen a Python stíluskövetelményeinek (PEP 8). Az Ön Makefile fájlja a flake8-et használja a lintinghez.
black: Egy véleményvezérelt kódformázó, amely automatikusan konzisztens stílusra formázza a kódot. Bár nem feltétlenül szükséges, jelentősen javítja a kód olvashatóságát és csökkenti a stílusvitákat. Az Ön Makefile fájlja tartalmaz egy parancsot a black-kel történő formázáshoz.
pytest-cov: Egy pytest plugin a kódlefedettség mérésére. Az Ön Makefile fájlja ezt használja lefedettségi jelentések generálásához.

Projekt mappa struktúra

A jól definiált projektstruktúra elengedhetetlen a karbantarthatóság és az együttműködés szempontjából. Íme egy gyakori és ajánlott struktúra egy Python modulhoz:

  your_module_name/
    .github/
    └── workflows/
        ├── python-publish.yml
        └── tests.yml
    src/
    └── your_module_name/
        ├── __init__.py
        ├── core.py
    tests/
        ├── __init__.py
        ├── requirements.txt
        └── test_your_module_name.py
    .gitattributes
    .gitignore
    CHANGELOG.md
    LICENSE
    Makefile
    pyproject.toml
    README.md
    requirements.txt
    setup.py

Bontsuk le az egyes összetevőket

.github/

Cél: Ez a könyvtár a GitHub-specifikus, és a tárolójához tartozó különböző GitHub funkciók konfigurálására szolgál.
Jelentősége a Python modulfejlesztés szempontjából: Gyakori a GitHub használata a modul forráskódjának tárolására, a hibák nyomon követésére és a közreműködések kezelésére.

.github/workflows/

Cél: Ez a .github/ alkönyvtár YAML fájlokat tartalmaz, amelyek automatizált munkafolyamatokat definiálnak. Ezek a munkafolyamatok a GitHub tárolójában bekövetkező események (pl. kód feltöltése, pull request megnyitása) által aktiválódnak.
Jelentősége a Python modulfejlesztés szempontjából: Itt definiálja a Continuous Integration/Continuous Deployment (CI/CD) folyamatait.
- python-publish.yml: Ez a munkafolyamat valószínűleg automatizálja a Python modul közzétételének folyamatát egy csomagindexen, például a PyPI-n (Python Package Index), amikor új kiadást hoz létre (pl. egy commit címkézése). Ez magában foglalhatja a csomag összeállítását, a tesztek futtatását, majd a PyPI-re való feltöltését.
- tests.yml: Ez a munkafolyamat általában úgy van konfigurálva, hogy automatikusan lefuttassa a teszteket, amikor kódot töltenek fel a tárolóba, vagy pull requestet nyitnak. Ez biztosítja, hogy a kódváltoztatások ne okozzanak regressziót. Tartalmazhat kódminőség-ellenőrzést (linting) és formázási ellenőrzéseket is.

src/

Cél: Ez a könyvtár a modul tényleges forráskódjának szabványos helye.
Jelentősége a Python modulfejlesztés szempontjából: Egyértelműen elkülöníti a modul logikáját más projektfájloktól, például a tesztektől és a dokumentációtól.

src/your_module_name/

Cél: Ez az alkönyvtár, amely a modul nevéről kapta a nevét, a tényleges Python csomag.
Jelentősége a Python modulfejlesztés szempontjából: Ez a struktúra tisztább importálást tesz lehetővé a projekten belül és akkor is, amikor a felhasználók telepítik a modult.
- __init__.py: Ez a fájl a your_module_name könyvtárat Python csomaggá teszi. Lehet üres, vagy tartalmazhat kódot a csomag inicializálásához vagy bizonyos modulok vagy függvények legfelső szinten történő elérhetővé tételéhez.
- core.py: Ez egy példa egy Python fájlra, amely a modul alapvető logikáját tartalmazza. Itt több .py fájl is lehet, amelyek mindegyike a modul funkcionalitásának különböző aspektusaiért felelős.

tests/

Cél: Ez a könyvtár tartalmazza az egységteszteket.
Jelentősége a Python modulfejlesztés szempontjából: Átfogó tesztek írása elengedhetetlen a modul megbízhatóságának és helyességének biztosításához.
- __init__.py: A src könyvtárhoz hasonlóan ez a fájl a tests könyvtárat is Python csomaggá teszi, bár tesztcsomagokban kevésbé gyakori az inicializálásra való használata.
- test_your_module_name.py: Ez egy példa egy tesztfájlra. Tartalmazza a tényleges tesztfüggvényeket, amelyek ellenőrzik a src/your_module_name/ könyvtárban lévő kód viselkedését. Általában több tesztfájl is található, amelyek a modul különböző részeit fedik le.
- requirements.txt (a tests/ könyvtáron belül): Ez a fájl felsorolja a tesztek futtatásához szükséges specifikus Python csomagokat. Ide tartozhatnak olyan tesztelési keretrendszerek, mint a pytest, lefedettségi eszközök, mint a pytest-cov, és minden egyéb függőség, amely csak tesztelési célokra szükséges. Ez elkülönül a fő projekt requirements.txt fájljától.

.gitattributes

Cél: Ez a fájl megmondja a Gitnek, hogyan kezelje a soremeléséket és más fájlattribútumokat a tárolójában.
Jelentősége a Python modulfejlesztés szempontjából: Segít biztosítani a konzisztenciát a különböző operációs rendszerek (Windows, Linux, macOS) között, ahol a soremelések eltérően kezelődnek. Gyakori bejegyzés a text=auto eol=lf a LF (Line Feed) soremelések kényszerítéséhez.

.gitignore

Cél: Ez a fájl meghatározza azokat a szándékosan nem követett fájlokat, amelyeket a Gitnek figyelmen kívül kell hagynia.
Jelentősége a Python modulfejlesztés szempontjából: Megakadályozza, hogy ideiglenes fájlok, build-artefaktumok, környezetspecifikus konfigurációk (például virtuális környezet mappák) és más szükségtelen fájlok bekerüljenek a tárolójába.

CHANGELOG.md

Cél: Ez a fájl nyomon követi a modul minden verziójában végrehajtott változásokat.
Jelentősége a Python modulfejlesztés szempontjából: Elengedhetetlen a felhasználók számára, hogy megértsék, mi az új, a továbbfejlesztett vagy a javított az egyes kiadásokban. Ajánlott egy szabvány, például a Keep a Changelog követése.

LICENSE

Cél: Ez a fájl tartalmazza a licencet, amely alatt a modul terjesztésre kerül.
Jelentősége a Python modulfejlesztés szempontjából: Egy nyílt forráskódú licenc kiválasztása egyértelműen meghatározza a modul használatának, módosításának és terjesztésének feltételeit mások számára.

Makefile

Cél: Ez a fájl automatizálja a gyakori fejlesztési feladatokat a make segédprogram segítségével.
Jelentősége a Python modulfejlesztés szempontjából: Ahogy az előző cikkben tárgyaltuk, kényelmes módot kínál tesztek futtatására, kódminőség-ellenőrzésre, kód formázására, a csomag összeállítására és más ismétlődő feladatok egyszerű parancsokkal történő elvégzésére.

pyproject.toml

Cél: Ez a fájl a Python projektek build rendszer követelményeit határozza meg a PEP 518 szerint.
Jelentősége a Python modulfejlesztés szempontjából: Ez a modern szabvány a projekt metaadatainak, a build függőségeinek és az opcionális függőségek kezelésére. Sok esetben helyettesíti a különálló setup.py fájlt, ha egy build backenddel, például a setuptools-szal együtt használják.

README.md

Cél: Ez a fájl áttekintést nyújt a modulról, beleértve a célját, a telepítési útmutatót, a használati példákat és minden egyéb releváns információt.
Jelentősége a Python modulfejlesztés szempontjából: Ez az első kapcsolattartási pont a felhasználók és a közreműködők számára, amely alapvető információkat nyújt a modulról.

requirements.txt (a gyökérszinten)

Cél: Ez a fájl felsorolja a Python modul futásidejű függőségeit.
Jelentősége a Python modulfejlesztés szempontjából: Amikor a felhasználók telepítik a modult a pip install your_module_name paranccsal, a pip ezt a fájlt fogja használni a szükséges függőségek telepítéséhez. Bár a pyproject.toml a modern megközelítés a függőségek deklarálására, a requirements.txt még mindig gyakran használt, különösen a pontos verziók megadására a reprodukálhatóság érdekében. Ezt generálhatja a fejlesztői környezetéből, vagy karbantarthatja a pyproject.toml mellett.

setup.py

Cél: Történelmileg ez a fájl szolgált arra, hogy meghatározza, hogyan kell a modult telepíteni és terjeszteni a setuptools segítségével.
Jelentősége a Python modulfejlesztés szempontjából: Bár a pyproject.toml az ajánlott modern megközelítés, a setup.py még mindig megtalálható számos projektben, különösen azokban, amelyek még nem migráltak teljesen. Gyakran együttműködik a pyproject.toml fájllal, ha a setuptools van megadva build backendként.

Ez a részletes lebontás világos képet kell, hogy adjon a jól strukturált Python modulprojekt minden egyes összetevőjének céljáról és jelentőségéről. Ez a struktúra elősegíti a szervezettséget, a karbantarthatóságot és az együttműködést.

Feladatok automatizálása a `Makefile` segítségével

A Makefile egy olyan fájl, amelyet a make segédprogram használ, ami egy parancssori eszköz a build folyamatok automatizálására. A szoftverfejlesztésben gyakori, hogy ismétlődően végre kell hajtani bizonyos feladatokat, például tesztek futtatását, kódminőség-ellenőrzést, formázást, dokumentáció készítését vagy a szoftver telepítését. A Makefile ezeket a feladatokat "célokként" definiálja, és megadja az egyes célok végrehajtásához szükséges parancsokat. Ez számos előnnyel jár:

Automatizálás: Automatizálja az ismétlődő feladatokat, időt takarít meg a fejlesztőknek és csökkenti a hibák esélyét.
Konzisztencia: Biztosítja, hogy ezek a feladatok minden alkalommal következetesen kerüljenek végrehajtásra.
Hatékonyság: A make elég intelligens ahhoz, hogy csak akkor hajtsa végre újra a feladatokat, ha a függőségeik megváltoztak, így a folyamat hatékonyabbá válik.
Dokumentáció: Maga a Makefile is egyfajta dokumentációként szolgál, felvázolva a projekt gyakori fejlesztési parancsait.

Példa `Makefile`

.PHONY: test lint format install uninstall coverage help

# Alapértelmezett cél, ha csak a 'make' parancsot futtatjuk
help:
  @echo "Elérhető parancsok:"
  @echo "  make test         - Összes teszt futtatása"
  @echo "  make lint         - Kódminőség-ellenőrzés futtatása"
  @echo "  make format       - Kód formázása Black-kel (ha telepítve van)"
  @echo "  make coverage     - Tesztlefedettségi jelentés generálása"
  @echo "  make install      - Csomag telepítése"
  @echo "  make uninstall    - Csomag eltávolítása"
  @echo "  make check        - Lint és teszt futtatása"

test:
  pytest tests/

lint:
  flake8 src/ tests/

format:
  black src/ tests/ || echo "A Black nincs telepítve. Futtassa a 'pip install black' parancsot a formázás engedélyezéséhez."

coverage:
  pytest --cov=<your_module_name> tests/ --cov-report=term --cov-report=html
  @echo "HTML lefedettségi jelentés generálva az htmlcov/ könyvtárban"

install:
  pip install .

uninstall:
  pip uninstall -y <your_module_name>

check: lint test

A parancsok magyarázata

.PHONY: test lint format install uninstall coverage help: Ez a sor deklarálja, hogy a felsorolt célok nem tényleges fájlok, hanem végrehajtandó parancsok.
help: Ez az alapértelmezett cél. A make argumentumok nélküli futtatása ezt a parancsot hajtja végre, megjelenítve az elérhető parancsok hasznos listáját.
test: Lefuttatja az egységteszteket a pytest használatával.
lint: Statikus kódelemzést végez a flake8 segítségével a potenciális stílusproblémák és hibák azonosítására.
format: Automatikusan formázza a kódot, hogy az megfeleljen egy konzisztens stílusnak a black használatával. A || echo ... rész biztosítja, hogy ha a black nincs telepítve, a parancs ne hibásodjon meg, hanem ehelyett egy hasznos üzenetet írjon ki.
coverage: Teszteket futtat lefedettségi elemzéssel a pytest-cov használatával. Termináljelentést és HTML jelentést is generál az htmlcov/ könyvtárban, megmutatva, hogy a kód mely részeit fedik le a tesztek.
install: Telepíti a modult a pip használatával. A . az aktuális könyvtárra utal, ahol a setup.py (vagy a build utasításokat tartalmazó pyproject.toml) található.
uninstall: Eltávolítja a modult a pip használatával. A -y jelző automatikusan megerősíti az eltávolítást.
check: Sorrendben lefuttatja a lint és a test parancsokat, biztosítva, hogy a kód stilisztikailag helyes legyen és minden teszten átmenjen.

A Makefile használatához a make segédprogramnak telepítve kell lennie a rendszerén. Linux és macOS rendszereken ez általában alapértelmezés szerint elérhető. Windows rendszeren előfordulhat, hogy telepítenie kell egy build eszközcsomagot.

Projekt metaadatok kezelése a `pyproject.toml` fájllal

A pyproject.toml fájl a Python projektek build rendszer követelményeinek és projekt metaadatainak megadásának modern szabványa a PEP 518-ban meghatározottak szerint. Központi konfigurációs fájlként szolgál, amely megmondja a build eszközöknek, például a pip-nek és a build-nek, hogyan építsék fel a projektet és milyen függőségei vannak. Ez számos előnnyel jár:

Szabványosítás: Szabványosított módot kínál a Python projektek konfigurálására, megkönnyítve a különböző eszközök számára a megértést és az együttműködést.
Függőségkezelés: Lehetővé teszi a build-időbeli és a futásidejű függőségek egyetlen fájlban történő deklarálását.
Build Backend specifikáció: Meghatározza, hogy melyik build backendet (pl. setuptools, poetry-core) kell használni a projekt felépítéséhez.
Metaadatok tárolása: Központosítja a projekt metaadatait, mint például a név, verzió, szerzők, licenc és egyebek.
Bővíthetőség: Támogatja a különböző eszközök, például a linters és a formázók további konfigurációs szakaszait.

Példa `pyproject.toml` tartalom

[project]
authors = [
    {name = "your_name", email = "your_email"},
]
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Intended Audience :: Developers",
    "Intended Audience :: Information Technology",
    "Natural Language :: English",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Topic :: Software Development :: Libraries",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Topic :: Text Processing :: General",
    "Typing :: Typed",
    "Framework :: Pytest",
]
dependencies = [
    "typing-extensions>=4.0.0; python_version<'3.11'",
]
description = "<your_project_description>"
keywords = []
license = {text = "<your_license>"}
maintainers = [
    {name = "your_name", email = "your_email"},
]
name = "<your_module_name>"
readme = "README.md"
requires-python = ">=3.10"
version = "1.0.0"

[project.urls]
"Bug Tracker" = "https://github.com/.../<your_module_name>/issues"
"Change Log" = "https://github.com/.../<your_module_name>/blob/main/CHANGELOG.md"
"Github" = "https://github.com/.../<your_module_name>"
"Homepage" = "https://github.com/.../<your_module_name>"

[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools>=65.0.0", "wheel"]

[project.optional-dependencies]
test = [
    "pytest>=8.3.0",
    "pytest-cov>=4.1.0",
    "flake8>=7.0.0",
]

A kulcsfontosságú szakaszok magyarázata

[project]: Tartalmazza az alapvető projekt metaadatokat, mint például a név, verzió, szerzők, leírás, licenc, függőségek és egyebek.
[project.urls]: Hivatkozásokat tartalmaz a releváns projekt erőforrásokhoz.
[build-system]: Meghatározza a build backendet és annak követelményeit.
[project.optional-dependencies]: Opcionális függőségeket definiál, gyakran fejlesztéshez vagy teszteléshez használják.

A pyproject.toml használatával egy modernebb és szabványosított megközelítést alkalmaz a Python projekt konfigurációjának kezelésére.

Robusztus kód írása egységtesztekkel a `pytest` használatával

Egy megbízható Python modul létrehozása szigorú tesztelést igényel. Az egységtesztek a kód egyes komponenseinek funkcionalitásának ellenőrzésére összpontosítanak, biztosítva, hogy azok a várt módon viselkedjenek különböző feltételek mellett. A pytest egy népszerű és hatékony tesztelési keretrendszer, amely leegyszerűsíti az egységtesztek írásának és futtatásának folyamatát Pythonban.

Nézzünk egy gyakorlati példát a pytest használatával az Ön által megadott tesztkód alapján:

import pytest

class TestMyModuleFunction:
    def test_should_return_five(self):
        assert my_add_function(2, 3) == 5

A tesztek futtatása

Ezeknek a teszteknek a pytest segítségével történő futtatásához általában a projekt gyökérkönyvtárába kell navigálnia a terminálban, és végre kell hajtania a következő parancsot:

make test

A Makefile fájljában definiáltak szerint ez a parancs utasítja a pytest-et, hogy fedezze fel és futtassa az összes tesztfájlt (amelyek neve általában test_-vel kezdődik, és a tests könyvtárban található). A pytest ezután összefoglalja a tesztek eredményeit, jelezve, hogy mely tesztek sikerültek és melyek nem.

Az egységtesztelés előnyei

Korai hibafelismerés: A tesztek írása segít a hibák korai szakaszban történő azonosításában és javításában, mielőtt azok összetettebbé válnának és nehezebben lennének nyomon követhetők.
Kódbiztonság: Az átfogó egységteszt-csomag biztosítja, hogy a kód megfelelően működik, és a jövőbeni módosítások nem okoznak regressziót.
Élő dokumentáció: A tesztek dokumentációként is szolgálnak, bemutatva, hogy a modul különböző részeit hogyan kell használni.
Továbbfejlesztett tervezés: A tesztek írásának folyamata gyakran arra kényszeríti, hogy alaposabban átgondolja a kód tervezését, ami modulárisabb és jobban tesztelhető komponensekhez vezet.

Az egységtesztelés pytest-tel történő beépítésével a Python modulfejlesztési munkafolyamatába jelentősen javíthatja a kód minőségét és megbízhatóságát. Ne feledkezzen meg a különböző forgatókönyvek, beleértve a normál eseteket, a határeseteket és a potenciális hibahelyzeteket is lefedő tesztek írásáról.

A Python csomag közzététele a PyPI-n

Miután elkészített egy jól strukturált és alaposan tesztelt Python modult, a következő logikus lépés az, hogy megossza azt a szélesebb Python közösséggel a Python Package Indexre (PyPI) történő közzététellel. Ez lehetővé teszi más fejlesztők számára, hogy egyszerűen telepítsék és használják a modult a projektjeikben. Íme, hogyan teheti elérhetővé a csomagját a PyPI-n:

Mielőtt belevágna a közzétételi folyamatba, győződjön meg arról, hogy a helyi környezete rendben van:

Kód formázása: Futtassa a make format parancsot, hogy a kód megfeleljen a következetes stílusirányelveknek.
Kódminőség-ellenőrzés: Futtassa a make lint parancsot a potenciális stílusproblémák vagy hibák észleléséhez.
Egységtesztek futtatása: Ellenőrizze a modul funkcionalitását a make test futtatásával. Minden tesztnek sikeresnek kell lennie a folytatás előtt.
Változtatások feltöltése a GitHubra: Commitálja az összes változtatást, és töltse fel őket a távoli GitHub tárolójába.

Készüljön fel a PyPI-n való közzétételre

Regisztráció a PyPI-n: Ha még nem tette meg, hozzon létre egy fiókot a hivatalos PyPI weboldalon: https://pypi.org (új ablakban nyílik meg)

API token alapú hitelesítés beállítása

Ahhoz, hogy API tokeneket használhasson a GitHub Actions munkafolyamatából történő közzétételhez, létre kell hoznia egy API tokent a PyPI-n, és biztonságosan el kell tárolnia azt titkosként a GitHub tárolójában:

API token generálása a PyPI-n

API token alapú hitelesítés beállítása

Jelentkezzen be a PyPI fiókjába a https://pypi.org (új ablakban nyílik meg) oldalon.
Navigáljon a fiókbeállításokhoz: https://pypi.org/manage/account (új ablakban nyílik meg).
Keresse meg az API tokens (API tokenek) szakaszt.
Kattintson az Add API token (API token hozzáadása) gombra.
Töltse ki a Token name (Token neve) mezőt.
Válassza ki a token hatókörét. Közzétételhez általában a konkrét projekthez tartozó hatókört vagy az "Entire account" (Teljes fiók) lehetőséget választja, ha több csomagot is tervez közzétenni.
Kattintson a "Create token" (Token létrehozása) gombra.

Fontos: Másolja ki a generált tokent, és azonnal tárolja biztonságos helyen. Később már nem fogja látni.

Az API token hozzáadása GitHub tároló titkosként

Lépjen a Python modulhoz tartozó GitHub tárolójába.
Navigáljon a lap tetején található Settings (Beállítások) menüpontra.
A bal oldali oldalsávon kattintson a Secrets and variables (Titkok és változók), majd az Actions (Műveletek) menüpontra.
Kattintson a Repository secrets (Tároló titkok) szakaszra.
Kattintson a zöld New repository secret (Új tároló titok) gombra.
A Name (Név) mezőbe írja be: PYPI_API_TOKEN.
A Secret (Titok) mezőbe illessze be a PyPI-ról másolt API tokent.
Kattintson a zöld Add secret (Titok hozzáadása) gombra.

Most, hogy a PyPI API tokenjét titkosként tárolta a GitHub tárolójában, a GitHub Actions munkafolyamata felhasználhatja azt a PyPI-vel való hitelesítéshez a csomag feltöltési folyamata során. Biztosítania kell, hogy a python-publish.yml munkafolyamata úgy legyen konfigurálva, hogy ezt a titkot használja a hitelesítéshez ahelyett, hogy kizárólag a megbízható közzétevő beállításra támaszkodna (vagy alternatív módszerként).

Csomag közzététel beállítása a PyPI-n

Ezt a PyPI fiókjában kell konfigurálnia:

Jelentkezzen be a PyPI fiókjába a https://pypi.org (új ablakban nyílik meg) oldalon.
Navigáljon a Trusted Publisher Management (Megbízható közzétevő kezelése) beállításokhoz: https://pypi.org/manage/account/publishing (új ablakban nyílik meg).
Keresse meg az Add a new pending publisher (Új függőben lévő közzétevő hozzáadása) szakaszt.
Töltse ki az űrlapot a projekt részleteivel, és küldje be. Ez összekapcsolja a PyPI projektet a GitHub tárolójával és a megadott munkafolyamattal.
- PyPI Project Name (kötelező): your_module_name (Ennek meg kell egyeznie a pyproject.toml fájlban lévő név mezővel).
- Owner (kötelező): A GitHub szervezetének neve vagy a tárolót birtokló GitHub felhasználónév.
- Repository name (kötelező): A GitHub tárolójának neve (pl. your_module_name).
- Workflow name (kötelező): python-publish.yml (Ez a közzétételi munkafolyamat fájlneve a GitHub tárolójának .github/workflows/ könyvtárában).
- Environment name (opcionális): Itt megadhat egy GitHub Actions környezetnevet, ha beállított egyet a közzétételhez a tároló beállításaiban. Dedikált közzétételi környezet használata erősen ajánlott a fokozott biztonság érdekében.

Végső lépések a Python modul kiadásához

A PyPI és a GitHub beállításainak befejezése után a későbbi közzétételi folyamat a GitHub Actions segítségével automatizált. A kiadás elindításához:

Projekt feltöltése a GitHubra: Győződjön meg arról, hogy minden helyi változtatás commitálva és feltöltve van a távoli GitHub tárolójába.
Új kiadás létrehozása: A GitHub tárolójában hozzon létre egy új kiadást. Ez a művelet a konfigurált GitHub Actions munkafolyamat (pl. python-publish.yml) indítójaként szolgál.

Új kiadás létrehozásakor a GitHub Actions automatikusan végrehajtja a közzétételi munkafolyamatot. Ez a munkafolyamat jellemzően olyan feladatokat hajt végre, mint a csomag összeállítása, és ha az összes definiált ellenőrzés (beleértve a teszteket is) sikeres, és a pyproject.toml sikeresen ellenőrzésre került a PyPI-vel, akkor továbblép a csomag újonnan létrehozott kiadásának a PyPI-re való feltöltésére.

Miután a GitHub Actions munkafolyamat sikeresen befejeződött, a Python csomagja nyilvánosan elérhető lesz a PyPI-n. A fejlesztők ezután a szokásos pip parancs segítségével telepíthetik:

pip install your_module_name

A közzétett csomagját a PyPI-n a következő URL-címen találja meg: https://pypi.org/project/your_module_name/ (cserélje le a your_module_name-t a modul tényleges nevére).

Legjobb gyakorlatok

Verziókezelés: Használjon szemantikus verziókezelést a pyproject.toml fájlban.
Dokumentáció: Tartsa naprakészen a README.md és a CHANGELOG.md fájlokat.
Tesztelés: Futtassa a make check (lint + test) parancsot a commitok előtt.

Következtetés

Egy professzionális Python modul létrehozása többet jelent, mint csupán kódírást. Egy jól definiált projektstruktúra követésével, a feladatok automatizálásával olyan eszközökkel, mint a make, a metaadatok kezelésével a pyproject.toml segítségével, és az alapvető fejlesztői csomagok használatával robusztus, karbantartható és könnyen megosztható Python modulokat hozhat létre, amelyek mind a saját projektjeit, mind a szélesebb Python közösséget szolgálják. Alkalmazza ezeket a gyakorlatokat, és fejlesztheti Python fejlesztői készségeit, és maradandó hatást gyakorolhat a kódjával.

Kérdések

Egy jól definiált projektstruktúra javítja a szervezettséget, a karbantarthatóságot és az áttekinthetőséget. A forráskód src/ könyvtárba való elkülönítése megelőzi az importálási problémákat és megkönnyíti a csomagolást, míg egy dedikált tests/ mappa a tesztkódot elkülöníti a fő logikától.

A Makefile automatizálja a gyakori fejlesztési feladatokat, mint például a tests, linting, formatting, installing és uninstalling futtatását, időt takarít meg és biztosítja a projekt konzisztenciáját.

A pyproject.toml a projekt metaadatainak és a build rendszer konfigurációjának modern szabványa. Gyakran helyettesíti a setup.py fájlt. A requirements.txt elsősorban a futásidejű függőségeket sorolja fel, míg a pyproject.toml a build függőségeket is megadhatja.

Az egységtesztek ellenőrzik a kód egyes részeinek működését, segítve a hibák korai felismerését, növelve a kód iránti bizalmat, dokumentációként szolgálva és javítva a modul általános tervezését.

Egy tesztelési keretrendszer, például a pytest használatával általában a projekt gyökerébe navigálva a terminálban, és egy olyan parancsot végrehajtva, mint a make test (ha van konfigurálva Makefile) vagy közvetlenül a pytest tests/ használatával futtathatja a teszteket.

A cikk két fő módszert vázol fel: a PyPI megbízható közzétevői mechanizmusának használata a GitHub Actions-szel, valamint a PyPI API tokenek használata a hitelesítéshez egy GitHub Actions munkafolyamaton belül.

A PyPI API token (új ablakban nyílik meg) biztonságos alternatíva a jelszó használatával szemben a csomagok feltöltéséhez. Finomabb kontrollt kínál, és visszavonható, ha veszélybe kerül, növelve a PyPI fiókja biztonságát.

A GitHub Actions (új ablakban nyílik meg) használatával létrehozhat egy munkafolyamatot, amely automatikusan felépíti, teszteli és közzéteszi a csomagját a PyPI-n, valahányszor új kiadást hoz létre a GitHub tárolójában. Ez jelentősen leegyszerűsíti a kiadási folyamatot.

Röviden és tömören

A fejlesztői környezet beállítása

Windows

A Chocolatey telepítése

A Make telepítése Windows rendszeren

Linux

macOS

Alapvető fejlesztői eszközök

Kulcsfontosságú csomagok a modulfejlesztéshez

Projekt mappa struktúra

Bontsuk le az egyes összetevőket

.github/

.github/workflows/

src/

src/your_module_name/

tests/

.gitattributes

.gitignore

CHANGELOG.md

LICENSE

Makefile

pyproject.toml

README.md

requirements.txt (a gyökérszinten)

setup.py

Feladatok automatizálása a Makefile segítségével

Példa Makefile

A parancsok magyarázata

Projekt metaadatok kezelése a pyproject.toml fájllal

Példa pyproject.toml tartalom

A kulcsfontosságú szakaszok magyarázata

Robusztus kód írása egységtesztekkel a pytest használatával

A tesztek futtatása

Az egységtesztelés előnyei

A Python csomag közzététele a PyPI-n

Készüljön fel a PyPI-n való közzétételre

API token alapú hitelesítés beállítása

API token generálása a PyPI-n

Az API token hozzáadása GitHub tároló titkosként

Csomag közzététel beállítása a PyPI-n

Végső lépések a Python modul kiadásához

Legjobb gyakorlatok

Következtetés

Kérdések

Miért ajánlott egy specifikus projektstruktúra (például a src/ és tests/ könyvtárak beleértése) a Python modulokhoz?

Mi a Makefile célja egy Python projektben?

Hogyan viszonyul a pyproject.toml a setup.py-hoz és a requirements.txt-hez?

Miért fontosak az egységtesztek egy Python modul fejlesztésekor?

Hogyan futtatom általában egy Python modul egységtesztjeit?

Melyek a Python csomag PyPI-re történő közzétételének főbb módjai?

Mi az a PyPI API token, és miért lehet érdemes használnom a közzétételhez?

Hogyan automatizálhatom a Python csomagom PyPI-re történő közzétételének folyamatát?

Vágjunk bele közösen, és valósítsuk meg elképzeléseit – együtt!

Iratkozzon fel hírlevelünkre

Feladatok automatizálása a `Makefile` segítségével

Példa `Makefile`

Projekt metaadatok kezelése a `pyproject.toml` fájllal

Példa `pyproject.toml` tartalom

Robusztus kód írása egységtesztekkel a `pytest` használatával