obspy.core.utcdatetime.UTCDateTime

class UTCDateTime(*args, **kwargs)

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:

• args (int, float, string, datetime.datetime, optional) The creation of a new UTCDateTime object depends from the given input parameters. All possible options are summarized in the Examples section below.
• iso8601 (boolean, optional) Enforce ISO8601:2004 detection. Works only with a string as first input argument.
• precision (int, optional) Sets the precision used by the rich comparison operators. Defaults to 6 digits after the decimal point. See also Precision section below.

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

UTCDateTime = UTCDateTime + delta

Adds/removes delta seconds (given as int or float) to/from the current UTCDateTime object and returns a new UTCDateTime object. See also: __add__().

delta = UTCDateTime - UTCDateTime

Calculates the time difference in seconds between two UTCDateTime objects. The time difference is given as float data type and may also contain a negative number. See also: __sub__().

Examples

1. 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)
   

2. 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)
     

3. 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)
   

4. 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)
   

5. 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)
   

6. 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,

1. 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
   

2. 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[, base]) -> integer
__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 microsecond 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 second 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.
fromDateTime	DEPRECATED: Please use UTCDateTime()._fromDateTime.
getDate	DEPRECATED: Please use UTCDateTime().date.
getDateTime	DEPRECATED: Please use UTCDateTime().datetime.
getDay	DEPRECATED: Please use UTCDateTime().day.
getHour	DEPRECATED: Please use UTCDateTime().hour.
getJulday	DEPRECATED: Please use UTCDateTime().julday.
getMicrosecond	DEPRECATED: Please use UTCDateTime().microsecond.
getMinute	DEPRECATED: Please use UTCDateTime().minute.
getMonth	DEPRECATED: Please use UTCDateTime().month.
getPrecision	DEPRECATED: Please use UTCDateTime().precision.
getSecond	DEPRECATED: Please use UTCDateTime().microsecond.
getTime	DEPRECATED: Please use UTCDateTime().time.
getTimeStamp	DEPRECATED: Please use UTCDateTime().timestamp.
getWeekday	DEPRECATED: Please use UTCDateTime().weekday.
getYear	DEPRECATED: Please use UTCDateTime().year.
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).
setPrecision	DEPRECATED: Please use UTCDateTime().precision.
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 microsecond 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 second 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.
_setPrecision	Set precision 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 ‘>’.
__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.