litsdb 0.1.0__py3-none-any.whl

litsdb/__init__.py

@@ -0,0 +1,61 @@
+"""
+Persistent, type-safe collections for Python, backed by SQLite and
+serialized with `pylits <https://pypi.org/project/pylits/>`_.
+
+Quick start::
+
+    import litsdb
+
+    db = litsdb.Database("mydb.db")
+
+    users: litsdb.LitSeq = db.seq("users")
+    tags:  litsdb.LitSet = db.set("tags")
+    names: litsdb.LitMap = db.map("names")
+
+    users.append(123)
+    tags.add("python")
+    names[123] = "Romashka"
+
+    # Transactions
+    try:
+        with names.transaction() as names_t:
+            names_t.set(123, "Vasyl")
+            names_t.pop(999)          # raises → rolls back
+    except litsdb.TransactionFailed as exc:
+        print(exc.failed.method)      # "pop"
+        print(exc.failed.msg)         # "KeyError: 999"
+
+Collection types
+----------------
+
++------------------+-------------------+--------------------------------+
+| Class            | Python analogue   | Primary key                    |
++==================+===================+================================+
+| :class:`LitSeq`  | :class:`list`     | Auto-increment integer ``id``  |
++------------------+-------------------+--------------------------------+
+| :class:`LitSet`  | :class:`set`      | The encoded value itself       |
++------------------+-------------------+--------------------------------+
+| :class:`LitMap`  | :class:`dict`     | The encoded key                |
++------------------+-------------------+--------------------------------+
+"""
+
+from ._database import Database
+from ._collection import LitCollection
+from ._seq import LitSeq
+from ._set import LitSet
+from ._map import LitMap
+from ._exceptions import LitsDBError, TransactionFailed, FailedOperation
+
+__all__ = [
+    "Database",
+    "LitCollection",
+    "LitSeq",
+    "LitSet",
+    "LitMap",
+    "LitsDBError",
+    "TransactionFailed",
+    "FailedOperation",
+]
+
+__version__ = "0.1.0"
+__author__ = "Romashka"

litsdb/_collection.py

