wp_python 0.1.0__py3-none-any.whl

src/wordpress_api/endpoints/users.py

@@ -0,0 +1,129 @@
+"""Users endpoint."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models.user import User, UserCreate, UserUpdate
+from .base import CRUDEndpoint
+
+
+class UsersEndpoint(CRUDEndpoint[User]):
+    """Endpoint for managing WordPress users."""
+
+    _path = "/wp/v2/users"
+    _model_class = User
+
+    def list(
+        self,
+        page: int = 1,
+        per_page: int = 10,
+        search: str | None = None,
+        order: str = "asc",
+        orderby: str = "name",
+        roles: str | list[str] | None = None,
+        capabilities: str | list[str] | None = None,
+        who: str | None = None,
+        has_published_posts: bool | str | list[str] | None = None,
+        slug: str | list[str] | None = None,
+        include: list[int] | None = None,
+        exclude: list[int] | None = None,
+        **kwargs: Any,
+    ) -> list[User]:
+        """List users with filtering options."""
+        params: dict[str, Any] = {
+            "page": page,
+            "per_page": per_page,
+            "order": order,
+            "orderby": orderby,
+        }
+        
+        if search:
+            params["search"] = search
+        if roles:
+            if isinstance(roles, list):
+                params["roles"] = ",".join(roles)
+            else:
+                params["roles"] = roles
+        if capabilities:
+            if isinstance(capabilities, list):
+                params["capabilities"] = ",".join(capabilities)
+            else:
+                params["capabilities"] = capabilities
+        if who:
+            params["who"] = who
+        if has_published_posts is not None:
+            if isinstance(has_published_posts, bool):
+                params["has_published_posts"] = has_published_posts
+            elif isinstance(has_published_posts, list):
+                params["has_published_posts"] = ",".join(has_published_posts)
+            else:
+                params["has_published_posts"] = has_published_posts
+        if slug:
+            if isinstance(slug, list):
+                params["slug"] = ",".join(slug)
+            else:
+                params["slug"] = slug
+        if include:
+            params["include"] = ",".join(map(str, include))
+        if exclude:
+            params["exclude"] = ",".join(map(str, exclude))
+
+        params.update(kwargs)
+        response = self._get(self._path, params=params)
+        return [User.model_validate(item) for item in response]
+
+    def create(self, data: UserCreate | dict[str, Any]) -> User:
+        """Create a new user."""
+        return super().create(data)
+
+    def update(self, id: int, data: UserUpdate | dict[str, Any]) -> User:
+        """Update an existing user."""
+        return super().update(id, data)
+
+    def me(self, context: str = "view") -> User:
+        """Get the current authenticated user."""
+        response = self._get(f"{self._path}/me", params={"context": context})
+        return User.model_validate(response)
+
+    def update_me(self, data: UserUpdate | dict[str, Any]) -> User:
+        """Update the current authenticated user."""
+        if isinstance(data, UserUpdate):
+            payload = data.model_dump(exclude_none=True)
+        else:
+            payload = data
+        response = self._post(f"{self._path}/me", data=payload)
+        return User.model_validate(response)
+
+    def delete(
+        self,
+        id: int,
+        force: bool = True,
+        reassign: int | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Delete a user.
+        
+        Args:
+            id: User ID to delete.
+            force: Must be true (users cannot be trashed).
+            reassign: Reassign posts to this user ID.
+        """
+        params = {"force": force}
+        if reassign is not None:
+            params["reassign"] = reassign
+        params.update(kwargs)
+        return self._delete(f"{self._path}/{id}", params=params)
+
+    def get_by_slug(self, slug: str) -> User | None:
+        """Get a user by their slug."""
+        users = self.list(slug=slug)
+        return users[0] if users else None
+
+    def list_authors(self, **kwargs: Any) -> list[User]:
+        """List users who have published posts."""
+        return self.list(has_published_posts=True, **kwargs)
+
+    def list_by_role(self, role: str, **kwargs: Any) -> list[User]:
+        """List users with a specific role."""
+        return self.list(roles=role, **kwargs)

src/wordpress_api/exceptions.py

