Pythoni paketi struktuur: Setup.py vs. Pyproject.toml – põhjalik juhend

Aastaid oli setup.py fail Pythoni pakettide haldamise nurgakiviks. Maastik on aga arenenud ja pyproject.toml on tõusnud kaasaegse alternatiivina. See põhjalik juhend uurib nende kahe lähenemisviisi erinevusi, aidates teil mõista, kumb neist teie projektile sobib ja kuidas oma Pythoni pakette tõhusalt hallata.

Aluste mõistmine

Mis on Pythoni pakett?

Pythoni pakett on viis oma Pythoni koodi korraldamiseks ja levitamiseks. See võimaldab teil seotud mooduleid gruppida kataloogihierarhiaks, muutes teie koodi moodulaarsemaks, korduvkasutatavamaks ja hooldatavamaks. Paketid on olulised oma koodi teistega jagamiseks ja oma projektides sõltuvuste haldamiseks.

Paketi metaandmete roll

Paketi metaandmed pakuvad olulist teavet teie paketi kohta, nagu selle nimi, versioon, autor, sõltuvused ja sisendipunktid. Pakettide haldurid, nagu pip, kasutavad neid metaandmeid teie pakettide installimiseks, täiendamiseks ja haldamiseks. Ajalooliselt oli setup.py selle metaandmete määratlemise peamine viis.

Setup.py: traditsiooniline lähenemisviis

Mis on Setup.py?

setup.py on Pythoni skript, mis kasutab setuptools teeki oma paketi struktuuri ja metaandmete määratlemiseks. See on dünaamiliselt täidetav fail, mis tähendab, et see käitab paketi konfigureerimiseks Pythoni koodi.

Setup.py peamised komponendid

Tüüpiline setup.py fail sisaldab järgmisi komponente:

• Paketi nimi: teie paketi nimi (nt my_package).
• Versioon: teie paketi versiooninumber (nt 1.0.0).
• Autori ja hooldaja teave: üksikasjad paketi autori ja hooldaja kohta.
• Sõltuvused: loend teistest pakettidest, millest teie pakett sõltub (nt requests >= 2.20.0).
• Sisendipunktid: käsurea skriptide või teie paketi muude sisendipunktide definitsioonid.
• Paketi andmed: mitte-koodifailid (nt konfiguratsioonifailid, andmefailid), mis tuleks paketti lisada.

Setup.py näide

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

            

              
                Copy
              
            
          

Setup.py eelised

• Tuttavus: see on traditsiooniline ja tuntud lähenemisviis, seega paljud arendajad tunnevad seda juba.
• Paindlikkus: Kuna see on Pythoni skript, pakub see suurt paindlikkust. Saate vajadusel sooritada keerulist loogikat ja kohandada ehitusprotsessi.
• Laiendatavus: Setuptools pakub rikkalikku funktsioonide komplekti ja seda saab laiendada kohandatud käskude ja laiendustega.

Setup.py puudused

• Dünaamiline täitmine: setup.py dünaamiline olemus võib olla turvarisk, kuna see täidab ehitusprotsessi ajal suvalist koodi.
• Implitsiitsed sõltuvused: setup.py tugineb sageli implitsiitsetele sõltuvustele, nagu setuptools ise, mis võib põhjustada vastuolusid ja vigu.
• Keerukus: keeruliste projektide puhul võib setup.py muutuda suureks ja raskesti hooldatavaks.
• Piiratud deklaratiivne konfigureerimine: suur osa paketi metaandmetest on määratletud käskivalt, mitte deklaratiivselt, muutes selle mõistmise raskemaks.

Pyproject.toml: kaasaegne alternatiiv

Mis on Pyproject.toml?

