Käytännön opas Setup.py:n käyttöön

Kun käytät pythonia ammattimaisesti, kannattaa projektit
asetella johdonmukaisesti. Tämä auttaa yhteistyökumppaneitasi ymmärtämään nopeasti
projektin
rakenteen ja helpottaa heitä asettamaan projektin
omalle koneelleen. Avain projektin määrittämiseen on setup.py-tiedosto.
Tässä blogissa menen tämän tiedoston yksityiskohtiin.

Miten aloitamme

Tässä oletan, että sinulla on jo valmiiksi paketti, jonka haluat määrittää.
Tämän ei tarvitse olla valmis paketti – ideaalitapauksessa luodaan
setup.py jo kauan ennen projektin valmistumista. Se voi olla jopa tyhjä paketti;
varmista vain, että pakettikansio on olemassa
ja sisältää tiedoston nimeltä init.py (joka voi olla tyhjä).

Jos noudatat kollegani Henkin rakennetta
projektillesi, lähtötilanteesi pitäisi näyttää jotakuinkin tältä:

example_project/├── exampleproject/ Python package with source code.│ ├── __init__.py Make the folder a package.│ └── example.py Example module.└── README.md README with info of the project.

Rakenteessasi voi olla muitakin tiedostoja tai kansioita, esimerkiksi
kansioita nimeltä notebooks/, tests/ tai data/, mutta niitä ei tarvita.

Juttu setup.py

Kun olet luonut tällaisen paketin, niin olet todennäköisesti
käyttänyt osaa koodista muissa paikoissa. Saatat esimerkiksi haluta
tehdä tämän muistikirjaan:

from exampleproject.example import example_function

Tämä toimisi, jos nykyinen työhakemistosi on example_project/, mutta
kaikissa muissa tapauksissa python antaa sinulle tulosteen kuten:

ModuleNotFoundError: No module named 'exampleproject'

Voisit kertoa pythonille, mistä etsiä pakettia asettamalla PYTHONPATH
ympäristömuuttujan PYTHONPATH
tai lisäämällä polun sys.path,
mutta se ei ole läheskään ihanteellista: se vaatisi erilaisia toimia eri
alustoilla, ja asetettava polku riippuu koodisi sijainnista.
Paljon parempi tapa on asentaa pakettisi käyttämällä setup.py ja pip,
koska pip on vakiotapa asentaa kaikki muut paketit, ja sen on pakko
toimia samalla tavalla kaikilla alustoilla.

Minimaalinen esimerkki

Miltä setup.py-tiedosto siis näyttää? Tässä on minimaalinen esimerkki0:

from setuptools import setup, find_packagessetup( name='example', version='0.1.0', packages=find_packages(include=))

Tässä määritetään kolme asiaa:

• Paketin nimi, joka on nimi, jota pip käyttää paketistasi.
  Tämän ei tarvitse olla sama kuin kansion nimi, jossa paketti asuu
  , vaikka voi olla hämmentävää, jos se ei ole. Esimerkki tilanteesta, jossa paketin
  nimi ja hakemisto eivät täsmää, on Scikit-Learn: asennat sen
  käyttämällä pip install scikit-learn, kun taas käytät sitä tuomalla sen sklearn:sta.
• Pakettisi versio. Tämä on versio, jonka pip ilmoittaa, ja sitä käytetään
  esimerkiksi silloin, kun julkaiset pakettisi PyPI:ssä1.
• Mitä paketteja sisällytetään; meidän tapauksessamme tämä on vain exampleproject/.
  Tässä annamme setuptools selvittää tämän
  automaattisesti2. Vaikka voisit periaatteessa käyttää find_packages()
  ilman argumentteja, tämä voi mahdollisesti johtaa siihen, että ei-toivottuja paketteja sisällytetään
  . Näin voi käydä esimerkiksi,
  jos olet sisällyttänyt __init__.py:n tests/
  hakemistoon. Vaihtoehtoisesti voit myös käyttää exclude-argumenttia, jolla voit nimenomaisesti
  estää testien sisällyttämisen pakettiin, mutta tämä on hieman
  epävarmempi.

