trace — Spåra utförandet av Python-satser

Källkod: Lib/trace.py

Med modulen trace kan du spåra programkörning, generera annoterade listor över utsagornas täckning, skriva ut relationer mellan uppringare och nedringare och lista funktioner som körts under en programkörning. Den kan användas i ett annat program eller från kommandoraden.

Se även

Coverage.py

Ett populärt tredjepartsverktyg för täckning som ger HTML-utdata tillsammans med avancerade funktioner som t.ex. täckning av grenar.

Användning av kommandoraden

Modulen trace kan anropas från kommandoraden. Det kan vara så enkelt som

python -m trace --count -C . somefile.py ...

Ovanstående kommer att exekvera somefile.py och generera annoterade listor över alla Python-moduler som importerats under exekveringen till den aktuella katalogen.

--help

Visa användning och avsluta.

--version

Visa modulens version och avsluta.

Tillagd i version 3.8: Lagt till alternativet --module som gör det möjligt att köra en körbar modul.

Huvudalternativ

Minst ett av följande alternativ måste anges när trace anropas. Alternativet --listfuncs är ömsesidigt uteslutande med alternativen --trace och --count. När --listfuncs anges accepteras varken --count eller --trace, och vice versa.

-c, --count

Producera en uppsättning annoterade listningsfiler när programmet är klart som visar hur många gånger varje sats kördes. Se även --coverdir, --file och --no-report nedan.

-t, --trace

Visa raderna när de utförs.

-l, --listfuncs

Visa de funktioner som utförs när programmet körs.

-r, --report

Producera en annoterad lista från en tidigare programkörning som använde alternativen --count och --file. Detta exekverar inte någon kod.

-T, --trackcalls

Visa de anropsrelationer som visas när programmet körs.

Modifierare

-f, --file=<file>

Namn på en fil för att ackumulera räkningar över flera spårningskörningar. Bör användas med alternativet --count.

-C, --coverdir=<dir>

Katalog där rapportfilerna sparas. Täckningsrapporten för package.module skrivs till filen dir/package/module.cover.

-m, --missing

When generating annotated listings, mark lines which were not executed with >>>>>>.

-s, --summary

När du använder --count eller --report, skriv en kort sammanfattning till stdout för varje fil som bearbetas.

-R, --no-report

Generera inte annoterade listor. Detta är användbart om du tänker göra flera körningar med --count, och sedan producera en enda uppsättning annoterade listor i slutet.

-g, --timing

Varje rad inleds med tiden sedan programmet startade. Används endast under spårning.

Filter

Dessa alternativ kan upprepas flera gånger.

--ignore-module=<mod>

Ignorerar alla de angivna modulnamnen och dess undermoduler (om det är ett paket). Argumentet kan vara en lista med namn åtskilda av ett kommatecken.

--ignore-dir=<dir>

Ignorera alla moduler och paket i den angivna katalogen och dess underkataloger. Argumentet kan vara en lista med kataloger åtskilda av os.pathsep.

Programmatiskt gränssnitt

class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

Skapa ett objekt för att spåra exekveringen av en enda sats eller ett uttryck. Alla parametrar är valfria. count aktiverar räkning av radnummer. trace aktiverar spårning av linjeexekvering. countfuncs aktiverar listning av de funktioner som anropas under körningen. countcallers aktiverar spårning av anropsrelationer. ignoremods är en lista över moduler eller paket som ska ignoreras. ignoredirs är en lista över kataloger vars moduler eller paket ska ignoreras. infile är namnet på den fil från vilken lagrad räkneinformation ska läsas. outfile är namnet på den fil i vilken uppdaterad räkneinformation ska skrivas. timing gör att en tidsstämpel i förhållande till när spårningen startade kan visas.

run(cmd)

Utför kommandot och samla in statistik från utförandet med de aktuella spårningsparametrarna. cmd måste vara en sträng eller ett kodobjekt, lämpligt att skicka till exec().

runctx(cmd, globals=None, locals=None)

Utför kommandot och samla in statistik från utförandet med de aktuella spårningsparametrarna i de definierade globala och lokala miljöerna. Om de inte definieras är globals och locals tomma ordböcker som standard.

runfunc(func, /, *args, **kwds)

Anropa func med de angivna argumenten under kontroll av Trace-objektet med de aktuella spårningsparametrarna.

results()

Returnerar ett CoverageResults-objekt som innehåller de ackumulerade resultaten av alla tidigare anrop till run, runctx och runfunc för den givna Trace-instansen. Återställer inte de ackumulerade spårningsresultaten.

class trace.CoverageResults

En behållare för täckningsresultat, skapad av Trace.results(). Bör inte skapas direkt av användaren.

update(other)

Sammanfoga data från ett annat CoverageResults-objekt.

write_results(show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)

Skriv täckningsresultat. Ange show_missing för att visa rader som inte hade några träffar. Ange summary för att inkludera täckningssammanfattningen per modul i utdata. coverdir anger den katalog där filerna med täckningsresultat ska skrivas ut. Om None placeras resultaten för varje källfil i dess katalog.

Om ignore_missing_files är True ignoreras täckningsräkningar för filer som inte längre finns. Annars kommer en saknad fil att ge upphov till ett FileNotFoundError.

Ändrad i version 3.13: Lagt till parametern ignore_missing_files.

Ett enkelt exempel som visar användningen av det programmatiska gränssnittet:

import sys
import trace

# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# run the new command using the given tracer
tracer.run('main()')

# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")