Pythoni pakettide levitamine: PyPI-s avaldamine ja versioonihaldus

Pythoni laiaulatuslik ökosüsteem põhineb tohutul hulgal pakettidel, mis on kergesti kättesaadavad Pythoni paketihalduri (PyPI) kaudu. See juhend annab põhjaliku ülevaate sellest, kuidas levitada oma Pythoni pakette PyPI kaudu, tagades nende kättesaadavuse arendajatele üle maailma. Uurime olulisi tööriistu, versioonihalduse parimaid praktikaid ning töövooge kvaliteetsete Pythoni pakettide loomiseks ja avaldamiseks.

Miks levitada oma Pythoni paketti?

Oma Pythoni paketi levitamine pakub mitmeid eeliseid:

• Oma töö jagamine: Võimaldab teistel arendajatel teie koodi hõlpsasti taaskasutada, soodustades koostööd ja innovatsiooni. Kujutage ette globaalset meeskonda, kes kasutab teie spetsialiseeritud andmeanalüüsi tööriistu, mis on ehitatud Pythonis.
• Sõltuvuste haldamine: Lihtsustab sõltuvuste haldamise protsessi teistes projektides. Teie paketi saab paigaldada ühe käsuga koos kõigi selle sõltuvustega.
• Avatud lähtekoodile kaasaaitamine: Võimaldab teil panustada avatud lähtekoodiga kogukonda ja saada tunnustust oma töö eest. Paljud kriitilised tarkvarakomponendid on avatud lähtekoodiga paketid, mida hooldavad arendajad üle maailma.
• Versioonikontroll ja uuendused: Pakub struktureeritud viisi versioonide haldamiseks, uuenduste väljastamiseks ja vigade parandamiseks. See tagab, et kasutajatel on alati juurdepääs teie paketi uusimale ja usaldusväärseimale versioonile.
• Lihtne paigaldamine: Lihtsustab kasutajate jaoks paigaldamist käsuga `pip install teie-paketi-nimi`.

Olulised tööriistad Pythoni pakettide levitamiseks

Pythoni pakettide loomiseks ja levitamiseks on olulised mitmed tööriistad:

• setuptools: Laialdaselt kasutatav teek paketi metaandmete, sealhulgas nime, versiooni, sõltuvuste ja sisestuspunktide määratlemiseks. See on de facto standard Pythoni projektide pakendamiseks.
• wheel: Levitamisformaat, mis pakub tõhusamat ja usaldusväärsemat paigaldusprotsessi võrreldes lähtekoodi distributsioonidega. Wheelid on eel-ehitatud distributsioonid, mida saab paigaldada kompileerimist nõudmata.
• twine: Tööriist teie paketi turvaliseks üleslaadimiseks PyPI-sse. Twine krüpteerib teie mandaadid ja paketi andmed edastamise ajal, kaitstes pealtkuulamise ja man-in-the-middle rünnakute eest.
• venv/virtualenv: Need on tööriistad isoleeritud Pythoni keskkondade loomiseks. Virtuaalsete keskkondade kasutamine on ülioluline sõltuvuste haldamiseks ja konfliktide vältimiseks erinevate projektide vahel.

Projekti seadistamine

Enne paketi levitamist peate oma projekti õigesti struktureerima.

Projekti struktuuri näide

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

Selgitus:

• my_package/: Peamine kaust, mis sisaldab teie paketi lähtekoodi.
• my_package/__init__.py: Muudab `my_package` kausta Pythoni paketiks. See võib olla tühi või sisaldada lähtestamiskoodi.
• my_package/module1.py, my_package/module2.py: Teie Pythoni moodulid, mis sisaldavad tegelikku koodi.
• tests/: Kaust, mis sisaldab teie ühikteste. Testide kirjutamine on ülioluline teie paketi kvaliteedi ja usaldusväärsuse tagamiseks.
• README.md: Markdown-fail, mis annab teie paketi kirjelduse, kasutusjuhised ja muud asjakohast teavet. See on sageli esimene asi, mida kasutajad PyPI-s näevad.
• LICENSE: Fail, mis sisaldab litsentsi, mille all teie pakett levitatakse (nt MIT, Apache 2.0, GPL). Sobiva litsentsi valimine on oluline selleks, et täpsustada, kuidas teised saavad teie koodi kasutada.
• setup.py: Peamine konfiguratsioonifail, mis määratleb teie paketi metaandmed ja ehitusjuhised.
• .gitignore: Määrab failid ja kaustad, mida Git peaks ignoreerima (nt ajutised failid, ehitusartefaktid).

Faili `setup.py` loomine

Fail `setup.py` on teie paketi levitamise süda. See sisaldab metaandmeid teie paketi kohta ning juhiseid selle ehitamiseks ja paigaldamiseks. Siin on näide:

import setuptools

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

