A Python client library for the Ökobox Online e-commerce REST API. This library provides an easy-to-use, async interface for interacting with organic food delivery and subscription services.
Note: This library is designed to be compatible with Home Assistant custom integrations and uses
aiohttpfor HTTP requests.
- Python 3.11+ - Modern Python features and performance improvements
- Async/await support - Built with modern Python async patterns
- aiohttp - Modern async HTTP client library
- Type hints - Full type annotation support with mypy
- Pydantic models - Robust data validation and serialization
- Comprehensive error handling - Detailed exception hierarchy
- Well tested - High test coverage with pytest
- Production ready - Follows Python packaging best practices
- External session support - Compatible with Home Assistant's shared aiohttp session
pip install pyoekoboxonlineNote: Requires Python 3.11 or higher.
import asyncio
from pyoekoboxonline import OekoboxClient
async def main():
# First, discover available shops
shops = await OekoboxClient.get_shop_info()
print(f"Found {len(shops)} shops")
# Connect to a specific shop
async with OekoboxClient(
shop_id="your_shop_id", # From shop list
username="your-username",
password="your-password"
) as client:
# Login
await client.logon()
# Browse product categories
groups = await client.get_groups()
for group in groups:
print(f"Category: {group.name}")
# Browse products
items = await client.get_items()
for item in items:
print(f"{item.name}: {item.price}")
# Add items to cart
await client.add_to_cart(item_id=123, amount=2.0)
# View orders
orders = await client.get_orders()
for order in orders:
print(f"Order {order.id}")
# Logout
await client.logout()
asyncio.run(main())For Home Assistant integrations, you can pass an external aiohttp.ClientSession:
import aiohttp
from pyoekoboxonline import OekoboxClient
async def setup_platform(hash, config, async_add_entities, discovery_info=None):
"""Set up the Ökobox Online integration."""
# Use Home Assistant's shared session
session = hash.helpers.aiohttp_client.async_get_clientsession()
# Create client with external session
client = OekoboxClient(
shop_id=config["shop_id"],
username=config["username"],
password=config["password"],
session=session, # Pass the external session
)
# No need for context manager when using external session
await client.logon()
# Use the client...
# The session will be managed by Home AssistantThe main client class for interacting with the Ökobox Online API.
Parameters:
shop_id(str): Shop identifier from the shop listusername(str): Your account usernamepassword(str): Your account passwordbase_url(str, optional): Custom base URL (auto-detected from shop_id)timeout(float, optional): Request timeout in seconds (default: 30.0)session(aiohttp.ClientSession, optional): External aiohttp session (for Home Assistant integrations)
Get list of available Ökobox Online shops with location data.
Authenticate and establish session.
Clear session and logout.
Get product categories.
Get available products, optionally filtered by category.
Search for products by name or description.
Get current cart contents.
Add item to cart.
Clear all items from cart.
Get customer's orders.
Create order from current cart.
from pyoekoboxonline.exceptions import (
OekoboxAuthenticationError,
OekoboxConnectionError,
OekoboxAPIError
)
try:
user = await client.login()
except OekoboxAuthenticationError:
print("Invalid credentials")
except OekoboxConnectionError as e:
print(f"Connection error: {e}")
except OekoboxAPIError as e:
print(f"API error: {e.message} (status: {e.status_code})")# Clone the repository
git clone https://github.com/usimd/pyoekoboxonline.git
cd pyoekoboxonline
# Install with uv (recommended) - requires Python 3.11+
uv sync --dev
# Or with pip
pip install -e ".[dev]"# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=src --cov-report=html# Run all pre-commit hooks (includes ruff, mypy, bandit, etc.)
uv run pre-commit run --all-files
# Install pre-commit hooks for automatic checking
uv run pre-commit installThis project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.