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

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

__dict__

__doc__

__module__

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

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.

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.

_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

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

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

__init_subclass__

This method is called when a class is subclassed.

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

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