oj-persistence 0.0.1__tar.gz

oj_persistence-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ownjoo.org
+
+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.

oj_persistence-0.0.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: oj-persistence
+Version: 0.0.1
+Summary: Thread-safe persistence management with pluggable storage backends
+Author-email: Speedy <speedy@ownjoo.org>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ownjoo-org/persistence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ijson
+Dynamic: license-file
+
+# oj-persistence
+
+Thread-safe persistence management with pluggable storage backends.
+
+## Installation
+
+```bash
+pip install oj-persistence
+```
+
+## Overview
+
+`oj-persistence` provides a singleton `PersistenceManager` that acts as the single I/O interface for all data operations. Callers register named stores with the manager and interact exclusively through it — stores are never touched directly for data operations.
+
+Designed for use with multi-threaded applications and async pipelines (e.g. [`io_chains`](https://github.com/ownjoo-org/io_chains)).
+
+## Quick start
+
+```python
+from oj_persistence import PersistenceManager, InMemoryStore, NdjsonFileStore
+
+pm = PersistenceManager()
+
+# Register stores by name
+pm.get_or_create('cache', lambda: InMemoryStore())
+pm.get_or_create('events', lambda: NdjsonFileStore('events.ndjson'))
+
+# All data ops go through the manager
+pm.create('cache', 'user:1', {'name': 'Alice'})
+pm.upsert('events', 'evt:1', {'type': 'login', 'user': 'user:1'})
+
+value = pm.read('cache', 'user:1')   # {'name': 'Alice'}
+pm.update('cache', 'user:1', {'name': 'Alice', 'role': 'admin'})
+pm.delete('cache', 'user:1')
+
+results = pm.list('cache', predicate=lambda v: v.get('role') == 'admin')
+```
+
+## CRUDL semantics
+
+| Method     | Behaviour                                      |
+|------------|------------------------------------------------|
+| `create`   | Raises `KeyError` if key already exists        |
+| `read`     | Returns `None` if key is missing               |
+| `update`   | Raises `KeyError` if key does not exist        |
+| `upsert`   | Creates or overwrites — never raises           |
+| `delete`   | No-op if key is missing                        |
+| `list`     | Returns all values, optionally filtered        |
+
+## Relational joins
+
+```python
+ON = lambda user, order: user['id'] == order['user_id']
+
+results = pm.join('users', 'orders', on=ON, how='left',
+                  where=lambda u, o: o['total'] > 100)
+# returns list of (left, right) tuples; unmatched rows have None on the missing side
+```
+
+Supported `how` values: `inner` (default), `left`, `right`, `outer`.
+
+## Storage backends
+
+| Class           | Format                    | Notes                              |
+|-----------------|---------------------------|------------------------------------|
+| `InMemoryStore` | In-process dict           | Fastest; not persistent            |
+| `FlatFileStore` | JSON (full load/save)     | Simple; loads entire file per op   |
+| `NdjsonFileStore` | NDJSON (one obj/line)   | Append-only creates; O(1) writes   |
+| `IjsonFileStore` | Standard JSON (streaming) | Streaming reads via `ijson`        |
+| `CsvFileStore`  | CSV                       | Fieldnames inferred or pre-specified |
+
+All file-backed stores are thread-safe via a writer-preferring `ReadWriteLock`.
+
+## Custom stores
+
+Implement `AbstractStore`:
+
+```python
+from oj_persistence.store.base import AbstractStore
+
+class MyStore(AbstractStore):
+    def create(self, key, value): ...
+    def read(self, key): ...
+    def update(self, key, value): ...
+    def upsert(self, key, value): ...
+    def delete(self, key): ...
+    def list(self, predicate=None): ...
+
+pm.register('custom', MyStore())
+```
+
+## Requirements
+
+- Python >= 3.11
+- `ijson` (for `IjsonFileStore`)

oj_persistence-0.0.1/README.md

@@ -0,0 +1,95 @@
+# oj-persistence
+
+Thread-safe persistence management with pluggable storage backends.
+
+## Installation
+
+```bash
+pip install oj-persistence
+```
+
+## Overview
+
+`oj-persistence` provides a singleton `PersistenceManager` that acts as the single I/O interface for all data operations. Callers register named stores with the manager and interact exclusively through it — stores are never touched directly for data operations.
+
+Designed for use with multi-threaded applications and async pipelines (e.g. [`io_chains`](https://github.com/ownjoo-org/io_chains)).
+
+## Quick start
+
+```python
+from oj_persistence import PersistenceManager, InMemoryStore, NdjsonFileStore
+
+pm = PersistenceManager()
+
+# Register stores by name
+pm.get_or_create('cache', lambda: InMemoryStore())
+pm.get_or_create('events', lambda: NdjsonFileStore('events.ndjson'))
+
+# All data ops go through the manager
+pm.create('cache', 'user:1', {'name': 'Alice'})
+pm.upsert('events', 'evt:1', {'type': 'login', 'user': 'user:1'})
+
+value = pm.read('cache', 'user:1')   # {'name': 'Alice'}
+pm.update('cache', 'user:1', {'name': 'Alice', 'role': 'admin'})
+pm.delete('cache', 'user:1')
+
+results = pm.list('cache', predicate=lambda v: v.get('role') == 'admin')
+```
+
+## CRUDL semantics
+
+| Method     | Behaviour                                      |
+|------------|------------------------------------------------|
+| `create`   | Raises `KeyError` if key already exists        |
+| `read`     | Returns `None` if key is missing               |
+| `update`   | Raises `KeyError` if key does not exist        |
+| `upsert`   | Creates or overwrites — never raises           |
+| `delete`   | No-op if key is missing                        |
+| `list`     | Returns all values, optionally filtered        |
+
+## Relational joins
+
+```python
+ON = lambda user, order: user['id'] == order['user_id']
+
+results = pm.join('users', 'orders', on=ON, how='left',
+                  where=lambda u, o: o['total'] > 100)
+# returns list of (left, right) tuples; unmatched rows have None on the missing side
+```
+
+Supported `how` values: `inner` (default), `left`, `right`, `outer`.
+
+## Storage backends
+
+| Class           | Format                    | Notes                              |
+|-----------------|---------------------------|------------------------------------|
+| `InMemoryStore` | In-process dict           | Fastest; not persistent            |
+| `FlatFileStore` | JSON (full load/save)     | Simple; loads entire file per op   |
+| `NdjsonFileStore` | NDJSON (one obj/line)   | Append-only creates; O(1) writes   |
+| `IjsonFileStore` | Standard JSON (streaming) | Streaming reads via `ijson`        |
+| `CsvFileStore`  | CSV                       | Fieldnames inferred or pre-specified |
+
+All file-backed stores are thread-safe via a writer-preferring `ReadWriteLock`.
+
+## Custom stores
+
+Implement `AbstractStore`:
+
+```python
+from oj_persistence.store.base import AbstractStore
+
+class MyStore(AbstractStore):
+    def create(self, key, value): ...
+    def read(self, key): ...
+    def update(self, key, value): ...
+    def upsert(self, key, value): ...
+    def delete(self, key): ...
+    def list(self, predicate=None): ...
+
+pm.register('custom', MyStore())
+```
+
+## Requirements
+
+- Python >= 3.11
+- `ijson` (for `IjsonFileStore`)

oj_persistence-0.0.1/oj_persistence/__init__.py

@@ -0,0 +1,17 @@
+from oj_persistence.manager import PersistenceManager
+from oj_persistence.store.base import AbstractStore
+from oj_persistence.store.csv_file import CsvFileStore
+from oj_persistence.store.flat_file import FlatFileStore
+from oj_persistence.store.ijson_file import IjsonFileStore
+from oj_persistence.store.in_memory import InMemoryStore
+from oj_persistence.store.ndjson_file import NdjsonFileStore
+
+__all__ = [
+    'PersistenceManager',
+    'AbstractStore',
+    'CsvFileStore',
+    'FlatFileStore',
+    'IjsonFileStore',
+    'InMemoryStore',
+    'NdjsonFileStore',
+]

oj_persistence-0.0.1/oj_persistence/manager.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable, Optional
+
+from oj_persistence.store.base import AbstractStore
+
+_VALID_JOIN_TYPES = {'inner', 'left', 'right', 'outer'}
+
+
+class PersistenceManager:
+    """
+    Singleton registry of named AbstractStore instances.
+
+    One instance per process — all threads share the same registry.
+    Thread safety is guaranteed by a class-level lock during construction
+    and an instance-level lock for registry mutations.
+
+    Correct usage — all data operations go through the manager:
+
+        pm = PersistenceManager()
+        pm.get_or_create('users', lambda: InMemoryStore())   # register once
+        pm.create('users', 'u1', {'name': 'Alice'})
+        pm.read('users', 'u1')
+        pm.update('users', 'u1', {'name': 'Bob'})
+        pm.upsert('users', 'u1', {'name': 'Charlie'})
+        pm.delete('users', 'u1')
+        pm.list('users')
+        pm.join('users', 'orders', on=lambda u, o: u['id'] == o['user_id'])
+
+    Stores are thread-safe independently (RWLock), but the correct usage model
+    is that threads share only the manager singleton — they never hold a
+    reference to a store and call its methods directly.
+    """
+
+    _instance: Optional['PersistenceManager'] = None
+    _init_lock: threading.Lock = threading.Lock()
+
+    def __new__(cls) -> 'PersistenceManager':
+        if cls._instance is None:
+            with cls._init_lock:
+                if cls._instance is None:
+                    instance = super().__new__(cls)
+                    instance._stores: dict[str, AbstractStore] = {}
+                    instance._registry_lock = threading.Lock()
+                    cls._instance = instance
+        return cls._instance
+
+    def get_or_create(self, name: str, factory: Callable[[], AbstractStore]) -> AbstractStore:
+        """
+        Return the store registered under name, creating it via factory if absent.
+
+        The factory is called at most once per name. Subsequent calls with the
+        same name return the existing store regardless of the factory provided.
+        Thread-safe: factory is never called concurrently for the same name.
+        """
+        store = self._stores.get(name)
+        if store is None:
+            with self._registry_lock:
+                store = self._stores.get(name)
+                if store is None:
+                    store = factory()
+                    self._stores[name] = store
+        return store
+
+    def register(self, name: str, store: AbstractStore) -> None:
+        """Register a store under name, replacing any existing entry."""
+        with self._registry_lock:
+            self._stores[name] = store
+
+    def get_store(self, name: str) -> Optional[AbstractStore]:
+        """Return the store registered under name, or None."""
+        return self._stores.get(name)
+
+    def unregister(self, name: str) -> None:
+        """Remove the store registered under name. No-op if not found."""
+        with self._registry_lock:
+            self._stores.pop(name, None)
+
+    # ------------------------------------------------------------------
+    # CRUDL — the primary data interface for callers
+    # ------------------------------------------------------------------
+
+    def _get_required(self, name: str) -> AbstractStore:
+        store = self._stores.get(name)
+        if store is None:
+            raise KeyError(name)
+        return store
+
+    def create(self, store_name: str, key: str, value: Any) -> None:
+        """Create a new entry in the named store. Raises KeyError if store or key already exists."""
+        self._get_required(store_name).create(key, value)
+
+    def read(self, store_name: str, key: str) -> Any:
+        """Return the value for key from the named store, or None if not found."""
+        return self._get_required(store_name).read(key)
+
+    def update(self, store_name: str, key: str, value: Any) -> None:
+        """Update an existing entry. Raises KeyError if store or key not found."""
+        self._get_required(store_name).update(key, value)
+
+    def upsert(self, store_name: str, key: str, value: Any) -> None:
+        """Create or overwrite an entry in the named store."""
+        self._get_required(store_name).upsert(key, value)
+
+    def delete(self, store_name: str, key: str) -> None:
+        """Remove an entry from the named store. No-op if key not found."""
+        self._get_required(store_name).delete(key)
+
+    def list(self, store_name: str, predicate: Optional[Callable[[Any], bool]] = None) -> list[Any]:
+        """Return all values from the named store, optionally filtered by predicate."""
+        return self._get_required(store_name).list(predicate)
+
+    def join(
+        self,
+        left: str,
+        right: str,
+        on: Callable[[Any, Any], bool],
+        how: str = 'inner',
+        where: Optional[Callable[[Any, Any], bool]] = None,
+    ) -> list[tuple[Any, Any]]:
+        """
+        Relational join across two registered stores.
+
+        Parameters
+        ----------
+        left, right : store names (must be registered)
+        on          : join predicate — called as on(left_val, right_val)
+        how         : 'inner' | 'left' | 'right' | 'outer'
+        where       : optional filter applied only to matched pairs (both non-None);
+                      unmatched rows produced by left/right/outer are always included
+
+        Returns
+        -------
+        list of (left_val, right_val) tuples. Unmatched sides are None.
+
+        Complexity
+        ----------
+        O(m × n) — naive nested loop over store.list() on both sides.
+        DB-backed stores (SQLite, Postgres, SQLAlchemy, …) should override
+        with a delegated query rather than relying on this implementation.
+        """
+        if how not in _VALID_JOIN_TYPES:
+            raise ValueError(f"Invalid how='{how}'. Expected one of: {sorted(_VALID_JOIN_TYPES)}")
+
+        left_vals = self._get_required(left).list()
+        right_vals = self._get_required(right).list()
+        results: list[tuple[Any, Any]] = []
+
+        if how == 'inner':
+            for lv in left_vals:
+                for rv in right_vals:
+                    if on(lv, rv) and (where is None or where(lv, rv)):
+                        results.append((lv, rv))
+
+        elif how == 'left':
+            for lv in left_vals:
+                has_on_match = False
+                for rv in right_vals:
+                    if on(lv, rv):
+                        has_on_match = True
+                        if where is None or where(lv, rv):
+                            results.append((lv, rv))
+                if not has_on_match:
+                    results.append((lv, None))
+
+        elif how == 'right':
+            for rv in right_vals:
+                has_on_match = False
+                for lv in left_vals:
+                    if on(lv, rv):
+                        has_on_match = True
+                        if where is None or where(lv, rv):
+                            results.append((lv, rv))
+                if not has_on_match:
+                    results.append((None, rv))
+
+        elif how == 'outer':
+            matched_right: set[int] = set()
+            for lv in left_vals:
+                has_on_match = False
+                for i, rv in enumerate(right_vals):
+                    if on(lv, rv):
+                        has_on_match = True
+                        matched_right.add(i)
+                        if where is None or where(lv, rv):
+                            results.append((lv, rv))
+                if not has_on_match:
+                    results.append((lv, None))
+            for i, rv in enumerate(right_vals):
+                if i not in matched_right:
+                    results.append((None, rv))
+
+        return results

oj_persistence-0.0.1/oj_persistence/store/__init__.py

@@ -0,0 +1,15 @@
+from oj_persistence.store.base import AbstractStore
+from oj_persistence.store.csv_file import CsvFileStore
+from oj_persistence.store.flat_file import FlatFileStore
+from oj_persistence.store.ijson_file import IjsonFileStore
+from oj_persistence.store.in_memory import InMemoryStore
+from oj_persistence.store.ndjson_file import NdjsonFileStore
+
+__all__ = [
+    'AbstractStore',
+    'CsvFileStore',
+    'FlatFileStore',
+    'IjsonFileStore',
+    'InMemoryStore',
+    'NdjsonFileStore',
+]

oj_persistence-0.0.1/oj_persistence/store/base.py

@@ -0,0 +1,44 @@
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Optional
+
+
+class AbstractStore(ABC):
+    """
+    CRUDL interface for all persistence backends.
+
+    Strict create/update semantics:
+      - create() raises KeyError if the key already exists
+      - update() raises KeyError if the key does not exist
+      - upsert() always succeeds (create or update)
+      - read()   returns None for missing keys (no raise)
+      - delete() is a no-op for missing keys (no raise)
+      - list()   returns all values, optionally filtered by predicate
+
+    Implementations must be thread-safe. Async variants are planned for a
+    future release to support io_chains integration as an async source or
+    subscriber.
+    """
+
+    @abstractmethod
+    def create(self, key: str, value: Any) -> None:
+        """Store value under key. Raises KeyError if key already exists."""
+
+    @abstractmethod
+    def read(self, key: str) -> Any:
+        """Return the value for key, or None if not found."""
+
+    @abstractmethod
+    def update(self, key: str, value: Any) -> None:
+        """Update value for an existing key. Raises KeyError if not found."""
+
+    @abstractmethod
+    def upsert(self, key: str, value: Any) -> None:
+        """Store value under key, creating or overwriting as needed."""
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Remove the entry for key. No-op if key does not exist."""
+
+    @abstractmethod
+    def list(self, predicate: Optional[Callable[[Any], bool]] = None) -> list[Any]:
+        """Return all values, or only those for which predicate(value) is True."""