brainlessdb 0.1.0__py3-none-any.whl

brainless/__init__.py

@@ -0,0 +1,57 @@
+"""Brainless - Schema-first async persistence for NATS JetStream KV."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from brainless.client import Brainless
+from brainless.collection import Collection
+from brainless.entity import Entity
+
+__all__ = ["Brainless", "Collection", "Entity", "setup", "stop", "flush"]
+
+_instance: Brainless | None = None
+
+
+async def setup(
+    nats: Any = None,
+    namespace: str = "default",
+    location: str = "local",
+    flush_interval: float = 0.5,
+) -> Brainless:
+    """Initialize and start the global Brainless instance
+
+    @param nats: Connected NATS client (optional for in-memory only mode)
+    @param namespace: Bucket prefix for isolation
+    @param location: Name of this site/node for UUID prefixes
+    @param flush_interval: Background flush interval in seconds
+    @return: The Brainless instance
+    """
+    global _instance
+    if _instance is not None:
+        await _instance.stop()
+    _instance = Brainless(nats, namespace, location, flush_interval)
+    await _instance.start()
+    return _instance
+
+
+async def stop() -> None:
+    """Stop the global Brainless instance."""
+    global _instance
+    if _instance is not None:
+        await _instance.stop()
+        _instance = None
+
+
+async def flush() -> int:
+    """Flush all dirty entities in the global instance."""
+    if _instance is None:
+        raise RuntimeError("Call brainless.setup() first")
+    return await _instance.flush()
+
+
+def __getattr__(name: str) -> Any:
+    """Proxy attribute access to global instance for collection access."""
+    if _instance is None:
+        raise RuntimeError("Call brainless.setup() first")
+    return getattr(_instance, name)

brainless/bucket.py

@@ -0,0 +1,127 @@
+"""NATS JetStream KV bucket wrapper."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from nats.js.errors import BucketNotFoundError
+
+if TYPE_CHECKING:
+    from nats.js.kv import KeyValue
+
+_log = logging.getLogger(__name__)
+
+
+class Bucket:
+    """Wrapper around NATS JetStream KV bucket
+
+    Provides simple get/put/delete operations with JSON serialization.
+    """
+
+    def __init__(self, name: str, kv: KeyValue) -> None:
+        self._name = name
+        self._kv = kv
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @classmethod
+    async def create(
+        cls,
+        js: Any,
+        name: str,
+        ttl: float | None = None,
+        max_bytes: int | None = None,
+    ) -> Bucket:
+        """Create or get existing KV bucket
+
+        @param js: JetStream context
+        @param name: Bucket name
+        @param ttl: Time-to-live in seconds (optional)
+        @param max_bytes: Max bucket size in bytes (optional)
+        @return: Bucket instance
+        """
+        from nats.js.api import KeyValueConfig
+
+        config = KeyValueConfig(bucket=name)
+        if ttl is not None:
+            config.ttl = ttl
+        if max_bytes is not None:
+            config.max_bytes = max_bytes
+
+        try:
+            kv = await js.key_value(name)
+            _log.debug("Using existing bucket: %s", name)
+        except BucketNotFoundError:
+            kv = await js.create_key_value(config)
+            _log.info("Created bucket: %s", name)
+
+        return cls(name, kv)
+
+    async def get(self, key: str) -> dict[str, Any] | None:
+        """Get value by key
+
+        @param key: Key to retrieve
+        @return: Deserialized value or None if not found
+        """
+        try:
+            entry = await self._kv.get(key)
+            if entry is None or entry.value is None:
+                return None
+            envelope = json.loads(entry.value.decode())
+            return envelope["data"]
+        except Exception as e:
+            if "not found" in str(e).lower():
+                return None
+            raise
+
+    async def put(self, key: str, value: dict[str, Any]) -> None:
+        """Store value by key
+
+        @param key: Key to store
+        @param value: Value to serialize and store
+        """
+        envelope = {"version": "1", "data": value}
+        data = json.dumps(envelope).encode()
+        await self._kv.put(key, data)
+
+    async def delete(self, key: str) -> bool:
+        """Delete key
+
+        @param key: Key to delete
+        @return: True if deleted, False if not found
+        """
+        try:
+            await self._kv.delete(key)
+            return True
+        except Exception as e:
+            if "not found" in str(e).lower():
+                return False
+            raise
+
+    async def keys(self) -> list[str]:
+        """Get all keys in bucket
+
+        @return: List of keys
+        """
+        try:
+            return await self._kv.keys()
+        except Exception as e:
+            if "no keys" in str(e).lower():
+                return []
+            raise
+
+    async def all(self) -> dict[str, dict[str, Any]]:
+        """Get all key-value pairs
+
+        @return: Dictionary of all entries
+        """
+        result = {}
+        for key in await self.keys():
+            value = await self.get(key)
+            if value is not None:
+                result[key] = value
+        return result

