Python kódminőség: A Black, Flake8 és mypy integrációjának mesteri szintű alkalmazása

A szoftverfejlesztés világában a működő kód megírása csak a csata fele. A konzisztens stílus fenntartása, a legjobb gyakorlatok követése és a típusbiztonság garantálása egyaránt elengedhetetlen a robusztus, karbantartható és kollaboratív projektek létrehozásához. A Python, amely az olvashatóságáról ismert, nagyban profitál azokból az eszközökből, amelyek automatizálják ezeket a szempontokat. Ez az átfogó útmutató három hatékony eszköz: a Black, a Flake8 és a mypy integrációját tárja fel, hogy Python kódjának minőségét a következő szintre emelje.

Miért számít a kódminőség

Mielőtt belemerülnénk az egyes eszközök részleteibe, értsük meg, miért is kiemelkedően fontos a kódminőség:

• Olvashatóság: A következetes kódstílus megkönnyíti a fejlesztők számára a kód megértését és módosítását.
• Karbantarthatóság: A jól formázott és típusellenőrzött kód csökkenti a hibák valószínűségét és egyszerűsíti a hibakeresést.
• Együttműködés: A közös kódstílusok biztosítják, hogy minden csapattag egységesen írjon kódot, elősegítve a zökkenőmentes együttműködést.
• Csökkentett technikai adósság: A kódminőségi problémák korai kezelése megakadályozza a technikai adósság felhalmozódását, hosszú távon időt és erőforrásokat takarítva meg.
• Fokozott megbízhatóság: A statikus típusellenőrzés még futásidő előtt elkapja a lehetséges hibákat, javítva az alkalmazások általános megbízhatóságát.

Ezek az előnyök nem korlátozódnak bizonyos iparágakra vagy régiókra. Akár egy webalkalmazást fejleszt Berlinben, egy adattudományi projektet Bengaluruban, vagy egy mobilalkalmazást Mexikóvárosban, a következetes kódminőség kétségtelenül javítani fogja a fejlesztési munkafolyamatát.

Bemutatkozik a Black: A megalkuvást nem ismerő kódformázó

A Black egy Python kódformázó, amely automatikusan újraformázza a kódot egy konzisztens stílusnak megfelelően. Véleményvezérelt (opinionated), ami azt jelenti, hogy döntéseket hoz helyetted a kód formázásával kapcsolatban, minimalizálva a stílusról szóló vitákat, és lehetővé téve a fejlesztőknek, hogy a funkcionalitásra összpontosítsanak.

A Black főbb jellemzői

• Automatikus formázás: A Black automatikusan újraformázza a kódot az előre meghatározott stílus útmutatója szerint (a PEP 8 alapján).
• Megalkuvást nem ismerő: A Black kevés teret hagy a testreszabásnak, egységes stílust kényszerítve ki a teljes kódbázisban.
• Integráció szerkesztőkkel: A Black zökkenőmentesen integrálódik olyan népszerű kódszerkesztőkkel, mint a VS Code, a PyCharm és a Sublime Text.
• Pre-commit hook: A Black használható pre-commit hookként, hogy biztosítsa, hogy a repositoryba commitolt minden kód megfelelően formázott legyen.

A Black telepítése

A Black-et a pip segítségével telepítheti:

            pip install black
            

              
                Copy
              
            
          

A Black használata

Egy Python fájl Black-kel való formázásához egyszerűen futtassa a következő parancsot:

            black my_file.py
            

              
                Copy
              
            
          

A Black helyben újraformázza a fájlt, betartva az előre meghatározott stílusszabályait. Egy teljes könyvtár formázásához futtassa:

            black my_directory
            

              
                Copy
              
            
          

Példa: Formázás a Blackkel

Vegyük a következő rosszul formázott Python kódot:

            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
              
            
          

A Black futtatása után a kód automatikusan a következőképpen lesz újraformázva:

            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
              
            
          

Figyelje meg, hogyan igazította a Black automatikusan a szóközöket, sortöréseket és behúzásokat, hogy megfeleljen a stílus útmutatójának.

A Black integrálása Pre-committel

A Pre-commit egy eszköz, amely lehetővé teszi, hogy ellenőrzéseket futtasson a kódján, mielőtt commitolná azt a repositoryba. A Black integrálása a pre-committel biztosítja, hogy minden commitolt kód megfelelően formázott legyen.

1. Telepítse a pre-commit-et:

            pip install pre-commit
            

              
                Copy
              
            
          

2. Hozzon létre egy .pre-commit-config.yaml fájlt a repository gyökerében:

            repos:
-   repo: https://github.com/psf/black
    rev: 23.12.1  # Cserélje le a legújabb verzióra
    hooks:
    -   id: black
            

              
                Copy
              
            
          

