zimbra-client 0.3.2__py3-none-any.whl

zimbra_client/__init__.py

@@ -0,0 +1,92 @@
+"""End-user Zimbra SOAP client."""
+
+from .client import (
+    ACCOUNT_NAMESPACE,
+    MAIL_NAMESPACE,
+    SOAP_NAMESPACE,
+    ZIMBRA_NAMESPACE,
+    ZimbraClient,
+    build_soap_envelope,
+    local_name,
+)
+from .config import ZimbraConfig, normalize_base_url
+from .errors import (
+    ZimbraAuthenticationError,
+    ZimbraConfigError,
+    ZimbraConnectionError,
+    ZimbraError,
+    ZimbraHTTPError,
+    ZimbraLimitError,
+    ZimbraNotFoundError,
+    ZimbraProtocolError,
+    ZimbraSOAPFault,
+)
+from .filters import (
+    filter_discard,
+    filter_file_into,
+    filter_from_address,
+    filter_keep,
+    filter_stop,
+    filter_subject_contains,
+    filter_tag,
+)
+from .models import (
+    AppointmentSummary,
+    Attachment,
+    Contact,
+    FilterAction,
+    FilterRule,
+    FilterTest,
+    Folder,
+    Identity,
+    Message,
+    Preference,
+    Recipient,
+    SearchResult,
+    SendResult,
+    Signature,
+    Task,
+)
+
+__all__ = [
+    "ACCOUNT_NAMESPACE",
+    "AppointmentSummary",
+    "Attachment",
+    "Contact",
+    "FilterAction",
+    "FilterRule",
+    "FilterTest",
+    "Folder",
+    "Identity",
+    "MAIL_NAMESPACE",
+    "Message",
+    "Preference",
+    "Recipient",
+    "SOAP_NAMESPACE",
+    "SearchResult",
+    "SendResult",
+    "Signature",
+    "Task",
+    "ZIMBRA_NAMESPACE",
+    "ZimbraAuthenticationError",
+    "ZimbraClient",
+    "ZimbraConfig",
+    "ZimbraConfigError",
+    "ZimbraConnectionError",
+    "ZimbraError",
+    "ZimbraHTTPError",
+    "ZimbraLimitError",
+    "ZimbraNotFoundError",
+    "ZimbraProtocolError",
+    "ZimbraSOAPFault",
+    "build_soap_envelope",
+    "filter_discard",
+    "filter_file_into",
+    "filter_from_address",
+    "filter_keep",
+    "filter_stop",
+    "filter_subject_contains",
+    "filter_tag",
+    "local_name",
+    "normalize_base_url",
+]

zimbra_client/account.py

