Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/dateutil/parser/isoparser.py: 60%

1""" 

2This module offers a parser for ISO-8601 strings 

3 

4It is intended to support all valid date, time and datetime formats per the 

5ISO-8601 specification. 

6 

7..versionadded:: 2.7.0 

8""" 

9from datetime import datetime, timedelta, time, date 

10import calendar 

11from dateutil import tz 

12 

13from functools import wraps 

14 

15import re 

16 

17__all__ = ["isoparse", "isoparser"] 

18 

19 

20def _takes_ascii(f): 

21 @wraps(f) 

22 def func(self, str_in, *args, **kwargs): 

23 # If it's a stream, read the whole thing 

24 str_in = getattr(str_in, 'read', lambda: str_in)() 

25 

26 # If it's unicode, turn it into bytes, since ISO-8601 only covers ASCII 

27 if isinstance(str_in, str): 

28 # ASCII is the same in UTF-8 

29 try: 

30 str_in = str_in.encode('ascii') 

31 except UnicodeEncodeError as e: 

32 msg = 'ISO-8601 strings should contain only ASCII characters' 

33 raise ValueError(msg) from e 

34 

35 return f(self, str_in, *args, **kwargs) 

36 

37 return func 

38 

39 

40class isoparser: 

41 def __init__(self, sep=None): 

42 """ 

43 :param sep: 

44 A single character that separates date and time portions. If 

45 ``None``, the parser will accept any single character. 

46 For strict ISO-8601 adherence, pass ``'T'``. 

47 """ 

48 if sep is not None: 

49 if (len(sep) != 1 or ord(sep) >= 128 or sep in '0123456789'): 

50 raise ValueError('Separator must be a single, non-numeric ' + 

51 'ASCII character') 

52 

53 sep = sep.encode('ascii') 

54 

55 self._sep = sep 

56 

57 @_takes_ascii 

58 def isoparse(self, dt_str): 

59 """ 

60 Parse an ISO-8601 datetime string into a :class:`datetime.datetime`. 

61 

62 An ISO-8601 datetime string consists of a date portion, followed 

63 optionally by a time portion - the date and time portions are separated 

64 by a single character separator, which is ``T`` in the official 

65 standard. Incomplete date formats (such as ``YYYY-MM``) may *not* be 

66 combined with a time portion. 

67 

68 Supported date formats are: 

69 

70 Common: 

71 

72 - ``YYYY`` 

73 - ``YYYY-MM`` 

74 - ``YYYY-MM-DD`` or ``YYYYMMDD`` 

75 

76 Uncommon: 

77 

78 - ``YYYY-Www`` or ``YYYYWww`` - ISO week (day defaults to 0) 

79 - ``YYYY-Www-D`` or ``YYYYWwwD`` - ISO week and day 

80 

81 The ISO week and day numbering follows the same logic as 

82 :func:`datetime.date.isocalendar`. 

83 

84 Supported time formats are: 

85 

86 - ``hh`` 

87 - ``hh:mm`` or ``hhmm`` 

88 - ``hh:mm:ss`` or ``hhmmss`` 

89 - ``hh:mm:ss.ssssss`` (Up to 6 sub-second digits) 

90 

91 Midnight is a special case for `hh`, as the standard supports both 

92 00:00 and 24:00 as a representation. The decimal separator can be 

93 either a dot or a comma. 

94 

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 if len(components) > 3 and components[3] == 24: 

141 components[3] = 0 

142 return datetime(*components) + timedelta(days=1) 

143 

144 return datetime(*components) 

145 

146 @_takes_ascii 

147 def parse_isodate(self, datestr): 

148 """ 

149 Parse the date portion of an ISO string. 

150 

151 :param datestr: 

152 The string portion of an ISO string, without a separator 

153 

154 :return: 

155 Returns a :class:`datetime.date` object 

156 """ 

157 components, pos = self._parse_isodate(datestr) 

158 if pos < len(datestr): 

159 raise ValueError('String contains unknown ISO ' + 

160 'components: {!r}'.format(datestr.decode('ascii'))) 

161 return date(*components) 

162 

163 @_takes_ascii 

164 def parse_isotime(self, timestr): 

165 """ 

166 Parse the time portion of an ISO string. 

167 

168 :param timestr: 

169 The time portion of an ISO string, without a separator 

170 

171 :return: 

172 Returns a :class:`datetime.time` object 

