Kvaliteta Python koda: Ovladavanje integracijom alata Black, Flake8 i mypy

U svijetu razvoja softvera, pisanje funkcionalnog koda samo je pola posla. Održavanje dosljednog stila, pridržavanje najboljih praksi i osiguravanje sigurnosti tipova jednako su ključni za stvaranje robusnih, održivih i kolaborativnih projekata. Python, poznat po svojoj čitljivosti, ima velike koristi od alata koji automatiziraju te aspekte. Ovaj sveobuhvatni vodič istražuje integraciju triju moćnih alata: Black, Flake8 i mypy, kako biste podigli kvalitetu svog Python koda na višu razinu.

Zašto je kvaliteta koda važna

Prije nego što zaronimo u specifičnosti svakog alata, shvatimo zašto je kvaliteta koda od presudne važnosti:

• Čitljivost: Dosljedan stil koda olakšava programerima razumijevanje i modificiranje koda.
• Održivost: Dobro formatiran kod s provjerom tipova smanjuje vjerojatnost pogrešaka i pojednostavljuje otklanjanje grešaka (debugging).
• Suradnja: Zajednički stilovi koda osiguravaju da svi članovi tima pišu kod na uniforman način, potičući besprijekornu suradnju.
• Smanjeni tehnički dug: Rano rješavanje problema s kvalitetom koda sprječava nakupljanje tehničkog duga, štedeći vrijeme i resurse na duge staze.
• Poboljšana pouzdanost: Statička provjera tipova hvata potencijalne pogreške prije izvođenja, poboljšavajući ukupnu pouzdanost vaših aplikacija.

Ove prednosti nisu ograničene na određene industrije ili regije. Bilo da razvijate web aplikaciju u Berlinu, projekt znanosti o podacima u Bangaloreu ili mobilnu aplikaciju u Mexico Cityju, dosljedna kvaliteta koda nedvojbeno će poboljšati vaš tijek rada.

Predstavljamo Black: Beskompromisni formater koda

Black je formater Python koda koji automatski preoblikuje vaš kod kako bi odgovarao dosljednom stilu. On je "tvrdoglav" (opinionated), što znači da donosi odluke umjesto vas o tome kako bi kod trebao biti formatiran, minimizirajući rasprave o stilu i omogućujući programerima da se usredotoče na funkcionalnost.

Ključne značajke alata Black

• Automatsko formatiranje: Black automatski preoblikuje vaš kod prema svom unaprijed definiranom stilskom vodiču (temeljenom na PEP 8).
• Beskompromisnost: Black ostavlja malo prostora za prilagodbu, namećući dosljedan stil u cijeloj vašoj kodnoj bazi.
• Integracija s uređivačima: Black se besprijekorno integrira s popularnim uređivačima koda poput VS Code, PyCharm i Sublime Text.
• Pre-commit hook: Black se može koristiti kao pre-commit hook kako bi se osiguralo da je sav kod koji se predaje u vaš repozitorij ispravno formatiran.

Instalacija alata Black

Black možete instalirati pomoću pip-a:

            pip install black
            

              
                Copy
              
            
          

Korištenje alata Black

Da biste formatirali Python datoteku s alatom Black, jednostavno pokrenite sljedeću naredbu:

            black my_file.py
            

              
                Copy
              
            
          

Black će preformatirati datoteku na mjestu, pridržavajući se svojih unaprijed definiranih stilskih pravila. Da biste formatirali cijeli direktorij, pokrenite:

            black my_directory
            

              
                Copy
              
            
          

Primjer: Formatiranje s alatom Black

Razmotrite sljedeći loše formatiran Python kod:

            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
              
            
          

Nakon pokretanja alata Black, kod će biti automatski preformatiran u:

            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
              
            
          

Primijetite kako je Black automatski prilagodio razmake, prijelome redaka i uvlačenje kako bi odgovarao svom stilskom vodiču.

Integracija alata Black s Pre-commitom

Pre-commit je alat koji vam omogućuje pokretanje provjera na vašem kodu prije nego što ga predate u repozitorij. Integracija alata Black s pre-commitom osigurava da je sav predani kod ispravno formatiran.

1. Instalirajte pre-commit:

            pip install pre-commit
            

              
                Copy
              
            
          

2. Stvorite datoteku .pre-commit-config.yaml u korijenu vašeg repozitorija:

            repos:
-   repo: https://github.com/psf/black
    rev: 23.12.1  # Zamijenite najnovijom verzijom
    hooks:
    -   id: black
            

              
                Copy
              
            
          

3. Instalirajte pre-commit hookove:

            pre-commit install
            

              
                Copy
              
            
          

Sada, svaki put kada predate kod, pre-commit će pokrenuti Black kako bi formatirao vaše datoteke. Ako Black napravi promjene, commit će biti prekinut, a vi ćete morati dodati promjene u stage i ponovno napraviti commit.

Predstavljamo Flake8: Provjeravač stila koda

Flake8 je omotač oko nekoliko popularnih Python alata za linting, uključujući pycodestyle (ranije pep8), pyflakes i mccabe. Provjerava vaš kod na stilske pogreške, sintaktičke pogreške i probleme sa složenošću koda, pomažući vam da se pridržavate stilskog vodiča PEP 8 i pišete čišći, održiviji kod.

Ključne značajke alata Flake8

• Otkrivanje stilskih pogrešaka: Flake8 identificira kršenja stilskog vodiča PEP 8, kao što su neispravno uvlačenje, kršenja duljine retka i neiskorišteni uvozi.
• Otkrivanje sintaktičkih pogrešaka: Flake8 otkriva sintaktičke pogreške u vašem kodu, pomažući vam da rano uhvatite potencijalne greške.
• Analiza složenosti koda: Flake8 koristi mccabe za izračunavanje ciklometrijske složenosti vašeg koda, identificirajući potencijalno složene i teško održive funkcije.
• Proširivost: Flake8 podržava širok raspon dodataka (pluginova), omogućujući vam da prilagodite njegovo ponašanje i dodate podršku za dodatne provjere.

Instalacija alata Flake8

Flake8 možete instalirati pomoću pip-a:

            pip install flake8
            

              
                Copy
              
            
          

Korištenje alata Flake8

Da biste provjerili Python datoteku s alatom Flake8, jednostavno pokrenite sljedeću naredbu:

            flake8 my_file.py
            

              
                Copy
              
            
          

Flake8 će ispisati popis svih stilskih pogrešaka, sintaktičkih pogrešaka ili problema sa složenošću koda koje pronađe u datoteci. Da biste provjerili cijeli direktorij, pokrenite:

            flake8 my_directory
            

              
                Copy
              
            
          

Primjer: Identificiranje stilskih pogrešaka s alatom Flake8

Razmotrite sljedeći Python kod:

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

              
                Copy
              
            
          

Pokretanje alata Flake8 na ovom kodu proizvest će sljedeći izlaz:

            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 je identificirao nekoliko stilskih pogrešaka, uključujući nedostatak praznih redaka, nedostatak razmaka nakon zareza, neispravno uvlačenje i nedostatak razmaka oko operatora. Ove pogreške treba ispraviti kako bi se poboljšala čitljivost koda i pridržavanje PEP 8.

Konfiguriranje alata Flake8

Flake8 se može konfigurirati pomoću datoteke .flake8 u korijenu vašeg repozitorija. Ova datoteka vam omogućuje da navedete koje provjere omogućiti ili onemogućiti, postavite maksimalnu duljinu retka i konfigurirate druge postavke.

Evo primjera datoteke .flake8:

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

              
                Copy
              
            
          

U ovom primjeru, maksimalna duljina retka postavljena je na 120 znakova, a provjere E203 i W503 su onemogućene. E203 se odnosi na razmak prije ':' i često se smatra stilskom preferencijom koju Black ionako rješava. W503 se odnosi na prijelome redaka prije binarnih operatora, što Black također rješava.

Integracija alata Flake8 s Pre-commitom

Da biste integrirali Flake8 s pre-commitom, dodajte sljedeće u svoju datoteku .pre-commit-config.yaml:

            -   repo: https://github.com/pycqa/flake8
    rev: 6.1.0 # Zamijenite najnovijom verzijom
    hooks:
    -   id: flake8
            

              
                Copy
              
            
          

Sada, svaki put kada predate kod, pre-commit će pokrenuti Flake8 kako bi provjerio stilske pogreške. Ako Flake8 pronađe bilo kakve pogreške, commit će biti prekinut, a vi ćete morati ispraviti pogreške i ponovno napraviti commit.

Predstavljamo mypy: Statički provjeravač tipova

