10.5.1 La classe Stats

10.5.1 La classe `Stats`

Gli oggetti di tipo Stats possiedono i seguenti metodi:

strip_dirs( ): Questo metodo per la classe Stats rimuove tutte le informazione relative alla directory nel percorso dei nomi di file. È molto utile per ridurre la larghezza dello stampato affinché si adatti al limite delle 80 colonne. Questo metodo modifica l'oggetto, e l'informazione rimossa viene definitivamente persa. Dopo l'esecuzione di questo metodo, le voci dell'oggetto si trovano in ordine ``casuale'', come dopo l'inizializzane ed il caricamento dell'oggetto. Se l'esecuzione di strip_dirs() fa sì che due funzioni diventino indistinguibili (cioè si trovano sulla stessa riga dello stesso file ed hanno lo stesso nome), allora le statistiche per queste due voci vengono riunite in una sola.

add( filename[, ...]): Questo metodo della classe Stats aggiunge ulteriori informazioni di profilatura a quella corrente. I suoi argomenti devono riferirirsi ai file creati dalla corrispondente versione di profile.run(). Statistiche per funzioni con stesso nome (vedi: file, line, name) vengono automaticamente riunite in una sola statistica.

dump_stats( filename): Salva i dati caricati nell'oggetto Stats in un file chimato filename. Il file viene creato se non esiste, o altrimenti sovrascritto. Questo è equivalente al metodo dello stesso nome nella classe profile.Profile. Nuovo nella versione 2.3.

sort_stats( key[, ...])

Questo metodo modifica l'oggetto Stats ordinandolo secondo i criteri specificati. L'argomento è tipicamente una stringa che identifica la base dell'ordinamento (esempio: 'time' o 'name').

Quando viene passato più di un argomento, le chiavi addizionali vengono utilizzate come criteri secondari quando le precedenti chiavi hanno prodotto delle righe uguali. Ad esempio, sort_stats('nome', 'file') ordinerà i record secondo il nome della funzione ed ordinerà le funzioni con stesso nome secondo il nome del file a cui appartengono.

Per i nomi delle chiavi si possono usare delle abbreviazioni, purché non creino ambiguità. Ecco l'elenco delle chiavi definite:

Argomento Significato

'calls' numero di chiamate
'cumulative' tempo cumulativo
'file' nome di file
'module' nome di file
'pcalls' numero di chiamate primitive
'line' numero di riga
'name' nome della funzione
'nfl' nome/file/riga
'stdname' nome standard
'time' tempo interno

Argomento	Significato
`'calls'`	numero di chiamate
`'cumulative'`	tempo cumulativo
`'file'`	nome di file
`'module'`	nome di file
`'pcalls'`	numero di chiamate primitive
`'line'`	numero di riga
`'name'`	nome della funzione
`'nfl'`	nome/file/riga
`'stdname'`	nome standard
`'time'`	tempo interno

Notate che tutti gli ordinamenti sulle statistiche avvengono in ordine decrescente (dal più costoso in termini di tempo al meno), mentre name, file e line sono in ordine ascendente (alfabeticamente). La sottile distinzione che c'è tra 'nfl' e 'stdname' è che quest'ultimo è un ordinamento del nome come stampato, e quindi i numeri delle righe vengono comparati in maniera bizzarra. Per esempio, le righe 3, 20, e 40 (se appartengono allo stesso file) verranno ordinate come 20, 3, 40. Invece, 'nfl' effettua una comparazione numerica dei numeri di riga. Infatti sort_stats('nfl') è la stessa cosa di sort_stats('name', 'file', 'line').

Per compatibilità con il vecchio profiler, viene consentito l'uso di argomenti numerici come -1, 0, 1 e 2. Vengono interpretati rispettivamente come 'stdname', 'calls', 'time' e 'cumulative'. Se usate questo formato per gli argomenti, potrete usare solo un tipo di ordinamento(la chiave numerica) ed ulteriori argomenti verranno silenziosamente ignorati.

reverse_order( ): Questo metodo per la classe Stats rovescia l'ordinamento della lista di base nell'oggetto. Questo metodo viene fornito principalmente per compatibilità con il vecchio profiler. La sua utilità è dubbia adesso che l'ordinamento ascendente o descendente viene selezionato correttamente in base alla chiave scelta.

print_stats( [restriction, ...])

Questo metodo della classe Stats stampa un rapporto come descritto nella definizione della funzione profile.run().

L'ordinamento con cui vengono stampati i risultati è basato sull'ultima operazione sort_stats() effettuata sull'oggetto (ed alle eventuali successive chiamate ai metodi add() e strip_dirs()).

Gli argomenti forniti possono venire utilizzati per limitare la lista alle voci più significative. Inizialmente, la lista include tutte le funzioni che sono state analizzate. Ogni restrizione può essere un intero (per selezionare una quantità di righe), o un decimale compreso tra 0.0 e 1.0 inclusi (per selezionare una percentuale di righe), o un'espressione regolare (per eseguire corrispondenze sullo standard che viene stampato; come in Python 1.5b1, si usa la sintassi per le espressioni regolari in stile Perl definita nel modulo re). Se si specificano varie restrizioni, queste vengono applicate sequenzialmente. Per esempio:

print_stats(.1, 'foo:')

innanzitutto limiterà lo stampato al 10% della lista e poi stamperà solamente le funzioni che appartengono ai file .*foo:. Invece il comando:

print_stats('foo:', .1)

prima selezionerà solo le funzioni che appartengono ai file .*foo: e poi stamperà solo il 10% della lista così ottenuta.

print_callers( [restriction, ...]): Questo metodo della classe Stats stampa una lista di tutte le funzioni che hanno chiamato le funzioni presenti nel database profilato. L'ordinamento, come anche la definizione degli argomenti di restrizione, è identico a quello fornito da print_stats(). Per comodità, viene anche mostrato un numero tra parentesi dopo ogni chiamante per indicare quante volte è stata effettuata questa specifica chiamata. Un secondo numero, non tra parentesi, rappresenta il tempo cumulativo speso nella funzione più a destra.

print_callees( [restriction, ...]): Questo metodo della classe Stats, stampa una lista di tutte le funzioni chiamate dalla funzione indicata. A parte questa visione inversa (``ha chiamato'' al posto di ``è stata chiamata da''), gli argomenti e l'ordinamento sono gli stessi del metodo print_callers().

ignore( ): Deprecato dalla versione 1.5.1 di Python. Non è necessario nelle moderne versioni di Python.^10.2

Footnotes

... Python.^10.2: Questo metodo una volta era necessario, in tempi in cui Python avrebbe stampato qualsiasi risultato di una espressione inutilizzata che non fosse None. Il metodo viene ancora definito per una questione di retrocompatibilità.

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