Python paketų platinimas: PyPI publikavimas ir versijų valdymas

Plati Python ekosistema yra paremta didžiule paketų kolekcija, lengvai pasiekiama per Python paketų indeksą (PyPI). Šis vadovas pateikia išsamią apžvalgą, kaip platinti savo Python paketus per PyPI, užtikrinant, kad jie būtų prieinami programuotojams visame pasaulyje. Išnagrinėsime esminius įrankius, geriausias versijų valdymo praktikas ir darbo eigas, skirtas kurti ir publikuoti aukštos kokybės Python paketus.

Kodėl verta platinti savo Python paketą?

Savo Python paketo platinimas suteikia daugybę privalumų:

• Dalijimasis savo darbu: Leidžia kitiems programuotojams lengvai pakartotinai naudoti jūsų kodą, skatinant bendradarbiavimą ir inovacijas. Įsivaizduokite pasaulinę komandą, naudojančią jūsų specializuotus duomenų analizės įrankius, sukurtus su Python.
• Priklausomybių valdymas: Supaprastina priklausomybių valdymą kituose projektuose. Jūsų paketas gali būti įdiegtas viena komanda kartu su visomis jo priklausomybėmis.
• Indėlis į atvirąjį kodą: Suteikia galimybę prisidėti prie atvirojo kodo bendruomenės ir pelnyti pripažinimą už savo darbą. Daugelis svarbių programinės įrangos komponentų yra atvirojo kodo paketai, prižiūrimi programuotojų visame pasaulyje.
• Versijų kontrolė ir atnaujinimai: Suteikia struktūrizuotą būdą valdyti versijas, išleisti atnaujinimus ir taisyti klaidas. Tai užtikrina, kad vartotojai visada turėtų prieigą prie naujausios ir patikimiausios jūsų paketo versijos.
• Lengvas diegimas: Supaprastina diegimą vartotojams naudojant `pip install jūsų-paketo-pavadinimas`.

Esminiai įrankiai Python paketų platinimui

Keli įrankiai yra būtini kuriant ir platinant Python paketus:

• setuptools: Plačiai naudojama biblioteka, skirta paketo metaduomenims apibrėžti, įskaitant pavadinimą, versiją, priklausomybes ir įvesties taškus. Tai yra de facto standartas Python projektų paketavimui.
• wheel: Platinimo formatas, kuris užtikrina efektyvesnį ir patikimesnį diegimo procesą, palyginti su išeities kodo distribucijomis. „Wheel“ yra iš anksto sukompiliuotos distribucijos, kurias galima įdiegti nereikalaujant kompiliavimo.
• twine: Įrankis saugiam jūsų paketo įkėlimui į PyPI. „Twine“ šifruoja jūsų prisijungimo duomenis ir paketo duomenis perdavimo metu, apsaugodamas nuo pasiklausymo ir „man-in-the-middle“ atakų.
• venv/virtualenv: Tai įrankiai izoliuotoms Python aplinkoms kurti. Virtualių aplinkų naudojimas yra labai svarbus valdant priklausomybes ir išvengiant konfliktų tarp skirtingų projektų.

Projekto paruošimas

Prieš pradedant platinti paketą, turite teisingai struktūrizuoti savo projektą.

Projekto struktūros pavyzdys

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

Paaiškinimas:

• my_package/: Pagrindinis katalogas, kuriame yra jūsų paketo išeities kodas.
• my_package/__init__.py: Paverčia `my_package` katalogą Python paketu. Jis gali būti tuščias arba turėti inicializacijos kodą.
• my_package/module1.py, my_package/module2.py: Jūsų Python moduliai, kuriuose yra tikrasis kodas.
• tests/: Katalogas, kuriame yra jūsų vienetų testai (unit tests). Labai svarbu rašyti testus, siekiant užtikrinti paketo kokybę ir patikimumą.
• README.md: Markdown failas, kuriame pateikiamas jūsų paketo aprašymas, naudojimo instrukcijos ir kita svarbi informacija. Tai dažnai yra pirmas dalykas, kurį vartotojai pamato PyPI.
• LICENSE: Failas, kuriame yra licencija, pagal kurią platinamas jūsų paketas (pvz., MIT, Apache 2.0, GPL). Pasirinkti tinkamą licenciją yra būtina, norint nurodyti, kaip kiti gali naudoti jūsų kodą.
• setup.py: Pagrindinis konfigūracijos failas, apibrėžiantis jūsų paketo metaduomenis ir kūrimo (build) instrukcijas.
• .gitignore: Nurodo failus ir katalogus, kuriuos Git turėtų ignoruoti (pvz., laikinuosius failus, kūrimo artefaktus).

