dbzero 0.3.3__tar.gz → 0.3.5__tar.gz

{dbzero-0.3.3 → dbzero-0.3.5}/AGENTS.md

@@ -19,15 +19,18 @@ All tests must pass before a change is considered complete.
 - Debug build: `./scripts/build.sh -d` (equivalent to `./scripts/build.sh`; debug is the default)
 - Release build: `./scripts/build.sh -r`
 - Release build with C++ unit test binary: `./scripts/build.sh -r -t`
+- For regular development and focused Python-side test runs, prefer the release build because it is significantly faster. Unless C++ tests are important for the current change, build without `-t`; skipping the C++ test binary is much faster.
+- Use a debug build when tracking a specific deep bug that needs assertions or debug-level checks, and before final handoff only when the user explicitly asks for handoff validation.
 
 ### Running tests
 
 - Python tests: `./scripts/run_tests.sh`
 - Final Python test checks: `./scripts/run_tests.sh -j 6`
 - C++ tests after a `-t` build: `./build/release/tests.x`
+- Broad debug/release builds and full-suite checks are final handoff validation only; run them when the user explicitly asks for handoff.
 - Before final handoff, also verify the code in debug mode with a debug build (`./scripts/build.sh -d`) and the relevant Python tests against that debug build. Debug assertions are part of the required validation, not optional diagnostics.
 - During development, do not run stress tests by default; they are intentionally slow. Run focused tests specific to the feature or refactor being worked on before finalization.
-- If any C++ source under the native/core part of the project was modified, also run the C++ test suite (do not rely on the Python tests alone to cover native changes).
+- If any C++ source under the native/core part of the project was modified, also run the C++ test suite during final handoff validation (do not rely on the Python tests alone to cover native changes).
 
 Never mark a task done while tests are failing.
 