3. Telepítse a pre-commit hookokat:

            pre-commit install
            

              
                Copy
              
            
          

Mostantól minden alkalommal, amikor kódot commitol, a pre-commit lefuttatja a Black-et a fájlok formázására. Ha a Black változtatásokat hajt végre, a commit megszakad, és Önnek stage-elnie kell a változtatásokat, majd újra commitolnia.

Bemutatkozik a Flake8: A kódstílus-ellenőrző

A Flake8 egy csomagoló (wrapper) több népszerű Python linting eszköz köré, beleértve a pycodestyle-t (korábban pep8), a pyflakes-t és a mccabe-et. Ellenőrzi a kódot stílus hibák, szintaktikai hibák és kód komplexitási problémák szempontjából, segítve a PEP 8 stílus útmutató betartását és tisztább, karbantarthatóbb kód írását.

A Flake8 főbb jellemzői

• Stílushiba-észlelés: A Flake8 azonosítja a PEP 8 stílus útmutató megsértését, mint például a helytelen behúzás, a sorhosszúság túllépése és a nem használt importok.
• Szintaktikai hiba észlelése: A Flake8 észleli a szintaktikai hibákat a kódban, segítve a lehetséges hibák korai elkapását.
• Kód komplexitás elemzése: A Flake8 a mccabe-et használja a kód ciklikus komplexitásának kiszámításához, azonosítva a potenciálisan bonyolult és nehezen karbantartható függvényeket.
• Bővíthetőség: A Flake8 támogatja a bővítmények széles skáláját, lehetővé téve viselkedésének testreszabását és további ellenőrzések hozzáadását.

A Flake8 telepítése

A Flake8-et a pip segítségével telepítheti:

            pip install flake8
            

              
                Copy
              
            
          

A Flake8 használata

Egy Python fájl Flake8-cel való ellenőrzéséhez egyszerűen futtassa a következő parancsot:

            flake8 my_file.py
            

              
                Copy
              
            
          

A Flake8 kiírja a fájlban talált stílus hibák, szintaktikai hibák vagy kód komplexitási problémák listáját. Egy teljes könyvtár ellenőrzéséhez futtassa:

            flake8 my_directory
            

              
                Copy
              
            
          

Példa: Stílushibák azonosítása a Flake8-cel

Vegyük a következő Python kódot:

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

              
                Copy
              
            
          

A Flake8 futtatása ezen a kódon a következő kimenetet eredményezi:

            my_file.py:1:1: E302 2 üres sor várt, 0 található
my_file.py:1:14: E231 hiányzó szóköz a ',' után
my_file.py:2:4: E128 a folytatódó sor alul-behúzott a vizuális behúzáshoz
my_file.py:3:12: E226 hiányzó szóköz az operátor körül

            

              
                Copy
              
            
          

A Flake8 több stílushibát azonosított, beleértve a hiányzó üres sorokat, a vessző utáni hiányzó szóközt, a helytelen behúzást és az operátor körüli hiányzó szóközt. Ezeket a hibákat orvosolni kell a kód olvashatóságának és a PEP 8-nak való megfelelés javítása érdekében.

A Flake8 konfigurálása

A Flake8 konfigurálható egy .flake8 fájl segítségével a repository gyökerében. Ez a fájl lehetővé teszi, hogy megadja, mely ellenőrzéseket engedélyezze vagy tiltsa le, beállítsa a maximális sorhosszúságot és egyéb beállításokat konfiguráljon.

Íme egy példa egy .flake8 fájlra:

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

              
                Copy
              
            
          

Ebben a példában a maximális sorhossz 120 karakterre van állítva, és az E203 és W503 ellenőrzések le vannak tiltva. Az E203 a ':' előtti szóközre vonatkozik, és gyakran stilisztikai preferenciának tekintik, amit a Black amúgy is kezel. A W503 a bináris operátorok előtti sortörésekre vonatkozik, amit szintén a Black kezel.

A Flake8 integrálása Pre-committel

A Flake8 Pre-committel való integrálásához adja hozzá a következőket a .pre-commit-config.yaml fájlhoz:

            -   repo: https://github.com/pycqa/flake8
    rev: 6.1.0 # Cserélje le a legújabb verzióra
    hooks:
    -   id: flake8
            

              
                Copy
              
            
          

Mostantól minden alkalommal, amikor kódot commitol, a pre-commit lefuttatja a Flake8-et a stílus hibák ellenőrzésére. Ha a Flake8 hibát talál, a commit megszakad, és Önnek ki kell javítania a hibákat, majd újra commitolnia.

Bemutatkozik a mypy: A statikus típusellenőrző

