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 currentUTCDateTime
object and returns a newUTCDateTime
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
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)
>>> UTCDateTime("1970/01/17 12:23:34") UTCDateTime(1970, 1, 17, 12, 23, 34)
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 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)
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 of6
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,
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 newUTCDateTime
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. - args (int, float, str,