{dbzero-0.3.3 → dbzero-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dbzero
-Version: 0.3.3
+Version: 0.3.5
 Summary: A state management system for Python 3.x that unifies your applications business logic, data persistence, and caching into a single, efficient layer.
 Author-Email: "DBZero Software sp. z o.o" <info@dbzero.io>
 License:                   GNU LESSER GENERAL PUBLIC LICENSE

dbzero-0.3.5/benchmarks/read_only_reads.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Benchmark regular db0 memo reads with read_only machinery compiled in.
+
+This benchmark intentionally performs only plain db0 read operations outside a
+read_only block. It answers whether the read_only mutation-check machinery
+slows existing read-heavy code when read_only is not active.
+
+Observed on this workspace:
+- CPU: 11th Gen Intel(R) Core(TM) i9-11950H @ 2.60GHz (2.61 GHz)
+- Python: 3.11.13
+- Build: release, default async-safe read_only implementation, mutation-only atomic API guard
+- Command:
+  PYTHONPATH=/src/dev/dbzero python3 benchmarks/read_only_reads.py --target-seconds 30
+- Current result:
+  iterations=55059079
+  elapsed_seconds=30.433811
+  reads_per_second=1809141.757
+  nanoseconds_per_read=552.748
+- Previous recorded result:
+  iterations=56095010
+  elapsed_seconds=30.795000
+  reads_per_second=1821562.283
+  nanoseconds_per_read=548.979
+"""
+
+import argparse
+import gc
+import tempfile
+import time
+
+import dbzero as db0
+
+
+@db0.memo
+class ReadBenchmarkMemo:
+    pass
+
+
+def run_reads(obj, iterations):
+    total = 0
+    for _ in range(iterations):
+        total += obj.value
+    return total
+
+
+def measure(obj, iterations):
+    gc_was_enabled = gc.isenabled()
+    gc.disable()
+    try:
+        start = time.perf_counter()
+        total = run_reads(obj, iterations)
+        elapsed = time.perf_counter() - start
+    finally:
+        if gc_was_enabled:
+            gc.enable()
+    return elapsed, total
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--iterations", type=int)
+    parser.add_argument("--target-seconds", type=float, default=30.0)
+    parser.add_argument("--calibration-seconds", type=float, default=2.0)
+    args = parser.parse_args()
+
+    with tempfile.TemporaryDirectory() as root:
+        db0.init(root)
+        db0.open("read-only-overhead-benchmark")
+        obj = ReadBenchmarkMemo()
+        obj.value = 1
+        object_id = db0.uuid(obj)
+        db0.commit()
+        obj = db0.fetch(object_id)
+
+        run_reads(obj, 10000)
+        if args.iterations is None:
+            calibration_iterations = 10000
+            elapsed = 0.0
+            while elapsed < args.calibration_seconds:
+                calibration_iterations *= 2
+                elapsed, _ = measure(obj, calibration_iterations)
+            iterations = max(1, int(calibration_iterations * args.target_seconds / elapsed))
+        else:
+            iterations = args.iterations
+
+        elapsed, total = measure(obj, iterations)
+        print(f"build_flags={db0.build_flags()}")
+        print(f"iterations={iterations}")
+        print(f"elapsed_seconds={elapsed:.6f}")
+        print(f"reads_per_second={iterations / elapsed:.3f}")
+        print(f"nanoseconds_per_read={elapsed * 1_000_000_000 / iterations:.3f}")
+        print(f"checksum={total}")
+
+
+if __name__ == "__main__":
+    main()

dbzero-0.3.5/benchmarks/tagging.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""Benchmark db0 tag assignment throughput.
+
+The benchmark creates memo objects in a preparation step, commits them, and
+pre-seeds a regular anchor tag before timing starts. The measured loop applies
+fresh simple tags to a fixed batch of existing objects and commits after every
+batch, so the reported throughput includes flushing pending tag index updates.
+
+Scenarios:
+- fresh-tags: creates a new tag key for every measured batch; this measures tag
+  key creation, inverted-list creation, assignment, and flush cost together.
+- precreated-tags: creates and flushes tag keys before timing starts, then uses
+  those existing keys once during timing; this focuses on assignment and flush
+  cost without string-pool/tag-key creation.
+
+Observed on this workspace:
+- CPU: 11th Gen Intel(R) Core(TM) i9-11950H @ 2.60GHz
+- Python: 3.11.13
+- Build: release
+- Commands:
+  python3 benchmarks/tagging.py --scenario fresh-tags --target-seconds 30
+  python3 benchmarks/tagging.py --scenario fresh-tags --target-seconds 30 --passive
+  python3 benchmarks/tagging.py --scenario precreated-tags --target-seconds 30
+  python3 benchmarks/tagging.py --scenario precreated-tags --target-seconds 30 --passive
+- Current result, fresh-tags:
+  regular:
+    object_count=10000
+    batch_size=1000
+    tags_per_batch=1
+    batches=1442
+    elapsed_seconds=30.012787
+    tag_assignments=1442000
+    tag_assignments_per_second=48046.187
+  passive:
+    object_count=10000
+    batch_size=1000
+    tags_per_batch=1
+    batches=1546
+    elapsed_seconds=30.021849
+    tag_assignments=1546000
+    tag_assignments_per_second=51495.829
+- Current result, precreated-tags:
+  regular:
+    object_count=10000
+    batch_size=1000
+    tags_per_batch=1
+    precreated_tag_count=5000
+    batches=1334
+    elapsed_seconds=30.006962
+    tag_assignments=1334000
+    tag_assignments_per_second=44456.349
+  passive:
+    object_count=10000
+    batch_size=1000
+    tags_per_batch=1
+    precreated_tag_count=5000
+    batches=1484
+    elapsed_seconds=30.018302
+    tag_assignments=1484000
+    tag_assignments_per_second=49436.507
+"""
+
+import argparse
+import gc
+import os
+import platform
+import tempfile
+import time
+
+import dbzero as db0
+
+
+@db0.memo
+class TagBenchmarkMemo:
+    def __init__(self, value):
+        self.value = value
+
+
+def read_cpu_model():
+    try:
+        with open("/proc/cpuinfo", "r", encoding="utf-8") as cpuinfo:
+            for line in cpuinfo:
+                if line.startswith("model name"):
+                    return line.split(":", 1)[1].strip()
+    except OSError:
+        pass
+    return platform.processor() or "unknown"
+
+
+def prepare_objects(object_count, batch_size):
+    objects = [TagBenchmarkMemo(i) for i in range(object_count)]
+    db0.commit()
+    target_objects = objects[:batch_size]
+    db0.tags(*target_objects).add("tagging-benchmark-anchor")
+    db0.commit()
+    return objects, target_objects
+
+
+def prepare_precreated_tags(tag_count, passive):
+    tag_owner = TagBenchmarkMemo(-1)
+    db0.commit()
+    tags = [
+        f"{'passive' if passive else 'regular'}-precreated-tag-{index}"
+        for index in range(tag_count)
+    ]
+    db0.tags(tag_owner, passive=passive).add(tags)
+    db0.commit()
+    return tag_owner, tags
+
+
+def apply_tag_batch(target_objects, tags, passive):
+    db0.tags(*target_objects, passive=passive).add(tags)
+    db0.commit()
+    return len(target_objects) * len(tags)
+
+
+def fresh_tag_batch(passive, batch_index, tags_per_batch):
+    return [
+        f"{'passive' if passive else 'regular'}-fresh-tag-{batch_index}-{index}"
+        for index in range(tags_per_batch)
+    ]
+
+
+def precreated_tag_batch(tags, batch_index, tags_per_batch):
+    start = batch_index * tags_per_batch
+    end = start + tags_per_batch
+    if end > len(tags):
+        return None
+    return tags[start:end]
+
+
+def measure(target_objects, passive, target_seconds, tags_per_batch, tag_batch_factory):
+    total_assignments = 0
+    batches = 0
+    exhausted_tags = False
+    gc_was_enabled = gc.isenabled()
+    gc.disable()
+    try:
+        start = time.perf_counter()
+        deadline = start + target_seconds
+        while True:
+            tags = tag_batch_factory(batches)
+            if tags is None:
+                exhausted_tags = True
+                break
+            total_assignments += apply_tag_batch(target_objects, tags, passive)
+            batches += 1
+            if time.perf_counter() >= deadline:
+                break
+        elapsed = time.perf_counter() - start
+    finally:
+        if gc_was_enabled:
+            gc.enable()
+    return elapsed, total_assignments, batches, exhausted_tags
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--scenario",
+        choices=("fresh-tags", "precreated-tags"),
+        default="fresh-tags",
+    )
+    parser.add_argument("--passive", action="store_true", help="assign passive tags")
+    parser.add_argument("--target-seconds", type=float, default=30.0)
+    parser.add_argument("--object-count", type=int, default=10000)
+    parser.add_argument("--batch-size", type=int, default=1000)
+    parser.add_argument("--tags-per-batch", type=int, default=1)
+    parser.add_argument(
+        "--precreated-tag-count",
+        type=int,
+        default=5000,
+        help="number of tag keys to create before timing in the precreated-tags scenario",
+    )
+    args = parser.parse_args()
+
+    if args.object_count < args.batch_size:
+        parser.error("--object-count must be greater than or equal to --batch-size")
+    if args.batch_size <= 0:
+        parser.error("--batch-size must be positive")
+    if args.tags_per_batch <= 0:
+        parser.error("--tags-per-batch must be positive")
+    if args.precreated_tag_count <= 0:
+        parser.error("--precreated-tag-count must be positive")
+
+    with tempfile.TemporaryDirectory() as root:
+        db0.init(root)
+        db0.open("tagging-throughput-benchmark")
+        objects, target_objects = prepare_objects(args.object_count, args.batch_size)
+        precreated_tag_owner = None
+        precreated_tags = None
+        if args.scenario == "precreated-tags":
+            if args.precreated_tag_count < args.tags_per_batch:
+                parser.error("--precreated-tag-count must cover at least one measured batch")
+            precreated_tag_owner, precreated_tags = prepare_precreated_tags(
+                args.precreated_tag_count,
+                args.passive,
+            )
+
+        if args.scenario == "fresh-tags":
+            tag_batch_factory = lambda batch: fresh_tag_batch(
+                args.passive,
+                batch,
+                args.tags_per_batch,
+            )
+        else:
+            tag_batch_factory = lambda batch: precreated_tag_batch(
+                precreated_tags,
+                batch,
+                args.tags_per_batch,
+            )
+
+        elapsed, assignments, batches, exhausted_tags = measure(
+            target_objects,
+            args.passive,
+            args.target_seconds,
+            args.tags_per_batch,
+            tag_batch_factory,
+        )
+
+        print(f"cpu={read_cpu_model()}")
+        print(f"python={platform.python_version()}")
+        print(f"build_flags={db0.build_flags()}")
+        print(f"pid={os.getpid()}")
+        print(f"scenario={args.scenario}")
+        print(f"passive={args.passive}")
+        print(f"object_count={len(objects)}")
+        print(f"batch_size={args.batch_size}")
+        print(f"tags_per_batch={args.tags_per_batch}")
+        print(f"precreated_tag_count={len(precreated_tags) if precreated_tags is not None else 0}")
+        print(f"precreated_tag_owner_kept={precreated_tag_owner is not None}")
+        print(f"batches={batches}")
+        print(f"elapsed_seconds={elapsed:.6f}")
+        print(f"tag_assignments={assignments}")
+        print(f"tag_assignments_per_second={assignments / elapsed if elapsed else 0:.3f}")
+        print(f"seconds_per_batch={elapsed / batches if batches else 0:.6f}")
+        print(f"exhausted_tags={exhausted_tags}")
+
+
+if __name__ == "__main__":
+    main()