mypy je statički provjeravač tipova za Python koji vam pomaže uhvatiti pogreške u tipovima prije izvođenja. Python je dinamički tipiziran jezik, što znači da se tip varijable provjerava tek pri izvođenju. To može dovesti do neočekivanih pogrešaka i grešaka. mypy vam omogućuje dodavanje napomena o tipovima (type hints) u vaš kod, omogućujući statičku provjeru tipova i poboljšavajući pouzdanost vaših aplikacija.

Ključne značajke alata mypy

• Statička provjera tipova: mypy provjerava tipove varijabli, argumenata funkcija i povratnih vrijednosti u vrijeme kompajliranja, hvatajući potencijalne pogreške u tipovima prije izvođenja.
• Napomene o tipovima: mypy koristi napomene o tipovima (type hints), koje su anotacije koje specificiraju očekivani tip varijable ili funkcije.
• Postupno tipiziranje: mypy podržava postupno tipiziranje (gradual typing), što znači da možete postupno dodavati napomene o tipovima u svoj kod, bez potrebe da odjednom provjeravate tipove u cijeloj kodnoj bazi.
• Integracija s uređivačima: mypy se besprijekorno integrira s popularnim uređivačima koda poput VS Code i PyCharm.

Instalacija alata mypy

mypy možete instalirati pomoću pip-a:

            pip install mypy
            

              
                Copy
              
            
          

Korištenje alata mypy

Da biste provjerili Python datoteku s alatom mypy, jednostavno pokrenite sljedeću naredbu:

            mypy my_file.py
            

              
                Copy
              
            
          

mypy će ispisati popis svih pogrešaka u tipovima koje pronađe u datoteci. Da biste provjerili cijeli direktorij, pokrenite:

            mypy my_directory
            

              
                Copy
              
            
          

Primjer: Dodavanje napomena o tipovima i otkrivanje pogrešaka u tipovima

Razmotrite sljedeći Python kod:

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

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

              
                Copy
              
            
          

Ovaj kod će se izvršiti bez pogrešaka, ali će proizvesti neočekivane rezultate jer zbraja cijeli broj i string. Da biste uhvatili ovu pogrešku u tipu, možete dodati napomene o tipovima u funkciju add:

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

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

              
                Copy
              
            
          

Sada, kada pokrenete mypy, ispisat će sljedeću pogrešku:

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

              
                Copy
              
            
          

mypy je otkrio da prosljeđujete string funkciji add, koja očekuje cijeli broj. To vam omogućuje da uhvatite pogrešku prije izvođenja i spriječite neočekivano ponašanje.

Konfiguriranje alata mypy

mypy se može konfigurirati pomoću datoteke mypy.ini ili pyproject.toml u korijenu vašeg repozitorija. Ova datoteka vam omogućuje da navedete koje provjere omogućiti ili onemogućiti, postavite verziju Pythona i konfigurirate druge postavke. Korištenje pyproject.toml je moderni preporučeni pristup.

Evo primjera datoteke pyproject.toml:

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

              
                Copy
              
            
          

U ovom primjeru, verzija Pythona postavljena je na 3.11, a strogi način (strict mode) je omogućen. Strogi način omogućuje sve najstrože provjere mypy-a, pomažući vam da uhvatite još više potencijalnih pogrešaka u tipovima.

Integracija alata mypy s Pre-commitom

Da biste integrirali mypy s pre-commitom, dodajte sljedeće u svoju datoteku .pre-commit-config.yaml:

            -   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.6.1 # Zamijenite najnovijom verzijom
    hooks:
    -   id: mypy
            

              
                Copy
              
            
          

Sada, svaki put kada predate kod, pre-commit će pokrenuti mypy kako bi provjerio pogreške u tipovima. Ako mypy pronađe bilo kakve pogreške, commit će biti prekinut, a vi ćete morati ispraviti pogreške i ponovno napraviti commit.

Sve zajedno: Potpuni primjer integracije

Da bismo demonstrirali snagu integracije alata Black, Flake8 i mypy, prođimo kroz potpuni primjer. Razmotrite sljedeći Python kod:

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

              
                Copy
              
            
          

Ovaj kod ima nekoliko problema:

• Nije formatiran prema PEP 8.
• Nedostaju mu napomene o tipovima.
• Koristi potencijalno zbunjujuće ime varijable (sum).
• Ne obrađuje slučaj kada je ulazna lista prazna (dijeljenje s nulom).

