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

Source code: Lib/trace.py

The `trace` module allows you to trace program execution, generate annotated statement coverage listings, print caller/callee relationships and list functions executed during a program run. It can be used in another program or from the command line.

Δείτε επίσης

Coverage.py

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

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

The `trace` module can be invoked from the command line. It can be as simple as

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

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

--help

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

--version

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

Added in version 3.8: Added `--module` option that allows running an executable module.

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

At least one of the following options must be specified when invoking `trace`. The `--listfuncs` option is mutually exclusive with the `--trace` and `--count` options. When `--listfuncs` is provided, neither `--count` nor `--trace` are accepted, and vice versa.

-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)

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

  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=".")