Kodkvalitet i Python: Bemästra integrationen av Black, Flake8 och mypy

Inom mjukvaruutveckling är att skriva fungerande kod bara halva jobbet. Att upprätthålla en konsekvent stil, följa bästa praxis och säkerställa typsäkerhet är lika avgörande för att skapa robusta, underhållbara och samarbetsvänliga projekt. Python, känt för sin läsbarhet, har stor nytta av verktyg som automatiserar dessa aspekter. Denna omfattande guide utforskar integrationen av tre kraftfulla verktyg: Black, Flake8 och mypy, för att lyfta din Python-kodkvalitet till nästa nivå.

Varför kodkvalitet är viktigt

Innan vi dyker in i detaljerna för varje verktyg, låt oss förstå varför kodkvalitet är av yttersta vikt:

• Läsbarhet: En konsekvent kodstil gör det enklare för utvecklare att förstå och ändra koden.
• Underhåll: Välformaterad och typkontrollerad kod minskar risken för buggar och förenklar felsökning.
• Samarbete: Delade kodstilar säkerställer att alla teammedlemmar skriver kod på ett enhetligt sätt, vilket främjar ett smidigt samarbete.
• Minskad teknisk skuld: Att åtgärda kodkvalitetsproblem tidigt förhindrar ackumulering av teknisk skuld, vilket sparar tid och resurser i det långa loppet.
• Förbättrad tillförlitlighet: Statisk typkontroll fångar potentiella fel före körtid, vilket förbättrar den övergripande tillförlitligheten hos dina applikationer.

Dessa fördelar är inte begränsade till specifika branscher eller regioner. Oavsett om du utvecklar en webbapplikation i Berlin, ett datavetenskapsprojekt i Bangalore eller en mobilapp i Mexico City, kommer en konsekvent kodkvalitet utan tvekan att förbättra ditt utvecklingsflöde.

Introduktion till Black: Den kompromisslösa kodformateraren

Black är en kodformaterare för Python som automatiskt omformaterar din kod för att följa en konsekvent stil. Den är "opinionated", vilket innebär att den fattar beslut åt dig om hur koden ska formateras, vilket minimerar diskussioner om stil och låter utvecklare fokusera på funktionalitet.

Nyckelfunktioner i Black

• Automatisk formatering: Black omformaterar automatiskt din kod enligt sin fördefinierade stilguide (baserad på PEP 8).
• Kompromisslös: Black lämnar lite utrymme för anpassning och upprätthåller en konsekvent stil över hela din kodbas.
• Integration med editorer: Black integreras sömlöst med populära kod-editorer som VS Code, PyCharm och Sublime Text.
• Pre-commit hook: Black kan användas som en pre-commit hook för att säkerställa att all kod som committas till ditt repository är korrekt formaterad.

Installera Black

Du kan installera Black med pip:

            pip install black
            

              
                Copy
              
            
          

Använda Black

För att formatera en Python-fil med Black, kör helt enkelt följande kommando:

            black my_file.py
            

              
                Copy
              
            
          

Black kommer att omformatera filen på plats, i enlighet med sina fördefinierade stilregler. För att formatera en hel katalog, kör:

            black my_directory
            

              
                Copy
              
            
          

Exempel: Formatering med Black

Tänk på följande dåligt formaterade 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
              
            
          

Efter att ha kört Black kommer koden automatiskt att omformateras till:

            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
              
            
          

Märk hur Black automatiskt har justerat mellanrum, radbrytningar och indentering för att följa sin stilguide.

Integrera Black med Pre-commit

Pre-commit är ett verktyg som låter dig köra kontroller på din kod innan du committar den till ditt repository. Att integrera Black med pre-commit säkerställer att all committad kod är korrekt formaterad.

1. Installera pre-commit:

            pip install pre-commit
            

              
                Copy
              
            
          

2. Skapa en .pre-commit-config.yaml-fil i roten av ditt repository:

            repos:
-   repo: https://github.com/psf/black
    rev: 23.12.1  # Replace with the latest version
    hooks:
    -   id: black
            

              
                Copy
              
            
          

3. Installera pre-commit-hooks:

            pre-commit install
            

              
                Copy
              
            
          

Nu, varje gång du committar kod, kommer pre-commit att köra Black för att formatera dina filer. Om Black gör ändringar kommer committen att avbrytas, och du måste stage:a ändringarna och committa igen.

Introduktion till Flake8: Kodstilsgranskaren

Flake8 är en "wrapper" runt flera populära Python linting-verktyg, inklusive pycodestyle (tidigare pep8), pyflakes och mccabe. Den kontrollerar din kod för stilfel, syntaxfel och problem med kodkomplexitet, vilket hjälper dig att följa PEP 8-stilguiden och skriva renare, mer underhållbar kod.

Nyckelfunktioner i Flake8

• Upptäckt av stilfel: Flake8 identifierar överträdelser av PEP 8-stilguiden, som felaktig indentering, överträdelser av radlängd och oanvända importer.
• Upptäckt av syntaxfel: Flake8 upptäcker syntaxfel i din kod, vilket hjälper dig att fånga potentiella buggar tidigt.
• Kodkomplexitetsanalys: Flake8 använder mccabe för att beräkna den cyklomatiska komplexiteten i din kod, och identifierar potentiellt komplexa och svårunderhållna funktioner.
• Utbyggbarhet: Flake8 stöder ett brett utbud av plugins, vilket gör att du kan anpassa dess beteende och lägga till stöd för ytterligare kontroller.

Installera Flake8

Du kan installera Flake8 med pip:

            pip install flake8
            

              
                Copy
              
            
          

Använda Flake8

För att kontrollera en Python-fil med Flake8, kör helt enkelt följande kommando:

            flake8 my_file.py
            

              
                Copy
              
            
          

Flake8 kommer att mata ut en lista över eventuella stilfel, syntaxfel eller kodkomplexitetsproblem den hittar i filen. För att kontrollera en hel katalog, kör:

            flake8 my_directory
            

              
                Copy
              
            
          

Exempel: Identifiera stilfel med Flake8

Tänk på följande Python-kod:

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

              
                Copy
              
            
          

Att köra Flake8 på denna kod kommer att producera följande utdata:

            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 har identifierat flera stilfel, inklusive saknade tomma rader, saknat blanksteg efter ett kommatecken, felaktig indentering och saknat blanksteg runt en operator. Dessa fel bör åtgärdas för att förbättra kodens läsbarhet och efterlevnad av PEP 8.

Konfigurera Flake8

Flake8 kan konfigureras med en .flake8-fil i roten av ditt repository. Denna fil låter dig specificera vilka kontroller som ska aktiveras eller inaktiveras, ställa in maximal radlängd och konfigurera andra inställningar.

Här är ett exempel på en .flake8-fil:

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

              
                Copy
              
            
          

I detta exempel är den maximala radlängden satt till 120 tecken, och kontrollerna E203 och W503 är inaktiverade. E203 avser blanksteg före ':' och anses ofta vara en stilpreferens som Black ändå hanterar. W503 avser radbrytningar före binära operatorer, vilket Black också adresserar.

Integrera Flake8 med Pre-commit

För att integrera Flake8 med pre-commit, lägg till följande i din .pre-commit-config.yaml-fil:

            -   repo: https://github.com/pycqa/flake8
    rev: 6.1.0 # Replace with the latest version
    hooks:
    -   id: flake8
            

              
                Copy
              
            
          

Nu, varje gång du committar kod, kommer pre-commit att köra Flake8 för att kontrollera efter stilfel. Om Flake8 hittar några fel kommer committen att avbrytas, och du måste åtgärda felen och committa igen.

Introduktion till mypy: Den statiska typkontrollanten

