From 378c6e3fef7f41c1caed9e39d77b169a7147b687 Mon Sep 17 00:00:00 2001
From: Goffi <goffi@goffi.org>
Date: Thu, 9 Apr 2026 13:41:11 +0200
Subject: [PATCH] memory (sqla): docstrings/type hints improvements

---
 libervia/backend/memory/sqla.py | 53 ++++++++++++++++++++-------------
 1 file changed, 33 insertions(+), 20 deletions(-)

diff --git a/libervia/backend/memory/sqla.py b/libervia/backend/memory/sqla.py
index f56b27c7..e873627f 100644
--- a/libervia/backend/memory/sqla.py
+++ b/libervia/backend/memory/sqla.py
@@ -18,13 +18,13 @@
 
 import asyncio
 from asyncio.subprocess import PIPE
-import copy
+from collections.abc import Callable, Iterable
 from datetime import datetime
 import json
 from pathlib import Path
 import sys
 import time
-from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 from alembic import config as al_config, script as al_script
 from alembic.runtime import migration as al_migration
@@ -332,11 +332,12 @@ class Storage:
             )
 
     @aio
-    async def create_profile(self, name: str, component_ep: Optional[str] = None) -> None:
+    async def create_profile(self, name: str, component_ep: str | None = None) -> Profile:
         """Create a new profile
 
         @param name: name of the profile
-        @param component: if not None, must point to a component entry point
+        @param component_ep: if not None, must point to a component entry point
+        @return: the created profile
         """
         async with self.session() as session:
             profile = Profile(name=name)
@@ -644,7 +645,8 @@ class Storage:
                     ).scalar_subquery()
                 )
             if "body" in filters:
-                # TODO: use REGEXP (function to be defined) instead of GLOB: https://www.sqlite.org/lang_expr.html
+                # TODO: use REGEXP (function to be defined) instead of GLOB:
+                #    https://www.sqlite.org/lang_expr.html
                 stmt = stmt.where(Message.message.like(f"%{filters['body']}%"))
             if "search" in filters:
                 search_term = f"%{filters['search']}%"
@@ -1520,13 +1522,17 @@ class Storage:
 
     @aio
     async def delete_pubsub_items(
-        self, node: PubsubNode, items_names: Optional[List[str]] = None
+        self,
+        node: PubsubNode | None,
+        items_names: list[str] | None = None,
     ) -> None:
-        """Delete items cached for a node
+        """Delete items from a node.
+
+        Used for pubsub operations like retract or purge.
 
         @param node: node from which items must be deleted
-        @param items_names: names of items to delete
-            if None, ALL items will be deleted
+        @param items_names: names of items to delete.
+            If None, deletes ALL items
         """
         stmt = delete(PubsubItem)
         if node is not None:
@@ -1543,19 +1549,26 @@ class Storage:
     @aio
     async def purge_pubsub_items(
         self,
-        services: Optional[List[jid.JID]] = None,
-        names: Optional[List[str]] = None,
-        types: Optional[List[str]] = None,
-        subtypes: Optional[List[str]] = None,
-        profiles: Optional[List[str]] = None,
-        created_before: Optional[datetime] = None,
-        updated_before: Optional[datetime] = None,
+        services: list[jid.JID] | None = None,
+        names: list[str] | None = None,
+        types: list[str] | None = None,
+        subtypes: list[str] | None = None,
+        profiles: list[str] | None = None,
+        created_before: datetime | None = None,
+        updated_before: datetime | None = None,
     ) -> None:
-        """Delete items cached for a node
+        """Bulk delete items for maintenance operations.
 
-        @param node: node from which items must be deleted
-        @param items_names: names of items to delete
-            if None, ALL items will be deleted
+        Deletes items across multiple nodes based on node properties or time criteria.
+        Used for administrative cleanup tasks.
+
+        @param services: filter by pubsub service JIDs
+        @param names: filter by node names
+        @param types: filter by node types
+        @param subtypes: filter by node subtypes
+        @param profiles: filter by profile names
+        @param created_before: delete items created before this datetime
+        @param updated_before: delete items updated before this datetime
         """
         stmt = delete(PubsubItem)
         node_fields = {