6.10 `time` -- Accesso al tempo e conversioni

Questo modulo fornisce varie funzioni relative al tempo. È sempre disponibile, ma non tutte le funzioni sono disponibili su tutte le piattaforme. La maggior parte delle funzioni definite in questo modulo chiamano le funzioni della libreria C della piattaforma con lo stesso nome. Qualche volta può essere utile consultare la documentazione della piattaforma specifica, poiché la semantica di queste funzioni varia tra le piattaforme.

Una spiegazione di alcune terminologie e convenzioni viene riportata di seguito:

epoch è l'istante da cui inizia in conteggio del tempo. Il 1° gennaio di quell'anno, all'ora 0, il ``tempo trascorso da epoch'' è zero. Per i sistemi Unix, epoch è il 1970. Per scoprire qual'è l'epoch, vedete gmtime(0).
Le funzioni in questo modulo non gestiscono i tempi e le date prima di epoch o lontane nel futuro. Il punto di interruzione nel futuro viene determinato dalla libreria C; per Unix, tale valore viene solitamente indicato nel 2038.
Problema dell'anno 2000 (Y2K): Python dipende dalla libreria C della piattaforma sottostante, che generalmente non viene condizionata dal problema dell'anno 2000, in quanto tutte le date ed i tempi vengono rappresentati internamente come il numero di secondi trascorsi da epoch. Le funzioni che accettano uno struct_time (vedete più avanti) generalmente richiedono un anno di 4 cifre. Per compatibilità all'indietro, vengono supportati anni con valori di 2 cifre se la variabile di modulo accept2dyear è un intero diverso da zero; questa variabile viene inizializzata a 1, a meno che la variabile d'ambiente PYTHONY2K non sia stata impostata ad una stringa non vuota, nel qual caso viene inizializzata a 0. Perciò potete impostare PYTHONY2K ad una stringa non vuota nell'ambiente, per fare in modo che venga richiesto per tutti gli input un anno di 4 cifre. Quando vengono accettati anni con 2 cifre, questi vengono convertiti secondo gli standard POSIX o X/Open: i valori 69-99 vengono mappati a 1969-1999, e i valori 0-68 vengono mappati a 2000-2068. I valori 100-1899 sono sempre non accettabili. Notate che questa è una novità introdotta in Python 1.5.2(a2); le versioni precedenti, fino a Python 1.5.1 e 1.5.2a1, avrebbero aggiunto 1900 ai valori di anno inferiori a 1900.
UTC è l'acronimo di Coordinated Universal Time (NdT: Tempo Universale Coordinato), precedentemente conosciuto come Greenwich Mean Time, (NdT: Tempo Medio di Greenwich) o GMT. L'acronimo UTC non è un errore grammaticale, ma deriva da un compromesso tra lingua Inglese e lingua Francese.
DST è l'acronimo di Daylight Saving Time, (NdT: Ora Legale), una correzione del fuso orario di (generalmente) un'ora, per una parte dell'anno. Le regole per il DST sono magiche (determinate dalle leggi locali) e possono cambiare di anno in anno. La libreria C ha una tabella contenente le regole locali (generalmente letta da un file di sistema, per flessibilità) ed è la sola fonte della ``Vera Saggezza'' a riguardo.
La precisione delle varie funzioni che restituiscono il tempo reale può essere inferiore rispetto a quanto suggerito dalle unità in cui il loro valore o gli argomenti vengono espressi. Per esempio, sulla maggior parte dei sistemi Unix, l'orologio fa ``tic-tac'' soltanto 50 o 100 volte al secondo, e su Mac, i tempi sono accurati soltanto all'intero secondo.
D'altra parte, la precisione delle funzioni time() e sleep() è migliore rispetto alle equivalenti Unix: i tempi vengono rappresentati mediante un numero in virgola mobile, time() restituisce il tempo disponibile più accurato (utilizzando la funzione Unix gettimeofday() dove presente), e sleep() accetterà un tempo con una frazione non nulla (la funzione Unix select(), dove disponibile, viene utilizzata per implementare questo comportamento).

Il valore di tempo restituito da gmtime(), localtime() e strptime(), e accettato da asctime(), mktime() e strftime(), è una sequenza di 9 interi. I valori restituiti da gmtime(), localtime(), e strptime(), forniscono anche i nomi degli attributi per i singoli campi.

