wp-python 0.1.3__tar.gz

wp_python-0.1.3/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.env
+.venv
+env/
+venv/
+.cache/
+*.db

wp_python-0.1.3/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wp_python-0.1.3/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: wp_python
+Version: 0.1.3
+Summary: A Python client for interacting with the WordPress REST API.
+Author-email: Andrew <andrew.neher1@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: hatch>=1.16.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pytest-mock>=3.15.1
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: respx>=0.22.0
+Description-Content-Type: text/markdown
+
+# WordPress REST API Python Client
+
+A full-featured Python 3.12 interface to the WordPress REST API.
+
+## Overview
+
+This library provides a comprehensive, type-safe Python client for interacting with WordPress sites via the REST API. It supports all major WordPress endpoints including posts, pages, media, users, comments, categories, tags, settings, plugins, themes, menus, and more.
+
+## Project Structure
+
+```
+src/wordpress_api/
+├── __init__.py          # Main exports
+├── client.py            # WordPressClient main class
+├── auth.py              # Authentication handlers
+├── exceptions.py        # Custom exceptions
+├── models/              # Pydantic data models
+│   ├── post.py
+│   ├── page.py
+│   ├── media.py
+│   ├── user.py
+│   ├── comment.py
+│   ├── category.py
+│   ├── tag.py
+│   └── ...
+└── endpoints/           # API endpoint classes
+    ├── posts.py
+    ├── pages.py
+    ├── media.py
+    ├── users.py
+    ├── comments.py
+    └── ...
+```
+
+## Quick Start
+
+```python
+from wordpress_api import WordPressClient, ApplicationPasswordAuth
+
+# Authenticate with WordPress Application Passwords
+auth = ApplicationPasswordAuth("username", "xxxx xxxx xxxx xxxx")
+client = WordPressClient("https://your-site.com", auth=auth)
+
+# List posts
+posts = client.posts.list()
+
+# Create a post
+from wordpress_api.models import PostCreate, PostStatus
+post = client.posts.create(PostCreate(
+    title="Hello World",
+    content="<p>My first post!</p>",
+    status=PostStatus.PUBLISH
+))
+
+# Get current user
+me = client.users.me()
+```
+
+## Features
+
+- **Full CRUD Support**: Posts, Pages, Media, Users, Comments, Categories, Tags
+- **Authentication**: Application Passwords, Basic Auth, JWT
+- **Type Safety**: Pydantic models for all WordPress objects
+- **Pagination**: Automatic iteration through all results
+- **Media Upload**: Upload files from path or file objects
+- **Custom Post Types**: Access any registered custom post type
+- **Block Editor**: Access block types and patterns
+- **Error Handling**: Typed exceptions for all API errors
+
+## Dependencies
+
+- httpx: Modern HTTP client
+- pydantic: Data validation using Python type annotations
+
+## Authentication Setup
+
+1. Go to your WordPress site
+2. Navigate to Users → Your Profile
+3. Scroll to "Application Passwords"
+4. Create a new application password
+5. Use it with `ApplicationPasswordAuth`

wp_python-0.1.3/README.md

@@ -0,0 +1,81 @@
+# WordPress REST API Python Client
+
+A full-featured Python 3.12 interface to the WordPress REST API.
+
+## Overview
+
+This library provides a comprehensive, type-safe Python client for interacting with WordPress sites via the REST API. It supports all major WordPress endpoints including posts, pages, media, users, comments, categories, tags, settings, plugins, themes, menus, and more.
+
+## Project Structure
+
+```
+src/wordpress_api/
+├── __init__.py          # Main exports
+├── client.py            # WordPressClient main class
+├── auth.py              # Authentication handlers
+├── exceptions.py        # Custom exceptions
+├── models/              # Pydantic data models
+│   ├── post.py
+│   ├── page.py
+│   ├── media.py
+│   ├── user.py
+│   ├── comment.py
+│   ├── category.py
+│   ├── tag.py
+│   └── ...
+└── endpoints/           # API endpoint classes
+    ├── posts.py
+    ├── pages.py
+    ├── media.py
+    ├── users.py
+    ├── comments.py
+    └── ...
+```
+
+## Quick Start
+
+```python
+from wordpress_api import WordPressClient, ApplicationPasswordAuth
+
+# Authenticate with WordPress Application Passwords
+auth = ApplicationPasswordAuth("username", "xxxx xxxx xxxx xxxx")
+client = WordPressClient("https://your-site.com", auth=auth)
+
+# List posts
+posts = client.posts.list()
+
+# Create a post
+from wordpress_api.models import PostCreate, PostStatus
+post = client.posts.create(PostCreate(
+    title="Hello World",
+    content="<p>My first post!</p>",
+    status=PostStatus.PUBLISH
+))
+
+# Get current user
+me = client.users.me()
+```
+
+## Features
+
+- **Full CRUD Support**: Posts, Pages, Media, Users, Comments, Categories, Tags
+- **Authentication**: Application Passwords, Basic Auth, JWT
+- **Type Safety**: Pydantic models for all WordPress objects
+- **Pagination**: Automatic iteration through all results
+- **Media Upload**: Upload files from path or file objects
+- **Custom Post Types**: Access any registered custom post type
+- **Block Editor**: Access block types and patterns
+- **Error Handling**: Typed exceptions for all API errors
+
+## Dependencies
+
+- httpx: Modern HTTP client
+- pydantic: Data validation using Python type annotations
+
+## Authentication Setup
+
+1. Go to your WordPress site
+2. Navigate to Users → Your Profile
+3. Scroll to "Application Passwords"
+4. Create a new application password
+5. Use it with `ApplicationPasswordAuth`

wp_python-0.1.3/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "wp_python"
+dynamic = ["version"]
+description = "A Python client for interacting with the WordPress REST API."
+readme = "README.md"
+authors = [
+    { name = "Andrew", email = "andrew.neher1@gmail.com"}
+]
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "hatch>=1.16.3",
+    "httpx>=0.28.1",
+    "pydantic>=2.12.5",
+    "pytest>=9.0.2",
+    "pytest-mock>=3.15.1",
+    "respx>=0.22.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wp_python"]
+
+[tool.hatch.build.targets.sdist]
+packages = ["src/wp_python"]
+
+[tool.hatch.version]
+path = "src/wp_python/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"

wp_python-0.1.3/wp_python/__init__.py

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

wp_python-0.1.3/wp_python/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