1. Alapvető dátum és idő típusok
A 2.3 verzióban jelent meg.
A datetime modul dátumok és idők kezelésére szolgáltat osztályokat - egyszerű és bonyolult módon is. Az aritmetikai műveletek támogatottak a dátumokon és időkön.
Két fajta dátum és idő objektum van: "naív" és "óvatos". Ez a megkülönböztetés arra vonatkozik, hogy az objektum számításba vesz-e időzónát, nyári időszámítást, vagy valamilyen más algoritmikus vagy politikai időkorrekciót. Az, hogy a naív datetime objektum egyezményes koordinált világidőt (UTC), helyi időt, vagy valamilyen időzóna szerinti időt reprezentál, az egyedül a programtól függ, csak úgy, mint ahogy a programtól függ az is, hogy egy bizonyos szám métert, mérföldet vagy tömeget jelöl. A naív datetime objektumokat könnyű megérteni és dolgozni velük, ám azon az áron, hogy figyelmen kívül hagyjuk a valóság bizonyos szempontjait.
A többet igénylő alkalmazások számára a datetime és time objektumok rendelkeznek egy opcionális időzóna adattaggal, a tzinfoval, ami az absztrakt tzinfo osztály egy alosztályának egy példányát tartalmazhatja. Ezen tzinfo objektumok információt tárolnak az UTC időtől való eltolásról, az időzóna nevéről, és hogy nyári időszámítás van-e érvényben. Figyeljük meg, hogy a datetime modul nem támogat semmilyen konkrét tzinfo osztályt. Az időzónák valamilyen szintű támogatása az alkalmazás feladata. Az időkorrekció szabályai világszerte inkább politikaiak mint ésszerűek, így nincs olyan sztenderd, ami minden alkalmazás számára megfelelő lenne.
A datetime modul a következő konstansokat exportálja:
MINYEAR --A legkisebb évszám, ami egy date vagy datetime objektumban megengedett (1).
MAXYEAR --A legnagyobb évszám, ami egy date vagy datetime objektumban megengedett (9999).
Lásd még:
calendar modul --általános, naptárral kapcsolatos függvények
time modul --idő elérés és konverziók
2. Rendelkezésre álló típusok
class date
Egy idealizált naív dátum, feltéve, hogy a mai Gergely-naptár mindig érvényben volt és lesz. Attribútumok: year, month, day.class time
Egy idealizált idő, független bármilyen konkrét naptól, feltéve, hogy minden nap pontosan 24*60*60 másodperces (mindenféle szökőmásodperc nélkül). Attribútumok: hour, minute, second, microsecond, tzinfo.class datetime
Egy date és egy time kombinációja. Attribútumok: year, month, day, hour, minute, second, microsecond és tzinfo.class timedelta
Egy időtartam, ami két date, time vagy datetime különbségét szimbolizálja mikromásodperces felbontással.class tzinfo
Egy absztrakt alaposztály időzóna-információt tartalmazó objekumok részére. Ezeket a datetime és time osztályok használják, hogy egy testre szabható fogalmat nyújtsanak az időkorrekcióra (pl. az időzónák ésvagy a nyári időszámítás jelölésére)Ezen osztályok objektumai immutable-ök.
A date típus objektumai mindig naívak.
Egy d objektum a time vagy datetime típusból lehet naív vagy óvatos. d óvatos ha d.tzinfo nem None és d.tzinfo.utcoffset(d) nem None-t ad vissza. Ha d.tzinfo None, vagy d.tzinfo nem None de d.tzinfo.utcoffset(d) None-t ad vissza, d naív.
A naív és óvatos közti megkülönböztetés nem vonatkozik a timedelta objektumokra.
3. timedelta objektumok
Egy timedelta objektum egy időtartamot reprezentál, két dátum vagy idő közti különbséget.
class timedelta( [days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])
Minden argumentum opcionális, és alapértelmezett értéke 0. Az argumentumok lehetnek intek, longok, vagy floatok, lehetnek pozitívak vagy negatívok.Csak a nap, másodperc és mikromásodperc tárolódik. Az argumentumok ezekre az egységekre konvertálódnak:
- Egy millimásodperc 1000 mikromásodpercre
- Egy perc 60 másodpercre
- Egy óra 3600 másodpercre
- Egy hét 7 napra
- 0 <= mikromásodperc < 1 000 000
- 0 <= másodperc < 3600*24 (a másodpercek száma egy napban)
- - 999 999 999 <= nap <= 999 999 999
Ha a napok normalizált értéke a kiszabott értékhatáron kívülre esik, OverflowError kivétel keletkezik.
Vegyük észre, hogy a negatív értékekre történő normalizáció meglepő lehet. Például,
>>> d = timedelte(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
Osztályattribútumok:
min
A legnegatívabb timedelta objektum, timedelta(-999999999).max
A legpozitívabb timedelta objektum, timedelta (999999999,23,59,59,999999).resolution
A legkisebb lehetséges eltérés két nemegyenlő timedelta objektum között, timedelta(microseconds=1).Objektumattribútumok (csak olvashatók):
days
-999 999 999 és 999 999 999 között (a határokat is beleértve).seconds
0 és 86 399 között (a határokat is beleértve).microseconds
0 és 999 999 között (a határokat is beleértve).Támogatott műveletek:
| t1 = t2 + t3 | t2 és t3 összege. Utána t1-t2==t3 és t1-t3==t2 teljesülnek. (1) |
| t1 = t2 - t3 | t2 és t3 különbsége. Utána t1==t2-t3 és t2==t1+t3 teljesülnek. (1) |
| t1 = t2 * i vagy t1 = i * t2 | integerrel vagy longgal való szorzás. Utána t1//i==t2 igaz, feltéve, hogy i!=0. Általában: t1*i==t1*(i-1)+t1 teljesül. (1) |
| t1 = t2 // i | Egészosztás. (3) |
| +t1 | Egy azonos értékű timedelta objektummal tér vissza. (2) |
| -t1 | Megegyezik ezzel: timedelta(-t1.days, -t1.seconds. -t1.microseconds), és ezzel: t1*-1. (1)(4) |
| abs(t) | Megegyezik +t-vel ha t.days>=0, és -t-vel, ha t.days<0. (2) |
Megjegyzések:
(1) Ez pontos, de túlcsordulhat.
(2) Ez pontos, és nem csordulhat túl.
(3) A nullával való osztá ZeroDivisionError kivételt okoz.
(4) -timedelta.max nem ábrázolható timedelta objektumként.
Ezen műveleteken túl a timedelta objektumok támogatnak bizonyos összeadásokat és kivonásokat a date és datetime objektumokkal (lásd alább).
A timedelta objektumok összehasonlításai támogatottak (a rövidebb időtartamot reprezentáló timedelta objektum számít kisebbnek). Hogy a különféle típusok közti összehasonlítás nehogy az alapértelmezett összehasonlítás legyen (az objektumcímek alapján), ha egy timedelta objektumot akarunk összehasonlítani egy másik típusú objektummal, TypeError kivétel keletkezik, hacsak az összehasonlítás nem == vagy !=. Az utóbbi esetek visszatérési értéke False vagy True, értelemszerűen.
A timedelta objektumok hasíthatók (használhatók dictionary kulcsokként), támogatják a hatékony elérést, és Boolean összefüggésben igaznak számítanak akkor és csak akkor, ha nem egyenlők timedelta(0)-val.
4. date objektumok
Egy date objektum egy dátumot (év, hónap, nap) reprezentál egy idealizált naptárban, a jelenleg érvényben levő Gergely-naptárt kiterjesztve mindkét irányba. Az első év január 1-e az 1-es nap, az első év január 2-a a 2-es nap és így tovább. Ez megegyezik a "proleptikus Gergely-naptárral", Dershowitz és Reingold Naptári számítésok című könyvéből, ahol ez az alapnaptár minden további számításhoz. Lásd a könyvet a Gergely-naptár és a többi naptári rendszer közötti konverziókhoz.
class date(year, month, day)
Minden argumentum megadása kötelező. Az argumentumok lehetnek intek vagy longok, a következő tartományokban:- MINYEAR <= year <= MAXYEAR
- 1 <= month <= 12
- 1 <= day <= napok száma az adott évben és hónapban
A többi konstruktor, mindegyik osztálymetódus:
today()
Az aktuális dátumot adja vissza. Ez ekvivalens ezzel: date.fromtimestamp(time.time()).fromtimestamp(timestamp)
A megadott POSIX időbélyegnek megfelelő helyi dátummal tér vissza (ilyet ad vissza pl a time.time()). Ez ValueError kivételt válthat ki, ha az időbélyeg kívül esik a C platformbeli localtime által támogatott értékhatáron. Általában ez az 1970. és a 2038. évek közöti tartományra való megszorítást jelent. Vegyük számításba, hogy olyan nem-POSIX rendszereken, ahol a szökőmásodperceket is számításba veszik az időbélyegeikben, a fromtimestamp() figyelmen kívül hagyja a szökőmásodperceket.fromordinal(ordinal)
A megadott proleptikus Gergely-naptárbeli sorszámnak megfelelő dátumot ad vissza, ahol az első év január 1-e az 1-es sorszámú nap. ValueError kivétel keletkezik, ha nem teljesül, hogy 1 <= ordinal <= date.max.toordinal(). Bármely d dátumra igaz: date.fromordinal(d.toordinal())==d.Osztályattribútumok:
min
A legkorábbi ábrázolható dátum, date(MINYEAR, 1, 1).max
A legkésőbbi ábrázolható dátum, date(MAXYEAR, 12, 31).resolution
A lehető legkisebb eltérés két nemegyenlő date objektum között, timedelta(days=1).Objektumattribútuok (csak olvashatóak):
year
MINYEAR és MAXYEAR között (határokat is beleértve).month
1 és 12 között (határokat is beleértve).day
1 és az adott év adott hónapjában levő napok száma között.Támogatott műveletek:
| date2 = date1 + timedelta | date1 timedelta.days nappal eltolva. (1) |
| date2 = date1 - timedelta | Ezután date2+timedelta==date1 teljesül. (2) |
| timedelta = date1-date2 | (3) |
| date1 < date2 | date1 kisebb date2-nél, ha megelőzi date2-t időben |
Megj:
(1) date2 előre tolódik az időben, ha timedelta.days>0, vagy visszafelé, ha timedelta.days< 0. Ezután date2-date1==timedelta.days. A timedelta.seconds és a timedelta.microseconds értékek nem számítanak. OverflowError keletkezik, ha date2.year kisebb lenne, mint MINYEAR vagy nagyobb, mint MAXYEAR.
(2) Ez nem egészen a date1+(-timedelta) megfelelője, mivel -timedelta önmagában túlcsordulhat, ahol a date1-timedelta nem. A timedelta.seconds és a timedelta.microseconds értékek nem számítanak.
(3) Ez pontos, és nem csordut túl. Ezután a timedelta.seconds és a timedelta.microseconds értékek nullák, ls date2+timedelta==date1 teljesül.
(4) Más szóval, date1 < date2 akkor, és csak akkor, ha date1.toordinal()
Dátumok használhatók dictionary kulcsként. Boolean összefüggésben minden date objektum igaznak számít.
Objektummmetódusok:
replace(year, month, day)
AZ eddigi értéket adja vissza, kivéve azokat a mezőket, amiknek az új értékét az argumentumokban megadtzuk. Például ha d==date(2002, 12, 31) teljesül, akkor d.replace(day=26)==date(2002, 12, 26) teljesül.timetuple()
Egy time.struct_time-ot ad vissza (ilyet ad vissza például a time.localtime()). Az órák, percek, másodpercek nullák, és a DST flag -1. d.timetuple() megfelel a következőnek: time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), d.toordinal()-date(d.year, 1, 1).toordinal()+1, -1)).toordinal()
A dátum proleptikus Gergely-naptár-beli sorszámát adja, ahol az első év január 1-e az 1-es sorszámú. Mindán d date objektumra: date.fromordinal(d.toordinal())==d teljesül.weekday()
A hét napját adja vissza egészként, ahol hétfő 0 és vasárnap 6. Például date(2002, 12, 4).weekday==2, azaz szerda. Láds még isoweekday().isoweekday()
A hét napját adja vissza egészként, ahol hétfő 1 és vasárnap 7. Például date(2002, 12, 4).isoweekday==3, azaz szerda. Láds még weekday(), isocalendar().isocalendar()
Egy rendezett hármast ad vissza: (ISO év, ISO hét száma, ISO hét napja)Az ISO naptár egy széleskörűen használt váltzata a Gergely-naptárnak (ld. http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm)
Az ISO év 52 vagy 53 teljes hétből áll. Egy hét hétfőn kezdődik és vasárnap ér véget. Egy ISO év első hete az első (Gergely-naptár-beli) naptári hete az évnek, amely tartalmaz csütörtököt. Ez a hét az első hét, és az ISO éve ennek a csütörtöknek ugyanaz, mint a Gergely-éve.
Például 2004. csütörtöki napon kezdődik, így a 2004. ISO év első fete hétfőn, 2003. december 29-én kezdődik, és vasárnap ér véget, 2004. január 4-én, így date(2003, 12, 29).isocalendar()==(2004, 1, 1) és date(2004, 1, 4).isocalendar()==(2004, 1, 7) fennállnak.