Indice Attributo Valore

0 tm_year (per esempio, 1993)
1 tm_mon intervallo [1,12]
2 tm_mday intervallo [1,31]
3 tm_hour intervallo [0,23]
4 tm_min intervallo [0,59]
5 tm_sec intervallo [0,61]; vedete (1) nella descrizione di strftime()
6 tm_wday intervallo [0,6], Lunedì è 0
7 tm_yday intervallo [1,366]
8 tm_isdst 0, 1 or -1; vedete sotto

Indice	Attributo	Valore
`0`	`tm_year`	(per esempio, 1993)
`1`	`tm_mon`	intervallo [1,12]
`2`	`tm_mday`	intervallo [1,31]
`3`	`tm_hour`	intervallo [0,23]
`4`	`tm_min`	intervallo [0,59]
`5`	`tm_sec`	intervallo [0,61]; vedete (1) nella descrizione di `strftime()`
`6`	`tm_wday`	intervallo [0,6], Lunedì è 0
`7`	`tm_yday`	intervallo [1,366]
`8`	`tm_isdst`	0, 1 or -1; vedete sotto

Notate che diversamente dalla struttura C, il valore del mese viene compreso nell'intervallo 1-12, non 0-11. Un valore per l'anno verrà gestito come descritto sopra, in ``Problema dell'anno 2000 (Y2K)''. Un argomento -1 come opzione per l'ora legale, passato a mktime() generalmente genererà il corretto stato per l'ora legale da inserire.

Quando una tupla di lunghezza non corretta viene passata ad una funzione che si aspetta uno struct_time, o quando sono presenti alcuni elementi del tipo errato, viene sollevata un'eccezione TypeError.

Modificato nella versione 2.2: La sequenza dei valori del tempo è stata cambiata da una tupla in una classe struct_time, con l'aggiunta dei nomi degli attributi per i campi..

Il modulo definisce i seguenti elementi di funzioni e dati:

accept2dyear: Un valore booleano che indica se gli anni a 2 cifre verranno accettati. Il valore predefinito è Vero, ma verrà impostato a Falso se la variabile d'ambiente PYTHONY2K è stata impostata ad una stringa non vuota. Può anche venire modificato a runtime.

