En dyptgående sammenligning av setup.py og pyproject.toml for Python-pakkehåndtering, som dekker beste praksis, migreringsstrategier og moderne verktøy.
Python-pakkestruktur: Setup.py vs. Pyproject.toml – En omfattende guide
I mange år var setup.py-filen selve hjørnesteinen i Python-pakkehåndtering. Landskapet har imidlertid utviklet seg, og pyproject.toml har dukket opp som et moderne alternativ. Denne omfattende guiden utforsker forskjellene mellom disse to tilnærmingene, og hjelper deg med å forstå hvilken som er riktig for prosjektet ditt og hvordan du effektivt kan administrere Python-pakkene dine.
Forstå det grunnleggende
Hva er en Python-pakke?
En Python-pakke er en måte å organisere og distribuere Python-koden din på. Den lar deg gruppere relaterte moduler i et kataloghierarki, noe som gjør koden din mer modulær, gjenbrukbar og vedlikeholdbar. Pakker er avgjørende for å dele koden din med andre og for å administrere avhengigheter i prosjektene dine.
Rollen til pakkemetadata
Pakkemetadata gir viktig informasjon om pakken din, for eksempel navn, versjon, forfatter, avhengigheter og inngangspunkter. Disse metadataene brukes av pakkebehandlere som pip til å installere, oppgradere og administrere pakkene dine. Historisk sett var setup.py den primære måten å definere disse metadataene på.
Setup.py: Den tradisjonelle tilnærmingen
Hva er Setup.py?
setup.py er et Python-skript som bruker setuptools-biblioteket til å definere strukturen og metadataene til pakken din. Det er en dynamisk utført fil, noe som betyr at den kjører Python-kode for å konfigurere pakken.
Viktige komponenter i Setup.py
En typisk setup.py-fil inneholder følgende komponenter:
- Pakkenavn: Navnet på pakken din (f.eks.
my_package). - Versjon: Versjonsnummeret på pakken din (f.eks.
1.0.0). - Informasjon om forfatter og vedlikeholder: Detaljer om forfatteren og vedlikeholderen av pakken.
- Avhengigheter: En liste over andre pakker som pakken din er avhengig av (f.eks.
requests >= 2.20.0). - Inngangspunkter: Definisjoner for kommandolinjeskript eller andre inngangspunkter til pakken din.
- Pakke data: Ikke-kodefiler (f.eks. konfigurasjonsfiler, datafiler) som skal inkluderes i pakken.
Eksempel på Setup.py
```python from setuptools import setup, find_packages setup( name='my_package', version='1.0.0', author='John Doe', author_email='john.doe@example.com', description='A simple Python package', packages=find_packages(), install_requires=[ 'requests >= 2.20.0', ], entry_points={ 'console_scripts': [ 'my_script = my_package.module:main', ], }, classifiers=[ 'Programming Language :: Python :: 3', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', ], ) ```Fordeler med Setup.py
- Kjennskap: Det er den tradisjonelle og velkjente tilnærmingen, så mange utviklere er allerede kjent med den.
- Fleksibilitet: Fordi det er et Python-skript, tilbyr det en høy grad av fleksibilitet. Du kan utføre kompleks logikk og tilpasse byggeprosessen etter behov.
- Utvidbarhet: Setuptools tilbyr et rikt sett med funksjoner og kan utvides med egendefinerte kommandoer og utvidelser.
Ulemper med Setup.py
- Dynamisk utførelse: Den dynamiske naturen til
setup.pykan være en sikkerhetsrisiko, da den utfører vilkårlig kode under byggeprosessen. - Implisitte avhengigheter:
setup.pyer ofte avhengig av implisitte avhengigheter, for eksempel setuptools selv, noe som kan føre til inkonsekvenser og feil. - Kompleksitet: For komplekse prosjekter kan
setup.pybli stor og vanskelig å vedlikeholde. - Begrenset deklarativ konfigurasjon: Mye av pakkemetadataene er definert imperativt i stedet for deklarativt, noe som gjør det vanskeligere å resonnere om.
Pyproject.toml: Det moderne alternativet
Hva er Pyproject.toml?
pyproject.toml er en konfigurasjonsfil som bruker TOML-formatet (Tom's Obvious, Minimal Language) til å definere byggesystemet og metadataene til pakken din. Det er en deklarativ tilnærming, som betyr at du spesifiserer hva du vil oppnå, i stedet for hvordan du oppnår det.
Viktige seksjoner i Pyproject.toml
En typiskpyproject.toml-fil inneholder følgende seksjoner:
[build-system]: Definerer byggesystemet som skal brukes (f.eks.setuptools,poetry,flit).[project]: Inneholder metadata om prosjektet, for eksempel navn, versjon, beskrivelse, forfattere og avhengigheter.[tool.poetry]eller[tool.flit]: Seksjoner for verktøyspesifikke konfigurasjoner (f.eks. Poetry, Flit).
Eksempel på Pyproject.toml (med Setuptools)
```toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = [ { name = "John Doe", email = "john.doe@example.com" } ] dependencies = [ "requests >= 2.20.0", ] [project.scripts] my_script = "my_package.module:main" [project.optional-dependencies] dev = [ "pytest", "flake8", ] [project.classifiers] classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.urls] homepage = "https://example.com" repository = "https://github.com/example/my_package" ```Eksempel på Pyproject.toml (med Poetry)
```toml [tool.poetry] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = ["John DoeFordeler med Pyproject.toml
- Deklarativ konfigurasjon:
pyproject.tomlgir en deklarativ måte å definere pakkemetadataene dine på, noe som gjør det lettere å forstå og vedlikeholde. - Standardisert byggesystem: Den spesifiserer byggesystemet som skal brukes, og sikrer konsistente bygg på tvers av forskjellige miljøer.
- Forbedret avhengighetshåndtering: Verktøy som Poetry og Pipenv integreres sømløst med
pyproject.tomlfor å gi robuste funksjoner for avhengighetshåndtering. - Reduserte sikkerhetsrisikoer: Fordi det er en statisk konfigurasjonsfil, eliminerer den sikkerhetsrisikoene forbundet med dynamisk utførelse av kode under byggeprosessen.
- Integrasjon med moderne verktøy:
pyproject.tomler standarden for moderne Python-pakkeverktøy som Poetry, Pipenv og Flit.
Ulemper med Pyproject.toml
- Læringskurve: Utviklere kan trenge å lære en ny syntaks (TOML) og en ny måte å tenke på pakkehåndtering.
- Begrenset fleksibilitet: Det er kanskje ikke egnet for svært tilpassede byggeprosesser som krever kompleks logikk.
- Verktøyavhengighet: Du må velge og lære å bruke et spesifikt byggesystem (f.eks. Setuptools, Poetry, Flit).
Sammenligning av Setup.py og Pyproject.toml
Her er en tabell som oppsummerer de viktigste forskjellene mellom setup.py og pyproject.toml:
| Funksjon | Setup.py | Pyproject.toml |
|---|---|---|
| Konfigurasjonsstil | Imperativ (Python-kode) | Deklarativ (TOML) |
| Byggesystem | Implisitt (Setuptools) | Eksplisitt (spesifisert i [build-system]) |
| Sikkerhet | Potensielt mindre sikker (dynamisk utførelse) | Mer sikker (statisk konfigurasjon) |
| Avhengighetshåndtering | Grunnleggende (install_requires) |
Avansert (integrasjon med Poetry, Pipenv) |
| Verktøy | Tradisjonell (Setuptools) | Moderne (Poetry, Pipenv, Flit) |
| Fleksibilitet | Høy | Moderat |
| Kompleksitet | Kan være høy for komplekse prosjekter | Generelt lavere |
Migreringsstrategier: Fra Setup.py til Pyproject.toml
Å migrere fra setup.py til pyproject.toml kan virke skremmende, men det er en verdt investering for langsiktig vedlikeholdbarhet og konsistens. Her er noen strategier du kan bruke:
1. Start med en minimal Pyproject.toml
Opprett en grunnleggende pyproject.toml-fil som spesifiserer byggesystemet, og migrer deretter gradvis metadataene fra setup.py til pyproject.toml.
2. Bruk Setuptools med Pyproject.toml
Fortsett å bruke Setuptools som byggesystem, men definer prosjektmetadataene i pyproject.toml. Dette lar deg dra nytte av fordelene med pyproject.toml mens du fortsatt bruker et kjent verktøy.
3. Migrer til et moderne verktøy som Poetry
Vurder å migrere til et moderne verktøy som Poetry eller Pipenv. Disse verktøyene gir omfattende funksjoner for avhengighetshåndtering og integreres sømløst med pyproject.toml.
Eksempel: Migrering til Poetry
- Installer Poetry:
pip install poetry - Initialiser Poetry i prosjektet ditt:
poetry init(Dette vil veilede deg gjennom opprettelsen av enpyproject.toml-fil) - Legg til avhengighetene dine:
poetry add requests(eller andre avhengigheter) - Bygg pakken din:
poetry build
4. Bruk verktøy for automatisert migrering
Noen verktøy kan hjelpe deg med å automatisere migreringsprosessen. Du kan for eksempel bruke verktøy til å konvertere setup.py-filen din til en pyproject.toml-fil.
Beste praksis for Python-pakkehåndtering
1. Bruk et virtuelt miljø
Bruk alltid et virtuelt miljø for å isolere prosjektets avhengigheter fra den systemomfattende Python-installasjonen. Dette forhindrer konflikter og sikrer at prosjektet ditt har de riktige avhengighetene.
Eksempel ved bruk av venv:
Eksempel ved bruk av conda:
2. Spesifiser avhengigheter nøyaktig
Bruk versjonsbegrensninger for å spesifisere de kompatible versjonene av avhengighetene dine. Dette forhindrer uventet oppførsel forårsaket av inkompatible bibliotekoppdateringer. Bruk verktøy som pip-tools for å administrere avhengighetene dine.
Eksempel på avhengighetsspesifikasjon:
``` requests >= 2.20.0, < 3.0.0 ```3. Bruk et konsistent byggesystem
Velg et byggesystem (f.eks. Setuptools, Poetry, Flit) og hold deg til det. Dette sikrer konsistente bygg på tvers av forskjellige miljøer og forenkler pakkeprosessen.
4. Dokumenter pakken din
Skriv klar og konsis dokumentasjon for pakken din. Dette hjelper brukere å forstå hvordan de skal bruke pakken din og gjør det lettere for andre å bidra til prosjektet ditt. Bruk verktøy som Sphinx for å generere dokumentasjon fra koden din.
5. Bruk kontinuerlig integrasjon (CI)
Sett opp et CI-system (f.eks. GitHub Actions, Travis CI, GitLab CI) for automatisk å bygge, teste og distribuere pakken din når endringer gjøres i koden din. Dette bidrar til å sikre at pakken din alltid er i en fungerende tilstand.
Eksempel på GitHub Actions-konfigurasjon:
```yaml name: Python Package on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 uses: actions/setup-python@v4 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install poetry poetry install - name: Lint with flake8 run: | poetry run flake8 . - name: Test with pytest run: | poetry run pytest ```6. Publiser pakken din til PyPI
Del pakken din med verden ved å publisere den til Python Package Index (PyPI). Dette gjør det enkelt for andre å installere og bruke pakken din.
Trinn for å publisere til PyPI:
- Registrer en konto på PyPI og TestPyPI.
- Installer
twine:pip install twine. - Bygg pakken din:
poetry buildellerpython setup.py sdist bdist_wheel. - Last opp pakken din til TestPyPI:
twine upload --repository testpypi dist/*. - Last opp pakken din til PyPI:
twine upload dist/*.
Eksempler fra virkeligheten
La oss se på hvordan noen populære Python-prosjekter bruker pyproject.toml:
- Poetry: Bruker
pyproject.tomlfor sin egen pakkehåndtering. - Black: Den kompromissløse kodeformatereren bruker også
pyproject.toml. - FastAPI: Et moderne, raskt (høyytelses) webrammeverk for å bygge API-er med Python bruker det også.
Konklusjon
pyproject.toml representerer den moderne standarden for Python-pakkehåndtering, og tilbyr en deklarativ og sikker måte å definere pakkemetadataene dine og administrere avhengigheter på. Mens setup.py har tjent oss godt, er migrering til pyproject.toml en verdt investering for langsiktig vedlikeholdbarhet, konsistens og integrasjon med moderne verktøy. Ved å ta i bruk beste praksis og bruke de riktige verktøyene, kan du strømlinjeforme Python-pakkearbeidsflyten din og lage gjenbrukbare pakker av høy kvalitet.