Source code

Download source archive ↓

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