altzone: La distanza del fuso orario DST locale, in secondi a ovest di UTC, se definita. Assume valore negativo se il fuso orario DST locale è ad est di UTC (come nell'Europa Ovest, incluso il Regno Unito). Utilizzatelo solamente se daylight è non nullo.

asctime( [t]): Converte una tupla o una classe struct_time rappresentante un tempo, come restituita da gmtime() o da localtime(), in una stringa di 24 caratteri, nella forma seguente: 'Sun Jun 20 23:21:05 1993'. Se t non viene fornito, viene utilizzato il tempo corrente restituito da localtime(). Le informazioni sulla localizzazione non vengono utilizzate da asctime(). Note: Diversamente dalla funzione C con lo stesso nome, non c'è qui un carattere di fine riga. Modificato nella versione 2.1: È consentito omettere t.

clock( ): Su Unix, restituisce il tempo di processore corrente come un numero in virgola mobile espresso in secondi. La precisione, ed in effetti la vera definizione del significato di ``tempo di processore'', dipende dalla funzione C con lo stesso nome, ma in ogni caso, questa è la funzione da utilizzare per effettuare le verifiche di performance su Python o sugli algoritmi di tempo.
Su Windows, questa funzione restituisce il tempo, in secondi, trascorso dalla prima chiamata a questa funzione, come un numero in virgola mobile, basato sulla funzione Win32 QueryPerformanceCounter(). La risoluzione tipicamente è migliore di un microsecondo.

ctime( [secs]): Converte un tempo espresso in secondi da epoch, in una stringa rappresentante il tempo locale. Se secs non viene fornito, viene utilizzato il valore corrente del tempo restituito dalla funzione time(). ctime(secs) è equivalente a asctime(localtime(secs)). Le informazioni sulla localizzazione non vengono utilizzate da ctime(). Modificato nella versione 2.1: È consentito omettere secs.

daylight: Un valore diverso da zero se viene definita una zona DST.

gmtime( [secs]): Converte un tempo espresso in secondi da epoch in una classe struct_time in UTC, in cui l'opzione DST è sempre zero. Se secs non viene fornito, viene utilizzato il tempo corrente restituito da time(). Le frazioni di secondo vengono ignorate. Vedete sopra per una descrizione dell'oggetto struct_time. Modificato nella versione 2.1: È consentito omettere secs.

localtime( [secs]): Come gmtime(), ma converte nel tempo locale. L'opzione dst viene impostata a 1 quando DST viene si applica al tempo corrente. Modificato nella versione 2.1: È consentito omettere secs.

mktime( t): È la funzione inversa di localtime(). Come argomento accetta una classe struct_time o una tupla di 9 elementi pieni (poiché l'opzione dst è necessaria; utilizzate -1 come valore per l'opzione dst se questa non è nota) che esprimone il tempo nel formato locale, non UTC. Restituisce un numero in virgola mobile, per compatibilità con time(). Se l'input non può venire rappresentato come un tempo valido, possono venire sollevate le eccezioni OverflowError o ValueError (quale delle due dipende da chi intercetta prima il valore errato, se Python o la libreria C sottostante). La data generabile più indietro nel temp dipende dalla piattaforma.

sleep( secs): Sospende l'esecuzione per il dato numero di secondi. L'argomento può essere un numero in virgola mobile, per indicare un tempo di sleep più preciso. Il reale tempo di sospensione può essere inferiore di quello richiesto poiché ogni segnale intercettato termina la funzione sleep(), continuando con l'esecuzione della routine di intercettazione del segnale. Inoltre, il tempo di sospensione potrebbe essere maggiore di quello richiesto di una quantità arbitraria, a seguito della schedulazione di altre attività nel sistema.

strftime( format[, t])

Converte una tupla o una classe struct_time, rappresentante un tempo come restituito da gmtime() o localtime(), in una stringa come specificato dall'argomento format. Se t non viene fornito, viene utilizzato il valore corrente di tempo come restituito da localtime(). format deve essere una stringa. Viene sollevata l'eccezione ValueError se uno dei campi in t risulti esterno all'intervallo consentito. Modificato nella versione 2.1: È consentito omettere t. Modificato nella versione 2.4: L'eccezione ValueError viene sollevata se un campo in t è esterno all'intervallo..

Le seguenti direttive possono venire inserite nella stringa format. Vengono mostrate senza specificare il campo facoltativo di ampiezza e precisione, e vengono sostituite dai caratteri indicati nel risultato di strftime().

Direttiva Significato Note

%a Nome abbreviato del giorno della settimana, secondo il locale corrente.
%A Nome completo del giorno delle settimana, secondo il locale corrente.
%b Nome abbreviato del mese, secondo il locale corrente.
%B Nome completo del mese, secondo il locale corrente.
%c Rappresentazione appropriata della data e dell'ora correnti, secondo il locale corrente.
%d Giorno del mese, come numero decimale [01,31].
%H Ora (orologio a 24 ore) come numero decimale [00,23].
%I Ora (orologio a 12 ore) come numero decimale [01,12].
%j Giorno del'anno come numero decimale [001,366].
%m Mese come numero decimale [01,12].
%M Minuto come numero decimale [00,59].
%p Equivalente di AM o PM, secondo il locale corrente. (1)
%S Secondo come numero decimale [00,61]. (2)
%U Numero della settimana dell'anno (Domenica come primo giorno della settimana) come numero decimale [00,53]. Tutti i giorni di un nuovo anno precedendi la prima Domenica vengono considerati come appartenenti alla settimana 0.
%w Giorno della settimana come numero decimale [0(Domenica),6].
%W Numero della settimana dell'anno (Lunedì come primo giorno della settimana) come numero decimale [00,53]. Tutti i giorni di un nuovo anno precedendi il primo Lunedì vengono considerati come appartenenti alla settimana 0.
%x Rappresentazione della data appropriata secondo il locale corrente.
%X Rappresentazione dell'ora appropriata secondo il locale corrente.
%y Anno senza il secolo come numero decimale [00,99].
%Y Anno con il secolo come numero decimale.
%Z Nome del fuso oraio (nessun carattere se non esiste un fuso orario).
%% Un carattere costante "%".

Direttiva	Significato	Note
`%a`	Nome abbreviato del giorno della settimana, secondo il locale corrente.
`%A`	Nome completo del giorno delle settimana, secondo il locale corrente.
`%b`	Nome abbreviato del mese, secondo il locale corrente.
`%B`	Nome completo del mese, secondo il locale corrente.
`%c`	Rappresentazione appropriata della data e dell'ora correnti, secondo il locale corrente.
`%d`	Giorno del mese, come numero decimale [01,31].
`%H`	Ora (orologio a 24 ore) come numero decimale [00,23].
`%I`	Ora (orologio a 12 ore) come numero decimale [01,12].
`%j`	Giorno del'anno come numero decimale [001,366].
`%m`	Mese come numero decimale [01,12].
`%M`	Minuto come numero decimale [00,59].
`%p`	Equivalente di AM o PM, secondo il locale corrente.	(1)
`%S`	Secondo come numero decimale [00,61].	(2)
`%U`	Numero della settimana dell'anno (Domenica come primo giorno della settimana) come numero decimale [00,53]. Tutti i giorni di un nuovo anno precedendi la prima Domenica vengono considerati come appartenenti alla settimana 0.
`%w`	Giorno della settimana come numero decimale [0(Domenica),6].
`%W`	Numero della settimana dell'anno (Lunedì come primo giorno della settimana) come numero decimale [00,53]. Tutti i giorni di un nuovo anno precedendi il primo Lunedì vengono considerati come appartenenti alla settimana 0.
`%x`	Rappresentazione della data appropriata secondo il locale corrente.
`%X`	Rappresentazione dell'ora appropriata secondo il locale corrente.
`%y`	Anno senza il secolo come numero decimale [00,99].
`%Y`	Anno con il secolo come numero decimale.
`%Z`	Nome del fuso oraio (nessun carattere se non esiste un fuso orario).
`%%`	Un carattere costante "`%`".

Note:

(1): Quando usata con la funzione strptime(), la direttiva %p influisce solo l'output del campo dell'ora, se la direttiva %I viene usata per analizzare l'ora.
(2): L'intervallo reale è da 0 a 61; questo spiega gli sbalzi di secondi e i (molto rari) doppi sbalzi di secondi.

Ecco un esempio, un formato per le date compatibile con quello specificato nella RFC 2822 Internet Email Standard. ^6.1

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

Ulteriori direttive possono venire supportate su certe piattaforme, ma solo quelle indicate sopra hanno un significato standardizzato dall'ANSI C.

Su alcune piattaforme, uno campo facoltativo, di ampiezza e precisione specificate, può immediatamente seguire il carattere "%" iniziale di una direttiva, nell'ordine che segue; anche questo non è portabile. L'ampiezza per il campo è normalmente 2, ad eccezione di %j in cui è 3.

strptime( string[, format]): Analizza una stringa rappresentante un tempo, in accordo con la formattazione fornita. Il valore restituito è una struct_time, come restituita da gmtime() o da localtime(). Il parametro format utilizza le stesse direttive usate da strftime(); viene impostato in modo predefinito a "%a %b %d %H:%M:%S %Y", che corrisponde al formato restituito da ctime(). Se string non può essere analizzata in accordo con format, viene sollevata l'eccezione ValueError. Se la stringa da analizzare ha dati in eccesso dopo l'analisi, viene sollevata l'eccezione ValueError. I valori predefiniti usati per riempire i dati mancanti sono: (1900, 1, 1, 0, 0, 0, 0, 1, -1).
Il supporto per la direttiva %Z si basa sui valori contenuti in tzname, e sul fatto che il valore di daylight risulti vero o meno. Per questo motivo, risulta dipendente dalla piattaforma, ad eccezione del riconoscimento di UTC e GMT che sono sempre noti (e vengono considerati fusi orari senza ora legale).

struct_time: Il tipo della sequenza dei valori del tempo restituita da gmtime(), localtime() e strptime(). Nuovo nella versione 2.2.

time( ): Restituisce il tempo come un numero in virgola mobile espresso in secondi da epoch, in UTC. Notate che anche se il tempo viene sempre restituito come numero in virgola mobile, non tutti i sistemi forniscono il tempo con una precisione superiore ad un secondo. Dato che questa funzione normalmente restituisce valori non decrescenti, può restituire un valore inferiore rispetto a quello di una precedente chiamata, se l'orologio di sistema è stato reimpostato tra le due chiamate.

timezone: La distanza del fuso orario locale (non DST), in secondi a ovest di UTC (valore negativo nella maggior parte dell'Europa, positivo in USA, zero nel Regno Unito).

tzname: Una tupla di due stringhe: la prima è il nome del fuso orario locale non DST, la seconda è il nome del fuso orario DST. Se nessun fuso DST viene definito, la seconda stringa non dovrebbe venire usata.

tzset( )

Reimposta le regole di conversione del tempo dalla libreria di sistema. La variabile d'ambiente TZ specifica come questo viene fatto. Nuovo nella versione 2.3.

Disponibilità: Unix.

Note: Anche se in molti casi, modificare la variabile d'ambiente TZ può influire sull'output di funzioni come localtime senza chiamare tzset, non si dovrebbe fare affidamento su questo comportamento.

La variabile d'ambiente TZ non dovrebbe contenere spazi vuoti.

Il formato standard per la variabile d'ambiente TZ è (gli spazi vengono aggiunti per chiarezza):

std offset [dst [offset] [,start[/time], end[/time]: ]]

Dove:

std and dst

Tre o più alfanumerici indicanti l'abbreviazione del fuso orario. Queste verranno espanse in time.tzname

offset

L'offset ha la forma ± hh[:mm[:ss]]. Indica il valore da aggiungere al tempo locale per ottenere UTC. Se preceduto da un '-', il fuso orario è ad est del meridiano principale; altrimenti è a ovest. Se nessun offset segue il DST, l'ora estiva viene assunta come un'ora avanti rispetto all'ora standard.

start[/time],end[/time]

Indica quando cambiare da e verso DST. Il formato delle date start e end passati come argomento, è uno dei seguenti:

Jn: Il giorno n secondo il calendario Giuliano (1 <= n <= 365). I giorni bisestili non vengono conteggiati, perciò in tutti gli anni il 28 febbraio è il giorno 59 ed il primo marzo è il giorno 60.
n: Il giorno secondo il calendario Giuliano, partendo da 0 (0 <= n <= 365). I giorni bisestili vengono conteggiati ed è possibile fare riferimento al 29 febbraio.
Mm.n.d: Il giorno d-esimo (0 <= d <= 6) o la settimana n del mese m dell'anno (1 <= n <= 5, 1 <= m <= 12, dove la settimana 5 indica "l'ultimo giorno d del mese m" che può presentarsi sia nella quarta che nella quinta settimana). La settimana 1 è la prima settimana in cui cade il giorno d. Il giorno zero è Domenica.

time ha lo stesso formato di offset ad eccezione del fatto che il segno ('-' o '+') non è ammesso. Il valore predefinito, se non viene passata nessuna ora, è 02:00:00.

>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'

Su molti sistemi Unix (inclusi *BSD, Linux, Solaris e Darwin), è più conveniente usare il database di sistema zoneinfo (tzfile(5)) per specificare tutte le regole di fuso orario. Per fare questo, impostate la variabile d'ambiente TZ al percorso del file riferito al fuso orario richiesto, relativamente alla radice del database di sistema di 'zoneinfo', generalmente posto in /usr/share/zoneinfo. Per esempio, 'US/Eastern', 'Australia/Melbourne', 'Egypt' o 'Europe/Amsterdam'.

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')

Vedete anche:

Modulo datetime:: Un'interfaccia più orientata agli oggetti per data e tempo.

Modulo locale:: Servizi di internazionalizzazione. Le impostazioni della localizzazione possono influenzare il valore restituito di alcune delle funzioni del modulo time.

Modulo calendar:: Generiche funzioni collegate al calendario. timegm() è l'inverso di gmtime() di questo modulo.

Footnotes

... Standard.^6.1: L'utilizzo di %Z viene adesso deprecato, ma l'escape %z che espande la distanza oraria ore/minuti preferita non viene supportato da tutte le librerie ANSI C. Inoltre, una lettura rigorosa dell'originale standard RFC 822 del 1992 richiede un anno di 2 cifre (%y invece che %Y), ma per pratica l'anno di 4 cifre è stato adottato prima dell'anno 2000. L'anno a 4 cifre è stato ufficializzato dalla RFC 2822, che ha reso obsoleta la RFC 822.

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

6.10 time -- Accesso al tempo e conversioni

Footnotes

6.10 `time` -- Accesso al tempo e conversioni