graphplug 0.2.0__py3-none-any.whl

graphplug/_request.py

@@ -0,0 +1,135 @@
+"""Building requests and shaping responses.
+
+Ported from the C# core's `GraphUrlBuilder`, `ResponseHeaderFilter` and `GraphOperation`.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Mapping, Optional
+from urllib.parse import quote, urlencode
+
+from ._errors import GraphError
+
+__all__ = ["build_url", "odata", "segment", "allowlisted", "reject_authorization", "DEFAULT_VERSION"]
+
+BASE_URL = "https://graph.microsoft.com"
+DEFAULT_VERSION = "v1.0"
+SUPPORTED_VERSIONS = (DEFAULT_VERSION, "beta")
+
+#: What tells a whole URL apart from a Graph path: a scheme and ``://`` at the very start.
+#:
+#: Deliberately not ``urlsplit(path).scheme``, which reads "C:\\secrets" as scheme "c". Anchored at
+#: the start because a Graph path may carry ``://`` further in -- a drive search for a URL, say.
+#: The equivalent check in the C# core was the fix for a bug that broke every request on Linux
+#: while passing on Windows.
+_ABSOLUTE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*://")
+
+#: Left alone when an id or a drive path goes into a URL path. Everything else -- ``#``, ``?``,
+#: ``%``, spaces -- is percent-encoded, or it would end the path early.
+_PATH_SAFE = "/:@=+$,!"
+
+#: OData parameters, spelled as Python keywords.
+ODATA_KEYWORDS = ("select", "filter", "top", "skip", "expand", "orderby", "search", "count")
+
+#: Response headers reach the caller through an allowlist, never a denylist: a denylist fails open
+#: on whatever header Microsoft adds tomorrow. Authorization and WWW-Authenticate therefore cannot
+#: escape even by accident.
+_HEADER_ALLOWLIST = (
+    "request-id",
+    "client-request-id",
+    "Date",
+    "Retry-After",
+    "Content-Type",
+    "Location",
+    "ETag",
+)
+
+
+def odata(options: Mapping[str, Any]) -> Dict[str, Any]:
+    """Turn ``select=...`` into ``$select``, leaving anything else a literal parameter."""
+    query: Dict[str, Any] = {}
+    for name, value in options.items():
+        if value is None:
+            continue
+        query[f"${name}" if name in ODATA_KEYWORDS else name] = value
+    return query
+
+
+def build_url(
+    path: Optional[str],
+    version: Optional[str] = None,
+    query: Optional[Mapping[str, Any]] = None,
+) -> str:
+    """Build the request URL.
+
+    An absolute ``path`` is used verbatim and ``version`` and ``query`` are ignored, because the
+    URL already carries them. That is what makes ``@odata.nextLink`` echo-back and pre-authenticated
+    download URLs work with no special case.
+    """
+    if not path or not path.strip():
+        raise GraphError(0, "invalidRequest", "'path' is required")
+
+    if _ABSOLUTE.match(path):
+        if not path.lower().startswith("https://"):
+            raise GraphError(0, "invalidRequest", "an absolute 'path' must use https")
+        return path
+
+    resolved = _resolve_version(version)
+    suffix = path if path.startswith("/") else "/" + path
+    url = f"{BASE_URL}/{resolved}{suffix}"
+
+    if query:
+        # safe="$" keeps $select readable on the wire; Graph accepts either form.
+        encoded = urlencode({k: _literal(v) for k, v in query.items()}, safe="$")
+        url = f"{url}{'&' if '?' in url else '?'}{encoded}"
+    return url
+
+
+def _literal(value: Any) -> str:
+    """OData is case-sensitive about booleans: ``$count=true``, never ``True``."""
+    return str(value).lower() if isinstance(value, bool) else str(value)
+
+
+def segment(value: str) -> str:
+    """Percent-encode an id or drive path for use inside a URL path.
+
+    A guest's user principal name carries ``#EXT#`` and a file may be called ``Q3 #1.xlsx``.
+    Unencoded, the ``#`` starts a fragment and the request silently goes to a different path.
+    """
+    return quote(value, safe=_PATH_SAFE)
+
+
+def _resolve_version(version: Optional[str]) -> str:
+    if not version:
+        return DEFAULT_VERSION
+    if version not in SUPPORTED_VERSIONS:
+        raise GraphError(
+            0, "invalidRequest", f"'version' must be one of {', '.join(SUPPORTED_VERSIONS)}"
+        )
+    return version
+
+
+def allowlisted(headers: Mapping[str, str]) -> Dict[str, str]:
+    """Only the named headers reach the caller."""
+    lowered = {name.lower(): value for name, value in headers.items()}
+    return {name: lowered[name.lower()] for name in _HEADER_ALLOWLIST if name.lower() in lowered}
+
+
+def reject_authorization(headers: Optional[Mapping[str, str]]) -> Dict[str, str]:
+    """Forward caller headers as supplied, except Authorization.
+
+    This package owns authentication; a caller-supplied bearer token would silently bypass the
+    credential the client was built with.
+    """
+    if not headers:
+        return {}
+
+    for name in headers:
+        if name.lower() == "authorization":
+            raise GraphError(
+                0,
+                "invalidRequest",
+                "'Authorization' may not be supplied; the client owns authentication",
+            )
+    return dict(headers)

graphplug/_resources/__init__.py

@@ -0,0 +1,10 @@
+"""Resource layer: the plug-and-play surface over the generic transport."""
+
+from .base import GraphResource
+from .calendar import Calendar
+from .files import Files
+from .mail import Mail
+from .teams import Teams
+from .users import Users
+
+__all__ = ["GraphResource", "Calendar", "Files", "Mail", "Teams", "Users"]

graphplug/_resources/base.py

@@ -0,0 +1,70 @@
+"""Shared behaviour for any Graph collection.
+
+Every Graph collection supports the same operations over a different path, which is a real
+variation point rather than a speculative one: a base class plus a thin subclass per resource
+means adding a resource later is one class and nothing else moves.
+"""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, List, Optional, Sequence, Tuple
+
+from .._request import segment
+
+__all__ = ["GraphResource"]
+
+
+class GraphResource:
+    """Base for a Graph collection. Subclasses set ``path`` and ``scopes``."""
+
+    #: The collection's path, e.g. ``/me/messages``.
+    path: str = ""
+
+    #: The delegated permissions this resource needs, for error messages and scope assembly.
+    scopes: Tuple[str, ...] = ()
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    # ── the shared five ──────────────────────────────────────────────────────
+
+    def list(self, **options: Any) -> AsyncIterator[Dict[str, Any]]:
+        """Every item, one page at a time. Returns an async generator."""
+        return self._client.paged(self.path, **options)
+
+    async def get(self, item_id: str, **options: Any) -> Dict[str, Any]:
+        return await self._client.get(f"{self.path}/{segment(item_id)}", **options)
+
+    async def create(self, body: Dict[str, Any], **options: Any) -> Dict[str, Any]:
+        return await self._client.post(self.path, body=body, **options)
+
+    async def update(self, item_id: str, body: Dict[str, Any], **options: Any) -> Dict[str, Any]:
+        return await self._client.patch(f"{self.path}/{segment(item_id)}", body=body, **options)
+
+    async def delete(self, item_id: str, **options: Any) -> None:
+        await self._client.delete(f"{self.path}/{segment(item_id)}", **options)
+
+    # ── the fast path ────────────────────────────────────────────────────────
+
+    async def get_many(
+        self, item_ids: Sequence[str], select: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """Fetch many items in as few round-trips as Graph allows.
+
+        Chunked into batches of twenty and dispatched concurrently, so two hundred lookups cost ten
+        round-trips rather than two hundred. Results come back in the order the ids were given.
+        """
+        query = f"?$select={select}" if select else ""
+        requests = [{"method": "GET", "url": f"{self.path}/{segment(i)}{query}"} for i in item_ids]
+        return await self._client.batch(requests)
+
+    # ── helpers for subclasses ───────────────────────────────────────────────
+
+    async def _action(self, item_id: str, action: str, body: Any = None) -> Any:
+        """POST to an action on one item, e.g. ``/me/messages/{id}/reply``."""
+        return await self._client.post(f"{self.path}/{segment(item_id)}/{action}", body=body)
+
+    async def _collection_action(self, action: str, body: Any = None) -> Any:
+        """POST to an action on the collection's owner, e.g. ``/me/sendMail``."""
+        owner = self.path.rsplit("/", 1)[0] or "/me"
+        return await self._client.post(f"{owner}/{action}", body=body)

