mgraphctl 0.1.0__py3-none-any.whl

mgraphctl/commands/__init__.py

@@ -0,0 +1,71 @@
+"""The noun registry. Phase 1 tasks add `commands/<noun>.py`; they never edit this file.
+
+A module that does not exist yet is skipped, so the CLI is usable at every point of the build.
+A module that does exist must expose `app: typer.Typer` (kind "group") or `command: Callable`
+(kind "command").
+"""
+
+import importlib
+import logging
+from dataclasses import dataclass
+from typing import Literal
+
+import typer
+
+log = logging.getLogger("mgraphctl.commands")
+
+
+@dataclass(frozen=True)
+class Noun:
+    name: str
+    module: str
+    help: str
+    kind: Literal["group", "command"] = "group"
+
+
+NOUNS: list[Noun] = [
+    Noun("mail", "mgraphctl.commands.mail", "Outlook mail."),
+    Noun(
+        "mailbox",
+        "mgraphctl.commands.mailbox",
+        "Mailbox settings, automatic replies, focused inbox.",
+    ),
+    Noun(
+        "calendar", "mgraphctl.commands.calendar", "Calendar events, availability, meeting times."
+    ),
+    Noun("people", "mgraphctl.commands.people", "People, contacts and directory users."),
+    Noun("org", "mgraphctl.commands.org", "Manager, direct reports, management chain."),
+    Noun("groups", "mgraphctl.commands.groups", "Microsoft 365 groups."),
+    Noun("teams", "mgraphctl.commands.teams", "Teams and channels."),
+    Noun("chats", "mgraphctl.commands.chats", "Teams chats and direct messages."),
+    Noun("presence", "mgraphctl.commands.presence", "Teams presence."),
+    Noun("meetings", "mgraphctl.commands.meetings", "Online meetings, transcripts, AI insights."),
+    Noun("onedrive", "mgraphctl.commands.onedrive", "OneDrive files."),
+    Noun("sharepoint", "mgraphctl.commands.sharepoint", "SharePoint sites, drives and lists."),
+    Noun("onenote", "mgraphctl.commands.onenote", "OneNote notebooks and pages."),
+    Noun("planner", "mgraphctl.commands.planner", "Planner plans and tasks."),
+    Noun("todo", "mgraphctl.commands.todo", "Microsoft To Do."),
+    Noun(
+        "search",
+        "mgraphctl.commands.search",
+        "Unified search across Microsoft 365.",
+        kind="command",
+    ),
+]
+
+
+def register_all(root: typer.Typer) -> None:
+    """Attach every noun that has a module. Missing modules are a debug line, not an error."""
+    for noun in NOUNS:
+        try:
+            module = importlib.import_module(noun.module)
+        except ModuleNotFoundError as exc:
+            # Only the noun's own module may be missing; a broken import inside it must surface.
+            if exc.name != noun.module:
+                raise
+            log.debug("noun %s not implemented yet", noun.name)
+            continue
+        if noun.kind == "command":
+            root.command(noun.name, help=noun.help)(module.command)
+        else:
+            root.add_typer(module.app, name=noun.name, help=noun.help)

mgraphctl/commands/api.py