A mypy egy statikus típusellenőrző Pythonhoz, amely segít a típus hibák futásidő előtti elkapásában. A Python egy dinamikusan tipizált nyelv, ami azt jelenti, hogy egy változó típusát csak futásidőben ellenőrzik. Ez váratlan hibákhoz és bugokhoz vezethet. A mypy lehetővé teszi, hogy típus jelöléseket (type hints) adjon a kódjához, lehetővé téve a statikus típusellenőrzést és javítva az alkalmazások megbízhatóságát.

A mypy főbb jellemzői

• Statikus típusellenőrzés: A mypy fordítási időben ellenőrzi a változók, függvény argumentumok és visszatérési értékek típusait, elkapva a lehetséges típus hibákat futásidő előtt.
• Típus jelölések (Type hints): A mypy típus jelöléseket használ, amelyek olyan annotációk, amelyek megadják egy változó vagy függvény várt típusát.
• Fokozatos tipizálás (Gradual typing): A mypy támogatja a fokozatos tipizálást, ami azt jelenti, hogy lépésről lépésre adhat hozzá típus jelöléseket a kódjához, anélkül, hogy egyszerre kellene típusellenőrzést végeznie a teljes kódbázison.
• Integráció szerkesztőkkel: A mypy zökkenőmentesen integrálódik olyan népszerű kódszerkesztőkkel, mint a VS Code és a PyCharm.

A mypy telepítése

A mypy-t a pip segítségével telepítheti:

            pip install mypy
            

              
                Copy
              
            
          

A mypy használata

Egy Python fájl mypy-val való ellenőrzéséhez egyszerűen futtassa a következő parancsot:

            mypy my_file.py
            

              
                Copy
              
            
          

A mypy kiírja a fájlban talált típus hibák listáját. Egy teljes könyvtár ellenőrzéséhez futtassa:

            mypy my_directory
            

              
                Copy
              
            
          

Példa: Típus jelölések hozzáadása és típus hibák észlelése

Vegyük a következő Python kódot:

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

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

              
                Copy
              
            
          

Ez a kód hiba nélkül lefut, de váratlan eredményt fog produkálni, mert egy egészet és egy sztringet ad össze. Ennek a típus hibának az elkapásához típus jelöléseket adhat az add függvényhez:

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

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

              
                Copy
              
            
          

Most, amikor a mypy-t futtatja, a következő hibát fogja kiadni:

            my_file.py:4: error: Az "add" függvény 2. argumentumának típusa ("str") inkompatibilis; "int" várt
            

              
                Copy
              
            
          

A mypy észlelte, hogy egy sztringet ad át az add függvénynek, amely egy egészet vár. Ez lehetővé teszi, hogy a hibát futásidő előtt elkapja és megelőzze a váratlan viselkedést.

A mypy konfigurálása

A mypy konfigurálható egy mypy.ini vagy pyproject.toml fájl segítségével a repository gyökerében. Ez a fájl lehetővé teszi, hogy megadja, mely ellenőrzéseket engedélyezze vagy tiltsa le, beállítsa a Python verziót és egyéb beállításokat konfiguráljon. A pyproject.toml használata a modern, ajánlott megközelítés.

Íme egy példa egy pyproject.toml fájlra:

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

              
                Copy
              
            
          

Ebben a példában a Python verzió 3.11-re van állítva, és a szigorú (strict) mód engedélyezve van. A szigorú mód engedélyezi a mypy összes legszigorúbb ellenőrzését, segítve még több potenciális típus hiba elkapását.

A mypy integrálása Pre-committel

A mypy Pre-committel való integrálásához adja hozzá a következőket a .pre-commit-config.yaml fájlhoz:

            -   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.6.1 # Cserélje le a legújabb verzióra
    hooks:
    -   id: mypy
            

              
                Copy
              
            
          

Mostantól minden alkalommal, amikor kódot commitol, a pre-commit lefuttatja a mypy-t a típus hibák ellenőrzésére. Ha a mypy hibát talál, a commit megszakad, és Önnek ki kell javítania a hibákat, majd újra commitolnia.

Mindent egybevetve: Egy teljes integrációs példa

Annak bemutatására, hogy milyen erőteljes a Black, Flake8 és mypy integrációja, nézzünk végig egy teljes példát. Vegyük a következő Python kódot:

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

              
                Copy
              
            
          

Ennek a kódnak több problémája is van:

• Nincs a PEP 8 szerint formázva.
• Hiányoznak a típus jelölések.
• Potenciálisan zavaró változónevet használ (sum).
• Nem kezeli azt az esetet, amikor a bemeneti lista üres (nullával való osztás).

Először futtassa a Black-et a kód formázásához:

            black my_file.py
            

              
                Copy
              
            
          

