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.
- nextcloud_client/__init__.py +477 -0
- nextcloud_client/auth.py +34 -0
- nextcloud_client/availability.py +290 -0
- nextcloud_client/base.py +443 -0
- nextcloud_client/calendar.py +3430 -0
- nextcloud_client/collectives.py +325 -0
- nextcloud_client/contacts.py +1321 -0
- nextcloud_client/cookbook.py +244 -0
- nextcloud_client/dav_errors.py +187 -0
- nextcloud_client/dav_urls.py +61 -0
- nextcloud_client/deck.py +930 -0
- nextcloud_client/groups.py +164 -0
- nextcloud_client/http.py +69 -0
- nextcloud_client/instrumentation.py +50 -0
- nextcloud_client/mail.py +825 -0
- nextcloud_client/models/__init__.py +1 -0
- nextcloud_client/models/deck.py +302 -0
- nextcloud_client/models/sharing.py +24 -0
- nextcloud_client/models/talk.py +136 -0
- nextcloud_client/models/users.py +41 -0
- nextcloud_client/news.py +394 -0
- nextcloud_client/notes.py +293 -0
- nextcloud_client/notes_search.py +113 -0
- nextcloud_client/ocs.py +140 -0
- nextcloud_client/py.typed +0 -0
- nextcloud_client/sharing.py +364 -0
- nextcloud_client/shopping_list.py +150 -0
- nextcloud_client/tables.py +146 -0
- nextcloud_client/talk.py +487 -0
- nextcloud_client/users.py +239 -0
- nextcloud_client/webdav.py +3046 -0
- nextcloud_client-0.211.0.dist-info/METADATA +102 -0
- nextcloud_client-0.211.0.dist-info/RECORD +34 -0
- nextcloud_client-0.211.0.dist-info/WHEEL +4 -0
|
@@ -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
|
+
}
|