codekingpro/portable-devtools

1# -*- coding: utf-8 -*-2"""3This module offers a parser for ISO-8601 strings4 5It is intended to support all valid date, time and datetime formats per the6ISO-8601 specification.7 8..versionadded:: 2.7.09"""10from datetime import datetime, timedelta, time, date11import calendar12from dateutil import tz13 14from functools import wraps15 16import re17import six18 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 thing26        str_in = getattr(str_in, 'read', lambda: str_in)()27 28        # If it's unicode, turn it into bytes, since ISO-8601 only covers ASCII29        if isinstance(str_in, six.text_type):30            # ASCII is the same in UTF-831            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 func40 41 42class isoparser(object):43    def __init__(self, sep=None):44        """45        :param sep:46            A single character that separates date and time portions. If47            ``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 = sep58 59    @_takes_ascii60    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, followed65        optionally by a time portion - the date and time portions are separated66        by a single character separator, which is ``T`` in the official67        standard. Incomplete date formats (such as ``YYYY-MM``) may *not* be68        combined with a time portion.69 70        Supported date formats are:71 72        Common:73 74        - ``YYYY``75        - ``YYYY-MM``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 day82 83        The ISO week and day numbering follows the same logic as84        :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 both94        00:00 and 24:00 as a representation. The decimal separator can be95        either a dot or a comma.96 97 98        .. caution::99 100            Support for fractional components other than seconds is part of the101            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 as112        :class:`dateutil.tz.tzutc`. Time zone offsets equivalent to UTC (such113        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 string117 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 be125            considered a stable part of the contract. Any valid ISO-8601 string126            that parses correctly with the default settings will continue to127            parse correctly in future versions, but invalid strings that128            currently fail (e.g. ``2017-01-01T00:00+00:00:00``) are not129            guaranteed to continue failing in future versions if they encode130            a valid date.131 132        .. versionadded:: 2.7.0133        """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] = 0144            return datetime(*components) + timedelta(days=1)145 146        return datetime(*components)147 148    @_takes_ascii149    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 separator155 156        :return:157            Returns a :class:`datetime.date` object158        """159        components, pos = self._parse_isodate(datestr)160        if pos < len(datestr):161            raise ValueError('String contains unknown ISO ' +162                             'components: {!r}'.format(datestr.decode('ascii')))163        return date(*components)164 165    @_takes_ascii166    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 separator172 173        :return:174            Returns a :class:`datetime.time` object175        """176        components = self._parse_isotime(timestr)177        if components[0] == 24:178            components[0] = 0179        return time(*components)180 181    @_takes_ascii182    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 offset190 191        :param zero_as_utc:192            Whether to return :class:`dateutil.tz.tzutc` for zero-offset zones193 194        :return:195            Returns :class:`dateutil.tz.tzoffset` for offsets and196            :class:`dateutil.tz.tzutc` for ``Z`` and (if ``zero_as_utc`` is197            specified) offsets equivalent to UTC.198        """199        return self._parse_tzstr(tzstr, zero_as_utc=zero_as_utc)200 201    # Constants202    _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        # Year220        components[0] = int(dt_str[0:4])221        pos = 4222        if pos >= len_str:223            return components, pos224 225        has_sep = dt_str[pos:pos + 1] == self._DATE_SEP226        if has_sep:227            pos += 1228 229        # Month230        if len_str - pos < 2:231            raise ValueError('Invalid common month')232 233        components[1] = int(dt_str[pos:pos + 2])234        pos += 2235 236        if pos >= len_str:237            if has_sep:238                return components, pos239            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 += 1246 247        # Day248        if len_str - pos < 2:249            raise ValueError('Invalid common day')250        components[2] = int(dt_str[pos:pos + 2])251        return components, pos + 2252 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 year258        year = int(dt_str[0:4])259 260        has_sep = dt_str[4:5] == self._DATE_SEP261 262        pos = 4 + has_sep       # Skip '-' if it's there263        if dt_str[pos:pos + 1] == b'W':264            # YYYY-?Www-?D?265            pos += 1266            weekno = int(dt_str[pos:pos + 2])267            pos += 2268 269            dayno = 1270            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_sep275 276                dayno = int(dt_str[pos:pos + 1])277                pos += 1278 279            base_date = self._calculate_weekdate(year, weekno, dayno)280        else:281            # YYYYDDD or YYYY-DDD282            if len(dt_str) - pos < 3:283                raise ValueError('Invalid ordinal day')284 285            ordinal_day = int(dt_str[pos:pos + 3])286            pos += 3287 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, pos296 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 of302        :func:`datetime.date.isocalendar`.303 304        :param year:305            The year in the ISO calendar306 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-7320            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 it324        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 want327        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 = 0334        comp = -1335 336        if len_str < 2:337            raise ValueError('ISO time too short')338 339        has_sep = False340 341        while pos < len_str and comp < 5:342            comp += 1343 344            if timestr[pos:pos + 1] in b'-+Zz':345                # Detect time zone boundary346                components[-1] = self._parse_tzstr(timestr[pos:])347                pos = len_str348                break349 350            if comp == 1 and timestr[pos:pos+1] == self._TIME_SEP:351                has_sep = True352                pos += 1353            elif comp == 2 and has_sep:354                if timestr[pos:pos+1] != self._TIME_SEP:355                    raise ValueError('Inconsistent use of colon separator')356                pos += 1357 358            if comp < 3:359                # Hour, minute, second360                components[comp] = int(timestr[pos:pos + 2])361                pos += 2362 363            if comp == 3:364                # Fraction of a second365                frac = self._FRACTION_REGEX.match(timestr[pos:])366                if not frac:367                    continue368 369                us_str = frac.group(1)[:6]  # Truncate to microseconds370                components[comp] = int(us_str) * 10**(6 - len(us_str))371                pos += len(frac.group())372 373        if pos < len_str:374            raise ValueError('Unused components in ISO string')375 376        if components[0] == 24:377            # Standard supports 00:00 and 24:00 as representations of midnight378            if any(component != 0 for component in components[1:4]):379                raise ValueError('Hour may only be 24 at 24:00:00.000')380 381        return components382 383    def _parse_tzstr(self, tzstr, zero_as_utc=True):384        if tzstr == b'Z' or tzstr == b'z':385            return tz.UTC386 387        if len(tzstr) not in {3, 5, 6}:388            raise ValueError('Time zone offset must be 1, 3, 5 or 6 characters')389 390        if tzstr[0:1] == b'-':391            mult = -1392        elif tzstr[0:1] == b'+':393            mult = 1394        else:395            raise ValueError('Time zone offset requires sign')396 397        hours = int(tzstr[1:3])398        if len(tzstr) == 3:399            minutes = 0400        else:401            minutes = int(tzstr[(4 if tzstr[3:4] == self._TIME_SEP else 3):])402 403        if zero_as_utc and hours == 0 and minutes == 0:404            return tz.UTC405        else:406            if minutes > 59:407                raise ValueError('Invalid minutes in time zone offset')408 409            if hours > 23:410                raise ValueError('Invalid hours in time zone offset')411 412            return tz.tzoffset(None, mult * (hours * 60 + minutes) * 60)413 414 415DEFAULT_ISOPARSER = isoparser()416isoparse = DEFAULT_ISOPARSER.isoparse417