Pythoni koodi kvaliteet: Black, Flake8 ja mypy integreerimise meisterlikkus

Tarkvaraarenduse maailmas on toimiva koodi kirjutamine vaid pool võitu. Ühtse stiili säilitamine, parimate tavade järgimine ja tüübiohutuse tagamine on sama olulised tugevate, hooldatavate ja koostööl põhinevate projektide loomisel. Python, mis on tuntud oma loetavuse poolest, saab suurt kasu tööriistadest, mis neid aspekte automatiseerivad. See põhjalik juhend uurib kolme võimsa tööriista integreerimist: Black, Flake8 ja mypy, et tõsta teie Pythoni koodi kvaliteet uuele tasemele.

Miks on koodi kvaliteet oluline

Enne iga tööriista spetsiifikasse sukeldumist, mõistkem, miks on koodi kvaliteet esmatähtis:

• Loetavus: Ühtne koodistiil teeb arendajatele koodi mõistmise ja muutmise lihtsamaks.
• Hooldatavus: Hästi vormindatud ja tüübikontrollitud kood vähendab vigade tõenäosust ja lihtsustab silumist.
• Koostöö: Jagatud koodistiilid tagavad, et kõik meeskonnaliikmed kirjutavad koodi ühtsel viisil, soodustades sujuvat koostööd.
• Vähendatud tehniline võlg: Koodikvaliteedi probleemidega varakult tegelemine hoiab ära tehnilise võla kuhjumise, säästes pikemas perspektiivis aega ja ressursse.
• Suurem töökindlus: Staatiline tüübikontroll püüab kinni potentsiaalsed vead enne käivitamist, parandades teie rakenduste üldist töökindlust.

Need eelised ei piirdu konkreetsete tööstusharude või piirkondadega. Olenemata sellest, kas arendate veebirakendust Berliinis, andmeteaduse projekti Bangalores või mobiilirakendust Mexico Citys, parandab ühtlane koodikvaliteet kahtlemata teie arendustöövoogu.

Tutvustame Blacki: kompromissitu koodivormindaja

Black on Pythoni koodivormindaja, mis vormindab teie koodi automaatselt ühtse stiili järgi. See on kindlameelne (opinionated), mis tähendab, et see teeb teie eest otsuseid koodi vormindamise kohta, minimeerides arutelusid stiili üle ja võimaldades arendajatel keskenduda funktsionaalsusele.

Blacki peamised omadused

• Automaatne vormindamine: Black vormindab teie koodi automaatselt vastavalt oma eelnevalt määratletud stiilijuhisele (põhineb PEP 8-l).
• Kompromissitu: Black jätab vähe ruumi kohandamiseks, jõustades ühtse stiili kogu teie koodibaasis.
• Integratsioon redaktoritega: Black integreerub sujuvalt populaarsete koodiredaktoritega nagu VS Code, PyCharm ja Sublime Text.
• Pre-commit hook: Blacki saab kasutada pre-commit hook'ina, et tagada kogu teie hoidlasse commititud koodi korrektne vormindamine.

Blacki paigaldamine

Saate Blacki paigaldada pip-i abil:

            pip install black
            

              
                Copy
              
            
          

Blacki kasutamine

Pythoni faili vormindamiseks Blackiga käivitage lihtsalt järgmine käsk:

            black my_file.py
            

              
                Copy
              
            
          

Black vormindab faili kohapeal ümber, järgides oma eelnevalt määratletud stiilireegleid. Terve kausta vormindamiseks käivitage:

            black my_directory
            

              
                Copy
              
            
          

Näide: Vormindamine Blackiga

Vaatleme järgmist halvasti vormindatud Pythoni koodi:

            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
              
            
          

Pärast Blacki käivitamist vormindatakse kood automaatselt ümber järgmiselt:

            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
              
            
          

Pange tähele, kuidas Black on automaatselt kohandanud tühikuid, reavahetusi ja taandeid, et need vastaksid tema stiilijuhisele.

Blacki integreerimine Pre-commitiga

Pre-commit on tööriist, mis võimaldab teil oma koodi kontrollida enne selle hoidlasse commitimist. Blacki integreerimine pre-commitiga tagab, et kogu commititud kood on korrektselt vormindatud.

1. Paigaldage pre-commit:

            pip install pre-commit
            

              
                Copy
              
            
          

2. Looge oma hoidla juurkataloogi fail nimega .pre-commit-config.yaml:

            repos:
