Python Paketų Struktūra: Setup.py prieš Pyproject.toml - Išsamus Vadovas

Jau daugelį metų setup.py failas buvo Python paketų valdymo kertinis akmuo. Tačiau aplinka pasikeitė, ir pyproject.toml iškilo kaip moderni alternatyva. Šis išsamus vadovas nagrinėja šių dviejų metodų skirtumus, padėdamas jums suprasti, kuris iš jų tinka jūsų projektui ir kaip efektyviai valdyti savo Python paketus.

Pagrindų Supratimas

Kas yra Python Paketas?

Python paketas yra būdas organizuoti ir platinti jūsų Python kodą. Jis leidžia jums grupuoti susijusius modulius į katalogų hierarchiją, darant jūsų kodą labiau modulinį, daugkartinio naudojimo ir prižiūrimą. Paketai yra būtini dalinantis savo kodu su kitais ir valdant priklausomybes jūsų projektuose.

Paketų Metaduomenų Vaidmuo

Paketų metaduomenys teikia esminę informaciją apie jūsų paketą, tokią kaip jo pavadinimas, versija, autorius, priklausomybės ir įėjimo taškai. Šiuos metaduomenis naudoja paketų tvarkytuvai, tokie kaip pip, norėdami įdiegti, atnaujinti ir valdyti jūsų paketus. Istoriškai setup.py buvo pagrindinis būdas apibrėžti šiuos metaduomenis.

Setup.py: Tradicinis Metodas

Kas yra Setup.py?

setup.py yra Python scenarijus, kuris naudoja setuptools biblioteką apibrėžti jūsų paketo struktūrą ir metaduomenis. Tai dinamiškai vykdomas failas, reiškiantis, kad jis vykdo Python kodą, kad sukonfigūruotų paketą.

Pagrindiniai Setup.py Komponentai

Tipiniame setup.py faile yra šie komponentai:

• Paketo Pavadinimas: Jūsų paketo pavadinimas (pvz., my_package).
• Versija: Jūsų paketo versijos numeris (pvz., 1.0.0).
• Autoriaus ir Palaikytojo Informacija: Detalės apie paketo autorių ir palaikytoją.
• Priklausomybės: Sąrašas kitų paketų, nuo kurių priklauso jūsų paketas (pvz., requests >= 2.20.0).
• Įėjimo Taškai: Komandų eilutės scenarijų ar kitų įėjimo taškų į jūsų paketą apibrėžimai.
• Paketo Duomenys: Ne kodo failai (pvz., konfigūracijos failai, duomenų failai), kurie turėtų būti įtraukti į paketą.

Setup.py Pavyzdys

            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 Privalumai

• Pažintumas: Tai tradicinis ir gerai žinomas metodas, todėl daugelis programuotojų jį jau pažįsta.
• Lankstumas: Kadangi tai yra Python scenarijus, jis suteikia didelį lankstumą. Galite atlikti sudėtingą logiką ir pritaikyti kūrimo procesą pagal poreikius.
• Plėtimo Galimybės: Setuptools suteikia daugybę funkcijų ir gali būti plečiamas su pasirinktinėmis komandomis ir plėtiniais.

Setup.py Trūkumai

• Dinaminis Vykdymas: setup.py dinamiškumas gali būti saugumo rizika, nes kūrimo metu vykdomas savavališkas kodas.
• Implikuotos Priklausomybės: setup.py dažnai remiasi implikuotomis priklausomybėmis, tokiomis kaip pats setuptools, o tai gali sukelti neatitikimus ir klaidas.
• Sudėtingumas: Sudėtingiems projektams setup.py gali tapti didelis ir sunkiai prižiūrimas.
• Ribota Deklaratyvi Konfigūracija: Didelė dalis paketų metaduomenų yra apibrėžiama imperatyviai, o ne deklaratyviai, todėl sunkiau suprasti.

Pyproject.toml: Moderni Alternatyva

Kas yra Pyproject.toml?

