refactor: improve function naming for clarity and consistency

Rename functions to use clearer verb-based names:
- pick_best_live_path → select_best_live_path
- escape_like_prefix → escape_sql_like_string
- list_tree → list_files_recursively
- check_asset_file_fast → verify_asset_file_unchanged
- _seed_from_paths_batch → _batch_insert_assets_from_paths
- reconcile_cache_states_for_root → sync_cache_states_with_filesystem
- touch_asset_info_by_id → update_asset_info_access_time
- replace_asset_info_metadata_projection → set_asset_info_metadata
- expand_metadata_to_rows → convert_metadata_to_rows
- _rows_per_stmt → _calculate_rows_per_statement
- ensure_within_base → validate_path_within_base
- _cleanup_temp → _delete_temp_file_if_exists
- validate_hash_format → normalize_and_validate_hash
- get_relative_to_root_category_path_of_asset → get_asset_category_and_relative_path

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/assets/database/queries/__init__.py

@@ -17,8 +17,8 @@ from app.assets.database.queries.asset_info import (
     list_asset_infos_page,
     fetch_asset_info_asset_and_tags,
     fetch_asset_info_and_asset,
-    touch_asset_info_by_id,
-    replace_asset_info_metadata_projection,
+    update_asset_info_access_time,
+    set_asset_info_metadata,
     delete_asset_info_by_id,
     set_asset_info_preview,
     bulk_insert_asset_infos_ignore_conflicts,
@@ -67,8 +67,8 @@ __all__ = [
     "list_asset_infos_page",
     "fetch_asset_info_asset_and_tags",
     "fetch_asset_info_and_asset",
-    "touch_asset_info_by_id",
-    "replace_asset_info_metadata_projection",
+    "update_asset_info_access_time",
+    "set_asset_info_metadata",
     "delete_asset_info_by_id",
     "set_asset_info_preview",
     "bulk_insert_asset_infos_ignore_conflicts",

app/assets/database/queries/asset.py

@@ -9,7 +9,7 @@ from app.assets.database.models import Asset
 MAX_BIND_PARAMS = 800
 
 
-def _rows_per_stmt(cols: int) -> int:
+def _calculate_rows_per_statement(cols: int) -> int:
     return max(1, MAX_BIND_PARAMS // max(1, cols))
 
 
@@ -90,5 +90,5 @@ def bulk_insert_assets(
     if not rows:
         return
     ins = sqlite.insert(Asset)
-    for chunk in _iter_chunks(rows, _rows_per_stmt(5)):
+    for chunk in _iter_chunks(rows, _calculate_rows_per_statement(5)):
         session.execute(ins, chunk)

app/assets/database/queries/asset_info.py

@@ -18,7 +18,7 @@ from sqlalchemy.orm import Session, contains_eager, noload
 from app.assets.database.models import (
     Asset, AssetInfo, AssetInfoMeta, AssetInfoTag, Tag
 )
-from app.assets.helpers import escape_like_prefix, normalize_tags, get_utc_now
+from app.assets.helpers import escape_sql_like_string, normalize_tags, get_utc_now
 
 
 def check_is_scalar(v):
@@ -31,7 +31,7 @@ def check_is_scalar(v):
     return False
 
 
-def expand_metadata_to_rows(key: str, value):
+def convert_metadata_to_rows(key: str, value):
     """
     Turn a metadata key/value into typed projection rows.
     Returns list[dict] with keys:
@@ -86,7 +86,7 @@ def expand_metadata_to_rows(key: str, value):
 MAX_BIND_PARAMS = 800
 
 
-def _rows_per_stmt(cols: int) -> int:
+def _calculate_rows_per_statement(cols: int) -> int:
     return max(1, MAX_BIND_PARAMS // max(1, cols))
 
 
@@ -296,7 +296,7 @@ def list_asset_infos_page(
     )
 
     if name_contains:
-        escaped, esc = escape_like_prefix(name_contains)
+        escaped, esc = escape_sql_like_string(name_contains)
         base = base.where(AssetInfo.name.ilike(f"%{escaped}%", escape=esc))
 
     base = _apply_tag_filters(base, include_tags, exclude_tags)
@@ -323,7 +323,7 @@ def list_asset_infos_page(
         .where(_build_visible_owner_clause(owner_id))
     )
     if name_contains:
-        escaped, esc = escape_like_prefix(name_contains)
+        escaped, esc = escape_sql_like_string(name_contains)
         count_stmt = count_stmt.where(AssetInfo.name.ilike(f"%{escaped}%", escape=esc))
     count_stmt = _apply_tag_filters(count_stmt, include_tags, exclude_tags)
     count_stmt = _apply_metadata_filter(count_stmt, metadata_filter)
@@ -401,7 +401,7 @@ def fetch_asset_info_and_asset(
     return pair[0], pair[1]
 
 
-def touch_asset_info_by_id(
+def update_asset_info_access_time(
     session: Session,
     asset_info_id: str,
     ts: datetime | None = None,
@@ -416,7 +416,7 @@ def touch_asset_info_by_id(
     session.execute(stmt.values(last_access_time=ts))
 
 
-def replace_asset_info_metadata_projection(
+def set_asset_info_metadata(
     session: Session,
     asset_info_id: str,
     user_metadata: dict | None = None,
@@ -437,7 +437,7 @@ def replace_asset_info_metadata_projection(
 
     rows: list[AssetInfoMeta] = []
     for k, v in user_metadata.items():
-        for r in expand_metadata_to_rows(k, v):
+        for r in convert_metadata_to_rows(k, v):
             rows.append(
                 AssetInfoMeta(
                     asset_info_id=asset_info_id,
@@ -501,7 +501,7 @@ def bulk_insert_asset_infos_ignore_conflicts(
     ins = sqlite.insert(AssetInfo).on_conflict_do_nothing(
         index_elements=[AssetInfo.asset_id, AssetInfo.owner_id, AssetInfo.name]
     )
-    for chunk in _iter_chunks(rows, _rows_per_stmt(9)):
+    for chunk in _iter_chunks(rows, _calculate_rows_per_statement(9)):
         session.execute(ins, chunk)
 
 

app/assets/database/queries/cache_state.py

@@ -7,7 +7,7 @@ from sqlalchemy.dialects import sqlite
 from sqlalchemy.orm import Session
 
 from app.assets.database.models import Asset, AssetCacheState, AssetInfo
-from app.assets.helpers import escape_like_prefix
+from app.assets.helpers import escape_sql_like_string
 
 MAX_BIND_PARAMS = 800
 
@@ -27,7 +27,7 @@ __all__ = [
 ]
 
 
-def _rows_per_stmt(cols: int) -> int:
+def _calculate_rows_per_statement(cols: int) -> int:
     return max(1, MAX_BIND_PARAMS // max(1, cols))
 
 
@@ -115,7 +115,7 @@ def delete_cache_states_outside_prefixes(session: Session, valid_prefixes: list[
 
     def make_prefix_condition(prefix: str):
         base = prefix if prefix.endswith(os.sep) else prefix + os.sep
-        escaped, esc = escape_like_prefix(base)
+        escaped, esc = escape_sql_like_string(base)
         return AssetCacheState.file_path.like(escaped + "%", escape=esc)
 
     matches_valid_prefix = sa.or_(*[make_prefix_condition(p) for p in valid_prefixes])
@@ -175,7 +175,7 @@ def get_cache_states_for_prefixes(
         base = os.path.abspath(p)
         if not base.endswith(os.sep):
             base += os.sep
-        escaped, esc = escape_like_prefix(base)
+        escaped, esc = escape_sql_like_string(base)
         conds.append(AssetCacheState.file_path.like(escaped + "%", escape=esc))
 
     rows = session.execute(
@@ -261,7 +261,7 @@ def bulk_insert_cache_states_ignore_conflicts(
     ins = sqlite.insert(AssetCacheState).on_conflict_do_nothing(
         index_elements=[AssetCacheState.file_path]
     )
-    for chunk in _iter_chunks(rows, _rows_per_stmt(3)):
+    for chunk in _iter_chunks(rows, _calculate_rows_per_statement(3)):
         session.execute(ins, chunk)
 
 

app/assets/database/queries/tags.py

@@ -7,12 +7,12 @@ from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from app.assets.database.models import AssetInfo, AssetInfoMeta, AssetInfoTag, Tag
-from app.assets.helpers import escape_like_prefix, normalize_tags, get_utc_now
+from app.assets.helpers import escape_sql_like_string, normalize_tags, get_utc_now
 
 MAX_BIND_PARAMS = 800
 
 
-def _rows_per_stmt(cols: int) -> int:
+def _calculate_rows_per_statement(cols: int) -> int:
     return max(1, MAX_BIND_PARAMS // max(1, cols))
 
 
@@ -262,7 +262,7 @@ def list_tags_with_usage(
     )
 
     if prefix:
-        escaped, esc = escape_like_prefix(prefix.strip().lower())
+        escaped, esc = escape_sql_like_string(prefix.strip().lower())
         q = q.where(Tag.name.like(escaped + "%", escape=esc))
 
     if not include_zero:
@@ -275,7 +275,7 @@ def list_tags_with_usage(
 
     total_q = select(func.count()).select_from(Tag)
     if prefix:
-        escaped, esc = escape_like_prefix(prefix.strip().lower())
+        escaped, esc = escape_sql_like_string(prefix.strip().lower())
         total_q = total_q.where(Tag.name.like(escaped + "%", escape=esc))
     if not include_zero:
         total_q = total_q.where(