obspy.core.utcdatetime.UTCDateTime

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

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. 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)
      
      >>> UTCDateTime("2009360T")                    # compact no time
      UTCDateTime(2009, 12, 26, 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

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 given format.

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.

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.

UTCDateTime._from_datetime(dt)[source]

Use Python datetime object to set current time.

Parameters:

dt (datetime.datetime) – Python datetime object.

UTCDateTime._from_iso8601_string(value)[source]

Parses an ISO8601:2004 date time string.

UTCDateTime._from_timestamp(value)[source]

Use given timestamp to set current time.

Parameters:

value (int, float) – Timestamp in seconds.

UTCDateTime._get_date()[source]

Returns a Python date object..

Return type:

datetime.date

Returns:

Python date object.

Example

>>> dt = UTCDateTime(2008, 10, 1, 12, 30, 35, 45020)
>>> dt.date
datetime.date(2008, 10, 1)
UTCDateTime._get_datetime()[source]

Returns a Python datetime object.

Return type:

datetime.datetime

Returns:

Python datetime object.

Example

>>> dt = UTCDateTime(2008, 10, 1, 12, 30, 35, 45020)
>>> dt.datetime
datetime.datetime(2008, 10, 1, 12, 30, 35, 45020)
UTCDateTime._get_day()[source]

Returns day as an integer.

Return type:

int

Returns:

Returns day as an integer.

Example

>>> dt = UTCDateTime(2012, 2, 11)
>>> dt.day
11
UTCDateTime._get_hour()[source]

Returns hour as an integer.

Return type:

int

Returns:

Returns hour as an integer.

Example

>>> dt = UTCDateTime(2012, 2, 11, 10, 11, 12)
>>> dt.hour
10
UTCDateTime._get_hours_after_midnight()[source]

Calculate foating point hours after midnight.

>>> t = UTCDateTime("2015-09-27T03:16:12.123456Z")
>>> t._get_hours_after_midnight()
3.270034293333333
UTCDateTime._get_julday()[source]

Returns Julian day as an integer.

Return type:

int

Returns:

Julian day as an integer.

Example

>>> dt = UTCDateTime(2008, 10, 1, 12, 30, 35, 45020)
>>> dt.julday
275
UTCDateTime._get_microsecond()[source]

Returns microseconds as an integer.

Return type:

int

Returns:

Returns microseconds as an integer.

Example

>>> dt = UTCDateTime(2012, 2, 11, 10, 11, 12, 345234)
>>> dt.microsecond
345234
UTCDateTime._get_minute()[source]

Returns minute as an integer.

Return type:

int

Returns:

Returns minute as an integer.

Example

>>> dt = UTCDateTime(2012, 2, 11, 10, 11, 12)
>>> dt.minute
11
UTCDateTime._get_month()[source]

Returns month as an integer (January is 1, December is 12).

Return type:

int

Returns:

Returns month as an integer, where January is 1 and December is 12.

Example

>>> dt = UTCDateTime(2012, 2, 11)
>>> dt.month
2
UTCDateTime._get_ns()[source]

Returns POSIX timestamp as integer nanoseconds.

This is the internal representation of UTCDateTime objects.

Return type:

int

Returns:

POSIX timestamp as integer nanoseconds

UTCDateTime._get_precision()[source]

Returns precision of current UTCDateTime object.

Returns:

int

Example

>>> dt = UTCDateTime()
>>> dt.precision
6
UTCDateTime._get_second()[source]

Returns seconds as an integer.

Return type:

int

Returns:

Returns seconds as an integer.

Example

>>> dt = UTCDateTime(2012, 2, 11, 10, 11, 12)
>>> dt.second
12
UTCDateTime._get_time()[source]

Returns a Python time object.

Return type:

datetime.time

Returns:

Python time object.

Example

>>> dt = UTCDateTime(2008, 10, 1, 12, 30, 35, 45020)
>>> dt.time
datetime.time(12, 30, 35, 45020)
UTCDateTime._get_timestamp()[source]

Returns UTC timestamp in seconds.

Return type:

float

Returns:

Timestamp in seconds.

Example

>>> dt = UTCDateTime(2008, 10, 1, 12, 30, 35, 123456)
>>> dt.timestamp
1222864235.123456
UTCDateTime._get_weekday()[source]

Return the day of the week as an integer (Monday is 0, Sunday is 6).

Return type:

int

Returns:

Returns day of the week as an integer, where Monday is 0 and Sunday is 6.

Example

>>> dt = UTCDateTime(2008, 10, 1, 12, 30, 35, 45020)
>>> dt.weekday
2
UTCDateTime._get_year()[source]

Returns year of the current UTCDateTime object.

Return type:

int

Returns:

Returns year as an integer.

Example

>>> dt = UTCDateTime(2012, 2, 11)
>>> dt.year
2012
UTCDateTime._handle_overflow(year, month, day, hour=0, minute=0, second=0, microsecond=0)[source]

Handles setting date if an overflow of usual value limits is detected.

UTCDateTime._operate(other, op_func)[source]
UTCDateTime._repr_pretty_(p, cycle)[source]
UTCDateTime._set(**kwargs)[source]

Sets current timestamp using kwargs.

UTCDateTime._set_day(value)[source]

Sets day of current UTCDateTime object.

Parameters:

value (int) – Day

UTCDateTime._set_hour(value)[source]

Sets hours of current UTCDateTime object.

Parameters:

value (int) – Hours

UTCDateTime._set_julday(value)[source]

Sets Julian day of current UTCDateTime object.

Parameters:

value (int) – Julian day

UTCDateTime._set_microsecond(value)[source]

Sets microseconds of current UTCDateTime object.

Parameters:

value (int) – Microseconds

UTCDateTime._set_minute(value)[source]

Sets minutes of current UTCDateTime object.

Parameters:

value (int) – Minutes

UTCDateTime._set_month(value)[source]

Sets month of current UTCDateTime object.

Parameters:

value (int) – Month

UTCDateTime._set_ns(value)[source]

Set UTCDateTime object from POSIX timestamp as integer nanoseconds.

Parameters:

value (int) – POSIX timestamp as integer nanoseconds

UTCDateTime._set_precision(value=6)[source]

Set precision of current UTCDateTime object.

Parameters:

value (int, optional) – Precision value used by the rich comparison operators. Defaults to 6.

Example

  1. Default precision

    >>> dt = UTCDateTime()
    >>> dt.precision
    6
    
  2. Set precision during initialization of UTCDateTime object.

    >>> dt = UTCDateTime(precision=5)
    >>> dt.precision
    5
    
UTCDateTime._set_second(value)[source]

Sets seconds of current UTCDateTime object.

Parameters:

value (int) – Seconds

UTCDateTime._set_year(value)[source]

Sets year of current UTCDateTime object.

Parameters:

value (int) – Year

Special Methods

UTCDateTime.__abs__()[source]

Returns absolute timestamp value of the current UTCDateTime object.

UTCDateTime.__add__(value)[source]

Adds seconds and microseconds to current UTCDateTime object.

Parameters:

value (int, float) – Seconds to add

Return type:

UTCDateTime

Returns:

New UTCDateTime object.

Example

>>> dt = UTCDateTime(1970, 1, 1, 0, 0)
>>> dt + 2
UTCDateTime(1970, 1, 1, 0, 0, 2)
>>> UTCDateTime(1970, 1, 1, 0, 0) + 1.123456
UTCDateTime(1970, 1, 1, 0, 0, 1, 123456)
UTCDateTime.__delattr__(name, /)

Implement delattr(self, name).

UTCDateTime.__dir__()

Default dir() implementation.

UTCDateTime.__eq__(other)[source]

Rich comparison operator ‘==’.

Comparing two UTCDateTime objects will compare the nanoseconds integers rounded to a number of significant digits determined by the precision attribute.

>>> t1 = UTCDateTime(123.000000012)
>>> t2 = UTCDateTime(123.000000099)
>>> t1 == t2
True

Defining a higher precision changes the behavior of the operator

>>> t1 = UTCDateTime(123.000000012, precision=9)
>>> t2 = UTCDateTime(123.000000099, precision=9)
>>> t1 == t2
False
UTCDateTime.__float__()[source]

Returns UTC timestamp in seconds.

Return type:

float

Returns:

Timestamp in seconds.

Example

>>> dt = UTCDateTime(2008, 10, 1, 12, 30, 35, 123456)
>>> float(dt)
1222864235.123456
UTCDateTime.__format__(format_spec, /)

Default object formatter.

UTCDateTime.__ge__(other)[source]

Rich comparison operator ‘>=’.

Comparing two UTCDateTime objects will compare the nanoseconds integers rounded to a number of significant digits determined by the precision attribute.

>>> t1 = UTCDateTime(123.000000012)
>>> t2 = UTCDateTime(123.000000099)
>>> t1 >= t2
True

Defining a higher precision changes the behavior of the operator

>>> t1 = UTCDateTime(123.000000012, precision=9)
>>> t2 = UTCDateTime(123.000000099, precision=9)
>>> t1 >= t2
False
UTCDateTime.__getattribute__(name, /)

Return getattr(self, name).

UTCDateTime.__gt__(other)[source]

Rich comparison operator ‘>’.

Comparing two UTCDateTime objects will compare the nanoseconds integers rounded to a number of significant digits determined by the precision attribute.

>>> t1 = UTCDateTime(123.000000099)
>>> t2 = UTCDateTime(123.000000012)
>>> t1 > t2
False

Defining a higher precision changes the behavior of the operator

>>> t1 = UTCDateTime(123.000000099, precision=9)
>>> t2 = UTCDateTime(123.000000012, precision=9)
>>> t1 > t2
True
UTCDateTime.__hash__()[source]

An object is hashable if it has a hash value which never changes during its lifetime. As an UTCDateTime object may change over time, it’s not hashable. Use the datetime() method to generate a datetime.datetime object for hashing. But be aware: once the UTCDateTime object changes, the hash is not valid anymore.

UTCDateTime.__init__(*args, **kwargs)[source]

Creates a new UTCDateTime object.

UTCDateTime.__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

UTCDateTime.__le__(other)[source]

Rich comparison operator ‘<=’.

Comparing two UTCDateTime objects will compare the nanoseconds integers rounded to a number of significant digits determined by the precision attribute.

>>> t1 = UTCDateTime(123.000000099)
>>> t2 = UTCDateTime(123.000000012)
>>> t1 <= t2
True

Defining a higher precision changes the behavior of the operator

>>> t1 = UTCDateTime(123.000000099, precision=9)
>>> t2 = UTCDateTime(123.000000012, precision=9)
>>> t1 <= t2
False
UTCDateTime.__lt__(other)[source]

Rich comparison operator ‘<’.

Comparing two UTCDateTime objects will compare the nanoseconds integers rounded to a number of significant digits determined by the precision attribute.

>>> t1 = UTCDateTime(123.000000012)
>>> t2 = UTCDateTime(123.000000099)
>>> t1 < t2
False

Defining a higher precision changes the behavior of the operator

>>> t1 = UTCDateTime(123.000000012, precision=9)
>>> t2 = UTCDateTime(123.000000099, precision=9)
>>> t1 < t2
True
UTCDateTime.__ne__(other)[source]

Rich comparison operator ‘!=’.

Comparing two UTCDateTime objects will compare the nanoseconds integers rounded to a number of significant digits determined by the precision attribute.

>>> t1 = UTCDateTime(123.000000012)
>>> t2 = UTCDateTime(123.000000099)
>>> t1 == t2
True

Defining a higher precision changes the behavior of the operator

>>> t1 = UTCDateTime(123.000000012, precision=9)
>>> t2 = UTCDateTime(123.000000099, precision=9)
>>> t1 == t2
False
UTCDateTime.__new__(**kwargs)
UTCDateTime.__reduce__()

Helper for pickle.

UTCDateTime.__reduce_ex__(protocol, /)

Helper for pickle.

UTCDateTime.__repr__()[source]

Returns a representation of UTCDatetime object.

UTCDateTime.__setattr__(key, value)[source]
UTCDateTime.__sizeof__()

Size of object in memory, in bytes.

UTCDateTime.__str__()[source]

Returns ISO8601 string representation from current UTCDateTime object.

Returns:

string

Example

>>> dt = UTCDateTime(2008, 10, 1, 12, 30, 35, 45020)
>>> str(dt)
'2008-10-01T12:30:35.045020Z'
UTCDateTime.__sub__(value)[source]

Subtracts seconds and microseconds from current UTCDateTime object.

Parameters:

value (int, float or UTCDateTime) – Seconds or UTCDateTime object to subtract. Subtracting an UTCDateTime objects results into a relative time span in seconds.

Return type:

UTCDateTime or float

Returns:

New UTCDateTime object or relative time span in seconds.

Example

>>> dt = UTCDateTime(1970, 1, 2, 0, 0)
>>> dt - 2
UTCDateTime(1970, 1, 1, 23, 59, 58)
>>> UTCDateTime(1970, 1, 2, 0, 0) - 1.123456
UTCDateTime(1970, 1, 1, 23, 59, 58, 876544)
>>> UTCDateTime(1970, 1, 2, 0, 0) - UTCDateTime(1970, 1, 1, 0, 0)
86400.0
UTCDateTime.__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

UTCDateTime.__unicode__()[source]

Returns ISO8601 unicode representation from current UTCDateTime object.

Returns:

string

Example

>>> dt = UTCDateTime(2008, 10, 1, 12, 30, 35, 45020)
>>> dt.__unicode__()
'2008-10-01T12:30:35.045020Z'