Pakettisi asentamiseksi sinun tarvitsee nyt vain suorittaa seuraava
hakemiston example_project/ sisältä3:

pip install -e .

Tässä . viittaa nykyiseen työhakemistoon, jonka oletan olevan se hakemisto
, josta setup.py löytyy. Lippu -e määrittää, että haluamme asentaa
muokattavassa tilassa, mikä tarkoittaa
että kun muokkaamme pakettimme tiedostoja, meidän ei tarvitse asentaa
pakettia uudelleen ennen kuin muutokset tulevat voimaan. Sinun on kuitenkin joko käynnistettävä
python uudelleen tai ladattava paketti uudelleen!

Kun muokkaat tietoja setup.py itse setup.py-paketissa, joudut useimmissa tapauksissa asentamaan
paketin uudelleen, ja myös jos lisäät uusia (ali)paketteja.
Kun olet epävarma, ei koskaan voi olla pahitteeksi asentaa uudelleen. Aja vain pip install -e . uudelleen.

Vaatimukset

Useimmilla projekteilla on joitakin riippuvuuksia. Olet todennäköisesti käyttänyt
vaatimuksia.txt
-tiedostoa ennenkin, tai environment.yml
-tiedostoa, jos käytät conda. Nyt kun luot setup.py-tiedoston, voit määrittää
riippuvuudet install_requires-argumentissa.
Tyypillisessä datatieteen projektissa voi esimerkiksi olla:

setup( name='example', version='0.1.0', packages=find_packages(include=), install_requires=)