@@ -0,0 +1,267 @@
+"""
+litsdb._collection
+~~~~~~~~~~~~~~~~~~
+
+Abstract base class shared by all persistent collection types.
+Provides thread-safe statement execution and the transaction context manager.
+"""
+from __future__ import annotations
+
+import threading
+from abc import ABC, abstractmethod
+from contextlib import contextmanager
+from typing import Any, Generator, TYPE_CHECKING, Self
+
+import pylits
+
+if TYPE_CHECKING:
+    from sqlalchemy import Table
+    from sqlalchemy.engine import Connection, Engine, CursorResult
+
+from ._exceptions import FailedOperation, TransactionFailed
+
+
+def _compile_sql(stmt, engine) -> str:
+    """Return a human-readable SQL string for *stmt*.
+
+    Falls back to :func:`repr` if compilation is not possible.
+
+    :param stmt: Any SQLAlchemy Core statement.
+    :param engine: Engine whose dialect is used for compilation.
+    :return: Compiled SQL string.
+    :rtype: str
+    """
+    try:
+        from sqlalchemy.dialects import sqlite as _d
+        return str(
+            stmt.compile(
+                dialect=_d.dialect(),
+                compile_kwargs={"literal_binds": True},
+            )
+        )
+    except Exception:
+        return repr(stmt)
+
+
+class LitCollection(ABC):
+    """Abstract base class for all persistent litsdb collections.
+
+    Subclasses (:class:`~litsdb.LitSeq`, :class:`~litsdb.LitSet`,
+    :class:`~litsdb.LitMap`) inherit thread-safe statement execution,
+    pylits-based serialization, and the :meth:`transaction` context
+    manager from this class.
+
+    :param name: Logical name of the collection (used as part of the
+                 underlying table name).
+    :type name: str
+    :param engine: SQLAlchemy :class:`~sqlalchemy.engine.Engine` shared
+                   with the parent :class:`~litsdb.Database`.
+    :type engine: sqlalchemy.engine.Engine
+    :param table: Bound :class:`~sqlalchemy.Table` that backs this
+                  collection.
+    :type table: sqlalchemy.Table
+    """
+
+    def __init__(
+        self,
+        name: str,
+        engine: "Engine",
+        table: "Table",
+    ) -> None:
+        self._name = name
+        self._engine = engine
+        self._table = table
+        # Reentrant so that nested internal calls within the same thread work.
+        self._lock = threading.RLock()
+        # Per-thread state: active transaction connection + last operation info.
+        self._local = threading.local()
+
+    # ------------------------------------------------------------------
+    # Public read-only properties
+    # ------------------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        """Logical name of this collection.
+
+        :rtype: str
+        """
+        return self._name
+
+    # ------------------------------------------------------------------
+    # Serialization helpers
+    # ------------------------------------------------------------------
+
+    def _encode(self, value: Any) -> str:
+        """Serialize *value* to a pylits string.
+
+        :param value: Any type supported by pylits
+                      (:class:`bool`, :class:`int`, :class:`float`,
+                      :class:`str`, :class:`list`, :class:`tuple`,
+                      :class:`set`, :class:`dict`, ``None``).
+        :return: Encoded string.
+        :rtype: str
+        :raises TypeError: If *value* is not a supported pylits type.
+        """
+        return pylits.encode(value)
+
+    def _decode(self, raw: str) -> Any:
+        """Deserialize a pylits-encoded string back to a Python value.
+
+        :param raw: Encoded string stored in the database.
+        :return: Original Python value.
+        """
+        return pylits.decode(raw)
+
+    # ------------------------------------------------------------------
+    # Execution layer
+    # ------------------------------------------------------------------
+
+    def _get_tx_conn(self) -> "Connection | None":
+        """Return the active transaction connection for the current thread.
+
+        :return: Open :class:`~sqlalchemy.engine.Connection` if this thread
+                 is inside a :meth:`transaction` block, otherwise ``None``.
+        """
+        return getattr(self._local, "tx_conn", None)
+
+    def _track(self, method_name: str, *args) -> None:
+        """Record the current operation for error reporting.
+
+        Call at the **start** of every public method so that
+        :meth:`transaction` can populate :class:`~litsdb.FailedOperation`
+        even when the method raises before :meth:`_execute` is reached.
+
+        :param method_name: Name of the calling method.
+        :param args: Arguments passed to the calling method.
+        """
+        self._local.last_method = method_name
+        self._local.last_args = args
+        self._local.last_stmt = ""  # overwritten by _execute if reached
+
+    def _execute(
+        self,
+        stmt,
+        *,
+        method_name: str = "<unknown>",
+        method_args: tuple = (),
+    ) -> "CursorResult":
+        """Execute *stmt* using the transaction connection when active.
+
+        When called inside a :meth:`transaction` block the statement is sent
+        to the shared transaction connection without an implicit commit.
+        Otherwise a fresh connection is obtained from the pool and the
+        statement is committed immediately.
+
+        The method also stores ``method_name``, ``method_args``, and the
+        compiled SQL in thread-local storage so that :meth:`transaction`
+        can populate :class:`~litsdb.FailedOperation` on rollback.
+
+        :param stmt: SQLAlchemy Core statement to execute.
+        :param method_name: Caller method name — used for error reporting.
+        :type method_name: str
+        :param method_args: Arguments passed by the caller — used for error
+                            reporting.
+        :type method_args: tuple
+        :return: SQLAlchemy :class:`~sqlalchemy.engine.CursorResult`.
+        """
+        tx_conn = self._get_tx_conn()
+
+        if tx_conn is not None:
+            # Update error context only when inside a transaction —
+            # this is the only place where the info will be consumed.
+            self._local.last_method = method_name
+            self._local.last_args = method_args
+            self._local.last_stmt = _compile_sql(stmt, self._engine)
+            return tx_conn.execute(stmt)
+
+        # Acquire the collection lock so that concurrent non-transaction calls
+        # from different threads do not interleave on a shared connection
+        # (relevant for StaticPool / in-memory databases).
+        with self._lock:
+            with self._engine.connect() as conn:
+                result = conn.execute(stmt)
+                conn.commit()
+                return result
+
+    # ------------------------------------------------------------------
+    # Transaction context manager
+    # ------------------------------------------------------------------
+
+    @contextmanager
+    def transaction(self) -> Generator["Self", None, None]:
+        """Atomic, thread-safe transaction context manager.
+
+        Acquires an exclusive lock on the collection for the calling thread,
+        opens a single database connection, and begins a transaction.  All
+        collection operations performed on the *yielded* object share that
+        connection.
+
+        On successful exit the transaction is **committed**.
+        On any exception the transaction is **rolled back** and a
+        :exc:`~litsdb.TransactionFailed` exception is raised, carrying a
+        :class:`~litsdb.FailedOperation` record with the method name,
+        compiled SQL, arguments, and error message.
+
+        :yields: This collection instance, bound to the open transaction.
+        :raises TransactionFailed: When any operation inside the block fails.
+
+        .. note::
+            The lock is reentrant (:class:`threading.RLock`), so nested
+            :meth:`transaction` calls from the **same thread** are safe.
+
+        Example::
+
+            try:
+                with names.transaction() as names_t:
+                    names_t.set(123, "Romashka")
+                    names_t.pop(456)
+            except TransactionFailed as exc:
+                print(exc.failed.method)   # e.g. "pop"
+                print(exc.failed.rawsql)   # compiled SQL
+                print(exc.failed.args)     # (456,)
+                print(exc.failed.msg)      # "KeyError: 456"
+        """
+        with self._lock:
+            with self._engine.connect() as conn:
+                # Explicit transaction: never rely on SA 2.x autobegin
+                # implicit commit — we call commit/rollback ourselves.
+                txn = conn.begin()
+                self._local.tx_conn = conn
+                try:
+                    yield self
+                    txn.commit()
+                except TransactionFailed:
+                    txn.rollback()
+                    raise
+                except Exception as exc:
+                    txn.rollback()
+                    raise TransactionFailed(
+                        FailedOperation(
+                            method=getattr(self._local, "last_method", "<unknown>"),
+                            rawsql=getattr(self._local, "last_stmt", ""),
+                            args=getattr(self._local, "last_args", ()),
+                            msg=str(exc),
+                        )
+                    ) from exc
+                finally:
+                    self._local.tx_conn = None
+
+    # ------------------------------------------------------------------
+    # Abstract interface every collection must implement
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove **all** entries from the collection.
+
+        Thread-safe; can be called inside a :meth:`transaction` block.
+        """
+
+    @property
+    @abstractmethod
+    def count(self) -> int:
+        """Total number of entries in the collection.
+
+        :rtype: int
+        """