Prvo, pokrenite Black da formatirate kod:

            black my_file.py
            

              
                Copy
              
            
          

Black će preformatirati kod u:

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

              
                Copy
              
            
          

Zatim, pokrenite Flake8 da provjerite stilske pogreške:

            flake8 my_file.py
            

              
                Copy
              
            
          

Flake8 će ispisati sljedeće pogreške:

            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
              
            
          

Ispravljanjem pogrešaka koje je prijavio Flake8 (imajte na umu da će se ovaj specifični izlaz razlikovati ovisno o vašoj konfiguraciji flake8) i dodavanjem napomena o tipovima, kod postaje:

            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  # Avoid division by zero
    total = sum(numbers)
    return total / len(numbers)
            

              
                Copy
              
            
          

Konačno, pokrenite mypy da provjerite pogreške u tipovima:

            mypy my_file.py
            

              
                Copy
              
            
          

Ako nema pogrešaka u tipovima, mypy neće ništa ispisati. U ovom slučaju, provjera prolazi. Kod je sada formatiran prema PEP 8, ima napomene o tipovima, koristi deskriptivnija imena varijabli i obrađuje slučaj kada je ulazna lista prazna. Ovo pokazuje kako Black, Flake8 i mypy mogu raditi zajedno kako bi poboljšali kvalitetu i pouzdanost vašeg Python koda.

Praktični uvidi i najbolje prakse

• Počnite rano: Integrirajte Black, Flake8 i mypy u svoj razvojni tijek rada od samog početka vaših projekata. To će vam pomoći da održite dosljedan stil koda i rano uhvatite potencijalne pogreške.
• Konfigurirajte svoje alate: Prilagodite Black, Flake8 i mypy svojim specifičnim potrebama i preferencijama. Koristite konfiguracijske datoteke da navedete koje provjere omogućiti ili onemogućiti, postavite maksimalnu duljinu retka i konfigurirate druge postavke.
• Koristite Pre-commit hookove: Integrirajte Black, Flake8 i mypy s pre-commitom kako biste osigurali da je sav kod koji se predaje u vaš repozitorij ispravno formatiran i provjeren na tipove.
• Automatizirajte svoj tijek rada: Koristite CI/CD cjevovode za automatsko pokretanje alata Black, Flake8 i mypy na svakom commitu. To će vam pomoći da uhvatite probleme s kvalitetom koda prije nego što stignu u produkciju. Usluge poput GitHub Actions, GitLab CI i Jenkins mogu se konfigurirati za automatsko pokretanje ovih provjera.
• Educirajte svoj tim: Osigurajte da su svi članovi tima upoznati s alatima Black, Flake8 i mypy i da razumiju kako ih učinkovito koristiti. Pružite obuku i dokumentaciju kako biste pomogli svom timu da usvoji ove alate i održava dosljedan stil koda.
• Prihvatite postupno tipiziranje: Ako radite na velikoj, postojećoj kodnoj bazi, razmislite o usvajanju postupnog tipiziranja. Počnite dodavanjem napomena o tipovima u najkritičnije dijelove vašeg koda i postupno proširujte pokrivenost tijekom vremena.

Zaključak

Ulaganje u kvalitetu koda je ulaganje u dugoročni uspjeh vaših projekata. Integracijom alata Black, Flake8 i mypy u svoj razvojni tijek rada, možete značajno poboljšati čitljivost, održivost i pouzdanost vašeg Python koda. Ovi alati su neophodni za svakog ozbiljnog Python programera, bez obzira na njihovu lokaciju ili prirodu njihovih projekata. Od startupa u Silicijskoj dolini do etabliranih poduzeća u Singapuru, prihvaćanje ovih najboljih praksi nedvojbeno će dovesti do učinkovitijeg i djelotvornijeg razvoja softvera.

Ne zaboravite prilagoditi ove smjernice i alate svom specifičnom kontekstu. Eksperimentirajte s različitim konfiguracijama, istražite dostupne dodatke i prilagodite svoj tijek rada kako bi zadovoljio jedinstvene potrebe vašeg tima i vaših projekata. Kontinuiranim težnjom za višom kvalitetom koda, bit ćete dobro pozicionirani za izgradnju robusnih, skalabilnih i održivih aplikacija koje pružaju vrijednost vašim korisnicima godinama koje dolaze.