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

      Συγχωνεύει δεδομένα από ένα άλλο αντικείμενο "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=".")
