Python-koodin laatu: Black-, Flake8- ja mypy-integraation hallinta

Ohjelmistokehityksen maailmassa toimivan koodin kirjoittaminen on vain puoli voittoa. Yhtenäisen tyylin ylläpitäminen, parhaiden käytäntöjen noudattaminen ja tyyppiturvallisuuden varmistaminen ovat yhtä tärkeitä vankkojen, ylläpidettävien ja yhteistyöhön perustuvien projektien luomisessa. Python, joka tunnetaan luettavuudestaan, hyötyy suuresti työkaluista, jotka automatisoivat näitä osa-alueita. Tämä kattava opas tutkii kolmen tehokkaan työkalun – Black, Flake8 ja mypy – integraatiota, jotta voit nostaa Python-koodisi laadun seuraavalle tasolle.

Miksi koodin laadulla on väliä

Ennen kuin syvennymme kunkin työkalun yksityiskohtiin, ymmärretään, miksi koodin laatu on ensisijaisen tärkeää:

• Luettavuus: Yhtenäinen koodityyli helpottaa kehittäjien ymmärtää ja muokata koodia.
• Ylläpidettävyys: Hyvin muotoiltu ja tyyppitarkistettu koodi vähentää bugien todennäköisyyttä ja yksinkertaistaa virheenkorjausta.
• Yhteistyö: Jaetut koodityylit varmistavat, että kaikki tiimin jäsenet kirjoittavat koodia yhtenäisellä tavalla, mikä edistää saumatonta yhteistyötä.
• Vähentynyt tekninen velka: Koodin laatuongelmiin puuttuminen varhaisessa vaiheessa estää teknisen velan kertymisen, mikä säästää aikaa ja resursseja pitkällä aikavälillä.
• Parannettu luotettavuus: Staattinen tyyppitarkistus löytää mahdolliset virheet ennen ajonaikaa, mikä parantaa sovellustesi yleistä luotettavuutta.

Nämä hyödyt eivät rajoitu tiettyihin toimialoihin tai alueisiin. Kehititpä sitten verkkosovellusta Berliinissä, datatiedeprojektia Bangaloressa tai mobiilisovellusta Mexico Cityssä, yhtenäinen koodin laatu parantaa epäilemättä kehitystyönkulkuasi.

Esittelyssä Black: tinkimätön koodin muotoilija

Black on Python-koodin muotoilija, joka muotoilee koodisi automaattisesti uudelleen yhtenäisen tyylin mukaiseksi. Se on "itsepäinen" (opinionated), mikä tarkoittaa, että se tekee puolestasi päätökset koodin muotoilusta, minimoiden tyylikeskustelut ja antaen kehittäjien keskittyä toiminnallisuuteen.

Blackin tärkeimmät ominaisuudet

• Automaattinen muotoilu: Black muotoilee koodisi automaattisesti ennalta määritellyn tyylioppaansa (perustuu PEP 8:aan) mukaisesti.
• Tinkimätön: Black jättää vähän tilaa mukauttamiselle, mikä takaa yhtenäisen tyylin koko koodikannassa.
• Integraatio editoreihin: Black integroituu saumattomasti suosittuihin koodieditoreihin, kuten VS Code, PyCharm ja Sublime Text.
• Pre-commit Hook: Blackia voidaan käyttää pre-commit-koukkuna varmistamaan, että kaikki arkistoon (repository) commitoitu koodi on oikein muotoiltu.

Blackin asentaminen

Voit asentaa Blackin pip-komennolla:

            pip install black
            

              
                Copy
              
            
          

Blackin käyttö

Muotoillaksesi Python-tiedoston Blackilla, suorita seuraava komento:

            black my_file.py
            

              
                Copy
              
            
          

Black muotoilee tiedoston paikallaan noudattaen ennalta määritettyjä tyylisääntöjään. Muotoillaksesi koko hakemiston, suorita:

            black my_directory
            

              
                Copy
              
            
          

Esimerkki: Muotoilu Blackilla

Tarkastellaan seuraavaa huonosti muotoiltua Python-koodia:

            def my_function(  long_argument_name, another_long_argument_name):
    if long_argument_name > 10:
        return  another_long_argument_name   +  long_argument_name
    else:
        return 0
            

              
                Copy
              
            
          

