Distribucija paketov Python: Objava na PyPI in upravljanje različic

Obsežen ekosistem Pythona poganja ogromna zbirka paketov, ki so na voljo preko indeksa paketov Python (PyPI). Ta vodnik ponuja celovit pregled distribucije lastnih paketov Python preko PyPI, s čimer zagotovite, da so dostopni razvijalcem po vsem svetu. Raziskali bomo bistvena orodja, najboljše prakse za upravljanje različic ter delovne tokove za ustvarjanje in objavljanje visokokakovostnih paketov Python.

Zakaj distribuirati svoj paket Python?

Distribucija vašega paketa Python ponuja številne prednosti:

• Deljenje vašega dela: Omogoča drugim razvijalcem, da enostavno ponovno uporabijo vašo kodo, kar spodbuja sodelovanje in inovacije. Predstavljajte si globalno ekipo, ki uporablja vaša specializirana orodja za analizo podatkov, zgrajena v Pythonu.
• Upravljanje odvisnosti: Poenostavi postopek upravljanja odvisnosti v drugih projektih. Vaš paket je mogoče namestiti z enim samim ukazom, skupaj z vsemi njegovimi odvisnostmi.
• Prispevek k odprti kodi: Omogoča vam, da prispevate k odprtokodni skupnosti in si pridobite priznanje za svoje delo. Številne ključne komponente programske opreme so odprtokodni paketi, ki jih vzdržujejo razvijalci po vsem svetu.
• Nadzor različic in posodobitve: Zagotavlja strukturiran način za upravljanje različic, izdajanje posodobitev in odpravljanje napak. To zagotavlja, da imajo uporabniki vedno dostop do najnovejše in najbolj zanesljive različice vašega paketa.
• Enostavna namestitev: Poenostavi namestitev za uporabnike z ukazom `pip install ime-vasega-paketa`.

Bistvena orodja za distribucijo paketov Python

Za ustvarjanje in distribucijo paketov Python je bistvenih več orodij:

• setuptools: Pogosto uporabljena knjižnica za definiranje metapodatkov paketa, vključno z imenom, različico, odvisnostmi in vstopnimi točkami. Je de facto standard za pakiranje projektov v Pythonu.
• wheel: Format za distribucijo, ki omogoča učinkovitejši in zanesljivejši postopek namestitve v primerjavi z distribucijami iz izvorne kode. "Wheels" so vnaprej zgrajene distribucije, ki jih je mogoče namestiti brez prevajanja.
• twine: Orodje za varno nalaganje vašega paketa na PyPI. Twine šifrira vaše poverilnice in podatke o paketu med prenosom, kar ščiti pred prisluškovanjem in napadi tipa "man-in-the-middle".
• venv/virtualenv: To sta orodji za ustvarjanje izoliranih okolij Python. Uporaba virtualnih okolij je ključnega pomena za upravljanje odvisnosti in preprečevanje konfliktov med različnimi projekti.

Priprava vašega projekta

Preden lahko distribuirate svoj paket, morate pravilno strukturirati svoj projekt.

Primer strukture projekta

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

Pojasnilo:

• my_package/: Glavna mapa, ki vsebuje izvorno kodo vašega paketa.
• my_package/__init__.py: Naredi mapo `my_package` za paket Python. Lahko je prazna ali vsebuje inicializacijsko kodo.
• my_package/module1.py, my_package/module2.py: Vaši moduli Python, ki vsebujejo dejansko kodo.
• tests/: Mapa, ki vsebuje vaše enotske teste. Pisanje testov je ključnega pomena za zagotavljanje kakovosti in zanesljivosti vašega paketa.
• README.md: Datoteka Markdown, ki vsebuje opis vašega paketa, navodila za uporabo in druge pomembne informacije. To je pogosto prva stvar, ki jo uporabniki vidijo na PyPI.
• LICENSE: Datoteka, ki vsebuje licenco, pod katero se distribuira vaš paket (npr. MIT, Apache 2.0, GPL). Izbira ustrezne licence je bistvena za določitev, kako lahko drugi uporabljajo vašo kodo.
• setup.py: Glavna konfiguracijska datoteka, ki določa metapodatke vašega paketa in navodila za gradnjo.
• .gitignore: Določa datoteke in mape, ki jih mora Git prezreti (npr. začasne datoteke, artefakti gradnje).

Ustvarjanje datoteke `setup.py`

Datoteka `setup.py` je srce distribucije vašega paketa. Vsebuje metapodatke o vašem paketu ter navodila za njegovo gradnjo in namestitev. Tukaj je primer:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # Zamenjajte z imenom vašega paketa
    version="0.1.0",
    author="Vaše Ime",  # Zamenjajte s svojim imenom
    author_email="vas.email@example.com", # Zamenjajte s svojim e-poštnim naslovom
    description="Majhen primer paketa",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # Zamenjajte z URL-jem vašega repozitorija
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # Primer odvisnosti
    ],
)