A Black a kódot a következőképpen fogja újraformázni:

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

              
                Copy
              
            
          

Ezután futtassa a Flake8-et a stílus hibák ellenőrzésére:

            flake8 my_file.py
            

              
                Copy
              
            
          

A Flake8 a következő hibákat fogja kiadni:

            my_file.py:2:1: F841 a 'sum' lokális változó értéket kap, de soha nincs használva
my_file.py:4:11: F821 nem definiált 'numbers' név

            

              
                Copy
              
            
          

A Flake8 hibák javítása után (megjegyzés: ez a konkrét hibakimenet a flake8 konfigurációjától függően változhat) és típus jelölések hozzáadásával a kód a következővé válik:

            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  # Nullával való osztás elkerülése
    total = sum(numbers)
    return total / len(numbers)
            

              
                Copy
              
            
          

Végül futtassa a mypy-t a típus hibák ellenőrzésére:

            mypy my_file.py
            

              
                Copy
              
            
          

Ha nincsenek típus hibák, a mypy nem ad ki semmit. Ebben az esetben átmegy az ellenőrzésen. A kód most már a PEP 8 szerint van formázva, rendelkezik típus jelölésekkel, leíróbb változóneveket használ, és kezeli azt az esetet, amikor a bemeneti lista üres. Ez bemutatja, hogyan működhet együtt a Black, a Flake8 és a mypy a Python kód minőségének és megbízhatóságának javítása érdekében.

Gyakorlati tanácsok és legjobb gyakorlatok

• Kezdje korán: Integrálja a Black-et, Flake8-et és mypy-t a fejlesztési munkafolyamatába már a projektjei elején. Ez segít fenntartani a következetes kódstílust és korán elkapni a lehetséges hibákat.
• Konfigurálja az eszközeit: Szabja testre a Black-et, Flake8-et és mypy-t a sajátos igényeinek és preferenciáinak megfelelően. Használjon konfigurációs fájlokat annak megadására, hogy mely ellenőrzéseket engedélyezze vagy tiltsa le, állítsa be a maximális sorhosszúságot és konfiguráljon egyéb beállításokat.
• Használjon Pre-commit hookokat: Integrálja a Black-et, Flake8-et és mypy-t a pre-committel, hogy biztosítsa, hogy minden a repositoryba commitolt kód megfelelően formázott és típusellenőrzött legyen.
• Automatizálja a munkafolyamatát: Használjon CI/CD pipeline-okat a Black, Flake8 és mypy automatikus futtatására minden commitnál. Ez segít elkapni a kódminőségi problémákat, mielőtt azok a production környezetbe kerülnének. Olyan szolgáltatások, mint a GitHub Actions, GitLab CI és Jenkins, konfigurálhatók ezen ellenőrzések automatikus futtatására.
• Oktassa a csapatát: Biztosítsa, hogy minden csapattag ismerje a Black-et, Flake8-et és mypy-t, és értse, hogyan kell őket hatékonyan használni. Biztosítson képzést és dokumentációt, hogy segítse csapatát ezen eszközök elfogadásában és a következetes kódstílus fenntartásában.
• Alkalmazza a fokozatos tipizálást: Ha egy nagy, meglévő kódbázison dolgozik, fontolja meg a fokozatos tipizálás bevezetését. Kezdje azzal, hogy típus jelöléseket ad a kód legkritikusabb részeihez, és idővel fokozatosan bővítse a lefedettséget.

Összegzés

A kódminőségbe való befektetés egy befektetés a projektjei hosszú távú sikerébe. A Black, Flake8 és mypy fejlesztési munkafolyamatba való integrálásával jelentősen javíthatja a Python kód olvashatóságát, karbantarthatóságát és megbízhatóságát. Ezek az eszközök elengedhetetlenek minden komoly Python fejlesztő számára, függetlenül a tartózkodási helyüktől vagy projektjeik természetétől. A Szilícium-völgyi startupoktól a szingapúri nagyvállalatokig, ezen legjobb gyakorlatok alkalmazása kétségtelenül hatékonyabb szoftverfejlesztéshez vezet.

Ne felejtse el ezeket az irányelveket és eszközöket a sajátos kontextusához igazítani. Kísérletezzen különböző konfigurációkkal, fedezze fel a rendelkezésre álló bővítményeket, és szabja testre munkafolyamatát, hogy megfeleljen csapata és projektjei egyedi igényeinek. A folyamatosan magasabb kódminőségre való törekvéssel jó helyzetben lesz ahhoz, hogy robusztus, skálázható és karbantartható alkalmazásokat építsen, amelyek éveken át értéket nyújtanak a felhasználóknak.