Ajettuasi Blackin, koodi muotoillaan automaattisesti uudelleen muotoon:

            def my_function(long_argument_name, another_long_argument_name):
    if long_argument_name > 10:
        return another_long_argument_name + long_argument_name
    else:
        return 0
            

              
                Copy
              
            
          

Huomaa, kuinka Black on automaattisesti säätänyt välilyöntejä, rivinvaihtoja ja sisennystä vastaamaan tyyliopastaan.

Blackin integrointi Pre-commitiin

Pre-commit on työkalu, jonka avulla voit suorittaa tarkistuksia koodillesi ennen sen commitoimista arkistoon. Blackin integrointi pre-commitiin varmistaa, että kaikki commitoitu koodi on oikein muotoiltu.

1. Asenna pre-commit:

            pip install pre-commit
            

              
                Copy
              
            
          

2. Luo .pre-commit-config.yaml-tiedosto arkistosi juureen:

            repos:
-   repo: https://github.com/psf/black
    rev: 23.12.1  # Korvaa uusimmalla versiolla
    hooks:
    -   id: black
            

              
                Copy
              
            
          

3. Asenna pre-commit-koukut:

            pre-commit install
            

              
                Copy
              
            
          

Nyt joka kerta kun commitoit koodia, pre-commit suorittaa Blackin muotoillakseen tiedostosi. Jos Black tekee muutoksia, commit keskeytetään, ja sinun tulee lisätä muutokset ("stage") ja yrittää commitoimista uudelleen.

Esittelyssä Flake8: koodityylin tarkistaja

Flake8 on "kääre" useiden suosittujen Pythonin linttaus-työkalujen ympärillä, mukaan lukien pycodestyle (entinen pep8), pyflakes ja mccabe. Se tarkistaa koodisi tyylivirheiden, syntaksivirheiden ja koodin monimutkaisuusongelmien varalta, auttaen sinua noudattamaan PEP 8 -tyyliopasta ja kirjoittamaan puhtaampaa, ylläpidettävämpää koodia.

Flake8:n tärkeimmät ominaisuudet

• Tyylivirheiden tunnistus: Flake8 tunnistaa PEP 8 -tyylioppaan rikkomukset, kuten virheelliset sisennykset, rivin pituusrajoitusten ylitykset ja käyttämättömät tuonnit.
• Syntaksivirheiden tunnistus: Flake8 havaitsee syntaksivirheet koodissasi, auttaen sinua löytämään mahdolliset bugit varhaisessa vaiheessa.
• Koodin monimutkaisuuden analyysi: Flake8 käyttää mccabea laskemaan koodisi syklomaattisen kompleksisuuden, tunnistaen mahdollisesti monimutkaiset ja vaikeasti ylläpidettävät funktiot.
• Laajennettavuus: Flake8 tukee laajaa valikoimaa lisäosia (plugin), joiden avulla voit mukauttaa sen toimintaa ja lisätä tuen uusille tarkistuksille.

Flake8:n asentaminen

Voit asentaa Flake8:n pip-komennolla:

            pip install flake8
            

              
                Copy
              
            
          

Flake8:n käyttö

Tarkistaaksesi Python-tiedoston Flake8:lla, suorita seuraava komento:

            flake8 my_file.py
            

              
                Copy
              
            
          

Flake8 tulostaa listan kaikista tyylivirheistä, syntaksivirheistä tai koodin monimutkaisuusongelmista, jotka se löytää tiedostosta. Tarkistaaksesi koko hakemiston, suorita:

            flake8 my_directory
            

              
                Copy
              
            
          

Esimerkki: Tyylivirheiden tunnistaminen Flake8:lla

Tarkastellaan seuraavaa Python-koodia:

            def my_function(x,y):
    if x> 10:
        return x+y
    else:
        return 0
            

              
                Copy
              
            
          

Flake8:n ajaminen tälle koodille tuottaa seuraavan tulosteen:

            my_file.py:1:1: E302 expected 2 blank lines, found 0
my_file.py:1:14: E231 missing whitespace after ','
my_file.py:2:4: E128 continuation line under-indented for visual indent
my_file.py:3:12: E226 missing whitespace around operator

            

              
                Copy
              
            
          