pyproject.toml on konfiguratsioonifail, mis kasutab TOML (Tom's Obvious, Minimal Language) vormingut oma paketi ehitussüsteemi ja metaandmete määratlemiseks. See on deklaratiivne lähenemisviis, mis tähendab, et määrate, mida soovite saavutada, mitte seda, kuidas seda saavutada.

Pyproject.toml peamised jaotised

• [build-system]: Määratleb kasutatava ehitussüsteemi (nt setuptools, poetry, flit).
• [project]: Sisaldab projekti metaandmeid, nagu selle nimi, versioon, kirjeldus, autorid ja sõltuvused.
• [tool.poetry] või [tool.flit]: Jaotised tööriistaspetsiifilisteks konfiguratsioonideks (nt Poetry, Flit).

Pyproject.toml näide (koos Setuptoolsiga)

            [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"


            

              
                Copy
              
            
          

Pyproject.toml näide (koos Poetryga)

            [tool.poetry]
name = "my_package"
version = "1.0.0"
description = "A simple Python package"
authors = ["John Doe "]
license = "MIT"
readme = "README.md"

[tool.poetry.dependencies]
python = ">=3.7,<3.12"
requests = ">=2.20.0"

[tool.poetry.dev-dependencies]
pytest = "^6.0"
flake8 = "^3.9"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

            

              
                Copy
              
            
          

Pyproject.toml eelised

• Deklaratiivne konfigureerimine: pyproject.toml pakub deklaratiivset viisi oma paketi metaandmete määratlemiseks, muutes selle mõistmise ja hooldamise lihtsamaks.
• Standardiseeritud ehitussüsteem: see määratleb kasutatava ehitussüsteemi, tagades ühtlased ehitused erinevates keskkondades.
• Täiustatud sõltuvuste haldus: tööriistad nagu Poetry ja Pipenv integreeruvad sujuvalt pyproject.toml-iga, et pakkuda robustseid sõltuvuste haldusfunktsioone.
• Vähendatud turvariskid: kuna tegemist on staatilise konfiguratsioonifailiga, kõrvaldab see ehitusprotsessi ajal dünaamilise koodi täitmisega seotud turvariskid.
• Integratsioon kaasaegsete tööriistadega: pyproject.toml on standard kaasaegsete Pythoni paketitööriistade nagu Poetry, Pipenv ja Flit jaoks.

Pyproject.toml puudused

• Õppimiskõver: arendajad peavad võib-olla õppima uue süntaksi (TOML) ja uue viisi pakettide haldamisele mõelda.
• Piiratud paindlikkus: see ei pruugi sobida väga kohandatud ehitusprotsesside jaoks, mis nõuavad keerukat loogikat.
• Tööriistade sõltuvus: peate valima ja õppima, kuidas kasutada konkreetset ehitussüsteemi (nt Setuptools, Poetry, Flit).

Setup.py ja Pyproject.toml võrdlus

Siin on tabel, mis võrdleb setup.py ja pyproject.toml peamisi erinevusi:

Migreerimisstrateegiad: Setup.py-st Pyproject.toml-i

Migreerimine setup.py-st pyproject.toml-i võib tunduda hirmutav, kuid see on väärt investeering pikaajaliseks hooldatavuseks ja järjepidevuseks. Siin on mõned strateegiad, mida saate kasutada:

1. Alustage minimaalse Pyproject.toml-iga

Looge põhiline pyproject.toml fail, mis määratleb ehitussüsteemi, ja migreerige seejärel järk-järgult metaandmed setup.py-st pyproject.toml-i.

            [build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

            

              
                Copy
              
            
          

2. Kasutage Setuptools koos Pyproject.toml-iga

Jätkake Setuptoolsi kasutamist oma ehitussüsteemina, kuid määrake projekti metaandmed pyproject.toml-is. See võimaldab teil kasutada pyproject.toml eeliseid, säilitades samal ajal tuttava tööriista.

3. Migreerige kaasaegsesse tööriista nagu Poetry

Kaaluge migreerimist kaasaegsesse tööriista nagu Poetry või Pipenv. Need tööriistad pakuvad põhjalikke sõltuvuste haldusfunktsioone ja integreeruvad sujuvalt pyproject.toml-iga.

Näide: migreerimine Poetry-sse

1. Installige Poetry: pip install poetry
2. Initialiseerige Poetry oma projektis: poetry init (See juhendab teid pyproject.toml faili loomisel)
3. Lisage oma sõltuvused: poetry add requests (või mis tahes muud sõltuvused)
4. Ehitage oma pakett: poetry build

4. Kasutage automatiseeritud migreerimise tööriistu

Mõned tööriistad saavad aidata migreerimisprotsessi automatiseerida. Näiteks saate kasutada tööriistu oma setup.py faili teisendamiseks pyproject.toml failiks.

Pythoni pakettide haldamise parimad tavad

1. Kasutage virtuaalset keskkonda

Kasutage alati virtuaalset keskkonda, et isoleerida oma projekti sõltuvused süsteemiülesest Pythoni installatsioonist. See väldib vastuolusid ja tagab, et teie projektil on õiged sõltuvused.

Näide venv kasutades:

            python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS süsteemides
.venv\Scripts\activate  # Windows süsteemides

            

              
                Copy
              
            
          

Näide conda kasutades:

            conda create -n myenv python=3.9
conda activate myenv

            

              
                Copy
              
            
          

2. Määrake sõltuvused täpselt

Kasutage versioonipiiranguid oma sõltuvuste ühilduvate versioonide määramiseks. See vähendab ühilduvuse muutustest tingitud ootamatuid käitumisi. Kasutage oma sõltuvuste haldamiseks selliseid tööriistu nagu pip-tools.

Näide sõltuvuse spetsifikatsioonist:

            
requests >= 2.20.0, < 3.0.0

            

              
                Copy
              
            
          

3. Kasutage järjepidevat ehitussüsteemi

Valige ehitussüsteem (nt Setuptools, Poetry, Flit) ja pidage sellest kinni. See tagab järjepidevad ehitused erinevates keskkondades ja lihtsustab paketiprotsessi.

4. Dokumenteerige oma pakett

Kirjutage oma paketi jaoks selge ja kokkuvõtlik dokumentatsioon. See aitab kasutajatel mõista, kuidas teie paketti kasutada, ja teeb teistele teie projekti panustamise lihtsamaks. Kasutage dokumentatsiooni genereerimiseks koodist selliseid tööriistu nagu Sphinx.

5. Kasutage pidevat integratsiooni (CI)

Seadistage CI süsteem (nt GitHub Actions, Travis CI, GitLab CI), et automaatselt ehitada, testida ja levitada oma paketti iga kord, kui teie koodis muudatusi tehakse. See aitab tagada, et teie pakett oleks alati töökorras.

Näide GitHub Actions konfiguratsioonist:

            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

            

              
                Copy
              
            
          

6. Avaldage oma pakett PyPI-s

Jagage oma paketti maailmaga, avaldades selle Python Package Index (PyPI) kaudu. See muudab selle hõlpsaks teistele teie paketi installimiseks ja kasutamiseks.

Sammud PyPI-s avaldamiseks:

1. Registreeruge PyPI ja TestPyPI konto.
2. Installige twine: pip install twine.
3. Ehitage oma pakett: poetry build või python setup.py sdist bdist_wheel.
4. Laadige oma pakett üles TestPyPI-sse: twine upload --repository testpypi dist/*.
5. Laadige oma pakett üles PyPI-sse: twine upload dist/*.

Reaalse maailma näited

Vaatame, kuidas mõned populaarsed Pythoni projektid kasutavad pyproject.toml:

• Poetry: Kasutab oma pakettide haldamiseks pyproject.toml-i.
• Black: Kompromissitu koodivormindaja kasutab samuti pyproject.toml-i.
• FastAPI: Kaasaegne, kiire (kõrge jõudlusega) veebiraamistik Pythoniga API-de loomiseks kasutab seda samuti.

Järeldus

pyproject.toml esindab kaasaegset standardit Pythoni pakettide haldamiseks, pakkudes deklaratiivset ja turvalist viisi oma paketi metaandmete määratlemiseks ja sõltuvuste haldamiseks. Kuigi setup.py on meid hästi teeninud, on migreerimine pyproject.toml-i väärt investeering pikaajaliseks hooldatavuseks, järjepidevuseks ja integratsiooniks kaasaegsete tööriistadega. Parimate tavade omaksvõtmise ja õigete tööriistade kasutamisega saate oma Pythoni pakettide loomise töövoogu sujuvamaks muuta ning luua kõrge kvaliteediga, korduvkasutatavaid pakette.

Lisaresursid

• Python Packaging User Guide: Tool Recommendations
• Pip: pyproject.toml support
• Poetry: The pyproject.toml file
• Setuptools: Using pyproject.toml