173 """ 

174 components = self._parse_isotime(timestr) 

175 if components[0] == 24: 

176 components[0] = 0 

177 return time(*components) 

178 

179 @_takes_ascii 

180 def parse_tzstr(self, tzstr, zero_as_utc=True): 

181 """ 

182 Parse a valid ISO time zone string. 

183 

184 See :func:`isoparser.isoparse` for details on supported formats. 

185 

186 :param tzstr: 

187 A string representing an ISO time zone offset 

188 

189 :param zero_as_utc: 

190 Whether to return :class:`dateutil.tz.tzutc` for zero-offset zones 

191 

192 :return: 

193 Returns :class:`dateutil.tz.tzoffset` for offsets and 

194 :class:`dateutil.tz.tzutc` for ``Z`` and (if ``zero_as_utc`` is 

195 specified) offsets equivalent to UTC. 

196 """ 

197 return self._parse_tzstr(tzstr, zero_as_utc=zero_as_utc) 

198 

199 # Constants 

200 _DATE_SEP = b'-' 

201 _TIME_SEP = b':' 

202 _FRACTION_REGEX = re.compile(b'[\\.,]([0-9]+)') 

203 

204 def _parse_isodate(self, dt_str): 

205 try: 

206 return self._parse_isodate_common(dt_str) 

207 except ValueError: 

208 return self._parse_isodate_uncommon(dt_str) 

209 

210 def _parse_isodate_common(self, dt_str): 

211 len_str = len(dt_str) 

212 components = [1, 1, 1] 

213 

214 if len_str < 4: 

215 raise ValueError('ISO string too short') 

216 

217 # Year 

218 components[0] = int(dt_str[0:4]) 

219 pos = 4 

220 if pos >= len_str: 

221 return components, pos 

222 

223 has_sep = dt_str[pos:pos + 1] == self._DATE_SEP 

224 if has_sep: 

225 pos += 1 

226 

227 # Month 

228 if len_str - pos < 2: 

229 raise ValueError('Invalid common month') 

230 

231 components[1] = int(dt_str[pos:pos + 2]) 

232 pos += 2 

233 

234 if pos >= len_str: 

235 if has_sep: 

236 return components, pos 

237 else: 

238 raise ValueError('Invalid ISO format') 

239 

240 if has_sep: 

241 if dt_str[pos:pos + 1] != self._DATE_SEP: 

242 raise ValueError('Invalid separator in ISO string') 

243 pos += 1 

244 

245 # Day 

246 if len_str - pos < 2: 

247 raise ValueError('Invalid common day') 

248 components[2] = int(dt_str[pos:pos + 2]) 

249 return components, pos + 2 

250 

251 def _parse_isodate_uncommon(self, dt_str): 

252 if len(dt_str) < 4: 

253 raise ValueError('ISO string too short') 

254 

255 # All ISO formats start with the year 

256 year = int(dt_str[0:4]) 

257 

258 has_sep = dt_str[4:5] == self._DATE_SEP 

259 

260 pos = 4 + has_sep # Skip '-' if it's there 

261 if dt_str[pos:pos + 1] == b'W': 

262 # YYYY-?Www-?D? 

263 pos += 1 

264 weekno = int(dt_str[pos:pos + 2]) 

265 pos += 2 

266 

267 dayno = 1 

268 if len(dt_str) > pos: 

269 if (dt_str[pos:pos + 1] == self._DATE_SEP) != has_sep: 

270 raise ValueError('Inconsistent use of dash separator') 

271 

272 pos += has_sep 

273 

274 dayno = int(dt_str[pos:pos + 1]) 

275 pos += 1 

276 

277 base_date = self._calculate_weekdate(year, weekno, dayno) 

278 else: 

279 # YYYYDDD or YYYY-DDD 

280 if len(dt_str) - pos < 3: 

281 raise ValueError('Invalid ordinal day') 

282 

283 ordinal_day = int(dt_str[pos:pos + 3]) 

284 pos += 3 

285 

286 if ordinal_day < 1 or ordinal_day > (365 + calendar.isleap(year)): 

287 raise ValueError('Invalid ordinal day' + 

288 ' {} for year {}'.format(ordinal_day, year)) 

289 

290 base_date = date(year, 1, 1) + timedelta(days=ordinal_day - 1) 

291 

292 components = [base_date.year, base_date.month, base_date.day] 

293 return components, pos 

294 

295 def _calculate_weekdate(self, year, week, day): 

296 """ 

