wp_python 0.1.0__py3-none-any.whl

src/wordpress_api/endpoints/application_passwords.py

@@ -0,0 +1,235 @@
+"""Application Passwords endpoint."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator
+
+from ..models.base import parse_datetime
+from .base import BaseEndpoint
+
+
+class ApplicationPassword(BaseModel):
+    """WordPress Application Password object."""
+
+    uuid: str = ""
+    app_id: str = ""
+    name: str = ""
+    created: datetime | None = None
+    last_used: datetime | None = None
+    last_ip: str | None = None
+
+    @field_validator("created", "last_used", mode="before")
+    @classmethod
+    def parse_dates(cls, v: Any) -> datetime | None:
+        return parse_datetime(v)
+
+
+class ApplicationPasswordCreated(BaseModel):
+    """Response when creating an Application Password (includes the password)."""
+
+    uuid: str = ""
+    app_id: str = ""
+    name: str = ""
+    created: datetime | None = None
+    password: str = ""
+
+    @field_validator("created", mode="before")
+    @classmethod
+    def parse_dates(cls, v: Any) -> datetime | None:
+        return parse_datetime(v)
+
+
+class ApplicationPasswordsEndpoint(BaseEndpoint):
+    """Endpoint for managing WordPress Application Passwords.
+    
+    Application Passwords were introduced in WordPress 5.6 and provide
+    a secure way to authenticate REST API requests.
+    """
+
+    def _get_path(self, user_id: int | str) -> str:
+        """Get the endpoint path for a user's application passwords."""
+        return f"/wp/v2/users/{user_id}/application-passwords"
+
+    def list(self, user_id: int | str = "me") -> list[ApplicationPassword]:
+        """List all application passwords for a user.
+        
+        Args:
+            user_id: User ID or "me" for current user.
+        
+        Returns:
+            List of application passwords (without the actual password values).
+        """
+        response = self._get(self._get_path(user_id))
+        return [ApplicationPassword.model_validate(item) for item in response]
+
+    def get(self, uuid: str, user_id: int | str = "me") -> ApplicationPassword:
+        """Get a specific application password by UUID.
+        
+        Args:
+            uuid: The UUID of the application password.
+            user_id: User ID or "me" for current user.
+        
+        Returns:
+            The application password details.
+        """
+        response = self._get(f"{self._get_path(user_id)}/{uuid}")
+        return ApplicationPassword.model_validate(response)
+
+    def create(
+        self,
+        name: str,
+        user_id: int | str = "me",
+        app_id: str | None = None,
+    ) -> ApplicationPasswordCreated:
+        """Create a new application password.
+        
+        Args:
+            name: A human-readable name for the application password.
+            user_id: User ID or "me" for current user.
+            app_id: Optional application identifier (UUID format).
+        
+        Returns:
+            The created application password including the password value.
+            Note: The password is only returned once at creation time!
+        """
+        data: dict[str, Any] = {"name": name}
+        if app_id:
+            data["app_id"] = app_id
+        
+        response = self._post(self._get_path(user_id), data=data)
+        return ApplicationPasswordCreated.model_validate(response)
+
+    def update(
+        self,
+        uuid: str,
+        name: str,
+        user_id: int | str = "me",
+    ) -> ApplicationPassword:
+        """Update an application password's name.
+        
+        Args:
+            uuid: The UUID of the application password.
+            name: The new name for the application password.
+            user_id: User ID or "me" for current user.
+        
+        Returns:
+            The updated application password.
+        """
+        response = self._post(
+            f"{self._get_path(user_id)}/{uuid}",
+            data={"name": name},
+        )
+        return ApplicationPassword.model_validate(response)
+
+    def delete(
+        self,
+        uuid: str,
+        user_id: int | str = "me",
+    ) -> dict[str, Any]:
+        """Delete an application password.
+        
+        Args:
+            uuid: The UUID of the application password.
+            user_id: User ID or "me" for current user.
+        
+        Returns:
+            Deletion confirmation.
+        """
+        return self._delete(f"{self._get_path(user_id)}/{uuid}")
+
+    def delete_all(self, user_id: int | str = "me") -> dict[str, Any]:
+        """Delete all application passwords for a user.
+        
+        Args:
+            user_id: User ID or "me" for current user.
+        
+        Returns:
+            Deletion confirmation.
+        """
+        return self._delete(self._get_path(user_id))
+
+    def get_or_create(
+        self,
+        name: str,
+        user_id: int | str = "me",
+        app_id: str | None = None,
+    ) -> ApplicationPasswordCreated | ApplicationPassword:
+        """Get an existing application password by name, or create one if none exist.
+        
+        This method checks if the user has any application passwords with the
+        given name. If found, it returns the existing one. If not found (or if
+        no application passwords exist), it creates a new one.
+        
+        Args:
+            name: The name to search for or use when creating.
+            user_id: User ID or "me" for current user.
+            app_id: Optional application identifier for new passwords.
+        
+        Returns:
+            Either an existing ApplicationPassword or a newly created
+            ApplicationPasswordCreated (which includes the password value).
+        
+        Note:
+            If an existing password is returned, the actual password value
+            is NOT included (WordPress doesn't store or return it after creation).
+            Only newly created passwords include the password value.
+        """
+        existing = self.list(user_id)
+        
+        for app_pass in existing:
+            if app_pass.name == name:
+                return app_pass
+        
+        return self.create(name=name, user_id=user_id, app_id=app_id)
+
+    def ensure_exists(
+        self,
+        name: str,
+        user_id: int | str = "me",
+        app_id: str | None = None,
+    ) -> tuple[ApplicationPasswordCreated | ApplicationPassword, bool]:
+        """Ensure an application password exists, creating if necessary.
+        
+        Args:
+            name: The name for the application password.
+            user_id: User ID or "me" for current user.
+            app_id: Optional application identifier for new passwords.
+        
+        Returns:
+            A tuple of (application_password, was_created).
+            If was_created is True, the password value is available.
+        """
+        existing = self.list(user_id)
+        
+        for app_pass in existing:
+            if app_pass.name == name:
+                return app_pass, False
+        
+        new_password = self.create(name=name, user_id=user_id, app_id=app_id)
+        return new_password, True
+
+    def has_any(self, user_id: int | str = "me") -> bool:
+        """Check if the user has any application passwords.
+        
+        Args:
+            user_id: User ID or "me" for current user.
+        
+        Returns:
+            True if the user has at least one application password.
+        """
+        return len(self.list(user_id)) > 0
+
+    def count(self, user_id: int | str = "me") -> int:
+        """Count the number of application passwords for a user.
+        
+        Args:
+            user_id: User ID or "me" for current user.
+        
+        Returns:
+            Number of application passwords.
+        """
+        return len(self.list(user_id))

