trace — Ιχνηλάτηση ή παρακολούθηση εκτέλεσης εντολών Python

Source code: Lib/trace.py

---

Το module trace σας επιτρέπει να ιχνηλατήσετε την εκτέλεση ενός προγράμματος, να παράγετε αρχεία κάλυψης με σημειωμένες δηλώσεις , να εκτυπώσετε σχέσεις κλήσεων και να αριθμήσετε τις συναρτήσεις που καλούνται κατά την εκτέλεση ενός προγράμματος. Μπορεί να χρησιμοποιηθεί σε κάποιο πρόγραμμα ή μέσω της γραμμής εντολών.

Δείτε επίσης

Coverage.py

Ένα δημοφιλές εργαλείο (διανέμεται από τρίτους) που παράγει αποτελέσματα σε HTML και διαθέτει ανεπτυγμένες δυνατότητες όπως branch coverage.

Οδηγίες χρήσης γραμμής εντολών

Το module trace μπορεί να κληθεί και από τη γραμμή εντολών , απλώς ως εξής

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

Το παραπάνω θα εκτελέσει το αρχείο somefile.py και θα παράγει μια σημειωμένη λίστα με όλα τα Python modules που εισήχθησαν κατά την εκτέλεση στον τρέχων φάκελο.

--help

Εμφανίζει τις οδηγίες χρήσης και τερματίζει την εκτέλεση.

--version

Εμφανίζει την έκδοση του module και τερματίζει την εκτέλεση.

Added in version 3.8: Προσετέθη η επιλογή --module που επιτρέπει την εκτέλεση ενός εκτελέσιμου module.

Κύριες επιλογές

Τουλάχιστον μία από τις ακόλουθες επιλογές πρέπει να προσδιορισθεί όταν καλείται η trace. Η επιλογή --listfunc είναι αμοιβαίως αποκλειόμενη με την επιλογή --trace και την επιλογή --count. Όταν δίνεται η επιλογή --listfuncs δεν γίνονται αποδεκτές οι επιλογές --count <-c> ή --trace και το αντίστροφο.

-c, --count

Κατά την ολοκλήρωση του προγράμματος δημιουργεί ένα σύνολο από σημειωμένα αρχεία όπου φαίνεται πόσες φορές εκτελέσθηκε κάθε έκφραση. Βλέπε επίσης --coverdir, --file και --no-report παρακάτω.

-t, --trace

Εμφανίζει τις γραμμές όπως εκτελούνται.

-l, --listfuncs

Εμφανίζει τις συναρτήσεις που εκτελούνται τρέχοντας το πρόγραμμα.

-r, --report

Παράγει μία σημειωμένη λίστα από την πρότερη εκτέλεση ενός προγράμματος που χρησιμοποίησε την επιλογή --count και --file. Δεν εκτελείται κάποιος κώδικας με την παρούσα επιλογή.

-T, --trackcalls

Εμφανίζει τις σχέσεις κλήσεων που δημιουργούνται εκτελώντας το πρόγραμμα.

Τροποποιητές

-f, --file=<file>

Όνομα αρχείου όπου σωρεύονται οι μετρήσεις πολλαπλών ιχνηλατήσεων. Πρέπει να χρησιμοποιείται με την επιλογή --count.

-C, --coverdir=<dir>

Κατάλογος όπου αποθηκεύονται τα αρχεία αναφοράς. Η αναφορά κάλυψης (coverage report) για το package.module εγγράφεται στο αρχείο dir/package/module.cover.

-m, --missing

Κατά την παραγωγή σημειωμένων λιστών, σημειώνει τις γραμμές που δεν εκτελέστηκαν με >>>>>>.

-s, --summary

Κατά την χρήση της επιλογής --count ή της επιλογής --report, γράφει μία σύντομη περίληψη για κάθε αρχείο που επεξεργάζεται.

-R, --no-report

Δεν δημιουργεί σημειωμένες λίστες. Αυτή η επιλογή είναι χρήσιμη εάν σκοπεύετε να κάνετε πολλές εκτελέσεις με την επιλογή --count και τελικώς δημιουργήσετε ένα ενιαίο σύνολο σημειωμένων λιστών.

-g, --timing

Προθεμάτιζει κάθε γραμμή με τον χρόνο που παρήλθε από την εκκίνηση του προγράμματος. Χρησιμοποιείται μόνο κατά την ιχνηλάτηση.

Φίλτρα

Αυτές οι επιλογές μπορούν να επαναληφθούν πολλαπλές φορές.

--ignore-module=<mod>

Αγνόησε κάθε ένα από τα δεδομένα modules και submodules (εάν είναι πακέτο). Το όρισμα μπορεί να είναι μία λίστα από ονόματα διαχωρισμένα με κόμμα.

