Celovit vodnik po formatu distribucije Wheel in ustvarjanju binarnih paketov za Python, ki zagotavlja učinkovito in zanesljivo distribucijo programske opreme.
Format distribucije Wheel: Ustvarjanje binarnih paketov za Python
Ekosistem Pythona se močno zanaša na učinkovito upravljanje paketov. Eden od temeljev tega ekosistema je format distribucije Wheel, ki ga pogosto prepoznamo po razširitvi .whl. Ta vodnik se poglobi v podrobnosti formata Wheel, njegove prednosti in kako ustvarjati binarne pakete za Python, namenjen razvijalcem po vsem svetu, ki si prizadevajo za gladko in zanesljivo distribucijo programske opreme.
Kaj je format Wheel?
Format Wheel je format predhodno zgrajenih paketov za Python. Zasnovan je tako, da se lažje namesti kot distribucije izvorne kode (sdist). Služi kot zamenjava za starejši format egg in odpravlja nekatere njegove pomanjkljivosti. V bistvu gre za ZIP arhiv s posebno strukturo in metapodatki, ki pip in drugim orodjem za namestitev omogočata hitro namestitev paketa brez potrebe po gradnji iz izvorne kode.
Ključne značilnosti Wheel-a
- Neodvisnost od platforme (kjer je primerno): Wheels se lahko gradijo za specifične platforme in arhitekture (npr. Windows 64-bit, Linux x86_64) ali so neodvisni od platforme (čisti Python). To omogoča ustvarjanje optimiziranih binarnih datotek za različne operacijske sisteme.
- Enostavna namestitev: Format Wheel vključuje predhodno zgrajene distribucije, kar zmanjšuje potrebo po prevajanju kode med namestitvijo. To znatno pospeši postopek namestitve, še posebej za pakete z C razširitvami ali drugimi prevedenimi komponentami.
- Vključitev metapodatkov: Wheels vsebujejo vse potrebne metapodatke o paketu, vključno z odvisnostmi, informacijami o različici in vstopnimi točkami. Ti metapodatki so ključni za upravitelje paketov, kot je
pip, da pravilno obravnavajo odvisnosti in namestijo paket. - Atomska namestitev:
pipnamesti pakete iz Wheel-ov na atomski način. To pomeni, da se namestitev bodisi uspešno zaključi bodisi se popolnoma razveljavi, s čimer se preprečijo delno nameščeni paketi, ki lahko vodijo do nedoslednosti. - Ponovljivost: Wheels izboljšujejo ponovljivost z zagotavljanjem doslednega gradbenega artefakta, ki ga je mogoče namestiti v več okolij, ne da bi bila potrebna ponovna prevedba (ob predpostavki, da se ciljna platforma ujema).
Zakaj uporabljati Wheels?
Izbira Wheels namesto distribucij izvorne kode ponuja številne prednosti, kar poenostavlja postopek namestitve in namestitve paketov. Tukaj je pregled ključnih prednosti:
Hitrejši časi namestitve
Ena najpomembnejših prednosti Wheels je njihova hitrost. Z zagotavljanjem predhodno zgrajenih distribucij, Wheels odpravljajo potrebo po prevajanju kode med namestitvijo. To je še posebej koristno za pakete s prevedenimi razširitvami, napisanimi v C, C++ ali drugih jezikih. Predstavljajte si, da namestite zapleteno znanstveno knjižnico; uporaba Wheel-a drastično skrajša čas namestitve na računalnikih končnih uporabnikov.
Primer: Namestitev numpy iz izvorne kode lahko traja več minut, še posebej na starejši strojni opremi. Namestitev iz Wheel-a običajno traja nekaj sekund.
Zmanjšana odvisnost od orodij za gradnjo
Namestitev paketov iz izvorne kode pogosto zahteva, da imajo uporabniki nameščena potrebna orodja za gradnjo (prevajalniki, glave itd.) na svojem sistemu. To je lahko ovira za začetnike, zlasti za uporabnike, ki niso seznanjeni z razvojem programske opreme. Wheels odpravijo to odvisnost, zaradi česar je namestitev enostavnejša in bolj dostopna.
Primer: Znanstvenik s podatki v raziskovalnem laboratoriju morda nima ustreznih prevajalnikov za gradnjo paketa iz izvorne kode. Wheel mu omogoča neposredno namestitev paketa brez potrebe po konfiguraciji njegovega okolja.
Izboljšana zanesljivost
Z zagotavljanjem predhodno zgrajenih binarnih datotek Wheels zagotavljajo, da je paket nameščen dosledno v različnih okoljih. To zmanjšuje tveganje napak pri namestitvi zaradi razlik v sistemskih konfiguracijah ali različicah orodij za gradnjo. Ta doslednost je najpomembnejša za aplikacije, ki zahtevajo stabilno in predvidljivo delovanje.
Primer: Spletna aplikacija, nameščena na več strežnikih, mora imeti dosledne različice paketov. Uporaba Wheels zagotavlja, da so na vsakem strežniku nameščene iste binarne datoteke, kar zmanjšuje tveganje težav z namestitvijo.
Izboljšana varnost
Wheels se lahko podpisujejo za preverjanje njihove pristnosti in celovitosti. To pomaga preprečiti, da bi zlonamerni akterji distribuirali spremenjene pakete. Podpisovanje paketov zagotavlja dodatno raven varnosti in zagotavlja, da uporabniki nameščajo zaupanja vredno programsko opremo.
Primer: Podjetja lahko uvedejo pravilnike, ki zahtevajo, da se vsi paketi podpišejo, preden se namestijo v proizvodna okolja. To ščiti pred napadi na dobavne verige, kjer je zlonamerna koda vbrizgana v pakete.
Ustvarjanje Wheel paketov: Vodnik po korakih
Ustvarjanje Wheel paketov je preprost postopek, ki vključuje uporabo paketov setuptools in wheel. Tukaj je podroben vodnik:
1. Nastavitev vašega projekta
Najprej se prepričajte, da je vaš projekt pravilno strukturiran. Vsaj potrebovali boste datoteko setup.py in izvorno kodo vašega paketa.
Primer strukture projekta:
my_package/ ├── my_module/ │ ├── __init__.py │ └── my_function.py ├── setup.py └── README.md
2. Datoteka setup.py
Datoteka setup.py je srce vašega projekta. Vsebuje metapodatke o vašem paketu in definira, kako naj se ga gradi in namesti. Tukaj je primer datoteke setup.py:
from setuptools import setup, find_packages
setup(
name='my_package',
version='0.1.0',
description='A simple example package',
long_description=open('README.md').read(),
long_description_content_type='text/markdown',
url='https://github.com/your_username/my_package',
author='Your Name',
author_email='your.email@example.com',
license='MIT',
packages=find_packages(),
install_requires=['requests'],
classifiers=[
'Development Status :: 3 - Alpha',
'Intended Audience :: Developers',
'License :: OSI Approved :: MIT License',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.7',
'Programming Language :: Python :: 3.8',
'Programming Language :: Python :: 3.9',
],
)
Razlaga ključnih polj:
name: Ime vašega paketa. To je ime, ki ga bodo uporabniki uporabili za namestitev vašega paketa (npr.pip install my_package).version: Številka različice vašega paketa. Upoštevajte semantično verzijoniranje (SemVer) za dosledne prakse verzijoniranja (npr.0.1.0,1.0.0,2.5.1).description: Kratek opis vašega paketa.long_description: Podroben opis vašega paketa. Ta se pogosto bere iz datotekeREADME.md.url: URL domače strani ali repozitorija vašega paketa.author: Ime avtorja paketa.author_email: E-poštni naslov avtorja paketa.license: Licenca, pod katero se vaš paket distribuira (npr. MIT, Apache 2.0, GPL).packages: Seznam paketov, ki jih želite vključiti v svojo distribucijo.find_packages()samodejno najde vse pakete v vašem projektu.install_requires: Seznam odvisnosti, ki jih vaš paket potrebuje.pipbo samodejno namestil te odvisnosti, ko bo vaš paket nameščen.classifiers: Metapodatki, ki pomagajo uporabnikom najti vaš paket na PyPI (Python Package Index). Ti klasifikatorji opisujejo status razvoja, namenjeno občinstvo, licenco in podprte različice Python-a.
3. Namestitev wheel
Če nimate nameščenega paketa wheel, ga lahko namestite z uporabo pip:
pip install wheel
4. Gradnja Wheel paketa
Pomaknite se v korensko mapo vašega projekta (kjer se nahaja setup.py) in zaženite naslednji ukaz:
python setup.py bdist_wheel
Ta ukaz bo ustvaril mapo dist, ki vsebuje Wheel paket (.whl datoteko) in distribucijo izvorne kode (.tar.gz datoteko).
5. Iskanje Wheel datoteke
Ustvarjena Wheel datoteka se bo nahajala v mapi dist. Njena imena bodo sledila formatu package_name-version-pyXX-none-any.whl, kjer:
package_name: Ime vašega paketa.version: Številka različice vašega paketa.pyXX: Različica Pythona, s katero je paket združljiv (npr.py37za Python 3.7).none: Označuje, da paket ni specifičen za platformo.any: Označuje, da je paket združljiv s katerokoli arhitekturo.
Za pakete, specifične za platformo, bodo oznaki none in any zamenjani z identifikatorji platforme in arhitekture (npr. win_amd64 za Windows 64-bit).
6. Testiranje Wheel paketa
Preden distribuirate svoj Wheel paket, je bistveno, da ga preizkusite, da zagotovite pravilno namestitev. To lahko storite z uporabo pip:
pip install dist/my_package-0.1.0-py39-none-any.whl
Zamenjajte dist/my_package-0.1.0-py39-none-any.whl z dejansko potjo do vaše Wheel datoteke.
7. Distribucija vašega Wheel paketa
Ko ste zgradili in preizkusili svoj Wheel paket, ga lahko distribuirate preko različnih kanalov:
- PyPI (Python Package Index): Najpogostejši način distribucije Python paketov. Svoj Wheel paket lahko naložite na PyPI z uporabo
twine. - Zasebni paketni indeks: Za notranjo uporabo znotraj organizacije lahko nastavite zasebni paketni indeks z orodji, kot sta
devpiali Artifactory. - Neposredna distribucija: Svoj Wheel paket lahko tudi neposredno distribuirate uporabnikom preko e-pošte, deljenja datotek ali drugih sredstev.
Obravnavanje C razširitev in platformno specifičnih Wheels
Ustvarjanje platformno specifičnih Wheels, zlasti tistih, ki vsebujejo C razširitve, zahteva dodatne korake. Tukaj je pregled postopka:
1. Prevajanje C razširitev
C razširitve je treba prevesti za vsako ciljno platformo. To običajno vključuje uporabo prevajalnika C (npr. GCC, MSVC) in orodij za gradnjo, specifičnih za platformo.
Primer: Na Windows morate za gradnjo C razširitev uporabiti prevajalnik Microsoft Visual C++. Na Linuxu običajno uporabljate GCC.
2. Uporaba cffi ali Cython
Orodja, kot sta cffi in Cython, lahko poenostavijo postopek ustvarjanja C razširitev. cffi vam omogoča neposredno klicanje C kode iz Pythona, ne da bi sami pisali C kodo, medtem ko Cython omogoča pisanje C-podobne kode, ki se prevede v C razširitve.
3. Določanje platformno specifičnih odvisnosti
V vaši datoteki setup.py lahko določite platformno specifične odvisnosti z uporabo parametrov setup_requires in install_requires. To vam omogoča določitev različnih odvisnosti za različne platforme.
Primer:
from setuptools import setup, Extension import platform if platform.system() == 'Windows': extra_compile_args = ['/O2', '/EHsc'] else: extra_compile_args = ['-O3'] setup( name='my_package', version='0.1.0', ext_modules=[ Extension( 'my_package.my_extension', ['my_package/my_extension.c'], extra_compile_args=extra_compile_args, ), ], )
4. Gradnja platformno specifičnih Wheels
Za gradnjo platformno specifičnih Wheels boste morali uporabiti ustrezno gradbeno okolje za vsako ciljno platformo. To lahko vključuje uporabo navideznih strojev ali tehnologij za kontejnerizacijo, kot je Docker.
Primer: Za gradnjo Wheel-a za Windows 64-bit morate postopek gradnje zagnati na sistemu Windows 64-bit z nameščenim prevajalnikom Microsoft Visual C++.
Najboljše prakse za ustvarjanje Wheel paketov
Upoštevanje najboljših praks zagotavlja, da so vaši Wheel paketi zanesljivi, vzdrževani in enostavni za uporabo. Tukaj je nekaj ključnih priporočil:
1. Uporabite semantično verzijoniranje (SemVer)
Upoštevajte semantično verzijoniranje (SemVer) za dosledne prakse verzijoniranja. SemVer uporablja tridelno številko različice (MAJOR.MINOR.PATCH) za označevanje vrste sprememb v vsaki izdaji.
- MAJOR: Označuje nezdružljive spremembe API-ja.
- MINOR: Označuje nove funkcije, ki so združljive nazaj.
- PATCH: Označuje popravke napak, ki so združljivi nazaj.
Primer: Spreminjanje parametrov funkcije na način, ki prekinja obstoječo kodo, bi upravičilo večje povečanje različice (npr. z 1.0.0 na 2.0.0). Dodajanje nove funkcije brez spreminjanja obstoječih bi upravičilo manjše povečanje različice (npr. z 1.0.0 na 1.1.0). Popravljanje napake bi upravičilo povečanje različice popravka (npr. z 1.0.0 na 1.0.1).
2. Vključite datoteko README.md
Vključite datoteko README.md, ki vsebuje podroben opis vašega paketa, vključno z navodili za namestitev, primeri uporabe in smernicami za prispevanje. To uporabnikom pomaga razumeti, kako uporabljati vaš paket, in spodbuja prispevke.
3. Pišite jasne in jedrnate dokumentacije
Pišite jasne in jedrnate dokumentacije za svoj paket, vključno z dokumentacijo API-ja, vodniki in primeri. Uporabite orodja, kot sta Sphinx ali Read the Docs, za ustvarjanje dokumentacije iz komentarjev vaše kode.
4. Uporabite licenco
Izberite licenco za svoj paket, ki jasno določa pogoje, pod katerimi ga je mogoče uporabljati, spreminjati in distribuirati. Pogoste licence vključujejo MIT, Apache 2.0 in GPL.
5. Temeljito preizkusite svoj paket
Svoj paket temeljito preizkusite z uporabo orodij za samodejno testiranje, kot sta pytest ali unittest. Napišite enotske teste, integracijske teste in končno-do-konca teste, da zagotovite, da vaš paket pravilno deluje v različnih scenarijih.
6. Uporabite neprekinjeno integracijo (CI)
Uporabite orodja za neprekinjeno integracijo (CI), kot sta GitHub Actions, GitLab CI ali Jenkins, za samodejno gradnjo in testiranje vašega paketa ob vsaki spremembi kode. To pomaga zgodaj odkriti napake in zagotavlja, da je vaš paket vedno v delujočem stanju.
7. Podpišite svoje pakete
Podpišite svoje pakete, da preverite njihovo pristnost in celovitost. To pomaga preprečiti, da bi zlonamerni akterji distribuirali spremenjene pakete. Uporabite orodja, kot sta gpg ali keyring, za podpis svojih paketov.
Napredne tehnike Wheel-a
Za naprednejše primere uporabe razmislite o naslednjih tehnikah:
1. Uporaba build
Paket build zagotavlja sodoben in standardiziran način za gradnjo Python paketov. Podpira tako Wheel kot distribucije izvorne kode in ponuja enostavnejši vmesnik kot setuptools.
pip install build python -m build
2. Urejalne namestitve
Urejalne namestitve vam omogočajo namestitev paketa na način, ki neposredno povezuje izvorno kodo. To je koristno za razvoj, saj so spremembe v izvorni kodi takoj vidne v nameščenem paketu, ne da bi ga bilo treba ponovno namestiti.
pip install -e .
3. Prilagajanje postopka gradnje
Postopek gradnje lahko prilagodite z definicijo skriptov za gradnjo ali z uporabo sistemov gradnje, kot sta Meson ali CMake. To vam omogoča obravnavanje bolj zapletenih scenarijev gradnje, kot je gradnja C razširitev s posebnimi zastavicami prevajalnika ali povezovanje z zunanjimi knjižnicami.
4. Uporaba auditwheel
Orodje auditwheel se uporablja za pregledovanje in popravljanje Linux Wheels, ki vsebujejo deljene knjižnice. Zagotavlja, da Wheel vsebuje vse potrebne odvisnosti za delovanje na široki paleti distribucij Linuxa.
pip install auditwheel auditwheel repair dist/my_package-0.1.0-py39-linux_x86_64.whl
Zaključek
Format distribucije Wheel je bistveno orodje za Python razvijalce, ki si prizadevajo za učinkovito, zanesljivo in varno distribucijo paketov. Z upoštevanjem korakov, opisanih v tem vodniku, in sprejemanjem najboljših praks lahko ustvarite Wheel pakete, ki poenostavijo postopek namestitve, zmanjšajo odvisnosti od orodij za gradnjo in izboljšajo splošno uporabniško izkušnjo. Ne glede na to, ali distribuirate pakete odprtokodni skupnosti ali nameščate notranje aplikacije, je razumevanje in uporaba formata Wheel dragocena veščina za vsakega Python razvijalca. Ker se Python še naprej razvija, sprejemanje sodobnih praks pakiranja, kot je Wheel, zagotavlja, da vaši projekti ostanejo dostopni in vzdrževani za globalno občinstvo.
Z uporabo teh praks prispevate k bolj robustnemu in dostopnemu Python ekosistemu po vsem svetu.