Bases: object
A UTC-based datetime object.
This datetime class is based on the POSIX time, a system for describing instants in time, defined as the number of seconds elapsed since midnight Coordinated Universal Time (UTC) of Thursday, January 1, 1970. Using a single float timestamp allows higher precision as the default Python datetime.datetime class. It features the full ISO8601:2004 specification and some additional string patterns during object initialization.
Parameters: |
|
---|
Changed in version 0.5.1: UTCDateTime is no longer based on Python’s datetime.datetime class instead uses timestamp as a single floating point value which allows higher precision.
Supported Operations
Examples
Using a timestamp.
>>> UTCDateTime(0)
UTCDateTime(1970, 1, 1, 0, 0)
>>> UTCDateTime(1240561632)
UTCDateTime(2009, 4, 24, 8, 27, 12)
>>> UTCDateTime(1240561632.5)
UTCDateTime(2009, 4, 24, 8, 27, 12, 500000)
Using a ISO8601:2004 string. The detection may be enforced by setting the iso8601 parameter to True.
Calendar date representation.
>>> UTCDateTime("2009-12-31T12:23:34.5")
UTCDateTime(2009, 12, 31, 12, 23, 34, 500000)
>>> UTCDateTime("20091231T122334.5") # compact
UTCDateTime(2009, 12, 31, 12, 23, 34, 500000)
>>> UTCDateTime("2009-12-31T12:23:34.5Z") # w/o time zone
UTCDateTime(2009, 12, 31, 12, 23, 34, 500000)
>>> UTCDateTime("2009-12-31T12:23:34+01:15") # w/ time zone
UTCDateTime(2009, 12, 31, 11, 8, 34)
Ordinal date representation.
>>> UTCDateTime("2009-365T12:23:34.5")
UTCDateTime(2009, 12, 31, 12, 23, 34, 500000)
>>> UTCDateTime("2009365T122334.5") # compact
UTCDateTime(2009, 12, 31, 12, 23, 34, 500000)
>>> UTCDateTime("2009001", iso8601=True) # enforce ISO8601
UTCDateTime(2009, 1, 1, 0, 0)
Week date representation.
>>> UTCDateTime("2009-W53-7T12:23:34.5")
UTCDateTime(2010, 1, 3, 12, 23, 34, 500000)
>>> UTCDateTime("2009W537T122334.5") # compact
UTCDateTime(2010, 1, 3, 12, 23, 34, 500000)
>>> UTCDateTime("2009W011", iso8601=True) # enforce ISO8601
UTCDateTime(2008, 12, 29, 0, 0)
Using not ISO8601 compatible strings.
>>> UTCDateTime("1970-01-01 12:23:34")
UTCDateTime(1970, 1, 1, 12, 23, 34)
>>> UTCDateTime("1970,01,01,12:23:34")
UTCDateTime(1970, 1, 1, 12, 23, 34)
>>> UTCDateTime("1970,001,12:23:34")
UTCDateTime(1970, 1, 1, 12, 23, 34)
>>> UTCDateTime("20090701121212")
UTCDateTime(2009, 7, 1, 12, 12, 12)
>>> UTCDateTime("19700101")
UTCDateTime(1970, 1, 1, 0, 0)
>>> UTCDateTime("20110818_03:00:00")
UTCDateTime(2011, 8, 18, 3, 0)
Using multiple arguments in the following order: year, month, day[, hour[, minute[, second[, microsecond]]]. The year, month and day arguments are required.
>>> UTCDateTime(1970, 1, 1)
UTCDateTime(1970, 1, 1, 0, 0)
>>> UTCDateTime(1970, 1, 1, 12, 23, 34, 123456)
UTCDateTime(1970, 1, 1, 12, 23, 34, 123456)
Using the following keyword arguments: year, month, day, julday, hour, minute, second, microsecond. Either the combination of year, month and day, or year and julday are required.
>>> UTCDateTime(year=1970, month=1, day=1, minute=15, microsecond=20)
UTCDateTime(1970, 1, 1, 0, 15, 0, 20)
>>> UTCDateTime(year=2009, julday=234, hour=14, minute=13)
UTCDateTime(2009, 8, 22, 14, 13)
Using a Python datetime.datetime object.
>>> dt = datetime.datetime(2009, 5, 24, 8, 28, 12, 5001)
>>> UTCDateTime(dt)
UTCDateTime(2009, 5, 24, 8, 28, 12, 5001)
Precision
The UTCDateTime class works with a default precision of 6 digits which effects the comparison of date/time values, e.g.:
>>> dt = UTCDateTime(0)
>>> dt2 = UTCDateTime(0.00001)
>>> dt3 = UTCDateTime(0.0000001)
>>> print(dt.precision)
6
>>> dt == dt2 # 5th digit is within current precision
False
>>> dt == dt3 # 7th digit will be neglected
True
You may change that behaviour either by,
using the precision keyword during object initialization:
>>> dt = UTCDateTime(0, precision=4)
>>> dt2 = UTCDateTime(0.00001, precision=4)
>>> print(dt.precision)
4
>>> dt == dt2
True
or set it the class attribute DEFAULT_PRECISION for all new UTCDateTime objects using a monkey patch:
>>> UTCDateTime.DEFAULT_PRECISION = 4
>>> dt = UTCDateTime(0)
>>> dt2 = UTCDateTime(0.00001)
>>> print(dt.precision)
4
>>> dt == dt2
True
Don’t forget to reset DEFAULT_PRECISION if not needed anymore!
>>> UTCDateTime.DEFAULT_PRECISION = 6
Attributes
DEFAULT_PRECISION | int(x=0) -> int or long |
__dict__ | |
__doc__ | str(object=’‘) -> string |
__module__ | str(object=’‘) -> string |
__weakref__ | list of weak references to the object (if defined) |
date | Returns a Python date object.. |
datetime | Returns a Python datetime object. |
day | Returns day as an integer. |
hour | Returns hour as an integer. |
julday | Returns Julian day as an integer. |
microsecond | Returns microseconds as an integer. |
minute | Returns minute as an integer. |
month | Returns month as an integer (January is 1, December is 12). |
precision | Returns precision of current UTCDateTime object. |
second | Returns seconds as an integer. |
time | Returns a Python time object. |
timestamp | float(x) -> floating point number |
weekday | Return the day of the week as an integer (Monday is 0, Sunday is 6). |
year | Returns year of the current UTCDateTime object. |
Public Methods
ctime | Return a string representing the date and time. |
dst | Returns None (to stay compatible with datetime.datetime) |
formatArcLink | Returns string representation for the ArcLink protocol. |
formatFissures | Returns string representation for the IRIS Fissures protocol. |
formatIRISWebService | Returns string representation usable for the IRIS Web services. |
formatSEED | Returns string representation for a SEED volume. |
formatSeedLink | Returns string representation for the SeedLink protocol. |
isocalendar | Returns a tuple containing (ISO year, ISO week number, ISO weekday). |
isoformat | Return a string representing the date and time in ISO 8601 format. |
isoweekday | Return the day of the week as an integer (Monday is 1, Sunday is 7). |
strftime | Return a string representing the date and time, controlled by an explicit format string. |
strptime | Return a UTCDateTime corresponding to date_string, parsed according to |
timetuple | Return a time.struct_time such as returned by time.localtime(). |
timetz | Return time object with same hour, minute, second, microsecond, and tzinfo attributes. |
toordinal | Return proleptic Gregorian ordinal. January 1 of year 1 is day 1. |
tzname | Returns None (to stay compatible with datetime.datetime) |
utcoffset | Returns None (to stay compatible with datetime.datetime) |
utctimetuple | Return a time.struct_time of current UTCDateTime object. |
Private Methods
_fromDateTime | Use Python datetime object to set current time. |
_getDate | Returns a Python date object.. |
_getDateTime | Returns a Python datetime object. |
_getDay | Returns day as an integer. |
_getHour | Returns hour as an integer. |
_getJulday | Returns Julian day as an integer. |
_getMicrosecond | Returns microseconds as an integer. |
_getMinute | Returns minute as an integer. |
_getMonth | Returns month as an integer (January is 1, December is 12). |
_getPrecision | Returns precision of current UTCDateTime object. |
_getSecond | Returns seconds as an integer. |
_getTime | Returns a Python time object. |
_getTimeStamp | Returns UTC timestamp in seconds. |
_getWeekday | Return the day of the week as an integer (Monday is 0, Sunday is 6). |
_getYear | Returns year of the current UTCDateTime object. |
_set | Sets current timestamp using kwargs. |
_setDay | Sets day of current UTCDateTime object. |
_setHour | Sets hours of current UTCDateTime object. |
_setJulday | Sets Julian day of current UTCDateTime object. |
_setMicrosecond | Sets microseconds of current UTCDateTime object. |
_setMinute | Sets minutes of current UTCDateTime object. |
_setMonth | Sets month of current UTCDateTime object. |
_setPrecision | Set precision of current UTCDateTime object. |
_setSecond | Sets seconds of current UTCDateTime object. |
_setYear | Sets year of current UTCDateTime object. |
Special Methods
__abs__ | Returns absolute timestamp value of the current UTCDateTime object. |
__add__ | Adds seconds and microseconds to current UTCDateTime object. |
__eq__ | Rich comparison operator ‘==’. |
__float__ | Returns UTC timestamp in seconds. |
__ge__ | Rich comparison operator ‘>=’. |
__gt__ | Rich comparison operator ‘>’. |
__hash__ | An object is hashable if it has a hash value which never changes during its lifetime. |
__init__ | Creates a new UTCDateTime object. |
__le__ | Rich comparison operator ‘<=’. |
__lt__ | Rich comparison operator ‘<’. |
__ne__ | Rich comparison operator ‘!=’. |
__repr__ | Returns a representation of UTCDatetime object. |
__str__ | Returns ISO8601 string representation from current UTCDateTime object. |
__sub__ | Subtracts seconds and microseconds from current UTCDateTime object. |
__unicode__ | Returns ISO8601 unicode representation from current UTCDateTime object. |