Pojasnilo:

• name: Ime vašega paketa, ki se bo uporabljalo na PyPI. Izberite edinstveno in opisno ime.
• version: Številka različice vašega paketa. Sledite semantičnemu različiciranju (glejte spodaj).
• author, author_email: Vaše ime in e-poštni naslov.
• description: Kratek opis vašega paketa.
• long_description: Daljši, podrobnejši opis, običajno prebran iz vaše datoteke `README.md`.
• long_description_content_type: Določa obliko vašega dolgega opisa (npr. "text/markdown").
• url: URL domače strani vašega paketa (npr. repozitorij na GitHubu).
• packages: Seznam paketov, ki jih želite vključiti v svojo distribucijo. `setuptools.find_packages()` samodejno odkrije vse pakete v vašem projektu.
• classifiers: Metapodatki, ki uporabnikom pomagajo najti vaš paket na PyPI. Izberite ustrezne klasifikatorje s seznama klasifikatorjev Trove. Razmislite o vključitvi klasifikatorjev za podprte različice Pythona, operacijske sisteme in licence.
• python_requires: Določa minimalno različico Pythona, potrebno za uporabo vašega paketa.
• install_requires: Seznam odvisnosti, ki jih vaš paket potrebuje. Te odvisnosti se bodo samodejno namestile ob namestitvi vašega paketa.

Upravljanje različic: Semantično različiciranje

Semantično različiciranje (SemVer) je široko sprejeta shema različiciranja, ki zagotavlja jasen in dosleden način sporočanja narave sprememb v vašem paketu.

Številka različice SemVer je sestavljena iz treh delov: MAJOR.MINOR.PATCH.

• MAJOR: Poveča se, ko naredite nezdružljive spremembe API-ja. To označuje pomembno spremembo, ki lahko od uporabnikov zahteva posodobitev njihove kode.
• MINOR: Poveča se, ko dodate funkcionalnost na nazaj združljiv način. To pomeni nove funkcije ali izboljšave, ki ne pokvarijo obstoječe kode.
• PATCH: Poveča se, ko naredite nazaj združljive popravke napak. To je za manjše popravke, ki ne dodajajo novih funkcij ali ne kvarijo obstoječe funkcionalnosti.

Primeri:

• 1.0.0: Začetna izdaja.
• 1.1.0: Dodana nova funkcionalnost brez lomljenja obstoječe kode.
• 1.0.1: Odpravljena napaka v izdaji 1.0.0.
• 2.0.0: Narejene nezdružljive spremembe API-ja.

Uporaba SemVer pomaga uporabnikom razumeti vpliv nadgradnje na novo različico vašega paketa.

Gradnja vašega paketa

Ko imate svojo datoteko `setup.py` nastavljeno, lahko zgradite svoj paket.

1. Ustvarite virtualno okolje: Zelo priporočljivo je ustvariti virtualno okolje za izolacijo odvisnosti vašega paketa. Uporabite `python3 -m venv .venv` (ali `virtualenv .venv`) in ga nato aktivirajte (`source .venv/bin/activate` na Linuxu/macOS, `.venv\Scripts\activate` na Windows).
2. Namestite odvisnosti za gradnjo: Zaženite `pip install --upgrade setuptools wheel`.
3. Zgradite paket: Zaženite `python setup.py sdist bdist_wheel`. Ta ukaz ustvari dve distribucijski datoteki v mapi `dist`: izvorno distribucijo (sdist) in "wheel" distribucijo (bdist_wheel).

`sdist` vsebuje vašo izvorno kodo in datoteko `setup.py`. `bdist_wheel` je vnaprej zgrajena distribucija, ki jo je mogoče namestiti hitreje.

Objava vašega paketa na PyPI

