wp_python 0.1.0__py3-none-any.whl

src/wordpress_api/__init__.py

@@ -0,0 +1,31 @@
+"""
+WordPress REST API Python Client
+
+A full-featured Python 3.12 interface to the WordPress REST API.
+"""
+
+from .client import WordPressClient
+from .auth import ApplicationPasswordAuth, BasicAuth, JWTAuth, OAuth2Auth
+from .exceptions import (
+    WordPressError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "WordPressClient",
+    "ApplicationPasswordAuth",
+    "BasicAuth",
+    "JWTAuth",
+    "OAuth2Auth",
+    "WordPressError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+]

src/wordpress_api/auth.py

@@ -0,0 +1,174 @@
+"""Authentication handlers for WordPress REST API."""
+
+import base64
+from abc import ABC, abstractmethod
+from typing import Any
+
+import httpx
+
+
+class AuthHandler(ABC):
+    """Abstract base class for authentication handlers."""
+
+    @abstractmethod
+    def get_headers(self) -> dict[str, str]:
+        """Return headers required for authentication."""
+        pass
+
+    @abstractmethod
+    def authenticate(self, request: httpx.Request) -> httpx.Request:
+        """Authenticate the request."""
+        pass
+
+
+class BasicAuth(AuthHandler):
+    """HTTP Basic Authentication.
+    
+    Note: Basic auth should only be used over HTTPS.
+    """
+
+    def __init__(self, username: str, password: str) -> None:
+        self.username = username
+        self.password = password
+        self._credentials = base64.b64encode(
+            f"{username}:{password}".encode()
+        ).decode()
+
+    def get_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Basic {self._credentials}"}
+
+    def authenticate(self, request: httpx.Request) -> httpx.Request:
+        request.headers.update(self.get_headers())
+        return request
+
+
+class ApplicationPasswordAuth(AuthHandler):
+    """WordPress Application Passwords authentication.
+    
+    Application Passwords were introduced in WordPress 5.6 and provide
+    a secure way to authenticate REST API requests without exposing
+    the user's main password.
+    """
+
+    def __init__(self, username: str, application_password: str) -> None:
+        self.username = username
+        self.application_password = application_password.replace(" ", "")
+        self._credentials = base64.b64encode(
+            f"{username}:{self.application_password}".encode()
+        ).decode()
+
+    def get_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Basic {self._credentials}"}
+
+    def authenticate(self, request: httpx.Request) -> httpx.Request:
+        request.headers.update(self.get_headers())
+        return request
+
+
+class JWTAuth(AuthHandler):
+    """JWT (JSON Web Token) Authentication.
+    
+    Requires a JWT authentication plugin on the WordPress site.
+    """
+
+    def __init__(self, token: str | None = None) -> None:
+        self.token = token
+        self._base_url: str | None = None
+
+    def set_base_url(self, url: str) -> None:
+        """Set the base URL for token requests."""
+        self._base_url = url
+
+    def get_headers(self) -> dict[str, str]:
+        if not self.token:
+            return {}
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def authenticate(self, request: httpx.Request) -> httpx.Request:
+        if self.token:
+            request.headers.update(self.get_headers())
+        return request
+
+    def obtain_token(
+        self,
+        client: httpx.Client,
+        username: str,
+        password: str,
+        endpoint: str = "/wp-json/jwt-auth/v1/token",
+    ) -> str:
+        """Obtain a JWT token from the WordPress site."""
+        response = client.post(
+            endpoint,
+            json={"username": username, "password": password},
+        )
+        response.raise_for_status()
+        data = response.json()
+        self.token = data.get("token", data.get("data", {}).get("token"))
+        return self.token
+
+    def validate_token(
+        self,
+        client: httpx.Client,
+        endpoint: str = "/wp-json/jwt-auth/v1/token/validate",
+    ) -> bool:
+        """Validate the current JWT token."""
+        if not self.token:
+            return False
+        response = client.post(endpoint, headers=self.get_headers())
+        return response.status_code == 200
+
+
+class OAuth2Auth(AuthHandler):
+    """OAuth 2.0 Authentication.
+    
+    Requires OAuth 2.0 plugin on the WordPress site.
+    """
+
+    def __init__(
+        self,
+        access_token: str | None = None,
+        refresh_token: str | None = None,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+    ) -> None:
+        self.access_token = access_token
+        self.refresh_token = refresh_token
+        self.client_id = client_id
+        self.client_secret = client_secret
+
+    def get_headers(self) -> dict[str, str]:
+        if not self.access_token:
+            return {}
+        return {"Authorization": f"Bearer {self.access_token}"}
+
+    def authenticate(self, request: httpx.Request) -> httpx.Request:
+        if self.access_token:
+            request.headers.update(self.get_headers())
+        return request
+
+    def refresh_access_token(
+        self,
+        client: httpx.Client,
+        token_endpoint: str,
+    ) -> str:
+        """Refresh the access token using the refresh token."""
+        if not self.refresh_token or not self.client_id:
+            raise ValueError("Refresh token and client ID required")
+
+        data: dict[str, Any] = {
+            "grant_type": "refresh_token",
+            "refresh_token": self.refresh_token,
+            "client_id": self.client_id,
+        }
+        if self.client_secret:
+            data["client_secret"] = self.client_secret
+
+        response = client.post(token_endpoint, data=data)
+        response.raise_for_status()
+        token_data = response.json()
+        
+        self.access_token = token_data["access_token"]
+        if "refresh_token" in token_data:
+            self.refresh_token = token_data["refresh_token"]
+        
+        return self.access_token

src/wordpress_api/client.py

@@ -0,0 +1,293 @@
+"""Main WordPress REST API Client."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urljoin  # noqa: F401
+
+import httpx
+
+from .auth import ApplicationPasswordAuth, AuthHandler, BasicAuth, JWTAuth  # noqa: F401
+from .endpoints.application_passwords import ApplicationPasswordsEndpoint
+from .endpoints.autosaves import AutosavesEndpoint
+from .endpoints.blocks import BlocksEndpoint
+from .endpoints.categories import CategoriesEndpoint
+from .endpoints.comments import CommentsEndpoint
+from .endpoints.media import MediaEndpoint
+from .endpoints.menus import MenusEndpoint
+from .endpoints.pages import PagesEndpoint
+from .endpoints.plugins import PluginsEndpoint
+from .endpoints.post_types import PostTypesEndpoint
+from .endpoints.posts import PostsEndpoint
+from .endpoints.revisions import RevisionsEndpoint
+from .endpoints.search import SearchEndpoint
+from .endpoints.settings import SettingsEndpoint
+from .endpoints.statuses import StatusesEndpoint
+from .endpoints.tags import TagsEndpoint
+from .endpoints.taxonomies import TaxonomiesEndpoint
+from .endpoints.themes import ThemesEndpoint
+from .endpoints.users import UsersEndpoint
+from .exceptions import WordPressError, raise_for_status  # noqa: F401
+
+
+class WordPressClient:
+    """WordPress REST API Client.
+
+    A full-featured Python interface to the WordPress REST API.
+
+    Example:
+        ```python
+        from wordpress_api import WordPressClient, ApplicationPasswordAuth
+
+        auth = ApplicationPasswordAuth("username", "xxxx xxxx xxxx xxxx xxxx xxxx")
+        client = WordPressClient("https://example.com", auth=auth)
+
+        # List posts
+        posts = client.posts.list()
+
+        # Create a new post
+        new_post = client.posts.create({
+            "title": "Hello World",
+            "content": "This is my first post!",
+            "status": "publish"
+        })
+
+        # Get current user
+        me = client.users.me()
+        ```
+
+    Args:
+        base_url: The WordPress site URL (e.g., "https://example.com").
+        auth: Authentication handler (ApplicationPasswordAuth, BasicAuth, or JWTAuth).
+        timeout: Request timeout in seconds (default 30).
+        verify_ssl: Whether to verify SSL certificates (default True).
+        user_agent: Custom User-Agent string.
+        api_prefix: REST API prefix (default "/wp-json").
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        auth: AuthHandler | None = None,
+        timeout: float = 30.0,
+        verify_ssl: bool = True,
+        user_agent: str | None = None,
+        api_prefix: str = "/wp-json",
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_prefix = api_prefix
+        self.auth = auth
+        self.timeout = timeout
+        self.verify_ssl = verify_ssl
+
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if user_agent:
+            headers["User-Agent"] = user_agent
+        else:
+            headers["User-Agent"] = "WordPress-Python-Client/1.0"
+
+        if auth:
+            headers.update(auth.get_headers())
+
+        self._client = httpx.Client(
+            base_url=f"{self.base_url}{self.api_prefix}",
+            headers=headers,
+            timeout=timeout,
+            verify=verify_ssl,
+        )
+
+        self._last_response: httpx.Response | None = None
+        self._total_pages: int | None = None
+        self._total_items: int | None = None
+
+        self._init_endpoints()
+
+    def _init_endpoints(self) -> None:
+        """Initialize all API endpoints."""
+        self.posts = PostsEndpoint(self)
+        self.pages = PagesEndpoint(self)
+        self.media = MediaEndpoint(self)
+        self.users = UsersEndpoint(self)
+        self.comments = CommentsEndpoint(self)
+        self.categories = CategoriesEndpoint(self)
+        self.tags = TagsEndpoint(self)
+        self.taxonomies = TaxonomiesEndpoint(self)
+        self.settings = SettingsEndpoint(self)
+        self.plugins = PluginsEndpoint(self)
+        self.themes = ThemesEndpoint(self)
+        self.menus = MenusEndpoint(self)
+        self.search = SearchEndpoint(self)
+        self.blocks = BlocksEndpoint(self)
+        self.revisions = RevisionsEndpoint(self)
+        self.autosaves = AutosavesEndpoint(self)
+        self.post_types = PostTypesEndpoint(self)
+        self.statuses = StatusesEndpoint(self)
+        self.application_passwords = ApplicationPasswordsEndpoint(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        content: bytes | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Make an HTTP request to the WordPress REST API."""
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        request_headers = {}
+        if headers:
+            request_headers.update(headers)
+
+        if content is not None:
+            response = self._client.request(
+                method,
+                path,
+                params=params,
+                content=content,
+                headers=request_headers,
+            )
+        elif files:
+            response = self._client.request(
+                method,
+                path,
+                params=params,
+                files=files,
+                headers=request_headers,
+            )
+        else:
+            response = self._client.request(
+                method,
+                path,
+                params=params,
+                json=json,
+                headers=request_headers,
+            )
+
+        self._last_response = response
+        self._total_pages = int(response.headers.get("X-WP-TotalPages", 0))
+        self._total_items = int(response.headers.get("X-WP-Total", 0))
+
+        if response.status_code >= 400:
+            try:
+                error_data = response.json()
+            except Exception:
+                error_data = {"message": response.text}
+            raise_for_status(response.status_code, error_data)
+
+        if response.status_code == 204:
+            return {}
+
+        try:
+            return response.json()
+        except Exception:
+            return {"raw": response.text}
+
+    def discover(self) -> dict[str, Any]:
+        """Discover the WordPress REST API.
+
+        Returns information about available routes and authentication.
+        """
+        return self._request("GET", "/")
+
+    def get_namespaces(self) -> list[str]:
+        """Get available API namespaces."""
+        discovery = self.discover()
+        return discovery.get("namespaces", [])
+
+    def get_routes(self) -> dict[str, Any]:
+        """Get all available API routes."""
+        discovery = self.discover()
+        return discovery.get("routes", {})
+
+    def get_authentication_status(self) -> dict[str, Any]:
+        """Check if the current authentication is valid."""
+        discovery = self.discover()
+        return discovery.get("authentication", {})
+
+    @property
+    def total_pages(self) -> int | None:
+        """Total pages from the last list request."""
+        return self._total_pages
+
+    @property
+    def total_items(self) -> int | None:
+        """Total items from the last list request."""
+        return self._total_items
+
+    @property
+    def last_response(self) -> httpx.Response | None:
+        """The last HTTP response received."""
+        return self._last_response
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "WordPressClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def custom_post_type(self, post_type: str) -> "CustomPostTypeEndpoint":
+        """Access a custom post type endpoint.
+
+        Args:
+            post_type: The custom post type slug (e.g., "products", "portfolio").
+
+        Returns:
+            A CustomPostTypeEndpoint instance for the specified post type.
+        """
+        return CustomPostTypeEndpoint(self, post_type)
+
+
+class CustomPostTypeEndpoint:
+    """Endpoint for custom post types."""
+
+    def __init__(self, client: WordPressClient, post_type: str) -> None:
+        self._client = client
+        self.post_type = post_type
+        self._path = f"/wp/v2/{post_type}"
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return self._client._request("GET", path, params=params)
+
+    def _post(self, path: str, data: dict[str, Any] | None = None) -> Any:
+        return self._client._request("POST", path, json=data)
+
+    def _delete(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return self._client._request("DELETE", path, params=params)
+
+    def list(
+        self,
+        page: int = 1,
+        per_page: int = 10,
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """List items of this custom post type."""
+        params = {"page": page, "per_page": per_page, **kwargs}
+        return self._get(self._path, params=params)
+
+    def get(self, id: int, **kwargs: Any) -> dict[str, Any]:
+        """Get a single item by ID."""
+        return self._get(f"{self._path}/{id}", params=kwargs)
+
+    def create(self, data: dict[str, Any]) -> dict[str, Any]:
+        """Create a new item."""
+        return self._post(self._path, data=data)
+
+    def update(self, id: int, data: dict[str, Any]) -> dict[str, Any]:
+        """Update an existing item."""
+        return self._post(f"{self._path}/{id}", data=data)
+
+    def delete(self, id: int, force: bool = False, **kwargs: Any) -> dict[str, Any]:
+        """Delete an item."""
+        params = {"force": force, **kwargs}
+        return self._delete(f"{self._path}/{id}", params=params)

src/wordpress_api/endpoints/__init__.py

@@ -0,0 +1,43 @@
+"""WordPress REST API Endpoints."""
+
+from .posts import PostsEndpoint
+from .pages import PagesEndpoint
+from .media import MediaEndpoint
+from .users import UsersEndpoint
+from .comments import CommentsEndpoint
+from .categories import CategoriesEndpoint
+from .tags import TagsEndpoint
+from .taxonomies import TaxonomiesEndpoint
+from .settings import SettingsEndpoint
+from .plugins import PluginsEndpoint
+from .themes import ThemesEndpoint
+from .menus import MenusEndpoint
+from .search import SearchEndpoint
+from .blocks import BlocksEndpoint
+from .revisions import RevisionsEndpoint
+from .autosaves import AutosavesEndpoint
+from .post_types import PostTypesEndpoint
+from .statuses import StatusesEndpoint
+from .application_passwords import ApplicationPasswordsEndpoint
+
+__all__ = [
+    "PostsEndpoint",
+    "PagesEndpoint",
+    "MediaEndpoint",
+    "UsersEndpoint",
+    "CommentsEndpoint",
+    "CategoriesEndpoint",
+    "TagsEndpoint",
+    "TaxonomiesEndpoint",
+    "SettingsEndpoint",
+    "PluginsEndpoint",
+    "ThemesEndpoint",
+    "MenusEndpoint",
+    "SearchEndpoint",
+    "BlocksEndpoint",
+    "RevisionsEndpoint",
+    "AutosavesEndpoint",
+    "PostTypesEndpoint",
+    "StatusesEndpoint",
+    "ApplicationPasswordsEndpoint",
+]