WTinyDB: Lightweight Pydantic Document Database Engine

wtinydb is a high-level, document-oriented NoSQL database abstraction built on top of TinyDB and Pydantic. It provides schema-validated CRUD operations, fluent query builders, async support, audit mixins, and command-line management for embedded Python applications.

Key Technologies & Libraries

• TinyDB: Pure Python document-oriented database storing records as JSON.
• Pydantic v2: Data validation, settings management, and JSON-schema document serialization.
• Pytest: Modern Python testing framework.
• Pytest-Cov: Code coverage measurement for pytest.
• Docker: Containerization for reproducible testing environments.

Features

• Enterprise Forensic Automation: Ghost table (_forensic_audit_log) audit trail for all document mutations (INSERT, UPDATE, DELETE).
• Multi-Table Manager & Registry: Multi-model registration with dictionary indexing app[User] and dynamic attribute dispatch app.user.
• Pydantic Model Mapping: Automatic serialization, deserialization, and schema validation.
• Fluent Query Builder (Q): Intuitive query building with comparison operators, regex matching, and text search.
• Async Support (AsyncWTinyDB): Non-blocking thread-pool execution for FastAPI and Starlette apps.
• Soft Delete & Audit Mixins: Built-in support for created_at, updated_at, is_deleted, and deleted_at.
• Thread Safety: Integrated reentrant locks for safe multi-threaded access.
• CLI Utility: Command-line tool wtinydb to inspect, count, and export JSON tables.

Quickstart Example

from pydantic import BaseModel, Field
from wtinydb import WTinyDB, Q, SoftDeleteMixin

# Define document schema
class User(SoftDeleteMixin, BaseModel):
    name: str
    email: str = Field(description="User email")
    age: int = 18

# Initialize WTinyDB repository (in-memory or file-backed)
db = WTinyDB(User, in_memory=True)

# 1. Insert
user = db.insert(User(name="Alice", email="alice@example.com", age=30))

# 2. Query
results = db.find(Q("age").gte("age", 25))

# 3. Soft Delete & Restore
db.delete(1, hard=False)

Running Unit Tests & Coverage

Local Pytest Execution

# Run pytest test suite
pytest tests/

# Calculate code coverage
./scripts/run_coverage.sh

Docker Containerized Test Execution

All unit tests can be executed inside an isolated Docker container:

./scripts/run_tests_docker.sh

Part of the wisrovi SUITE ecosystem.

👤 Autor & Afiliación Oficial

• William Steve Rodriguez Villamizar (Wisrovi)
• Cargo: Principal AI Engineer & Applied AI Solutions Architect | Scientific Researcher
• 📧 Email: wisrovi.rodriguez@gmail.com
• 🌐 Portal Oficial: wisrovi.dev
• 💼 LinkedIn: wisrovi-rodriguez
• 🆔 ORCID: 0009-0005-0710-1861
• 📦 PyPI: pypi.org/user/wisrovi/
• 🐙 GitHub: @wisrovi