`setup.py` failo kūrimas

`setup.py` failas yra jūsų paketo platinimo pagrindas. Jame yra metaduomenys apie jūsų paketą ir instrukcijos, kaip jį sukurti ir įdiegti. Štai pavyzdys:

import setuptools

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

setuptools.setup(
    name="my_package",  # Pakeiskite savo paketo pavadinimu
    version="0.1.0",
    author="Jūsų Vardas",  # Pakeiskite savo vardu
    author_email="jusu.pastas@example.com", # Pakeiskite savo el. paštu
    description="Mažas pavyzdinis paketas",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/jusu-vardas/my_package", # Pakeiskite savo repozitorijos URL
    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", # Priklausomybės pavyzdys
    ],
)

Paaiškinimas:

• name: Jūsų paketo pavadinimas, kuris bus naudojamas PyPI. Pasirinkite unikalų ir aprašomąjį pavadinimą.
• version: Jūsų paketo versijos numeris. Vadovaukitės semantiniu versijavimu (žr. žemiau).
• author, author_email: Jūsų vardas ir el. pašto adresas.
• description: Trumpas jūsų paketo aprašymas.
• long_description: Ilgesnis, išsamesnis aprašymas, paprastai nuskaitomas iš jūsų `README.md` failo.
• long_description_content_type: Nurodo jūsų ilgojo aprašymo formatą (pvz., "text/markdown").
• url: Jūsų paketo pagrindinio puslapio URL (pvz., GitHub repozitorija).
• packages: Paketų, kuriuos reikia įtraukti į jūsų distribuciją, sąrašas. `setuptools.find_packages()` automatiškai suranda visus paketus jūsų projekte.
• classifiers: Metaduomenys, padedantys vartotojams rasti jūsų paketą PyPI. Pasirinkite tinkamus klasifikatorius iš Trove klasifikatorių sąrašo. Apsvarstykite galimybę įtraukti klasifikatorius palaikomoms Python versijoms, operacinėms sistemoms ir licencijoms.
• python_requires: Nurodo minimalią Python versiją, reikalingą jūsų paketui naudoti.
• install_requires: Priklausomybių, kurių reikalauja jūsų paketas, sąrašas. Šios priklausomybės bus automatiškai įdiegtos, kai bus diegiamas jūsų paketas.

Versijų valdymas: semantinis versijavimas

Semantinis versijavimas (SemVer) yra plačiai paplitusi versijavimo schema, kuri suteikia aiškų ir nuoseklų būdą pranešti apie pakeitimų pobūdį jūsų pakete.

SemVer versijos numerį sudaro trys dalys: MAJOR.MINOR.PATCH.

• MAJOR: Didinama, kai atliekate nesuderinamus API pakeitimus. Tai rodo reikšmingą pakeitimą, dėl kurio vartotojams gali tekti atnaujinti savo kodą.
• MINOR: Didinama, kai pridedate funkcionalumą atgaliniu būdu suderinamu būdu. Tai reiškia naujas funkcijas ar patobulinimus, kurie nepažeidžia esamo kodo.
• PATCH: Didinama, kai atliekate atgaliniu būdu suderinamus klaidų pataisymus. Tai skirta smulkiems pataisymams, kurie neprideda naujų funkcijų ir nepažeidžia esamo funkcionalumo.

Pavyzdžiai:

• 1.0.0: Pradinis išleidimas.
• 1.1.0: Pridėta nauja funkcija nepažeidžiant esamo kodo.
• 1.0.1: Ištaisyta klaida 1.0.0 versijoje.
• 2.0.0: Atlikti nesuderinami API pakeitimai.

Naudojant SemVer vartotojai lengviau supranta, kokį poveikį turės atsinaujinimas į naują jūsų paketo versiją.

Paketo kūrimas (Building)

Kai sukonfigūruosite `setup.py` failą, galite sukurti savo paketą.

1. Sukurkite virtualią aplinką: Labai rekomenduojama sukurti virtualią aplinką, kad izoliuotumėte savo paketo priklausomybes. Naudokite `python3 -m venv .venv` (arba `virtualenv .venv`) ir tada ją aktyvuokite (`source .venv/bin/activate` Linux/macOS sistemose, `.venv\Scripts\activate` Windows sistemose).
2. Įdiekite kūrimo priklausomybes: Paleiskite `pip install --upgrade setuptools wheel`.
3. Sukurkite paketą: Paleiskite `python setup.py sdist bdist_wheel`. Ši komanda sukuria du distribucijos failus `dist` kataloge: išeities kodo distribuciją (sdist) ir „wheel“ distribuciją (bdist_wheel).

`sdist` yra jūsų išeities kodas ir `setup.py` failas. `bdist_wheel` yra iš anksto sukurta distribucija, kurią galima įdiegti greičiau.

Paketo publikavimas PyPI

