Wheel-distributionsformat: Skapa binära paket för Python

Pythons ekosystem förlitar sig i hög grad på effektiv pakethantering. En av hörnstenarna i detta ekosystem är Wheel-distributionsformatet, ofta identifierat med filändelsen .whl. Denna guide fördjupar sig i detaljerna kring Wheel-formatet, dess fördelar och hur man skapar binära paket för Python, riktat till utvecklare globalt som siktar på smidig och pålitlig programvarudistribution.

Vad är Wheel-formatet?

Wheel-formatet är ett färdigbyggt paketformat för Python. Det är utformat för att vara enklare att installera än källdistributioner (sdist). Det fungerar som en ersättning för det äldre egg-formatet och åtgärdar flera av dess brister. I grunden är det ett ZIP-arkiv med en specifik struktur och metadata som gör det möjligt för pip och andra installationsverktyg att snabbt installera paketet utan att behöva bygga det från källkoden.

Huvudegenskaper för Wheel

• Plattformsoberoende (där det är tillämpligt): Wheels kan byggas för specifika plattformar och arkitekturer (t.ex. Windows 64-bit, Linux x86_64) eller vara plattformsoberoende (ren Python). Detta gör det möjligt att skapa optimerade binärer för olika operativsystem.
• Enkel installation: Wheel-formatet inkluderar förkompilerade distributioner, vilket minimerar behovet av att kompilera kod under installationen. Detta påskyndar installationsprocessen avsevärt, särskilt för paket med C-tillägg eller andra kompilerade komponenter.
• Inkludering av metadata: Wheels innehåller all nödvändig metadata om paketet, inklusive beroenden, versionsinformation och ingångspunkter. Denna metadata är avgörande för att pakethanterare som pip ska kunna hantera beroenden och installera paketet korrekt.
• Atomär installation: pip installerar paket från Wheels på ett atomärt sätt. Detta innebär att installationen antingen slutförs framgångsrikt eller rullas tillbaka helt, vilket förhindrar delvis installerade paket som kan leda till inkonsekvenser.
• Reproducerbarhet: Wheels förbättrar reproducerbarheten genom att tillhandahålla en konsekvent byggartefakt som kan installeras i flera miljöer utan att kräva omkompilering (förutsatt att målplattformen matchar).

Varför använda Wheels?

Att välja Wheels framför källdistributioner erbjuder många fördelar som effektiviserar installations- och driftsättningsprocessen för paket. Här är en genomgång av de viktigaste fördelarna:

Snabbare installationstider

En av de mest betydande fördelarna med Wheels är deras hastighet. Genom att tillhandahålla förkompilerade distributioner eliminerar Wheels behovet av att kompilera kod under installationen. Detta är särskilt fördelaktigt för paket med kompilerade tillägg skrivna i C, C++ eller andra språk. Föreställ dig att driftsätta ett komplext vetenskapligt bibliotek; att använda en Wheel minskar drastiskt installationstiden på slutanvändarens datorer.

Exempel: Att installera numpy från källkoden kan ta flera minuter, särskilt på äldre hårdvara. Att installera från en Wheel tar vanligtvis några sekunder.

Minskat beroende av byggverktyg

Att installera paket från källkoden kräver ofta att användare har nödvändiga byggverktyg (kompilatorer, headers, etc.) installerade på sitt system. Detta kan vara ett hinder för inträde, särskilt för användare som inte är bekanta med mjukvaruutveckling. Wheels tar bort detta beroende, vilket gör installationen enklare och mer tillgänglig.

Exempel: En data scientist i ett forskningslabb kanske inte har de nödvändiga kompilatorerna för att bygga ett paket från källkoden. En Wheel gör det möjligt för dem att installera paketet direkt utan att behöva konfigurera sin miljö.

Förbättrad tillförlitlighet

Genom att tillhandahålla förkompilerade binärer säkerställer Wheels att paketet installeras på ett konsekvent sätt i olika miljöer. Detta minskar risken för installationsfel på grund av variationer i systemkonfigurationer eller versioner av byggverktyg. Denna konsistens är av största vikt för applikationer som kräver stabilt och förutsägbart beteende.

Exempel: En webbapplikation som driftsätts på flera servrar måste ha konsekventa paketversioner. Att använda Wheels säkerställer att samma binärer installeras på varje server, vilket minimerar risken för driftsättningsproblem.

Förbättrad säkerhet

Wheels kan signeras för att verifiera deras äkthet och integritet. Detta hjälper till att förhindra att illasinnade aktörer distribuerar manipulerade paket. Paketsignering ger ett extra säkerhetslager, vilket säkerställer att användare installerar betrodd programvara.

Exempel: Organisationer kan implementera policyer som kräver att alla paket är signerade innan de driftsätts i produktionsmiljöer. Detta skyddar mot supply chain-attacker där skadlig kod injiceras i paket.

Skapa Wheel-paket: En steg-för-steg-guide

Att skapa Wheel-paket är en enkel process som involverar användning av paketen setuptools och wheel. Här är en detaljerad guide:

1. Konfigurera ditt projekt

