You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

406 lines
13 KiB

4 years ago
  1. # -*- coding: utf-8 -*-
  2. """
  3. This module offers a parser for ISO-8601 strings
  4. It is intended to support all valid date, time and datetime formats per the
  5. ISO-8601 specification.
  6. ..versionadded:: 2.7.0
  7. """
  8. from datetime import datetime, timedelta, time, date
  9. import calendar
  10. from dateutil import tz
  11. from functools import wraps
  12. import re
  13. import six
  14. __all__ = ["isoparse", "isoparser"]
  15. def _takes_ascii(f):
  16. @wraps(f)
  17. def func(self, str_in, *args, **kwargs):
  18. # If it's a stream, read the whole thing
  19. str_in = getattr(str_in, 'read', lambda: str_in)()
  20. # If it's unicode, turn it into bytes, since ISO-8601 only covers ASCII
  21. if isinstance(str_in, six.text_type):
  22. # ASCII is the same in UTF-8
  23. try:
  24. str_in = str_in.encode('ascii')
  25. except UnicodeEncodeError as e:
  26. msg = 'ISO-8601 strings should contain only ASCII characters'
  27. six.raise_from(ValueError(msg), e)
  28. return f(self, str_in, *args, **kwargs)
  29. return func
  30. class isoparser(object):
  31. def __init__(self, sep=None):
  32. """
  33. :param sep:
  34. A single character that separates date and time portions. If
  35. ``None``, the parser will accept any single character.
  36. For strict ISO-8601 adherence, pass ``'T'``.
  37. """
  38. if sep is not None:
  39. if (len(sep) != 1 or ord(sep) >= 128 or sep in '0123456789'):
  40. raise ValueError('Separator must be a single, non-numeric ' +
  41. 'ASCII character')
  42. sep = sep.encode('ascii')
  43. self._sep = sep
  44. @_takes_ascii
  45. def isoparse(self, dt_str):
  46. """
  47. Parse an ISO-8601 datetime string into a :class:`datetime.datetime`.
  48. An ISO-8601 datetime string consists of a date portion, followed
  49. optionally by a time portion - the date and time portions are separated
  50. by a single character separator, which is ``T`` in the official
  51. standard. Incomplete date formats (such as ``YYYY-MM``) may *not* be
  52. combined with a time portion.
  53. Supported date formats are:
  54. Common:
  55. - ``YYYY``
  56. - ``YYYY-MM`` or ``YYYYMM``
  57. - ``YYYY-MM-DD`` or ``YYYYMMDD``
  58. Uncommon:
  59. - ``YYYY-Www`` or ``YYYYWww`` - ISO week (day defaults to 0)
  60. - ``YYYY-Www-D`` or ``YYYYWwwD`` - ISO week and day
  61. The ISO week and day numbering follows the same logic as
  62. :func:`datetime.date.isocalendar`.
  63. Supported time formats are:
  64. - ``hh``
  65. - ``hh:mm`` or ``hhmm``
  66. - ``hh:mm:ss`` or ``hhmmss``
  67. - ``hh:mm:ss.sss`` or ``hh:mm:ss.ssssss`` (3-6 sub-second digits)
  68. Midnight is a special case for `hh`, as the standard supports both
  69. 00:00 and 24:00 as a representation.
  70. .. caution::
  71. Support for fractional components other than seconds is part of the
  72. ISO-8601 standard, but is not currently implemented in this parser.
  73. Supported time zone offset formats are:
  74. - `Z` (UTC)
  75. - `±HH:MM`
  76. - `±HHMM`
  77. - `±HH`
  78. Offsets will be represented as :class:`dateutil.tz.tzoffset` objects,
  79. with the exception of UTC, which will be represented as
  80. :class:`dateutil.tz.tzutc`. Time zone offsets equivalent to UTC (such
  81. as `+00:00`) will also be represented as :class:`dateutil.tz.tzutc`.
  82. :param dt_str:
  83. A string or stream containing only an ISO-8601 datetime string
  84. :return:
  85. Returns a :class:`datetime.datetime` representing the string.
  86. Unspecified components default to their lowest value.
  87. .. warning::
  88. As of version 2.7.0, the strictness of the parser should not be
  89. considered a stable part of the contract. Any valid ISO-8601 string
  90. that parses correctly with the default settings will continue to
  91. parse correctly in future versions, but invalid strings that
  92. currently fail (e.g. ``2017-01-01T00:00+00:00:00``) are not
  93. guaranteed to continue failing in future versions if they encode
  94. a valid date.
  95. .. versionadded:: 2.7.0
  96. """
  97. components, pos = self._parse_isodate(dt_str)
  98. if len(dt_str) > pos:
  99. if self._sep is None or dt_str[pos:pos + 1] == self._sep:
  100. components += self._parse_isotime(dt_str[pos + 1:])
  101. else:
  102. raise ValueError('String contains unknown ISO components')
  103. return datetime(*components)
  104. @_takes_ascii
  105. def parse_isodate(self, datestr):
  106. """
  107. Parse the date portion of an ISO string.
  108. :param datestr:
  109. The string portion of an ISO string, without a separator
  110. :return:
  111. Returns a :class:`datetime.date` object
  112. """
  113. components, pos = self._parse_isodate(datestr)
  114. if pos < len(datestr):
  115. raise ValueError('String contains unknown ISO ' +
  116. 'components: {}'.format(datestr))
  117. return date(*components)
  118. @_takes_ascii
  119. def parse_isotime(self, timestr):
  120. """
  121. Parse the time portion of an ISO string.
  122. :param timestr:
  123. The time portion of an ISO string, without a separator
  124. :return:
  125. Returns a :class:`datetime.time` object
  126. """
  127. return time(*self._parse_isotime(timestr))
  128. @_takes_ascii
  129. def parse_tzstr(self, tzstr, zero_as_utc=True):
  130. """
  131. Parse a valid ISO time zone string.
  132. See :func:`isoparser.isoparse` for details on supported formats.
  133. :param tzstr:
  134. A string representing an ISO time zone offset
  135. :param zero_as_utc:
  136. Whether to return :class:`dateutil.tz.tzutc` for zero-offset zones
  137. :return:
  138. Returns :class:`dateutil.tz.tzoffset` for offsets and
  139. :class:`dateutil.tz.tzutc` for ``Z`` and (if ``zero_as_utc`` is
  140. specified) offsets equivalent to UTC.
  141. """
  142. return self._parse_tzstr(tzstr, zero_as_utc=zero_as_utc)
  143. # Constants
  144. _MICROSECOND_END_REGEX = re.compile(b'[-+Z]+')
  145. _DATE_SEP = b'-'
  146. _TIME_SEP = b':'
  147. _MICRO_SEP = b'.'
  148. def _parse_isodate(self, dt_str):
  149. try:
  150. return self._parse_isodate_common(dt_str)
  151. except ValueError:
  152. return self._parse_isodate_uncommon(dt_str)
  153. def _parse_isodate_common(self, dt_str):
  154. len_str = len(dt_str)
  155. components = [1, 1, 1]
  156. if len_str < 4:
  157. raise ValueError('ISO string too short')
  158. # Year
  159. components[0] = int(dt_str[0:4])
  160. pos = 4
  161. if pos >= len_str:
  162. return components, pos
  163. has_sep = dt_str[pos:pos + 1] == self._DATE_SEP
  164. if has_sep:
  165. pos += 1
  166. # Month
  167. if len_str - pos < 2:
  168. raise ValueError('Invalid common month')
  169. components[1] = int(dt_str[pos:pos + 2])
  170. pos += 2
  171. if pos >= len_str:
  172. if has_sep:
  173. return components, pos
  174. else:
  175. raise ValueError('Invalid ISO format')
  176. if has_sep:
  177. if dt_str[pos:pos + 1] != self._DATE_SEP:
  178. raise ValueError('Invalid separator in ISO string')
  179. pos += 1
  180. # Day
  181. if len_str - pos < 2:
  182. raise ValueError('Invalid common day')
  183. components[2] = int(dt_str[pos:pos + 2])
  184. return components, pos + 2
  185. def _parse_isodate_uncommon(self, dt_str):
  186. if len(dt_str) < 4:
  187. raise ValueError('ISO string too short')
  188. # All ISO formats start with the year
  189. year = int(dt_str[0:4])
  190. has_sep = dt_str[4:5] == self._DATE_SEP
  191. pos = 4 + has_sep # Skip '-' if it's there
  192. if dt_str[pos:pos + 1] == b'W':
  193. # YYYY-?Www-?D?
  194. pos += 1
  195. weekno = int(dt_str[pos:pos + 2])
  196. pos += 2
  197. dayno = 1
  198. if len(dt_str) > pos:
  199. if (dt_str[pos:pos + 1] == self._DATE_SEP) != has_sep:
  200. raise ValueError('Inconsistent use of dash separator')
  201. pos += has_sep
  202. dayno = int(dt_str[pos:pos + 1])
  203. pos += 1
  204. base_date = self._calculate_weekdate(year, weekno, dayno)
  205. else:
  206. # YYYYDDD or YYYY-DDD
  207. if len(dt_str) - pos < 3:
  208. raise ValueError('Invalid ordinal day')
  209. ordinal_day = int(dt_str[pos:pos + 3])
  210. pos += 3
  211. if ordinal_day < 1 or ordinal_day > (365 + calendar.isleap(year)):
  212. raise ValueError('Invalid ordinal day' +
  213. ' {} for year {}'.format(ordinal_day, year))
  214. base_date = date(year, 1, 1) + timedelta(days=ordinal_day - 1)
  215. components = [base_date.year, base_date.month, base_date.day]
  216. return components, pos
  217. def _calculate_weekdate(self, year, week, day):
  218. """
  219. Calculate the day of corresponding to the ISO year-week-day calendar.
  220. This function is effectively the inverse of
  221. :func:`datetime.date.isocalendar`.
  222. :param year:
  223. The year in the ISO calendar
  224. :param week:
  225. The week in the ISO calendar - range is [1, 53]
  226. :param day:
  227. The day in the ISO calendar - range is [1 (MON), 7 (SUN)]
  228. :return:
  229. Returns a :class:`datetime.date`
  230. """
  231. if not 0 < week < 54:
  232. raise ValueError('Invalid week: {}'.format(week))
  233. if not 0 < day < 8: # Range is 1-7
  234. raise ValueError('Invalid weekday: {}'.format(day))
  235. # Get week 1 for the specific year:
  236. jan_4 = date(year, 1, 4) # Week 1 always has January 4th in it
  237. week_1 = jan_4 - timedelta(days=jan_4.isocalendar()[2] - 1)
  238. # Now add the specific number of weeks and days to get what we want
  239. week_offset = (week - 1) * 7 + (day - 1)
  240. return week_1 + timedelta(days=week_offset)
  241. def _parse_isotime(self, timestr):
  242. len_str = len(timestr)
  243. components = [0, 0, 0, 0, None]
  244. pos = 0
  245. comp = -1
  246. if len(timestr) < 2:
  247. raise ValueError('ISO time too short')
  248. has_sep = len_str >= 3 and timestr[2:3] == self._TIME_SEP
  249. while pos < len_str and comp < 5:
  250. comp += 1
  251. if timestr[pos:pos + 1] in b'-+Z':
  252. # Detect time zone boundary
  253. components[-1] = self._parse_tzstr(timestr[pos:])
  254. pos = len_str
  255. break
  256. if comp < 3:
  257. # Hour, minute, second
  258. components[comp] = int(timestr[pos:pos + 2])
  259. pos += 2
  260. if (has_sep and pos < len_str and
  261. timestr[pos:pos + 1] == self._TIME_SEP):
  262. pos += 1
  263. if comp == 3:
  264. # Microsecond
  265. if timestr[pos:pos + 1] != self._MICRO_SEP:
  266. continue
  267. pos += 1
  268. us_str = self._MICROSECOND_END_REGEX.split(timestr[pos:pos + 6],
  269. 1)[0]
  270. components[comp] = int(us_str) * 10**(6 - len(us_str))
  271. pos += len(us_str)
  272. if pos < len_str:
  273. raise ValueError('Unused components in ISO string')
  274. if components[0] == 24:
  275. # Standard supports 00:00 and 24:00 as representations of midnight
  276. if any(component != 0 for component in components[1:4]):
  277. raise ValueError('Hour may only be 24 at 24:00:00.000')
  278. components[0] = 0
  279. return components
  280. def _parse_tzstr(self, tzstr, zero_as_utc=True):
  281. if tzstr == b'Z':
  282. return tz.tzutc()
  283. if len(tzstr) not in {3, 5, 6}:
  284. raise ValueError('Time zone offset must be 1, 3, 5 or 6 characters')
  285. if tzstr[0:1] == b'-':
  286. mult = -1
  287. elif tzstr[0:1] == b'+':
  288. mult = 1
  289. else:
  290. raise ValueError('Time zone offset requires sign')
  291. hours = int(tzstr[1:3])
  292. if len(tzstr) == 3:
  293. minutes = 0
  294. else:
  295. minutes = int(tzstr[(4 if tzstr[3:4] == self._TIME_SEP else 3):])
  296. if zero_as_utc and hours == 0 and minutes == 0:
  297. return tz.tzutc()
  298. else:
  299. if minutes > 59:
  300. raise ValueError('Invalid minutes in time zone offset')
  301. if hours > 23:
  302. raise ValueError('Invalid hours in time zone offset')
  303. return tz.tzoffset(None, mult * (hours * 60 + minutes) * 60)
  304. DEFAULT_ISOPARSER = isoparser()
  305. isoparse = DEFAULT_ISOPARSER.isoparse