Python-kehittäjälle on tavallista etsiä pakettikirjastosta (Python Package Index, PyPi) valmiita kirjastoja. PyPistä löytyy, oli sitten kyse yksinkertaisesta merkkijonokirjastosta tai kokonaisesta koneoppimisjärjestelmästä.
Kirjastojen lataaminen on helppoa Pythonin pip-työkalulla, eikä peruskäyttö vaadi muuta tietoa kuin paketin nimen. Tämä voi kuitenkin ajan mittaan koitua ongelmaksi, jos projekti kasvaa ja kypsyy pisteeseen, jossa pitäisi huolehtia versionumeroista ja riippuvuuksista. Asiat mutkistuvat jopa mahdottomiksi, jos tietokoneella tehdään useampaa projektia, jotka vaativat eri versioita paketeista tai jopa itse Pythonista. Puhumattakaan lopullisen tuotteen paketoinnista asiakkaalle toimitettavaksi.
Poetry näyttää ensisilmäyksellä työkalulta, jolla helposti paketoidaan ja julkaistaan Python-kirjastoja PyPiin. Pinnan alta löytyy kuitenkin erinomainen kokonaisuus, joka soveltuu käytännössä minkä tahansa projektin kehitystyöhön. Erityisesti, jos projektissa on tarvetta tiukasti hallinnoida kirjastoja ja niiden versioita toimialan asettamien säädösten takia, on Poetryllä helppoa asettaa versiot ja lähteet täsmällisesti.
Poetry tarjoaa seuraavat ominaisuudet samassa paketissa:
- riippuvuuksien määrittely ja hallinta
- kirjastojen yksityisten säilytyspaikkojen määrittely
- eristetty ympäristö sekä Pythonille että kirjastoille
- käyttäjäystävälliset komentorivityökalut
- kirjastokehitystä varten käännös- ja julkaisutyökalut
Tässä artikkelissa tutustutaan kohtiin 1, 3 ja 4 esimerkkiprojektin avulla. Kohdista 2 ja 5 lyhyesti seuraavassa.
Kohta 2: Tietoturvasyistä, tai alan säädösten vuoksi, voi olla tarpeellista tarjota oma yksityinen lähde kirjastoille ja jopa estää julkisten säilöjen käyttö. Poetryn voi konfiguroida käyttämään yksityisiä säilöjä, esimerkiksi Artifactorya ja jopa estämään julkisen PyPi-sivuston käyttö kokonaan. Näin saadaan varmistettua, ettei Poetrya käyttävän kehitysprojektin aikana vahingossa pääse mukaan livahtamaan kirjastoja, joita ei ole erikseen hyväksytty käyttöä varten.
Kohta 5: Poetryn tarjoamat kaksi komentoa, build ja publish, paketoivat Poetry-projektin ja julkaisevat sen joko PyPiin tai käyttäjän konfiguroimaan säilöön. Komennot helpottavat kirjastojen kehitystyötä tiivistämällä sisällöstä riippumattomat rutiinioperaatiot yhteen. Kuten kohdassa 2, publish-komennolle on mahdollista määritellä kohteeksi yksityinen säilö, joten komento toimii tarvittaessa myös organisaatioiden sisäisessä työssä.
Asennus ja käyttöönotto
Asennusohje lyhyesti:
- Asenna Python 3.9
- Asenna Poetry käyttämällä virallista asennustyökalua, jonka saa täältä
- Lisää Poetry PATH-ympäristömuuttujaan asennustyökalun ohjeiden mukaisesti
Poetry-projektin tärkein tiedosto on pyproject.toml. Se määrittelee projektin perustietojen lisäksi mm. sallitut Python-tulkin versiot ja projektin sekä Poetryn riippuvuudet. Lisäksi tiedoston avulla on mahdollista laajentaa Poetrya määrittelemällä omia komentoja.
Ennen kuin siirrytään rakentamaan omaa esimerkki-pyproject.toml-tiedostoa, on syytä mainita yhdestä aika keskeisestä rajoituksesta. Poetry on suunniteltu olemaan välittämättä käyttöjärjestelmään asennetusta Python-tulkin versiosta. Filosofiana on, että riippumatta siitä, mikä Python koneelle on asennettu, Poetry hanskaa versiokohtaiset erot ja työkalu yksinkertaisesti toimii. Valitettavasti tämä saattaa virheellisesti antaa ymmärtää, että Poetry hallitsisi muiden riippuvuuksien tapaan itse Pythoninkin asennuksen. Näin ei kuitenkaan ole, vaan Poetry jättää Python-versioiden asennuksen käyttäjän harteille. Jos tietokoneelle on asennettu useampi Python-tulkki, hallitsee Poetry automaattisesti halutun version käytön projektin sisällä.
Poetryn käyttöönotto voidaan tehdä kahdella tavalla: joko luomalla uusi projektipohja tai sitten lisäämällä konfiguraatiotiedosto olemassa olevalle projektille.
Komentamalla poetry new ExampleProject, luo Poetry uuden kansion ExampleProject ja sen alle kansiorakenteen sekä konfigurointitiedoston. Tämä on nopein tapa luoda pohja, joka soveltuu julkaistavalle Python-kirjastolle. Poetry valmistelee kaiken automaattisesti versionumeroa ja yksikkötestipohjia myöten sen kummemmin kyselemättä.
Vaihtoehtoisesti voidaan siirtyä kansioon, joka jo sisältää Python-projektin tiedostot ja käyttää komentoa poetry init. Tämä kyselee muutaman kysymyksen ja luo pyproject.toml-tiedoston. Mitään muita tiedostoja tai kansioita ei luoda.
Esimerkkiprojekti
Seuraavassa käydään paloittain läpi pyproject.toml-tiedoston sisältö. Tiedoston voi kirjoittaa joko käsin tai komentamalla poetry init.
Projektitiedoston ensimmäinen osa, tool.poetry, määrittelee vähintään seuraavat projektin yleiset tiedot: nimen, version, lyhyen kuvauksen sekä tekijöiden nimet.
[tool.poetry] name = "PoetryDemo" version = "0.1.0" description = "" authors = ["Your Name <[email protected]>"]
Seuraavaksi tool.poetry.dependencies-osiossa määritellään projektin Python-tulkin versio. Tähän osioon tullaan myöhemmin listaamaan kaikki riippuvuudet, jotka normaalisti asennettaisiin pip-komennolla.
[tool.poetry.dependencies] python = "^3.9"
Lopuksi määritellään Poetryn omat vaatimukset:
[build-system] requires = ["poetry-core>=1.0.0"] build-backend = "poetry.core.masonry.api"
Jos haluaa testata itse tehtyä projektitiedostoa, poetry check-komento tarkistaa pyproject.toml-tiedoston sisällön.
Lisätään projektille Robot Framework -kirjasto. Lisäyksen voi tehdä joko Poetryn komennolla add tai lisäämällä rivin pyproject.toml-tiedostoon käsin:
[tool.poetry.dependencies] python = "^3.9" robotframework = "^4.1.3"
Jos projektitiedostoa muokkaa käsin, pitää muutokset ottaa käyttöön poetry install-komennolla.
Käyttämällä Poetryn omaa komentoa: poetry add robotframework@^4.1.3, ajetaan install-komento automattisesti.
Poetryn install on tärkein komento ajaa ensimmäisenä, kun projekti otetaan käyttöön esimerkiksi CI/CD-ympäristössä. Sen voi turvallisesti ajaa vaikka joka kerta automaattisesti. Komento etsii poetry.lock-tiedostoa ja lataa sen pohjalta riippuvuudet käyttäen aina samoja versioita. Jos poetry.lock-tiedostoa ei vielä ole olemassa tai se on poistettu, siirtyy install-komento lukemaan pyproject.toml-tiedostoa ja luo sen pohjalta poetry.lock-tiedoston asentaessaan kirjastoja.
Nyt meillä on valmis ympäristö Robot-automaattitestien ajoon. Jos haluaa kokeilla, miltä maailma tässä ympäristössä näyttää, voi projektiympäristön sisälle hypätä komennolla poetry shell. Komento käynnistää shellin, jossa toimivat projektin pohjalta rakennetussa virtuaaliympäristössä Python, kaikki oheistyökalut sekä Poetryyn mahdollisesti määritellyt omat komennot.
Shellin sisällä voi kokeilla esimerkiksi seuraavia komentoja tutustuakseen ympäristön rakenteeseen:
robot --versionpip listwhich python(toimii Linuxissa ja MacOS:ssa)where python(toimii Windowsissa)
Shellistä pääsee pois komennolla exit.
Poetryn shell on käytännössä sama asia kuin Pythonista tuttu “venv”. Merkittävä ero on se, että komentoja voi ajaa helposti virtuaaliympäristön ulkopuolelta. Tämä soveltuu hyvin esimerkiksi CI/CD-ympäristöihin.
CD/CD-putkessa riittää, että määrittelee vaikkapa seuraavat askelet:
poetry installpoetry run robot -d robot-logs robot-tests
Poetry huolehtii kaikesta ja lopputuloksena robot-logs-kansiossa ovat testitulokset.
Skriptaus
Yksittäisten komentojen ajaminen peräkkäin suuremmissa projekteissa ei ole käytännöllistä, joten Poetry tarjoaa mahdollisuuden laajentaa itseään helposti Pythonilla.
Luodaan projektikansioon uusi tiedosto: scripts.py:
import os
import shutil
def run_tests():
shutil.rmtree("robot-logs", ignore_errors=True)
os.system("robot -d robot-logs robot-tests")
Lisätään pyproject.toml-tiedostoon uusi osio, tool.poetry.scripts ja sen alle määritellään komento robottests:
[tool.poetry.scripts] robottests = "scripts:run_tests"
Kun ajetaan poetry install, luo Poetry virtuaaliympäristön sisälle komennon, joka ajaa scripts.py-tiedostosta run_tests()-funktion. Komentoa voi ajaa joko suoraan shell-ympäristössä komentamalla robottests tai komentamalla virtuaaliympäristön ulkopuolelta poetry run robottests. run_tests()-funktioon voidaan paketoida kaikki testiympäristön alustukseen vaadittavat komennot. Ohjeistamalla käyttäjiä ajamaan testit aina robottests-komennolla, eliminoidaan testiympäristön eri käyttötavoista syntyvät mahdolliset ongelmat.
Huomio! Jos loit projektin käyttäen poetry init-komentoa, pitää [tool.poetry]-osioon lisätä seuraava rivi:
packages = [{include = "scripts"}]
Tämä lisää scripts-kansion Poetryn moduuliluetteloon ja varmistaa, että robottests = "scripts:run_tests"-rivi löytää oikean Python-tiedoston. Luodessa projektia poetry new-komennolla, koko projekti määritellään kirjastoksi ja scripts-kansio on silloin automaattisesti osana moduulien hakupolkua.
Lopuksi vielä asiaa itse virtuaaliympäristöistä. Poetry piilottaa huolellisesti konepellin alla olevan mekaniikan, eikä ympäristön tiedostohierarkia ole projektikansion alla. Tämä tekee projektin tallentamisen versiohallintaan helpoksi. Jos kuitenkin haluaa tietää, missä Poetryn ympäristöt oikeasti ovat, voi sijainnin pyytää nähtäville komennolla poetry env list --full-path.
Poetryn soveltuvuutta kehitystyössä tai CI/CD-putkessa voi pohtia edellistä esimerkkiä laajentamalla omien komentojen avulla. Poetryn laajentaminen Pythonilla avaa ovet monimutkaistenkin ympäristöjen rakentamiseen, joita voidaan ohjata vain muutamalla helposti muistettavalla komennolla. Ja koko paketti pysyy kasassa ympäristöstä toiseen, kiitos Poetryn.
Lisää luettavaa:
Kirjoittaja on Ouron Senior Developer Matti Kärki