Först, se till att ditt projekt är korrekt strukturerat. Som ett minimum behöver du en setup.py-fil och ditt pakets källkod.

Exempel på projektstruktur:

my_package/
 ├── my_module/
 │   ├── __init__.py
 │   └── my_function.py
 ├── setup.py
 └── README.md

2. setup.py-filen

Filen setup.py är hjärtat i ditt projekt. Den innehåller metadata om ditt paket och definierar hur det ska byggas och installeras. Här är ett exempel på en setup.py-fil:

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',
 ],
)

Förklaring av nyckelfält:

• name: Namnet på ditt paket. Detta är det namn användare kommer att använda för att installera ditt paket (t.ex. pip install my_package).
• version: Versionsnumret för ditt paket. Följ semantisk versionering (SemVer) för konsekventa versioneringsmetoder (t.ex. 0.1.0, 1.0.0, 2.5.1).
• description: En kort beskrivning av ditt paket.
• long_description: En detaljerad beskrivning av ditt paket. Denna läses ofta från en README.md-fil.
• url: URL:en till ditt pakets hemsida eller arkiv.
• author: Namnet på paketets författare.
• author_email: E-postadressen till paketets författare.
• license: Licensen under vilken ditt paket distribueras (t.ex. MIT, Apache 2.0, GPL).
• packages: En lista över paket som ska inkluderas i din distribution. find_packages() hittar automatiskt alla paket i ditt projekt.
• install_requires: En lista över beroenden som ditt paket kräver. pip installerar automatiskt dessa beroenden när ditt paket installeras.
• classifiers: Metadata som hjälper användare att hitta ditt paket på PyPI (Python Package Index). Dessa klassificerare beskriver utvecklingsstatus, avsedd målgrupp, licens och stödda Python-versioner.

3. Installera wheel

Om du inte har wheel-paketet installerat kan du installera det med pip:

pip install wheel

4. Bygga Wheel-paketet

Navigera till rotkatalogen för ditt projekt (där setup.py finns) och kör följande kommando:

python setup.py bdist_wheel

Detta kommando skapar en dist-katalog som innehåller Wheel-paketet (.whl-fil) och en källdistribution (.tar.gz-fil).

5. Hitta Wheel-filen

Den genererade Wheel-filen kommer att finnas i dist-katalogen. Dess namn följer formatet package_name-version-pyXX-none-any.whl, där:

• package_name: Namnet på ditt paket.
• version: Versionsnumret för ditt paket.
• pyXX: Python-versionen som paketet är kompatibelt med (t.ex. py37 för Python 3.7).
• none: Indikerar att paketet inte är plattformsspecifikt.
• any: Indikerar att paketet är kompatibelt med alla arkitekturer.

För plattformsspecifika wheels kommer taggarna none och any att ersättas med plattforms- och arkitekturidentifierare (t.ex. win_amd64 för Windows 64-bit).

6. Testa Wheel-paketet

Innan du distribuerar ditt Wheel-paket är det viktigt att testa det för att säkerställa att det installeras korrekt. Du kan göra detta med pip:

pip install dist/my_package-0.1.0-py39-none-any.whl

Ersätt dist/my_package-0.1.0-py39-none-any.whl med den faktiska sökvägen till din Wheel-fil.

7. Distribuera ditt Wheel-paket

När du har byggt och testat ditt Wheel-paket kan du distribuera det via olika kanaler:

• PyPI (Python Package Index): Det vanligaste sättet att distribuera Python-paket. Du kan ladda upp ditt Wheel-paket till PyPI med twine.
• Privat paketindex: För internt bruk inom en organisation kan du sätta upp ett privat paketindex med verktyg som devpi eller Artifactory.
• Direkt distribution: Du kan också distribuera ditt Wheel-paket direkt till användare via e-post, fildelning eller andra medel.

Hantera C-tillägg och plattformsspecifika Wheels

Att skapa plattformsspecifika Wheels, särskilt de som innehåller C-tillägg, kräver ytterligare steg. Här är en översikt över processen:

1. Kompilera C-tillägg

C-tillägg måste kompileras för varje målplattform. Detta involverar vanligtvis användning av en C-kompilator (t.ex. GCC, MSVC) och plattformsspecifika byggverktyg.

Exempel: På Windows behöver du använda Microsoft Visual C++-kompilatorn för att bygga C-tillägg. På Linux använder du vanligtvis GCC.

2. Använda cffi eller Cython

Verktyg som cffi och Cython kan förenkla processen att skapa C-tillägg. cffi låter dig anropa C-kod direkt från Python utan att skriva C-kod själv, medan Cython låter dig skriva C-liknande kod som kompileras till C-tillägg.

3. Definiera plattformsspecifika beroenden

I din setup.py-fil kan du definiera plattformsspecifika beroenden med parametrarna setup_requires och install_requires. Detta gör att du kan specificera olika beroenden för olika plattformar.

Exempel:

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. Bygga plattformsspecifika Wheels

För att bygga plattformsspecifika Wheels behöver du använda lämplig byggmiljö för varje målplattform. Detta kan innebära att använda virtuella maskiner eller containeriseringstekniker som Docker.

