6.9.4 Oggetti di tipo datetime

6.9.4 Oggetti di tipo `datetime`

Un oggetto di tipo datetime contiene in una singola istanza le informazioni di un oggetto di tipo date e di un oggetto di tipo time. Come oggetto di tipo date, un oggetto di tipo datetime usa il calendario Gregoriano corrente esteso in entrambe le direzioni; come oggetto di tipo time, un oggetto di tipo datetime assume che vi siano esattamente 3600*24 secondi per ogni giorno.

Costruttore:

class datetime( year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])

Gli argomenti "year" (anno), "month" (mese) e "day" (giorno) sono obbligatori. Il parametro tzinfo può essere None o un'istanza di una classe derivata di tzinfo. Gli altri argomenti possono essere interi o interi long, nei seguenti intervalli:

MINYEAR <= year <= MAXYEAR
1 <= month <= 12
1 <= day <= numero di giorni del mese e dell'anno specificati
0 <= hour < 24
0 <= minute < 60
0 <= second < 60
0 <= microsecond < 1000000

Se viene passato un argomento esterno a questi intervalli, viene sollevata l'eccezione ValueError.

Altri costruttori, tutti metodi di classe:

today( ): Restituisce un oggetto datetime che rappresenta la data e l'ora locale correnti, con tzinfo uguale None. Tale oggetto è equivalente a quello calcolato con l'espressione datetime.fromtimestamp(time.time()). Vedete anche le funzioni now() e fromtimestamp().

now( [tz]): Restituisce la data ed il tempo locali correnti. Se l'argomento facoltativo tz vale None o non viene specificato, il metodo è equivalente a today(), ma, se possibile, offre una maggiore precisione di quella che può ottenersi attraverso il valore di tempo restituito da time.time() (questo può ad esempio verificarsi su piattaforme che forniscano una implementazione della funzione C gettimeofday()).
Se non vale None, allora l'argomento tz deve essere una istanza di una classe derivata di tzinfo, e data e tempo correnti vengono convertiti nel fuso orario espresso da tz. In questo caso, il risultato equivale all'espressione tz.fromutc(datetime.utcnow().replace(tzinfo=tz)). Vedete anche i metodi today(), utcnow().

utcnow( ): Restituisce la data ed il tempo corrente con riferimento UTC, con l'attributo tzinfo uguale a None. Questo metodo è simile a now(), ma restituisce la data ed il tempo correnti con riferimento UTC, come un oggetto datetime di tipo semplice. Vedete anche il metodo now().

fromtimestamp( timestamp[, tz])

Restituisce il tempo e la data locali corrispondenti al tempo di riferimento POSIX specificato dall'argomento timestamp, come restituito da time.time(). Se l'argomento facoltativo tz vale None o non viene specificato, allora il tempo di riferimento passato in input viene convertito nel tempo locale della piattaforma, e l'oggetto di tipo datetime restituito è di tipo semplice.

Se non vale None, l'argomento tz deve essere una istanza di una classe derivata di tzinfo, ed il valore di tempo in input viene convertito nel fuso orario espresso da tz. In questo caso il risultato è equivalente all'espressione tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz)).

Il metodo fromtimestamp() può sollevare un'eccezione di tipo ValueError, nel caso che il tempo di riferimento sia esterno all'intervallo di valori supportati dall'implementazione delle funzioni C localtime() o gmtime() fornite dalla piattaforma ospite. È comune che il valore del tempo venga ristretto agli anni tra il 1970 ed il 2038. Notate che, su sistemi non POSIX che includano i "leap seconds" nella loro nozione di valori del tempo, tali secondi vengono ignorati dal metodo fromtimestamp(), ed è quindi possibile che due valori di tempo differenti per un secondo conducano a valori identici di datetime. Vedete anche il metodo utcfromtimestamp().

utcfromtimestamp( timestamp): Restituisce l'oggetto datetime rappresentante il tempo e la data UTC corrispondenti al valore di tempo POSIX passato come input, con l'attributo tzinfo posto uguale a None. Questo metodo può sollevare l'eccezione ValueError, nel caso che l'input sia esterno all'intervallo di valori supportati dalla funzione C gmtime() offerta dalla piattaforma ospite. È comune che questa funzione venga ristretta agli anni tra il 1970 ed il 2038. Vedete anche fromtimestamp().

fromordinal( ordinal): Restituisce l'oggetto di tipo datetime rappresentante l'ordinale del calendario prolettico Gregoriano, dove il primo Gennaio dell'anno 1 ha ordinale 1. Nel caso che non sia vera la condizione 1 <= ordinal <= datetime.max.toordinal(), viene sollevata l'eccezione ValueError. Gli attributi dell'oggetto corrispondenti all'ora, minuto, secondo e microsecondo vengono posti a zero, mentre tzinfo viene impostato a None.