-   repo: https://github.com/psf/black
    rev: 23.12.1  # Asenda uusima versiooniga
    hooks:
    -   id: black
            

              
                Copy
              
            
          

3. Paigaldage pre-commit hookid:

            pre-commit install
            

              
                Copy
              
            
          

Nüüd, iga kord kui koodi commitite, käivitab pre-commit Blacki, et teie failid vormindada. Kui Black teeb muudatusi, siis commit tühistatakse ja teil tuleb muudatused stage'ida ja uuesti commitida.

Tutvustame Flake8: koodistiili kontrollija

Flake8 on ümbris mitme populaarse Pythoni lintimise tööriista ümber, sealhulgas pycodestyle (endine pep8), pyflakes ja mccabe. See kontrollib teie koodi stiilivigade, süntaksivigade ja koodi keerukuse probleemide osas, aidates teil järgida PEP 8 stiilijuhist ja kirjutada puhtamat, paremini hooldatavat koodi.

Flake8 peamised omadused

• Stiilivigade tuvastamine: Flake8 tuvastab PEP 8 stiilijuhise rikkumised, näiteks vale taane, rea pikkuse rikkumised ja kasutamata importimised.
• Süntaksivigade tuvastamine: Flake8 tuvastab teie koodis süntaksivigu, aidates teil potentsiaalseid vigu varakult avastada.
• Koodi keerukuse analüüs: Flake8 kasutab mccabe'i teie koodi tsüklomaatilise keerukuse arvutamiseks, tuvastades potentsiaalselt keerulisi ja raskesti hooldatavaid funktsioone.
• Laiendatavus: Flake8 toetab laia valikut pluginaid, mis võimaldavad teil selle käitumist kohandada ja lisada tuge täiendavatele kontrollidele.

Flake8 paigaldamine

Saate Flake8 paigaldada pip-i abil:

            pip install flake8
            

              
                Copy
              
            
          

Flake8 kasutamine

Pythoni faili kontrollimiseks Flake8-ga käivitage lihtsalt järgmine käsk:

            flake8 my_file.py
            

              
                Copy
              
            
          

Flake8 väljastab nimekirja kõigist stiilivigadest, süntaksivigadest või koodi keerukuse probleemidest, mida ta failist leiab. Terve kausta kontrollimiseks käivitage:

            flake8 my_directory
            

              
                Copy
              
            
          

Näide: Stiilivigade tuvastamine Flake8-ga

Vaatleme järgmist Pythoni koodi:

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

              
                Copy
              
            
          

Flake8 käivitamine sellel koodil annab järgmise väljundi:

            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 tuvastanud mitu stiiliviga, sealhulgas puuduvad tühjad read, puuduv tühik pärast koma, vale taane ja puuduv tühik operaatori ümber. Need vead tuleks parandada, et parandada koodi loetavust ja vastavust PEP 8-le.

Flake8 konfigureerimine

Flake8 saab konfigureerida faili .flake8 abil oma hoidla juurkataloogis. See fail võimaldab teil määrata, milliseid kontrolle lubada või keelata, seada maksimaalse rea pikkuse ja konfigureerida muid seadeid.

Siin on näide .flake8 failist:

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

              
                Copy
              
            
          

Selles näites on maksimaalne rea pikkus seatud 120 märgile ning kontrollid E203 ja W503 on keelatud. E203 viitab tühikule enne koolonit (':') ja seda peetakse sageli stiililiseks eelistuseks, mida Black niikuinii haldab. W503 viitab reavahetusele enne binaaroperaatoreid, mida Black samuti käsitleb.

Flake8 integreerimine Pre-commitiga

Flake8 integreerimiseks pre-commitiga lisage oma .pre-commit-config.yaml faili järgmine:

            -   repo: https://github.com/pycqa/flake8
    rev: 6.1.0 # Asenda uusima versiooniga
    hooks:
    -   id: flake8
            

              
                Copy
              
            
          

Nüüd, iga kord kui koodi commitite, käivitab pre-commit Flake8, et kontrollida stiilivigu. Kui Flake8 leiab vigu, siis commit tühistatakse ja teil tuleb vead parandada ja uuesti commitida.

Tutvustame mypy: staatiline tüübikontrollija