Voit määrittää vaatimukset ilman versiota (PyYAML), kiinnittää version (pandas==0.23.3), määritellä
minimi
versiossa ('numpy>=1.14.5) tai määritellä versioiden vaihteluväli (matplotlib>=2.2.0,<3.0.0). Nämä
vaatimukset asennetaan automaattisesti pip, kun asennat pakettisi.

Extras-require

Joskus sinulla voi olla riippuvuuksia, joita tarvitaan vain tietyissä tilanteissa. Tietotutkijana
teen usein paketteja, joita käytän mallin kouluttamiseen. Kun työskentelen tällaisen mallin parissa vuorovaikutteisesti
saatan tarvita matplotlib ja jupyter asennettuna, jotta voin työskennellä vuorovaikutteisesti
datan kanssa ja luoda visualisointeja
mallin suorituskyvystä. Toisaalta, jos malli toimii tuotannossa, en
halua asentaa matplotlib enkä jupyter siihen koneeseen (tai konttiin), jossa harjoittelen
tai teen päättelyä. Onneksi setuptools mahdollistaa valinnaisten riippuvuuksien määrittämisen extras_require:

setup( name='example', version='0.1.0', packages=find_packages(include=), install_requires=, extras_require={ 'interactive': , })

Nyt jos asennamme paketin normaalisti (pip install example PyPI:stä tai pip install -e . paikallisesti)
asennetaan vain riippuvuudet PyYAML, pandas ja numpy. Kun kuitenkin määrittelemme
haluavamme valinnaiset interactive-riippuvuudet (pip install example
tai pip install -e .),
asennetaan myös matplotlib ja jupyter.

Skriptit ja sisäänmenopisteet

PyPI:stä asennettavien useimpien python-pakettien pääasiallinen käyttötarkoitus on tarjota toiminnallisuutta
, jota voidaan käyttää muussa python-koodissa. Toisin sanoen, voit import käyttää näitä paketteja.
Datatutkijana teen usein paketteja, joita ei ole tarkoitus käyttää muussa python-koodissa, mutta
on tarkoitus tehdä jotain, esimerkiksi kouluttaa malli. Näin ollen minulla on usein python-skripti, jonka
haluan suorittaa komentoriviltä.

Paras tapa4 paljastaa pakettisi toiminnallisuus komentoriville on määritellä
a entry_point seuraavasti:

setup( # ..., entry_points={ 'console_scripts': })

Nyt voit käyttää komentoriviltä komentoa my-command, joka puolestaan suorittaa exampleproject/example.py:n sisällä olevan main
funktion main
. Älä unohda asentaa uudelleen – muuten komento
ei rekisteröidy.

Testit

Kun kirjoitat mitä tahansa koodia, kehotan sinua painokkaasti kirjoittamaan tälle koodille myös testit. Testaamiseen
pythonilla suosittelen käyttämään pytest. Et tietenkään halua lisätä pytest riippuvuuksiisi
kohdassa install_requires: pakettisi käyttäjät eivät tarvitse sitä. Jotta se asennetaan
automaattisesti testejä suorittaessasi, voit lisätä setup.py:

setup( # ..., setup_requires=, tests_require=,)

Lisäksi sinun on luotava tiedosto nimeltä setup.cfg, jonka sisältö on seuraava:

test=pytest

Nyt voit yksinkertaisesti suorittaa python setup.py test ja setuptools varmistaa, että tarvittavat riippuvuudet
on asennettu ja suorittaa pytest puolestasi! Katso täältä, jos
haluat antaa argumentteja tai asettaa konfiguraatioasetuksia pytest:lle.

Jos sinulla on lisävaatimuksia testausta varten (esim. pytest-flask), voit lisätä ne kohtaan tests_require.

Flake8

Henkilökohtaisesti olen sitä mieltä, että Flake8:n ajaminen on hyvä ajatus, jotta voit
tehdä tarkistuksen ohjelmakoodisi muotoilusta. Aivan kuten pytest:n kohdalla, et halua lisätä flake8:tä
install_requires-riippuvuuksiin: sitä ei tarvitse asentaa, jotta voit käyttää
pakkaustasi. Sen sijaan voit lisätä sen setup_requires:

setup( # ..., setup_requires=)

Nyt voit yksinkertaisesti suorittaa python setup.py flake8. Voit tietysti myös kiinnittää flake8:n (tai minkä tahansa muun paketin) version
kohtaan setup_requires.

Jos haluat muuttaa joitain Flake8:n konfiguraatioparametreja, voit lisätä -osion
kohtaan setup.cfg. Esimerkiksi:

max-line-length=120

Paketin tiedot

Joskus saatat haluta sisällyttää pakettiisi joitakin muita kuin python-tiedostoja. Nämä
voivat olla esimerkiksi skeematiedostoja tai pieni hakutaulukko. Huomaa, että tällaiset tiedostot
paketoidaan yhdessä koodisi kanssa, joten on yleisesti ottaen huono idea sisällyttää
mitä tahansa suuria tiedostoja.

Esitettäkö, että meillä on schema.json projektissamme schema.json, jonka sijoitamme exampleproject/data/schema.json.
Jos haluamme sisällyttää sen pakettiimme, meidän on käytettävä package_data-argumenttia setup:

setup( # ..., package_data={'exampleproject': })

Tämä varmistaa, että tiedosto sisällytetään pakettiin. Voimme myös valita sisällyttää
kaikki tiedostot jonkin mallin perusteella, esimerkiksi:

setup( # ..., package_data={'': })

Tämä lisää kaikki *.json-tiedostot kaikkiin kohtaamiinsa paketteihin.

Älä nyt yritä itse selvittää asennettujen tiedostojen sijaintia, sillä
pkg_resources:ssä on joitakin erittäin käteviä käteviä toimintoja:

• pkg_resources.resource_stream antaa sinulle tiedoston virran, aivan kuten
  objekti, jonka saat, kun kutsut open(),
• pkg_resources.resource_string antaa sinulle tiedoston sisällön merkkijonona,
• pkg_resources.resource_filename antaa sinulle tiedoston nimen (ja purkaa
  se väliaikaiseksi, jos se sisältyy pakattuun pakettiin), jos kaksi edellä mainittua vaihtoehtoa
  eivät vastaa tarpeitasi.

Voisimme esimerkiksi lukea skeemamme sisään käyttämällä:

from json import loadfrom pkg_resources import resource_streamschema = load(resource_stream('exampleproject', 'data/schema.json'))

Metadata

Jos aiot julkaista pakettisi, haluat luultavasti antaa
potentiaalisille käyttäjillesi lisätietoa paketistasi, mukaan lukien kuvauksen,
tekijän tai ylläpitäjän nimen ja url-osoitteen paketin kotisivulle.
Luettelon kaikista sallituista metatiedoista löydät setuptools
dokumenteista.

Lisäksi, jos aiot julkaista PyPI:ssä, voit halutessasi
automaattisesti ladata README.md
sisällön long_description,
ja tarjota luokittelijoita, jotka kertovat pip vielä
enemmän paketistasi.

Pakkaus

Tämän blogin pitäisi olla hyvä lähtökohta useimpien python-projekteidesi asentamiseen.
Jos haluat lukea lisää python-paketoinnista, vilkaise
dokumentteja. Tässä on esimerkki setup.py
jossa yhdistyvät kaikki tässä blogissa esitetyt osat:

from setuptools import setup, find_packagessetup( name='example', version='0.1.0', description='Setting up a python package', author='Rogier van der Geer', author_email='[email protected]', url='https://blog.godatadriven.com/setup-py', packages=find_packages(include=), install_requires=, extras_require={'plotting': }, setup_requires=, tests_require=, entry_points={ 'console_scripts': }, package_data={'exampleproject': })

ja oheinen setup.cfg:

test=pytestmax-line-length=120

Paranna Python-taitojasi, opi asiantuntijoilta!

GoDataDrivenillä tarjoamme lukuisia Python-kursseja aloittelijasta asiantuntijaan, ja niitä opettavat alan parhaimmat asiantuntijat. Liity meihin ja nosta Python-pelisi tasoa:

• Python Essentials – Sopii loistavasti, jos vasta aloitat Pythonilla.
• Certified Data Science with Python Foundation – Haluatko ottaa askeleen ylöspäin data-analyysistä ja visualisoinnista todelliseen datatieteeseen? Tämä on oikea kurssi.
• Advanced Data Science with Python – Opi tuottamaan mallejasi ammattilaisen tavoin ja käyttämään Pythonia koneoppimiseen.

Footnotes

0: Tässä blogissa olen käyttänyt setuptools
esimerkkiprojektin perustamiseen. Vaihtoehtoisesti
voisit myös käyttää distutilsia,
joka on pythonin vakiotyökalu pakkaamiseen, mutta siitä puuttuu ominaisuuksia
kuten find_packages()-funktio ja entry_points.
Koska setuptoolsin käyttö on nykyään hyvin yleistä ja monet sen ominaisuuksista
voivat olla erityisen hyödyllisiä, suosittelen käyttämään setuptoolsia.

1: Jos haluat, että pakettisi versio
on saatavilla myös pythonin sisällä,
katso täältä.

2: Voit myös listata pakettisi manuaalisesti, mutta tämä on erityisen virhealtista.

3: Vaihtoehtoisesti voit käyttää python setup.py install, mutta pip:n käyttämisellä on
paljon etuja, muun muassa riippuvuuksien automaattinen asennus ja
mahdollisuus poistaa tai päivittää pakettisi.

4: Voisit myös käyttää scripts-argumenttia (katso
esimerkki täältä)
mutta koska tämä edellyttää python-shell-skriptin luomista, se ei ehkä toimi
yhtä hyvin (tai ei ollenkaan) Windowsissa.

Mitä?