Flake8 on tunnistanut useita tyylivirheitä, mukaan lukien puuttuvat tyhjät rivit, puuttuva välilyönti pilkun jälkeen, virheellinen sisennys ja puuttuva välilyönti operaattorin ympärillä. Nämä virheet tulisi korjata koodin luettavuuden ja PEP 8 -yhteensopivuuden parantamiseksi.

Flake8:n konfigurointi

Flake8 voidaan konfiguroida käyttämällä .flake8-tiedostoa arkistosi juuressa. Tässä tiedostossa voit määrittää, mitkä tarkistukset otetaan käyttöön tai poistetaan käytöstä, asettaa rivin enimmäispituuden ja konfiguroida muita asetuksia.

Tässä on esimerkki .flake8-tiedostosta:

            [flake8]
max-line-length = 120
ignore = E203, W503
            

              
                Copy
              
            
          

Tässä esimerkissä rivin enimmäispituus on asetettu 120 merkkiin, ja E203- ja W503-tarkistukset on poistettu käytöstä. E203 viittaa välilyöntiin ennen kaksoispistettä (':') ja sitä pidetään usein tyylillisenä mieltymyksenä, jonka Black joka tapauksessa hoitaa. W503 viittaa rivinvaihtoihin ennen binäärioperaattoreita, minkä Black myös käsittelee.

Flake8:n integrointi Pre-commitiin

Integroidaksesi Flake8:n pre-commitiin, lisää seuraava sisältö .pre-commit-config.yaml-tiedostoosi:

            -   repo: https://github.com/pycqa/flake8
    rev: 6.1.0 # Korvaa uusimmalla versiolla
    hooks:
    -   id: flake8
            

              
                Copy
              
            
          

Nyt joka kerta kun commitoit koodia, pre-commit suorittaa Flake8:n tarkistaakseen tyylivirheet. Jos Flake8 löytää virheitä, commit keskeytetään, ja sinun tulee korjata virheet ja yrittää commitoimista uudelleen.

Esittelyssä mypy: staattinen tyyppitarkistaja

mypy on staattinen tyyppitarkistaja Pythonille, joka auttaa sinua löytämään tyyppivirheet ennen ajonaikaa. Python on dynaamisesti tyypitetty kieli, mikä tarkoittaa, että muuttujan tyyppiä ei tarkisteta ennen kuin vasta ajon aikana. Tämä voi johtaa odottamattomiin virheisiin ja bugeihin. mypy antaa sinun lisätä tyyppivihjeitä koodiisi, mikä mahdollistaa staattisen tyyppitarkistuksen ja parantaa sovellustesi luotettavuutta.

mypyn tärkeimmät ominaisuudet

• Staattinen tyyppitarkistus: mypy tarkistaa muuttujien, funktioargumenttien ja paluuarvojen tyypit käännösaikana, löytäen mahdolliset tyyppivirheet ennen ajonaikaa.
• Tyyppivihjeet: mypy käyttää tyyppivihjeitä (type hints), jotka ovat annotaatioita, jotka määrittävät muuttujan tai funktion odotetun tyypin.
• Asteittainen tyypitys: mypy tukee asteittaista tyypitystä (gradual typing), mikä tarkoittaa, että voit lisätä tyyppivihjeitä koodiisi vähitellen ilman, että sinun tarvitsee tyyppitarkistaa koko koodikantaasi kerralla.
• Integraatio editoreihin: mypy integroituu saumattomasti suosittuihin koodieditoreihin, kuten VS Code ja PyCharm.

mypyn asentaminen

Voit asentaa mypyn pip-komennolla:

            pip install mypy
            

              
                Copy
              
            
          

mypyn käyttö

Tarkistaaksesi Python-tiedoston mypyllä, suorita seuraava komento:

            mypy my_file.py
            

              
                Copy
              
            
          

mypy tulostaa listan kaikista tyyppivirheistä, jotka se löytää tiedostosta. Tarkistaaksesi koko hakemiston, suorita:

            mypy my_directory
            

              
                Copy
              
            
          

Esimerkki: Tyyppivihjeiden lisääminen ja tyyppivirheiden tunnistaminen

Tarkastellaan seuraavaa Python-koodia:

            def add(x, y):
    return x + y

