obspy.core.utcdatetime.UTCDateTime¶

class UTCDateTime(*args, **kwargs)[source]¶

Bases: builtins.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. Internally, the POSIX time is represented in nanoseconds as an integer, which allows higher precision than 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, str, 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 (bool or None, optional) Enforce/disable ISO8601:2004 mode. Defaults to None for auto detection. Works only with a string as first input argument. strict (bool, optional) If True, Conform to ISO8601:2004 limits on positional and keyword arguments. If False, allow hour, minute, second, and microsecond values to exceed 23, 59, 59, and 1_000_000 respectively. 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 1.1.0: UTCDateTime is no longer based on a single floating point value but rather an integer representing nanoseconds elapsed since midnight Coordinated Universal Time (UTC) of Thursday, January 1, 1970. An integer internal representation allows higher precision and more predictable behavior than a float representation.

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 enabled/disabled using the``iso8601`` parameter, the default is to attempt to auto-detect ISO8601 compliant strings.

   • 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)
     

   • Specifying time zones.

     >>> UTCDateTime('2019-09-18T+06')  # time zone is UTC+6
     UTCDateTime(2019, 9, 17, 18, 0)
     

     >>> UTCDateTime('2019-09-18T02-02')  # time zone is UTC-2
     UTCDateTime(2019, 9, 18, 4, 0)
     

     >>> UTCDateTime('2019-09-18T18:23:10.22-01')  # time zone is UTC-1
     UTCDateTime(2019, 9, 18, 19, 23, 10, 220000)
     

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)
   

   >>> UTCDateTime("1970/01/17 12:23:34")
   UTCDateTime(1970, 1, 17, 12, 23, 34)
   

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 Julian day are required. This is the only input mode that supports using hour, minute, or second values above the natural limits of 24, 60, 60, respectively.

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

7. Using strict=False the limits of hour, minute, and second become more flexible:

   >>> UTCDateTime(year=1970, month=1, day=1, hour=48, strict=False)
   UTCDateTime(1970, 1, 3, 0, 0)
   

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 behavior either by,

1. using the precision keyword during object initialization (preferred):

   >>> dt = UTCDateTime(0, precision=4)
   >>> dt2 = UTCDateTime(0.00001, precision=4)
   >>> print(dt.precision)
   4
   >>> dt == dt2
   True
   

2. or by setting the class attribute DEFAULT_PRECISION to the desired precision to affect all new UTCDateTime objects (not recommended):

   >>> 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) -> integer
__dict__
__doc__	str(object=’‘) -> str
__module__	str(object=’‘) -> str
__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.
matplotlib_date	Maplotlib date number representation.
microsecond	Returns microseconds as an integer.
minute	Returns minute as an integer.
month	Returns month as an integer (January is 1, December is 12).
ns	Returns POSIX timestamp as integer nanoseconds.
precision	Returns precision of current UTCDateTime object.
second	Returns seconds as an integer.
time	Returns a Python time object.
timestamp	Returns UTC timestamp in seconds.
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)
format_arclink	Returns string representation for the ArcLink protocol.
format_fissures	Returns string representation for the IRIS Fissures protocol.
format_iris_web_service	Returns string representation usable for the IRIS Web services.
format_seed	Returns string representation for a SEED volume.
format_seedlink	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).
now	Returns current UTC datetime.
replace	Return a new UTCDateTime object with one or more parameters replaced.
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)
utcnow	Returns current UTC datetime.
utcoffset	Returns None (to stay compatible with datetime.datetime)
utctimetuple	Return a time.struct_time of current UTCDateTime object.

Private Methods

Warning

Private methods are mainly for internal/developer use and their API might change without notice.

_from_datetime	Use Python datetime object to set current time.
_from_iso8601_string	Parses an ISO8601:2004 date time string.
_from_timestamp	Use given timestamp to set current time.
_get_date	Returns a Python date object..
_get_datetime	Returns a Python datetime object.
_get_day	Returns day as an integer.
_get_hour	Returns hour as an integer.
_get_hours_after_midnight	Calculate foating point hours after midnight.
_get_julday	Returns Julian day as an integer.
_get_microsecond	Returns microseconds as an integer.
_get_minute	Returns minute as an integer.
_get_month	Returns month as an integer (January is 1, December is 12).
_get_ns	Returns POSIX timestamp as integer nanoseconds.
_get_precision	Returns precision of current UTCDateTime object.
_get_second	Returns seconds as an integer.
_get_time	Returns a Python time object.
_get_timestamp	Returns UTC timestamp in seconds.
_get_weekday	Return the day of the week as an integer (Monday is 0, Sunday is 6).
_get_year	Returns year of the current UTCDateTime object.
_handle_overflow	Handles setting date if an overflow of usual value limits is detected.
_operate
_repr_pretty_
_set	Sets current timestamp using kwargs.
_set_day	Sets day of current UTCDateTime object.
_set_hour	Sets hours of current UTCDateTime object.
_set_julday	Sets Julian day of current UTCDateTime object.
_set_microsecond	Sets microseconds of current UTCDateTime object.
_set_minute	Sets minutes of current UTCDateTime object.
_set_month	Sets month of current UTCDateTime object.
_set_ns	Set UTCDateTime object from POSIX timestamp as integer nanoseconds.
_set_precision	Set precision of current UTCDateTime object.
_set_second	Sets seconds of current UTCDateTime object.
_set_year	Sets year of current UTCDateTime object.
_strftime_replacement	Replace all simple, year-independent strftime commands

Special Methods

__abs__	Returns absolute timestamp value of the current UTCDateTime object.
__add__	Adds seconds and microseconds to current UTCDateTime object.
__dir__	default dir() implementation
__eq__	Rich comparison operator ‘==’.
__float__	Returns UTC timestamp in seconds.
__format__	default object formatter
__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 ‘!=’.
__new__	Create and return a new object.
__reduce__	helper for pickle
__reduce_ex__	helper for pickle
__repr__	Returns a representation of UTCDatetime object.
__setattr__
__sizeof__	size of object in memory, in bytes
__str__	Returns ISO8601 string representation from current UTCDateTime object.
__sub__	Subtracts seconds and microseconds from current UTCDateTime object.
__subclasshook__	Abstract classes can override this to customize issubclass().
__unicode__	Returns ISO8601 unicode representation from current UTCDateTime object.