--ignore-dir=<dir>

Αγνοεί όλα τα modules και πακέτα στους δεδομένους φακέλους και υποφακέλους. Το όρισμα μπορεί να είναι μία λίστα από φάκελους που χωρίζονται με os.pathsep.

Προγραμματιστική διεπαφή

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

Δημιουργεί ένα αντικείμενο για την ιχνηλάτηση της εκτέλεσης μίας μόνο εντολής ή έκφρασης. Όλες οι παράμετροι είναι προαιρετικές. Η count επιτρέπει την αρίθμηση των γραμμών. Η trace επιτρέπει την ιχνηλάτηση εκτελέσεων ανά γραμμή. Η countfuncs επιτρέπει την αρίθμηση των συναρτήσεων που εκλήθησαν κατά την εκτέλεση. Η countcallers επιτρέπει την ιχνηλάτηση συσχετισμένων κλήσεων. Η ignoremods είναι μία λίστα με modules ή πακέτα προς παράβλεψη. Η ignoredirs είναι μία λίστα φακέλων με προς παράβλεψη modules ή πακέτα. Η infile είναι το όνομα του αρχείου εκ του οποίου θα ληφθούν αποθηκευμένα αποτελέσματα ιχνηλατήσεων. Η outfile είναι το όνομα του αρχείου εις το οποίο θα εγγραφούν τα νεώτερα αποτελέσματα ιχνηλάτησης. Η timing ενεργοποιεί μία χρονοσφραγίδα σχετική με την έναρξη της εμφάνισης ιχνηλάτησης.

run(cmd)

Εκτελεί την εντολή και συλλέγει στατιστικά από την εκτέλεση με τις τρέχουσες επιλογές ιχνηλάτησης. Η cmd πρέπει να είναι μία συμβολοσειρά ή αντικείμενο κώδικα, κατάλληλο για διαβίβαση στην συνάρτηση exec().

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

Εκτελεί την εντολή και συλλέγει στατιστικά από την εκτέλεση με τις τρέχουσες επιλογές ιχνηλάτησης, στο ορισμένο καθολικό και τοπικό περιβάλλον. Εάν δεν ορισθούν, οι globals και locals λαμβάνουν την τιμή κενού dictionary.

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

Καλεί την func με τα δεδομένα ορίσματα υπό τον έλεγχο του αντικειμένου Trace με τις τρέχουσες επιλογές ιχνηλάτησης.

results()

Επιστρέφει ένα αντικείμενο CoverageResults που περιέχει τα σωρευτικά αποτελέσματα όλων των προηγούμενων κλήσεων στις run, runctx και runfunc για το δοθέν Trace στιγμιότυπο. Δεν επαναφέρει τα συσσωρευμένα αποτελέσματα ιχνηλατήσεων.

class trace.CoverageResults

Ένας περιέκτης για αποτελέσματα κάλυψης (coverage results), που δημιουργείται από τη Trace.results(). Δεν πρέπει να δημιουργείται απευθείας από τον χρήστη.

update(other)

Συγχωνεύει δεδομένα από ένα άλλο αντικείμενο CoveragaResults.

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

Γράφει τα αποτελέσματα κάλυψης. Ορίστε την show_missing για να εμφανίζονται οι γραμμές που δεν εκτελέσθηκαν. Ορίστε την summary ώστε να συμπεριληφθεί στο αποτέλεσμα η περίληψη κάλυψης ανά module. Η coverdir προσδιορίζει τον φάκελο εις τον οποίο θα εγγραφούν τα αρχεία με τα αποτελέσματα. Εάν είναι None τα αποτελέσματα για κάθε αρχείο εγγράφονται στον φάκελο του αρχείου αυτού.

Εάν η ignore_missing_files είναι True, η κάλυψη για μη υπάρχοντα αρχεία αγνοείται σιωπηρά. Ειδαλλιώς, ένα μη υπάρχον αρχείο θα εγείρει FileNotFoundError.

Άλλαξε στην έκδοση 3.13: Προστέθηκε η παράμετρος ignore_missing_files.

Ένα απλό παράδειγμα που υποδεικνύει τη χρήση της προγραμματιστικής διεπαφής:

import sys
import trace

# δημιούργησε ένα αντικείμενο Trace λέγοντάς του τι να αγνοήσει και
# εάν θα κάνει ιχνηλάτηση, αρίθμηση γραμμών ή και τα δύο.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# τρέξε τη νέα εντολή χρησιμοποιώντας τον δεδομένο ιχνηλάτη
tracer.run('main()')

# φτιάξε μια αναφορά τοποθετώντας το αποτέλεσμα στον τρέχων φάκελο
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")