vdirsyncer-graph 0.1.0__py3-none-any.whl

graphpim/__init__.py

@@ -0,0 +1,13 @@
+"""graphpim: Microsoft Graph JSON <-> iCalendar / vCard mapping.
+
+Pure functions, no network. The semantics mirror the Microsoft 365 (Graph)
+resource in kdepim-runtime (resources/graph) and are pinned by the fixtures in
+``fixtures/`` so that other implementations can verify against the same cases.
+
+SPDX-FileCopyrightText: 2026 Malte Zilinski <malte@zilinski.eu>
+SPDX-License-Identifier: LGPL-2.0-or-later
+"""
+
+from graphpim import contacts, events, todos
+
+__all__ = ["contacts", "events", "todos"]

graphpim/_datetime.py

@@ -0,0 +1,68 @@
+"""Graph ``dateTimeTimeZone`` <-> Python datetime helpers."""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, datetime, timezone, tzinfo
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+log = logging.getLogger(__name__)
+
+GRAPH_FORMAT = "%Y-%m-%dT%H:%M:%S.0000000"
+
+
+def _zone(name: str | None) -> tzinfo:
+    """Resolve a Graph timeZone value (IANA or Windows name) to a tzinfo."""
+    if not name or name.upper() == "UTC":
+        return timezone.utc
+    try:
+        return ZoneInfo(name)
+    except (ZoneInfoNotFoundError, ValueError):
+        pass
+    try:  # Windows names such as "W. Europe Standard Time"
+        from tzlocal.windows_tz import win_tz
+
+        iana = win_tz.get(name)
+        if iana:
+            return ZoneInfo(iana)
+    except ImportError:  # pragma: no cover
+        pass
+    log.warning("unknown Graph time zone %r, falling back to UTC", name)
+    return timezone.utc
+
+
+def parse_graph_datetime(dtz: dict | None, *, all_day: bool = False) -> datetime | date | None:
+    """Graph ``{"dateTime": "...", "timeZone": "..."}`` -> aware datetime (or date).
+
+    Graph uses 7 fractional digits, which ``datetime.fromisoformat`` rejects on
+    older Pythons; the fraction is dropped. All-day values are taken verbatim as a
+    date (converting the midnight to another zone would shift the day).
+    """
+    if not dtz:
+        return None
+    raw = dtz.get("dateTime") or ""
+    if not raw:
+        return None
+    raw = raw.split(".", 1)[0]
+    try:
+        naive = datetime.strptime(raw, "%Y-%m-%dT%H:%M:%S")
+    except ValueError:
+        return None
+    if all_day:
+        return naive.date()
+    return naive.replace(tzinfo=_zone(dtz.get("timeZone")))
+
+
+def to_graph_datetime(value: datetime | date) -> dict:
+    """datetime/date -> Graph ``dateTimeTimeZone`` in UTC.
+
+    Dates (all-day) are written verbatim at midnight; aware datetimes are
+    converted to UTC, naive ones are assumed to be UTC.
+    """
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        text = value.astimezone(timezone.utc).strftime(GRAPH_FORMAT)
+    else:
+        text = f"{value.isoformat()}T00:00:00.0000000"
+    return {"dateTime": text, "timeZone": "UTC"}

graphpim/_ical.py