mypy on Pythoni staatiline tüübikontrollija, mis aitab teil tüübivigu avastada enne käivitamist. Python on dünaamiliselt tüübitud keel, mis tähendab, et muutuja tüüpi ei kontrollita enne käivitamist. See võib põhjustada ootamatuid vigu ja probleeme. mypy võimaldab teil lisada oma koodile tüübihüvitiseid (type hints), mis võimaldab staatilist tüübikontrolli ja parandab teie rakenduste töökindlust.

mypy peamised omadused

• Staatiline tüübikontroll: mypy kontrollib muutujate, funktsioonide argumentide ja tagastusväärtuste tüüpe kompileerimise ajal, püüdes kinni potentsiaalsed tüübivead enne käivitamist.
• Tüübihüvitised (Type Hints): mypy kasutab tüübihüvitisi, mis on annotatsioonid, mis määravad muutuja või funktsiooni oodatava tüübi.
• Järkjärguline tüpiseerimine: mypy toetab järkjärgulist tüpiseerimist, mis tähendab, et saate oma koodile tüübihüvitisi lisada järk-järgult, ilma et peaksite korraga kogu oma koodibaasi tüübikontrolli tegema.
• Integratsioon redaktoritega: mypy integreerub sujuvalt populaarsete koodiredaktoritega nagu VS Code ja PyCharm.

mypy paigaldamine

Saate mypy paigaldada pip-i abil:

            pip install mypy
            

              
                Copy
              
            
          

mypy kasutamine

Pythoni faili kontrollimiseks mypy-ga käivitage lihtsalt järgmine käsk:

            mypy my_file.py
            

              
                Copy
              
            
          

mypy väljastab nimekirja kõigist tüübivigadest, mida ta failist leiab. Terve kausta kontrollimiseks käivitage:

            mypy my_directory
            

              
                Copy
              
            
          

Näide: Tüübihüvitiste lisamine ja tüübivigade tuvastamine

Vaatleme järgmist Pythoni koodi:

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

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

              
                Copy
              
            
          

See kood käivitub vigadeta, kuid annab ootamatuid tulemusi, kuna see liidab täisarvu ja sõne. Selle tüübivea tabamiseks saate lisada add funktsioonile tüübihüvitised:

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

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

              
                Copy
              
            
          

Nüüd, kui käivitate mypy, väljastab see järgmise vea:

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

              
                Copy
              
            
          

mypy on tuvastanud, et edastate add funktsioonile sõne, mis ootab täisarvu. See võimaldab teil vea enne käivitamist tabada ja vältida ootamatut käitumist.

mypy konfigureerimine

mypy saab konfigureerida faili mypy.ini või pyproject.toml abil oma hoidla juurkataloogis. See fail võimaldab teil määrata, milliseid kontrolle lubada või keelata, seada Pythoni versiooni ja konfigureerida muid seadeid. pyproject.toml-i kasutamine on kaasaegne soovitatav lähenemine.

Siin on näide pyproject.toml failist:

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

              
                Copy
              
            
          

Selles näites on Pythoni versiooniks seatud 3.11 ja range režiim on lubatud. Range režiim lubab kõik mypy kõige rangemad kontrollid, aidates teil tabada veelgi rohkem potentsiaalseid tüübivigu.

mypy integreerimine Pre-commitiga

mypy integreerimiseks pre-commitiga lisage oma .pre-commit-config.yaml faili järgmine:

            -   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.6.1 # Asenda uusima versiooniga
    hooks:
    -   id: mypy
            

              
                Copy
              
            
          

Nüüd, iga kord kui koodi commitite, käivitab pre-commit mypy, et kontrollida tüübivigu. Kui mypy leiab vigu, siis commit tühistatakse ja teil tuleb vead parandada ja uuesti commitida.

Kõike kokku pannes: täielik integratsiooni näide

Et demonstreerida Blacki, Flake8 ja mypy integreerimise võimsust, vaatame läbi täieliku näite. Vaatleme järgmist Pythoni koodi:

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

              
                Copy
              
            
          

Sellel koodil on mitu probleemi:

• See ei ole vormindatud vastavalt PEP 8-le.
• Sellel puuduvad tüübihüvitised.
• See kasutab potentsiaalselt segadust tekitavat muutujanime (sum).
• See ei käsitle juhtu, kus sisendloend on tühi (nulliga jagamine).

Esiteks käivitage Black koodi vormindamiseks:

            black my_file.py
            

              
                Copy
              
            
          

Black vormindab koodi ümber järgmiselt:

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

              
                Copy
              
            
          

