Metadata-Version: 2.4
Name: ScoloDB
Version: 0.1.0
Summary: Async-first SQLite storage for Python bots and services.
Author: G3tFun
License-Expression: MIT
Project-URL: Homepage, https://github.com/G3tFun/ScoloDB
Project-URL: Repository, https://github.com/G3tFun/ScoloDB
Project-URL: Documentation, https://github.com/G3tFun/ScoloDB#readme
Project-URL: Issues, https://github.com/G3tFun/ScoloDB/issues
Keywords: sqlite,database,asyncio,storage,telegram-bot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ScoloLogger<0.2,>=0.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# ScoloDB

ScoloDB is an async-first SQLite key-value store for bots and small Python services. It stores JSON-compatible values locally, uses SQLite WAL mode, supports TTL, atomic counters, and transactions, and requires no database server.

## Installation

```bash
pip install ScoloDB
```

## Quick start

```python
import asyncio
from scolodb import ScoloDB

async def main() -> None:
    async with ScoloDB('bot.sqlite3') as db:
        await db.set('users', '42', {'language': 'ru'})
        user = await db.get('users', '42')
        print(user['language'])

asyncio.run(main())
```

A namespace is required for every key. It keeps unrelated data separate without requiring multiple database files.

## TTL cache

```python
await db.set('cache', 'weather:moscow', {'temperature': 18}, ttl=300)
weather = await db.get('cache', 'weather:moscow')
```

Expired values behave as missing and are removed during reads, scans, or `purge_expired()`.

## Atomic counters

```python
messages = await db.increment('metrics', 'messages')
```

`increment()` is serialised through the database lock, so concurrent asyncio tasks cannot lose updates.

## Transactions

```python
async with db.transaction() as transaction:
    await transaction.set('order', '42:status', 'paid')
    await transaction.set('order', '42:receipt_sent', True)
```

An exception inside the block rolls back every write from that transaction.

## Logging

ScoloDB depends on ScoloLogger for optional structured operation events. It never configures logging automatically. Applications that need diagnostics can configure ScoloLogger themselves:

```python
from scolologger import configure

configure(level='DEBUG')
```

Stored values and keys are not placed in log events.

## Limits

ScoloDB 0.1.0 targets one process and a local SQLite file. It is not a replacement for PostgreSQL, Redis, or a distributed database. Values must be JSON-compatible.

## License

MIT.