@@ -0,0 +1,62 @@
+"""Shared iCalendar helpers (icalendar package)."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+
+from icalendar import Calendar
+
+PRODID = "-//graphpim//Microsoft Graph mapping//EN"
+
+
+def new_calendar() -> Calendar:
+    cal = Calendar()
+    cal.add("prodid", PRODID)
+    cal.add("version", "2.0")
+    return cal
+
+
+def first_component(raw: str, name: str):
+    """Parse an iCalendar text and return the first component of ``name``."""
+    cal = Calendar.from_ical(raw)
+    if cal.name == name:
+        return cal
+    for comp in cal.walk(name):
+        return comp
+    raise ValueError(f"no {name} component in item")
+
+
+def categories(comp) -> list[str]:
+    cats: list[str] = []
+    for prop in comp.get("categories", []) if isinstance(comp.get("categories"), list) else [comp.get("categories")]:
+        if prop is None:
+            continue
+        if hasattr(prop, "cats"):
+            cats.extend(str(c) for c in prop.cats)
+        else:
+            cats.extend(s.strip() for s in str(prop).split(",") if s.strip())
+    return cats
+
+
+def text(comp, key: str) -> str:
+    v = comp.get(key)
+    return "" if v is None else str(v)
+
+
+def decoded(comp, key: str):
+    """Decoded DTSTART/DTEND/DUE/COMPLETED or None."""
+    if comp.get(key) is None:
+        return None
+    return comp.decoded(key)
+
+
+def as_utc(value: datetime | date) -> datetime | date:
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+    return value
+
+
+def stamp() -> datetime:
+    return datetime.now(timezone.utc).replace(microsecond=0)

graphpim/contacts.py

@@ -0,0 +1,176 @@
+"""Graph ``contact`` <-> vCard 3.0.
+
+Semantics (mirroring kdepim-runtime resources/graph/contact/graphcontacthandler.cpp):
+
+* N = surname;givenName;middleName;title(prefix); FN = displayName.
+* First e-mail address is TYPE=PREF; order is preserved.
+* businessPhones -> TEL;TYPE=WORK, homePhones -> TEL;TYPE=HOME,
+  mobilePhone -> TEL;TYPE=CELL (one mobile number only).
+* businessAddress -> ADR;TYPE=WORK, homeAddress -> ADR;TYPE=HOME
+  (street;city;state;postalCode;countryOrRegion). Addresses without a
+  ``street`` key are ignored on read, as in the KDE handler.
+* birthday is read into BDAY but **never written back**: Exchange reacts to a
+  birthday write by creating a recurring event in the Birthdays calendar.
+* The photo is not part of the contact JSON. Callers fetch
+  ``/me/contacts/{id}/photo/$value`` separately and pass ``photo=(bytes, mime)``.
+"""
+
+from __future__ import annotations
+
+import base64
+from datetime import datetime
+
+from graphpim.vcard import Property, escape, parse, serialize, split_structured
+
+_ADDR_KEYS = ("street", "city", "state", "postalCode", "countryOrRegion")
+
+
+def _adr(json: dict, kind: str) -> Property:
+    parts = ["", "", json.get("street") or "", json.get("city") or "", json.get("state") or "",
+             json.get("postalCode") or "", json.get("countryOrRegion") or ""]
+    return Property("ADR", ";".join(escape(p) for p in parts), {"TYPE": [kind]})
+
+
+def graph_to_vcard(json: dict, photo: tuple[bytes, str] | None = None) -> str:
+    props: list[Property] = []
+    if json.get("id"):
+        props.append(Property("UID", escape(json["id"])))
+    n = [json.get("surname") or "", json.get("givenName") or "", json.get("middleName") or "",
+         json.get("title") or "", ""]
+    props.append(Property("N", ";".join(escape(p) for p in n)))
+    fn = json.get("displayName") or " ".join(p for p in (json.get("givenName"), json.get("surname")) if p)
+    props.append(Property("FN", escape(fn)))
+    if json.get("nickName"):
+        props.append(Property("NICKNAME", escape(json["nickName"])))
+
+    for i, e in enumerate(json.get("emailAddresses") or []):
+        addr = (e or {}).get("address")
+        if addr:
+            params = {"TYPE": ["INTERNET", "PREF"]} if i == 0 else {"TYPE": ["INTERNET"]}
+            props.append(Property("EMAIL", escape(addr), params))
+
+    for num in json.get("businessPhones") or []:
+        if num:
+            props.append(Property("TEL", escape(num), {"TYPE": ["WORK", "VOICE"]}))
+    for num in json.get("homePhones") or []:
+        if num:
+            props.append(Property("TEL", escape(num), {"TYPE": ["HOME", "VOICE"]}))
+    if json.get("mobilePhone"):
+        props.append(Property("TEL", escape(json["mobilePhone"]), {"TYPE": ["CELL"]}))
+
+    if json.get("jobTitle"):
+        props.append(Property("TITLE", escape(json["jobTitle"])))
+    org = json.get("companyName") or ""
+    dept = json.get("department") or ""
+    if org or dept:
+        props.append(Property("ORG", f"{escape(org)};{escape(dept)}" if dept else escape(org)))
+    if json.get("personalNotes"):
+        props.append(Property("NOTE", escape(json["personalNotes"])))
+
+    business = json.get("businessAddress") or {}
+    if business and "street" in business:
+        props.append(_adr(business, "WORK"))
+    home = json.get("homeAddress") or {}
+    if home and "street" in home:
+        props.append(_adr(home, "HOME"))
+
+    birthday = json.get("birthday")
+    if birthday:
+        try:
+            props.append(Property("BDAY", datetime.fromisoformat(birthday.replace("Z", "+00:00")).date().isoformat()))
+        except ValueError:
+            pass
+
+    cats = [c for c in json.get("categories") or [] if c]
+    if cats:
+        props.append(Property("CATEGORIES", ",".join(escape(c) for c in cats)))
+
+    if photo and photo[0]:
+        data, mime = photo
+        sub = (mime.split("/", 1)[1] if "/" in mime else mime or "jpeg").upper()
+        props.append(Property("PHOTO", base64.b64encode(data).decode("ascii"), {"ENCODING": ["b"], "TYPE": [sub]}))
+    return serialize(props)
+
+
+def _types(prop: Property) -> set[str]:
+    return set(prop.param("TYPE"))
+
+
+def vcard_to_graph(raw: str) -> dict:
+    """vCard text -> Graph contact JSON body for POST/PATCH (photo excluded)."""
+    props = parse(raw)
+    by_name: dict[str, list[Property]] = {}
+    for p in props:
+        by_name.setdefault(p.name, []).append(p)
+
+    def one(name: str) -> str:
+        return split_structured(by_name[name][0].value, "\x00")[0] if name in by_name else ""
+
+    json: dict = {}
+    n = split_structured(by_name["N"][0].value) if "N" in by_name else []
+    n += [""] * (5 - len(n))
+    json["surname"] = n[0]
+    json["givenName"] = n[1]
+    json["middleName"] = n[2]
+    json["title"] = n[3]
+    json["nickName"] = one("NICKNAME")
+    json["displayName"] = one("FN")
+    json["jobTitle"] = one("TITLE")
+    org = split_structured(by_name["ORG"][0].value) if "ORG" in by_name else []
+    json["companyName"] = org[0] if org else ""
+    json["department"] = org[1] if len(org) > 1 else ""
+    json["personalNotes"] = one("NOTE")
+
+    emails = [p for p in by_name.get("EMAIL", [])]
+    emails.sort(key=lambda p: 0 if "PREF" in _types(p) or "PREF" in p.params else 1)
+    json["emailAddresses"] = [{"address": split_structured(p.value, "\x00")[0]} for p in emails if p.value]
+
+    business, home, mobile = [], [], ""
+    for p in by_name.get("TEL", []):
+        num = split_structured(p.value, "\x00")[0]
+        if not num:
+            continue
+        t = _types(p)
+        if "CELL" in t:
+            mobile = mobile or num
+        elif "HOME" in t:
+            home.append(num)
+        else:
+            business.append(num)
+    json["businessPhones"] = business
+    json["homePhones"] = home
+    if mobile:
+        json["mobilePhone"] = mobile
+
+    for p in by_name.get("ADR", []):
+        parts = split_structured(p.value)
+        parts += [""] * (7 - len(parts))
+        addr = dict(zip(_ADDR_KEYS, parts[2:7]))
+        if not any(addr.values()):
+            continue
+        key = "homeAddress" if "HOME" in _types(p) else "businessAddress"
+        json.setdefault(key, addr)
+
+    # BDAY deliberately not written (see module docstring).
+    cats: list[str] = []
+    for p in by_name.get("CATEGORIES", []):
+        cats.extend(c for c in split_structured(p.value, ",") if c)
+    json["categories"] = cats
+    return json
+
+
+def vcard_photo(raw: str) -> tuple[bytes, str] | None:
+    """Extract an inline PHOTO (base64) as (bytes, mime) for the photo endpoint."""
+    for p in parse(raw):
+        if p.name != "PHOTO":
+            continue
+        enc = {v.upper() for v in p.param("ENCODING")}
+        value = p.value
+        if value.lower().startswith("data:"):  # vCard 4 data URI
+            header, _, b64 = value.partition(",")
+            mime = header[5:].split(";", 1)[0] or "image/jpeg"
+            return base64.b64decode(b64), mime
+        if "B" in enc or "BASE64" in enc:
+            sub = (p.param("TYPE") or ["JPEG"])[0].lower()
+            return base64.b64decode(value), f"image/{sub}"
+    return None

graphpim/events.py

@@ -0,0 +1,200 @@
+"""Graph ``event`` <-> VEVENT.
+
+Semantics (mirroring kdepim-runtime resources/graph/calendar/grapheventhandler.cpp):
+
+* UID = ``iCalUId``, falling back to the Graph ``id``.
+* Only ``body.contentType == "text"`` is mapped to DESCRIPTION; HTML bodies fall
+  back to ``bodyPreview``. Written bodies are always plain text.
+* Times are written in UTC. All-day events are DATE values; Graph's all-day end
+  is exclusive, exactly like iCalendar DTEND, so no +-1 day is needed here
+  (KCalendarCore's inclusive end was a KDE-only concern).
+* ``showAs == "free"`` -> TRANSP:TRANSPARENT, everything else busy/OPAQUE.
+* ``sensitivity`` private/confidential -> CLASS.
+* Attendee ``status.response`` -> PARTSTAT.
+* Recurrence via :mod:`graphpim.recurrence`.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from icalendar import Event, vCalAddress, vRecur
+
+from graphpim import _ical
+from graphpim._datetime import parse_graph_datetime, to_graph_datetime
+from graphpim.recurrence import graph_to_rrule, rrule_to_graph
+
+_RESPONSE_TO_PARTSTAT = {
+    "accepted": "ACCEPTED",
+    "declined": "DECLINED",
+    "tentativelyAccepted": "TENTATIVE",
+    "notResponded": "NEEDS-ACTION",
+    "none": "NEEDS-ACTION",
+    "organizer": "ACCEPTED",
+}
+_PARTSTAT_TO_RESPONSE = {
+    "ACCEPTED": "accepted",
+    "DECLINED": "declined",
+    "TENTATIVE": "tentativelyAccepted",
+}
+
+
+def graph_to_event(json: dict) -> Event | None:
+    """Graph event JSON -> icalendar.Event. None when the JSON carries no ``id``."""
+    gid = json.get("id") or ""
+    if not gid:
+        return None
+    ev = Event()
+    ev.add("uid", json.get("iCalUId") or gid)
+    ev.add("dtstamp", _ical.stamp())
+    ev.add("summary", json.get("subject") or "")
+
+    body = json.get("body") or {}
+    if body.get("contentType") == "text":
+        description = body.get("content") or ""
+    else:
+        description = json.get("bodyPreview") or ""
+    if description:
+        ev.add("description", description)
+
+    all_day = bool(json.get("isAllDay"))
+    start = parse_graph_datetime(json.get("start"), all_day=all_day)
+    end = parse_graph_datetime(json.get("end"), all_day=all_day)
+    if start is not None:
+        ev.add("dtstart", start)
+    if end is not None:
+        ev.add("dtend", end)
+
+    location = (json.get("location") or {}).get("displayName") or ""
+    if location:
+        ev.add("location", location)
+
+    organizer = (json.get("organizer") or {}).get("emailAddress") or {}
+    if organizer.get("address"):
+        org = vCalAddress(f"mailto:{organizer['address']}")
+        if organizer.get("name"):
+            org.params["CN"] = organizer["name"]
+        ev.add("organizer", org, encode=0)
+
+    for att in json.get("attendees") or []:
+        email = (att.get("emailAddress") or {})
+        if not email.get("address"):
+            continue
+        addr = vCalAddress(f"mailto:{email['address']}")
+        if email.get("name"):
+            addr.params["CN"] = email["name"]
+        response = (att.get("status") or {}).get("response")
+        if response in _RESPONSE_TO_PARTSTAT:
+            addr.params["PARTSTAT"] = _RESPONSE_TO_PARTSTAT[response]
+        att_type = att.get("type")
+        if att_type == "optional":
+            addr.params["ROLE"] = "OPT-PARTICIPANT"
+        elif att_type == "resource":
+            addr.params["CUTYPE"] = "RESOURCE"
+        ev.add("attendee", addr, encode=0)
+
+    cats = [c for c in json.get("categories") or [] if c]
+    if cats:
+        ev.add("categories", cats)
+
+    ev.add("transp", "TRANSPARENT" if json.get("showAs") == "free" else "OPAQUE")
+    sensitivity = json.get("sensitivity")
+    if sensitivity == "private":
+        ev.add("class", "PRIVATE")
+    elif sensitivity == "confidential":
+        ev.add("class", "CONFIDENTIAL")
+
+    if json.get("isCancelled"):
+        ev.add("status", "CANCELLED")
+
+    rrule = graph_to_rrule(json.get("recurrence"))
+    if rrule:
+        ev.add("rrule", vRecur(rrule))
+    return ev
+
+
+def graph_to_ical(json: dict) -> str | None:
+    """Graph event JSON -> full VCALENDAR text (or None without ``id``)."""
+    ev = graph_to_event(json)
+    if ev is None:
+        return None
+    cal = _ical.new_calendar()
+    cal.add_component(ev)
+    return cal.to_ical().decode("utf-8")
+
+
+def event_to_graph(ev: Event) -> dict:
+    """icalendar.Event -> Graph event JSON body for POST/PATCH."""
+    json: dict = {"subject": _ical.text(ev, "summary")}
+    json["body"] = {"contentType": "text", "content": _ical.text(ev, "description")}
+
+    start = _ical.decoded(ev, "dtstart")
+    end = _ical.decoded(ev, "dtend")
+    all_day = isinstance(start, date) and not isinstance(start, datetime)
+    json["isAllDay"] = all_day
+    if start is not None:
+        if end is None:
+            duration = ev.get("duration")
+            if duration is not None:
+                end = start + duration.dt
+            elif all_day:
+                end = start + (date(2000, 1, 2) - date(2000, 1, 1))
+            else:
+                end = start
+        if all_day and isinstance(end, datetime):
+            end = end.date()
+        json["start"] = to_graph_datetime(_ical.as_utc(start))
+        json["end"] = to_graph_datetime(_ical.as_utc(end))
+
+    location = _ical.text(ev, "location")
+    if location:
+        json["location"] = {"displayName": location}
+
+    cats = _ical.categories(ev)
+    if cats:
+        json["categories"] = cats
+
+    json["showAs"] = "free" if _ical.text(ev, "transp").upper() == "TRANSPARENT" else "busy"
+    klass = _ical.text(ev, "class").upper()
+    if klass == "PRIVATE":
+        json["sensitivity"] = "private"
+    elif klass == "CONFIDENTIAL":
+        json["sensitivity"] = "confidential"
+    elif klass:
+        json["sensitivity"] = "normal"
+
+    attendees = []
+    raw_attendees = ev.get("attendee")
+    if raw_attendees is not None:
+        if not isinstance(raw_attendees, list):
+            raw_attendees = [raw_attendees]
+        for a in raw_attendees:
+            address = str(a)
+            if address.lower().startswith("mailto:"):
+                address = address[7:]
+            if not address:
+                continue
+            entry: dict = {"emailAddress": {"address": address}}
+            name = a.params.get("CN") if hasattr(a, "params") else None
+            if name:
+                entry["emailAddress"]["name"] = str(name)
+            partstat = str(a.params.get("PARTSTAT", "")).upper() if hasattr(a, "params") else ""
+            if partstat in _PARTSTAT_TO_RESPONSE:
+                entry["status"] = {"response": _PARTSTAT_TO_RESPONSE[partstat], "time": "0001-01-01T00:00:00Z"}
+            role = str(a.params.get("ROLE", "")).upper() if hasattr(a, "params") else ""
+            cutype = str(a.params.get("CUTYPE", "")).upper() if hasattr(a, "params") else ""
+            entry["type"] = "resource" if cutype == "RESOURCE" else ("optional" if role == "OPT-PARTICIPANT" else "required")
+            attendees.append(entry)
+    if attendees:
+        json["attendees"] = attendees
+
+    if start is not None:
+        recurrence = rrule_to_graph(ev.get("rrule"), start)
+        if recurrence:
+            json["recurrence"] = recurrence
+    return json
+
+
+def ical_to_graph(raw: str) -> dict:
+    """VCALENDAR/VEVENT text -> Graph event JSON body."""
+    return event_to_graph(_ical.first_component(raw, "VEVENT"))