{"id":27840174,"url":"https://github.com/innerkorehq/wp-api-client","last_synced_at":"2025-09-11T01:45:48.633Z","repository":{"id":290617176,"uuid":"975061930","full_name":"innerkorehq/wp-api-client","owner":"innerkorehq","description":"Python client for the WordPress REST API","archived":false,"fork":false,"pushed_at":"2025-04-29T18:43:49.000Z","size":0,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-29T18:52:53.489Z","etag":null,"topics":["wordpress","wordpress-api","wordpress-api-v2","wp-api"],"latest_commit_sha":null,"homepage":"https://wp-api-client.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/innerkorehq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-29T18:10:39.000Z","updated_at":"2025-04-29T18:48:43.000Z","dependencies_parsed_at":"2025-04-29T18:52:57.185Z","dependency_job_id":"11da0d93-0866-47a6-96e7-631e16982dbf","html_url":"https://github.com/innerkorehq/wp-api-client","commit_stats":null,"previous_names":["innerkorehq/wp-api-client"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innerkorehq%2Fwp-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innerkorehq%2Fwp-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innerkorehq%2Fwp-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innerkorehq%2Fwp-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/innerkorehq","download_url":"https://codeload.github.com/innerkorehq/wp-api-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252140331,"owners_count":21700752,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["wordpress","wordpress-api","wordpress-api-v2","wp-api"],"created_at":"2025-05-03T03:40:58.695Z","updated_at":"2025-05-03T03:41:03.788Z","avatar_url":"https://github.com/innerkorehq.png","language":"Python","readme":"# WordPress REST API Python Client\n\nA comprehensive Python library for interacting with the WordPress REST API.\n\n## Features\n\n- Complete support for WordPress REST API endpoints\n- Multiple authentication methods (Application Passwords, Basic Auth, OAuth1)\n- Intuitive interface for common WordPress operations (posts, pages, media, etc.)\n- Support for custom taxonomies and post types\n- Custom fields (post meta) management\n- Robust error handling with specific exception types\n- Full typing support for better IDE integration\n- Automatic retries for failed requests\n- Comprehensive documentation\n\n## Installation\n\n```bash\npip install wp-api-client\n```\n\n## Quick Start\n\n```python\nfrom wp_api import WPClient\nfrom wp_api.auth import ApplicationPasswordAuth\n\n# Initialize client with Application Password authentication\nauth = ApplicationPasswordAuth(username=\"your_username\", app_password=\"your_app_password\")\nclient = WPClient(base_url=\"https://your-wordpress-site.com\", auth=auth) #auth is optional\n\n# Get all published posts\nposts = client.posts.list(status=\"publish\")\nfor post in posts:\n    print(f\"Post ID: {post['id']}, Title: {post['title']['rendered']}\")\n\n# Create a new post\nnew_post = client.posts.create(\n    title=\"Hello World\",\n    content=\"This is my first post created with the WordPress REST API Python client!\",\n    status=\"publish\"\n)\n```\n\n## Authentication Methods\n\n### Application Passwords (Recommended for WordPress 5.6+)\n\n```python\nfrom wp_api import WPClient\nfrom wp_api.auth import ApplicationPasswordAuth\n\nauth = ApplicationPasswordAuth(username=\"your_username\", app_password=\"your_app_password\")\nclient = WPClient(base_url=\"https://your-wordpress-site.com\", auth=auth)\n```\n\n### Basic Authentication\n\n```python\nfrom wp_api import WPClient\nfrom wp_api.auth import BasicAuth\n\nauth = BasicAuth(username=\"your_username\", password=\"your_password\")\nclient = WPClient(base_url=\"https://your-wordpress-site.com\", auth=auth)\n```\n\n### OAuth1 Authentication\n\n```python\nfrom wp_api import WPClient\nfrom wp_api.auth import OAuth1\n\nauth = OAuth1(\n    consumer_key=\"your_consumer_key\",\n    consumer_secret=\"your_consumer_secret\",\n    token=\"your_token\",\n    token_secret=\"your_token_secret\"\n)\nclient = WPClient(base_url=\"https://your-wordpress-site.com\", auth=auth)\n```\n\n## API Endpoints\n\nThe library provides convenient access to various WordPress REST API endpoints:\n\n### Posts\n\n```python\n# List posts with filtering\nrecent_posts = client.posts.list(\n    per_page=5,\n    status=\"publish\",\n    orderby=\"date\",\n    order=\"desc\"\n)\n\n# Get a specific post\npost = client.posts.get(123)\n\n# Create a new post\nnew_post = client.posts.create(\n    title=\"My New Post\",\n    content=\"This is the content of my post.\",\n    status=\"publish\",\n    categories=[5, 7],\n    tags=[12, 15]\n)\n\n# Update a post\nupdated_post = client.posts.update(\n    123,\n    title=\"Updated Title\",\n    content=\"Updated content\"\n)\n\n# Delete a post\nclient.posts.delete(123)\n\n# Get post revisions\nrevisions = client.posts.get_revisions(123)\n```\n\n### Pages\n\n```python\n# List pages\npages = client.pages.list()\n\n# Get a specific page\npage = client.pages.get(45)\n\n# Create a new page\nnew_page = client.pages.create(\n    title=\"About Us\",\n    content=\"\u003ch2\u003eOur Story\u003c/h2\u003e\u003cp\u003eThis is our company story...\u003c/p\u003e\",\n    status=\"publish\"\n)\n\n# Update a page\nupdated_page = client.pages.update(\n    45,\n    title=\"Updated About Us\",\n    content=\"\u003ch2\u003eOur Updated Story\u003c/h2\u003e\u003cp\u003eNew content here...\u003c/p\u003e\"\n)\n\n# Delete a page\nclient.pages.delete(45)\n```\n\n### Media\n\n```python\n# List media items\nmedia_items = client.media.list()\n\n# Get a specific media item\nmedia = client.media.get(67)\n\n# Upload a new image\nwith open(\"image.jpg\", \"rb\") as image_file:\n    media = client.media.upload(\n        image_file,\n        file_name=\"my-image.jpg\",\n        title=\"My Image\",\n        alt_text=\"Description of my image\"\n    )\n\n# Update media item\nupdated_media = client.media.update(\n    67,\n    title=\"Updated Image Title\",\n    alt_text=\"Updated alternative text\"\n)\n\n# Delete media item\nclient.media.delete(67)\n```\n\n### Users\n\n```python\n# List users\nusers = client.users.list()\n\n# Get the current user\nme = client.users.me()\n\n# Get a specific user\nuser = client.users.get(2)\n\n# Create a user (requires appropriate permissions)\nnew_user = client.users.create(\n    username=\"newuser\",\n    email=\"new.user@example.com\",\n    password=\"secure_password\",\n    roles=[\"author\"]\n)\n\n# Update a user\nupdated_user = client.users.update(\n    2,\n    first_name=\"John\",\n    last_name=\"Doe\"\n)\n```\n\n### Categories\n\n```python\n# List categories\ncategories = client.categories.list()\n\n# Get a specific category\ncategory = client.categories.get(5)\n\n# Create a category\nnew_category = client.categories.create(\n    name=\"Technology\",\n    description=\"Tech-related posts\"\n)\n\n# Update a category\nupdated_category = client.categories.update(\n    5,\n    name=\"Updated Category Name\"\n)\n\n# Delete a category\nclient.categories.delete(5)\n```\n\n### Tags\n\n```python\n# List tags\ntags = client.tags.list()\n\n# Get a specific tag\ntag = client.tags.get(12)\n\n# Create a tag\nnew_tag = client.tags.create(\n    name=\"WordPress\",\n    description=\"Posts about WordPress\"\n)\n\n# Update a tag\nupdated_tag = client.tags.update(\n    12,\n    description=\"Updated tag description\"\n)\n\n# Delete a tag\nclient.tags.delete(12)\n```\n\n### Comments\n\n```python\n# List comments\ncomments = client.comments.list()\n\n# Get comments for a specific post\npost_comments = client.comments.list(post=123)\n\n# Get a specific comment\ncomment = client.comments.get(78)\n\n# Create a comment\nnew_comment = client.comments.create(\n    post=123,\n    content=\"This is a comment on the post.\",\n    author_name=\"John Doe\",\n    author_email=\"john@example.com\"\n)\n\n# Update a comment\nupdated_comment = client.comments.update(\n    78,\n    content=\"Updated comment text\"\n)\n\n# Delete a comment\nclient.comments.delete(78)\n```\n\n### Taxonomies\n\n```python\n# Get all taxonomies\ntaxonomies = client.taxonomies.list()\n\n# Get a specific taxonomy\ntaxonomy = client.taxonomies.get(\"category\")\n\n# Work with a custom taxonomy\nproduct_categories = client.get_custom_taxonomy(\"product_cat\")\nproduct_terms = product_categories.list()\n```\n\n### Custom Post Types\n\n```python\n# Get custom post type handler\nproducts = client.get_custom_post_type(\"product\")\n\n# List products\nall_products = products.list(per_page=20)\n\n# Get a specific product\nproduct = products.get(123)\n\n# Create a product\nnew_product = products.create(\n    title=\"New Product\",\n    status=\"publish\",\n    regular_price=\"19.99\"  # Custom field\n)\n\n# Get custom fields for products\nproduct_meta = products.get_meta()\n```\n\n### Custom Fields (Post Meta)\n\n```python\n# Get custom fields handler for posts\npost_meta = client.get_custom_fields(\"posts\")\n\n# Get all meta for a post\nall_meta = post_meta.get_all(123)\n\n# Get a specific meta value\nmeta_value = post_meta.get(123, \"meta_key\")\n\n# Create a new meta field\nnew_meta = post_meta.create(123, \"meta_key\", \"meta_value\")\n\n# Update or create a meta field\nmeta = post_meta.update_or_create(123, \"meta_key\", \"new_value\")\n\n# Delete a meta field\npost_meta.delete(123, meta_id=456)\n```\n\n### Settings\n\n```python\n# Get all settings\nsettings = client.settings.get()\n\n# Update settings\nupdated_settings = client.settings.update(\n    title=\"My Site Title\",\n    description=\"My site tagline\"\n)\n```\n\n### Block Patterns (WordPress 5.8+)\n\n```python\n# Get all block patterns\npatterns = client.block_patterns.list()\n\n# Get block pattern categories\npattern_categories = client.block_patterns.get_categories()\n```\n\n## Error Handling\n\nThe library provides specific exception types for different error scenarios:\n\n```python\nfrom wp_api import WPClient\nfrom wp_api.auth import ApplicationPasswordAuth\nfrom wp_api.exceptions import (\n    WPAPIError,             # Base exception for all WP API errors\n    WPAPIAuthError,         # Authentication errors\n    WPAPIRequestError,      # General request errors\n    WPAPIRateLimitError,    # Rate limiting (429)\n    WPAPINotFoundError,     # Resource not found (404)\n    WPAPIPermissionError,   # Permission denied (401, 403)\n    WPAPIValidationError,   # Validation errors (400)\n    WPAPIBadRequestError,   # Bad request errors (400)\n    WPAPIServerError,       # Server errors (500+)\n    WPAPITimeoutError,      # Request timeout\n    WPAPIConnectionError    # Connection error\n)\n\ntry:\n    auth = ApplicationPasswordAuth(username=\"your_username\", app_password=\"your_app_password\")\n    client = WPClient(base_url=\"https://your-wordpress-site.com\", auth=auth)\n    \n    # Try to access a resource\n    post = client.posts.get(999999)  # Non-existent post ID\n    \nexcept WPAPIAuthError as e:\n    print(f\"Authentication error: {e}\")\n    \nexcept WPAPIPermissionError as e:\n    print(f\"Permission denied: {e}\")\n    \nexcept WPAPINotFoundError as e:\n    print(f\"Resource not found: {e}\")\n    \nexcept WPAPIRateLimitError as e:\n    print(f\"Rate limit exceeded: {e}\")\n    \nexcept WPAPIServerError as e:\n    print(f\"Server error: {e}\")\n    print(f\"Status code: {e.status_code}\")\n    \nexcept WPAPIValidationError as e:\n    print(f\"Validation error: {e}\")\n    print(f\"Error details: {e.error_data}\")\n    \nexcept WPAPIRequestError as e:\n    print(f\"Request error: {e}\")\n    print(f\"Status code: {e.status_code}\")\n    \nexcept WPAPIError as e:\n    print(f\"WordPress API error: {e}\")\n```\n\nThe library also maps specific WordPress REST API error codes to appropriate exception types.\n\n## Advanced Usage\n\n### Configuring Request Retries\n\n```python\n# Configure client with retry settings\nclient = WPClient(\n    base_url=\"https://your-wordpress-site.com\",\n    auth=auth,\n    timeout=30,              # 30 second timeout\n    retry_count=3,           # Retry failed requests 3 times\n    retry_backoff_factor=0.5 # Increase wait time between retries\n)\n```\n\n### Discovering API Endpoints\n\n```python\n# Discover available endpoints\nendpoints = client.discover_endpoints()\n```\n\n### Custom Request Parameters\n\nAll endpoint methods accept additional parameters that will be passed to the API request:\n\n```python\n# Pass custom parameters to the API\nposts = client.posts.list(\n    status=\"publish\",\n    custom_param=\"value\"\n)\n```\n\n## Development\n\n### Setting Up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/username/wp-api-client.git\ncd wp-api-client\n\n# Create a virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install development dependencies\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run tests with coverage report\npytest --cov=wp_api tests/\n\n# Run tests across multiple Python versions\ntox\n```\n\n### Building Documentation\n\n```bash\n# Build documentation\nmake docs\n```\n\n### Building and Publishing\n\n```bash\n# Create distribution\nmake dist\n\n# Publish to PyPI\nmake release\n```\n\n## API Reference\n\nFor a complete API reference, see the detailed [API Documentation](https://wp-api-client.readthedocs.io/).\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgements\n\n- WordPress REST API documentation: https://developer.wordpress.org/rest-api/\n- The requests library: https://requests.readthedocs.io/","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnerkorehq%2Fwp-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finnerkorehq%2Fwp-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnerkorehq%2Fwp-api-client/lists"}