# obspy.core.utcdatetime.UTCDateTime

class `UTCDateTime`(*args, **kwargs)

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

### Thank you!

We would like to thank our contributors, whose efforts make this software what it is. These people have helped by writing code and documentation, and by testing. They have created and maintained this product, its associated libraries and applications, our build tools and our web sites.

#### Contributors

- Ackerley, Nick
- Allgeyer, Sebastien
- Ammon, Charles J.
- Antunes, Emanuel
- Arnarsson, Ólafur St.
- Bank, Markus
- Barsch, Robert
- Behr, Yannik
- Bernardi, Fabrizio
- Bernauer, Felix
- Bes de Berc, Maxime
- Beyreuther, Moritz
- Boltz, Shawn
- Bonaimé, Sébastien
- Carothers, Lloyd
- Chamberlain, Calum
- Chambers, Derrick
- Chen, Zhao
- Clark, Adam
- Danecek, Peter
- Egdorf, Sven
- Engels, Fabian
- Ermert, Laura
- Eulenfeld, Tom

- Fabbri, Tommaso
- Falco, Nicholas
- Fee, Jeremy
- Grellier, Clément
- Grunberg, Marc
- Hammer, Conny
- Heimann, Sebastian
- Heiniger, Lukas
- Hope, Gaute
- Igel, Heiner
- Inza, Adolfo
- Isken, Marius
- Ketchum, David
- Koymans, Mathijs
- Kremers, Simon
- Kress, Victor
- Krieger, Lars
- Krischer, Lion
- Kula, Damian
- Käufl, Paul
- Köhler, Andreas
- Lecocq, Thomas
- Leeman, John
- Legovini, Paride

- Lesage, Philippe
- Li, Yulin
- Lomax, Anthony
- Lopes, Rui L.
- MacCarthy, Jonathan
- Maggi, Alessia
- Martin, Henri
- Medlin, Andrew
- Megies, Tobias
- Meschede, Matthias
- Michelini, Alberto
- Miller, Nathaniel C.
- Morgenstern, Bernhard
- Nof, Ran Novitsky
- Panning, Mark P.
- Parker, Tom
- Pestourie, Romain
- Rapagnani, Giovanni
- Reyes, Celso
- Ringler, Adam
- Rothenhäusler, Nicolas
- Russo, Emiliano
- Sales de Andrade, Elliott

- Satriano, Claudio
- Saul, Joachim
- Scheingraber, Chris
- Schneider, Simon
- Sippl, Christian
- Snoke, Arthur
- Stange, Stefan
- Stähler, Simon C.
- Sullivan, Benjamin
- Tian, Dongdong
- Trabant, Chad
- Trani, Luca
- Uieda, Leonardo
- Walker, Andrew
- Walther, Marcus
- Wassermann, Joachim
- Williams, Mark C.
- Winkelman, Andrew
- Zaccarelli, Riccardo
- Zad, Seyed Kasra Hosseini
- Zhu, Lijun
- van Driel, Martin
- van Wijk, Kasper

#### Funds

ObsPy was partially funded by the

- German Science Foundation (DFG) via grant DFG IG 16/9-1
- German Ministry for Education and Research (BMBF), GEOTECHNOLOGIEN grant 03G0646H.
- NERA project (Network of European Research Infrastructures for Earthquake Risk Assessment and Mitigation) under the European Community's Seventh Framework Programme (FP7/2007-2013) grant agreement n° 262330
- Leibniz Institute for Applied Geophysics (LIAG)
- VERCE EU-FP7 project (no. 283543)