mypy är en statisk typkontrollant för Python som hjälper dig att fånga typfel före körtid. Python är ett dynamiskt typat språk, vilket innebär att typen av en variabel inte kontrolleras förrän vid körtid. Detta kan leda till oväntade fel och buggar. mypy låter dig lägga till typ-ledtrådar (type hints) till din kod, vilket möjliggör statisk typkontroll och förbättrar tillförlitligheten hos dina applikationer.

Nyckelfunktioner i mypy

• Statisk typkontroll: mypy kontrollerar typerna av variabler, funktionsargument och returvärden vid kompileringstid, och fångar potentiella typfel före körtid.
• Typ-ledtrådar (Type Hints): mypy använder typ-ledtrådar, vilka är annotationer som specificerar den förväntade typen av en variabel eller funktion.
• Gradvis typning: mypy stöder gradvis typning, vilket innebär att du kan lägga till typ-ledtrådar till din kod inkrementellt, utan att behöva typkontrollera hela din kodbas på en gång.
• Integration med editorer: mypy integreras sömlöst med populära kod-editorer som VS Code och PyCharm.

Installera mypy

Du kan installera mypy med pip:

            pip install mypy
            

              
                Copy
              
            
          

Använda mypy

För att kontrollera en Python-fil med mypy, kör helt enkelt följande kommando:

            mypy my_file.py
            

              
                Copy
              
            
          

mypy kommer att mata ut en lista över eventuella typfel den hittar i filen. För att kontrollera en hel katalog, kör:

            mypy my_directory
            

              
                Copy
              
            
          

Exempel: Lägga till typ-ledtrådar och upptäcka typfel

Tänk på följande Python-kod:

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

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

              
                Copy
              
            
          

Denna kod kommer att köras utan fel, men den kommer att producera oväntade resultat eftersom den adderar ett heltal och en sträng. För att fånga detta typfel kan du lägga till typ-ledtrådar till add-funktionen:

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

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

              
                Copy
              
            
          

Nu, när du kör mypy, kommer den att mata ut följande fel:

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

              
                Copy
              
            
          

mypy har upptäckt att du skickar en sträng till add-funktionen, som förväntar sig ett heltal. Detta låter dig fånga felet före körtid och förhindra oväntat beteende.

Konfigurera mypy

mypy kan konfigureras med en mypy.ini- eller pyproject.toml-fil i roten av ditt repository. Denna fil låter dig specificera vilka kontroller som ska aktiveras eller inaktiveras, ställa in Python-versionen och konfigurera andra inställningar. Att använda pyproject.toml är det moderna rekommenderade tillvägagångssättet.

Här är ett exempel på en pyproject.toml-fil:

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

              
                Copy
              
            
          

I detta exempel är Python-versionen satt till 3.11, och strikt läge är aktiverat. Strikt läge aktiverar alla mypys strängaste kontroller, vilket hjälper dig att fånga ännu fler potentiella typfel.

Integrera mypy med Pre-commit

För att integrera mypy med pre-commit, lägg till följande i din .pre-commit-config.yaml-fil:

            -   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.6.1 # Replace with the latest version
    hooks:
    -   id: mypy
            

              
                Copy
              
            
          

Nu, varje gång du committar kod, kommer pre-commit att köra mypy för att kontrollera efter typfel. Om mypy hittar några fel kommer committen att avbrytas, och du måste åtgärda felen och committa igen.

Att sätta ihop allt: Ett komplett integrationsexempel

För att demonstrera kraften i att integrera Black, Flake8 och mypy, låt oss gå igenom ett komplett exempel. Tänk på följande Python-kod:

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

              
                Copy
              
            
          

Denna kod har flera problem:

• Den är inte formaterad enligt PEP 8.
• Den saknar typ-ledtrådar.
• Den använder ett potentiellt förvirrande variabelnamn (sum).
• Den hanterar inte fallet där inmatningslistan är tom (division med noll).

