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

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:

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.

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: {!r}'.format(datestr.decode('ascii')))

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_str < 2:

337 raise ValueError('ISO time too short')

338

339 has_sep = False

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 == 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

357

358 if comp < 3:

359 # Hour, minute, second

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

361 pos += 2

362

363 if comp == 3:

364 # Fraction of a second

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

366 if not frac:

367 continue

368

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())

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 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')

380

381 return components

382

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

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

385 return tz.UTC

386

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 = -1

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

393 mult = 1

394 else:

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

396

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):])

402

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')

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.isoparse