grocy-py

A Python client library for the Grocy ERP system API.

grocy provides a clean, typed Python interface to manage your household inventory — products, stock, shopping lists, chores, tasks, batteries, equipment, meal plans, and more.

Quick Example

from grocy import Grocy

grocy = Grocy("https://your-grocy-instance.com", "YOUR_API_KEY")

# Get current stock
for product in grocy.stock.current():
    print(f"{product.name}: {product.available_amount} in stock")

# Get overdue products
for product in grocy.stock.overdue_products():
    print(f"{product.name} is overdue!")

# Manage shopping list
shopping_list = grocy.shopping_list.items(get_details=True)
for item in shopping_list:
    print(f"{item.product.name}: {item.amount}")

Features

• Stock — query, add, consume, open, transfer, and inventory products
• Shopping lists — view, add/remove products, bulk operations
• Chores — list, execute, undo, and assign chores
• Tasks — manage and complete tasks
• Batteries — track battery charge cycles
• Equipment — manage household equipment
• Recipes — get details, check fulfillment, consume
• Meal plans — view meal plans and sections
• Users — manage user accounts and settings
• System — server info, time, and configuration
• Calendar — iCalendar export and sharing
• Files — upload, download, and delete files
• Generic CRUD — create, read, update, delete any entity type

Architecture Overview

grocy
├── Grocy              # High-level client (you use this)
├── GrocyApiClient     # Low-level HTTP API wrapper
├── Data Models        # Rich domain objects (Product, Chore, Task, ...)
├── API Responses      # Pydantic models for raw API responses
├── Enums              # EntityType, TransactionType, etc.
└── Errors             # GrocyError exception

Layer	Purpose
Grocy	Main entry point. Methods return rich data model objects.
GrocyApiClient	Handles HTTP requests/responses. Returns Pydantic response models.
Data Models	Domain classes like Product, Chore, Task with properties.
API Responses	Pydantic BaseModel classes for JSON deserialization.
Enums	EntityType, TransactionType, PeriodType, etc.
Errors	GrocyError raised on HTTP 4xx/5xx responses.