Prieš publikuojant paketą, turite susikurti paskyrą PyPI (https://pypi.org/) ir sugeneruoti API raktą (token). Šis raktas bus naudojamas jūsų įkėlimams autentifikuoti.

1. Užsiregistruokite PyPI: Eikite į https://pypi.org/account/register/ ir susikurkite paskyrą.
2. Sukurkite API raktą: Eikite į https://pypi.org/manage/account/, slinkite žemyn iki skilties „API tokens“ ir sukurkite naują raktą. Saugiai jį išsaugokite, nes jo prireiks įkeliant paketą.
3. Įdiekite Twine: Paleiskite `pip install twine`.
4. Įkelkite savo paketą: Paleiskite `twine upload dist/*`. Jūsų paprašys įvesti vartotojo vardą (__token__) ir slaptažodį (jūsų sukurtą API raktą).

Svarbi saugumo pastaba: Niekada neįkelkite savo API rakto į repozitoriją. Saugokite jį saugiai ir naudokite aplinkos kintamuosius ar kitus saugius metodus, kad galėtumėte jį pasiekti įkėlimo proceso metu.

Paketo diegimo testavimas

Po paketo publikavimo būtina patikrinti, ar jį galima teisingai įdiegti.

1. Sukurkite naują virtualią aplinką: Tai užtikrins, kad diegimą testuojate švarioje aplinkoje.
2. Įdiekite savo paketą: Paleiskite `pip install jūsų-paketo-pavadinimas`.
3. Importuokite ir naudokite savo paketą: Python interpretatoriuje importuokite savo paketą ir patikrinkite, ar jis veikia kaip tikėtasi.

Nuolatinė integracija ir nuolatinis diegimas (CI/CD)

Norėdami automatizuoti paketo kūrimo, testavimo ir publikavimo procesą, galite naudoti CI/CD įrankius, tokius kaip GitHub Actions, GitLab CI ar Travis CI.

Štai GitHub Actions darbo eigos pavyzdys, kuris kuria ir publikuoja jūsų paketą PyPI:

name: Publikuoti į PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Nustatyti Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Įdiegti priklausomybes
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Kurti paketą
      run: python setup.py sdist bdist_wheel
    - name: Publikuoti paketą į PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Paaiškinimas:

• Ši darbo eiga paleidžiama, kai GitHub'e publikuojama nauja versija (release).
• Ji paima kodą, nustato Python, įdiegia priklausomybes, sukuria paketą ir įkelia jį į PyPI.
• secrets.PYPI_API_TOKEN yra GitHub paslaptis (secret), kurioje saugomas jūsų PyPI API raktas. Šią paslaptį turite sukonfigūruoti savo GitHub repozitorijos nustatymuose.

Geriausios Python paketų platinimo praktikos

• Rašykite išsamią dokumentaciją: Įtraukite detalų `README.md` failą, taip pat API dokumentaciją, naudodami įrankius, tokius kaip Sphinx. Aiški ir išsami dokumentacija yra labai svarbi, kad jūsų paketas būtų lengvai naudojamas.
• Rašykite vienetų testus: Kruopščiai testuokite savo kodą, kad užtikrintumėte jo kokybę ir patikimumą. Naudokite testavimo karkasus, tokius kaip pytest ar unittest.
• Laikykitės PEP 8 stiliaus gairių: Laikykitės Python Enhancement Proposal 8 (PEP 8) stiliaus vadovo, kad užtikrintumėte nuoseklų ir skaitomą kodą.
• Naudokite licenciją: Pasirinkite tinkamą atvirojo kodo licenciją, kad nurodytumėte, kaip kiti gali naudoti jūsų kodą.
• Atnaujinkite priklausomybes: Reguliariai atnaujinkite savo paketo priklausomybes, kad pasinaudotumėte klaidų pataisymais, saugumo atnaujinimais ir naujomis funkcijomis.
• Naudokite virtualią aplinką: Visada kurkite ir testuokite savo paketą virtualioje aplinkoje, kad izoliuotumėte priklausomybes.
• Apsvarstykite internacionalizaciją (i18n) ir lokalizaciją (l10n): Jei jūsų paketas apdoroja vartotojui matomą tekstą ar duomenis, apsvarstykite galimybę pritaikyti jį skirtingoms kalboms ir regionams. Tai praplečia jūsų potencialių vartotojų ratą visame pasaulyje. Su tuo gali padėti įrankiai, tokie kaip Babel.
• Apdorokite skirtingas laiko juostas ir valiutas: Jei jūsų paketas dirba su datomis, laikais ar finansinėmis operacijomis, atsižvelkite į skirtingas laiko juostas ir valiutas visame pasaulyje. Naudokite tinkamas bibliotekas ir API, kad teisingai tvarkytumėte šiuos sudėtingumus.
• Pateikite aiškius klaidų pranešimus: Rašykite informatyvius klaidų pranešimus, kurie padėtų vartotojams suprasti, kas nutiko negerai ir kaip tai ištaisyti. Jei įmanoma, išverskite šiuos klaidų pranešimus į skirtingas kalbas.
• Pagalvokite apie prieinamumą: Kurdami paketo sąsają ir dokumentaciją, atsižvelkite į vartotojus su negalia. Laikykitės prieinamumo gairių, kad užtikrintumėte, jog jūsų paketas būtų naudojamas visiems.

Temos pažengusiems

• Vardų srities paketai (Namespace packages): Leidžia padalinti vieną Python paketą į kelis katalogus ar net kelias distribucijas.
• Įvesties taškai (Entry points): Leidžia apibrėžti funkcijas ar klases, kurias galima iškviesti iš kitų paketų arba iš komandinės eilutės.
• Duomenų failai: Leidžia įtraukti ne Python failus (pvz., duomenų failus, konfigūracijos failus) į savo distribuciją.
• Sąlyginės priklausomybės: Leidžia nurodyti priklausomybes, kurios reikalingos tik tam tikromis sąlygomis (pvz., konkrečioje operacinėje sistemoje).

Išvada

Savo Python paketo platinimas PyPI yra puikus būdas pasidalinti savo darbu su pasauliu ir prisidėti prie Python ekosistemos. Vadovaudamiesi šiame vadove aprašytais veiksmais ir geriausiomis praktikomis, galite kurti ir publikuoti aukštos kokybės Python paketus, kuriuos lengva įdiegti, naudoti ir prižiūrėti. Nepamirškite teikti pirmenybę aiškiai dokumentacijai, kruopščiam testavimui ir nuosekliam versijų valdymui, kad užtikrintumėte savo paketo sėkmę.