Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/dateutil/parser/isoparser.py: 14%
185 statements
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
1# -*- coding: utf-8 -*-
2"""
3This module offers a parser for ISO-8601 strings
5It is intended to support all valid date, time and datetime formats per the
6ISO-8601 specification.
8..versionadded:: 2.7.0
9"""
10from datetime import datetime, timedelta, time, date
11import calendar
12from dateutil import tz
14from functools import wraps
16import re
17import six
19__all__ = ["isoparse", "isoparser"]
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)()
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)
37 return f(self, str_in, *args, **kwargs)
39 return func
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: 50 ↛ 51line 50 didn't jump to line 51, because the condition on line 50 was never true
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')
55 sep = sep.encode('ascii')
57 self._sep = sep
59 @_takes_ascii
60 def isoparse(self, dt_str):
61 """
62 Parse an ISO-8601 datetime string into a :class:`datetime.datetime`.
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.
70 Supported date formats are:
72 Common:
74 - ``YYYY``
75 - ``YYYY-MM`` or ``YYYYMM``
76 - ``YYYY-MM-DD`` or ``YYYYMMDD``
78 Uncommon:
80 - ``YYYY-Www`` or ``YYYYWww`` - ISO week (day defaults to 0)
81 - ``YYYY-Www-D`` or ``YYYYWwwD`` - ISO week and day
83 The ISO week and day numbering follows the same logic as
84 :func:`datetime.date.isocalendar`.
86 Supported time formats are:
88 - ``hh``
89 - ``hh:mm`` or ``hhmm``
90 - ``hh:mm:ss`` or ``hhmmss``
91 - ``hh:mm:ss.ssssss`` (Up to 6 sub-second digits)
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.
98 .. caution::
100 Support for fractional components other than seconds is part of the
101 ISO-8601 standard, but is not currently implemented in this parser.
103 Supported time zone offset formats are:
105 - `Z` (UTC)
106 - `±HH:MM`
107 - `±HHMM`
108 - `±HH`
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`.
115 :param dt_str:
116 A string or stream containing only an ISO-8601 datetime string
118 :return:
119 Returns a :class:`datetime.datetime` representing the string.
120 Unspecified components default to their lowest value.
122 .. warning::
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.
132 .. versionadded:: 2.7.0
133 """
134 components, pos = self._parse_isodate(dt_str)
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')
142 if len(components) > 3 and components[3] == 24:
143 components[3] = 0
144 return datetime(*components) + timedelta(days=1)
146 return datetime(*components)
148 @_takes_ascii
149 def parse_isodate(self, datestr):
150 """
151 Parse the date portion of an ISO string.
153 :param datestr:
154 The string portion of an ISO string, without a separator
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: {!r}'.format(datestr.decode('ascii')))
163 return date(*components)
165 @_takes_ascii
166 def parse_isotime(self, timestr):
167 """
168 Parse the time portion of an ISO string.
170 :param timestr:
171 The time portion of an ISO string, without a separator
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)
181 @_takes_ascii
182 def parse_tzstr(self, tzstr, zero_as_utc=True):
183 """
184 Parse a valid ISO time zone string.
186 See :func:`isoparser.isoparse` for details on supported formats.
188 :param tzstr:
189 A string representing an ISO time zone offset
191 :param zero_as_utc:
192 Whether to return :class:`dateutil.tz.tzutc` for zero-offset zones
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)
201 # Constants
202 _DATE_SEP = b'-'
203 _TIME_SEP = b':'
204 _FRACTION_REGEX = re.compile(b'[\\.,]([0-9]+)')
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)
212 def _parse_isodate_common(self, dt_str):
213 len_str = len(dt_str)
214 components = [1, 1, 1]
216 if len_str < 4:
217 raise ValueError('ISO string too short')
219 # Year
220 components[0] = int(dt_str[0:4])
221 pos = 4
222 if pos >= len_str:
223 return components, pos
225 has_sep = dt_str[pos:pos + 1] == self._DATE_SEP
226 if has_sep:
227 pos += 1
229 # Month
230 if len_str - pos < 2:
231 raise ValueError('Invalid common month')
233 components[1] = int(dt_str[pos:pos + 2])
234 pos += 2
236 if pos >= len_str:
237 if has_sep:
238 return components, pos
239 else:
240 raise ValueError('Invalid ISO format')
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
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
253 def _parse_isodate_uncommon(self, dt_str):
254 if len(dt_str) < 4:
255 raise ValueError('ISO string too short')
257 # All ISO formats start with the year
258 year = int(dt_str[0:4])
260 has_sep = dt_str[4:5] == self._DATE_SEP
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
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')
274 pos += has_sep
276 dayno = int(dt_str[pos:pos + 1])
277 pos += 1
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')
285 ordinal_day = int(dt_str[pos:pos + 3])
286 pos += 3
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))
292 base_date = date(year, 1, 1) + timedelta(days=ordinal_day - 1)
294 components = [base_date.year, base_date.month, base_date.day]
295 return components, pos
297 def _calculate_weekdate(self, year, week, day):
298 """
299 Calculate the day of corresponding to the ISO year-week-day calendar.
301 This function is effectively the inverse of
302 :func:`datetime.date.isocalendar`.
304 :param year:
305 The year in the ISO calendar
307 :param week:
308 The week in the ISO calendar - range is [1, 53]
310 :param day:
311 The day in the ISO calendar - range is [1 (MON), 7 (SUN)]
313 :return:
314 Returns a :class:`datetime.date`
315 """
316 if not 0 < week < 54:
317 raise ValueError('Invalid week: {}'.format(week))
319 if not 0 < day < 8: # Range is 1-7
320 raise ValueError('Invalid weekday: {}'.format(day))
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)
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)
330 def _parse_isotime(self, timestr):
331 len_str = len(timestr)
332 components = [0, 0, 0, 0, None]
333 pos = 0
334 comp = -1
336 if len_str < 2:
337 raise ValueError('ISO time too short')
339 has_sep = False
341 while pos < len_str and comp < 5:
342 comp += 1
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
350 if comp == 1 and timestr[pos:pos+1] == self._TIME_SEP:
351 has_sep = True
352 pos += 1
353 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 += 1
358 if comp < 3:
359 # Hour, minute, second
360 components[comp] = int(timestr[pos:pos + 2])
361 pos += 2
363 if comp == 3:
364 # Fraction of a second
365 frac = self._FRACTION_REGEX.match(timestr[pos:])
366 if not frac:
367 continue
369 us_str = frac.group(1)[:6] # Truncate to microseconds
370 components[comp] = int(us_str) * 10**(6 - len(us_str))
371 pos += len(frac.group())
373 if pos < len_str:
374 raise ValueError('Unused components in ISO string')
376 if components[0] == 24:
377 # Standard supports 00:00 and 24:00 as representations of midnight
378 if any(component != 0 for component in components[1:4]):
379 raise ValueError('Hour may only be 24 at 24:00:00.000')
381 return components
383 def _parse_tzstr(self, tzstr, zero_as_utc=True):
384 if tzstr == b'Z' or tzstr == b'z':
385 return tz.UTC
387 if len(tzstr) not in {3, 5, 6}:
388 raise ValueError('Time zone offset must be 1, 3, 5 or 6 characters')
390 if tzstr[0:1] == b'-':
391 mult = -1
392 elif tzstr[0:1] == b'+':
393 mult = 1
394 else:
395 raise ValueError('Time zone offset requires sign')
397 hours = int(tzstr[1:3])
398 if len(tzstr) == 3:
399 minutes = 0
400 else:
401 minutes = int(tzstr[(4 if tzstr[3:4] == self._TIME_SEP else 3):])
403 if zero_as_utc and hours == 0 and minutes == 0:
404 return tz.UTC
405 else:
406 if minutes > 59:
407 raise ValueError('Invalid minutes in time zone offset')
409 if hours > 23:
410 raise ValueError('Invalid hours in time zone offset')
412 return tz.tzoffset(None, mult * (hours * 60 + minutes) * 60)
415DEFAULT_ISOPARSER = isoparser()
416isoparse = DEFAULT_ISOPARSER.isoparse