10.5 Manuale di riferimento

Il punto di entrata iniziale del profiler è la funzione globale profile.run(). Essa viene tipicamente utilizzata per creare tutte le informazione di profilo. I risultati vengono formattati e stampati usando i metodi della classe pstats.Stats. Ciò che segue è una descrizione di tutte queste funzioni e punti d'ingresso standard. Per una visione più approfondita di alcune porzioni di codice, prendete in considerazione la lettura della sezione successiva sulle Estensioni al Profiler, che spiega come derivare profiler ``migliori'' dalla classe qui presentata, oppure leggendo il codice sorgente di questi moduli.

run( command[, filename])

Questa funzione richiede un singolo argomento che possa venire passato all'istruzione exec ed un nome di file facoltativo. In tutti i casi questa procedura tenta di eseguire tramite exec il suo primo argomento, costruendo un profilo dalla sua esecuzione. Se non è presente un nome di file questa funzione stampa automaticamente a video un semplice profilo, ordinando ogni riga secondo la stringa standard (file/riga/nome-funzione). Ecco l'output tipico di questa chiamata:

      main()
      2706 function calls (2004 primitive calls) in 4.504 CPU seconds

Ordered by: standard name

ncalls  tottime  percall  cumtime  percall filename:lineno(function)
     2    0.006    0.003    0.953    0.477 pobject.py:75(save_objects)
  43/3    0.533    0.012    0.749    0.250 pobject.py:99(evaluate)
 ...

La prima riga indica che questo profilo è stato generato dalla chiamata:
profile.run('main()') e quindi la stringa passata ad exec è stata 'main()'. La seconda riga indica che sono state monitorate 2706 chiamate di funzione. Di queste, 2004 erano chiamate primitive. Per primitiva si intende una chiamata che non è stata indotta tramite ricorsione. La riga successiva: Ordered by: standard name, indica che l'ordinamento delle righe è avvenuto in base alla stringa presente nella colonna più a destra. Le intestazioni delle colonne includono:

ncalls: il numero di chiamate,
tottime: il tempo totale speso in questa funzione (escludendo il tempo trascorso per chiamare altre sotto funzioni),
percall: il rapporto tra tottime e ncalls
cumtime: il tempo totale speso dalla funzione corrente e da tutte le sue sotto funzioni(dall'invocazione all'uscita). Il risultato comprende anche le funzioni ricorsive.
percall: il rapporto tra cumtime ed il numero di chiamate primitive
filename:lineno(function): fornisce informazioni su ogni funzione

Quando ci sono due numeri nella prima colonna (per esempio, "43/3"), allora il secondo è il numero di chiamate primitive, mentre il primo è il numero di chiamate reali. Notate che quando una funzione non è ricorsiva, questi due numeri sono identici, e quindi ne viene stampato solo uno.

runctx( command, globals, locals[, filename])

Questa funzione è simile a profile.run(), con argomenti aggiuntivi per supplire ai dizionari locali e globali per la stringa command.

L'analisi dei dati prodotti dal profiler si esegue usando la classe definita nel modulo pstats:

class Stats( filename[, ...])

Il costruttore di questa classe crea un'istanza di un ``oggetto delle statistiche'' a partire da uno o più nomi di file filename. Gli oggetti di tipo Stats posseggono dei metodi per manipolare e stampare statistiche utili.

Il file passato al costruttore deve essere stato creato dalla corrispondente versione di profile. In particolare, non viene garantita la compatibilità del formato del file con future versioni del profiler, e non c'è alcuna compatibilità con i file generati da altri profiler (come il vecchio profiler di sistema).

Se vengono passati al costruttore vari file, tutte le statistiche di una funzione vengono riunite in una sola, cosicché si possa avere in un unico rapporto la visione generale di vari processi. Se dopo la creazione dell'oggetto Stats si ha la necessità di combinare i suoi dati con altri file aggiuntivi, si può sempre utilizzare il metodo add().

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.