Preden lahko objavite svoj paket, morate ustvariti račun na PyPI (https://pypi.org/) in ustvariti žeton API. Ta žeton se bo uporabljal za avtentikacijo vaših nalaganj.

1. Registracija na PyPI: Pojdite na https://pypi.org/account/register/ in ustvarite račun.
2. Ustvarite žeton API: Pojdite na https://pypi.org/manage/account/, se pomaknite navzdol do razdelka "API tokens" in ustvarite nov žeton. Ta žeton varno shranite, saj ga boste potrebovali za nalaganje svojega paketa.
3. Namestite Twine: Zaženite `pip install twine`.
4. Naložite svoj paket: Zaženite `twine upload dist/*`. Pozvani boste k vnosu uporabniškega imena (__token__) in gesla (žeton API, ki ste ga ustvarili).

Pomembno varnostno opozorilo: Nikoli ne shranjujte svojega žetona API v svoj repozitorij. Shranite ga varno in uporabite okoljske spremenljivke ali druge varne metode za dostop do njega med postopkom nalaganja.

Testiranje namestitve vašega paketa

Po objavi paketa je bistveno preveriti, ali ga je mogoče pravilno namestiti.

1. Ustvarite novo virtualno okolje: To zagotavlja, da testirate namestitev v čistem okolju.
2. Namestite svoj paket: Zaženite `pip install ime-vasega-paketa`.
3. Uvozite in uporabite svoj paket: V tolmaču Python uvozite svoj paket in preverite, ali deluje, kot je pričakovano.

Neprekinjena integracija in neprekinjena dostava (CI/CD)

Za avtomatizacijo procesa gradnje, testiranja in objavljanja vašega paketa lahko uporabite orodja CI/CD, kot so GitHub Actions, GitLab CI ali Travis CI.

Tukaj je primer delovnega toka GitHub Actions, ki zgradi in objavi vaš paket na PyPI:

name: Objava na PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Nastavitev Pythona 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Namestitev odvisnosti
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Gradnja paketa
      run: python setup.py sdist bdist_wheel
    - name: Objava paketa na PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Pojasnilo:

• Ta delovni tok se sproži, ko je na GitHubu objavljena nova izdaja.
• Prevzame kodo, nastavi Python, namesti odvisnosti, zgradi paket in ga naloži na PyPI.
• secrets.PYPI_API_TOKEN je skrivnost na GitHubu, ki hrani vaš žeton API za PyPI. To skrivnost morate nastaviti v nastavitvah svojega repozitorija na GitHubu.

Najboljše prakse za distribucijo paketov Python

• Napišite celovito dokumentacijo: Vključite podrobno datoteko `README.md` ter dokumentacijo API-ja z uporabo orodij, kot je Sphinx. Jasna in popolna dokumentacija je ključnega pomena za enostavno uporabo vašega paketa.
• Pišite enotske teste: Temeljito testirajte svojo kodo, da zagotovite njeno kakovost in zanesljivost. Uporabite ogrodje za testiranje, kot sta pytest ali unittest.
• Sledite slogovnim smernicam PEP 8: Upoštevajte slogovni vodnik Python Enhancement Proposal 8 (PEP 8), da zagotovite dosledno in berljivo kodo.
• Uporabite licenco: Izberite ustrezno odprtokodno licenco, da določite, kako lahko drugi uporabljajo vašo kodo.
• Posodabljajte svoje odvisnosti: Redno posodabljajte odvisnosti vašega paketa, da boste imeli koristi od popravkov napak, varnostnih popravkov in novih funkcij.
• Uporabljajte virtualno okolje: Vedno razvijajte in testirajte svoj paket znotraj virtualnega okolja, da izolirate odvisnosti.
• Razmislite o internacionalizaciji (i18n) in lokalizaciji (l10n): Če vaš paket obravnava besedilo ali podatke, vidne uporabnikom, razmislite o prilagoditvi različnim jezikom in regijam. To razširi vašo potencialno bazo uporabnikov po vsem svetu. Pri tem vam lahko pomagajo orodja, kot je Babel.
• Upravljajte različne časovne pasove in valute: Če se vaš paket ukvarja z datumi, časi ali finančnimi transakcijami, bodite pozorni na različne časovne pasove in valute po svetu. Uporabite ustrezne knjižnice in API-je za pravilno obravnavo teh zapletenosti.
• Zagotovite jasna sporočila o napakah: Napišite informativna sporočila o napakah, ki uporabnikom pomagajo razumeti, kaj je šlo narobe in kako to popraviti. Če je mogoče, prevedite ta sporočila o napakah v različne jezike.
• Mislite na dostopnost: Pri načrtovanju vmesnika in dokumentacije vašega paketa upoštevajte uporabnike z oviranostmi. Sledite smernicam za dostopnost, da zagotovite, da je vaš paket uporaben za vse.

Napredne teme

• Imenski prostori paketov (Namespace packages): Omogočajo vam razdelitev enega paketa Python na več map ali celo več distribucij.
• Vstopne točke (Entry points): Omogočajo vam definiranje funkcij ali razredov, ki jih je mogoče klicati iz drugih paketov ali iz ukazne vrstice.
• Podatkovne datoteke (Data files): Omogočajo vam vključitev datotek, ki niso Python (npr. podatkovne datoteke, konfiguracijske datoteke), v vašo distribucijo.
• Pogojne odvisnosti (Conditional dependencies): Omogočajo vam določitev odvisnosti, ki so potrebne le pod določenimi pogoji (npr. na določenem operacijskem sistemu).

Zaključek

Distribucija vašega paketa Python na PyPI je odličen način za deljenje vašega dela s svetom in prispevanje k ekosistemu Pythona. S sledenjem korakom in najboljšim praksam, opisanim v tem vodniku, lahko ustvarite in objavite visokokakovostne pakete Python, ki jih je enostavno namestiti, uporabljati in vzdrževati. Ne pozabite dati prednosti jasni dokumentaciji, temeljitemu testiranju in doslednemu upravljanju različic, da zagotovite uspeh svojega paketa.