297 Calculate the day of corresponding to the ISO year-week-day calendar. 

298 

299 This function is effectively the inverse of 

300 :func:`datetime.date.isocalendar`. 

301 

302 :param year: 

303 The year in the ISO calendar 

304 

305 :param week: 

306 The week in the ISO calendar - range is [1, 53] 

307 

308 :param day: 

309 The day in the ISO calendar - range is [1 (MON), 7 (SUN)] 

310 

311 :return: 

312 Returns a :class:`datetime.date` 

313 """ 

314 if not 0 < week < 54: 

315 raise ValueError('Invalid week: {}'.format(week)) 

316 

317 if not 0 < day < 8: # Range is 1-7 

318 raise ValueError('Invalid weekday: {}'.format(day)) 

319 

320 # Get week 1 for the specific year: 

321 jan_4 = date(year, 1, 4) # Week 1 always has January 4th in it 

322 week_1 = jan_4 - timedelta(days=jan_4.isocalendar()[2] - 1) 

323 

324 # Now add the specific number of weeks and days to get what we want 

325 week_offset = (week - 1) * 7 + (day - 1) 

326 return week_1 + timedelta(days=week_offset) 

327 

328 def _parse_isotime(self, timestr): 

329 len_str = len(timestr) 

330 components = [0, 0, 0, 0, None] 

331 pos = 0 

332 comp = -1 

333 

334 if len_str < 2: 

335 raise ValueError('ISO time too short') 

336 

337 has_sep = False 

338 

339 while pos < len_str and comp < 5: 

340 comp += 1 

341 

342 if timestr[pos:pos + 1] in b'-+Zz': 

343 # Detect time zone boundary 

344 components[-1] = self._parse_tzstr(timestr[pos:]) 

345 pos = len_str 

346 break 

347 

348 if comp == 1 and timestr[pos:pos+1] == self._TIME_SEP: 

349 has_sep = True 

350 pos += 1 

351 elif comp == 2 and has_sep: 

352 if timestr[pos:pos+1] != self._TIME_SEP: 

353 raise ValueError('Inconsistent use of colon separator') 

354 pos += 1 

355 

356 if comp < 3: 

357 # Hour, minute, second 

358 components[comp] = int(timestr[pos:pos + 2]) 

359 pos += 2 

360 

361 if comp == 3: 

362 # Fraction of a second 

363 frac = self._FRACTION_REGEX.match(timestr[pos:]) 

364 if not frac: 

365 continue 

366 

367 us_str = frac.group(1)[:6] # Truncate to microseconds 

368 components[comp] = int(us_str) * 10**(6 - len(us_str)) 

369 pos += len(frac.group()) 

370 

371 if pos < len_str: 

372 raise ValueError('Unused components in ISO string') 

373 

374 if components[0] == 24: 

375 # Standard supports 00:00 and 24:00 as representations of midnight 

376 if any(component != 0 for component in components[1:4]): 

377 raise ValueError('Hour may only be 24 at 24:00:00.000') 

378 

379 return components 

380 

381 def _parse_tzstr(self, tzstr, zero_as_utc=True): 

382 if tzstr == b'Z' or tzstr == b'z': 

383 return tz.UTC 

384 

385 if len(tzstr) not in {3, 5, 6}: 

386 raise ValueError('Time zone offset must be 1, 3, 5 or 6 characters') 

387 

388 if tzstr[0:1] == b'-': 

389 mult = -1 

390 elif tzstr[0:1] == b'+': 

391 mult = 1 

392 else: 

393 raise ValueError('Time zone offset requires sign') 

394 

395 hours = int(tzstr[1:3]) 

396 if len(tzstr) == 3: 

397 minutes = 0 

398 else: 

399 minutes = int(tzstr[(4 if tzstr[3:4] == self._TIME_SEP else 3):]) 

400 

401 if zero_as_utc and hours == 0 and minutes == 0: 

402 return tz.UTC 

403 else: 

404 if minutes > 59: 

405 raise ValueError('Invalid minutes in time zone offset') 

406 

407 if hours > 23: 

408 raise ValueError('Invalid hours in time zone offset') 

409 

410 return tz.tzoffset(None, mult * (hours * 60 + minutes) * 60) 

411 

412 

413DEFAULT_ISOPARSER = isoparser() 

414isoparse = DEFAULT_ISOPARSER.isoparse