@@ -0,0 +1,79 @@
+"""WordPress API Exception Classes."""
+
+from typing import Any
+
+
+class WordPressError(Exception):
+    """Base exception for WordPress API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        error_code: str | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        self.data = data or {}
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status_code:
+            parts.append(f"[HTTP {self.status_code}]")
+        if self.error_code:
+            parts.append(f"[{self.error_code}]")
+        return " ".join(parts)
+
+
+class AuthenticationError(WordPressError):
+    """Authentication failed."""
+    pass
+
+
+class NotFoundError(WordPressError):
+    """Resource not found."""
+    pass
+
+
+class ValidationError(WordPressError):
+    """Validation error in request data."""
+    pass
+
+
+class RateLimitError(WordPressError):
+    """Rate limit exceeded."""
+    pass
+
+
+class ServerError(WordPressError):
+    """Server-side error."""
+    pass
+
+
+class PermissionError(WordPressError):
+    """Permission denied."""
+    pass
+
+
+def raise_for_status(status_code: int, response_data: dict[str, Any]) -> None:
+    """Raise appropriate exception based on status code."""
+    message = response_data.get("message", "Unknown error")
+    error_code = response_data.get("code", "unknown_error")
+
+    if status_code == 401:
+        raise AuthenticationError(message, status_code, error_code, response_data)
+    elif status_code == 403:
+        raise PermissionError(message, status_code, error_code, response_data)
+    elif status_code == 404:
+        raise NotFoundError(message, status_code, error_code, response_data)
+    elif status_code == 400:
+        raise ValidationError(message, status_code, error_code, response_data)
+    elif status_code == 429:
+        raise RateLimitError(message, status_code, error_code, response_data)
+    elif status_code >= 500:
+        raise ServerError(message, status_code, error_code, response_data)
+    elif status_code >= 400:
+        raise WordPressError(message, status_code, error_code, response_data)

src/wordpress_api/models/__init__.py

@@ -0,0 +1,49 @@
+"""Pydantic models for WordPress API responses."""
+
+from .post import Post, PostCreate, PostUpdate, PostStatus, PostFormat
+from .page import Page, PageCreate, PageUpdate
+from .media import Media, MediaCreate, MediaUpdate, MediaType
+from .user import User, UserCreate, UserUpdate, UserRole
+from .comment import Comment, CommentCreate, CommentUpdate, CommentStatus
+from .category import Category, CategoryCreate, CategoryUpdate
+from .tag import Tag, TagCreate, TagUpdate
+from .taxonomy import Taxonomy
+from .settings import Settings
+from .plugin import Plugin
+from .theme import Theme
+from .menu import Menu, MenuItem
+
+__all__ = [
+    "Post",
+    "PostCreate",
+    "PostUpdate",
+    "PostStatus",
+    "PostFormat",
+    "Page",
+    "PageCreate",
+    "PageUpdate",
+    "Media",
+    "MediaCreate",
+    "MediaUpdate",
+    "MediaType",
+    "User",
+    "UserCreate",
+    "UserUpdate",
+    "UserRole",
+    "Comment",
+    "CommentCreate",
+    "CommentUpdate",
+    "CommentStatus",
+    "Category",
+    "CategoryCreate",
+    "CategoryUpdate",
+    "Tag",
+    "TagCreate",
+    "TagUpdate",
+    "Taxonomy",
+    "Settings",
+    "Plugin",
+    "Theme",
+    "Menu",
+    "MenuItem",
+]

src/wordpress_api/models/base.py

@@ -0,0 +1,65 @@
+"""Base models and utilities."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+
+class WordPressModel(BaseModel):
+    """Base model for WordPress objects."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="allow",
+    )
+
+
+class RenderedContent(BaseModel):
+    """Content with rendered HTML."""
+
+    rendered: str = ""
+    raw: str | None = None
+    protected: bool = False
+
+    model_config = ConfigDict(extra="allow")
+
+
+class WPLink(BaseModel):
+    """WordPress REST API link."""
+
+    href: str
+    embeddable: bool = False
+
+    model_config = ConfigDict(extra="allow")
+
+
+class WPLinks(BaseModel):
+    """Collection of WordPress REST API links."""
+
+    self_: list[WPLink] | None = None
+    collection: list[WPLink] | None = None
+    about: list[WPLink] | None = None
+    author: list[WPLink] | None = None
+    replies: list[WPLink] | None = None
+    version_history: list[WPLink] | None = None
+    predecessor_version: list[WPLink] | None = None
+    wp_attachment: list[WPLink] | None = None
+    wp_term: list[WPLink] | None = None
+    curies: list[WPLink] | None = None
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+def parse_datetime(value: Any) -> datetime | None:
+    """Parse WordPress datetime string."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, str):
+        try:
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+    return None

