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.ssssss`` (Up to 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. The decimal separator can be
95        either a dot or a comma.
96
97
98        .. caution::
99
100            Support for fractional components other than seconds is part of the
101            ISO-8601 standard, but is not currently implemented in this parser.
102
103        Supported time zone offset formats are:
104
105        - `Z` (UTC)
106        - `±HH:MM`
107        - `±HHMM`
108        - `±HH`
109
110        Offsets will be represented as :class:`dateutil.tz.tzoffset` objects,
111        with the exception of UTC, which will be represented as
112        :class:`dateutil.tz.tzutc`. Time zone offsets equivalent to UTC (such
113        as `+00:00`) will also be represented as :class:`dateutil.tz.tzutc`.
114
115        :param dt_str:
116            A string or stream containing only an ISO-8601 datetime string
117
118        :return:
119            Returns a :class:`datetime.datetime` representing the string.
120            Unspecified components default to their lowest value.
121
122        .. warning::
123
124            As of version 2.7.0, the strictness of the parser should not be
125            considered a stable part of the contract. Any valid ISO-8601 string
126            that parses correctly with the default settings will continue to
127            parse correctly in future versions, but invalid strings that
128            currently fail (e.g. ``2017-01-01T00:00+00:00:00``) are not
129            guaranteed to continue failing in future versions if they encode
130            a valid date.
131
132        .. versionadded:: 2.7.0
133        """
134        components, pos = self._parse_isodate(dt_str)
135
136        if len(dt_str) > pos:
137            if self._sep is None or dt_str[pos:pos + 1] == self._sep:
138                components += self._parse_isotime(dt_str[pos + 1:])
139            else:
140                raise ValueError('String contains unknown ISO components')
141
142        if len(components) > 3 and components[3] == 24:
143            components[3] = 0
144            return datetime(*components) + timedelta(days=1)
145
146        return datetime(*components)
147
148    @_takes_ascii
149    def parse_isodate(self, datestr):
150        """
151        Parse the date portion of an ISO string.
152
153        :param datestr:
154            The string portion of an ISO string, without a separator
155
156        :return:
157            Returns a :class:`datetime.date` object
158        """
159        components, pos = self._parse_isodate(datestr)
160        if pos < len(datestr):
161            raise ValueError('String contains unknown ISO ' +
162                             'components: {}'.format(datestr))
163        return date(*components)
164
165    @_takes_ascii
166    def parse_isotime(self, timestr):
167        """
168        Parse the time portion of an ISO string.
169
170        :param timestr:
171            The time portion of an ISO string, without a separator
172
173        :return:
174            Returns a :class:`datetime.time` object
175        """
176        components = self._parse_isotime(timestr)
177        if components[0] == 24:
178            components[0] = 0
179        return time(*components)
180
181    @_takes_ascii
182    def parse_tzstr(self, tzstr, zero_as_utc=True):
183        """
184        Parse a valid ISO time zone string.
185
186        See :func:`isoparser.isoparse` for details on supported formats.
187
188        :param tzstr:
189            A string representing an ISO time zone offset
190
191        :param zero_as_utc:
192            Whether to return :class:`dateutil.tz.tzutc` for zero-offset zones
193
194        :return:
195            Returns :class:`dateutil.tz.tzoffset` for offsets and
196            :class:`dateutil.tz.tzutc` for ``Z`` and (if ``zero_as_utc`` is
197            specified) offsets equivalent to UTC.
198        """
199        return self._parse_tzstr(tzstr, zero_as_utc=zero_as_utc)
200
201    # Constants
202    _DATE_SEP = b'-'
203    _TIME_SEP = b':'
204    _FRACTION_REGEX = re.compile(b'[\\.,]([0-9]+)')
205
206    def _parse_isodate(self, dt_str):
207        try:
208            return self._parse_isodate_common(dt_str)
209        except ValueError:
210            return self._parse_isodate_uncommon(dt_str)
211
212    def _parse_isodate_common(self, dt_str):
213        len_str = len(dt_str)
214        components = [1, 1, 1]
215
216        if len_str < 4:
217            raise ValueError('ISO string too short')
218
219        # Year
220        components[0] = int(dt_str[0:4])
221        pos = 4
222        if pos >= len_str:
223            return components, pos
224
225        has_sep = dt_str[pos:pos + 1] == self._DATE_SEP
226        if has_sep:
227            pos += 1
228
229        # Month
230        if len_str - pos < 2:
231            raise ValueError('Invalid common month')
232
233        components[1] = int(dt_str[pos:pos + 2])
234        pos += 2
235
236        if pos >= len_str:
237            if has_sep:
238                return components, pos
239            else:
240                raise ValueError('Invalid ISO format')
241
242        if has_sep:
243            if dt_str[pos:pos + 1] != self._DATE_SEP:
244                raise ValueError('Invalid separator in ISO string')
245            pos += 1
246
247        # Day
248        if len_str - pos < 2:
249            raise ValueError('Invalid common day')
250        components[2] = int(dt_str[pos:pos + 2])
251        return components, pos + 2
252
253    def _parse_isodate_uncommon(self, dt_str):
254        if len(dt_str) < 4:
255            raise ValueError('ISO string too short')
256
257        # All ISO formats start with the year
258        year = int(dt_str[0:4])
259
260        has_sep = dt_str[4:5] == self._DATE_SEP
261
262        pos = 4 + has_sep       # Skip '-' if it's there
263        if dt_str[pos:pos + 1] == b'W':
264            # YYYY-?Www-?D?
265            pos += 1
266            weekno = int(dt_str[pos:pos + 2])
267            pos += 2
268
269            dayno = 1
270            if len(dt_str) > pos:
271                if (dt_str[pos:pos + 1] == self._DATE_SEP) != has_sep:
272                    raise ValueError('Inconsistent use of dash separator')
273
274                pos += has_sep
275
276                dayno = int(dt_str[pos:pos + 1])
277                pos += 1
278
279            base_date = self._calculate_weekdate(year, weekno, dayno)
280        else:
281            # YYYYDDD or YYYY-DDD
282            if len(dt_str) - pos < 3:
283                raise ValueError('Invalid ordinal day')
284
285            ordinal_day = int(dt_str[pos:pos + 3])
286            pos += 3
287
288            if ordinal_day < 1 or ordinal_day > (365 + calendar.isleap(year)):
289                raise ValueError('Invalid ordinal day' +
290                                 ' {} for year {}'.format(ordinal_day, year))
291
292            base_date = date(year, 1, 1) + timedelta(days=ordinal_day - 1)
293
294        components = [base_date.year, base_date.month, base_date.day]
295        return components, pos
296
297    def _calculate_weekdate(self, year, week, day):
298        """
299        Calculate the day of corresponding to the ISO year-week-day calendar.
300
301        This function is effectively the inverse of
302        :func:`datetime.date.isocalendar`.
303
304        :param year:
305            The year in the ISO calendar
306
307        :param week:
308            The week in the ISO calendar - range is [1, 53]
309
310        :param day:
311            The day in the ISO calendar - range is [1 (MON), 7 (SUN)]
312
313        :return:
314            Returns a :class:`datetime.date`
315        """
316        if not 0 < week < 54:
317            raise ValueError('Invalid week: {}'.format(week))
318
319        if not 0 < day < 8:     # Range is 1-7
320            raise ValueError('Invalid weekday: {}'.format(day))
321
322        # Get week 1 for the specific year:
323        jan_4 = date(year, 1, 4)   # Week 1 always has January 4th in it
324        week_1 = jan_4 - timedelta(days=jan_4.isocalendar()[2] - 1)
325
326        # Now add the specific number of weeks and days to get what we want
327        week_offset = (week - 1) * 7 + (day - 1)
328        return week_1 + timedelta(days=week_offset)
329
330    def _parse_isotime(self, timestr):
331        len_str = len(timestr)
332        components = [0, 0, 0, 0, None]
333        pos = 0
334        comp = -1
335
336        if len(timestr) < 2:
337            raise ValueError('ISO time too short')
338
339        has_sep = len_str >= 3 and timestr[2:3] == self._TIME_SEP
340
341        while pos < len_str and comp < 5:
342            comp += 1
343
344            if timestr[pos:pos + 1] in b'-+Zz':
345                # Detect time zone boundary
346                components[-1] = self._parse_tzstr(timestr[pos:])
347                pos = len_str
348                break
349
350            if comp < 3:
351                # Hour, minute, second
352                components[comp] = int(timestr[pos:pos + 2])
353                pos += 2
354                if (has_sep and pos < len_str and
355                        timestr[pos:pos + 1] == self._TIME_SEP):
356                    pos += 1
357
358            if comp == 3:
359                # Fraction of a second
360                frac = self._FRACTION_REGEX.match(timestr[pos:])
361                if not frac:
362                    continue
363
364                us_str = frac.group(1)[:6]  # Truncate to microseconds
365                components[comp] = int(us_str) * 10**(6 - len(us_str))
366                pos += len(frac.group())
367
368        if pos < len_str:
369            raise ValueError('Unused components in ISO string')
370
371        if components[0] == 24:
372            # Standard supports 00:00 and 24:00 as representations of midnight
373            if any(component != 0 for component in components[1:4]):
374                raise ValueError('Hour may only be 24 at 24:00:00.000')
375
376        return components
377
378    def _parse_tzstr(self, tzstr, zero_as_utc=True):
379        if tzstr == b'Z' or tzstr == b'z':
380            return tz.tzutc()
381
382        if len(tzstr) not in {3, 5, 6}:
383            raise ValueError('Time zone offset must be 1, 3, 5 or 6 characters')
384
385        if tzstr[0:1] == b'-':
386            mult = -1
387        elif tzstr[0:1] == b'+':
388            mult = 1
389        else:
390            raise ValueError('Time zone offset requires sign')
391
392        hours = int(tzstr[1:3])
393        if len(tzstr) == 3:
394            minutes = 0
395        else:
396            minutes = int(tzstr[(4 if tzstr[3:4] == self._TIME_SEP else 3):])
397
398        if zero_as_utc and hours == 0 and minutes == 0:
399            return tz.tzutc()
400        else:
401            if minutes > 59:
402                raise ValueError('Invalid minutes in time zone offset')
403
404            if hours > 23:
405                raise ValueError('Invalid hours in time zone offset')
406
407            return tz.tzoffset(None, mult * (hours * 60 + minutes) * 60)
408
409
410DEFAULT_ISOPARSER = isoparser()
411isoparse = DEFAULT_ISOPARSER.isoparse
412