rfc2579_date_time.py 7.25 KB
Newer Older
1 2 3
# -*- coding: utf-8 -*-
"""RFC2579 date-time implementation."""

4 5
from __future__ import unicode_literals

6 7
import decimal

8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
from dfdatetime import definitions
from dfdatetime import interface


class RFC2579DateTime(interface.DateTimeValues):
  """RFC2579 date-time.

  The RFC2579 date-time structure is 11 bytes of size and contains:

  struct {
      uin16_t year,
      uint8_t month,
      uint8_t day_of_month,
      uint8_t hours,
      uint8_t minutes,
      uint8_t seconds,
      uint8_t deciseconds,
      char direction_from_utc,
      uint8_t hours_from_utc,
      uint8_t minuted_from_utc
  }

  Also see:
    https://tools.ietf.org/html/rfc2579

  Attributes:
    year (int): year, 0 through 65536.
    month (int): month of year, 1 through 12.
    day_of_month (int): day of month, 1 through 31.
    hours (int): hours, 0 through 23.
    minutes (int): minutes, 0 through 59.
    seconds (int): seconds, 0 through 59, where 60 is used to represent
        a leap-second.
    deciseconds (int): deciseconds, 0 through 9.
  """

44 45
  # TODO: make attributes read-only.

46 47 48 49 50 51 52 53 54 55 56 57 58 59
  def __init__(self, rfc2579_date_time_tuple=None):
    """Initializes a RFC2579 date-time.

    Args:
      rfc2579_date_time_tuple:
          (Optional[tuple[int, int, int, int, int, int, int]]):
          RFC2579 date-time time, contains year, month, day of month, hours,
          minutes, seconds and deciseconds.

    Raises:
      ValueError: if the system time is invalid.
    """
    super(RFC2579DateTime, self).__init__()
    self._number_of_seconds = None
60
    self._precision = definitions.PRECISION_100_MILLISECONDS
61 62 63 64 65 66 67 68 69 70 71
    self.day_of_month = None
    self.hours = None
    self.deciseconds = None
    self.minutes = None
    self.month = None
    self.seconds = None
    self.year = None

    if rfc2579_date_time_tuple:
      if len(rfc2579_date_time_tuple) < 10:
        raise ValueError(
72
            'Invalid RFC2579 date-time tuple 10 elements required.')
73 74

      if rfc2579_date_time_tuple[0] < 0 or rfc2579_date_time_tuple[0] > 65536:
75
        raise ValueError('Year value out of bounds.')
76 77

      if rfc2579_date_time_tuple[1] not in range(1, 13):
78
        raise ValueError('Month value out of bounds.')
79 80 81 82 83

      days_per_month = self._GetDaysPerMonth(
          rfc2579_date_time_tuple[0], rfc2579_date_time_tuple[1])
      if (rfc2579_date_time_tuple[2] < 1 or
          rfc2579_date_time_tuple[2] > days_per_month):
84
        raise ValueError('Day of month value out of bounds.')
85 86

      if rfc2579_date_time_tuple[3] not in range(0, 24):
87
        raise ValueError('Hours value out of bounds.')
88 89

      if rfc2579_date_time_tuple[4] not in range(0, 60):
90
        raise ValueError('Minutes value out of bounds.')
91 92 93

      # TODO: support a leap second?
      if rfc2579_date_time_tuple[5] not in range(0, 60):
94
        raise ValueError('Seconds value out of bounds.')
95 96

      if rfc2579_date_time_tuple[6] < 0 or rfc2579_date_time_tuple[6] > 9:
97
        raise ValueError('Deciseconds value out of bounds.')
98

99 100
      if rfc2579_date_time_tuple[7] not in ('+', '-'):
        raise ValueError('Direction from UTC value out of bounds.')
101 102

      if rfc2579_date_time_tuple[8] not in range(0, 14):
103
        raise ValueError('Hours from UTC value out of bounds.')
104 105

      if rfc2579_date_time_tuple[9] not in range(0, 60):
106
        raise ValueError('Minutes from UTC value out of bounds.')
107 108 109 110 111 112

      time_zone_offset = (
          (rfc2579_date_time_tuple[8] * 60) + rfc2579_date_time_tuple[9])

      # Note that when the sign of the time zone offset is negative
      # the difference needs to be added. We do so by flipping the sign.