setuptools.setup(
    name="my_package",  # Asenda oma paketi nimega
    version="0.1.0",
    author="Sinu Nimi",  # Asenda oma nimega
    author_email="sinu.email@example.com", # Asenda oma e-posti aadressiga
    description="Väike näidispakett",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/sinunimi/my_package", # Asenda oma repositooriumi URL-iga
    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", # Sõltuvuse näide
    ],
)

Selgitus:

• name: Teie paketi nimi, mida kasutatakse PyPI-s. Valige unikaalne ja kirjeldav nimi.
• version: Teie paketi versiooninumber. Järgige semantilist versioonimist (vt allpool).
• author, author_email: Teie nimi ja e-posti aadress.
• description: Teie paketi lühikirjeldus.
• long_description: Pikem ja üksikasjalikum kirjeldus, tavaliselt loetakse teie `README.md` failist.
• long_description_content_type: Määrab teie pika kirjelduse vormingu (nt "text/markdown").
• url: Teie paketi kodulehe URL (nt GitHubi repositoorium).
• packages: Levitamisse kaasatavate pakettide loend. `setuptools.find_packages()` avastab automaatselt kõik teie projekti paketid.
• classifiers: Metaandmed, mis aitavad kasutajatel teie paketti PyPI-s leida. Valige sobivad klassifikaatorid Trove klassifikaatorite loendist. Kaaluge klassifikaatorite lisamist toetatud Pythoni versioonide, operatsioonisüsteemide ja litsentside jaoks.
• python_requires: Määrab minimaalse Pythoni versiooni, mis on vajalik teie paketi kasutamiseks.
• install_requires: Teie paketi nõutavate sõltuvuste loend. Need sõltuvused paigaldatakse automaatselt, kui teie pakett paigaldatakse.

Versioonihaldus: Semantiline versioonimine

Semantiline versioonimine (SemVer) on laialdaselt kasutatav versioonimisskeem, mis pakub selget ja järjepidevat viisi teie paketi muudatuste olemuse edastamiseks.

SemVeri versiooninumber koosneb kolmest osast: MAJOR.MINOR.PATCH.

• MAJOR: Suurendatakse, kui teete ühildumatuid API muudatusi. See viitab olulisele muudatusele, mis võib nõuda kasutajatelt oma koodi värskendamist.
• MINOR: Suurendatakse, kui lisate funktsionaalsust tagasiühilduval viisil. See tähistab uusi funktsioone või täiustusi, mis ei riku olemasolevat koodi.
• PATCH: Suurendatakse, kui teete tagasiühilduvaid veaparandusi. See on mõeldud väikeste paranduste jaoks, mis ei lisa uusi funktsioone ega riku olemasolevat funktsionaalsust.

Näited:

• 1.0.0: Esmaväljaanne.
• 1.1.0: Lisati uus funktsioon olemasolevat koodi rikkumata.
• 1.0.1: Parandati viga versioonis 1.0.0.
• 2.0.0: Tehti ühildumatuid API muudatusi.

SemVeri kasutamine aitab kasutajatel mõista teie paketi uuele versioonile ülemineku mõju.

Paketi ehitamine

Kui olete oma `setup.py` faili konfigureerinud, saate oma paketi ehitada.

1. Looge virtuaalne keskkond: On väga soovitatav luua virtuaalne keskkond, et isoleerida oma paketi sõltuvused. Kasutage käsku `python3 -m venv .venv` (või `virtualenv .venv`) ja seejärel aktiveerige see (`source .venv/bin/activate` Linuxis/macOS-is, `.venv\Scripts\activate` Windowsis).
2. Paigaldage ehitussõltuvused: Käivitage `pip install --upgrade setuptools wheel`.
3. Ehitage pakett: Käivitage `python setup.py sdist bdist_wheel`. See käsk loob `dist` kausta kaks distributsioonifaili: lähtekoodi distributsiooni (sdist) ja wheel-distributsiooni (bdist_wheel).

`sdist` sisaldab teie lähtekoodi ja `setup.py` faili. `bdist_wheel` on eel-ehitatud distributsioon, mida saab kiiremini paigaldada.

Paketi avaldamine PyPI-s