combine( date, time): Restituisce un nuovo oggetto di tipo datetime i cui membri vengono impostati agli stessi valori di quelli di date, mentre i membri tzinfo vengono impostati ai valori di quelli dell'argomento time. Per ogni oggetto d di tipo datetime, è vera l'espressione d == datetime.combine(d.date(), d.timetz()). Nel caso in cui l'argomento date sia un oggetto di tipo datetime, sia i suoi attributi rappresentanti il tempo che tzinfo, vengono ignorati.

Attributi di classe:

min: L'oggetto datetime corrispondente al più lontano tempo passato rappresentabile, cioè datetime(MINYEAR, 1, 1, tzinfo=None).

max: L'oggetto datetime corrispondente al più lontano tempo futuro rappresentabile, cioè datetime, datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None).

resolution: La più piccola differenza possibile tra oggetti datetime non uguali, cioè timedelta(microseconds=1).

Attributi d'istanza (in sola lettura):

year: Anno. Compreso tra MINYEAR e MAXYEAR, limiti inclusi.

month: Mese. Compreso tra 1 e 12, limiti inclusi.

day: Giorno. Compreso tra 1 ed il numero di giorni del mese e dell'anno specificato.

hour: Ora. Compreso nell'intervallo dato da range(24).

minute: Minuto. Compreso nell'intervallo dato da range(60).

second: Secondo. Compreso nell'intervallo dato da range(60).

microsecond: Microsecondo. Compreso nell'intervallo dato da range(1000000).

tzinfo: L'oggetto passato come argomento tzinfo al costruttore datetime, oppure None se l'argomento non viene specificato.

Operationi supportate:

Operazione Risultato

datetime2 = datetime1 + timedelta (1)
datetime2 = datetime1 - timedelta (2)
timedelta = datetime1 - datetime2 (3)
datetime1 < datetime2 Confronta due oggetti datetime. (4)

Operazione	Risultato
`datetime2 = datetime1 + timedelta`	(1)
`datetime2 = datetime1 - timedelta`	(2)
`timedelta = datetime1 - datetime2`	(3)
`datetime1 < datetime2`	Confronta due oggetti `datetime`. (4)

(1)

datetime2 rappresenta un tempo distante timedelta rispetto a datetime1, spostato nel futuro se timedelta.days > 0, o nel passato se timedelta.days < 0. Il risultato ha lo stesso membro tzinfo dell'oggetto datetime di input, e dopo l'operazione è vera l'espressione datetime2 - datetime1 == timedelta. Viene sollevata un'eccezione OverflowError se datetime2.year risulta minore di MINYEAR o maggiore di MAXYEAR. Notate che non viene effettuato alcun aggiustamento di fuso orario, anche se il primo operando è un oggetto di tipo "complesso".

(2)

Calcola datetime2 tale che sia vera l'espressione datetime2 + timedelta == datetime1. Come nel caso dell'addizione, il risultato ha lo stesso attributo tzinfo del primo operando, e nessun aggiustamento di tempo dovuto al fuso orario viene effettuato, anche se il primo operando è un oggetto di tipo "complesso". Questa operazione non è esattamene equivalente a datetime1 + (-timedelta)", perché il valore -timedelta, considerato isolatamente, può andare in overflow nei casi in cui con datetime1 - timedelta ciò non accade.

(3)

La sottrazione tra due oggetti di tipo datetime viene definita solo se entrambi gli operandi sono "semplici" o "complessi". Se uno è "complesso" e l'altro è "semplice", viene sollevata un'eccezione di tipo TypeError.

Se entrambi gli operandi sono "semplici" oppure sono "complessi", ma hanno lo stesso valore per l'attributo tzinfo, tali valori vengono ignorati ed il risultato è un oggetto t di tipo timedelta, tale che datetime2 + t == datetime1. In questo caso non viene effettuato alcun aggiustamento di fuso orario.

Se entrambi gli operandi sono "complessi" ed hanno attributi tzinfo non uguali, allora a-b funziona convertendo prima a e b in oggetti "semplici" con riferimendto ad UTC. Il risultato è equivalente a quello dell'espressione (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()), eccetto per il fatto che l'implementazione reale non va mai in overflow.

(4)

datetime1 viene considerato inferiore a datetime2 se lo precede nel tempo.

