wtinydb 0.1.0__py3-none-any.whl

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/cli/__init__.py

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

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/core/__init__.py

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

wtinydb/core/async_db.py

@@ -0,0 +1,106 @@
+"""Asynchronous WTinyDB wrapper matching WMongoAsync interface."""
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Dict, Generic, List, Optional, Type, TypeVar, Union
+from pydantic import BaseModel
+from tinydb import Query
+
+from wtinydb.core.database import WTinyDB
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class AsyncWTinyDB(Generic[T]):
+    """Asynchronous wrapper for WTinyDB operations using asyncio thread executor."""
+
+    QUEUE_NAME = "wtinydb:notifications:changes"
+
+    def __init__(
+        self,
+        sync_db: Optional[WTinyDB[T]] = None,
+        executor: Optional[ThreadPoolExecutor] = None,
+        **kwargs: Any,
+    ):
+        """Initialize AsyncWTinyDB wrapping a synchronous WTinyDB instance.
+
+        If sync_db is not provided, passes kwargs to construct a default WTinyDB instance.
+        """
+        if sync_db is None:
+            sync_db = WTinyDB(**kwargs)
+        self.sync_db = sync_db
+        self._executor = executor
+
+    async def _run(self, func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        """Run synchronous function in thread executor."""
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(self._executor, lambda: func(*args, **kwargs))
+
+    async def insert(
+        self,
+        collection_or_instance: Union[str, T],
+        document: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Async insert single model instance or collection document."""
+        return await self._run(self.sync_db.insert, collection_or_instance, document)
+
+    async def insert_many(self, instances: List[T]) -> List[T]:
+        """Async insert multiple model instances."""
+        return await self._run(self.sync_db.insert_many, instances)
+
+    async def get(self, doc_id: int) -> T:
+        """Async get model instance by doc_id."""
+        return await self._run(self.sync_db.get, doc_id)
+
+    async def get_by_field(self, field_name: str, value: Any) -> Optional[T]:
+        """Async get document by field value."""
+        return await self._run(self.sync_db.get_by_field, field_name, value)
+
+    async def get_all(self, include_deleted: bool = False) -> List[T]:
+        """Async get all documents."""
+        return await self._run(self.sync_db.get_all, include_deleted=include_deleted)
+
+    async def find(
+        self,
+        collection_or_cond: Union[str, Query, Callable[[Dict[str, Any]], bool]],
+        query: Optional[Dict[str, Any]] = None,
+        include_deleted: bool = False,
+    ) -> List[Any]:
+        """Async find documents matching condition or collection query."""
+        return await self._run(self.sync_db.find, collection_or_cond, query=query, include_deleted=include_deleted)
+
+    async def update(
+        self,
+        collection_or_id: Union[str, int],
+        query_or_data: Union[Dict[str, Any], T],
+        update_values: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Async update document by doc_id or collection query."""
+        return await self._run(self.sync_db.update, collection_or_id, query_or_data, update_values=update_values)
+
+    async def delete(
+        self,
+        collection_or_id: Union[str, int],
+        query: Optional[Dict[str, Any]] = None,
+        hard: bool = False,
+    ) -> Any:
+        """Async delete document by doc_id or collection query."""
+        return await self._run(self.sync_db.delete, collection_or_id, query=query, hard=hard)
+
+    async def count(self, include_deleted: bool = False) -> int:
+        """Async count total documents."""
+        return await self._run(self.sync_db.count, include_deleted=include_deleted)
+
+    async def clear(self) -> None:
+        """Async purge table documents."""
+        await self._run(self.sync_db.clear)
+
+    async def close(self) -> None:
+        """Async close database storage."""
+        await self._run(self.sync_db.close)
+
+    async def __aenter__(self) -> "AsyncWTinyDB":
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+        await self.close()

wtinydb/core/database.py

@@ -0,0 +1,410 @@
+"""Synchronous WTinyDB client matching WMongo interface with Pydantic support, caching, and notifications."""
+
+import json
+import os
+import threading
+import time
+from typing import Any, Callable, Dict, Generic, List, Optional, Type, TypeVar, Union
+from cryptography.fernet import Fernet
+from pydantic import BaseModel, ValidationError as PydanticValidationError
+from tinydb import Query, TinyDB, where
+from tinydb.storages import JSONStorage, MemoryStorage
+
+from wtinydb.exceptions import DocumentNotFoundError, StorageError, ValidationError
+from wtinydb.models import SoftDeleteMixin
+
+try:
+    import redis
+except ImportError:
+    redis = None
+
+try:
+    from wredis.queue import RedisQueueManager
+except ImportError:
+    RedisQueueManager = None
+
+T = TypeVar("T", bound=BaseModel)
+
+# 🔐 Encryption Key
+ENCRYPTION_KEY = Fernet.generate_key()
+cipher_suite = Fernet(ENCRYPTION_KEY)
+
+
+def _extract_id(target: Any) -> int:
+    """Extract integer document ID from integer or Pydantic model instance."""
+    if isinstance(target, int):
+        return target
+    if isinstance(target, BaseModel):
+        for attr in ("doc_id", "id", "_doc_id", "_id"):
+            val = getattr(target, attr, None)
+            if isinstance(val, int):
+                return val
+    try:
+        return int(target)
+    except (ValueError, TypeError):
+        raise ValueError(f"Could not extract document ID from target: {target}")
+
+
+class WTinyDB(Generic[T]):
+    """Synchronous WTinyDB client providing WMongo-compatible collection CRUD, Redis cache, notifications, and Pydantic models."""
+
+    QUEUE_NAME = "wtinydb:notifications:changes"
+
+    def __init__(
+        self,
+        model_class: Optional[Type[T]] = None,
+        db_path: str = "wtinydb.json",
+        table_name: Optional[str] = None,
+        verbose: bool = False,
+        read_only: bool = False,
+        enable_notifications: bool = False,
+        enable_notification_receiver: bool = False,
+        notification_callback: Optional[Callable[[str], None]] = None,
+        redis_host: Optional[str] = None,
+        redis_port: Optional[int] = None,
+        redis_db: Optional[int] = None,
+        in_memory: bool = False,
+        storage: Type = JSONStorage,
+        **storage_kwargs: Any,
+    ):
+        """Initialize WTinyDB instance with disk persistence by default."""
+        self.model_class = model_class
+        self.table_name = table_name or (model_class.__name__.lower() if model_class else "default")
+        self.verbose = verbose
+        self.read_only = read_only
+        self.enable_notifications = enable_notifications
+        self.enable_notification_receiver = enable_notification_receiver
+        self.notification_callback = notification_callback
+        self._lock = threading.RLock()
+
+        if in_memory:
+            self.db = TinyDB(storage=MemoryStorage)
+        else:
+            db_dir = os.path.dirname(db_path)
+            if db_dir:
+                os.makedirs(db_dir, exist_ok=True)
+            self.db = TinyDB(db_path, storage=storage, **storage_kwargs)
+
+        self.table = self.db.table(self.table_name)
+        self.is_soft_delete_model = issubclass(model_class, SoftDeleteMixin) if model_class else False
+
+        # Configure Redis Cache
+        self.use_cache = False
+        self.redis_client = None
+        if redis and redis_host and redis_port is not None and redis_db is not None:
+            try:
+                self.redis_client = redis.Redis(
+                    host=redis_host, port=redis_port, db=redis_db, decode_responses=True
+                )
+                self.redis_client.ping()
+                self.use_cache = True
+            except Exception:
+                self.use_cache = False
+
+        # Configure Redis Queue Manager
+        self.redis_queue_manager = None
+        if (self.enable_notifications or self.enable_notification_receiver) and RedisQueueManager and redis_host:
+            try:
+                self.redis_queue_manager = RedisQueueManager(
+                    host=redis_host, port=redis_port, db=redis_db, verbose=self.verbose
+                )
+            except Exception:
+                self.redis_queue_manager = None
+
+    def _to_doc(self, instance: T) -> Dict[str, Any]:
+        """Serialize Pydantic model instance to dict."""
+        return instance.model_dump(mode="json")
+
+    def _to_model(self, doc: Dict[str, Any], doc_id: int) -> T:
+        """Deserialize TinyDB doc dict into Pydantic model instance with doc_id and id attributes."""
+        if not self.model_class:
+            return doc
+        try:
+            doc_copy = dict(doc)
+            if "doc_id" not in doc_copy:
+                doc_copy["doc_id"] = doc_id
+            if "id" not in doc_copy:
+                doc_copy["id"] = doc_id
+
+            model = self.model_class.model_validate(doc_copy)
+
+            # Ensure doc_id, id, and _doc_id are accessible directly on model instance
+            object.__setattr__(model, "doc_id", doc_id)
+            object.__setattr__(model, "id", doc_id)
+            object.__setattr__(model, "_doc_id", doc_id)
+            return model
+        except PydanticValidationError as e:
+            raise ValidationError(f"Failed to validate document doc_id={doc_id}: {e}") from e
+
+    def insert(
+        self,
+        collection_or_instance: Union[str, T],
+        document: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Insert document or Pydantic model. Accepts WMongo style `insert('users', doc)` or `insert(model_instance)`."""
+        if self.read_only:
+            raise PermissionError("Database is in read-only mode!")
+
+        with self._lock:
+            if isinstance(collection_or_instance, str):
+                collection_name = collection_or_instance
+                doc_data = document or {}
+                tbl = self.db.table(collection_name)
+                doc_id = tbl.insert(doc_data)
+
+                if self.use_cache and self.redis_client:
+                    doc_data["_id"] = str(doc_id)
+                    self.redis_client.set(f"cache:{collection_name}:{doc_id}", json.dumps(doc_data), ex=300)
+
+                if self.enable_notifications:
+                    self._send_notification({
+                        "database": self.table_name,
+                        "collection": collection_name,
+                        "action": "insert",
+                        "document": doc_data,
+                        "timestamp": time.time(),
+                        "id": str(doc_id),
+                    })
+                return doc_id
+            else:
+                instance = collection_or_instance
+                doc_data = self._to_doc(instance)
+                doc_id = self.table.insert(doc_data)
+                return self._to_model(doc_data, doc_id)
+
+    def find(
+        self,
+        collection_or_cond: Union[str, Query, Callable[[Dict[str, Any]], bool]],
+        query: Optional[Dict[str, Any]] = None,
+        include_deleted: bool = False,
+    ) -> List[Any]:
+        """Find documents. Accepts WMongo style `find('users', {'name': 'Alice'})` or Query objects."""
+        with self._lock:
+            if isinstance(collection_or_cond, dict):
+                query_dict = collection_or_cond
+                results = self.table.search(
+                    lambda doc: all(doc.get(k) == v for k, v in query_dict.items())
+                )
+                models = []
+                for doc in results:
+                    model = self._to_model(doc, doc.doc_id)
+                    if not include_deleted and self.is_soft_delete_model and getattr(model, "is_deleted", False):
+                        continue
+                    models.append(model)
+                return models
+            elif isinstance(collection_or_cond, str):
+                collection_name = collection_or_cond
+                query_dict = query or {}
+                tbl = self.db.table(collection_name)
+
+                if not query_dict:
+                    results = tbl.all()
+                else:
+                    results = tbl.search(
+                        lambda doc: all(doc.get(k) == v for k, v in query_dict.items())
+                    )
+
+                for doc in results:
+                    if "_id" not in doc and hasattr(doc, "doc_id"):
+                        doc["_id"] = str(doc.doc_id)
+                return results
+            else:
+                cond = collection_or_cond
+                results = self.table.search(cond)
+                models = []
+                for doc in results:
+                    model = self._to_model(doc, doc.doc_id)
+                    if not include_deleted and self.is_soft_delete_model and getattr(model, "is_deleted", False):
+                        continue
+                    models.append(model)
+                return models
+
+    def update(
+        self,
+        collection_or_id_or_model: Union[str, int, T],
+        query_or_data: Union[Dict[str, Any], T],
+        update_values: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Update documents. Accepts WMongo style `update('users', query, update_values)` or `update(model_instance_or_id, data)`."""
+        if self.read_only:
+            raise PermissionError("Database is in read-only mode!")
+
+        with self._lock:
+            if isinstance(collection_or_id_or_model, (Query, Callable)):
+                cond = collection_or_id_or_model
+                update_dict = query_or_data if isinstance(query_or_data, dict) else self._to_doc(query_or_data)
+                return self.table.update(update_dict, cond)
+            elif isinstance(collection_or_id_or_model, str):
+                collection_name = collection_or_id_or_model
+                query_dict = query_or_data if isinstance(query_or_data, dict) else {}
+                vals = update_values or {}
+                tbl = self.db.table(collection_name)
+
+                updated_ids = tbl.update(
+                    vals,
+                    cond=lambda doc: all(doc.get(k) == v for k, v in query_dict.items()) if query_dict else True,
+                )
+                updated_count = len(updated_ids)
+
+                if self.enable_notifications and updated_count > 0:
+                    self._send_notification({
+                        "database": self.table_name,
+                        "collection": collection_name,
+                        "action": "update",
+                        "query": query_dict,
+                        "update_values": vals,
+                        "timestamp": time.time(),
+                        "modified_count": updated_count,
+                    })
+                return updated_count
+            else:
+                doc_id = _extract_id(collection_or_id_or_model)
+                if not self.table.contains(doc_id=doc_id):
+                    raise DocumentNotFoundError(doc_id=doc_id, table_name=self.table_name)
+                update_dict = self._to_doc(query_or_data) if isinstance(query_or_data, BaseModel) else query_or_data
+                self.table.update(update_dict, doc_ids=[doc_id])
+                return self.get(doc_id)
+
+    def delete(
+        self,
+        collection_or_id_or_model: Union[str, int, Query, T],
+        query: Optional[Dict[str, Any]] = None,
+        hard: bool = False,
+    ) -> Any:
+        """Delete documents. Accepts WMongo style `delete('users', query)` or `delete(model_instance_or_id)` or `delete(Query)`."""
+        if self.read_only:
+            raise PermissionError("Database is in read-only mode!")
+
+        with self._lock:
+            if isinstance(collection_or_id_or_model, (Query, Callable)):
+                cond = collection_or_id_or_model
+                return self.table.remove(cond)
+            elif isinstance(collection_or_id_or_model, str):
+                collection_name = collection_or_id_or_model
+                query_dict = query or {}
+                tbl = self.db.table(collection_name)
+
+                deleted_ids = tbl.remove(
+                    cond=lambda doc: all(doc.get(k) == v for k, v in query_dict.items()) if query_dict else True
+                )
+                deleted_count = len(deleted_ids)
+
+                if self.enable_notifications and deleted_count > 0:
+                    self._send_notification({
+                        "database": self.table_name,
+                        "collection": collection_name,
+                        "action": "delete",
+                        "query": query_dict,
+                        "timestamp": time.time(),
+                        "deleted_count": deleted_count,
+                    })
+                return deleted_count
+            else:
+                doc_id = _extract_id(collection_or_id_or_model)
+                if not self.table.contains(doc_id=doc_id):
+                    raise DocumentNotFoundError(doc_id=doc_id, table_name=self.table_name)
+
+                if self.is_soft_delete_model and not hard:
+                    from datetime import datetime, timezone
+                    self.table.update({"is_deleted": True, "deleted_at": datetime.now(timezone.utc).isoformat()}, doc_ids=[doc_id])
+                    return True
+                else:
+                    self.table.remove(doc_ids=[doc_id])
+                    return True
+
+    def insert_many(self, instances: List[T]) -> List[T]:
+        """Insert multiple Pydantic model instances."""
+        if self.read_only:
+            raise PermissionError("Database is in read-only mode!")
+        with self._lock:
+            docs = [self._to_doc(inst) for inst in instances]
+            doc_ids = self.table.insert_multiple(docs)
+            return [self._to_model(doc, doc_id) for doc, doc_id in zip(docs, doc_ids)]
+
+    def get(self, target: Union[int, T]) -> T:
+        """Retrieve a document by TinyDB doc_id or Pydantic model instance."""
+        doc_id = _extract_id(target)
+        with self._lock:
+            doc = self.table.get(doc_id=doc_id)
+            if doc is None:
+                raise DocumentNotFoundError(doc_id=doc_id, table_name=self.table_name)
+            model = self._to_model(doc, doc_id)
+            if self.is_soft_delete_model and getattr(model, "is_deleted", False):
+                raise DocumentNotFoundError(doc_id=doc_id, table_name=self.table_name)
+            return model
+
+    def get_by_field(self, field_name: str, value: Any) -> Optional[T]:
+        """Retrieve first document matching field_name == value."""
+        with self._lock:
+            results = self.find(where(field_name) == value)
+            return results[0] if results else None
+
+    def get_all(self, include_deleted: bool = False) -> List[T]:
+        """Retrieve all documents in the primary table."""
+        with self._lock:
+            models = []
+            for doc in self.table.all():
+                model = self._to_model(doc, doc.doc_id)
+                if not include_deleted and self.is_soft_delete_model and getattr(model, "is_deleted", False):
+                    continue
+                models.append(model)
+            return models
+
+    def count(self, include_deleted: bool = False) -> int:
+        """Return total document count."""
+        with self._lock:
+            if not self.is_soft_delete_model or include_deleted:
+                return len(self.table)
+            return len(self.get_all(include_deleted=False))
+
+    def clear(self) -> None:
+        """Purge all documents from primary table."""
+        if self.read_only:
+            raise PermissionError("Database is in read-only mode!")
+        with self._lock:
+            self.table.truncate()
+
+    def _send_notification(self, message: Dict[str, Any]) -> None:
+        """Send notification via Redis Queue Manager."""
+        if self.redis_queue_manager:
+            try:
+                self.redis_queue_manager.publish(self.QUEUE_NAME, message)
+            except Exception:
+                pass
+
+    def listen_notifications(self) -> None:
+        """Start listening for change notifications using Redis Queue Manager."""
+        if self.redis_queue_manager and self.notification_callback:
+            @self.redis_queue_manager.on_message(self.QUEUE_NAME)
+            def handle_message(record: str) -> None:
+                self.notification_callback(record)
+
+            self.redis_queue_manager.start()
+            self.redis_queue_manager.wait()
+
+    def has_permission(self, user_id: str, collection: str) -> bool:
+        """Check user permission for target collection."""
+        roles_tbl = self.db.table("roles")
+        roles = roles_tbl.search(where("user_id") == user_id)
+        if not roles:
+            return False
+        return collection in roles[0].get("collections", [])
+
+    def encrypt(self, data: str) -> str:
+        """Encrypt sensitive string data."""
+        return cipher_suite.encrypt(data.encode()).decode()
+
+    def decrypt(self, data: str) -> str:
+        """Decrypt encrypted string data."""
+        return cipher_suite.decrypt(data.encode()).decode()
+
+    def close(self) -> None:
+        """Close TinyDB instance and liberate resources."""
+        with self._lock:
+            self.db.close()
+
+    def __enter__(self) -> "WTinyDB":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()

wtinydb/core/query.py

@@ -0,0 +1,91 @@
+"""Fluent Query Builder for WTinyDB operations with N-level nested JSON support."""
+
+import re
+from typing import Any, Callable, Dict, List, Optional
+from tinydb import Query, where
+
+
+def _resolve_query(field: str) -> Query:
+    """Resolve field path into a TinyDB Query object, supporting N-level nested dotted notation."""
+    if "." not in field:
+        return where(field)
+    parts = field.split(".")
+    q = Query()
+    for part in parts:
+        q = q[part]
+    return q
+
+
+class QueryBuilder:
+    """Fluent Builder for constructing complex TinyDB query conditions with nested field support."""
+
+    def __init__(self, field_name: Optional[str] = None):
+        """Initialize QueryBuilder, optionally specifying target field."""
+        self.field_name = field_name
+
+    def _get_target_and_val(self, arg1: Any, arg2: Any = None) -> tuple[str, Any]:
+        """Resolve target field name and comparison value."""
+        if arg2 is None:
+            if not self.field_name:
+                raise ValueError("Target field name must be specified in Q('field') or method call.")
+            return self.field_name, arg1
+        return str(arg1), arg2
+
+    def eq(self, arg1: Any, arg2: Any = None) -> Any:
+        """Field equals value. Accepts `Q('field').eq(val)` or `Q().eq('field', val)`."""
+        field, val = self._get_target_and_val(arg1, arg2)
+        return _resolve_query(field) == val
+
+    def neq(self, arg1: Any, arg2: Any = None) -> Any:
+        """Field does not equal value."""
+        field, val = self._get_target_and_val(arg1, arg2)
+        return _resolve_query(field) != val
+
+    def gt(self, arg1: Any, arg2: Any = None) -> Any:
+        """Field greater than value."""
+        field, val = self._get_target_and_val(arg1, arg2)
+        return _resolve_query(field) > val
+
+    def gte(self, arg1: Any, arg2: Any = None) -> Any:
+        """Field greater than or equal to value."""
+        field, val = self._get_target_and_val(arg1, arg2)
+        return _resolve_query(field) >= val
+
+    def lt(self, arg1: Any, arg2: Any = None) -> Any:
+        """Field less than value."""
+        field, val = self._get_target_and_val(arg1, arg2)
+        return _resolve_query(field) < val
+
+    def lte(self, arg1: Any, arg2: Any = None) -> Any:
+        """Field less than or equal to value."""
+        field, val = self._get_target_and_val(arg1, arg2)
+        return _resolve_query(field) <= val
+
+    def in_list(self, arg1: Any, arg2: Any = None) -> Any:
+        """Field value is in list of values."""
+        field, val = self._get_target_and_val(arg1, arg2)
+        return _resolve_query(field).one_of(val)
+
+    def matches(self, arg1: Any, arg2: Any = None, flags: int = 0) -> Any:
+        """Field matches regular expression pattern."""
+        field, pattern = self._get_target_and_val(arg1, arg2)
+        return _resolve_query(field).matches(pattern, flags=flags)
+
+    def exists(self, field: Optional[str] = None) -> Any:
+        """Field exists in document."""
+        target = field or self.field_name
+        if not target:
+            raise ValueError("Target field name must be specified.")
+        return _resolve_query(target).exists()
+
+    def search_text(self, arg1: Any, arg2: Any = None, case_sensitive: bool = False) -> Any:
+        """Field contains text substring."""
+        field, substring = self._get_target_and_val(arg1, arg2)
+        if case_sensitive:
+            return _resolve_query(field).search(re.escape(str(substring)))
+        return _resolve_query(field).search(re.escape(str(substring)), flags=re.IGNORECASE)
+
+
+def Q(field: str) -> QueryBuilder:
+    """Factory helper for QueryBuilder."""
+    return QueryBuilder(field)

wtinydb/exceptions.py

@@ -0,0 +1,29 @@
+"""WTinyDB custom exception definitions."""
+
+
+class WTinyDBError(Exception):
+    """Base exception class for all WTinyDB errors."""
+
+    pass
+
+
+class DocumentNotFoundError(WTinyDBError):
+    """Raised when a requested document is not found in the database collection."""
+
+    def __init__(self, doc_id: str or int, table_name: str = "default"):
+        """Initialize DocumentNotFoundError with doc_id and table_name."""
+        super().__init__(f"Document with ID '{doc_id}' not found in table '{table_name}'.")
+        self.doc_id = doc_id
+        self.table_name = table_name
+
+
+class ValidationError(WTinyDBError):
+    """Raised when document data fails Pydantic schema validation."""
+
+    pass
+
+
+class StorageError(WTinyDBError):
+    """Raised when a underlying storage or IO error occurs."""
+
+    pass

wtinydb/models.py

@@ -0,0 +1,44 @@
+"""WTinyDB Base Mixins and Document models."""
+
+from datetime import datetime, timezone
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+def _utc_now() -> datetime:
+    """Helper returning current UTC datetime."""
+    return datetime.now(timezone.utc)
+
+
+class TimestampMixin(BaseModel):
+    """Mixin for models requiring created_at and updated_at timestamps."""
+
+    created_at: datetime = Field(default_factory=_utc_now, description="Creation timestamp")
+    updated_at: datetime = Field(default_factory=_utc_now, description="Last update timestamp")
+
+    def touch(self) -> None:
+        """Update updated_at timestamp to current UTC time."""
+        self.updated_at = _utc_now()
+
+
+class SoftDeleteMixin(BaseModel):
+    """Mixin for models implementing logical (soft) deletion."""
+
+    is_deleted: bool = Field(default=False, description="Flag indicating soft deletion status")
+    deleted_at: Optional[datetime] = Field(default=None, description="Timestamp when deleted soft")
+
+    def soft_delete(self) -> None:
+        """Mark object as soft-deleted."""
+        self.is_deleted = True
+        self.deleted_at = _utc_now()
+
+    def restore(self) -> None:
+        """Restore a soft-deleted object."""
+        self.is_deleted = False
+        self.deleted_at = None
+
+
+class AuditMixin(TimestampMixin, SoftDeleteMixin):
+    """Combined mixin providing timestamps and soft-delete audit features."""
+
+    pass

wtinydb-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+wtinydb/__init__.py,sha256=wRpXe7VSFOjizzWDU2sHJdnCm2eZlI74tCKzZycRJ5s,601
+wtinydb/exceptions.py,sha256=QA417CjTjIEDI059Mve-ZuldV4P4bgbXj0mPChhb3Ls,806
+wtinydb/models.py,sha256=3Sanp1lofMbD1bU8eJIhHsB5rRDF51mHuCcpv0-xi7w,1427
+wtinydb/cli/__init__.py,sha256=Jo2NO8371QnDWToQEfEKaHowjz48hEEPvZEWMPOHyi8,31
+wtinydb/cli/main.py,sha256=A0BUMWUSNP_mBhUrNrTlD4dqIIUn8jbVFlzy-kfqCa8,2046
+wtinydb/core/__init__.py,sha256=tTh3bG7xkveyKlExYftWdNEbN_Kfcn_dkrvZmidgYlI,32
+wtinydb/core/async_db.py,sha256=RCPPaMTlELYdze-p1JlOQ3g8fbq94bvqhF_ZketWCgY,4058
+wtinydb/core/database.py,sha256=1WKZDwqw6BWN8CsyIwWu2AzEwh9QjWQZvTOuWMsOmWY,17205
+wtinydb/core/query.py,sha256=jiQqM73TIyX0S7oCRhV9nPVvdLLO5NPuXzYkRwtzflQ,3671
+wtinydb-0.1.0.dist-info/licenses/LICENSE,sha256=Oyqf3mzTxsLVAFwTwTpmcfEsdCeJnA4jMu5Dv-Jq_Ag,1074
+wtinydb-0.1.0.dist-info/METADATA,sha256=5zG652_X3bbaAbYfIQJa2i4I7w4a6Ot4c_67PHPD3dA,3027
+wtinydb-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+wtinydb-0.1.0.dist-info/entry_points.txt,sha256=RxgMIDaYlqWGmeRLoshQdLjhWplo6HwdZfa6v60BY0E,50
+wtinydb-0.1.0.dist-info/top_level.txt,sha256=2MRK53HEeDm9zW3cY6jj1SnN6gqEmHBCVKRzswGVv0o,8
+wtinydb-0.1.0.dist-info/RECORD,,

wtinydb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wtinydb-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wtinydb = wtinydb.cli.main:main

wtinydb-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+wtinydb