plentymarkets-api-client 0.1.2

Async Python client for the PlentyMarkets REST API

pyPlentyAPI

Async Python client for the PlentyMarkets REST API.

Features

• Async-first: Built on httpx.AsyncClient for high-performance async/await support.
• Lazy-loaded modules: Access orders, items, stock, and contacts as properties of PlentyClient.
• Auto-refreshing auth: Tokens are refreshed automatically when within 60 seconds of expiry.
• Comprehensive error handling: Custom exceptions for HTTP status codes (e.g., NotFoundError, RateLimitError).
• Pagination support: Async generators for iterating across all pages of results.
• Type hints: Full type annotations for IDE support and static analysis.

Installation

pip install plentymarkets-api-client

Or with uv:

uv add plentymarkets-api-client

Quickstart

import asyncio
from plentymarkets import PlentyClient

async def main():
    async with PlentyClient(username="your_username", password="your_password") as client:
        # Fetch an order by ID
        order = await client.orders.get(123)
        print(order)
        
        # List all items (paginated)
        async for item in client.items.paginate_items():
            print(item)

asyncio.run(main())

Modules

Module	Description	Key Methods
Orders	Manage orders and order statuses.	get(), list(), create(), update_status(), paginate_orders()
Items	Manage items and item variants.	get(), list(), create(), update(), paginate_items()
Stock	Manage stock across warehouses.	get_by_warehouse(), correct(), paginate_stock()
Contacts	Manage customer and supplier data.	get(), list(), create(), update(), paginate_contacts()

Authentication

1. Initialize PlentyClient with your PlentyMarkets username and password.
2. The client automatically logs in and manages the accessToken lifecycle.
3. Tokens are sent as Authorization: Bearer <token> in all requests.
4. If a 401 error occurs, the client attempts to re-login once before failing.

Error Handling

Custom exceptions are raised for HTTP errors:

• AuthError: 401 Unauthorized
• NotFoundError: 404 Not Found
• RateLimitError: 429 Too Many Requests
• ServerError: 5xx Server Errors
• ConnectionError: Network failures

Example:

try:
    order = await client.orders.get(99999)
except plentymarkets.NotFoundError:
    print("Order not found")
except plentymarkets.RateLimitError:
    print("Rate limit exceeded")

Pagination

Use async generators to iterate across all pages:

async for order in client.orders.paginate_orders():
    print(order)

Development

Setup

uv sync --extra dev
uv run pre-commit install --hook-type commit-msg

Running Tests

uv run pytest                        # Unit tests
uv run pytest -m integration         # Integration tests (requires live credentials)

License

MIT