1"""Functions to parse datetime objects."""
2
3from __future__ import annotations
4
5# We're using regular expressions rather than time.strptime because:
6# - They provide both validation and parsing.
7# - They're more flexible for datetimes.
8# - The date/datetime/time constructors produce friendlier error messages.
9import datetime
10
11from plain.utils.regex_helper import _lazy_re_compile
12from plain.utils.timezone import get_fixed_timezone
13
14date_re = _lazy_re_compile(r"(?P<year>\d{4})-(?P<month>\d{1,2})-(?P<day>\d{1,2})$")
15
16time_re = _lazy_re_compile(
17 r"(?P<hour>\d{1,2}):(?P<minute>\d{1,2})"
18 r"(?::(?P<second>\d{1,2})(?:[\.,](?P<microsecond>\d{1,6})\d{0,6})?)?$"
19)
20
21datetime_re = _lazy_re_compile(
22 r"(?P<year>\d{4})-(?P<month>\d{1,2})-(?P<day>\d{1,2})"
23 r"[T ](?P<hour>\d{1,2}):(?P<minute>\d{1,2})"
24 r"(?::(?P<second>\d{1,2})(?:[\.,](?P<microsecond>\d{1,6})\d{0,6})?)?"
25 r"\s*(?P<tzinfo>Z|[+-]\d{2}(?::?\d{2})?)?$"
26)
27
28standard_duration_re = _lazy_re_compile(
29 r"^"
30 r"(?:(?P<days>-?\d+) (days?, )?)?"
31 r"(?P<sign>-?)"
32 r"((?:(?P<hours>\d+):)(?=\d+:\d+))?"
33 r"(?:(?P<minutes>\d+):)?"
34 r"(?P<seconds>\d+)"
35 r"(?:[\.,](?P<microseconds>\d{1,6})\d{0,6})?"
36 r"$"
37)
38
39# Support the sections of ISO 8601 date representation that are accepted by
40# timedelta
41iso8601_duration_re = _lazy_re_compile(
42 r"^(?P<sign>[-+]?)"
43 r"P"
44 r"(?:(?P<days>\d+([\.,]\d+)?)D)?"
45 r"(?:T"
46 r"(?:(?P<hours>\d+([\.,]\d+)?)H)?"
47 r"(?:(?P<minutes>\d+([\.,]\d+)?)M)?"
48 r"(?:(?P<seconds>\d+([\.,]\d+)?)S)?"
49 r")?"
50 r"$"
51)
52
53# Support PostgreSQL's day-time interval format, e.g. "3 days 04:05:06". The
54# year-month and mixed intervals cannot be converted to a timedelta and thus
55# aren't accepted.
56postgres_interval_re = _lazy_re_compile(
57 r"^"
58 r"(?:(?P<days>-?\d+) (days? ?))?"
59 r"(?:(?P<sign>[-+])?"
60 r"(?P<hours>\d+):"
61 r"(?P<minutes>\d\d):"
62 r"(?P<seconds>\d\d)"
63 r"(?:\.(?P<microseconds>\d{1,6}))?"
64 r")?$"
65)
66
67
68def parse_date(value: str) -> datetime.date | None:
69 """Parse a string and return a datetime.date.
70
71 Raise ValueError if the input is well formatted but not a valid date.
72 Return None if the input isn't well formatted.
73 """
74 try:
75 return datetime.date.fromisoformat(value)
76 except ValueError:
77 if match := date_re.match(value):
78 kw = {k: int(v) for k, v in match.groupdict().items()}
79 return datetime.date(**kw)
80 return None
81
82
83def parse_time(value: str) -> datetime.time | None:
84 """Parse a string and return a datetime.time.
85
86 This function doesn't support time zone offsets.
87
88 Raise ValueError if the input is well formatted but not a valid time.
89 Return None if the input isn't well formatted, in particular if it
90 contains an offset.
91 """
92 try:
93 # The fromisoformat() method takes time zone info into account and
94 # returns a time with a tzinfo component, if possible. However, there
95 # are no circumstances where aware datetime.time objects make sense, so
96 # remove the time zone offset.
97 return datetime.time.fromisoformat(value).replace(tzinfo=None)
98 except ValueError:
99 if match := time_re.match(value):
100 kw = match.groupdict()
101 kw["microsecond"] = kw["microsecond"] and kw["microsecond"].ljust(6, "0")
102 kw = {k: int(v) for k, v in kw.items() if v is not None}
103 return datetime.time(**kw) # ty: ignore[invalid-argument-type]
104
105
106def parse_datetime(value: str) -> datetime.datetime | None:
107 """Parse a string and return a datetime.datetime.
108
109 This function supports time zone offsets. When the input contains one,
110 the output uses a timezone with a fixed offset from UTC.
111
112 Raise ValueError if the input is well formatted but not a valid datetime.
113 Return None if the input isn't well formatted.
114 """
115 try:
116 return datetime.datetime.fromisoformat(value)
117 except ValueError:
118 if match := datetime_re.match(value):
119 kw = match.groupdict()
120 kw["microsecond"] = kw["microsecond"] and kw["microsecond"].ljust(6, "0")
121 tzinfo = kw.pop("tzinfo")
122 if tzinfo == "Z":
123 tzinfo = datetime.UTC
124 elif tzinfo is not None:
125 offset_mins = int(tzinfo[-2:]) if len(tzinfo) > 3 else 0
126 offset = 60 * int(tzinfo[1:3]) + offset_mins
127 if tzinfo[0] == "-":
128 offset = -offset
129 tzinfo = get_fixed_timezone(offset)
130 kw = {k: int(v) for k, v in kw.items() if v is not None}
131 return datetime.datetime(**kw, tzinfo=tzinfo)
132 return None
133
134
135def parse_duration(value: str) -> datetime.timedelta | None:
136 """Parse a duration string and return a datetime.timedelta.
137
138 The preferred format for durations in Plain is '%d %H:%M:%S.%f'.
139
140 Also supports ISO 8601 representation and PostgreSQL's day-time interval
141 format.
142 """
143 match = (
144 standard_duration_re.match(value)
145 or iso8601_duration_re.match(value)
146 or postgres_interval_re.match(value)
147 )
148 if match:
149 kw = match.groupdict()
150 sign = -1 if kw.pop("sign", "+") == "-" else 1
151 if kw.get("microseconds"):
152 kw["microseconds"] = kw["microseconds"].ljust(6, "0")
153 kw = {k: float(v.replace(",", ".")) for k, v in kw.items() if v is not None}
154 days = datetime.timedelta(kw.pop("days", 0.0) or 0.0)
155 if match.re == iso8601_duration_re:
156 days *= sign
157 return days + sign * datetime.timedelta(**kw)