@@ -0,0 +1,164 @@
+"""The raw `api` escape hatch (spec §8.17). No scopes are declared; Graph decides."""
+
+import json as jsonlib
+import sys
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from mgraphctl import odata
+from mgraphctl.cli import AllFlag, DryRunFlag, JsonFlag, graph_command
+from mgraphctl.errors import UsageError
+from mgraphctl.http import GraphClient, PlannedRequest
+from mgraphctl.render import DryRunResult, FileResult, TextResult, WriteResult, fmt_size
+
+JSON_CONTENT = "application/json"
+PAGE_CAP = sys.maxsize
+
+
+def _params(query: list[str]) -> dict[str, str]:
+    """`--query k=v` pairs, split on the first `=`."""
+    out: dict[str, str] = dict()
+    for item in query:
+        key, sep, value = item.partition("=")
+        if not sep:
+            raise UsageError("USAGE", f"--query needs k=v, got {item!r}")
+        out[key] = value
+    return out
+
+
+def _headers(header: list[str]) -> dict[str, str]:
+    """`--header k:v` pairs, split on the first `:`."""
+    out: dict[str, str] = dict()
+    for item in header:
+        key, sep, value = item.partition(":")
+        if not sep:
+            raise UsageError("USAGE", f"--header needs k:v, got {item!r}")
+        out[key.strip()] = value.strip()
+    return out
+
+
+def _body(body: str | None) -> Any:
+    """JSON text, or `@FILE` naming a file that holds it."""
+    if body is None:
+        return None
+    text = Path(body[1:]).read_text() if body.startswith("@") else body
+    try:
+        return jsonlib.loads(text)
+    except jsonlib.JSONDecodeError as exc:
+        raise UsageError("USAGE", f"--body is not valid JSON: {exc}") from exc
+
+
+def _write_bytes(data: bytes, output: Path | None) -> FileResult | None:
+    if output is None:
+        sys.stdout.flush()
+        sys.stdout.buffer.write(data)
+        sys.stdout.buffer.flush()
+        return None
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_bytes(data)
+    return FileResult(
+        path=output,
+        bytes=len(data),
+        meta=dict(),
+        message=f"Wrote {fmt_size(len(data))} to {output}",
+    )
+
+
+def _document(obj: Any) -> TextResult:
+    """A JSON body, pretty-printed in text mode and passed through unchanged in JSON mode."""
+    return TextResult(text=jsonlib.dumps(obj, indent=2, ensure_ascii=False), json_obj=obj)
+
+
+@graph_command(scopes=[])
+def api(
+    client: GraphClient,
+    method: Annotated[str, typer.Argument(metavar="METHOD", help="GET, POST, PATCH, PUT, DELETE.")],
+    path: Annotated[
+        str, typer.Argument(metavar="PATH", help="Graph path such as /me, or an absolute URL.")
+    ],
+    query: Annotated[
+        list[str] | None, typer.Option("--query", help="k=v query parameter (repeatable).")
+    ] = None,
+    body: Annotated[
+        str | None, typer.Option("--body", help="JSON request body, or @FILE holding it.")
+    ] = None,
+    header: Annotated[
+        list[str] | None, typer.Option("--header", help="k:v request header (repeatable).")
+    ] = None,
+    beta: Annotated[
+        bool, typer.Option("--beta", help="Send this call to the /beta endpoint.")
+    ] = False,
+    all_: AllFlag = False,
+    raw: Annotated[
+        bool, typer.Option("--raw", help="Treat the response as bytes, not JSON.")
+    ] = False,
+    output: Annotated[
+        Path | None, typer.Option("--output", help="Write the --raw bytes to this file.")
+    ] = None,
+    outlook_tz: Annotated[
+        bool,
+        typer.Option(
+            "--outlook-tz",
+            hidden=True,
+            help="Send Prefer: outlook.timezone for mail/calendar paths.",
+        ),
+    ] = False,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Send one request to Microsoft Graph and print what comes back."""
+    params = _params(query or [])
+    headers = _headers(header or [])
+    payload = _body(body)
+    verb = method.upper()
+    use_beta = True if beta else None
+    if all_ and (raw or output is not None):
+        raise UsageError("USAGE", "--all cannot be combined with --raw or --output")
+    if output is not None and not raw:
+        raise UsageError("USAGE", "--output writes the bytes of a --raw response; add --raw")
+    if dry_run:
+        planned = dict(headers)
+        if payload is not None:
+            planned.setdefault("Content-Type", JSON_CONTENT)
+        url = client.url(odata.with_query(path, params), beta=use_beta)
+        return DryRunResult([PlannedRequest(verb, url, planned, payload)])
+    if all_:
+        page = client.paginate(
+            path,
+            params=params,
+            headers=headers or None,
+            beta=use_beta,
+            outlook_tz=outlook_tz,
+            limit=None,
+            all_=True,
+            cap=PAGE_CAP,
+            page_size=None,
+        )
+        return _document(dict(value=page.items))
+    call = dict(
+        params=params,
+        json=payload,
+        headers=headers or None,
+        beta=use_beta,
+        outlook_tz=outlook_tz,
+    )
+    if raw:
+        return _write_bytes(client.request(verb, path, expect="bytes", **call), output)
+    response = client.request(verb, path, expect="response", **call)
+    content_type = response.headers.get("content-type", "")
+    data = response.read()
+    response.close()
+    if not data:
+        return WriteResult(obj=None, message="OK")
+    if "json" in content_type:
+        return _document(jsonlib.loads(data))
+    text_body = data.decode("utf-8", errors="replace")
+    # A non-JSON body is still the answer: --json emits it as a JSON string, never null.
+    return TextResult(text=text_body, json_obj=text_body)
+
+
+def register(root: typer.Typer) -> None:
+    """Attach `api` to the root app."""
+    root.command("api")(api)