brainless/client.py

@@ -0,0 +1,150 @@
+"""Brainless main client."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from brainless.bucket import Bucket
+from brainless.collection import Collection
+
+_log = logging.getLogger(__name__)
+
+
+class Brainless:
+    """Schema-first async persistence for NATS JetStream KV
+
+    Manages collections backed by NATS JetStream KV buckets. Schema is stored
+    in NATS itself, allowing data access without predefined classes.
+
+    Access collections as attributes: db.users, db.calls, etc.
+    """
+
+    def __init__(
+        self,
+        nats: Any = None,
+        namespace: str = "default",
+        location: str = "local",
+        flush_interval: float = 0.5,
+    ) -> None:
+        """Initialize Brainless client
+
+        @param nats: Connected NATS client (optional for in-memory only mode)
+        @param namespace: Bucket prefix for isolation (e.g., "myapp" -> "myapp-calls")
+        @param location: Name of this site/node (e.g., "prague-1"), used as prefix
+                         in record UUIDs and for ownership in multi-location sync
+        @param flush_interval: Background flush interval in seconds
+        """
+        self._nats = nats
+        self._namespace = namespace
+        self._location = location
+        self._flush_interval = flush_interval
+        self._started = False
+        self._collections: dict[str, Collection] = {}
+        self._js: Any = None
+        self._flush_task: asyncio.Task | None = None
+
+    @property
+    def namespace(self) -> str:
+        return self._namespace
+
+    @property
+    def location(self) -> str:
+        return self._location
+
+    @property
+    def connected(self) -> bool:
+        """True if connected to NATS."""
+        return self._nats is not None and self._js is not None
+
+    def _bucket_name(self, collection: str) -> str:
+        """Generate bucket name for collection."""
+        return f"{self._namespace}-{collection}"
+
+    async def get_bucket(self, collection: str) -> Bucket | None:
+        """Get or create bucket for collection."""
+        if not self.connected:
+            return None
+        name = self._bucket_name(collection)
+        return await Bucket.create(self._js, name)
+
+    def collection(self, name: str) -> Collection:
+        """Get or create a collection by name
+
+        @param name: Collection name
+        @return: Collection instance
+        """
+        if name not in self._collections:
+            self._collections[name] = Collection(self, name)
+        return self._collections[name]
+
+    def __getattr__(self, name: str) -> Collection:
+        """Access collections as attributes: db.users, db.calls, etc."""
+        if name.startswith("_"):
+            raise AttributeError(f"'{type(self).__name__}' has no attribute '{name}'")
+        return self.collection(name)
+
+    async def _flush_loop(self) -> None:
+        """Background task to flush dirty entities."""
+        try:
+            while self._started:
+                await asyncio.sleep(self._flush_interval)
+                await self.flush()
+        except asyncio.CancelledError:
+            pass
+
+    async def flush(self) -> int:
+        """Flush all dirty entities to NATS
+
+        @return: Number of entities flushed
+        """
+        total = 0
+        for collection in self._collections.values():
+            total += await collection.flush()
+        return total
+
+    async def start(self) -> None:
+        """Start the client and connect to NATS."""
+        if self._started:
+            return
+
+        # Get JetStream context if NATS is available
+        if self._nats is not None:
+            self._js = self._nats.jetstream()
+
+        self._started = True
+
+        # Start background flush task
+        if self.connected:
+            self._flush_task = asyncio.create_task(self._flush_loop())
+
+        _log.info(
+            "Brainless started (namespace=%s, location=%s, connected=%s)",
+            self._namespace,
+            self._location,
+            self.connected,
+        )
+
+    async def stop(self) -> None:
+        """Stop the client and flush pending changes."""
+        if not self._started:
+            return
+
+        self._started = False
+
+        # Cancel flush task
+        if self._flush_task is not None:
+            self._flush_task.cancel()
+            try:
+                await self._flush_task
+            except asyncio.CancelledError:
+                pass
+            self._flush_task = None
+
+        # Final flush
+        flushed = await self.flush()
+        if flushed > 0:
+            _log.info("Flushed %d entities on shutdown", flushed)
+
+        _log.info("Brainless stopped")