wptui 0.1.1__py3-none-any.whl

wptui/__init__.py

@@ -0,0 +1,3 @@
+"""wp-tui: a terminal UI for editing WordPress posts."""
+
+__version__ = "0.1.0"

wptui/__main__.py

@@ -0,0 +1,13 @@
+"""Console entry point: ``python -m wptui`` / ``wptui``."""
+
+from __future__ import annotations
+
+from wptui.app import WPTuiApp
+
+
+def main() -> None:
+    WPTuiApp().run()
+
+
+if __name__ == "__main__":
+    main()

wptui/api/__init__.py

@@ -0,0 +1,25 @@
+"""WordPress REST API client layer."""
+
+from wptui.api.client import WordPressClient
+from wptui.api.dto import MediaItem, PostDetail, PostSettings, PostSummary, Term
+from wptui.api.errors import (
+    ApiError,
+    AuthError,
+    ConflictError,
+    NetworkError,
+    NotFoundError,
+)
+
+__all__ = [
+    "WordPressClient",
+    "PostSummary",
+    "PostDetail",
+    "PostSettings",
+    "Term",
+    "MediaItem",
+    "ApiError",
+    "AuthError",
+    "ConflictError",
+    "NetworkError",
+    "NotFoundError",
+]

wptui/api/client.py

