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