nextcloud-client 0.211.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,290 @@
1
+ """Interval arithmetic behind ``nc_calendar_find_availability``.
2
+
3
+ Everything here is pure: it takes already-fetched event dicts (or an
4
+ already-fetched VFREEBUSY blob) and returns time spans. The I/O lives in
5
+ ``CalendarClient.find_availability``, which is what makes this testable
6
+ without a CalDAV server.
7
+
8
+ The shape of the answer is *maximal free windows*, not a grid of candidate
9
+ start times: a free 09:00-12:00 is returned once as a 180-minute slot rather
10
+ than as five overlapping 60-minute ones. The caller wanted to know where the
11
+ gaps are, and a grid multiplies the answer by an arbitrary granularity
12
+ constant nobody asked for.
13
+ """
14
+
15
+ import datetime as dt
16
+ import logging
17
+ from typing import Any
18
+
19
+ from icalendar import Calendar
20
+
21
+ logger = logging.getLogger(__name__)
22
+
23
+ # A span is a half-open [start, end) interval of aware datetimes.
24
+ Span = tuple[dt.datetime, dt.datetime]
25
+
26
+ # "Business hours" in the sense the tool's parameter means it.
27
+ BUSINESS_START = dt.time(9, 0)
28
+ BUSINESS_END = dt.time(17, 0)
29
+
30
+ # RFC 5545 3.2.9: FBTYPE=FREE marks a period that does *not* consume time.
31
+ # Everything else (BUSY, BUSY-TENTATIVE, BUSY-UNAVAILABLE, absent) does.
32
+ _FREE_FBTYPE = "FREE"
33
+
34
+
35
+ def parse_time_ranges(value: str | list[str] | None) -> list[tuple[dt.time, dt.time]]:
36
+ """Parse ``"09:00-12:00,14:00-17:00"`` into time pairs.
37
+
38
+ Accepts the already-split list the MCP layer produces as well as the raw
39
+ comma-separated string. Malformed entries are logged and skipped rather
40
+ than raising: one typo in a preferred-times hint should not fail the whole
41
+ availability query.
42
+ """
43
+ if not value:
44
+ return []
45
+ parts = value.split(",") if isinstance(value, str) else list(value)
46
+
47
+ ranges: list[tuple[dt.time, dt.time]] = []
48
+ for part in parts:
49
+ text = part.strip()
50
+ if not text:
51
+ continue
52
+ start_text, _, end_text = text.partition("-")
53
+ try:
54
+ start = dt.time.fromisoformat(start_text.strip())
55
+ end = dt.time.fromisoformat(end_text.strip())
56
+ except ValueError:
57
+ logger.warning("Ignoring malformed preferred time range %r", text)
58
+ continue
59
+ if start >= end:
60
+ logger.warning("Ignoring inverted preferred time range %r", text)
61
+ continue
62
+ ranges.append((start, end))
63
+ return ranges
64
+
65
+
66
+ def to_aware(value: Any, tz: dt.tzinfo) -> dt.datetime | None:
67
+ """Coerce an event's ISO datetime (or date) string into an aware datetime.
68
+
69
+ Naive values are floating local time in RFC 5545 terms, so they are read in
70
+ ``tz`` -- the same zone the daily windows are built in, which is what makes
71
+ "does this event overlap business hours" answerable at all.
72
+ """
73
+ if isinstance(value, dt.datetime):
74
+ return value if value.tzinfo else value.replace(tzinfo=tz)
75
+ if isinstance(value, dt.date):
76
+ return dt.datetime.combine(value, dt.time(0, 0), tzinfo=tz)
77
+ if not isinstance(value, str) or not value:
78
+ return None
79
+ try:
80
+ parsed = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
81
+ except ValueError:
82
+ logger.debug("Unparseable datetime %r", value)
83
+ return None
84
+ return parsed if parsed.tzinfo else parsed.replace(tzinfo=tz)
85
+
86
+
87
+ def event_is_busy(event: dict[str, Any], *, include_all_day: bool) -> bool:
88
+ """Whether an event should block time.
89
+
90
+ Four things make an event non-blocking, and all four matter on real
91
+ calendars:
92
+
93
+ * its calendar is marked "never show me as busy"
94
+ (``schedule-calendar-transp: transparent``, RFC 4791 5.2.9);
95
+ * the event itself is ``TRANSP:TRANSPARENT`` (RFC 5545 3.8.2.7);
96
+ * it is cancelled;
97
+ * it is all-day and the caller did not opt in. Birthdays, name days and
98
+ subscribed school-holiday feeds are all-day and OPAQUE, so honouring them
99
+ erases entire working days -- the exact complaint in issue #1394.
100
+ """
101
+ if event.get("calendar_transparent"):
102
+ return False
103
+ if str(event.get("transp") or "OPAQUE").upper() == "TRANSPARENT":
104
+ return False
105
+ if str(event.get("status") or "").upper() == "CANCELLED":
106
+ return False
107
+ if event.get("all_day") and not include_all_day:
108
+ return False
109
+ return True
110
+
111
+
112
+ def busy_spans_from_events(
113
+ events: list[dict[str, Any]],
114
+ *,
115
+ tz: dt.tzinfo,
116
+ include_all_day: bool = False,
117
+ ) -> list[Span]:
118
+ """Busy spans for the events that actually consume time."""
119
+ spans: list[Span] = []
120
+ for event in events:
121
+ if not event_is_busy(event, include_all_day=include_all_day):
122
+ continue
123
+
124
+ start = to_aware(event.get("start_datetime"), tz)
125
+ if start is None:
126
+ continue
127
+
128
+ end = to_aware(event.get("end_datetime"), tz)
129
+ if end is None and event.get("all_day"):
130
+ # An all-day event with no DTEND covers its one day.
131
+ end = start + dt.timedelta(days=1)
132
+ if end is None or end <= start:
133
+ # Zero-length (and inverted) events mark an instant, not a block.
134
+ continue
135
+ spans.append((start, end))
136
+ return spans
137
+
138
+
139
+ def busy_spans_from_vfreebusy(data: str, tz: dt.tzinfo) -> list[Span]:
140
+ """Busy spans from an RFC 6638 free/busy reply for one attendee.
141
+
142
+ Periods come back as ``start/end`` or ``start/duration``; icalendar hands
143
+ both back as a ``vPeriod`` whose ``.dt`` is a 2-tuple, with the FBTYPE
144
+ parameter attached per period rather than per FREEBUSY line.
145
+ """
146
+ try:
147
+ calendar = Calendar.from_ical(data)
148
+ except Exception as e: # icalendar raises bare ValueError subclasses
149
+ logger.warning("Unparseable free/busy reply: %s", e)
150
+ return []
151
+
152
+ spans: list[Span] = []
153
+ for component in calendar.walk("VFREEBUSY"):
154
+ periods = component.get("freebusy")
155
+ if periods is None:
156
+ continue
157
+ for period in periods if isinstance(periods, list) else [periods]:
158
+ span = _period_to_span(period, tz)
159
+ if span is not None:
160
+ spans.append(span)
161
+ return spans
162
+
163
+
164
+ def _period_to_span(period: Any, tz: dt.tzinfo) -> Span | None:
165
+ """One FREEBUSY period as a busy span, or None if it consumes no time."""
166
+ if str(period.params.get("FBTYPE", "BUSY")).upper() == _FREE_FBTYPE:
167
+ return None
168
+
169
+ start, end_or_duration = period.dt
170
+ end = (
171
+ start + end_or_duration
172
+ if isinstance(end_or_duration, dt.timedelta)
173
+ else end_or_duration
174
+ )
175
+ start = to_aware(start, tz)
176
+ end = to_aware(end, tz)
177
+ if start is None or end is None or end <= start:
178
+ return None
179
+ return (start, end)
180
+
181
+
182
+ def merge_spans(spans: list[Span]) -> list[Span]:
183
+ """Sort and coalesce overlapping/touching spans."""
184
+ merged: list[Span] = []
185
+ for start, end in sorted(spans):
186
+ if merged and start <= merged[-1][1]:
187
+ if end > merged[-1][1]:
188
+ merged[-1] = (merged[-1][0], end)
189
+ else:
190
+ merged.append((start, end))
191
+ return merged
192
+
193
+
194
+ def daily_windows(
195
+ start: dt.datetime,
196
+ end: dt.datetime,
197
+ *,
198
+ tz: dt.tzinfo,
199
+ business_hours_only: bool = True,
200
+ exclude_weekends: bool = True,
201
+ preferred_times: list[tuple[dt.time, dt.time]] | None = None,
202
+ ) -> list[Span]:
203
+ """The spans the caller is willing to meet in, day by day, clipped to
204
+ ``[start, end)``.
205
+
206
+ ``preferred_times`` *replaces* business hours rather than intersecting with
207
+ them. Intersecting would make ``preferred_times="08:00-09:00"`` return
208
+ nothing at all under the default ``business_hours_only=True`` -- an empty
209
+ answer that looks like "you are fully booked", which is the failure mode
210
+ this whole tool is being fixed for.
211
+ """
212
+ windows: list[Span] = []
213
+ day = start.astimezone(tz).date()
214
+ last_day = end.astimezone(tz).date()
215
+ ranges = preferred_times or (
216
+ [(BUSINESS_START, BUSINESS_END)] if business_hours_only else []
217
+ )
218
+
219
+ while day <= last_day:
220
+ if exclude_weekends and day.weekday() >= 5:
221
+ day += dt.timedelta(days=1)
222
+ continue
223
+
224
+ if ranges:
225
+ # Merged, because overlapping preferred ranges ("09:00-12:00,
226
+ # 11:00-14:00") would otherwise yield overlapping windows and hand
227
+ # the caller the same free time twice.
228
+ day_spans = merge_spans(
229
+ [
230
+ (
231
+ dt.datetime.combine(day, from_time, tzinfo=tz),
232
+ dt.datetime.combine(day, to_time, tzinfo=tz),
233
+ )
234
+ for from_time, to_time in ranges
235
+ ]
236
+ )
237
+ else:
238
+ midnight = dt.datetime.combine(day, dt.time(0, 0), tzinfo=tz)
239
+ day_spans = [(midnight, midnight + dt.timedelta(days=1))]
240
+
241
+ for window_start, window_end in day_spans:
242
+ clipped_start = max(window_start, start)
243
+ clipped_end = min(window_end, end)
244
+ if clipped_start < clipped_end:
245
+ windows.append((clipped_start, clipped_end))
246
+
247
+ day += dt.timedelta(days=1)
248
+
249
+ return sorted(windows)
250
+
251
+
252
+ def free_slots(
253
+ windows: list[Span], busy: list[Span], minimum: dt.timedelta
254
+ ) -> list[Span]:
255
+ """Subtract busy spans from the candidate windows, keeping what is long enough."""
256
+ busy = merge_spans(busy)
257
+ return [slot for window in windows for slot in _free_within(window, busy, minimum)]
258
+
259
+
260
+ def _free_within(window: Span, busy: list[Span], minimum: dt.timedelta) -> list[Span]:
261
+ """The gaps of at least ``minimum`` left in one window. ``busy`` is merged."""
262
+ window_start, window_end = window
263
+ slots: list[Span] = []
264
+ cursor = window_start
265
+
266
+ for busy_start, busy_end in busy:
267
+ if busy_end <= cursor:
268
+ continue
269
+ if busy_start >= window_end:
270
+ break
271
+ if busy_start - cursor >= minimum:
272
+ slots.append((cursor, busy_start))
273
+ cursor = max(cursor, busy_end)
274
+ if cursor >= window_end:
275
+ break
276
+
277
+ if window_end - cursor >= minimum:
278
+ slots.append((cursor, window_end))
279
+ return slots
280
+
281
+
282
+ def slot_to_dict(span: Span) -> dict[str, Any]:
283
+ """Render a span the way ``AvailabilitySlot`` expects it."""
284
+ start, end = span
285
+ return {
286
+ "start": start.isoformat(),
287
+ "end": end.isoformat(),
288
+ "duration_minutes": int((end - start).total_seconds() // 60),
289
+ "date": start.date().isoformat(),
290
+ }