{"id":37072355,"url":"https://github.com/usimd/pyoekoboxonline","last_synced_at":"2026-01-14T08:29:40.886Z","repository":{"id":318757222,"uuid":"1074978756","full_name":"usimd/pyoekoboxonline","owner":"usimd","description":"Python client for API of Oekobox Online ERP SaaS","archived":false,"fork":false,"pushed_at":"2025-11-01T21:49:14.000Z","size":317,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-01T23:27:30.475Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usimd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"usimd"}},"created_at":"2025-10-12T20:45:02.000Z","updated_at":"2025-11-01T21:48:29.000Z","dependencies_parsed_at":"2025-10-15T06:19:56.471Z","dependency_job_id":"390befe8-e8c1-4d6c-8778-c858293971f8","html_url":"https://github.com/usimd/pyoekoboxonline","commit_stats":null,"previous_names":["usimd/pyoekoboxonline"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/usimd/pyoekoboxonline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usimd%2Fpyoekoboxonline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usimd%2Fpyoekoboxonline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usimd%2Fpyoekoboxonline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usimd%2Fpyoekoboxonline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usimd","download_url":"https://codeload.github.com/usimd/pyoekoboxonline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usimd%2Fpyoekoboxonline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414075,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:16:59.381Z","status":"ssl_error","status_checked_at":"2026-01-14T08:13:45.490Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T08:29:40.179Z","updated_at":"2026-01-14T08:29:40.872Z","avatar_url":"https://github.com/usimd.png","language":"Python","funding_links":["https://github.com/sponsors/usimd"],"categories":[],"sub_categories":[],"readme":"[![codecov](https://codecov.io/gh/usimd/pyoekoboxonline/graph/badge.svg?token=VDG1IFFZSL)](https://codecov.io/gh/usimd/pyoekoboxonline)\n[![PyPI](https://img.shields.io/pypi/v/pyoekoboxonline.svg)](https://pypi.org/project/pyoekoboxonline/)\n[![Python Version](https://img.shields.io/pypi/pyversions/pyoekoboxonline.svg)](https://pypi.org/project/pyoekoboxonline/)\n[![License](https://img.shields.io/pypi/l/pyoekoboxonline.svg)](https://pypi.org/project/pyoekoboxonline/)\n# Pyoekoboxonline\n\nA 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.\n\n\u003e **Note**: This library is designed to be compatible with Home Assistant custom integrations and uses `aiohttp` for HTTP requests.\n\n## Requirements\n\n- **Python 3.11+** - Modern Python features and performance improvements\n- **Async/await support** - Built with modern Python async patterns\n- **aiohttp** - Modern async HTTP client library\n\n## Features\n\n- **Type hints** - Full type annotation support with mypy\n- **Pydantic models** - Robust data validation and serialization\n- **Comprehensive error handling** - Detailed exception hierarchy\n- **Well tested** - High test coverage with pytest\n- **Production ready** - Follows Python packaging best practices\n- **External session support** - Compatible with Home Assistant's shared aiohttp session\n\n## Installation\n\n```bash\npip install pyoekoboxonline\n```\n\n**Note**: Requires Python 3.11 or higher.\n\n## Quick Start\n\n### Standard Usage\n\n```python\nimport asyncio\nfrom pyoekoboxonline import OekoboxClient\n\nasync def main():\n    # First, discover available shops\n    shops = await OekoboxClient.get_shop_info()\n    print(f\"Found {len(shops)} shops\")\n\n    # Connect to a specific shop\n    async with OekoboxClient(\n        shop_id=\"your_shop_id\",  # From shop list\n        username=\"your-username\",\n        password=\"your-password\"\n    ) as client:\n        # Login\n        await client.logon()\n\n        # Browse product categories\n        groups = await client.get_groups()\n        for group in groups:\n            print(f\"Category: {group.name}\")\n\n        # Browse products\n        items = await client.get_items()\n        for item in items:\n            print(f\"{item.name}: {item.price}\")\n\n        # Add items to cart\n        await client.add_to_cart(item_id=123, amount=2.0)\n\n        # View orders\n        orders = await client.get_orders()\n        for order in orders:\n            print(f\"Order {order.id}\")\n\n        # Logout\n        await client.logout()\n\nasyncio.run(main())\n```\n\n### Home Assistant Integration (External Session)\n\nFor Home Assistant integrations, you can pass an external `aiohttp.ClientSession`:\n\n```python\nimport aiohttp\nfrom pyoekoboxonline import OekoboxClient\n\nasync def setup_platform(hash, config, async_add_entities, discovery_info=None):\n    \"\"\"Set up the Ökobox Online integration.\"\"\"\n\n    # Use Home Assistant's shared session\n    session = hash.helpers.aiohttp_client.async_get_clientsession()\n\n    # Create client with external session\n    client = OekoboxClient(\n        shop_id=config[\"shop_id\"],\n        username=config[\"username\"],\n        password=config[\"password\"],\n        session=session,  # Pass the external session\n    )\n\n    # No need for context manager when using external session\n    await client.logon()\n\n    # Use the client...\n    # The session will be managed by Home Assistant\n```\n\n## API Reference\n\n### Client\n\n#### `OekoboxClient(shop_id, username, password, base_url=None, timeout=30.0, session=None)`\n\nThe main client class for interacting with the Ökobox Online API.\n\n**Parameters:**\n- `shop_id` (str): Shop identifier from the shop list\n- `username` (str): Your account username\n- `password` (str): Your account password\n- `base_url` (str, optional): Custom base URL (auto-detected from shop_id)\n- `timeout` (float, optional): Request timeout in seconds (default: 30.0)\n- `session` (aiohttp.ClientSession, optional): External aiohttp session (for Home Assistant integrations)\n\n### Shop Discovery\n\n#### `await OekoboxClient.get_available_shops() -\u003e List[Shop]`\n\nGet list of available Ökobox Online shops with location data.\n\n### Authentication\n\n#### `await client.login() -\u003e UserInfo`\n\nAuthenticate and establish session.\n\n#### `await client.logout()`\n\nClear session and logout.\n\n### Product Catalog\n\n#### `await client.get_groups() -\u003e List[Group]`\n\nGet product categories.\n\n#### `await client.get_items(group_id=None, subgroup_id=None) -\u003e List[Item]`\n\nGet available products, optionally filtered by category.\n\n#### `await client.search_items(query: str) -\u003e List[Item]`\n\nSearch for products by name or description.\n\n### Shopping Cart\n\n#### `await client.get_cart() -\u003e List[CartItem]`\n\nGet current cart contents.\n\n#### `await client.add_to_cart(item_id: str, quantity: float)`\n\nAdd item to cart.\n\n#### `await client.clear_cart()`\n\nClear all items from cart.\n\n### Orders\n\n#### `await client.get_orders() -\u003e List[Order]`\n\nGet customer's orders.\n\n#### `await client.create_order() -\u003e Order`\n\nCreate order from current cart.\n\n## Error Handling\n\n```python\nfrom pyoekoboxonline.exceptions import (\n    OekoboxAuthenticationError,\n    OekoboxConnectionError,\n    OekoboxAPIError\n)\n\ntry:\n    user = await client.login()\nexcept OekoboxAuthenticationError:\n    print(\"Invalid credentials\")\nexcept OekoboxConnectionError as e:\n    print(f\"Connection error: {e}\")\nexcept OekoboxAPIError as e:\n    print(f\"API error: {e.message} (status: {e.status_code})\")\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/usimd/pyoekoboxonline.git\ncd pyoekoboxonline\n\n# Install with uv (recommended) - requires Python 3.11+\nuv sync --dev\n\n# Or with pip\npip install -e \".[dev]\"\n```\n\n### Testing\n\n```bash\n# Run tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=src --cov-report=html\n```\n\n### Code Quality\n\n```bash\n# Run all pre-commit hooks (includes ruff, mypy, bandit, etc.)\nuv run pre-commit run --all-files\n\n# Install pre-commit hooks for automatic checking\nuv run pre-commit install\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusimd%2Fpyoekoboxonline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusimd%2Fpyoekoboxonline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusimd%2Fpyoekoboxonline/lists"}