wp-connector-2 0.1.2

Python SDK for the WordPress REST API.

wp_connector

Python SDK for the WordPress REST API.

What it does

• Layered transport, auth, config, retry, and rate limiting (core/).
• Route discovery and plugin detection (discovery/).
• CRUD services for posts, categories, tags, and media (resources/).
• Typed schemas for the common WP record types (schemas/).
• Adapters and a sync engine contract for cross-system sync (adapters/, sync/).
• An integration tester that probes a live site and reports per-route classification (testing/).

The transport layer wraps requests.Session with connection pooling, configurable retry/backoff, optional rate limiting, and request logging that redacts credential headers. WordPressClient itself depends only on an HttpClientInterface, so the transport can be swapped without touching anything else.

Installation

pip install wp-connector-2

The Python import name is wp_connector (matches the package contents):

from wp_connector import WordPressClient, BasicAuth

For development:

git clone https://github.com/IslamIbrahimAIM/wp-connector.git
cd wp-connector
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"

Configuration

Copy .env.example to .env and set:

• WP_SITE_URL: your WordPress site (e.g. https://example.com).
• WP_USERNAME: WP user.
• WP_APP_PASSWORD: Application Password (Users -> Profile -> Application Passwords). Spaces are part of the value.
• WP_TEST_LIMIT: optional, max routes the integration tester probes.

The SDK only reads from env via WordPressConfig.from_env(). Construct a config explicitly to load from any other source.

Quick start

from wp_connector import (
    BasicAuth, PostService, RetryConfig,
    SessionHttpClient, WordPressClient, WordPressConfig,
)

config = WordPressConfig.from_env()
auth = BasicAuth(config.username, config.app_password)
http = SessionHttpClient(timeout=10, retry_config=RetryConfig())
client = WordPressClient(config, http, auth)

posts = PostService(client)
for post in posts.paginate(per_page=100):
    print(post["id"], post["slug"])

Authentication

from wp_connector import BasicAuth

BasicAuth(username, app_password) produces a Basic auth header. Implement another WordPressAuth subclass for JWT, OAuth, or anything else; the rest of the SDK is unchanged.

Running discovery against a live site

python -m wp_connector.main

Runs the full integration tester: authentication check, namespace dump, plugin detection, post types, taxonomies, dynamic route classification (OK / AUTH_REQUIRED / REQUIRES_PARAMS / INVALID_METHOD / SERVER_ERROR / UNSUPPORTED), postable route survey, and read-only validation of PostService / CategoryService / TagService.

CLI

wp-connector test-auth
wp-connector discover-routes
wp-connector detect-features
wp-connector list-posts --limit 10
wp-connector list-post-types
wp-connector list-taxonomies

Each command builds the same wiring used by main.py and emits JSON for piping (| jq ...).

Generic resources

For arbitrary endpoints (custom post types, plugin endpoints, WooCommerce, Elementor, ACF):

from wp_connector import ResourceFactory

factory = ResourceFactory(client)
products = factory.resource("/wc/v3/products")        # WooCommerce
templates = factory.resource("/elementor/v1/globals") # Elementor
skills = factory.resource("/wp/v2/skill")             # custom post type

The returned object is a BaseResource with list/retrieve/create/update/delete/paginate.

Discovering custom post types and taxonomies dynamically

from wp_connector import (
    CustomPostTypeRegistry, ResourceFactory,
    RouteDiscoveryService, TaxonomyRegistry,
)

discovery = RouteDiscoveryService(client)
factory = ResourceFactory(client)

cpt_registry = CustomPostTypeRegistry(discovery, factory)
for slug in cpt_registry.list_rest_enabled():
    resource = cpt_registry.get_resource(slug)
    # use resource like any BaseResource

tax_registry = TaxonomyRegistry(discovery, factory)

Uploading media

from wp_connector import MediaService

media = MediaService(client)
result = media.upload_file(
    "/path/to/image.png",
    title="Cover image",
    alt_text="A descriptive alt text",
)
print(result["source_url"])

Tests

pytest tests/

All tests run offline against mocks; no live WordPress site required.

Cross-system sync

The adapters/ and sync/ packages provide the seams for syncing WP content into another system (CRM, ERP, custom database):

• RecordAdapter: abstract WP-to-external mapping. Subclass and implement to_external / from_external for your target schema. The SDK ships WordPressIdentityAdapter as a pass-through default.
• SyncEngine: abstract runner composed of a resource, an adapter, and a SyncState bookmark. Subclass with your own persistence and scheduling layer.
• Reporter: write integration-tester output anywhere (stdout, app log table, structured event stream). The SDK ships ConsoleReporter.

License

MIT. See LICENSE.