@@ -0,0 +1,411 @@
+"""Async WordPress REST API client (self-hosted, Application Passwords)."""
+
+from __future__ import annotations
+
+import mimetypes
+from collections.abc import Callable
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from wptui.api.dto import MediaItem, PostDetail, PostSummary, PostSettings, Term
+from wptui.api.errors import (
+    AuthError,
+    ConflictError,
+    NetworkError,
+    NotFoundError,
+)
+from wptui.config import SiteProfile
+
+# Fields fetched for an editable post/page (context=edit gives the raw variants).
+_POST_FIELDS = (
+    "id,title,content,status,modified_gmt,link,type,slug,excerpt,date,"
+    "password,categories,tags,featured_media,parent,menu_order,template"
+)
+_TYPE_PATH = {"post": "posts", "page": "pages"}
+
+
+def _type_path(post_type: str) -> str:
+    """REST collection segment for a post type (``post`` -> ``posts``)."""
+    return _TYPE_PATH.get(post_type, "posts")
+
+
+_IMAGE_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+}
+
+
+def _guess_mime(filename: str) -> str:
+    ext = Path(filename).suffix.lower()
+    if ext in _IMAGE_MIME:
+        return _IMAGE_MIME[ext]
+    guessed, _ = mimetypes.guess_type(filename)
+    return guessed or "application/octet-stream"
+
+
+class WordPressClient:
+    """Thin async wrapper over ``/wp-json/wp/v2/`` using HTTP Basic auth.
+
+    Use as an async context manager so the underlying httpx client is closed::
+
+        async with WordPressClient(profile, app_password) as wp:
+            posts = await wp.list_posts()
+    """
+
+    def __init__(
+        self,
+        profile: SiteProfile,
+        app_password: str,
+        *,
+        timeout: float = 20.0,
+    ) -> None:
+        self._profile = profile
+        # WordPress Application Passwords are shown with spaces for readability but
+        # are validated with them stripped.
+        self._client = httpx.AsyncClient(
+            base_url=profile.api_root,
+            auth=(profile.username, app_password.replace(" ", "")),
+            timeout=timeout,
+            headers={"Accept": "application/json"},
+            follow_redirects=True,
+        )
+
+    async def __aenter__(self) -> "WordPressClient":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    # -- requests -----------------------------------------------------------
+
+    async def _send(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Send a request, mapping transport failures to :class:`NetworkError` but NOT
+        raising for an HTTP error status — the caller inspects the response itself. Used by
+        :meth:`create_term` to read a ``term_exists`` 400 that carries the existing term id.
+        """
+        try:
+            return await self._client.request(method, path, **kwargs)
+        except httpx.HTTPError as err:  # connect/timeout/TLS/etc.
+            raise NetworkError(str(err)) from err
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        response = await self._send(method, path, **kwargs)
+        _raise_for_status(response)
+        return response
+
+    @staticmethod
+    def _json(response: httpx.Response) -> Any:
+        """Decode a JSON body, mapping a non-JSON 2xx to :class:`NetworkError`.
+
+        A captive portal, security plugin, or reverse-proxy page can return HTTP 200
+        with an HTML body; without this guard the raw ``JSONDecodeError`` would escape
+        the async worker and crash the whole TUI.
+        """
+        try:
+            return response.json()
+        except ValueError as err:
+            raise NetworkError(
+                "The server returned a non-JSON response. Is this a WordPress REST API "
+                "endpoint, and is the site reachable without a login/proxy page?"
+            ) from err
+
+    async def verify(self) -> dict[str, Any]:
+        """Confirm credentials by fetching the authenticated user.
+
+        Returns the ``/users/me`` payload. Raises :class:`AuthError` on 401/403.
+        """
+        response = await self._request("GET", "/users/me", params={"context": "edit"})
+        data = self._json(response)
+        if not isinstance(data, dict):
+            raise NetworkError("Unexpected response shape from /users/me.")
+        return data
+
+    async def list_posts(
+        self,
+        *,
+        status: str = "any",
+        search: str | None = None,
+        page: int = 1,
+        per_page: int = 50,
+    ) -> list[PostSummary]:
+        params: dict[str, Any] = {
+            "context": "edit",
+            "status": status,
+            "page": page,
+            "per_page": per_page,
+            "orderby": "modified",
+            "order": "desc",
+            "_fields": "id,title,status,modified_gmt,link,type",
+        }
+        if search:
+            params["search"] = search
+        response = await self._request("GET", "/posts", params=params)
+        return _parse_list(self._json(response), PostSummary.from_json, "posts")
+
+    async def get_post(self, post_id: int, post_type: str = "post") -> PostDetail:
+        """Fetch one post/page with raw, editable content + settings (``context=edit``)."""
+        params = {"context": "edit", "_fields": _POST_FIELDS}
+        path = _type_path(post_type)
+        response = await self._request("GET", f"/{path}/{post_id}", params=params)
+        return _post_detail(self._json(response))
+
+    async def create_post(
+        self,
+        post_type: str,
+        *,
+        title_raw: str = "",
+        content_raw: str = "",
+        settings: PostSettings | None = None,
+    ) -> PostDetail:
+        """Create a new post/page and return it. No conflict pre-check (nothing exists)."""
+        payload: dict[str, Any] = {"title": title_raw, "content": content_raw}
+        if settings is not None:
+            payload.update(settings.to_payload())
+        payload.setdefault("status", "draft")
+        params = {"context": "edit", "_fields": _POST_FIELDS}
+        path = _type_path(post_type)
+        response = await self._request("POST", f"/{path}", params=params, json=payload)
+        return _post_detail(self._json(response))
+
+    async def update_post(
+        self,
+        post_id: int,
+        *,
+        content_raw: str | None = None,
+        title_raw: str | None = None,
+        settings: PostSettings | None = None,
+        expected_modified_gmt: str | None = None,
+    ) -> PostDetail:
+        """Update a post/page's content, title, and/or settings.
+
+        If ``expected_modified_gmt`` is given, re-check the server's current value
+        first and raise :class:`ConflictError` if it changed (app-level lost-update
+        guard — WordPress posts don't expose strong ETags).
+        """
+        post_type = settings.post_type if settings is not None else "post"
+        if expected_modified_gmt is not None:
+            current = await self.get_post(post_id, post_type)
+            if current.modified_gmt != expected_modified_gmt:
+                raise ConflictError(
+                    "The post was modified on the server since you opened it.",
+                    server_modified_gmt=current.modified_gmt,
+                )
+
+        payload: dict[str, Any] = {}
+        if content_raw is not None:
+            payload["content"] = content_raw
+        if title_raw is not None:
+            payload["title"] = title_raw
+        if settings is not None:
+            payload.update(settings.to_payload())
+
+        params = {"context": "edit", "_fields": _POST_FIELDS}
+        path = _type_path(post_type)
+        response = await self._request(
+            "POST", f"/{path}/{post_id}", params=params, json=payload
+        )
+        return _post_detail(self._json(response))
+
+    # -- media --------------------------------------------------------------
+
+    async def upload_media(
+        self,
+        file_path: str,
+        *,
+        title: str = "",
+        alt: str = "",
+        caption: str = "",
+        description: str = "",
+        timeout: float = 120.0,
+    ) -> MediaItem:
+        """Upload a local file to the media library in one multipart request.
+
+        Uses an extended timeout since media POSTs can be large. Raises
+        :class:`NetworkError` if the file can't be read or the server rejects it.
+        """
+        path = Path(file_path)
+        try:
+            data = path.read_bytes()
+        except OSError as err:
+            raise NetworkError(f"Cannot read file '{file_path}': {err}") from err
+        files = {"file": (path.name, data, _guess_mime(path.name))}
+        form: dict[str, str] = {}
+        if title:
+            form["title"] = title
+        if alt:
+            form["alt_text"] = alt
+        if caption:
+            form["caption"] = caption
+        if description:
+            form["description"] = description
+        response = await self._request(
+            "POST", "/media", files=files, data=form, timeout=timeout
+        )
+        return _media_item(self._json(response))
+
+    async def get_media(self, media_id: int) -> MediaItem:
+        """Fetch one media item (used to resolve a featured image for display)."""
+        params = {"context": "edit", "_fields": "id,source_url,alt_text,caption,title,mime_type"}
+        response = await self._request("GET", f"/media/{media_id}", params=params)
+        return _media_item(self._json(response))
+
+    async def list_media(
+        self, search: str | None = None, *, per_page: int = 30
+    ) -> list[MediaItem]:
+        """List recent library images (newest first), optionally filtered by ``search``."""
+        params: dict[str, Any] = {
+            "context": "edit",
+            "media_type": "image",
+            "orderby": "date",
+            "order": "desc",
+            "per_page": per_page,
+            "_fields": "id,source_url,alt_text,caption,title,mime_type",
+        }
+        if search:
+            params["search"] = search
+        response = await self._request("GET", "/media", params=params)
+        return _parse_list(self._json(response), MediaItem.from_json, "media items")
+
+    # -- taxonomy terms -----------------------------------------------------
+
+    async def list_terms(
+        self, taxonomy: str, search: str | None = None, *, per_page: int = 50
+    ) -> list[Term]:
+        """List terms for a taxonomy REST route (``categories`` or ``tags``)."""
+        params: dict[str, Any] = {
+            "context": "edit",
+            "per_page": per_page,
+            "_fields": "id,name,taxonomy",
+            "orderby": "count",
+            "order": "desc",
+        }
+        if search:
+            params["search"] = search
+        response = await self._request("GET", f"/{taxonomy}", params=params)
+        return _parse_list(self._json(response), Term.from_json, "terms")
+
+    async def create_term(self, taxonomy: str, name: str) -> Term:
+        """Create a term, or return the existing one when the name already exists.
+
+        The name is lowercased first so casing-only variants ("Apple" vs "apple") collapse to
+        a single term. WordPress enforces term uniqueness by slug, so a duplicate name comes
+        back as HTTP 400 ``term_exists`` carrying the existing ``term_id``; we resolve and
+        return that term instead of raising, so an inline "add" of a name that already exists
+        lands on the term the user meant rather than dead-ending on an error.
+        """
+        name = name.strip().lower()
+        params = {"context": "edit", "_fields": "id,name,taxonomy"}
+        response = await self._send(
+            "POST", f"/{taxonomy}", params=params, json={"name": name}
+        )
+        if response.status_code == 400:
+            term_id = _term_exists_id(response)
+            if term_id is not None:
+                return await self._get_term(taxonomy, term_id)
+        _raise_for_status(response)
+        data = self._json(response)
+        if not isinstance(data, dict) or "id" not in data:
+            raise NetworkError("Unexpected response creating a term.")
+        return Term.from_json(data)
+
+    async def _get_term(self, taxonomy: str, term_id: int) -> Term:
+        """Fetch one term by id (resolves a ``term_exists`` collision to a real Term)."""
+        params = {"context": "edit", "_fields": "id,name,taxonomy"}
+        response = await self._request("GET", f"/{taxonomy}/{term_id}", params=params)
+        data = self._json(response)
+        if not isinstance(data, dict) or "id" not in data:
+            raise NetworkError("Unexpected response fetching a term.")
+        return Term.from_json(data)
+
+
+def _parse_list(
+    data: Any, from_json: Callable[[dict[str, Any]], Any], label: str
+) -> list[Any]:
+    """Coerce a JSON list body into DTOs, rejecting a non-list shape as a NetworkError.
+
+    Shared by ``list_posts``/``list_media``/``list_terms`` so the list-shape guard and the
+    skip-non-dict-entries rule stay identical across all three collection reads.
+    """
+    if not isinstance(data, list):
+        raise NetworkError(f"Expected a list of {label} from the server.")
+    return [from_json(item) for item in data if isinstance(item, dict)]
+
+
+def _post_detail(data: Any) -> PostDetail:
+    """Build a PostDetail, rejecting an unexpected body shape as a NetworkError."""
+    if not isinstance(data, dict) or "id" not in data:
+        raise NetworkError("Unexpected response shape for a post.")
+    return PostDetail.from_json(data)
+
+
+def _media_item(data: Any) -> MediaItem:
+    """Build a MediaItem, rejecting an unexpected body shape as a NetworkError."""
+    if not isinstance(data, dict) or "id" not in data:
+        raise NetworkError("Unexpected response shape for a media item.")
+    return MediaItem.from_json(data)
+
+
+def _term_exists_id(response: httpx.Response) -> int | None:
+    """Return the existing term id from a WordPress ``term_exists`` 400 body, else None.
+
+    A duplicate-name POST returns ``{"code": "term_exists", "data": {"term_id": N}}``. WP has
+    historically typed ``term_id`` as either an int or a numeric string, so accept both; a
+    bool (an int subclass) is rejected so a stray ``true`` can't masquerade as id 1.
+    """
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    if not isinstance(body, dict) or body.get("code") != "term_exists":
+        return None
+    data = body.get("data")
+    if not isinstance(data, dict):
+        return None
+    term_id = data.get("term_id")
+    if isinstance(term_id, bool):
+        return None
+    if isinstance(term_id, int):
+        return term_id
+    if isinstance(term_id, str) and term_id.isdigit():
+        return int(term_id)
+    return None
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    code = response.status_code
+    detail = _error_detail(response)
+    if code in (401, 403):
+        raise AuthError(detail or f"Authentication failed (HTTP {code}).")
+    if code == 404:
+        raise NotFoundError(detail or "Not found (HTTP 404).")
+    raise NetworkError(detail or f"Request failed (HTTP {code}).")
+
+
+def _error_detail(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+    except ValueError:
+        return ""
+    if isinstance(body, dict):
+        return str(body.get("message", "")) or ""
+    return ""

wptui/api/dto.py

@@ -0,0 +1,191 @@
+"""Data-transfer objects mirroring the raw REST API shapes we consume."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class PostSummary:
+    """A row in the post list."""
+
+    id: int
+    title: str
+    status: str
+    modified_gmt: str
+    link: str
+    post_type: str = "post"
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "PostSummary":
+        return cls(
+            id=data["id"],
+            title=_rendered(data.get("title")) or "(no title)",
+            status=data.get("status", ""),
+            modified_gmt=data.get("modified_gmt", ""),
+            link=data.get("link", ""),
+            post_type=data.get("type", "post"),
+        )
+
+
+@dataclass(frozen=True)
+class PostDetail:
+    """A single post opened for editing, carrying raw content and editable settings."""
+
+    id: int
+    title_raw: str
+    content_raw: str
+    status: str
+    modified_gmt: str
+    link: str
+    post_type: str = "post"
+    slug: str = ""
+    excerpt_raw: str = ""
+    date: str = ""
+    password: str = ""
+    categories: tuple[int, ...] = ()
+    tags: tuple[int, ...] = ()
+    featured_media: int = 0
+    parent: int = 0
+    menu_order: int = 0
+    template: str = ""
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "PostDetail":
+        return cls(
+            id=data["id"],
+            title_raw=_raw(data.get("title")),
+            content_raw=_raw(data.get("content")),
+            status=data.get("status", ""),
+            modified_gmt=data.get("modified_gmt", ""),
+            link=data.get("link", ""),
+            post_type=data.get("type", "post"),
+            slug=data.get("slug", ""),
+            excerpt_raw=_raw(data.get("excerpt")),
+            date=data.get("date", ""),
+            password=data.get("password", ""),
+            categories=tuple(data.get("categories", []) or []),
+            tags=tuple(data.get("tags", []) or []),
+            featured_media=data.get("featured_media", 0) or 0,
+            parent=data.get("parent", 0) or 0,
+            menu_order=data.get("menu_order", 0) or 0,
+            template=data.get("template", ""),
+        )
+
+
+@dataclass
+class PostSettings:
+    """The editor's in-memory, editable settings for one post/page.
+
+    Seeded from a :class:`PostDetail` on load (so untouched fields round-trip), mutated by
+    the settings screen, and serialized to a REST payload merged into the save request.
+    ``to_payload`` emits only the keys valid for its ``post_type`` (categories/tags for
+    posts; parent/menu_order/template for pages).
+    """
+
+    post_type: str = "post"
+    status: str = "draft"
+    slug: str = ""
+    excerpt_raw: str = ""
+    date: str = ""
+    password: str = ""
+    categories: list[int] = field(default_factory=list)
+    tags: list[int] = field(default_factory=list)
+    featured_media: int = 0
+    parent: int = 0
+    menu_order: int = 0
+    template: str = ""
+
+    @classmethod
+    def from_detail(cls, detail: PostDetail) -> "PostSettings":
+        return cls(
+            post_type=detail.post_type or "post",
+            status=detail.status or "draft",
+            slug=detail.slug,
+            excerpt_raw=detail.excerpt_raw,
+            date=detail.date,
+            password=detail.password,
+            categories=list(detail.categories),
+            tags=list(detail.tags),
+            featured_media=detail.featured_media,
+            parent=detail.parent,
+            menu_order=detail.menu_order,
+            template=detail.template,
+        )
+
+    def to_payload(self) -> dict[str, Any]:
+        # Every field here is seeded from the loaded post, so sending it back is
+        # idempotent — and sending it even when empty is what lets the user *clear* it
+        # (notably removing a password / excerpt / slug). ``date`` is the exception: it's
+        # omitted when empty so a new post defaults to "now" rather than being rejected.
+        payload: dict[str, Any] = {
+            "status": self.status,
+            "slug": self.slug,
+            "excerpt": self.excerpt_raw,
+            "password": self.password,
+            "featured_media": self.featured_media,
+        }
+        if self.date:
+            payload["date"] = self.date
+        if self.post_type == "page":
+            payload["parent"] = self.parent
+            payload["menu_order"] = self.menu_order
+            payload["template"] = self.template
+        else:
+            payload["categories"] = list(self.categories)
+            payload["tags"] = list(self.tags)
+        return payload
+
+
+@dataclass(frozen=True)
+class Term:
+    """A taxonomy term (category or tag)."""
+
+    id: int
+    name: str
+    taxonomy: str
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Term":
+        return cls(
+            id=data["id"],
+            name=data.get("name", ""),
+            taxonomy=data.get("taxonomy", ""),
+        )
+
+
+@dataclass(frozen=True)
+class MediaItem:
+    """An uploaded media library item."""
+
+    id: int
+    source_url: str
+    alt: str = ""
+    caption_raw: str = ""
+    title_raw: str = ""
+    mime: str = ""
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "MediaItem":
+        return cls(
+            id=data["id"],
+            source_url=data.get("source_url", ""),
+            alt=data.get("alt_text", ""),
+            caption_raw=_raw(data.get("caption")),
+            title_raw=_raw(data.get("title")),
+            mime=data.get("mime_type", ""),
+        )
+
+
+def _rendered(field_value: dict[str, Any] | None) -> str:
+    if not field_value:
+        return ""
+    return field_value.get("rendered", "") or ""
+
+
+def _raw(field_value: dict[str, Any] | None) -> str:
+    """Prefer ``raw`` (context=edit); fall back to ``rendered`` if absent."""
+    if not field_value:
+        return ""
+    return field_value.get("raw", field_value.get("rendered", "")) or ""

wptui/api/errors.py

@@ -0,0 +1,27 @@
+"""Typed exceptions surfaced from the API layer to the UI."""
+
+from __future__ import annotations
+
+
+class ApiError(Exception):
+    """Base class for all API-layer errors."""
+
+
+class NetworkError(ApiError):
+    """Connection failed, timed out, or TLS/DNS error — the request never landed."""
+
+
+class AuthError(ApiError):
+    """Authentication or authorization failed (HTTP 401 / 403)."""
+
+
+class NotFoundError(ApiError):
+    """The requested resource does not exist (HTTP 404)."""
+
+
+class ConflictError(ApiError):
+    """The post changed on the server since we loaded it (lost-update guard)."""
+
+    def __init__(self, message: str, *, server_modified_gmt: str | None = None) -> None:
+        super().__init__(message)
+        self.server_modified_gmt = server_modified_gmt