pyproject.toml yra konfigūracijos failas, kuris naudoja TOML (Tom's Obvious, Minimal Language) formatą, norėdamas apibrėžti jūsų paketo kūrimo sistemą ir metaduomenis. Tai deklaratyvus metodas, reiškiantis, kad nurodote, ką norite pasiekti, o ne kaip tai pasiekti.

Pagrindinės Pyproject.toml Sekcijos

• [build-system]: Apibrėžia naudojamą kūrimo sistemą (pvz., setuptools, poetry, flit).
• [project]: Yra projekto metaduomenys, tokie kaip jo pavadinimas, versija, aprašymas, autoriai ir priklausomybės.
• [tool.poetry] arba [tool.flit]: Sekcijos specifinei įrankių konfigūracijai (pvz., Poetry, Flit).

Pyproject.toml Pavyzdys (su Setuptools)

            [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 Pavyzdys (su Poetry)

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

• Deklaratyvi Konfigūracija: pyproject.toml suteikia deklaratyvų būdą apibrėžti jūsų paketo metaduomenis, todėl juos lengviau suprasti ir prižiūrėti.
• Standartizuota Kūrimo Sistema: Ji nurodo naudojamą kūrimo sistemą, užtikrinant nuoseklius kūrimus skirtingose aplinkose.
• Patobulintas Priklausomybių Valdymas: Tokie įrankiai kaip Poetry ir Pipenv sklandžiai integruojasi su pyproject.toml, suteikdami tvirtas priklausomybių valdymo funkcijas.
• Sumažintos Saugumo Rizikos: Kadangi tai yra statinis konfigūracijos failas, jis pašalina saugumo rizikas, susijusias su kodu, vykdomu kūrimo metu.
• Integracija su Moderniais Įrankiais: pyproject.toml yra standartas moderniems Python pakavimo įrankiams, tokiems kaip Poetry, Pipenv ir Flit.

Pyproject.toml Trūkumai

• Mokymosi Kreivė: Programuotojai gali turėti išmokti naują sintaksę (TOML) ir naują būdą mąstyti apie paketų valdymą.
• Ribotas Lankstumas: Gali netikti labai pritaikytiems kūrimo procesams, reikalaujantiems sudėtingos logikos.
• Įrankių Priklausomybė: Jums reikės pasirinkti ir išmokti naudoti konkrečią kūrimo sistemą (pvz., Setuptools, Poetry, Flit).

Setup.py ir Pyproject.toml Palyginimas

Šioje lentelėje apibendrinami pagrindiniai skirtumai tarp setup.py ir pyproject.toml:

Migracijos Strategijos: Nuo Setup.py prie Pyproject.toml

Migracija iš setup.py į pyproject.toml gali atrodyti sudėtinga, tačiau tai vertinga investicija ilgalaikiam palaikomumui ir nuoseklumui. Štai kelios strategijos, kurias galite naudoti:

1. Pradėkite su Minimaliu Pyproject.toml

Sukurkite pagrindinį pyproject.toml failą, kuriame nurodykite kūrimo sistemą, o tada palaipsniui migruokite metaduomenis iš setup.py į pyproject.toml.

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

            

              
                Copy
              
            
          

2. Naudokite Setuptools su Pyproject.toml

Tęskite Setuptools naudojimą kaip savo kūrimo sistemą, tačiau projekto metaduomenis apibrėžkite pyproject.toml faile. Tai leidžia pasinaudoti pyproject.toml privalumais, tuo pačiu metu naudojant pažįstamą įrankį.

3. Migruokite į Modernų Įrankį, pvz., Poetry

Apsvarstykite migraciją į modernų įrankį, pvz., Poetry ar Pipenv. Šie įrankiai suteikia išsamių priklausomybių valdymo funkcijų ir sklandžiai integruojasi su pyproject.toml.

Pavyzdys: Migracija į Poetry

1. Įdiekite Poetry: pip install poetry
2. Inicijuokite Poetry jūsų projekte: poetry init (Tai padės jums sukurti pyproject.toml failą)
3. Pridėkite savo priklausomybes: poetry add requests (ar bet kokias kitas priklausomybes)
4. Sukurkite savo paketą: poetry build

4. Naudokite Įrankius Automatizuotai Migracijai

Kai kurie įrankiai gali padėti automatizuoti migracijos procesą. Pavyzdžiui, galite naudoti įrankius, kad konvertuotumėte savo setup.py failą į pyproject.toml failą.

Geriausios Python Paketų Valdymo Praktikos

1. Naudokite Virtualią Aplinką

Visada naudokite virtualią aplinką, kad izoliuotumėte savo projekto priklausomybes nuo sistemos lygio Python diegimo. Tai padeda išvengti konfliktų ir užtikrina, kad jūsų projektas turi tinkamas priklausomybes.

Pavyzdys naudojant venv:

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

            

              
                Copy
              
            
          

Pavyzdys naudojant conda:

            conda create -n myenv python=3.9
conda activate myenv

            

              
                Copy
              
            
          

2. Tiksliai Nurodykite Priklausomybes

Naudokite versijų apribojimus, kad nurodytumėte suderinamas jūsų priklausomybių versijas. Tai padeda išvengti netikėto elgesio dėl nesuderinamų bibliotekų atnaujinimų. Naudokite įrankius, tokius kaip pip-tools, savo priklausomybėms valdyti.

Priklausomybės apibrėžimo pavyzdys:

            requests >= 2.20.0, < 3.0.0

            

              
                Copy
              
            
          

3. Naudokite Nuoseklią Kūrimo Sistemą

Pasirinkite kūrimo sistemą (pvz., Setuptools, Poetry, Flit) ir jos laikykitės. Tai užtikrina nuoseklius kūrimus skirtingose aplinkose ir supaprastina paketavimo procesą.

4. Dokumentuokite Savo Paketą

Rašykite aiškią ir glaustą dokumentaciją savo paketui. Tai padeda vartotojams suprasti, kaip naudoti jūsų paketą, ir palengvina kitų bendradarbiavimą jūsų projekte. Naudokite įrankius, tokius kaip Sphinx, norėdami generuoti dokumentaciją iš savo kodo.

5. Naudokite Nuolatinę Integraciją (CI)

Nustatykite CI sistemą (pvz., GitHub Actions, Travis CI, GitLab CI), kad automatiškai sukurtumėte, ištestuotumėte ir diegtumėte savo paketą, kai tik bus pakeistas jūsų kodas. Tai padeda užtikrinti, kad jūsų paketas visada veiktų.

GitHub Actions konfigūracijos pavyzdys:

            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. Publikuokite Savo Paketą į PyPI

Pasidalykite savo paketu su pasauliu, publikuodami jį Python Package Index (PyPI). Tai leidžia kitiems lengvai įdiegti ir naudoti jūsų paketą.

Veiksmai, norint publikuoti į PyPI:

1. Užregistruokite paskyrą PyPI ir TestPyPI.
2. Įdiekite twine: pip install twine.
3. Sukurkite savo paketą: poetry build arba python setup.py sdist bdist_wheel.
4. Įkelkite savo paketą į TestPyPI: twine upload --repository testpypi dist/*.
5. Įkelkite savo paketą į PyPI: twine upload dist/*.

Realių Pavyzdžių Analizė

Pažvelkime, kaip kai kurie populiarūs Python projektai naudoja pyproject.toml:

• Poetry: Naudoja pyproject.toml savo paties paketų valdymui.
• Black: Kompromisų nedarantis kodo formatuotojas taip pat naudoja pyproject.toml.
• FastAPI: Modernus, greitas (aukšto našumo) API kūrimo Python pagrindu web framework taip pat jį naudoja.

Išvada

pyproject.toml atstovauja modernų Python paketų valdymo standartą, siūlantį deklaratyvų ir saugų būdą apibrėžti jūsų paketo metaduomenis ir valdyti priklausomybes. Nors setup.py mums gerai tarnavo, migracija į pyproject.toml yra vertinga investicija ilgalaikiam palaikomumui, nuoseklumui ir integracijai su moderniais įrankiais. Pritaikydami geriausias praktikas ir naudodami tinkamus įrankius, galite supaprastinti savo Python paketų kūrimo eigą ir sukurti aukštos kokybės, daugkartinio naudojimo paketus.

Papildomi Resursai

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