src/wordpress_api/endpoints/autosaves.py

@@ -0,0 +1,106 @@
+"""Autosaves endpoint."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, field_validator
+
+from ..models.base import RenderedContent, parse_datetime
+from .base import BaseEndpoint
+
+
+class Autosave(BaseModel):
+    """WordPress Autosave object."""
+
+    id: int
+    author: int = 0
+    date: datetime | None = None
+    date_gmt: datetime | None = None
+    modified: datetime | None = None
+    modified_gmt: datetime | None = None
+    parent: int = 0
+    slug: str = ""
+    title: RenderedContent | None = None
+    content: RenderedContent | None = None
+    excerpt: RenderedContent | None = None
+
+    @field_validator("date", "date_gmt", "modified", "modified_gmt", mode="before")
+    @classmethod
+    def parse_dates(cls, v: Any) -> datetime | None:
+        return parse_datetime(v)
+
+
+class AutosavesEndpoint(BaseEndpoint):
+    """Endpoint for managing post and page autosaves."""
+
+    def list_post_autosaves(self, post_id: int, **kwargs: Any) -> list[Autosave]:
+        """List autosaves for a post."""
+        response = self._get(f"/wp/v2/posts/{post_id}/autosaves", params=kwargs)
+        return [Autosave.model_validate(item) for item in response]
+
+    def get_post_autosave(self, post_id: int, autosave_id: int) -> Autosave:
+        """Get a specific post autosave."""
+        response = self._get(f"/wp/v2/posts/{post_id}/autosaves/{autosave_id}")
+        return Autosave.model_validate(response)
+
+    def create_post_autosave(
+        self,
+        post_id: int,
+        title: str | None = None,
+        content: str | None = None,
+        excerpt: str | None = None,
+        **kwargs: Any,
+    ) -> Autosave:
+        """Create an autosave for a post."""
+        data: dict[str, Any] = {}
+        if title:
+            data["title"] = title
+        if content:
+            data["content"] = content
+        if excerpt:
+            data["excerpt"] = excerpt
+        data.update(kwargs)
+        
+        response = self._post(f"/wp/v2/posts/{post_id}/autosaves", data=data)
+        return Autosave.model_validate(response)
+
+    def list_page_autosaves(self, page_id: int, **kwargs: Any) -> list[Autosave]:
+        """List autosaves for a page."""
+        response = self._get(f"/wp/v2/pages/{page_id}/autosaves", params=kwargs)
+        return [Autosave.model_validate(item) for item in response]
+
+    def get_page_autosave(self, page_id: int, autosave_id: int) -> Autosave:
+        """Get a specific page autosave."""
+        response = self._get(f"/wp/v2/pages/{page_id}/autosaves/{autosave_id}")
+        return Autosave.model_validate(response)
+
+    def create_page_autosave(
+        self,
+        page_id: int,
+        title: str | None = None,
+        content: str | None = None,
+        excerpt: str | None = None,
+        **kwargs: Any,
+    ) -> Autosave:
+        """Create an autosave for a page."""
+        data: dict[str, Any] = {}
+        if title:
+            data["title"] = title
+        if content:
+            data["content"] = content
+        if excerpt:
+            data["excerpt"] = excerpt
+        data.update(kwargs)
+        
+        response = self._post(f"/wp/v2/pages/{page_id}/autosaves", data=data)
+        return Autosave.model_validate(response)
+
+    def get_latest_autosave(self, post_id: int, post_type: str = "posts") -> Autosave | None:
+        """Get the most recent autosave."""
+        if post_type == "pages":
+            autosaves = self.list_page_autosaves(post_id)
+        else:
+            autosaves = self.list_post_autosaves(post_id)
+        return autosaves[0] if autosaves else None

src/wordpress_api/endpoints/base.py

@@ -0,0 +1,117 @@
+"""Base endpoint class."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar, Generic, TYPE_CHECKING
+from collections.abc import Iterator
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class BaseEndpoint:
+    """Base class for all API endpoints."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """Make GET request."""
+        return self._client._request("GET", path, params=params)
+
+    def _post(
+        self,
+        path: str,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+    ) -> Any:
+        """Make POST request."""
+        return self._client._request("POST", path, json=data, files=files)
+
+    def _put(self, path: str, data: dict[str, Any] | None = None) -> Any:
+        """Make PUT request."""
+        return self._client._request("PUT", path, json=data)
+
+    def _patch(self, path: str, data: dict[str, Any] | None = None) -> Any:
+        """Make PATCH request."""
+        return self._client._request("PATCH", path, json=data)
+
+    def _delete(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """Make DELETE request."""
+        return self._client._request("DELETE", path, params=params)
+
+
+class CRUDEndpoint(BaseEndpoint, Generic[T]):
+    """Base class for CRUD endpoints."""
+
+    _path: str = ""
+    _model_class: type[T]
+
+    def list(
+        self,
+        page: int = 1,
+        per_page: int = 10,
+        search: str | None = None,
+        order: str = "desc",
+        orderby: str = "date",
+        **kwargs: Any,
+    ) -> list[T]:
+        """List resources with pagination."""
+        params: dict[str, Any] = {
+            "page": page,
+            "per_page": per_page,
+            "order": order,
+            "orderby": orderby,
+        }
+        if search:
+            params["search"] = search
+        params.update(kwargs)
+
+        response = self._get(self._path, params=params)
+        return [self._model_class.model_validate(item) for item in response]
+
+    def get(self, id: int, context: str = "view", **kwargs: Any) -> T:
+        """Get a single resource by ID."""
+        params = {"context": context, **kwargs}
+        response = self._get(f"{self._path}/{id}", params=params)
+        return self._model_class.model_validate(response)
+
+    def create(self, data: BaseModel | dict[str, Any]) -> T:
+        """Create a new resource."""
+        if isinstance(data, BaseModel):
+            payload = data.model_dump(exclude_none=True)
+        else:
+            payload = data
+        response = self._post(self._path, data=payload)
+        return self._model_class.model_validate(response)
+
+    def update(self, id: int, data: BaseModel | dict[str, Any]) -> T:
+        """Update an existing resource."""
+        if isinstance(data, BaseModel):
+            payload = data.model_dump(exclude_none=True)
+        else:
+            payload = data
+        response = self._post(f"{self._path}/{id}", data=payload)
+        return self._model_class.model_validate(response)
+
+    def delete(self, id: int, force: bool = False, **kwargs: Any) -> dict[str, Any]:
+        """Delete a resource."""
+        params = {"force": force, **kwargs}
+        return self._delete(f"{self._path}/{id}", params=params)
+
+    def iterate_all(
+        self,
+        per_page: int = 100,
+        **kwargs: Any,
+    ) -> Iterator[T]:
+        """Iterate through all resources with automatic pagination."""
+        page = 1
+        while True:
+            items = self.list(page=page, per_page=per_page, **kwargs)
+            if not items:
+                break
+            yield from items
+            if len(items) < per_page:
+                break
+            page += 1

src/wordpress_api/endpoints/blocks.py

@@ -0,0 +1,107 @@
+"""Block Types and Patterns endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .base import BaseEndpoint
+
+
+class BlockType(BaseModel):
+    """WordPress Block Type."""
+
+    name: str = ""
+    title: str = ""
+    description: str = ""
+    icon: str | None = None
+    category: str = ""
+    keywords: list[str] = Field(default_factory=list)
+    parent: list[str] | None = None
+    supports: dict[str, Any] = Field(default_factory=dict)
+    styles: list[dict[str, Any]] = Field(default_factory=list)
+    textdomain: str = ""
+    example: dict[str, Any] | None = None
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    provides_context: dict[str, str] = Field(default_factory=dict)
+    uses_context: list[str] = Field(default_factory=list)
+    editor_script: str | None = None
+    script: str | None = None
+    editor_style: str | None = None
+    style: str | None = None
+    is_dynamic: bool = False
+    api_version: int = 1
+
+
+class BlockPattern(BaseModel):
+    """WordPress Block Pattern."""
+
+    name: str = ""
+    title: str = ""
+    description: str = ""
+    content: str = ""
+    categories: list[str] = Field(default_factory=list)
+    keywords: list[str] = Field(default_factory=list)
+    viewport_width: int | None = None
+    block_types: list[str] = Field(default_factory=list)
+    inserter: bool = True
+
+
+class BlockPatternCategory(BaseModel):
+    """WordPress Block Pattern Category."""
+
+    name: str = ""
+    label: str = ""
+    description: str = ""
+
+
+class BlocksEndpoint(BaseEndpoint):
+    """Endpoint for WordPress block types and patterns."""
+
+    _types_path = "/wp/v2/block-types"
+    _patterns_path = "/wp/v2/block-patterns/patterns"
+    _pattern_categories_path = "/wp/v2/block-patterns/categories"
+
+    def list_types(self, namespace: str | None = None, **kwargs: Any) -> list[BlockType]:
+        """List registered block types.
+        
+        Args:
+            namespace: Filter by block namespace (e.g., 'core').
+        """
+        params: dict[str, Any] = {}
+        if namespace:
+            params["namespace"] = namespace
+        params.update(kwargs)
+        
+        response = self._get(self._types_path, params=params)
+        return [BlockType.model_validate(item) for item in response]
+
+    def get_type(self, namespace: str, name: str, **kwargs: Any) -> BlockType:
+        """Get a specific block type.
+        
+        Args:
+            namespace: Block namespace (e.g., 'core').
+            name: Block name (e.g., 'paragraph').
+        """
+        response = self._get(f"{self._types_path}/{namespace}/{name}", params=kwargs)
+        return BlockType.model_validate(response)
+
+    def list_core_blocks(self) -> list[BlockType]:
+        """List all core WordPress blocks."""
+        return self.list_types(namespace="core")
+
+    def list_patterns(self, **kwargs: Any) -> list[BlockPattern]:
+        """List registered block patterns."""
+        response = self._get(self._patterns_path, params=kwargs)
+        return [BlockPattern.model_validate(item) for item in response]
+
+    def list_pattern_categories(self, **kwargs: Any) -> list[BlockPatternCategory]:
+        """List block pattern categories."""
+        response = self._get(self._pattern_categories_path, params=kwargs)
+        return [BlockPatternCategory.model_validate(item) for item in response]
+
+    def get_patterns_by_category(self, category: str) -> list[BlockPattern]:
+        """Get patterns filtered by category."""
+        patterns = self.list_patterns()
+        return [p for p in patterns if category in p.categories]