Se un termine di paragone è un oggetto "semplice" e l'altro un oggetto "complesso", viene sollevata un'eccezione TypeError. Se entrambi i termini sono oggetti "complessi" ed hanno lo stesso valore per l'attributo tzinfo, allora questo viene ignorato e vengono semplicemente confrontati i tempi base. Se entrambi i termini sono "complessi" ed hanno diversi valori per l'attributo tzinfo, allora entrambi vengono prima corretti sottraendone le differenze di fuso orario rispetto al riferimento UTC (ottenuto da self.utcoffset()). Note: Per impedire che si ricada nel comportamento predefinito per il confronto di oggetti, che è quello di confrontarne gli indirizzi, il metodo di confronto della classe datetime normalmente solleva un'eccezione TypeError se uno dei due termini non è un oggetto datetime. Tuttavia, nel caso invece che tale oggetto abbia un attributo timetuple, viene restituito il valore NotImplemented. Questa estensione al meccanismo di confronto consente che generi di oggetti date diversi possano avere la possibilità di implementare dei confronti, pur non essendo dello stesso tipo. Se l'oggetto non ha un attributo timetuple, quando lo si confronta con un oggetto datetime viene sollevata un'eccezione TypeError, a meno che il confronto non sia == o !=. In questo caso, il confronto restituisce rispettivamente False e True.

Oggetti datetime possono venire usati come chiavi di dizionario. In un contesto booleano, tutti gli oggetti datetime vengono considerati veri.

Metodi di istanza:

date( ): Restituisce un oggetto date con lo stesso anno, mese e giorno.

time( ): Restituisce un oggetto time con gli stessi valori per ora, minuto, secondo e microsecondo. L'attributo tzinfo vale None. Vedete anche il metodo timetz().

timetz( ): Restituisce un oggetto time con gli stessi valori di attributi per ora, minuto, secondo, microsecondo ed il fuso orario (tzinfo). Vedete anche il metodo time().

replace( [year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]]): Restituisce un oggetto datetime con gli stessi valori di attributo, eccetto per quelli per cui vengono forniti nuovi valori tramite gli argomenti passati per nome. Notate che si può specificare tzinfo=None per creare un oggetto "semplice" partendo da uno "complessi", senza che venga effettuata alcuna conversione dei valori degli attributi di tempo e data.

astimezone( tz)

Restituisce un oggetto datetime con l'attributo tzinfo che assume il valore dell'argomento tz, provocando una correzione dei valori degli attributi di tempo e data tale da ottenere lo stesso tempo dell'oggetto di partenza (self), ma nel fuso orario locale tz.

L'argomento tz deve essere un'istanza di una classe derivata di tzinfo, ed i sui metodi utcoffset() e dst() non devono restituire None. L'oggetto di partenza (self) deve essere di tipo "complesso", (self.tzinfo deve essere diverso da None e self.utcoffset() non deve restituire None).

Nel caso in cui self.tzinfo sia uguale a tz, l'espressione self.astimezone(tz) risulta uguale a self: non viene effettuata alcuna correzione dei valori degli attributi di tempo e data. In caso contrario il risultato rappresenta il tempo, espresso nel fuso orario di tz, corripondente allo stesso UTC rappresentato da self: dopo aver eseguito l'istruzione astz = dt.astimezone(tz), generalmente risulta vero che l'espressione astz - astz.utcoffset() abbia gli stessi membri di data e tempo corrispondenti a dt - dt.utcoffset(). La spiegazione a proposito della classe tzinfo tratta i casi limite, riguardanti i passaggi da e verso l'ora legale, in cui non è possibile ottenere l'egualianza di cui sopra.

Se volete semplicemente aggiungere un oggetto tz che rappresenti un fuso orario ad un oggetto dt di tipo datetime, senza correggere i valori di data e tempo di quest'ultimo, allora usate dt.replace(tzinfo=tz). Se volete semplicemente rimuovere l'informazione sul fuso orario da un oggetto dt di tipo complesso, senza correzione dei valori di data e tempo, allora usate dt.replace(tzinfo=None).

Notate che l'implementazione predefinita del metodo tzinfo.fromutc() può venire sostituita in una classe derivata di tzinfo allo scopo di influenzare il risultato restituito da astimezone(). Ignorando i casi di errore, astimezone() funziona così:

  def astimezone(self, tz):
      if self.tzinfo is tz:
          return self
      # Converte self in UTC, e aggunge il nuovo oggetto rappresentante
      # il fuso orario.
      utc = (self - self.utcoffset()).replace(tzinfo=tz)
      # Converte da UTC al fuso orario espresso da tz.
      return tz.fromutc(utc)