Exempel: För att bygga en Wheel för Windows 64-bit behöver du köra byggprocessen på ett Windows 64-bit-system med Microsoft Visual C++-kompilatorn installerad.

Bästa praxis för att skapa Wheel-paket

Att följa bästa praxis säkerställer att dina Wheel-paket är tillförlitliga, underhållbara och lätta att använda. Här är några viktiga rekommendationer:

1. Använd semantisk versionering (SemVer)

Följ semantisk versionering (SemVer) för konsekventa versioneringsmetoder. SemVer använder ett tredelat versionsnummer (MAJOR.MINOR.PATCH) för att indikera typen av ändringar i varje utgåva.

• MAJOR: Indikerar inkompatibla API-ändringar.
• MINOR: Indikerar nya funktioner som är bakåtkompatibla.
• PATCH: Indikerar buggfixar som är bakåtkompatibla.

Exempel: Att ändra en funktions parametrar på ett sätt som bryter befintlig kod skulle motivera en höjning av huvudversionen (t.ex. från 1.0.0 till 2.0.0). Att lägga till en ny funktion utan att ändra befintliga skulle motivera en höjning av delversionen (t.ex. från 1.0.0 till 1.1.0). Att åtgärda en bugg skulle motivera en höjning av patch-versionen (t.ex. från 1.0.0 till 1.0.1).

2. Inkludera en README.md-fil

Inkludera en README.md-fil som ger en detaljerad beskrivning av ditt paket, inklusive installationsanvisningar, användningsexempel och riktlinjer för bidrag. Detta hjälper användare att förstå hur de använder ditt paket och uppmuntrar till bidrag.

3. Skriv tydlig och koncis dokumentation

Skriv tydlig och koncis dokumentation för ditt paket, inklusive API-dokumentation, handledningar och exempel. Använd verktyg som Sphinx eller Read the Docs för att generera dokumentation från dina kodkommentarer.

4. Använd en licens

Välj en licens för ditt paket som tydligt definierar villkoren under vilka det kan användas, modifieras och distribueras. Vanliga licenser inkluderar MIT, Apache 2.0 och GPL.

5. Testa ditt paket noggrant

Testa ditt paket noggrant med automatiserade testverktyg som pytest eller unittest. Skriv enhetstester, integrationstester och end-to-end-tester för att säkerställa att ditt paket fungerar korrekt i olika scenarier.

6. Använd kontinuerlig integration (CI)

Använd verktyg för kontinuerlig integration (CI) som GitHub Actions, GitLab CI eller Jenkins för att automatiskt bygga och testa ditt paket när ändringar görs i kodbasen. Detta hjälper till att fånga buggar tidigt och säkerställer att ditt paket alltid är i ett fungerande skick.

7. Signera dina paket

Signera dina paket för att verifiera deras äkthet och integritet. Detta hjälper till att förhindra att illasinnade aktörer distribuerar manipulerade paket. Använd verktyg som gpg eller keyring för att signera dina paket.

Avancerade Wheel-tekniker

För mer avancerade användningsfall, överväg dessa tekniker:

1. Använda build

Paketet build erbjuder ett modernt och standardiserat sätt att bygga Python-paket. Det stöder både Wheel- och källdistributioner och erbjuder ett enklare gränssnitt än setuptools.

pip install build
python -m build

2. Redigerbara installationer

Redigerbara installationer låter dig installera ett paket på ett sätt som länkar direkt till källkoden. Detta är användbart för utveckling, eftersom ändringar i källkoden omedelbart återspeglas i det installerade paketet utan att behöva installera om det.

pip install -e .

3. Anpassa byggprocessen

Du kan anpassa byggprocessen genom att definiera anpassade byggskript eller använda byggsystem som Meson eller CMake. Detta gör att du kan hantera mer komplexa byggscenarier, som att bygga C-tillägg med specifika kompilatorflaggor eller länka mot externa bibliotek.

4. Använda auditwheel

Verktyget auditwheel används för att granska och reparera Linux-Wheels som innehåller delade bibliotek. Det säkerställer att Wheel-paketet innehåller alla nödvändiga beroenden för att köras på ett brett utbud av Linux-distributioner.

pip install auditwheel
auditwheel repair dist/my_package-0.1.0-py39-linux_x86_64.whl

Slutsats

Wheel-distributionsformatet är ett viktigt verktyg för Python-utvecklare som siktar på effektiv, tillförlitlig och säker paketdistribution. Genom att följa stegen som beskrivs i denna guide och anta bästa praxis kan du skapa Wheel-paket som effektiviserar installationsprocessen, minskar beroendet av byggverktyg och förbättrar den övergripande användarupplevelsen. Oavsett om du distribuerar paket till open source-gemenskapen eller driftsätter interna applikationer är förståelse och användning av Wheel-formatet en värdefull färdighet för alla Python-utvecklare. När Python fortsätter att utvecklas säkerställer anammandet av moderna paketeringsmetoder som Wheel att dina projekt förblir tillgängliga och underhållbara för en global publik.

Genom att anamma dessa metoder bidrar du till ett mer robust och tillgängligt Python-ekosystem världen över.