@@ -0,0 +1,225 @@
+"""SOAP request builders and response parsers for Zimbra account operations."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from typing import Mapping, Optional, Sequence, Tuple
+
+from .errors import ZimbraNotFoundError
+from .models import Identity, Preference, Signature
+
+ACCOUNT_NAMESPACE = "urn:zimbraAccount"
+
+
+def local_name(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1] if "}" in tag else tag
+
+
+def _qname(namespace: str, name: str) -> str:
+    return f"{{{namespace}}}{name}"
+
+
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _attr(element: ET.Element, name: str, default: str = "") -> str:
+    return _text(element.get(name, default))
+
+
+def _parse_signature(element: ET.Element) -> Signature:
+    text_plain = ""
+    text_html = ""
+    for child in element:
+        if local_name(child.tag) != "content":
+            continue
+        content_type = _attr(child, "type")
+        if content_type == "text/html":
+            text_html = _text(child.text)
+        else:
+            text_plain = _text(child.text)
+    return Signature(
+        id=_attr(element, "id"),
+        name=_attr(element, "name"),
+        text_plain=text_plain,
+        text_html=text_html,
+        contact_id=_attr(element, "cid"),
+    )
+
+
+def _parse_identity(element: ET.Element) -> Identity:
+    attrs = {}
+    for child in element:
+        if local_name(child.tag) == "a":
+            name = _attr(child, "name")
+            if name:
+                attrs[name] = _text(child.text)
+    return Identity(
+        id=_attr(element, "id"),
+        name=_attr(element, "name"),
+        attrs=attrs,
+    )
+
+
+def _parse_pref(element: ET.Element) -> Preference:
+    modified = _attr(element, "modified")
+    return Preference(
+        name=_attr(element, "name"),
+        value=_text(element.text),
+        modified=int(modified) if modified.isdigit() else None,
+    )
+
+
+def parse_signatures_response(root: ET.Element) -> Tuple[Signature, ...]:
+    return tuple(
+        _parse_signature(elem)
+        for elem in root.iter()
+        if local_name(elem.tag) == "signature" and _attr(elem, "id")
+    )
+
+
+def parse_signature_response(root: ET.Element, *, signature_id: str = "") -> Signature:
+    signatures = parse_signatures_response(root)
+    if signatures:
+        return signatures[0]
+    raise ZimbraNotFoundError(
+        "Signature not found in response",
+        resource_type="signature",
+        resource_id=signature_id,
+    )
+
+
+def parse_identities_response(root: ET.Element) -> Tuple[Identity, ...]:
+    return tuple(
+        _parse_identity(elem)
+        for elem in root.iter()
+        if local_name(elem.tag) == "identity" and _attr(elem, "id")
+    )
+
+
+def parse_identity_response(root: ET.Element, *, identity_id: str = "") -> Identity:
+    identities = parse_identities_response(root)
+    if identities:
+        return identities[0]
+    raise ZimbraNotFoundError(
+        "Identity not found in response",
+        resource_type="identity",
+        resource_id=identity_id,
+    )
+
+
+def parse_prefs_response(root: ET.Element) -> Tuple[Preference, ...]:
+    return tuple(
+        _parse_pref(elem)
+        for elem in root.iter()
+        if local_name(elem.tag) == "pref" and _attr(elem, "name")
+    )
+
+
+def build_get_signatures_request() -> ET.Element:
+    return ET.Element(_qname(ACCOUNT_NAMESPACE, "GetSignaturesRequest"))
+
+
+def build_create_signature_request(
+    name: str,
+    *,
+    text: str = "",
+    html: str = "",
+    contact_id: str = "",
+) -> ET.Element:
+    request = ET.Element(_qname(ACCOUNT_NAMESPACE, "CreateSignatureRequest"))
+    signature = ET.SubElement(request, "signature")
+    signature.set("name", name)
+    if contact_id:
+        cid = ET.SubElement(signature, "cid")
+        cid.text = contact_id
+    if text:
+        content = ET.SubElement(signature, "content")
+        content.set("type", "text/plain")
+        content.text = text
+    if html:
+        content = ET.SubElement(signature, "content")
+        content.set("type", "text/html")
+        content.text = html
+    return request
+
+
+def build_modify_signature_request(
+    signature_id: str,
+    *,
+    name: Optional[str] = None,
+    text: Optional[str] = None,
+    html: Optional[str] = None,
+) -> ET.Element:
+    request = ET.Element(_qname(ACCOUNT_NAMESPACE, "ModifySignatureRequest"))
+    signature = ET.SubElement(request, "signature")
+    signature.set("id", signature_id)
+    if name is not None:
+        signature.set("name", name)
+    if text is not None:
+        content = ET.SubElement(signature, "content")
+        content.set("type", "text/plain")
+        content.text = text
+    if html is not None:
+        content = ET.SubElement(signature, "content")
+        content.set("type", "text/html")
+        content.text = html
+    return request
+
+
+def build_delete_signature_request(signature_id: str) -> ET.Element:
+    request = ET.Element(_qname(ACCOUNT_NAMESPACE, "DeleteSignatureRequest"))
+    signature = ET.SubElement(request, "signature")
+    signature.set("id", signature_id)
+    return request
+
+
+def build_get_identities_request() -> ET.Element:
+    return ET.Element(_qname(ACCOUNT_NAMESPACE, "GetIdentitiesRequest"))
+
+
+def _append_identity_attrs(parent: ET.Element, attrs: Mapping[str, str]) -> None:
+    for name, value in attrs.items():
+        element = ET.SubElement(parent, "a")
+        element.set("name", name)
+        element.text = str(value)
+
+
+def build_create_identity_request(name: str, attrs: Mapping[str, str]) -> ET.Element:
+    request = ET.Element(_qname(ACCOUNT_NAMESPACE, "CreateIdentityRequest"))
+    identity = ET.SubElement(request, "identity")
+    identity.set("name", name)
+    _append_identity_attrs(identity, attrs)
+    return request
+
+
+def build_modify_identity_request(identity_id: str, attrs: Mapping[str, str]) -> ET.Element:
+    request = ET.Element(_qname(ACCOUNT_NAMESPACE, "ModifyIdentityRequest"))
+    identity = ET.SubElement(request, "identity")
+    identity.set("id", identity_id)
+    _append_identity_attrs(identity, attrs)
+    return request
+
+
+def build_delete_identity_request(identity_id: str) -> ET.Element:
+    request = ET.Element(_qname(ACCOUNT_NAMESPACE, "DeleteIdentityRequest"))
+    identity = ET.SubElement(request, "identity")
+    identity.set("id", identity_id)
+    return request
+
+
+def build_get_prefs_request(names: Sequence[str] = ()) -> ET.Element:
+    request = ET.Element(_qname(ACCOUNT_NAMESPACE, "GetPrefsRequest"))
+    for name in names:
+        pref = ET.SubElement(request, "pref")
+        pref.set("name", name)
+    return request
+
+
+def build_modify_prefs_request(values: Mapping[str, str]) -> ET.Element:
+    request = ET.Element(_qname(ACCOUNT_NAMESPACE, "ModifyPrefsRequest"))
+    for name, value in values.items():
+        pref = ET.SubElement(request, "pref")
+        pref.set("name", name)
+        pref.text = str(value)
+    return request

zimbra_client/calendar.py

@@ -0,0 +1,339 @@
+"""SOAP request builders and response parsers for Zimbra calendar and tasks."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from datetime import datetime
+from typing import Mapping, Optional, Sequence, Tuple, Union
+
+from .errors import ZimbraNotFoundError
+from .mail import _append_body_parts
+from .models import AppointmentSummary, Task, datetime_to_epoch_ms, epoch_ms_to_datetime
+
+MAIL_NAMESPACE = "urn:zimbraMail"
+
+
+def local_name(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1] if "}" in tag else tag
+
+
+def _qname(namespace: str, name: str) -> str:
+    return f"{{{namespace}}}{name}"
+
+
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _attr(element: ET.Element, name: str, default: str = "") -> str:
+    return _text(element.get(name, default))
+
+
+def _instance_times(element: ET.Element) -> Tuple[Optional[datetime], Optional[datetime]]:
+    start_ms = _attr(element, "s")
+    duration_ms = _attr(element, "d") or _attr(element, "dur")
+    start = epoch_ms_to_datetime(start_ms) if start_ms else None
+    end = None
+    if start and duration_ms.isdigit():
+        end = epoch_ms_to_datetime(int(start_ms) + int(duration_ms))
+    end_attr = _attr(element, "e")
+    if end_attr:
+        end = epoch_ms_to_datetime(end_attr)
+    return start, end
+
+
+def _parse_appointment(element: ET.Element) -> AppointmentSummary:
+    start, end = _instance_times(element)
+    inst = next((item for item in element if local_name(item.tag) == "inst"), None)
+    if inst is not None:
+        inst_start, inst_end = _instance_times(inst)
+        start = inst_start or start
+        end = inst_end or end
+    return AppointmentSummary(
+        id=_attr(element, "id") or _attr(element, "invId"),
+        uid=_attr(element, "uid"),
+        name=_attr(element, "name"),
+        location=_attr(element, "loc"),
+        start=start,
+        end=end,
+        folder_id=_attr(element, "l"),
+        all_day=_attr(element, "allDay") in {"1", "true"},
+        status=_attr(element, "status"),
+    )
+
+
+def _parse_task_from_inv(comp: ET.Element, task_id: str = "") -> Task:
+    body_text = ""
+    for child in comp.iter():
+        if local_name(child.tag) == "mp" and _attr(child, "body") == "1":
+            content = next((item for item in child if local_name(item.tag) == "content"), None)
+            if content is not None and _text(content.text):
+                body_text = _text(content.text)
+                break
+    due = epoch_ms_to_datetime(_attr(comp, "due"))
+    status = _attr(comp, "status") or _attr(comp, "ptst")
+    return Task(
+        id=task_id or _attr(comp, "calItemId"),
+        subject=_attr(comp, "name"),
+        status=status,
+        due=due,
+        location=_attr(comp, "loc"),
+        body_text=body_text,
+        completed=status in {"COMP", "CO"},
+    )
+
+
+def parse_appointments_response(root: ET.Element) -> Tuple[AppointmentSummary, ...]:
+    return tuple(
+        _parse_appointment(elem)
+        for elem in root.iter()
+        if local_name(elem.tag) == "appt" and (_attr(elem, "id") or _attr(elem, "invId"))
+    )
+
+
+def parse_appointment_response(root: ET.Element, appointment_id: str = "") -> AppointmentSummary:
+    appointments = parse_appointments_response(root)
+    if appointment_id:
+        for appointment in appointments:
+            if appointment.id == appointment_id:
+                return appointment
+    if not appointments:
+        message = next((elem for elem in root.iter() if local_name(elem.tag) == "m"), None)
+        if message is not None:
+            appt = _parse_appointment(message)
+            if appt.id:
+                return appt
+    if appointments:
+        return appointments[0]
+    raise ZimbraNotFoundError(
+        "Appointment not found in response",
+        resource_type="appointment",
+        resource_id=appointment_id,
+    )
+
+
+def parse_task_response(root: ET.Element, task_id: str = "") -> Task:
+    for message in root.iter():
+        if local_name(message.tag) != "m":
+            continue
+        message_id = _attr(message, "id") or task_id
+        for inv in message.iter():
+            if local_name(inv.tag) != "inv":
+                continue
+            comp = next((item for item in inv if local_name(item.tag) == "comp"), None)
+            if comp is not None:
+                return _parse_task_from_inv(comp, message_id)
+    for elem in root.iter():
+        if local_name(elem.tag) in {"c", "appt", "task"}:
+            task = Task(
+                id=_attr(elem, "id"),
+                subject=_attr(elem, "name") or _attr(elem, "su"),
+                status=_attr(elem, "status") or _attr(elem, "ptst"),
+                due=epoch_ms_to_datetime(_attr(elem, "due") or _attr(elem, "d")),
+                location=_attr(elem, "loc"),
+                completed=_attr(elem, "status") in {"COMP", "CO"},
+            )
+            if task.id:
+                return task
+    raise ZimbraNotFoundError(
+        "Task not found in response",
+        resource_type="task",
+        resource_id=task_id,
+    )
+
+
+def parse_tasks_search_response(root: ET.Element) -> Tuple[Task, ...]:
+    tasks = []
+    for elem in root.iter():
+        if local_name(elem.tag) not in {"c", "appt", "task"}:
+            continue
+        task_id = _attr(elem, "id")
+        if not task_id:
+            continue
+        tasks.append(
+            Task(
+                id=task_id,
+                subject=_attr(elem, "name") or _attr(elem, "su"),
+                status=_attr(elem, "status") or _attr(elem, "ptst"),
+                due=epoch_ms_to_datetime(_attr(elem, "due") or _attr(elem, "d")),
+                location=_attr(elem, "loc"),
+                completed=_attr(elem, "status") in {"COMP", "CO"},
+            )
+        )
+    return tuple(tasks)
+
+
+def _build_invite_component(
+    *,
+    subject: str,
+    start: datetime,
+    end: datetime,
+    location: str = "",
+    attendees: Sequence[str] = (),
+    due: Optional[datetime] = None,
+    status: str = "CONF",
+    percent_complete: Optional[str] = None,
+) -> ET.Element:
+    comp = ET.Element("comp")
+    comp.set("name", subject)
+    comp.set("status", status)
+    if location:
+        comp.set("loc", location)
+    if due is not None:
+        comp.set("due", datetime_to_epoch_ms(due))
+    else:
+        comp.set("s", datetime_to_epoch_ms(start))
+        comp.set("e", datetime_to_epoch_ms(end))
+    if percent_complete is not None:
+        comp.set("percentComplete", percent_complete)
+    for attendee in attendees:
+        element = ET.SubElement(comp, "at")
+        element.set("a", attendee)
+    return comp
+
+
+def build_create_appointment_request(
+    subject: str,
+    start: datetime,
+    end: datetime,
+    *,
+    location: str = "",
+    attendees: Optional[Sequence[str]] = None,
+    text: str = "",
+    html: str = "",
+    folder_id: Optional[str] = None,
+) -> ET.Element:
+    request = ET.Element(_qname(MAIL_NAMESPACE, "CreateAppointmentRequest"))
+    message = ET.SubElement(request, "m")
+    if folder_id:
+        message.set("l", folder_id)
+    subject_element = ET.SubElement(message, "su")
+    subject_element.text = subject
+    invite = ET.SubElement(message, "inv")
+    comp = _build_invite_component(
+        subject=subject,
+        start=start,
+        end=end,
+        location=location,
+        attendees=(),
+        status="CONF",
+    )
+    invite.append(comp)
+    for attendee in attendees or ():
+        email = attendee.email if hasattr(attendee, "email") else str(attendee)
+        element = ET.SubElement(comp, "at")
+        element.set("a", email)
+    _append_body_parts(message, text=text, html=html)
+    return request
+
+
+def build_get_appt_summaries_request(
+    start: datetime,
+    end: datetime,
+    *,
+    folder_id: Optional[str] = None,
+) -> ET.Element:
+    request = ET.Element(_qname(MAIL_NAMESPACE, "GetApptSummariesRequest"))
+    request.set("s", datetime_to_epoch_ms(start))
+    request.set("e", datetime_to_epoch_ms(end))
+    if folder_id:
+        request.set("l", folder_id)
+    return request
+
+
+def build_get_appointment_request(appointment_id: str) -> ET.Element:
+    request = ET.Element(_qname(MAIL_NAMESPACE, "GetAppointmentRequest"))
+    appointment = ET.SubElement(request, "m")
+    appointment.set("id", appointment_id)
+    return request
+
+
+def build_cancel_appointment_request(appointment_id: str, *, comp: int = 0) -> ET.Element:
+    request = ET.Element(_qname(MAIL_NAMESPACE, "CancelAppointmentRequest"))
+    component = ET.SubElement(request, "comp")
+    component.set("id", appointment_id)
+    component.set("comp", str(comp))
+    return request
+
+
+def build_create_task_request(
+    subject: str,
+    *,
+    due: Optional[datetime] = None,
+    location: str = "",
+    text: str = "",
+) -> ET.Element:
+    request = ET.Element(_qname(MAIL_NAMESPACE, "CreateTaskRequest"))
+    message = ET.SubElement(request, "m")
+    subject_element = ET.SubElement(message, "su")
+    subject_element.text = subject
+    invite = ET.SubElement(message, "inv")
+    start = due or datetime.now().astimezone()
+    invite.append(
+        _build_invite_component(
+            subject=subject,
+            start=start,
+            end=start,
+            location=location,
+            due=due,
+            status="NEED",
+        )
+    )
+    if text:
+        _append_body_parts(message, text=text, html="")
+    return request
+
+
+def build_get_task_request(task_id: str) -> ET.Element:
+    request = ET.Element(_qname(MAIL_NAMESPACE, "GetTaskRequest"))
+    task = ET.SubElement(request, "task")
+    task.set("id", task_id)
+    return request
+
+
+def build_modify_task_request(
+    task_id: str,
+    *,
+    subject: Optional[str] = None,
+    due: Optional[datetime] = None,
+    status: Optional[str] = None,
+    text: Optional[str] = None,
+    percent_complete: Optional[str] = None,
+) -> ET.Element:
+    request = ET.Element(_qname(MAIL_NAMESPACE, "ModifyTaskRequest"))
+    message = ET.SubElement(request, "m")
+    message.set("id", task_id)
+    if subject is not None:
+        subject_element = ET.SubElement(message, "su")
+        subject_element.text = subject
+    invite = ET.SubElement(message, "inv")
+    comp = ET.SubElement(invite, "comp")
+    if subject is not None:
+        comp.set("name", subject)
+    if due is not None:
+        comp.set("due", datetime_to_epoch_ms(due))
+    if status is not None:
+        comp.set("status", status)
+    if percent_complete is not None:
+        comp.set("percentComplete", percent_complete)
+    if text is not None:
+        _append_body_parts(message, text=text, html="")
+    return request
+
+
+def build_search_tasks_request(
+    *,
+    folder_id: Optional[str] = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> ET.Element:
+    request = ET.Element(_qname(MAIL_NAMESPACE, "SearchRequest"))
+    request.set("types", "task")
+    request.set("limit", str(limit))
+    request.set("offset", str(offset))
+    query = "in:tasks"
+    if folder_id:
+        query = f"inid:{folder_id}"
+    query_element = ET.SubElement(request, "query")
+    query_element.text = query
+    return request