utcoffset( ): Se l'attributo tzinfo vale None, restituisce None, altrimenti restituisce self.tzinfo.utcoffset(self) e solleva un'eccezione se quest'ultimo restituisce un valore diverso da None o da un oggetto timedelta che rappresenti un numero totale di minuti inferiore a quelli di un giorno.

dst( ): Se l'attributo tzinfo vale None restituisce None, altrimenti restituisce self.tzinfo.dst(self) e solleva un'eccezione se quest'ultimo restituisce un valore diverso da None e da un oggetto timedelta che rappresenti un numero totale di minuti inferiore a quelli di un giorno.

tzname( ): Se l'attributo tzinfo vale None, restituisce None, altrimenti restituisce self.tzinfo.tzname(self) e solleva un'eccezione se quest'ultimo non restituisce None o un oggetto stringa.

timetuple( ): Restituisce un oggetto time.struct_time così come restituito da time.localtime(). L'espressione d.timetuple() è equivalente a time.struct_time((d.year, d.month, d.day, d.hour, d.minute, d.second, d.weekday(), d.toordinal() - date(d.year, 1, 1).toordinal() + 1, dst)). L'opzione tm_isdst del risultato viene impostata in accordo col metodo dst(): se l'attributo tzinfo vale None oppure se dst() restituisce None, allora tm_isdst viene posto uguale a -1; se invece dst() restituisce un valore non nullo, tm_isdst viene posto uguale ad 1; altrimenti tm_dst viene posto uguale a 0.

utctimetuple( ): Se l'istanza d di datetime è di tipo semplice, allora questo metodo è equivalente a d.timetuple(), eccetto per il fatto che l'opzione tm_isdst viene forzata a 0, indipendentemente dal valore restituito da d.dst(). Il DST (NdT: Daylight Saving Time, ora locale) non viene mai applicato ai tempi con riferimento UTC.
Se d è un oggetto di tipo "complesso", allora viene normalizzato in tempo con riferimento UTC sottraendone d.utcoffset(), e viene quindi restituita un'istanza di time.struct_time per il tempo normalizzato. tm_isdst viene impostato a 0. Notate che il risultato del valore dell'attributo tm_year potrebbe essere MINYEAR-1 o MAXYEAR+1, se d.year era MINYEAR o MAXYEAR, e la correzione UTC potrebbe andare oltre i limiti imposti agli anni.

toordinal( ): Restituisce l'ordinale del calendario Gregoriano prolettico corrispondente alla data rappresentata dall'oggetto. È equivalente a self.date().toordinal().

weekday( ): Restituisce il giorno della settimana in forma di intero, dove Lunedì corrisponde a 0 e Sabato a 6. È equivalente a self.date().weekday(). Vedete anche isoweekday().

isoweekday( ): Restituisce il giorno della settimana come intero, dove Lunedì corrisponde ad 1 e Sabato a 7. È equivalente a self.date().isoweekday(). Vedete anche weekday() e isocalendar().

isocalendar( ): Restituisce una tupla di 3 elementi (anno ISO, numero ISO della settimana, giorno ISO della settimana). È equivalente a self.date().isocalendar().

isoformat( [sep])

Restituisce una stringa rappresentante la data ed il tempo in formato ISO 8601, YYYY-MM-DDTHH:MM:SS.mmmmmm, oppure, se microsecond vale 0, YYYY-MM-DDTHH:MM:SS.

Se utcoffset() non restituisce None, viene aggiunta una stringa di 6 caratteri, indicante la differenza rispetto all'UTC in ore e minuti (con segno): YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM oppure, se microsecond vale 0, YYYY-MM-DDTHH:MM:SS+HH:MM

L'argomento facoltativo sep (il suo valore predefinito è 'T') è un separatore di un singolo carattere, piazzato tra la porzione data e la porzione tempo del risultato. Per esempio:

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     def utcoffset(self, dt): return timedelta(minutes=-399)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'

__str__( ): Per un'istanza d della classe datetime, str(d) è equivalente a d.isoformat(' ').

ctime( ): Restituisce una stringa rappresentante la data ed il tempo, ad esempio datetime(2002, 12, 4, 20, 30, 40).ctime() restituisce 'Wed Dec 4 20:30:40 2002'. L'espressione d.ctime() è equivalente all'espressione time.ctime(time.mktime(d.timetuple())) sulle piattaforme in cui la funzione C ctime() (che viene chiamata da time.ctime() ma non da datetime.ctime()) risulti conforme allo standard del linguaggio C.

strftime( format): Restituisce una stringa rappresentante la data ed il tempo, formattata secondo una specifica stringa di formato. Vedete la sezione sul comportamento di strftime().

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