result = add(10, "20")
print(result)
            

              
                Copy
              
            
          

Tämä koodi suoritetaan ilman virheitä, mutta se tuottaa odottamattomia tuloksia, koska se yrittää laskea yhteen kokonaisluvun ja merkkijonon. Tämän tyyppivirheen nappaamiseksi voit lisätä tyyppivihjeet add-funktioon:

            def add(x: int, y: int) -> int:
    return x + y

result = add(10, "20")
print(result)
            

              
                Copy
              
            
          

Nyt, kun ajat mypyn, se tulostaa seuraavan virheen:

            my_file.py:4: error: Argument 2 to "add" has incompatible type "str"; expected "int"
            

              
                Copy
              
            
          

mypy on havainnut, että välität merkkijonon add-funktiolle, joka odottaa kokonaislukua. Tämä antaa sinun napata virheen ennen ajonaikaa ja estää odottamattoman toiminnan.

mypyn konfigurointi

mypy voidaan konfiguroida käyttämällä mypy.ini- tai pyproject.toml-tiedostoa arkistosi juuressa. Tässä tiedostossa voit määrittää, mitkä tarkistukset otetaan käyttöön tai poistetaan käytöstä, asettaa Python-version ja konfiguroida muita asetuksia. pyproject.toml-tiedoston käyttö on nykyaikainen suositeltu tapa.

Tässä on esimerkki pyproject.toml-tiedostosta:

            [tool.mypy]
python_version = "3.11"
strict = true
            

              
                Copy
              
            
          

Tässä esimerkissä Python-versio on asetettu 3.11:een ja strict-tila on käytössä. Strict-tila ottaa käyttöön kaikki mypyn tiukimmat tarkistukset, auttaen sinua löytämään vielä enemmän mahdollisia tyyppivirheitä.

mypyn integrointi Pre-commitiin

Integroidaksesi mypyn pre-commitiin, lisää seuraava sisältö .pre-commit-config.yaml-tiedostoosi:

            -   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.6.1 # Korvaa uusimmalla versiolla
    hooks:
    -   id: mypy
            

              
                Copy
              
            
          

Nyt joka kerta kun commitoit koodia, pre-commit suorittaa mypyn tarkistaakseen tyyppivirheet. Jos mypy löytää virheitä, commit keskeytetään, ja sinun tulee korjata virheet ja yrittää commitoimista uudelleen.

Kaikki yhdessä: täydellinen integraatioesimerkki

Osoittaaksemme Blackin, Flake8:n ja mypyn integroinnin voiman, käydään läpi täydellinen esimerkki. Tarkastellaan seuraavaa Python-koodia:

            def calculate_average(numbers):
    sum=0
    for number in numbers:
        sum+=number
    return sum/len(numbers)
            

              
                Copy
              
            
          

Tässä koodissa on useita ongelmia:

• Sitä ei ole muotoiltu PEP 8:n mukaisesti.
• Siitä puuttuvat tyyppivihjeet.
• Se käyttää mahdollisesti hämmentävää muuttujan nimeä (sum).
• Se ei käsittele tapausta, jossa syötelista on tyhjä (nollalla jakaminen).

Suorita ensin Black muotoillaksesi koodin:

            black my_file.py
            

              
                Copy
              
            
          

Black muotoilee koodin uudelleen muotoon:

            def calculate_average(numbers):
    sum = 0
    for number in numbers:
        sum += number
    return sum / len(numbers)
            

              
                Copy
              
            
          

Suorita seuraavaksi Flake8 tarkistaaksesi tyylivirheet:

            flake8 my_file.py
            

              
                Copy
              
            
          

Flake8 tulostaa seuraavat virheet:

            my_file.py:2:1: F841 local variable 'sum' is assigned to but never used
my_file.py:4:11: F821 undefined name 'numbers'

            

              
                Copy
              
            
          

Korjattuasi Flake8-virheet (huomaa, että tämä virhetuloste voi vaihdella flake8-konfiguraatiosi mukaan) ja lisättyäsi tyyppivihjeet, koodista tulee:

            from typing import List

