src/rdflib/xsd_datetime.py
1"""
2Large parts of this module are taken from the `isodate` package.
3https://pypi.org/project/isodate/
4Modifications are made to isodate features to allow compatibility with
5XSD dates and durations that are not necessarily valid ISO8601 strings.
6
7Copyright (c) 2024, Ashley Sommer, and RDFLib contributors
8Copyright (c) 2021, Hugo van Kemenade and contributors
9Copyright (c) 2009-2018, Gerhard Weis and contributors
10Copyright (c) 2009, Gerhard Weis
11All rights reserved.
12
13Redistribution and use in source and binary forms, with or without
14modification, are permitted provided that the following conditions are met:
15- Redistributions of source code must retain the above copyright
16notice, this list of conditions and the following disclaimer.
17- Redistributions in binary form must reproduce the above copyright
18notice, this list of conditions and the following disclaimer in the
19documentation and/or other materials provided with the distribution.
20- Neither the name of the <organization> nor the
21names of its contributors may be used to endorse or promote products
22derived from this software without specific prior written permission.
23
24THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
25ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
26WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
27DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
28DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
29(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
31ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34"""
35
36from __future__ import annotations
37
38import re
39import sys
40from datetime import date, datetime, time, timedelta
41from decimal import ROUND_FLOOR, Decimal
42from typing import List, Tuple, Union, cast
43
44if sys.version_info[:3] < (3, 11, 0):
45 from isodate import parse_date, parse_datetime, parse_time
46else:
47 # On python 3.11, use the built-in parsers
48 parse_date = date.fromisoformat
49 parse_datetime = datetime.fromisoformat
50 parse_time = time.fromisoformat
51
52
53def fquotmod(
54 val: Decimal, low: Union[Decimal, int], high: Union[Decimal, int]
55) -> Tuple[int, Decimal]:
56 """A divmod function with boundaries."""
57 # assumes that all the maths is done with Decimals.
58 # divmod for Decimal uses truncate instead of floor as builtin
59 # divmod, so we have to do it manually here.
60 a: Decimal = val - low
61 b: Union[Decimal, int] = high - low
62 div: Decimal = (a / b).to_integral(ROUND_FLOOR)
63 mod: Decimal = a - div * b
64 # if we were not using Decimal, it would look like this.
65 # div, mod = divmod(val - low, high - low)
66 mod += low
67 return int(div), mod
68
69
70def max_days_in_month(year: int, month: int) -> int:
71 """
72 Determines the number of days of a specific month in a specific year.
73 """
74 if month in (1, 3, 5, 7, 8, 10, 12):
75 return 31
76 if month in (4, 6, 9, 11):
77 return 30
78 if month < 1 or month > 12:
79 raise ValueError("Month must be in 1..12")
80 # Month is February
81 if ((year % 400) == 0) or ((year % 100) != 0) and ((year % 4) == 0):
82 return 29
83 return 28
84
85
86class Duration:
87 """A class which represents a duration.
88
89 The difference to datetime.timedelta is, that this class handles also
90 differences given in years and months.
91 A Duration treats differences given in year, months separately from all
92 other components.
93
94 A Duration can be used almost like any timedelta object, however there
95 are some restrictions:
96 - It is not really possible to compare Durations, because it is unclear,
97 whether a duration of 1 year is bigger than 365 days or not.
98 - Equality is only tested between the two (year, month vs. timedelta)
99 basic components.
100
101 A Duration can also be converted into a datetime object, but this requires
102 a start date or an end date.
103
104 The algorithm to add a duration to a date is defined at
105 http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes
106 """
107
108 def __init__(
109 self,
110 days: float = 0,
111 seconds: float = 0,
112 microseconds: float = 0,
113 milliseconds: float = 0,
114 minutes: float = 0,
115 hours: float = 0,
116 weeks: float = 0,
117 months: Union[Decimal, float, int, str] = 0,
118 years: Union[Decimal, float, int, str] = 0,
119 ):
120 """
121 Initialise this Duration instance with the given parameters.
122 """
123 if not isinstance(months, Decimal):
124 months = Decimal(str(months))
125 if not isinstance(years, Decimal):
126 years = Decimal(str(years))
127 new_years, months = fquotmod(months, 0, 12)
128 self.months = months
129 self.years = Decimal(years + new_years)
130 self.tdelta = timedelta(
131 days, seconds, microseconds, milliseconds, minutes, hours, weeks
132 )
133 if self.years < 0 and self.tdelta.days < 0:
134 raise ValueError("Duration cannot have negative years and negative days")
135
136 def __getstate__(self):
137 return self.__dict__
138
139 def __setstate__(self, state):
140 self.__dict__.update(state)
141
142 def __getattr__(self, name):
143 """
144 Provide direct access to attributes of included timedelta instance.
145 """
146 return getattr(self.tdelta, name)
147
148 def __str__(self):
149 """
150 Return a string representation of this duration similar to timedelta.
151 """
152 params = []
153 if self.years:
154 params.append("%d years" % self.years)
155 if self.months:
156 fmt = "%d months"
157 if self.months <= 1:
158 fmt = "%d month"
159 params.append(fmt % self.months)
160 params.append(str(self.tdelta))
161 return ", ".join(params)
162
163 def __repr__(self):
164 """
165 Return a string suitable for repr(x) calls.
166 """
167 return "%s.%s(%d, %d, %d, years=%s, months=%s)" % (
168 self.__class__.__module__,
169 self.__class__.__name__,
170 self.tdelta.days,
171 self.tdelta.seconds,
172 self.tdelta.microseconds,
173 str(self.years),
174 str(self.months),
175 )
176
177 def __hash__(self):
178 """
179 Return a hash of this instance so that it can be used in, for
180 example, dicts and sets.
181 """
182 return hash((self.tdelta, self.months, self.years))
183
184 def __neg__(self):
185 """A simple unary minus.
186
187 Returns a new Duration instance with all it's negated.
188 """
189 negduration = Duration(years=-self.years, months=-self.months)
190 negduration.tdelta = -self.tdelta
191 return negduration
192
193 def __add__(self, other: Union[Duration, timedelta, date, datetime]):
194 """
195 Durations can be added with Duration, timedelta, date and datetime
196 objects.
197 """
198 if isinstance(other, Duration):
199 newduration = Duration(
200 years=self.years + other.years, months=self.months + other.months
201 )
202 newduration.tdelta = self.tdelta + other.tdelta
203 return newduration
204 elif isinstance(other, timedelta):
205 newduration = Duration(years=self.years, months=self.months)
206 newduration.tdelta = self.tdelta + other
207 return newduration
208 try:
209 # try anything that looks like a date or datetime
210 # 'other' has attributes year, month, day
211 # and relies on 'timedelta + other' being implemented
212 if not (float(self.years).is_integer() and float(self.months).is_integer()):
213 raise ValueError(
214 "fractional years or months not supported for date calculations"
215 )
216 newmonth: Decimal = Decimal(other.month) + self.months
217 carry, newmonth = fquotmod(newmonth, 1, 13)
218 newyear: int = other.year + int(self.years) + carry
219 maxdays: int = max_days_in_month(newyear, int(newmonth))
220 newday: Union[int, float]
221 if other.day > maxdays:
222 newday = maxdays
223 else:
224 newday = other.day
225 newdt = other.replace(year=newyear, month=int(newmonth), day=newday)
226 # does a timedelta + date/datetime
227 return self.tdelta + newdt
228 except AttributeError:
229 # other probably was not a date/datetime compatible object
230 pass
231 # we have tried everything .... return a NotImplemented
232 return NotImplemented
233
234 __radd__ = __add__
235
236 def __mul__(self, other):
237 if isinstance(other, int):
238 newduration = Duration(years=self.years * other, months=self.months * other)
239 newduration.tdelta = self.tdelta * other
240 return newduration
241 return NotImplemented
242
243 __rmul__ = __mul__
244
245 def __sub__(self, other: Union[Duration, timedelta]):
246 """
247 It is possible to subtract Duration and timedelta objects from Duration
248 objects.
249 """
250 if isinstance(other, Duration):
251 newduration = Duration(
252 years=self.years - other.years, months=self.months - other.months
253 )
254 newduration.tdelta = self.tdelta - other.tdelta
255 return newduration
256 try:
257 # do maths with our timedelta object ....
258 newduration = Duration(years=self.years, months=self.months)
259 newduration.tdelta = self.tdelta - other
260 return newduration
261 except TypeError:
262 # looks like timedelta - other is not implemented
263 pass
264 return NotImplemented
265
266 def __rsub__(self, other: Union[timedelta, date, datetime]):
267 """
268 It is possible to subtract Duration objects from date, datetime and
269 timedelta objects.
270 """
271 # TODO: there is some weird behaviour in date - timedelta ...
272 # if timedelta has seconds or microseconds set, then
273 # date - timedelta != date + (-timedelta)
274 # for now we follow this behaviour to avoid surprises when mixing
275 # timedeltas with Durations, but in case this ever changes in
276 # the stdlib we can just do:
277 # return -self + other
278 # instead of all the current code
279
280 if isinstance(other, timedelta):
281 tmpdur = Duration()
282 tmpdur.tdelta = other
283 return tmpdur - self
284 try:
285 # check if other behaves like a date/datetime object
286 # does it have year, month, day and replace?
287 if not (float(self.years).is_integer() and float(self.months).is_integer()):
288 raise ValueError(
289 "fractional years or months not supported for date calculations"
290 )
291 newmonth: Decimal = Decimal(other.month) - self.months
292 carry, newmonth = fquotmod(newmonth, 1, 13)
293 newyear: int = other.year - int(self.years) + carry
294 maxdays: int = max_days_in_month(newyear, int(newmonth))
295 newday: Union[int, float]
296 if other.day > maxdays:
297 newday = maxdays
298 else:
299 newday = other.day
300 newdt = other.replace(year=newyear, month=int(newmonth), day=newday)
301 return newdt - self.tdelta
302 except AttributeError:
303 # other probably was not compatible with data/datetime
304 pass
305 return NotImplemented
306
307 def __eq__(self, other):
308 """
309 If the years, month part and the timedelta part are both equal, then
310 the two Durations are considered equal.
311 """
312 if isinstance(other, Duration):
313 if (self.years * 12 + self.months) == (
314 other.years * 12 + other.months
315 ) and self.tdelta == other.tdelta:
316 return True
317 return False
318 # check if other con be compared against timedelta object
319 # will raise an AssertionError when optimisation is off
320 if self.years == 0 and self.months == 0:
321 return self.tdelta == other
322 return False
323
324 def __ne__(self, other):
325 """
326 If the years, month part or the timedelta part is not equal, then
327 the two Durations are considered not equal.
328 """
329 if isinstance(other, Duration):
330 if (self.years * 12 + self.months) != (
331 other.years * 12 + other.months
332 ) or self.tdelta != other.tdelta:
333 return True
334 return False
335 # check if other can be compared against timedelta object
336 # will raise an AssertionError when optimisation is off
337 if self.years == 0 and self.months == 0:
338 return self.tdelta != other
339 return True
340
341 def totimedelta(self, start=None, end=None):
342 """Convert this duration into a timedelta object.
343
344 This method requires a start datetime or end datetime, but raises
345 an exception if both are given.
346 """
347 if start is None and end is None:
348 raise ValueError("start or end required")
349 if start is not None and end is not None:
350 raise ValueError("only start or end allowed")
351 if start is not None:
352 return (start + self) - start
353 return end - (end - self)
354
355
356ISO8601_PERIOD_REGEX = re.compile(
357 r"^(?P<sign>[+-])?"
358 r"P(?!\b)"
359 r"(?P<years>[0-9]+([,.][0-9]+)?Y)?"
360 r"(?P<months>[0-9]+([,.][0-9]+)?M)?"
361 r"(?P<weeks>[0-9]+([,.][0-9]+)?W)?"
362 r"(?P<days>[0-9]+([,.][0-9]+)?D)?"
363 r"((?P<separator>T)(?P<hours>[0-9]+([,.][0-9]+)?H)?"
364 r"(?P<minutes>[0-9]+([,.][0-9]+)?M)?"
365 r"(?P<seconds>[0-9]+([,.][0-9]+)?S)?)?$"
366)
367# regular expression to parse ISO duration strings.
368
369
370def parse_xsd_duration(
371 dur_string: str, as_timedelta_if_possible: bool = True
372) -> Union[Duration, timedelta]:
373 """Parses an ISO 8601 durations into datetime.timedelta or Duration objects.
374
375 If the ISO date string does not contain years or months, a timedelta
376 instance is returned, else a Duration instance is returned.
377
378 The following duration formats are supported:
379
380 -`PnnW` duration in weeks
381 -`PnnYnnMnnDTnnHnnMnnS` complete duration specification
382 -`PYYYYMMDDThhmmss` basic alternative complete date format
383 -`PYYYY-MM-DDThh:mm:ss` extended alternative complete date format
384 -`PYYYYDDDThhmmss` basic alternative ordinal date format
385 -`PYYYY-DDDThh:mm:ss` extended alternative ordinal date format
386
387 The '-' is optional.
388
389 Limitations: ISO standard defines some restrictions about where to use
390 fractional numbers and which component and format combinations are
391 allowed. This parser implementation ignores all those restrictions and
392 returns something when it is able to find all necessary components.
393 In detail:
394 - it does not check, whether only the last component has fractions.
395 - it allows weeks specified with all other combinations
396 The alternative format does not support durations with years, months or
397 days set to 0.
398 """
399 if not isinstance(dur_string, str):
400 raise TypeError(f"Expecting a string: {dur_string!r}")
401 match = ISO8601_PERIOD_REGEX.match(dur_string)
402 if not match:
403 # try alternative format:
404 if dur_string.startswith("P"):
405 durdt = parse_datetime(dur_string[1:])
406 if as_timedelta_if_possible and durdt.year == 0 and durdt.month == 0:
407 # FIXME: currently not possible in alternative format
408 # create timedelta
409 return timedelta(
410 days=durdt.day,
411 seconds=durdt.second,
412 microseconds=durdt.microsecond,
413 minutes=durdt.minute,
414 hours=durdt.hour,
415 )
416 else:
417 # create Duration
418 return Duration(
419 days=durdt.day,
420 seconds=durdt.second,
421 microseconds=durdt.microsecond,
422 minutes=durdt.minute,
423 hours=durdt.hour,
424 months=durdt.month,
425 years=durdt.year,
426 )
427 raise ValueError("Unable to parse duration string " + dur_string)
428 groups = match.groupdict()
429 for key, val in groups.items():
430 if key not in ("separator", "sign"):
431 if val is None:
432 groups[key] = "0n"
433 # print groups[key]
434 if key in ("years", "months"):
435 groups[key] = Decimal(groups[key][:-1].replace(",", "."))
436 else:
437 # these values are passed into a timedelta object,
438 # which works with floats.
439 groups[key] = float(groups[key][:-1].replace(",", "."))
440 ret: Union[Duration, timedelta]
441 if as_timedelta_if_possible and groups["years"] == 0 and groups["months"] == 0:
442 ret = timedelta(
443 days=groups["days"], # type: ignore[arg-type]
444 hours=groups["hours"], # type: ignore[arg-type]
445 minutes=groups["minutes"], # type: ignore[arg-type]
446 seconds=groups["seconds"], # type: ignore[arg-type]
447 weeks=groups["weeks"], # type: ignore[arg-type]
448 )
449 if groups["sign"] == "-":
450 ret = timedelta(0) - ret
451 else:
452 ret = Duration(
453 years=cast(Decimal, groups["years"]),
454 months=cast(Decimal, groups["months"]),
455 days=groups["days"], # type: ignore[arg-type]
456 hours=groups["hours"], # type: ignore[arg-type]
457 minutes=groups["minutes"], # type: ignore[arg-type]
458 seconds=groups["seconds"], # type: ignore[arg-type]
459 weeks=groups["weeks"], # type: ignore[arg-type]
460 )
461 if groups["sign"] == "-":
462 ret = Duration(0) - ret
463
464 return ret
465
466
467def duration_isoformat(tdt: Union[Duration, timedelta], in_weeks: bool = False) -> str:
468 if not in_weeks:
469 ret: List[str] = []
470 minus = False
471 has_year_or_month = False
472 if isinstance(tdt, Duration):
473 if tdt.years == 0 and tdt.months == 0:
474 pass # don't do anything, we have no year or month
475 else:
476 has_year_or_month = True
477 months = tdt.years * 12 + tdt.months
478 if months < 0:
479 minus = True
480 months = abs(months)
481 # We can use divmod instead of fquotmod here because its month_count
482 # not month_index, and we don't have any negative months at this point.
483 new_years, new_months = divmod(months, 12)
484 if new_years:
485 ret.append(str(new_years) + "Y")
486 if tdt.months:
487 ret.append(str(new_months) + "M")
488 tdt = tdt.tdelta
489 usecs: int = ((tdt.days * 86400) + tdt.seconds) * 1000000 + tdt.microseconds
490 if usecs < 0:
491 if minus:
492 raise ValueError(
493 "Duration cannot have negative years and negative days"
494 )
495 elif has_year_or_month:
496 raise ValueError(
497 "Duration cannot have positive years and months but negative days"
498 )
499 minus = True
500 usecs = abs(usecs)
501 if usecs == 0:
502 # No delta parts other than years and months
503 pass
504 else:
505 seconds, usecs = divmod(usecs, 1000000)
506 minutes, seconds = divmod(seconds, 60)
507 hours, minutes = divmod(minutes, 60)
508 days, hours = divmod(hours, 24)
509 if days:
510 ret.append(str(days) + "D")
511 if hours or minutes or seconds or usecs:
512 ret.append("T")
513 if hours:
514 ret.append(str(hours) + "H")
515 if minutes:
516 ret.append(str(minutes) + "M")
517 if seconds or usecs:
518 if usecs:
519 ret.append(("%d.%06d" % (seconds, usecs)).rstrip("0"))
520 else:
521 ret.append("%d" % seconds)
522 ret.append("S")
523 if ret:
524 return ("-P" if minus else "P") + "".join(ret)
525 else:
526 # at least one component has to be there.
527 return "-P0D" if minus else "P0D"
528 else:
529 if tdt.days < 0:
530 return f"-P{abs(tdt.days // 7)}W"
531 return f"P{tdt.days // 7}W"
532
533
534def xsd_datetime_isoformat(dt: datetime):
535 if dt.microsecond == 0:
536 no_tz_str = dt.strftime("%Y-%m-%dT%H:%M:%S")
537 else:
538 no_tz_str = dt.strftime("%Y-%m-%dT%H:%M:%S.%f")
539 if dt.tzinfo is None:
540 return no_tz_str
541 else:
542 offset_string = dt.strftime("%z")
543 if offset_string == "+0000":
544 return no_tz_str + "Z"
545 first_char = offset_string[0]
546 if first_char == "+" or first_char == "-":
547 offset_string = offset_string[1:]
548 sign = first_char
549 else:
550 sign = "+"
551 tz_part = sign + offset_string[:2] + ":" + offset_string[2:]
552 return no_tz_str + tz_part
553
554
555def parse_xsd_date(date_string: str):
556 """
557 XSD Dates have more features than ISO8601 dates, specifically
558 XSD allows timezones on dates, that must be stripped off.
559 Also, XSD requires dashed separators, while ISO8601 is optional.
560 RDFLib test suite has some date strings with times, the times are expected
561 to be dropped during parsing.
562 """
563 if date_string.endswith("Z") or date_string.endswith("z"):
564 date_string = date_string[:-1]
565 if date_string.startswith("-"):
566 date_string = date_string[1:]
567 minus = True
568 else:
569 minus = False
570 if "T" in date_string:
571 # RDFLib test suite has some strange date strings, with times.
572 # this has the side effect of also dropping the
573 # TZ part, that is not wanted anyway for a date.
574 date_string = date_string.split("T")[0]
575 else:
576 has_plus = date_string.rfind("+")
577 if has_plus > 0:
578 # Drop the +07:00 timezone part
579 date_string = date_string[:has_plus]
580 else:
581 split_parts = date_string.rsplit("-", 1)
582 if len(split_parts) > 1 and ":" in split_parts[-1]:
583 # Drop the -09:00 timezone part
584 date_string = split_parts[0]
585 if "-" not in date_string:
586 raise ValueError("XSD Date string must contain at least two dashes")
587 return parse_date(date_string if not minus else ("-" + date_string))
588
589
590# Parse XSD Datetime is the same as ISO8601 Datetime
591# It uses datetime.fromisoformat for python 3.11 and above
592# or isodate.parse_datetime for older versions
593# parse_xsd_datetime = parse_datetime
594
595# Parse XSD Time is the same as ISO8601 Time
596# It uses time.fromisoformat for python 3.11 and above
597# or isodate.parse_time for older versions
598# parse_xsd_time = parse_time