Enne paketi avaldamist peate looma konto PyPI-s (https://pypi.org/) ja looma API-võtme. Seda võtit kasutatakse teie üleslaadimiste autentimiseks.

1. Registreeruge PyPI-s: Minge aadressile https://pypi.org/account/register/ ja looge konto.
2. Looge API-võti: Minge aadressile https://pypi.org/manage/account/, kerige alla jaotiseni "API tokens" ja looge uus võti. Hoidke seda võtit turvaliselt, kuna vajate seda oma paketi üleslaadimiseks.
3. Paigaldage Twine: Käivitage `pip install twine`.
4. Laadige oma pakett üles: Käivitage `twine upload dist/*`. Teilt küsitakse kasutajanime (__token__) ja parooli (loodud API-võti).

Oluline turvamärkus: Ärge kunagi lisage oma API-võtit oma repositooriumisse. Hoidke seda turvaliselt ja kasutage keskkonnamuutujaid või muid turvalisi meetodeid sellele juurdepääsemiseks üleslaadimisprotsessi ajal.

Paketi paigaldamise testimine

Pärast paketi avaldamist on oluline testida, kas seda saab õigesti paigaldada.

1. Looge uus virtuaalne keskkond: See tagab, et testite paigaldamist puhtas keskkonnas.
2. Paigaldage oma pakett: Käivitage `pip install teie-paketi-nimi`.
3. Importige ja kasutage oma paketti: Pythoni interpretaatoris importige oma pakett ja veenduge, et see töötab ootuspäraselt.

Pidev integratsioon ja pidev tarnimine (CI/CD)

Paketi ehitamise, testimise ja avaldamise protsessi automatiseerimiseks saate kasutada CI/CD tööriistu, nagu GitHub Actions, GitLab CI või Travis CI.

Siin on näide GitHub Actionsi töövoost, mis ehitab ja avaldab teie paketi PyPI-s:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Build package
      run: python setup.py sdist bdist_wheel
    - name: Publish package to PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Selgitus:

• See töövoog käivitub, kui GitHubis avaldatakse uus väljalase.
• See laadib koodi alla, seadistab Pythoni, paigaldab sõltuvused, ehitab paketi ja laadib selle PyPI-sse üles.
• secrets.PYPI_API_TOKEN on GitHubi saladus, mis salvestab teie PyPI API-võtme. Peate selle saladuse konfigureerima oma GitHubi repositooriumi seadetes.

Pythoni pakettide levitamise parimad praktikad

• Kirjutage põhjalik dokumentatsioon: Lisage üksikasjalik `README.md` fail, samuti API dokumentatsioon, kasutades tööriistu nagu Sphinx. Selge ja täielik dokumentatsioon on ülioluline, et muuta teie pakett lihtsasti kasutatavaks.
• Kirjutage ühiktestid: Testige oma koodi põhjalikult, et tagada selle kvaliteet ja usaldusväärsus. Kasutage testimisraamistikku nagu pytest või unittest.
• Järgige PEP 8 stiilijuhiseid: Järgige Python Enhancement Proposal 8 (PEP 8) stiilijuhendit, et tagada ühtlane ja loetav kood.
• Kasutage litsentsi: Valige sobiv avatud lähtekoodiga litsents, et täpsustada, kuidas teised saavad teie koodi kasutada.
• Hoidke oma sõltuvused ajakohasena: Värskendage regulaarselt oma paketi sõltuvusi, et saada kasu veaparandustest, turvapaikadest ja uutest funktsioonidest.
• Kasutage virtuaalset keskkonda: Arendage ja testige oma paketti alati virtuaalses keskkonnas, et isoleerida sõltuvused.
• Kaaluge rahvusvahelistamist (i18n) ja lokaliseerimist (l10n): Kui teie pakett tegeleb kasutajale suunatud teksti või andmetega, kaaluge selle kohandamist erinevatele keeltele ja piirkondadele. See laiendab teie potentsiaalset kasutajaskonda globaalselt. Tööriistad nagu Babel võivad siin abiks olla.
• Käsitlege erinevaid ajavööndeid ja valuutasid: Kui teie pakett tegeleb kuupäevade, kellaaegade või finantstehingutega, olge teadlik erinevatest ajavöönditest ja valuutadest üle maailma. Kasutage sobivaid teeke ja API-sid, et neid keerukusi õigesti käsitleda.
• Pakkuge selgeid veateateid: Kirjutage informatiivseid veateateid, mis aitavad kasutajatel mõista, mis läks valesti ja kuidas seda parandada. Tõlkige need veateated võimalusel erinevatesse keeltesse.
• Mõelge ligipääsetavusele: Arvestage puuetega kasutajatega oma paketi liidese ja dokumentatsiooni kujundamisel. Järgige ligipääsetavuse juhiseid, et tagada teie paketi kasutatavus kõigile.

Täpsemad teemad

• Nimeruumipaketid: Võimaldavad jagada ühe Pythoni paketi mitme kausta või isegi mitme distributsiooni vahel.
• Sisestuspunktid: Võimaldavad määratleda funktsioone või klasse, mida saab kutsuda teistest pakettidest või käsurealt.
• Andmefailid: Võimaldavad lisada oma distributsiooni mitte-Pythoni faile (nt andmefailid, konfiguratsioonifailid).
• Tingimuslikud sõltuvused: Võimaldavad määrata sõltuvusi, mis on vajalikud ainult teatud tingimustel (nt konkreetses operatsioonisüsteemis).

Kokkuvõte

Oma Pythoni paketi levitamine PyPI-s on suurepärane viis oma töö jagamiseks maailmaga ja panustamiseks Pythoni ökosüsteemi. Järgides selles juhendis toodud samme ja parimaid praktikaid, saate luua ja avaldada kvaliteetseid Pythoni pakette, mida on lihtne paigaldada, kasutada ja hooldada. Ärge unustage seada esikohale selget dokumentatsiooni, põhjalikku testimist ja järjepidevat versioonihaldust, et tagada oma paketi edu.