Metadata-Version: 2.4
Name: wp-connector-2
Version: 0.1.2
Summary: Python SDK for the WordPress REST API.
Project-URL: Homepage, https://github.com/IslamIbrahimAIM/wp-connector
Project-URL: Repository, https://github.com/IslamIbrahimAIM/wp-connector
Project-URL: Issues, https://github.com/IslamIbrahimAIM/wp-connector/issues
Project-URL: Changelog, https://github.com/IslamIbrahimAIM/wp-connector/blob/main/CHANGELOG.md
Author-email: Islam Ibrahim <islam@growthfactors.ae>
License: MIT
License-File: LICENSE
Keywords: api-client,headless,rest,sdk,wordpress,wordpress-rest-api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: python-decouple>=3.8
Requires-Dist: requests>=2.31
Requires-Dist: urllib3>=1.26
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install wp-connector-2
```

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

```python
from wp_connector import WordPressClient, BasicAuth
```

For development:

```bash
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

```python
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

```python
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

```bash
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

```bash
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):

```python
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

```python
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

```python
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

```bash
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](LICENSE).
