https://github.com/usimd/pyoekoboxonline
Python client for API of Oekobox Online ERP SaaS
https://github.com/usimd/pyoekoboxonline
Last synced: 5 months ago
JSON representation
Python client for API of Oekobox Online ERP SaaS
- Host: GitHub
- URL: https://github.com/usimd/pyoekoboxonline
- Owner: usimd
- License: mit
- Created: 2025-10-12T20:45:02.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-11-01T21:49:14.000Z (7 months ago)
- Last Synced: 2025-11-01T23:27:30.475Z (7 months ago)
- Language: Python
- Size: 310 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://codecov.io/gh/usimd/pyoekoboxonline)
[](https://pypi.org/project/pyoekoboxonline/)
[](https://pypi.org/project/pyoekoboxonline/)
[](https://pypi.org/project/pyoekoboxonline/)
# Pyoekoboxonline
A Python client library for the [Ökobox Online](https://oekobox-online.de) 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 `aiohttp` for HTTP requests.
## Requirements
- **Python 3.11+** - Modern Python features and performance improvements
- **Async/await support** - Built with modern Python async patterns
- **aiohttp** - Modern async HTTP client library
## Features
- **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
## Installation
```bash
pip install pyoekoboxonline
```
**Note**: Requires Python 3.11 or higher.
## Quick Start
### Standard Usage
```python
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())
```
### Home Assistant Integration (External Session)
For Home Assistant integrations, you can pass an external `aiohttp.ClientSession`:
```python
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 Assistant
```
## API Reference
### Client
#### `OekoboxClient(shop_id, username, password, base_url=None, timeout=30.0, session=None)`
The main client class for interacting with the Ökobox Online API.
**Parameters:**
- `shop_id` (str): Shop identifier from the shop list
- `username` (str): Your account username
- `password` (str): Your account password
- `base_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)
### Shop Discovery
#### `await OekoboxClient.get_available_shops() -> List[Shop]`
Get list of available Ökobox Online shops with location data.
### Authentication
#### `await client.login() -> UserInfo`
Authenticate and establish session.
#### `await client.logout()`
Clear session and logout.
### Product Catalog
#### `await client.get_groups() -> List[Group]`
Get product categories.
#### `await client.get_items(group_id=None, subgroup_id=None) -> List[Item]`
Get available products, optionally filtered by category.
#### `await client.search_items(query: str) -> List[Item]`
Search for products by name or description.
### Shopping Cart
#### `await client.get_cart() -> List[CartItem]`
Get current cart contents.
#### `await client.add_to_cart(item_id: str, quantity: float)`
Add item to cart.
#### `await client.clear_cart()`
Clear all items from cart.
### Orders
#### `await client.get_orders() -> List[Order]`
Get customer's orders.
#### `await client.create_order() -> Order`
Create order from current cart.
## Error Handling
```python
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})")
```
## Development
### Setup
```bash
# 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]"
```
### Testing
```bash
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=src --cov-report=html
```
### Code Quality
```bash
# 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 install
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.