Pylint ja koodin staattinen analyysi

Tämä ohje on kopio kurssin Ohjelmistotekniikka Pylint-ohjeesta ohjeesta muutamin lisäyksin

Koodin testauksen lisäksi koodin laadun ylläpitäminen on tärkeää. Laadun ylläpitäminen on mahdollista erilaisilla manuaalisilla menetelmillä, kuten laatuvaatimusten dokumentoinnilla ja koodikatselmoinneilla. Monet manuaaliset laadunhallinnan menetelmät osoittautuvat kuitenkin laajoissa ohjelmistoprojekteissa usein turhan aikaavieviksi ja virhealttiiksi. Staattinen analyysi on menetelmä, jonka avulla koodia voidaan analysoida automatisoidusti ilman, että sitä tarvitsee suorittaa. Staattista analyysia hyödynnetään ohjelmistokehityksessä laajasti mm. ohjelmointivirheiden huomaamiseen ja laatutarkistuksien tekemiseen.

Eräs Python-koodin staattisessa analyysissä laajasti käytetty työkalu on Pylint. Pylintin avulla voimme määrittä koodin laadulle erilaisia vaatimuksia ja automatisoidusti tarkastaa, noudattaako tarkastettava koodi näitä sääntöjä.

Pylint is a tool that checks for errors in Python code, tries to enforce a coding standard and looks for code smells. It can also look for certain type errors, it can recommend suggestions about how particular blocks can be refactored and can offer you details about the code’s complexity.

Pylintin käyttöönotto projektissa

Pylint on helppo ottaa käyttöön Poetry-projektissa. Aloitetaan asentamalla Pylint projektimme kehityksen aikaiseksi riippuvuudeksi:

poetry add pylint --group dev

Pylintille tulee määritellä joukko tarkistettavia sääntöjä. Säännöt määritellään projektin juurihakemiston .pylintrc-tiedostossa. Luo kyseinen tiedosto ja kopioi sinne tämän tiedoston sisältö. Tiedosto sisältää hieman muunnellun version Pylintin suosittelemasta konfiguraatiosta, jota voi katsella komennolla pylint --generate-rcfile.

Pylintin laatutarkitukset voi suorittaa komentoriviltä siirtymällä ensin virtuaaliympäristöön komennolla poetry shell ja sen jälkeen suorittamalla komennon pylint src. Komento tulee suorittaa projektin juurihakemistossa, eli samassa hakemistossa missä pyproject.toml-tiedosto sijaitsee. Kyseinen komento suorittaa laatutarkitukset src hakemistossa. Pylint antaa koodille “arvosanan” sen laadun mukaan, joka löytyy tulosteen lopusta:

Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

Laatutarkistuksien kytkeminen pois päältä

Lähtökohtaisesti Pylintin huomauttamat laatuvirheet kannattaa yrittää kaikin keinoin korjata. Tämä johtaa lähes aina laadukkaampaan koodin. Joissain tilanteissa voimme kuitenkin hyväksyä laatuvirheet ja kytkeä tarkastukset pois päältä. Tähän löytyy erilaisia keinoja.

Otetaan esimerkiksi seuraava src/index.py-tiedosto:

x = 3
print(x)

Komennon pylint src suorittaminen paljastaa, että Pylint löytää tiedostosta seuraavan virheen:

src/index.py:1:0: C0103: Constant name "x" doesn't conform to UPPER_CASE naming style (invalid-name)

Eli tiedoston src/index.py-riviltä yksi löytyy väärin nimetty muuttuja. Rikottavan säännön nimi on tässä tilanteessa invalid-name. Järkevintä olisi vain antaa muuttujalle nimeksi X, mutta havainnollistetaan, kuinka säännön tarkistuksen voi ottaa riviltä pois päältä. Lisätään riville seuraava kommentti:

x = 3 # pylint: disable=invalid-name
print(x)

Nyt pylint src-komennon suorittaminen pitäisi kertoa, ettei virheitä enää löydy.

Voimme myös jättää tarkistuksien ulkopuolelle kokonaisia hakemistoja ja tiedostoja. Muokkaamalla tätä riviä .pylintrc tiedossa. Voimme esimerkiksi jättää käyttöliittymästä vastaavan koodin hakemistossa src/ui ja testit hakemistossa src/tests tarkistuksien ulkopuolle:

ignore=CVS,ui,tests

Integrointi editoriin

Monissa editoreissa on lisäosia, jotka huomauttavat laatuvirheistä suoraan koodissa. Tämä tekee niiden huomaamisesta ja korjaamisesta nopeampaa. Jos käytössäsi on Visual Studio Code, riittää että asennat Pylint-lisäosan:

Tämän jälkeen Visual Studio Coden (joka pitää ehkä käynnistää uudelleen lisäosan asennuksen jälkeen) tulisi huomauttaa laatuvirheistä suoraan koodissa punaisella alleviivauksessa. Viemällä hiiren ongelmallisen koodin päälle pitäisi aueta tarkempaa tietoa virheestä:

Jos integroinnin kanssa ilmenee ongelmia, tutustu Visual Studio Coden ohjeisiin.

Bonus: automaattinen formatointi

Tiettyjen laatukorjausten, kuten sisennysten ja liian pitkien koodirivien korjaaminen tuottaa välillä turhaa manuaalista työtä. Koodin automaattisessa formatoinnissa auttaa autopep8-kirjasto. Kirjasto formatoi koodin automaattisesti PEP 8-tyyliohjeiden mukaisesti. Aloitetaan sen käyttö asentamalle se projektin riippuvuudeksi:

poetry add autopep8 --group dev

Tämän jälkeen voimme virtuaaliympäristössä formatoida src hakemiston koodin komennolla:

autopep8 --in-place --recursive src

Koodin formatointi onnistuu myös monissa editoreissa kätevästi yhdellä näppäinkomennolla. Ohje koodin formatointiin Visual Studio Codessa löytyy täältä.