graphplug/_resources/calendar.py

@@ -0,0 +1,194 @@
+"""Calendar and meetings.
+
+As with mail, the value here is the payload. A Teams meeting needs ``isOnlineMeeting`` paired with
+``onlineMeetingProvider``; attendees are objects carrying a ``type``; and every time is a
+``dateTime``/``timeZone`` pair rather than an ISO string. None of that is guessable from the call
+site, so it lives here once.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, AsyncIterator, Dict, Iterable, List, Optional, Sequence, Union
+
+from .._errors import GraphError
+from .._request import build_url, odata
+from .._scopes import Scopes
+from .base import GraphResource
+
+__all__ = ["Calendar"]
+
+Attendees = Union[str, Sequence[str], None]
+
+_RESPONSES = {"accept", "decline", "tentativelyAccept"}
+
+
+def _graph_time(moment: datetime, tz: str) -> Dict[str, str]:
+    """Graph wants a naive local time plus a named zone, not an offset."""
+    if moment.tzinfo is not None:
+        moment = moment.astimezone(timezone.utc).replace(tzinfo=None)
+        tz = "UTC"
+    return {"dateTime": moment.isoformat(timespec="seconds"), "timeZone": tz}
+
+
+def _attendees(value: Attendees, kind: str = "required") -> List[Dict[str, Any]]:
+    if not value:
+        return []
+    addresses = [value] if isinstance(value, str) else list(value)
+    return [
+        {"emailAddress": {"address": address}, "type": kind}
+        for address in addresses
+    ]
+
+
+class Calendar(GraphResource):
+    """Events on the signed-in user's calendar."""
+
+    path = "/me/events"
+    scopes = Scopes.CALENDARS_READ_WRITE
+
+    # ── scheduling ───────────────────────────────────────────────────────────
+
+    def compose(
+        self,
+        subject: str,
+        start: datetime,
+        end: datetime,
+        attendees: Attendees = None,
+        optional_attendees: Attendees = None,
+        online: bool = False,
+        location: Optional[str] = None,
+        body: str = "",
+        html: bool = False,
+        timezone_name: str = "UTC",
+        reminder_minutes: Optional[int] = None,
+        all_day: bool = False,
+    ) -> Dict[str, Any]:
+        """Build the event payload without creating it."""
+        if end <= start:
+            raise GraphError(0, "invalidRequest", "'end' must be after 'start'")
+
+        event: Dict[str, Any] = {
+            "subject": subject,
+            "start": _graph_time(start, timezone_name),
+            "end": _graph_time(end, timezone_name),
+        }
+
+        people = _attendees(attendees) + _attendees(optional_attendees, "optional")
+        if people:
+            event["attendees"] = people
+        if body:
+            event["body"] = {"contentType": "HTML" if html else "Text", "content": body}
+        if location:
+            event["location"] = {"displayName": location}
+        if reminder_minutes is not None:
+            event["reminderMinutesBeforeStart"] = reminder_minutes
+            event["isReminderOn"] = True
+        if all_day:
+            event["isAllDay"] = True
+
+        if online:
+            # Both fields are needed; isOnlineMeeting alone produces an event with no join link.
+            event["isOnlineMeeting"] = True
+            event["onlineMeetingProvider"] = "teamsForBusiness"
+
+        return event
+
+    async def schedule(self, **fields: Any) -> Dict[str, Any]:
+        """Create an event. Takes everything ``compose`` takes.
+
+        With ``online=True`` the response carries ``onlineMeeting.joinUrl``.
+        """
+        return await self.create(self.compose(**fields))
+
+    async def schedule_many(self, events: Sequence[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Create many events in as few round-trips as Graph allows."""
+        requests = [{
+            "method": "POST",
+            "url": self.path,
+            "headers": {"Content-Type": "application/json"},
+            "body": self.compose(**fields),
+        } for fields in events]
+        return await self._client.batch(requests)
+
+    # ── reading ──────────────────────────────────────────────────────────────
+
+    def upcoming(
+        self,
+        days: int = 7,
+        select: str = "id,subject,start,end,location,onlineMeeting,organizer,attendees",
+        top: int = 50,
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Events in the next ``days``, soonest first.
+
+        Uses calendarView, which is the endpoint that expands recurring series -- listing /events
+        returns the series master instead of its occurrences.
+        """
+        now = datetime.now(timezone.utc)
+        query = odata({
+            "select": select,
+            "top": top,
+            "orderby": "start/dateTime",
+        })
+        query["startDateTime"] = now.isoformat(timespec="seconds").replace("+00:00", "Z")
+        query["endDateTime"] = (now + timedelta(days=days)).isoformat(
+            timespec="seconds").replace("+00:00", "Z")
+
+        return self._client.paged(build_url("/me/calendarView", None, query))
+
+    # ── responding ───────────────────────────────────────────────────────────
+
+    async def respond(
+        self, event_id: str, response: str, comment: str = "", send_response: bool = True
+    ) -> None:
+        """Accept, decline or tentatively accept an invitation."""
+        if response not in _RESPONSES:
+            raise GraphError(
+                0, "invalidRequest", f"'response' must be one of {', '.join(sorted(_RESPONSES))}"
+            )
+        await self._action(event_id, response, {
+            "comment": comment,
+            "sendResponse": send_response,
+        })
+
+    async def cancel(self, event_id: str, comment: str = "") -> None:
+        """Cancel a meeting you organise, notifying the attendees."""
+        await self._action(event_id, "cancel", {"comment": comment})
+
+    # ── finding a slot ───────────────────────────────────────────────────────
+
+    async def find_times(
+        self,
+        attendees: Attendees,
+        duration_minutes: int = 30,
+        within_days: int = 5,
+        minimum_attendance_percent: int = 100,
+    ) -> List[Dict[str, Any]]:
+        """Ask Graph for slots that suit everyone. Returns the suggestions, best first."""
+        now = datetime.now(timezone.utc)
+        suggestions = await self._collection_action("findMeetingTimes", {
+            "attendees": _attendees(attendees),
+            "timeConstraint": {
+                "activityDomain": "work",
+                "timeSlots": [{
+                    "start": _graph_time(now, "UTC"),
+                    "end": _graph_time(now + timedelta(days=within_days), "UTC"),
+                }],
+            },
+            "meetingDuration": f"PT{duration_minutes}M",
+            "minimumAttendeePercentage": minimum_attendance_percent,
+            "returnSuggestionReasons": True,
+        })
+        return (suggestions or {}).get("meetingTimeSuggestions", [])
+
+    async def free_busy(
+        self, people: Iterable[str], start: datetime, end: datetime, interval_minutes: int = 30
+    ) -> List[Dict[str, Any]]:
+        """Each person's availability over a window."""
+        schedules = await self._collection_action("calendar/getSchedule", {
+            "schedules": list(people),
+            "startTime": _graph_time(start, "UTC"),
+            "endTime": _graph_time(end, "UTC"),
+            "availabilityViewInterval": interval_minutes,
+        })
+        return (schedules or {}).get("value", [])

graphplug/_resources/files.py

@@ -0,0 +1,149 @@
+"""OneDrive and SharePoint files.
+
+The thing that makes Graph's file API hard to write against is addressing. The same item is
+``/me/drive/items/01ABC...`` by id and ``/me/drive/root:/reports/q3.xlsx:`` by path -- with a colon
+opening the path segment and *another* colon closing it before whatever comes next. Forgetting the
+trailing colon gives a 400 that says nothing about colons.
+
+``_address`` decides between the two on one rule: a leading slash means a path, anything else is an
+id. Every method here takes either.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, AsyncIterator, Dict, Optional, Union
+
+from .._errors import GraphError
+from .._request import segment
+from .._scopes import Scopes
+from .base import GraphResource
+
+__all__ = ["Files"]
+
+DRIVE = "/me/drive"
+
+DEFAULT_FIELDS = "id,name,size,webUrl,lastModifiedDateTime,file,folder"
+
+#: Graph's own names for what happens when a new folder's name is taken.
+_CONFLICT = ("rename", "replace", "fail")
+
+#: Who a sharing link works for. "anonymous" is frequently disabled by tenant policy.
+_SCOPES = ("anonymous", "organization", "users")
+
+_LINK_KINDS = ("view", "edit", "embed")
+
+
+class Files(GraphResource):
+    """Items in the signed-in user's drive.
+
+    Every method takes either a drive path (``"/reports/q3.xlsx"``, leading slash) or an item id.
+    """
+
+    path = f"{DRIVE}/items"
+    scopes = Scopes.FILES_READ_WRITE
+
+    @staticmethod
+    def _address(item: str) -> str:
+        """The endpoint for one item, by path or by id."""
+        if not item or not item.strip():
+            raise GraphError(0, "invalidRequest", "'item' is required")
+        if not item.startswith("/"):
+            return f"{DRIVE}/items/{segment(item)}"
+        if item == "/":
+            return f"{DRIVE}/root"
+        # The closing colon is what separates the path from whatever follows it.
+        return f"{DRIVE}/root:{segment(item.rstrip('/'))}:"
+
+    # ── moving bytes ─────────────────────────────────────────────────────────
+
+    async def upload(self, source: Union[str, Path], to: Optional[str] = None) -> Dict[str, Any]:
+        """Send a local file to the drive, replacing whatever is at the destination.
+
+        ``to`` is the destination drive path; omit it and the file keeps its own name at the root.
+        Files above 4 MiB switch to a resumable upload session on their own -- the caller never
+        picks a strategy, and the path is the same either way.
+        """
+        local = Path(source)
+        if not local.is_file():
+            raise GraphError(0, "invalidRequest", f"'{source}' does not exist")
+
+        destination = to or f"/{local.name}"
+        if not destination.startswith("/"):
+            destination = "/" + destination
+
+        return await self._client.upload(f"{self._address(destination)}/content", str(local))
+
+    async def download(self, item: str, dest_path: Union[str, Path]) -> Dict[str, Any]:
+        """Stream a file to disk. The destination directory must already exist.
+
+        Graph answers the content endpoint with a redirect to a short-lived, pre-authenticated URL
+        on another host. The transport follows it and deliberately does not attach the bearer token
+        to that second hop.
+        """
+        return await self._client.download(f"{self._address(item)}/content", str(dest_path))
+
+    # ── looking around ───────────────────────────────────────────────────────
+
+    def folder(
+        self, path: str = "/", select: str = DEFAULT_FIELDS, top: int = 200
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Everything directly inside a folder. Defaults to the drive root."""
+        return self._client.paged(f"{self._address(path)}/children", select=select, top=top)
+
+    def search(self, query: str, select: str = DEFAULT_FIELDS) -> AsyncIterator[Dict[str, Any]]:
+        """Search the whole drive by name and content."""
+        if not query:
+            raise GraphError(0, "invalidRequest", "'query' is required")
+        # Graph spells this one as a function on the path, not as $search.
+        escaped = segment(query.replace("'", "''")).replace("/", "%2F")
+        return self._client.paged(f"{DRIVE}/root/search(q='{escaped}')", select=select)
+
+    async def metadata(self, item: str, select: str = DEFAULT_FIELDS) -> Dict[str, Any]:
+        """One item's properties, without its bytes."""
+        return await self._client.get(self._address(item), select=select)
+
+    # ── changing things ──────────────────────────────────────────────────────
+
+    async def make_folder(self, path: str, conflict: str = "fail") -> Dict[str, Any]:
+        """Create a folder. ``path`` is the full drive path of the folder to create."""
+        if not path.startswith("/"):
+            path = "/" + path
+        parent, _, name = path.rstrip("/").rpartition("/")
+        if not name:
+            raise GraphError(0, "invalidRequest", "'path' must name the folder to create")
+
+        if conflict not in _CONFLICT:
+            raise GraphError(
+                0, "invalidRequest", f"'conflict' must be one of {', '.join(_CONFLICT)}"
+            )
+
+        return await self._client.post(f"{self._address(parent or '/')}/children", body={
+            "name": name,
+            "folder": {},
+            "@microsoft.graph.conflictBehavior": conflict,
+        })
+
+    async def remove(self, item: str) -> None:
+        """Move an item to the recycle bin."""
+        await self._client.delete(self._address(item))
+
+    async def share_link(
+        self, item: str, kind: str = "view", scope: str = "organization"
+    ) -> str:
+        """Create a sharing link and return just the URL.
+
+        ``scope="anonymous"`` produces a link anyone can open, and is frequently disabled by tenant
+        policy -- that arrives as an ``accessDenied`` error rather than a working link.
+        """
+        if kind not in _LINK_KINDS:
+            raise GraphError(
+                0, "invalidRequest", f"'kind' must be one of {', '.join(_LINK_KINDS)}"
+            )
+        if scope not in _SCOPES:
+            raise GraphError(0, "invalidRequest", f"'scope' must be one of {', '.join(_SCOPES)}")
+
+        created = await self._client.post(
+            f"{self._address(item)}/createLink", body={"type": kind, "scope": scope}
+        )
+        return ((created or {}).get("link") or {}).get("webUrl", "")