psycache 26.1.0__py3-none-any.whl

psycache/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+from ._async import AsyncCleanupService, AsyncPostgresCache
+from ._sync import CleanupService, PostgresCache
+from ._tables import init_db
+from .typing import CacheInstrumentation
+
+
+__all__ = [
+    "AsyncCleanupService",
+    "AsyncPostgresCache",
+    "CacheInstrumentation",
+    "CleanupService",
+    "PostgresCache",
+    "init_db",
+]

psycache/__main__.py

@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+import argparse
+import sys
+
+from collections.abc import Sequence
+
+import psycopg
+
+from ._tables import init_db
+
+
+def _do_init_db(dsn: str) -> int:
+    try:
+        with psycopg.connect(dsn, autocommit=True) as conn:
+            init_db(conn)
+    except psycopg.Error as e:
+        print(f"psycache: init-db failed: {e}", file=sys.stderr)
+        return 1
+
+    print("psycache: initialized the cache table.")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m psycache",
+        description="Maintenance commands for psycache.",
+    )
+    subparsers = parser.add_subparsers(required=True)
+
+    init_db_parser = subparsers.add_parser(
+        "init-db",
+        help="Create the psycache table and index.",
+        description="Create the psycache table and index in the database "
+        "identified by DSN.",
+    )
+    init_db_parser.add_argument(
+        "dsn",
+        metavar="DSN",
+        help="A libpq connection string, e.g. postgresql://user@host/db.",
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    return _do_init_db(args.dsn)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

psycache/_async.py

@@ -0,0 +1,203 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+import asyncio
+import datetime as dt
+import logging
+
+from collections.abc import Awaitable, Callable, Sequence
+from contextlib import suppress
+from typing import Any, Self
+
+import attrs
+
+from psycopg.types.json import Jsonb
+
+from . import _sql
+from ._durations import (
+    _coerce_cleanup_interval_seconds,
+    _coerce_stop_timeout_seconds,
+)
+from .instrumentation._spans import (
+    _cleanup_span,
+    _flush_span,
+    _lookup_span,
+    _put_span,
+    _remove_span,
+)
+from .typing import AsyncCachePool, CacheInstrumentation
+
+
+logger = logging.getLogger(__name__)
+
+
+async def _cleanup_loop(
+    cleanup: Callable[[], Awaitable[int]],
+    interval_seconds: float,
+    stop_event: asyncio.Event,
+) -> None:
+    while not stop_event.is_set():
+        try:
+            await cleanup()
+        except Exception:
+            logger.exception("Periodic cache cleanup failed")
+
+        with suppress(TimeoutError):
+            await asyncio.wait_for(stop_event.wait(), interval_seconds)
+
+
+@attrs.frozen
+class AsyncCleanupService:
+    """
+    Handle for a periodic cache cleanup task.
+
+    Can be used as an async context manager or stopped manually via `stop()`.
+    """
+
+    _task: asyncio.Task[None] = attrs.field(alias="task")
+    _stop_event: asyncio.Event = attrs.field(alias="stop_event")
+
+    async def stop(
+        self,
+        timeout: dt.timedelta | float | None = 5.0,  # noqa: ASYNC109
+    ) -> bool:
+        """
+        Stop the cleanup task and wait for it to finish.
+
+        Return whether the task exited before the timeout elapsed.
+        """
+        self._stop_event.set()
+        try:
+            await asyncio.wait_for(
+                asyncio.shield(self._task),
+                _coerce_stop_timeout_seconds(timeout),
+            )
+        except TimeoutError:
+            logger.warning(
+                "Cleanup task did not stop within timeout=%s", timeout
+            )
+            return False
+
+        return True
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.stop()
+
+
+@attrs.frozen
+class AsyncPostgresCache:
+    """
+    An asyncio-based Postgres cache.
+    """
+
+    pool: AsyncCachePool
+    instrumentations: Sequence[CacheInstrumentation] = attrs.field(
+        default=(), kw_only=True
+    )
+
+    async def get_raw(
+        self, key: str, span_name: str | None = None
+    ) -> dict[str, Any] | None:
+        with _lookup_span(self.instrumentations, key, span_name) as span:
+            async with self.pool.connect() as conn:
+                cur = await conn.execute(_sql.GET, (key,))
+                row = await cur.fetchone()
+
+            if row is None:
+                span.record_cache_miss()
+                return None
+
+            span.record_cache_hit(row[1])
+
+        return row[0]  # type: ignore[no-any-return]
+
+    async def put_raw(
+        self,
+        key: str,
+        value: dict[str, Any],
+        ttl: int | dt.timedelta,
+        span_name: str | None = None,
+    ) -> None:
+        with _put_span(self.instrumentations, key, span_name) as span:
+            if isinstance(ttl, int):
+                ttl = dt.timedelta(seconds=ttl)
+
+            expires_at = dt.datetime.now().astimezone() + ttl
+
+            async with self.pool.connect() as conn:
+                cur = await conn.execute(
+                    _sql.PUT, (key, Jsonb(value), expires_at)
+                )
+                row = await cur.fetchone()
+
+            span.record_put(row[0])  # type: ignore[index]  # ty: ignore[not-subscriptable]
+
+    async def remove(self, key: str) -> None:
+        with _remove_span(self.instrumentations, key) as span:
+            async with self.pool.connect() as conn:
+                await conn.execute(_sql.REMOVE, (key,))
+
+            span.record_removed()
+
+    async def cleanup_expired(self) -> int:
+        """
+        Delete all expired cache entries.
+
+        Return the number of deleted entries.
+        """
+        with _cleanup_span(self.instrumentations) as span:
+            async with self.pool.connect() as conn:
+                cur = await conn.execute(_sql.CLEANUP_EXPIRED)
+                num_deleted: int = cur.rowcount
+
+            span.record_cleanup(num_deleted)
+
+        return num_deleted
+
+    def start_cleanup_task(
+        self, interval: dt.timedelta | float
+    ) -> AsyncCleanupService:
+        """
+        Start a task that periodically deletes expired cache entries.
+
+        Must be called within a running asyncio event loop.
+
+        Args:
+            interval:
+                Time between cleanup runs. In seconds or as a timedelta.
+
+        Returns:
+            An `AsyncCleanupService` that can be used to stop the task.
+        """
+        interval_seconds = _coerce_cleanup_interval_seconds(interval)
+
+        stop_event = asyncio.Event()
+        task = asyncio.create_task(
+            _cleanup_loop(
+                self.cleanup_expired,
+                interval_seconds,
+                stop_event,
+            ),
+            name="psycache-cleanup",
+        )
+
+        return AsyncCleanupService(task=task, stop_event=stop_event)
+
+    async def flush(self) -> int:
+        """
+        Flush all cache entries.
+
+        Return the number of flushed entries.
+        """
+        with _flush_span(self.instrumentations) as span:
+            async with self.pool.connect() as conn:
+                cur = await conn.execute(_sql.FLUSH)
+                num_flushed: int = cur.rowcount
+
+            span.record_flush(num_flushed)
+
+        return num_flushed

psycache/_durations.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+import datetime as dt
+import math
+
+
+def _coerce_seconds(value: dt.timedelta | float, *, name: str) -> float:
+    seconds = (
+        value.total_seconds() if isinstance(value, dt.timedelta) else value
+    )
+
+    if not math.isfinite(seconds):
+        msg = f"{name} must be finite"
+        raise ValueError(msg)
+
+    return seconds
+
+
+def _coerce_stop_timeout_seconds(
+    timeout: dt.timedelta | float | None,
+    *,
+    max_seconds: float | None = None,
+) -> float | None:
+    if timeout is None:
+        return None
+
+    timeout_seconds = _coerce_seconds(timeout, name="stop timeout")
+    if timeout_seconds < 0:
+        msg = "stop timeout must be non-negative"
+        raise ValueError(msg)
+
+    if max_seconds is not None and timeout_seconds > max_seconds:
+        msg = f"stop timeout must not exceed {max_seconds}"
+        raise ValueError(msg)
+
+    return timeout_seconds
+
+
+def _coerce_cleanup_interval_seconds(
+    interval: dt.timedelta | float,
+    *,
+    max_seconds: float | None = None,
+) -> float:
+    interval_seconds = _coerce_seconds(interval, name="cleanup interval")
+    if interval_seconds <= 0:
+        msg = "cleanup interval must be positive"
+        raise ValueError(msg)
+
+    if max_seconds is not None and interval_seconds > max_seconds:
+        msg = f"cleanup interval must not exceed {max_seconds}"
+        raise ValueError(msg)
+
+    return interval_seconds

psycache/_sql.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+GET = """\
+SELECT value, pg_column_size(value)
+FROM psycache
+WHERE key = %s
+  AND expires_at > statement_timestamp()
+"""
+
+PUT = """\
+INSERT INTO psycache (key, value, expires_at)
+VALUES (%s, %s, %s)
+ON CONFLICT (key) DO UPDATE SET
+    value = EXCLUDED.value,
+    expires_at = EXCLUDED.expires_at
+RETURNING pg_column_size(value)
+"""
+
+REMOVE = """\
+DELETE FROM psycache
+WHERE key = %s
+"""
+
+CLEANUP_EXPIRED = """\
+DELETE FROM psycache
+WHERE expires_at < statement_timestamp()
+"""
+
+FLUSH = """\
+DELETE FROM psycache
+"""

psycache/_sync.py

@@ -0,0 +1,198 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+import datetime as dt
+import logging
+import threading
+
+from collections.abc import Callable, Sequence
+from typing import Any, Self
+
+import attrs
+
+from psycopg.types.json import Jsonb
+
+from . import _sql
+from ._durations import (
+    _coerce_cleanup_interval_seconds,
+    _coerce_stop_timeout_seconds,
+)
+from .instrumentation._spans import (
+    _cleanup_span,
+    _flush_span,
+    _lookup_span,
+    _put_span,
+    _remove_span,
+)
+from .typing import CacheInstrumentation, CachePool
+
+
+logger = logging.getLogger(__name__)
+
+
+def _cleanup_loop(
+    cleanup: Callable[[], int],
+    interval_seconds: float,
+    stop_event: threading.Event,
+) -> None:
+    while not stop_event.is_set():
+        try:
+            cleanup()
+        except Exception:
+            logger.exception("Periodic cache cleanup failed")
+
+        stop_event.wait(interval_seconds)
+
+
+@attrs.frozen
+class CleanupService:
+    """
+    Handle for a periodic cache cleanup thread.
+
+    Can be used as a context manager or stopped manually via `stop()`.
+    """
+
+    _thread: threading.Thread = attrs.field(alias="thread")
+    _stop_event: threading.Event = attrs.field(alias="stop_event")
+
+    def stop(self, timeout: dt.timedelta | float | None = 5.0) -> bool:
+        """
+        Stop the cleanup thread and wait for it to finish.
+
+        Return whether the thread exited before the timeout elapsed.
+        """
+        self._stop_event.set()
+        self._thread.join(
+            _coerce_stop_timeout_seconds(
+                timeout, max_seconds=threading.TIMEOUT_MAX
+            )
+        )
+
+        stopped = not self._thread.is_alive()
+        if not stopped:
+            logger.warning(
+                "Cleanup thread did not stop within timeout=%s", timeout
+            )
+
+        return stopped
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.stop()
+
+
+@attrs.frozen
+class PostgresCache:
+    """
+    A Postgres-based cache.
+    """
+
+    pool: CachePool
+    instrumentations: Sequence[CacheInstrumentation] = attrs.field(
+        default=(), kw_only=True
+    )
+
+    def get_raw(
+        self, key: str, span_name: str | None = None
+    ) -> dict[str, Any] | None:
+        with _lookup_span(self.instrumentations, key, span_name) as span:
+            with self.pool.connect() as conn:
+                row = conn.execute(_sql.GET, (key,)).fetchone()
+
+            if row is None:
+                span.record_cache_miss()
+                return None
+
+            span.record_cache_hit(row[1])
+
+        return row[0]  # type: ignore[no-any-return]
+
+    def put_raw(
+        self,
+        key: str,
+        value: dict[str, Any],
+        ttl: int | dt.timedelta,
+        span_name: str | None = None,
+    ) -> None:
+        with _put_span(self.instrumentations, key, span_name) as span:
+            if isinstance(ttl, int):
+                ttl = dt.timedelta(seconds=ttl)
+
+            expires_at = dt.datetime.now().astimezone() + ttl
+
+            with self.pool.connect() as conn:
+                row = conn.execute(
+                    _sql.PUT, (key, Jsonb(value), expires_at)
+                ).fetchone()
+
+            span.record_put(row[0])  # type: ignore[index]  # ty: ignore[not-subscriptable]
+
+    def remove(self, key: str) -> None:
+        with _remove_span(self.instrumentations, key) as span:
+            with self.pool.connect() as conn:
+                conn.execute(_sql.REMOVE, (key,))
+
+            span.record_removed()
+
+    def cleanup_expired(self) -> int:
+        """
+        Delete all expired cache entries.
+
+        Return the number of deleted entries.
+        """
+        with _cleanup_span(self.instrumentations) as span:
+            with self.pool.connect() as conn:
+                num_deleted: int = conn.execute(_sql.CLEANUP_EXPIRED).rowcount
+
+            span.record_cleanup(num_deleted)
+
+        return num_deleted
+
+    def flush(self) -> int:
+        """
+        Flush all cache entries.
+
+        Return the number of flushed entries.
+        """
+        with _flush_span(self.instrumentations) as span:
+            with self.pool.connect() as conn:
+                num_flushed: int = conn.execute(_sql.FLUSH).rowcount
+
+            span.record_flush(num_flushed)
+
+        return num_flushed
+
+    def start_cleanup_thread(
+        self, interval: dt.timedelta | float
+    ) -> CleanupService:
+        """
+        Start a daemon thread that periodically deletes expired cache entries.
+
+        Args:
+            interval:
+                Time between cleanup runs. In seconds or as a timedelta.
+
+        Returns:
+            A `CleanupService` that can be used to stop the thread.
+        """
+        interval_seconds = _coerce_cleanup_interval_seconds(
+            interval, max_seconds=threading.TIMEOUT_MAX
+        )
+
+        stop_event = threading.Event()
+        thread = threading.Thread(
+            name="psycache-cleanup",
+            target=_cleanup_loop,
+            args=(
+                self.cleanup_expired,
+                interval_seconds,
+                stop_event,
+            ),
+            daemon=True,
+        )
+        thread.start()
+
+        return CleanupService(thread=thread, stop_event=stop_event)

psycache/_tables.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+import psycopg
+
+
+_CREATE_TABLE = """\
+CREATE UNLOGGED TABLE IF NOT EXISTS psycache (
+    key text PRIMARY KEY,
+    value jsonb NOT NULL,
+    expires_at timestamptz NOT NULL
+)
+"""
+
+_CREATE_INDEX = """\
+CREATE INDEX IF NOT EXISTS ix_psycache_expires_at
+    ON psycache (expires_at)
+"""
+
+
+def init_db(conn: psycopg.Connection) -> None:
+    conn.execute(_CREATE_TABLE)
+    conn.execute(_CREATE_INDEX)

psycache/instrumentation/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Instrumentation for cache operations.
+"""
+
+from ._spans import NoopAnySpan
+
+
+__all__ = ["NoopAnySpan"]