{dbzero-0.3.3 → dbzero-0.3.5}/dbzero/dbzero/__init__.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2025 DBZero Software sp. z o.o.
 
 from .dbzero import *
-from .dbzero import _check_interned, _init_data_filter, _init_data_masking
+from .dbzero import _check_interned, _in_read_only, _init_data_filter, _init_data_masking
 from .memo import *
 from .enum import *
 from .fast_query import *
@@ -10,6 +10,7 @@ from .reflection_api import *
 from .storage_api import *
 from .atomic import *
 from .locked import *
+from .read_only import *
 from .utilities import taggify
 from .decorators import *
 from .select import *

dbzero-0.3.5/dbzero/dbzero/atomic.py

@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright (c) 2025 DBZero Software sp. z o.o.
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import threading
+import weakref
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+from .interfaces import Memo
+from .dbzero import _in_read_only, begin_atomic, begin_async_atomic, assign
+
+
+_async_atomic_locks: weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, asyncio.Lock] = weakref.WeakKeyDictionary()
+_async_atomic_locks_guard = threading.Lock()
+
+
+@dataclass(frozen=True)
+class _AsyncAtomicState:
+    owner_task: asyncio.Task
+    depth: int
+    lock: asyncio.Lock
+
+
+_async_atomic_state: contextvars.ContextVar[Optional[_AsyncAtomicState]] = contextvars.ContextVar(
+    "dbzero_async_atomic_state",
+    default=None,
+)
+
+
+class _NoOpAtomicContext:
+    def close(self):
+        pass
+
+    def cancel(self):
+        pass
+
+
+_NO_OP_ATOMIC_CONTEXT = _NoOpAtomicContext()
+
+
+def _current_async_task() -> Optional[asyncio.Task]:
+    try:
+        return asyncio.current_task()
+    except RuntimeError:
+        return None
+
+
+def _get_async_atomic_lock(loop: asyncio.AbstractEventLoop) -> asyncio.Lock:
+    with _async_atomic_locks_guard:
+        lock = _async_atomic_locks.get(loop)
+        if lock is None:
+            lock = asyncio.Lock()
+            _async_atomic_locks[loop] = lock
+        return lock
+
+
+class AtomicManager:
+    """Context manager that provides atomic context functionality for dbzero operations.
+
+    It is intended for use in a 'with' statement. 
+    """
+
+    def __init__(self):
+        self.__ctx = None
+
+    def __enter__(self) -> AtomicManager:
+        self.begin()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        if exc_type is None:
+            self.close()
+        else:
+            self.cancel()
+
+    def begin(self):
+        """Begin the atomic context"""
+        if self.__ctx is None:
+            self.__ctx = _NO_OP_ATOMIC_CONTEXT if _in_read_only() else begin_atomic()
+
+    def close(self):
+        """Close the atomic context, staging the changes for commit"""
+        if self.__ctx is None:
+            return
+
+        self.__ctx.close()
+        self.__ctx = None
+
+    def cancel(self):
+        """Cancel the atomic context, reverting all changes"""
+        if self.__ctx is None:
+            return
+
+        self.__ctx.cancel()
+        self.__ctx = None
+
+
+def atomic() -> AtomicManager:
+    """Open a context manager to group multiple mutating operations into a single indivisible transaction.
+
+    This function ensures that all modifications within  the `with` block are applied together, or none are applied at all.
+    If the block completes successfully, all changes are merged into the current 
+    transaction. If an exception occurs inside the block, or if the transaction is 
+    manually canceled, all changes are reverted, leaving the data in its previous state.
+
+    Returns
+    -------
+    AtomicManager
+        A context manager that provides atomic context functionality.
+
+    Examples
+    --------
+    Grouping successful operations:
+    
+    >>> obj1 = MyMemoClass("initial value")
+    >>> with dbzero.atomic():
+    ...     obj1.value = "updated value"
+    ...     obj2 = MyMemoClass("new object")
+    ...     dbzero.tags(obj2).add("new")
+    >>> # Both changes are now visible
+    >>> assert obj1.value == "updated value"
+
+    Automatic rollback on exception:
+    
+    >>> obj = MyMemoClass(value=100)
+    >>> try:
+    ...     with dbzero.atomic():
+    ...         obj.value = 200  # This change will be reverted
+    ...         raise ValueError("Something went wrong")
+    ... except ValueError:
+    ...     print("Caught expected error.")
+    >>> # The object's value is unchanged
+    >>> assert obj.value == 100
+
+    Manual rollback with cancel():
+    
+    >>> obj = MyMemoClass(value=100)
+    >>> with dbzero.atomic() as atomic:
+    ...     obj.value = 200
+    ...     if obj.value > 150:
+    ...         print("Value too high, canceling.")
+    ...         atomic.cancel()
+    >>> # The changes were discarded
+    >>> assert obj.value == 100
+
+    Notes
+    -----
+    An atomic() block does not immediately create a new, committed transaction or 
+    increment the global state number. Instead, the changes are staged 
+    and applied as part of the surrounding transaction, which is then committed 
+    either manually via dbzero.commit() or by the autocommit mechanism.
+    """
+    return AtomicManager()
+
+
+class AsyncAtomicManager:
+    """Async context manager for dbzero atomic operations in asyncio tasks."""
+
+    def __init__(self):
+        self.__ctx = None
+        self.__state_token = None
+        self.__lock = None
+        self.__release_lock = False
+
+    async def __aenter__(self) -> AsyncAtomicManager:
+        if _in_read_only():
+            self.__ctx = _NO_OP_ATOMIC_CONTEXT
+            return self
+
+        task = _current_async_task()
+        if task is None:
+            raise RuntimeError("db0.async_atomic requires a running asyncio task")
+
+        state = _async_atomic_state.get()
+        if state is not None and state.owner_task is task:
+            self.__lock = state.lock
+            next_state = _AsyncAtomicState(task, state.depth + 1, state.lock)
+        else:
+            loop = asyncio.get_running_loop()
+            self.__lock = _get_async_atomic_lock(loop)
+            await self.__lock.acquire()
+            self.__release_lock = True
+            next_state = _AsyncAtomicState(task, 1, self.__lock)
+
+        try:
+            self.__ctx = begin_async_atomic()
+        except BaseException:
+            if self.__release_lock and self.__lock is not None:
+                self.__lock.release()
+            self.__release_lock = False
+            self.__lock = None
+            raise
+
+        self.__state_token = _async_atomic_state.set(next_state)
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        try:
+            if exc_type is None:
+                self.close()
+            else:
+                self.cancel()
+        finally:
+            if self.__state_token is not None:
+                _async_atomic_state.reset(self.__state_token)
+                self.__state_token = None
+            if self.__release_lock and self.__lock is not None:
+                self.__lock.release()
+            self.__release_lock = False
+            self.__lock = None
+
+    def close(self):
+        """Close the atomic context, staging the changes for commit."""
+        if self.__ctx is None:
+            return
+
+        self.__ctx.close()
+        self.__ctx = None
+
+    def cancel(self):
+        """Cancel the atomic context, reverting all changes."""
+        if self.__ctx is None:
+            return
+
+        self.__ctx.cancel()
+        self.__ctx = None
+
+
+def async_atomic() -> AsyncAtomicManager:
+    """Open an asyncio-aware atomic context manager for dbzero operations."""
+    if _current_async_task() is None:
+        raise RuntimeError("db0.async_atomic requires a running asyncio task")
+    return AsyncAtomicManager()
+
+
+def atomic_assign(*objects: Memo, **attributes: Dict[str, Any]) -> None:
+    """Perform bulk attribute updates on one or more Memo objects within an atomic transaction.
+
+    This is a helper function that performs `dbzero.assign` operation in an atomic context.
+
+    Parameters
+    ----------
+    *objects : Any
+        A variable number of Memo objects to modify.
+    **attributes : Dict[str, Any]
+        The attributes to update, provided as name=value pairs where each key is 
+        the name of an attribute to update and the corresponding value is the new 
+        value to assign.
+    """
+    with atomic():
+        assign(*objects, **attributes)

{dbzero-0.3.3 → dbzero-0.3.5}/dbzero/dbzero/dbzero.py

@@ -10,7 +10,7 @@ def load_dynamic(name, path):
 
 def __bootstrap__():
     global __bootstrap__, __loader__, __file__
-    paths = [os.path.join(os.path.split(__file__)[0]), "/src/dev/build/debug", "/usr/local/lib/python3/dist-packages/dbzero/"]
+    paths = [os.path.join(os.path.split(__file__)[0]), "/src/dev/build/release", "/usr/local/lib/python3/dist-packages/dbzero/"]
     __file__ = None
     for path in paths:
         if os.path.isdir(path):