wtinydb 0.1.0__tar.gz

wtinydb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wtinydb-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: wtinydb
+Version: 0.1.0
+Summary: Pydantic-powered document database abstraction layer on top of TinyDB
+Author-email: "WILLIAM R." <william@ecapturedtech.com>
+License: MIT
+Keywords: tinydb,pydantic,nosql,document-database,orm,database
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tinydb>=4.8.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# 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](https://tinydb.readthedocs.io/)**: Pure Python document-oriented database storing records as JSON.
+- **[Pydantic v2](https://docs.pydantic.dev/)**: Data validation, settings management, and JSON-schema document serialization.
+- **[Pytest](https://docs.pytest.org/)**: Modern Python testing framework.
+- **[Pytest-Cov](https://pytest-cov.readthedocs.io/)**: Code coverage measurement for pytest.
+- **[Docker](https://www.docker.com/)**: Containerization for reproducible testing environments.
+
+---
+
+## Features
+
+- **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
+
+```python
+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
+
+```bash
+# 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:
+
+```bash
+./scripts/run_tests_docker.sh
+```
+
+---
+
+*Part of the wisrovi SUITE ecosystem.*

wtinydb-0.1.0/README.md

@@ -0,0 +1,75 @@
+# 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](https://tinydb.readthedocs.io/)**: Pure Python document-oriented database storing records as JSON.
+- **[Pydantic v2](https://docs.pydantic.dev/)**: Data validation, settings management, and JSON-schema document serialization.
+- **[Pytest](https://docs.pytest.org/)**: Modern Python testing framework.
+- **[Pytest-Cov](https://pytest-cov.readthedocs.io/)**: Code coverage measurement for pytest.
+- **[Docker](https://www.docker.com/)**: Containerization for reproducible testing environments.
+
+---
+
+## Features
+
+- **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
+
+```python
+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
+
+```bash
+# 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:
+
+```bash
+./scripts/run_tests_docker.sh
+```
+
+---
+
+*Part of the wisrovi SUITE ecosystem.*

wtinydb-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wtinydb"
+version = "0.1.0"
+description = "Pydantic-powered document database abstraction layer on top of TinyDB"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "WILLIAM R.", email = "william@ecapturedtech.com"}
+]
+keywords = ["tinydb", "pydantic", "nosql", "document-database", "orm", "database"]
+dependencies = [
+    "tinydb>=4.8.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.scripts]
+wtinydb = "wtinydb.cli.main:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

wtinydb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wtinydb-0.1.0/tests/test_async.py

@@ -0,0 +1,50 @@
+"""Unit tests for AsyncWTinyDB async database wrapper.
+
+Validates non-blocking async CRUD operations.
+"""
+
+from pydantic import BaseModel
+import pytest
+
+from wtinydb import AsyncWTinyDB, WTinyDB
+
+
+class Item(BaseModel):
+    """Pydantic model for async testing."""
+
+    name: str
+    quantity: int
+
+
+@pytest.mark.asyncio
+async def test_async_crud_operations():
+    """Validates asynchronous insert, get, update, count, and delete operations."""
+    sync_db = WTinyDB(Item, in_memory=True)
+    async_db = AsyncWTinyDB(sync_db)
+
+    # Async insert
+    inserted = await async_db.insert(Item(name="Widget", quantity=10))
+    assert inserted.name == "Widget"
+
+    # Async count
+    cnt = await async_db.count()
+    assert cnt == 1
+
+    # Async get
+    retrieved = await async_db.get(1)
+    assert retrieved.quantity == 10
+
+    # Async update
+    updated = await async_db.update(1, {"quantity": 15})
+    assert updated.quantity == 15
+
+    # Async get_all
+    all_items = await async_db.get_all()
+    assert len(all_items) == 1
+
+    # Async delete
+    deleted = await async_db.delete(1)
+    assert deleted is True
+    assert await async_db.count() == 0
+
+    await async_db.close()

wtinydb-0.1.0/tests/test_cli.py

@@ -0,0 +1,32 @@
+"""Unit tests for WTinyDB command-line interface (CLI)."""
+
+import sys
+from unittest.mock import patch
+from pydantic import BaseModel
+from wtinydb import WTinyDB
+from wtinydb.cli.main import main
+
+
+class Task(BaseModel):
+    """Task model for CLI test."""
+
+    title: str
+
+
+def test_cli_inspect_and_count(tmp_path):
+    """Validates CLI inspect and count subcommands on a temporary JSON database file."""
+    db_file = str(tmp_path / "test_cli.json")
+    db = WTinyDB(Task, db_path=db_file)
+    db.insert(Task(title="Do homework"))
+    db.insert(Task(title="Buy milk"))
+    db.close()
+
+    # Test CLI inspect command
+    test_args = ["wtinydb", "inspect", db_file]
+    with patch.object(sys, "argv", test_args):
+        main()
+
+    # Test CLI count command
+    test_args_count = ["wtinydb", "count", db_file, "--table", "task"]
+    with patch.object(sys, "argv", test_args_count):
+        main()

wtinydb-0.1.0/tests/test_database.py

@@ -0,0 +1,140 @@
+"""Unit tests for WTinyDB synchronous operations.
+
+This test file validates CRUD operations, soft-deletion handling,
+batch inserts, document lookups, exceptions, and WMongo-compatible collection operations.
+"""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+import pytest
+
+from wtinydb import WTinyDB, DocumentNotFoundError, SoftDeleteMixin
+
+
+class User(BaseModel):
+    """Pydantic model representing a User document."""
+
+    name: str = Field(description="User full name")
+    email: str = Field(description="User email address")
+    age: int = Field(default=18, description="User age")
+
+
+class SoftUser(SoftDeleteMixin, BaseModel):
+    """Pydantic model representing a User document with soft-delete capabilities."""
+
+    name: str
+    role: str = "member"
+
+
+def test_insert_and_get():
+    """Validates model insertion and retrieval by doc_id."""
+    db = WTinyDB(User, in_memory=True)
+    user_data = User(name="Alice", email="alice@example.com", age=30)
+    inserted_user = db.insert(user_data)
+
+    assert inserted_user.name == "Alice"
+    assert inserted_user.email == "alice@example.com"
+    assert getattr(inserted_user, "_doc_id") == 1
+
+    retrieved_user = db.get(1)
+    assert retrieved_user.name == "Alice"
+    assert retrieved_user.age == 30
+    db.close()
+
+
+def test_wmongo_collection_crud():
+    """Validates WMongo-compatible collection CRUD operations (insert, find, update, delete)."""
+    db = WTinyDB(in_memory=True)
+
+    # Collection insert
+    doc_id = db.insert("customers", {"name": "John Doe", "status": "active"})
+    assert doc_id == 1
+
+    # Collection find
+    found = db.find("customers", {"status": "active"})
+    assert len(found) == 1
+    assert found[0]["name"] == "John Doe"
+
+    # Collection update
+    updated_count = db.update("customers", {"name": "John Doe"}, {"status": "inactive"})
+    assert updated_count == 1
+
+    # Collection delete
+    deleted_count = db.delete("customers", {"status": "inactive"})
+    assert deleted_count == 1
+
+    db.close()
+
+
+def test_insert_many_and_get_all():
+    """Validates batch insertion of multiple documents."""
+    db = WTinyDB(User, in_memory=True)
+    users = [
+        User(name="Bob", email="bob@example.com", age=25),
+        User(name="Charlie", email="charlie@example.com", age=35),
+    ]
+    inserted = db.insert_many(users)
+
+    assert len(inserted) == 2
+    assert db.count() == 2
+
+    all_users = db.get_all()
+    assert len(all_users) == 2
+    assert all_users[0].name == "Bob"
+    assert all_users[1].name == "Charlie"
+    db.close()
+
+
+def test_get_by_field():
+    """Validates document lookup by specific field name and value."""
+    db = WTinyDB(User, in_memory=True)
+    db.insert(User(name="David", email="david@example.com", age=40))
+
+    user = db.get_by_field("email", "david@example.com")
+    assert user is not None
+    assert user.name == "David"
+
+    missing_user = db.get_by_field("email", "nonexistent@example.com")
+    assert missing_user is None
+    db.close()
+
+
+def test_update_document():
+    """Validates document modification using dictionary update data."""
+    db = WTinyDB(User, in_memory=True)
+    inserted = db.insert(User(name="Eve", email="eve@example.com", age=22))
+
+    updated = db.update(1, {"age": 23})
+    assert updated.age == 23
+
+    retrieved = db.get(1)
+    assert retrieved.age == 23
+    db.close()
+
+
+def test_soft_delete():
+    """Validates soft-delete functionality using SoftDeleteMixin."""
+    db = WTinyDB(SoftUser, in_memory=True)
+    user = db.insert(SoftUser(name="Frank", role="admin"))
+
+    db.delete(1, hard=False)
+
+    with pytest.raises(DocumentNotFoundError):
+        db.get(1)
+
+    assert len(db.get_all(include_deleted=False)) == 0
+
+    all_docs = db.get_all(include_deleted=True)
+    assert len(all_docs) == 1
+    assert all_docs[0].is_deleted is True
+    db.close()
+
+
+def test_document_not_found_exception():
+    """Validates that accessing a non-existent document ID raises DocumentNotFoundError."""
+    db = WTinyDB(User, in_memory=True)
+
+    with pytest.raises(DocumentNotFoundError):
+        db.get(999)
+
+    db.close()

wtinydb-0.1.0/tests/test_models.py

@@ -0,0 +1,42 @@
+"""Unit tests for TimestampMixin, SoftDeleteMixin, and AuditMixin."""
+
+from pydantic import BaseModel
+from wtinydb.models import AuditMixin, SoftDeleteMixin, TimestampMixin
+
+
+class SampleTimestampDoc(TimestampMixin, BaseModel):
+    """Model using TimestampMixin."""
+
+    name: str
+
+
+class SampleAuditDoc(AuditMixin, BaseModel):
+    """Model using AuditMixin."""
+
+    title: str
+
+
+def test_timestamp_mixin():
+    """Validates default timestamp creation and touch functionality."""
+    doc = SampleTimestampDoc(name="test")
+    assert doc.created_at is not None
+    assert doc.updated_at is not None
+
+    initial_updated = doc.updated_at
+    doc.touch()
+    assert doc.updated_at >= initial_updated
+
+
+def test_audit_mixin():
+    """Validates soft deletion and restoration capabilities in AuditMixin."""
+    doc = SampleAuditDoc(title="audit test")
+    assert doc.is_deleted is False
+    assert doc.deleted_at is None
+
+    doc.soft_delete()
+    assert doc.is_deleted is True
+    assert doc.deleted_at is not None
+
+    doc.restore()
+    assert doc.is_deleted is False
+    assert doc.deleted_at is None

wtinydb-0.1.0/tests/test_query.py

@@ -0,0 +1,90 @@
+"""Unit tests for QueryBuilder and Q helper functionality.
+
+This file validates fluent query construction, comparison operators,
+regex matching, nested dotted path querying, and list containment queries.
+"""
+
+from pydantic import BaseModel
+from wtinydb import Q, QueryBuilder, WTinyDB
+
+
+class Product(BaseModel):
+    """Pydantic model representing a product in inventory."""
+
+    title: str
+    price: float
+    category: str
+
+
+class Geo(BaseModel):
+    lat: float
+    lon: float
+
+
+class Address(BaseModel):
+    city: str
+    geo: Geo
+
+
+class Organization(BaseModel):
+    name: str
+    address: Address
+
+
+def test_query_builder_operators():
+    """Validates equality, greater-than, and list comparison operators with QueryBuilder."""
+    db = WTinyDB(Product, in_memory=True)
+
+    db.insert(Product(title="Laptop", price=999.99, category="electronics"))
+    db.insert(Product(title="Mouse", price=25.00, category="electronics"))
+    db.insert(Product(title="Book", price=15.00, category="books"))
+
+    books = db.find(Q("category").eq("category", "books"))
+    assert len(books) == 1
+    assert books[0].title == "Book"
+
+    expensive = db.find(Q("price").gte("price", 100.00))
+    assert len(expensive) == 1
+    assert expensive[0].title == "Laptop"
+
+    items = db.find(Q("category").in_list("category", ["electronics", "books"]))
+    assert len(items) == 3
+
+    db.close()
+
+
+def test_query_regex_and_text_search():
+    """Validates regex pattern matching and text search functionality."""
+    db = WTinyDB(Product, in_memory=True)
+    db.insert(Product(title="Wireless Keyboard", price=45.00, category="electronics"))
+    db.insert(Product(title="Mechanical Keyboard", price=85.00, category="electronics"))
+
+    keyboards = db.find(Q("title").search_text("title", "keyboard"))
+    assert len(keyboards) == 2
+
+    wireless = db.find(Q("title").matches("title", r"^Wireless"))
+    assert len(wireless) == 1
+    assert wireless[0].title == "Wireless Keyboard"
+
+    db.close()
+
+
+def test_nested_dotted_path_query():
+    """Validates querying N-level nested JSON fields using dotted notation paths."""
+    db = WTinyDB(Organization, in_memory=True)
+    org = Organization(
+        name="Acme",
+        address=Address(city="Madrid", geo=Geo(lat=40.4168, lon=-3.7038)),
+    )
+    db.insert(org)
+
+    # Query 3-level deep nested field
+    found_city = db.find(Q("address.city").eq("address.city", "Madrid"))
+    assert len(found_city) == 1
+    assert found_city[0].name == "Acme"
+
+    # Query 4-level deep nested numeric field
+    found_geo = db.find(Q("address.geo.lat").gte("address.geo.lat", 40.0))
+    assert len(found_geo) == 1
+
+    db.close()

wtinydb-0.1.0/wtinydb/__init__.py

@@ -0,0 +1,23 @@
+"""WTinyDB package initialization."""
+
+from wtinydb.core.async_db import AsyncWTinyDB
+from wtinydb.core.database import WTinyDB
+from wtinydb.core.query import Q, QueryBuilder
+from wtinydb.exceptions import DocumentNotFoundError, StorageError, ValidationError, WTinyDBError
+from wtinydb.models import AuditMixin, SoftDeleteMixin, TimestampMixin
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "WTinyDB",
+    "AsyncWTinyDB",
+    "QueryBuilder",
+    "Q",
+    "TimestampMixin",
+    "SoftDeleteMixin",
+    "AuditMixin",
+    "WTinyDBError",
+    "DocumentNotFoundError",
+    "ValidationError",
+    "StorageError",
+]

wtinydb-0.1.0/wtinydb/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for WTinyDB."""

wtinydb-0.1.0/wtinydb/cli/main.py

@@ -0,0 +1,60 @@
+"""WTinyDB Command Line Interface (CLI)."""
+
+import argparse
+import json
+import sys
+from tinydb import TinyDB
+
+
+def main():
+    """Main CLI entrypoint for WTinyDB commands."""
+    parser = argparse.ArgumentParser(description="WTinyDB CLI Manager")
+    subparsers = parser.add_subparsers(dest="command", help="Subcommand to run")
+
+    # Command: inspect
+    inspect_parser = subparsers.add_parser("inspect", help="Inspect tables in a TinyDB JSON database file")
+    inspect_parser.add_argument("db_path", help="Path to TinyDB JSON file")
+
+    # Command: count
+    count_parser = subparsers.add_parser("count", help="Count documents in a table")
+    count_parser.add_argument("db_path", help="Path to TinyDB JSON file")
+    count_parser.add_argument("--table", default="_default", help="Table name (default: _default)")
+
+    # Command: export
+    export_parser = subparsers.add_parser("export", help="Export table content as formatted JSON")
+    export_parser.add_argument("db_path", help="Path to TinyDB JSON file")
+    export_parser.add_argument("--table", default="_default", help="Table name")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    try:
+        db = TinyDB(args.db_path)
+        if args.command == "inspect":
+            tables = list(db.tables())
+            print(f"Database: {args.db_path}")
+            print(f"Tables found: {len(tables)}")
+            for t in tables:
+                table_obj = db.table(t)
+                print(f"  - Table '{t}': {len(table_obj)} document(s)")
+
+        elif args.command == "count":
+            table_obj = db.table(args.table)
+            print(f"Table '{args.table}' contains {len(table_obj)} document(s).")
+
+        elif args.command == "export":
+            table_obj = db.table(args.table)
+            docs = table_obj.all()
+            print(json.dumps(docs, indent=2))
+
+        db.close()
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

wtinydb-0.1.0/wtinydb/core/__init__.py

@@ -0,0 +1 @@
+"""Core modules for WTinyDB."""