grocy-py

A Python client library for the Grocy ERP system API.

Check out the documentation.

Installation

pip install grocy-py

Usage

from grocy import Grocy

grocy = Grocy("https://example.com", "GROCY_API_KEY")

With custom port and SSL options:

grocy = Grocy("https://example.com", "GROCY_API_KEY", port=9192, verify_ssl=True)

Get current stock:

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

Features

All features are accessed through manager objects on the Grocy instance:

Stability

From 1.0.0 this library follows semantic versioning.

What is covered. Everything exported from the grocy package — Grocy, the manager classes, EntityType, TransactionType — plus any name reachable through a submodule path that does not start with an underscore, such as the data models in grocy.data_models.

Within that surface:

• a major bump may remove or rename things, or change a signature incompatibly;
• a minor bump only adds;
• a patch bump only fixes behaviour.

What is not covered. GrocyApiClient and its _do_get_request / _do_post_request / _do_put_request / _do_delete_request methods are internal. They are deliberately not re-exported from the package root and may change in any release. If you find yourself reaching for them because the managers cannot express what you need, please open an issue — that is a gap worth filling with public API instead.

Development

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest

# Lint and format
uv run ruff check .
uv run ruff format .

# Build docs
uv run mkdocs serve

Support

If you need help using grocy check the discussions section. Feel free to create an issue for feature requests, bugs and errors in the library.