litsdb/_database.py

@@ -0,0 +1,308 @@
+"""
+litsdb._database
+~~~~~~~~~~~~~~~~
+
+Top-level ``Database`` class — the single entry point for creating and
+managing persistent collections.
+"""
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+from typing import Dict, TYPE_CHECKING
+
+from sqlalchemy import create_engine, MetaData, inspect, text
+
+from ._collection import LitCollection
+from ._seq import LitSeq
+from ._set import LitSet
+from ._map import LitMap
+from ._exceptions import LitsDBError
+
+
+class Database:
+    """Top-level interface for a litsdb SQLite database file.
+
+    A single :class:`Database` instance manages one SQLite file and acts as
+    the factory for all persistent collections (:class:`~litsdb.LitSeq`,
+    :class:`~litsdb.LitSet`, :class:`~litsdb.LitMap`).
+
+    The underlying :class:`~sqlalchemy.engine.Engine` is configured with
+    ``check_same_thread=False`` and a reentrant lock so that the same
+    :class:`Database` handle can be safely shared across threads.
+
+    :param path: File path to the SQLite database.  Parent directories are
+                 created automatically.  Use ``":memory:"`` for an in-memory
+                 database (not recommended for production use).
+    :type path: str
+
+    Example::
+
+        import litsdb
+
+        db = litsdb.Database("mydb.db")
+        users: litsdb.LitSeq = db.seq("users")
+        names: litsdb.LitMap = db.map("names")
+
+        users.append(123)
+        names[123] = "Romashka"
+
+    Context-manager usage::
+
+        with litsdb.Database("mydb.db") as db:
+            users = db.seq("users")
+            users.append(1)
+        # engine is disposed automatically on exit
+    """
+
+    def __init__(self, path: str) -> None:
+        if path != ":memory:":
+            dir_path = os.path.dirname(path)
+            if dir_path:
+                os.makedirs(dir_path, exist_ok=True)
+
+        self._path = path
+
+        if path == ":memory:":
+            # StaticPool keeps a single connection so every thread sees the
+            # same in-memory database (SQLite :memory: is per-connection).
+            from sqlalchemy.pool import StaticPool
+            self._engine = create_engine(
+                "sqlite:///:memory:",
+                connect_args={"check_same_thread": False},
+                poolclass=StaticPool,
+            )
+        else:
+            self._engine = create_engine(
+                f"sqlite:///{path}",
+                connect_args={"check_same_thread": False},
+            )
+        self._metadata = MetaData()
+        self._lock = threading.RLock()
+        # Cache of already-opened collections keyed by their SQL table name.
+        self._collections: Dict[str, LitCollection] = {}
+
+    # ------------------------------------------------------------------
+    # Collection factories
+    # ------------------------------------------------------------------
+
+    def seq(self, name: str) -> LitSeq:
+        """Return (or open) a :class:`~litsdb.LitSeq` collection.
+
+        The backing SQL table is created on first access.
+
+        :param name: Logical name of the sequence.
+        :type name: str
+        :rtype: LitSeq
+
+        Example::
+
+            users: LitSeq = db.seq("users")
+        """
+        return self._get_or_create(name, LitSeq) # pyright: ignore[reportReturnType]
+
+    def set(self, name: str) -> LitSet:
+        """Return (or open) a :class:`~litsdb.LitSet` collection.
+
+        The backing SQL table is created on first access.
+
+        :param name: Logical name of the set.
+        :type name: str
+        :rtype: LitSet
+
+        Example::
+
+            tags: LitSet = db.set("tags")
+        """
+        return self._get_or_create(name, LitSet) # pyright: ignore[reportReturnType]
+
+    def map(self, name: str) -> LitMap:
+        """Return (or open) a :class:`~litsdb.LitMap` collection.
+
+        The backing SQL table is created on first access.
+
+        :param name: Logical name of the mapping.
+        :type name: str
+        :rtype: LitMap
+
+        Example::
+
+            names: LitMap = db.map("names")
+        """
+        return self._get_or_create(name, LitMap) # pyright: ignore[reportReturnType]
+
+    # ------------------------------------------------------------------
+    # Database management
+    # ------------------------------------------------------------------
+
+    def drop(self, name: str) -> bool:
+        """Drop the collection named *name* and its underlying table.
+
+        Removes the collection from the in-memory cache and issues a
+        ``DROP TABLE IF EXISTS`` statement.
+
+        .. warning::
+            This operation is **irreversible**.  All data in the collection
+            is permanently deleted.
+
+        :param name: Logical name of the collection to drop.
+        :type name: str
+        :return: ``True`` if a table was dropped, ``False`` if nothing was
+                 found.
+        :rtype: bool
+
+        Example::
+
+            db.drop("users")
+        """
+        with self._lock:
+            # Check cached collections first (all possible type prefixes).
+            for prefix in ("_seq_", "_set_", "_map_"):
+                table_name = f"{prefix}{name}"
+                cached_key = table_name
+                self._collections.pop(cached_key, None)
+
+            # Inspect the actual database for any matching table.
+            insp = inspect(self._engine)
+            dropped = False
+            for prefix in ("_seq_", "_set_", "_map_"):
+                table_name = f"{prefix}{name}"
+                if insp.has_table(table_name):
+                    with self._engine.connect() as conn:
+                        conn.execute(text(f'DROP TABLE IF EXISTS "{table_name}"'))
+                        conn.commit()
+                    # Refresh metadata so SQLAlchemy stops tracking it.
+                    self._metadata.remove(self._metadata.tables[table_name])
+                    dropped = True
+            return dropped
+
+    def tables(self) -> Dict[str, LitCollection]:
+        """Return all collection handles that have been opened in this session.
+
+        The mapping key is the SQL table name (e.g. ``"_seq_users"``).
+        To discover tables that exist on disk but have not been opened yet,
+        use :meth:`inspect_tables`.
+
+        :rtype: dict[str, LitCollection]
+        """
+        with self._lock:
+            return dict(self._collections)
+
+    def inspect_tables(self) -> Dict[str, str]:
+        """Scan the database file and return all litsdb-managed tables.
+
+        :return: ``{logical_name: collection_type}`` where *collection_type*
+                 is one of ``"seq"``, ``"set"``, or ``"map"``.
+        :rtype: dict[str, str]
+
+        Example::
+
+            db.inspect_tables()
+            # {"users": "seq", "names": "map", "tags": "set"}
+        """
+        insp = inspect(self._engine)
+        result: Dict[str, str] = {}
+        for tname in insp.get_table_names():
+            for prefix, kind in (
+                ("_seq_", "seq"),
+                ("_set_", "set"),
+                ("_map_", "map"),
+            ):
+                if tname.startswith(prefix):
+                    result[tname[len(prefix):]] = kind
+        return result
+
+    def backup(self, path: str) -> None:
+        """Create a consistent backup of the database at *path*.
+
+        Uses the `SQLite online backup API`_ which is safe to call while the
+        database is open and actively used by other threads.
+
+        Parent directories of *path* are created automatically.
+
+        :param path: Destination path for the backup file.
+        :type path: str
+        :raises LitsDBError: If the backup fails for any reason.
+        :raises ValueError: If called on an in-memory database.
+
+        Example::
+
+            db.backup("backups/21_04_2026.db")
+
+        .. _SQLite online backup API:
+            https://www.sqlite.org/backup.html
+        """
+        dir_path = os.path.dirname(path)
+        if dir_path:
+            os.makedirs(dir_path, exist_ok=True)
+
+        try:
+            dst = sqlite3.connect(path)
+            try:
+                if self._path == ":memory:":
+                    # Obtain the raw DBAPI connection from the pool;
+                    # works for both StaticPool and regular pool.
+                    raw = self._engine.raw_connection()
+                    try:
+                        raw.backup(dst)
+                    finally:
+                        raw.close()
+                else:
+                    with sqlite3.connect(self._path) as src_conn:
+                        src_conn.backup(dst)
+            finally:
+                dst.close()
+        except LitsDBError:
+            raise
+        except Exception as exc:
+            raise LitsDBError(f"Backup to {path!r} failed: {exc}") from exc
+
+    def close(self) -> None:
+        """Dispose the engine and release all pooled connections.
+
+        Called automatically when :class:`Database` is used as a context
+        manager.  Calling :meth:`close` does **not** invalidate existing
+        collection handles — they will simply fail on next use.
+        """
+        self._engine.dispose()
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "Database":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"Database(path={self._path!r}, "
+            f"open_collections={len(self._collections)})"
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_or_create(self, name: str, cls) -> LitCollection:
+        """Return a cached collection instance or construct a new one.
+
+        The cache key is the SQL table name so that a ``seq`` and a ``map``
+        with the same logical name can coexist without collision.
+
+        :param name: Logical collection name.
+        :param cls: Concrete :class:`LitCollection` subclass to instantiate.
+        :return: Collection instance.
+        """
+        prefix_map = {LitSeq: "_seq_", LitSet: "_set_", LitMap: "_map_"}
+        table_name = f"{prefix_map[cls]}{name}"
+
+        with self._lock:
+            if table_name not in self._collections:
+                self._collections[table_name] = cls(
+                    name, self._engine, self._metadata
+                )
+            return self._collections[table_name]