113
      if rfc2579_date_time_tuple[7] != '-':
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
        time_zone_offset = -time_zone_offset

      self.year, self.month, self.day_of_month, self.hours, self.minutes = (
          self._AdjustForTimeZoneOffset(
              rfc2579_date_time_tuple[0], rfc2579_date_time_tuple[1],
              rfc2579_date_time_tuple[2], rfc2579_date_time_tuple[3],
              rfc2579_date_time_tuple[4], time_zone_offset))

      self.deciseconds = rfc2579_date_time_tuple[6]
      self.seconds = rfc2579_date_time_tuple[5]

      self._number_of_seconds = self._GetNumberOfSecondsFromElements(
          self.year, self.month, self.day_of_month, self.hours, self.minutes,
          self.seconds)

129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
  def _GetNormalizedTimestamp(self):
    """Retrieves the normalized timestamp.

    Returns:
      decimal.Decimal: normalized timestamp, which contains the number of
          seconds since January 1, 1970 00:00:00 and a fraction of second used
          for increased precision, or None if the normalized timestamp cannot be
          determined.
    """
    if self._normalized_timestamp is None:
      if self._number_of_seconds is not None:
        self._normalized_timestamp = (
            decimal.Decimal(self.deciseconds) /
            definitions.DECISECONDS_PER_SECOND)
        self._normalized_timestamp += decimal.Decimal(self._number_of_seconds)

    return self._normalized_timestamp

147
  def CopyFromDateTimeString(self, time_string):
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
    """Copies a RFC2579 date-time from a date and time string.

    Args:
      time_string (str): date and time value formatted as:
          YYYY-MM-DD hh:mm:ss.######[+-]##:##

          Where # are numeric digits ranging from 0 to 9 and the seconds
          fraction can be either 3 or 6 digits. The time of day, seconds
          fraction and time zone offset are optional. The default time zone
          is UTC.

    Raises:
      ValueError: if the date string is invalid or not supported.
    """
    date_time_values = self._CopyDateTimeFromString(time_string)

164 165 166 167 168 169
    year = date_time_values.get('year', 0)
    month = date_time_values.get('month', 0)
    day_of_month = date_time_values.get('day_of_month', 0)
    hours = date_time_values.get('hours', 0)
    minutes = date_time_values.get('minutes', 0)
    seconds = date_time_values.get('seconds', 0)
170

171
    microseconds = date_time_values.get('microseconds', 0)
172 173
    deciseconds, _ = divmod(
        microseconds, definitions.MICROSECONDS_PER_DECISECOND)
174 175

    if year < 0 or year > 65536:
176
      raise ValueError('Unsupported year value: {0:d}.'.format(year))
177

178
    self._normalized_timestamp = None
179 180 181 182 183 184 185 186 187 188 189 190 191
    self._number_of_seconds = self._GetNumberOfSecondsFromElements(
        year, month, day_of_month, hours, minutes, seconds)

    self.year = year
    self.month = month
    self.day_of_month = day_of_month
    self.hours = hours
    self.minutes = minutes
    self.seconds = seconds
    self.deciseconds = deciseconds

    self.is_local_time = False

192 193 194 195
  def CopyToDateTimeString(self):
    """Copies the RFC2579 date-time to a date and time string.

    Returns:
196 197
      str: date and time value formatted as: "YYYY-MM-DD hh:mm:ss.#" or
          None if the number of seconds is missing.
198 199
    """
    if self._number_of_seconds is None:
200
      return None
201

202
    return '{0:04d}-{1:02d}-{2:02d} {3:02d}:{4:02d}:{5:02d}.{6:01d}'.format(
203
        self.year, self.month, self.day_of_month, self.hours, self.minutes,
204
        self.seconds, self.deciseconds)
205

206 207
  def GetDate(self):
    """Retrieves the date represented by the date and time values.
208 209

    Returns:
210 211
       tuple[int, int, int]: year, month, day of month or (None, None, None)
           if the date and time values do not represent a date.
212 213
    """
    if self._number_of_seconds is None:
214
      return None, None, None
215

216
    return self.year, self.month, self.day_of_month