Först, kör Black för att formatera koden:

            black my_file.py
            

              
                Copy
              
            
          

Black kommer att omformatera koden till:

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

              
                Copy
              
            
          

Sedan, kör Flake8 för att kontrollera efter stilfel:

            flake8 my_file.py
            

              
                Copy
              
            
          

Flake8 kommer att mata ut följande fel:

            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
              
            
          

Efter att ha åtgärdat Flake8-felen (notera att denna specifika felutmatning kan variera beroende på din flake8-konfiguration) och lagt till typ-ledtrådar, blir koden:

            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
              
            
          

Slutligen, kör mypy för att kontrollera efter typfel:

            mypy my_file.py
            

              
                Copy
              
            
          

Om det inte finns några typfel kommer mypy inte att mata ut någonting. I det här fallet godkänns den. Koden är nu formaterad enligt PEP 8, har typ-ledtrådar, använder mer beskrivande variabelnamn och hanterar fallet där inmatningslistan är tom. Detta demonstrerar hur Black, Flake8 och mypy kan arbeta tillsammans för att förbättra kvaliteten och tillförlitligheten hos din Python-kod.

Praktiska insikter och bästa praxis

• Börja tidigt: Integrera Black, Flake8 och mypy i ditt utvecklingsflöde från början av dina projekt. Detta hjälper dig att upprätthålla en konsekvent kodstil och fånga potentiella fel tidigt.
• Konfigurera dina verktyg: Anpassa Black, Flake8 och mypy för att passa dina specifika behov och preferenser. Använd konfigurationsfiler för att specificera vilka kontroller som ska aktiveras eller inaktiveras, ställa in maximal radlängd och konfigurera andra inställningar.
• Använd Pre-commit Hooks: Integrera Black, Flake8 och mypy med pre-commit för att säkerställa att all kod som committas till ditt repository är korrekt formaterad och typkontrollerad.
• Automatisera ditt arbetsflöde: Använd CI/CD-pipelines för att automatiskt köra Black, Flake8 och mypy vid varje commit. Detta hjälper dig att fånga problem med kodkvalitet innan de når produktion. Tjänster som GitHub Actions, GitLab CI och Jenkins kan konfigureras för att köra dessa kontroller automatiskt.
• Utbilda ditt team: Se till att alla teammedlemmar är bekanta med Black, Flake8 och mypy och förstår hur man använder dem effektivt. Tillhandahåll utbildning och dokumentation för att hjälpa ditt team att anamma dessa verktyg och upprätthålla en konsekvent kodstil.
• Anamma gradvis typning: Om du arbetar med en stor, befintlig kodbas, överväg att anamma gradvis typning. Börja med att lägga till typ-ledtrådar till de mest kritiska delarna av din kod och utöka gradvis täckningen över tid.

Slutsats

Att investera i kodkvalitet är en investering i dina projekts långsiktiga framgång. Genom att integrera Black, Flake8 och mypy i ditt utvecklingsflöde kan du avsevärt förbättra läsbarheten, underhållet och tillförlitligheten hos din Python-kod. Dessa verktyg är väsentliga för alla seriösa Python-utvecklare, oavsett deras plats eller typen av deras projekt. Från startups i Silicon Valley till etablerade företag i Singapore, att anamma dessa bästa praxis kommer utan tvekan att leda till effektivare och mer ändamålsenlig mjukvaruutveckling.

Kom ihåg att anpassa dessa riktlinjer och verktyg till ditt specifika sammanhang. Experimentera med olika konfigurationer, utforska tillgängliga plugins och skräddarsy ditt arbetsflöde för att möta de unika behoven hos ditt team och dina projekt. Genom att kontinuerligt sträva efter högre kodkvalitet kommer du att vara väl positionerad för att bygga robusta, skalbara och underhållbara applikationer som levererar värde till dina användare i många år framöver.