src/wordpress_api/models/category.py

@@ -0,0 +1,41 @@
+"""Category models."""
+
+from typing import Any
+
+from pydantic import Field
+
+from .base import WordPressModel
+
+
+class Category(WordPressModel):
+    """WordPress Category object."""
+
+    id: int
+    count: int = 0
+    description: str = ""
+    link: str = ""
+    name: str = ""
+    slug: str = ""
+    taxonomy: str = "category"
+    parent: int = 0
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class CategoryCreate(WordPressModel):
+    """Data for creating a new category."""
+
+    name: str
+    description: str | None = None
+    slug: str | None = None
+    parent: int | None = None
+    meta: dict[str, Any] | None = None
+
+
+class CategoryUpdate(WordPressModel):
+    """Data for updating a category."""
+
+    name: str | None = None
+    description: str | None = None
+    slug: str | None = None
+    parent: int | None = None
+    meta: dict[str, Any] | None = None

src/wordpress_api/models/comment.py

@@ -0,0 +1,75 @@
+"""Comment models."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import Field, field_validator
+
+from .base import WordPressModel, RenderedContent, parse_datetime
+
+
+class CommentStatus(str, Enum):
+    """Comment status options."""
+
+    APPROVED = "approved"
+    HOLD = "hold"
+    SPAM = "spam"
+    TRASH = "trash"
+
+
+class Comment(WordPressModel):
+    """WordPress Comment object."""
+
+    id: int
+    post: int = 0
+    parent: int = 0
+    author: int = 0
+    author_name: str = ""
+    author_email: str = ""
+    author_url: str = ""
+    author_ip: str = ""
+    author_user_agent: str = ""
+    date: datetime | None = None
+    date_gmt: datetime | None = None
+    content: RenderedContent | None = None
+    link: str = ""
+    status: str = "approved"
+    type: str = "comment"
+    author_avatar_urls: dict[str, str] = Field(default_factory=dict)
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("date", "date_gmt", mode="before")
+    @classmethod
+    def parse_dates(cls, v: Any) -> datetime | None:
+        return parse_datetime(v)
+
+
+class CommentCreate(WordPressModel):
+    """Data for creating a new comment."""
+
+    post: int
+    content: str
+    parent: int | None = None
+    author: int | None = None
+    author_name: str | None = None
+    author_email: str | None = None
+    author_url: str | None = None
+    status: CommentStatus | None = None
+    meta: dict[str, Any] | None = None
+    date: datetime | str | None = None
+
+
+class CommentUpdate(WordPressModel):
+    """Data for updating a comment."""
+
+    content: str | None = None
+    post: int | None = None
+    parent: int | None = None
+    author: int | None = None
+    author_name: str | None = None
+    author_email: str | None = None
+    author_url: str | None = None
+    status: CommentStatus | None = None
+    meta: dict[str, Any] | None = None
+    date: datetime | str | None = None

src/wordpress_api/models/media.py

@@ -0,0 +1,108 @@
+"""Media models."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import Field, field_validator
+
+from .base import WordPressModel, RenderedContent, parse_datetime
+
+
+class MediaType(str, Enum):
+    """Media type options."""
+
+    IMAGE = "image"
+    FILE = "file"
+    AUDIO = "audio"
+    VIDEO = "video"
+    APPLICATION = "application"
+
+
+class MediaSize(WordPressModel):
+    """Individual media size details."""
+
+    file: str = ""
+    width: int = 0
+    height: int = 0
+    mime_type: str = ""
+    source_url: str = ""
+
+
+class MediaDetails(WordPressModel):
+    """Media file details."""
+
+    width: int = 0
+    height: int = 0
+    file: str = ""
+    filesize: int = 0
+    sizes: dict[str, MediaSize] = Field(default_factory=dict)
+    image_meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class Media(WordPressModel):
+    """WordPress Media object."""
+
+    id: int
+    date: datetime | None = None
+    date_gmt: datetime | None = None
+    guid: RenderedContent | None = None
+    modified: datetime | None = None
+    modified_gmt: datetime | None = None
+    slug: str = ""
+    status: str = "inherit"
+    type: str = "attachment"
+    link: str = ""
+    title: RenderedContent | None = None
+    author: int = 0
+    comment_status: str = "open"
+    ping_status: str = "closed"
+    template: str = ""
+    meta: dict[str, Any] = Field(default_factory=dict)
+    description: RenderedContent | None = None
+    caption: RenderedContent | None = None
+    alt_text: str = ""
+    media_type: str = ""
+    mime_type: str = ""
+    media_details: MediaDetails | None = None
+    post: int | None = None
+    source_url: str = ""
+
+    @field_validator("date", "date_gmt", "modified", "modified_gmt", mode="before")
+    @classmethod
+    def parse_dates(cls, v: Any) -> datetime | None:
+        return parse_datetime(v)
+
+
+class MediaCreate(WordPressModel):
+    """Data for creating/uploading new media."""
+
+    title: str | None = None
+    caption: str | None = None
+    alt_text: str | None = None
+    description: str | None = None
+    post: int | None = None
+    author: int | None = None
+    comment_status: str | None = None
+    ping_status: str | None = None
+    meta: dict[str, Any] | None = None
+    slug: str | None = None
+    status: str | None = None
+    date: datetime | str | None = None
+
+
+class MediaUpdate(WordPressModel):
+    """Data for updating media."""
+
+    title: str | None = None
+    caption: str | None = None
+    alt_text: str | None = None
+    description: str | None = None
+    post: int | None = None
+    author: int | None = None
+    comment_status: str | None = None
+    ping_status: str | None = None
+    meta: dict[str, Any] | None = None
+    slug: str | None = None
+    status: str | None = None
+    date: datetime | str | None = None