src/wordpress_api/endpoints/categories.py

@@ -0,0 +1,91 @@
+"""Categories endpoint."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models.category import Category, CategoryCreate, CategoryUpdate
+from .base import CRUDEndpoint
+
+
+class CategoriesEndpoint(CRUDEndpoint[Category]):
+    """Endpoint for managing WordPress categories."""
+
+    _path = "/wp/v2/categories"
+    _model_class = Category
+
+    def list(
+        self,
+        page: int = 1,
+        per_page: int = 10,
+        search: str | None = None,
+        order: str = "asc",
+        orderby: str = "name",
+        hide_empty: bool = False,
+        parent: int | None = None,
+        post: int | None = None,
+        slug: str | list[str] | None = None,
+        include: list[int] | None = None,
+        exclude: list[int] | None = None,
+        **kwargs: Any,
+    ) -> list[Category]:
+        """List categories with filtering options."""
+        params: dict[str, Any] = {
+            "page": page,
+            "per_page": per_page,
+            "order": order,
+            "orderby": orderby,
+            "hide_empty": hide_empty,
+        }
+        
+        if search:
+            params["search"] = search
+        if parent is not None:
+            params["parent"] = parent
+        if post is not None:
+            params["post"] = post
+        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 [Category.model_validate(item) for item in response]
+
+    def create(self, data: CategoryCreate | dict[str, Any]) -> Category:
+        """Create a new category."""
+        return super().create(data)
+
+    def update(self, id: int, data: CategoryUpdate | dict[str, Any]) -> Category:
+        """Update an existing category."""
+        return super().update(id, data)
+
+    def get_by_slug(self, slug: str) -> Category | None:
+        """Get a category by its slug."""
+        categories = self.list(slug=slug)
+        return categories[0] if categories else None
+
+    def get_children(self, parent_id: int, **kwargs: Any) -> list[Category]:
+        """Get child categories of a parent."""
+        return self.list(parent=parent_id, **kwargs)
+
+    def get_hierarchy(self) -> dict[int, list[Category]]:
+        """Get all categories organized by parent ID."""
+        all_categories = list(self.iterate_all())
+        hierarchy: dict[int, list[Category]] = {}
+        for category in all_categories:
+            parent = category.parent
+            if parent not in hierarchy:
+                hierarchy[parent] = []
+            hierarchy[parent].append(category)
+        return hierarchy
+
+    def get_for_post(self, post_id: int) -> list[Category]:
+        """Get categories assigned to a specific post."""
+        return self.list(post=post_id)