def calculate_average(numbers: List[float]) -> float:
    """Calculates the average of a list of numbers."""
    if not numbers:
        return 0.0  # Vältä nollalla jakamista
    total = sum(numbers)
    return total / len(numbers)
            

              
                Copy
              
            
          

Suorita lopuksi mypy tarkistaaksesi tyyppivirheet:

            mypy my_file.py
            

              
                Copy
              
            
          

Jos tyyppivirheitä ei ole, mypy ei tulosta mitään. Tässä tapauksessa tarkistus menee läpi. Koodi on nyt muotoiltu PEP 8:n mukaisesti, siinä on tyyppivihjeet, se käyttää kuvaavampia muuttujien nimiä ja käsittelee tapauksen, jossa syötelista on tyhjä. Tämä osoittaa, kuinka Black, Flake8 ja mypy voivat toimia yhdessä parantaakseen Python-koodisi laatua ja luotettavuutta.

Käytännön ohjeita ja parhaita käytäntöjä

• Aloita ajoissa: Integroi Black, Flake8 ja mypy kehitystyönkulkuusi heti projektien alusta alkaen. Tämä auttaa ylläpitämään yhtenäistä koodityyliä ja nappaamaan mahdolliset virheet varhaisessa vaiheessa.
• Konfiguroi työkalusi: Mukauta Black, Flake8 ja mypy vastaamaan omia tarpeitasi ja mieltymyksiäsi. Käytä konfiguraatiotiedostoja määrittääksesi, mitkä tarkistukset otetaan käyttöön tai pois käytöstä, aseta rivin enimmäispituus ja konfiguroi muita asetuksia.
• Käytä Pre-commit-koukkuja: Integroi Black, Flake8 ja mypy pre-commitiin varmistaaksesi, että kaikki arkistoon commitoitu koodi on oikein muotoiltu ja tyyppitarkistettu.
• Automatisoi työnkulkusi: Käytä CI/CD-putkia suorittaaksesi Blackin, Flake8:n ja mypyn automaattisesti jokaisen commitin yhteydessä. Tämä auttaa sinua nappaamaan koodin laatuongelmat ennen kuin ne pääsevät tuotantoon. Palvelut kuten GitHub Actions, GitLab CI ja Jenkins voidaan konfiguroida suorittamaan nämä tarkistukset automaattisesti.
• Kouluta tiimisi: Varmista, että kaikki tiimin jäsenet tuntevat Blackin, Flake8:n ja mypyn ja ymmärtävät, kuinka niitä käytetään tehokkaasti. Tarjoa koulutusta ja dokumentaatiota auttaaksesi tiimiäsi omaksumaan nämä työkalut ja ylläpitämään yhtenäistä koodityyliä.
• Ota käyttöön asteittainen tyypitys: Jos työskentelet suuren, olemassa olevan koodikannan parissa, harkitse asteittaisen tyypityksen omaksumista. Aloita lisäämällä tyyppivihjeitä koodisi kriittisimpiin osiin ja laajenna kattavuutta vähitellen ajan myötä.

Yhteenveto

Panostaminen koodin laatuun on investointi projektien pitkän aikavälin menestykseen. Integroimalla Blackin, Flake8:n ja mypyn kehitystyönkulkuusi voit merkittävästi parantaa Python-koodisi luettavuutta, ylläpidettävyyttä ja luotettavuutta. Nämä työkalut ovat välttämättömiä jokaiselle vakavasti otettavalle Python-kehittäjälle, riippumatta heidän sijainnistaan tai projektiensa luonteesta. Piilaakson startup-yrityksistä Singaporen vakiintuneisiin yrityksiin, näiden parhaiden käytäntöjen omaksuminen johtaa epäilemättä tehokkaampaan ja vaikuttavampaan ohjelmistokehitykseen.

Muista mukauttaa nämä ohjeet ja työkalut omaan kontekstiisi. Kokeile erilaisia konfiguraatioita, tutustu saatavilla oleviin lisäosiin ja räätälöi työnkulkusi vastaamaan tiimisi ja projektiesi ainutlaatuisia tarpeita. Pyrkimällä jatkuvasti korkeampaan koodin laatuun olet hyvissä asemissa rakentamaan vankkoja, skaalautuvia ja ylläpidettäviä sovelluksia, jotka tuottavat arvoa käyttäjillesi vuosien ajan.