src/wordpress_api/models/menu.py

@@ -0,0 +1,83 @@
+"""Menu models."""
+
+from typing import Any
+
+from pydantic import Field
+
+from .base import WordPressModel
+
+
+class MenuItem(WordPressModel):
+    """WordPress Menu Item object."""
+
+    id: int
+    title: str = ""
+    status: str = "publish"
+    url: str = ""
+    attr_title: str = ""
+    description: str = ""
+    type: str = "custom"
+    type_label: str = ""
+    object: str = "custom"
+    object_id: int = 0
+    parent: int = 0
+    menu_order: int = 0
+    target: str = ""
+    classes: list[str] = Field(default_factory=list)
+    xfn: list[str] = Field(default_factory=list)
+    invalid: bool = False
+    menus: int = 0
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class Menu(WordPressModel):
+    """WordPress Navigation Menu object."""
+
+    id: int
+    name: str = ""
+    slug: str = ""
+    description: str = ""
+    count: int = 0
+    auto_add: bool = False
+    locations: list[str] = Field(default_factory=list)
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class MenuItemCreate(WordPressModel):
+    """Data for creating a menu item."""
+
+    title: str
+    url: str | None = None
+    status: str = "publish"
+    attr_title: str | None = None
+    description: str | None = None
+    type: str = "custom"
+    object: str | None = None
+    object_id: int | None = None
+    parent: int | None = None
+    menu_order: int | None = None
+    target: str | None = None
+    classes: list[str] | None = None
+    xfn: list[str] | None = None
+    menus: int | None = None
+    meta: dict[str, Any] | None = None
+
+
+class MenuItemUpdate(WordPressModel):
+    """Data for updating a menu item."""
+
+    title: str | None = None
+    url: str | None = None
+    status: str | None = None
+    attr_title: str | None = None
+    description: str | None = None
+    type: str | None = None
+    object: str | None = None
+    object_id: int | None = None
+    parent: int | None = None
+    menu_order: int | None = None
+    target: str | None = None
+    classes: list[str] | None = None
+    xfn: list[str] | None = None
+    menus: int | None = None
+    meta: dict[str, Any] | None = None