itemdb

The itemdb library allows you to store and retrieve Python dicts in a database on the local filesystem, in an easy, fast, and reliable way.

Based on the rock-solid and ACID compliant SQLite, but with easy and explicit transactions using a with statement. It provides a simple object-based API, with the flexibility to store (JSON-compatible) items with arbitrary fields, and add indices when needed.

Originally developed as part of TimaTagger and MyPaaS.

Installation

pip install itemdb

Quick usage example

import itemdb

# Open the database and make sure there is a table with appopriate indices
db = itemdb.ItemDB(":memory:")
db.ensure_table("persons", "!name", "age")

# Add some items to the db
with db:
    db.put_one("persons", name="Jane", age=22)
    db.put_one("persons", name="John", age=18, fav_number=7)
    db.put("persons", {"name": "Guido"}, {"name": "Anne", "age": 42})

# Update an item
with db:
    db.put_one("persons", name="John", age=19, fav_number=8)

# Query items
db.count_all("persons")  # -> 4
db.select("persons", "age > ?", 20)  # -> list of 2 items

See the guide for details.

Async

The AsyncItemDB class provides the same API, but async:

import itemdb

db = await itemdb.AsyncItemDB(":memory:")
await db.ensure_table("persons", "!name", "age")

async with db:
    await db.put_one("persons", name="Jane", age=22)

...

Alternatively, a decorator is provided to turn a normal function into an async one (running in a separate thread).

@asycify
def your_db_interaction_logic(...):
    db = ItemDB(filename)
    ...

async def your_async_code(...):
    await your_db_interaction_logic(...)

License

MIT

Developers

• Run ruff format to autoformat.
• Run ruff check to lint.
• Run pytest tests to run unit tests.