Järgmisena käivitage Flake8 stiilivigade kontrollimiseks:

            flake8 my_file.py
            

              
                Copy
              
            
          

Flake8 väljastab järgmised vead:

            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
              
            
          

Flake8 vigade parandamine (pange tähele, et see konkreetne vea väljund varieerub sõltuvalt teie flake8 konfiguratsioonist) ja tüübihüvitiste lisamine muudab koodi järgmiseks:

            from typing import List

def calculate_average(numbers: List[float]) -> float:
    """Arvutab arvude loendi keskmise."""
    if not numbers:
        return 0.0  # Väldi nulliga jagamist
    total = sum(numbers)
    return total / len(numbers)
            

              
                Copy
              
            
          

Lõpuks käivitage mypy tüübivigade kontrollimiseks:

            mypy my_file.py
            

              
                Copy
              
            
          

Kui tüübivigu pole, ei väljasta mypy midagi. Sel juhul see läbib kontrolli. Kood on nüüd vormindatud vastavalt PEP 8-le, sellel on tüübihüvitised, see kasutab kirjeldavamaid muutujanimesid ja käsitleb juhtu, kus sisendloend on tühi. See demonstreerib, kuidas Black, Flake8 ja mypy saavad koos töötada, et parandada teie Pythoni koodi kvaliteeti ja töökindlust.

Praktilised nõuanded ja parimad tavad

• Alustage varakult: Integreerige Black, Flake8 ja mypy oma arendustöövoogu juba projektide algusest peale. See aitab teil säilitada ühtset koodistiili ja püüda potentsiaalseid vigu varakult kinni.
• Konfigureerige oma tööriistad: Kohandage Black, Flake8 ja mypy vastavalt oma konkreetsetele vajadustele ja eelistustele. Kasutage konfiguratsioonifaile, et määrata, milliseid kontrolle lubada või keelata, seada maksimaalne rea pikkus ja konfigureerida muid seadeid.
• Kasutage Pre-commit Hooke: Integreerige Black, Flake8 ja mypy pre-commitiga, et tagada kogu teie hoidlasse commititud koodi korrektne vormindamine ja tüübikontroll.
• Automatiseerige oma töövoog: Kasutage CI/CD konveierliine, et automaatselt käivitada Black, Flake8 ja mypy iga commiti peal. See aitab teil tabada koodikvaliteedi probleeme enne, kui need jõuavad tootmiskeskkonda. Teenuseid nagu GitHub Actions, GitLab CI ja Jenkins saab konfigureerida neid kontrolle automaatselt käivitama.
• Harige oma meeskonda: Veenduge, et kõik meeskonnaliikmed tunneksid Blacki, Flake8 ja mypy'd ning mõistaksid, kuidas neid tõhusalt kasutada. Pakkuge koolitust ja dokumentatsiooni, et aidata oma meeskonnal neid tööriistu kasutusele võtta ja säilitada ühtset koodistiili.
• Võtke omaks järkjärguline tüpiseerimine: Kui töötate suure, olemasoleva koodibaasiga, kaaluge järkjärgulise tüpiseerimise kasutuselevõttu. Alustage tüübihüvitiste lisamisest oma koodi kõige kriitilisematele osadele ja laiendage katvust järk-järgult aja jooksul.

Kokkuvõte

Investeerimine koodi kvaliteeti on investeering teie projektide pikaajalisse edusse. Integreerides Blacki, Flake8 ja mypy oma arendustöövoogu, saate oluliselt parandada oma Pythoni koodi loetavust, hooldatavust ja töökindlust. Need tööriistad on hädavajalikud igale tõsisele Pythoni arendajale, olenemata nende asukohast või projektide olemusest. Alates idufirmadest Silicon Valley's kuni väljakujunenud ettevõteteni Singapuris – nende parimate tavade omaksvõtmine viib kahtlemata tõhusama ja efektiivsema tarkvaraarenduseni.

Pidage meeles, et kohandage neid juhiseid ja tööriistu oma konkreetse kontekstiga. Katsetage erinevate konfiguratsioonidega, uurige saadaolevaid pluginaid ja kohandage oma töövoogu vastavalt oma meeskonna ja projektide ainulaadsetele vajadustele. Pidevalt kõrgema koodikvaliteedi poole püüeldes olete heas positsioonis, et ehitada tugevaid, skaleeritavaid ja hooldatavaid rakendusi, mis pakuvad teie kasutajatele väärtust aastaid.