Metadata-Version: 2.1
Name: itemdb
Version: 1.3.0
Summary: Easy transactional database for Python dicts, backed by SQLite
Keywords: database,sqlite,no-sql
Author: Almar Klein
Requires-Python: >= 3.7
Description-Content-Type: text/markdown
Requires-Dist: itemdb[lint,tests, docs] ; extra == "dev"
Requires-Dist: sphinx ; extra == "docs"
Requires-Dist: sphinx_rtd_theme ; extra == "docs"
Requires-Dist: ruff ; extra == "lint"
Requires-Dist: pytest ; extra == "tests"
Project-URL: Documentation, http://itemdb.readthedocs.io
Project-URL: Homepage, https://github.com/almarklein/itemdb
Project-URL: Repository, https://github.com/almarklein/itemdb
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: lint
Provides-Extra: tests

[![PyPI Version](https://img.shields.io/pypi/v/itemdb.svg)](https://pypi.python.org/pypi/itemdb/)
[![CI](https://github.com/almarklein/itemdb/workflows/CI/badge.svg)](https://github.com/almarklein/itemdb/actions)
[![Documentation Status](https://readthedocs.org/projects/itemdb/badge/?version=latest)](https://itemdb.readthedocs.io/en/latest/?badge=latest)

# 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](https://timetagger.app)
and [MyPaaS](https://github.com/almarklein/mypaas).


## Installation

```
pip install itemdb
```


## Quick usage example

```py
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](https://itemdb.readthedocs.io/en/latest/guide.html) for details.


## Async

The `AsyncItemDB` class provides the same API, but async:

```py
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).

```py

@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.

