shortcutxl 0.2.19 → 0.2.21

package/xll/modules/shortcut_xl/_managed.py

@@ -22,11 +22,22 @@ from shortcut_xl.api.worksheet import Worksheet
 # Without __import__, `import X` is a syntax-level dead end: Python's import
 # machinery calls __builtins__.__import__ under the hood, and it's simply not
 # here.  This blocks pip, subprocess, os, ctypes — everything.
-_BLOCKED_BUILTINS = frozenset({
-    '__import__', 'open', 'eval', 'exec', 'compile',
-    'breakpoint', 'exit', 'quit', 'input',
-    'memoryview', '__loader__', '__spec__',
-})
+_BLOCKED_BUILTINS = frozenset(
+    {
+        '__import__',
+        'open',
+        'eval',
+        'exec',
+        'compile',
+        'breakpoint',
+        'exit',
+        'quit',
+        'input',
+        'memoryview',
+        '__loader__',
+        '__spec__',
+    }
+)
 _raw = __builtins__.__dict__ if hasattr(__builtins__, '__dict__') else __builtins__
 _SAFE_BUILTINS = {k: v for k, v in _raw.items() if k not in _BLOCKED_BUILTINS}
 
@@ -85,7 +96,8 @@ def run_managed(code_str):
             try:
                 dirty.extend(tracker.collect_changes())
             except BaseException as e:
-                xl_log(f"run_managed: collect_changes failed: {e}")
+                xl_log(f'run_managed: collect_changes failed: {e}')
+
             # Restore Excel state.  We must catch BaseException (not
             # Exception) because ExecutionTimeout is a BaseException that
             # can fire at any bytecode boundary via PyThreadState_SetAsyncExc.
@@ -113,6 +125,7 @@ def run_managed(code_str):
                         app.Calculation = _XL_CALCULATION_AUTOMATIC
                 except BaseException:
                     pass
+
             try:
                 _restore()
             except BaseException:
@@ -121,7 +134,7 @@ def run_managed(code_str):
                 try:
                     _restore()
                 except BaseException:
-                    xl_log("run_managed: restoration failed twice")
+                    xl_log('run_managed: restoration failed twice')
 
         return dirty
 
@@ -140,8 +153,10 @@ def run_managed(code_str):
 
 def xl_batch(fn):
     """Run fn(app) on the main thread with ScreenUpdating disabled."""
+
     def _batched():
         import pythoncom
+
         app = xl_app()
         app.ScreenUpdating = False
         try:
@@ -155,6 +170,7 @@ def xl_batch(fn):
                 pythoncom.PumpWaitingMessages()
             except BaseException:
                 pass
+
     _run_on_main(_batched)
 
 
@@ -169,7 +185,8 @@ def schedule_call(fn, delay_seconds=0.0):
             fn()
         except Exception as e:
             import traceback
-            xl_log(f"schedule_call error: {e}\n{traceback.format_exc()}")
+
+            xl_log(f'schedule_call error: {e}\n{traceback.format_exc()}')
 
     t = threading.Thread(target=_run, daemon=True)
     t.start()

package/xll/modules/shortcut_xl/_registry.py

@@ -21,16 +21,21 @@ def xl_func(fn=None, *, name=None):
         def my_func(a, b):
             return a + b
     """
+
     def _register(f):
         excel_name = name if name else f.__name__
         sig = inspect.signature(f)
-        n_args = len([
-            p for p in sig.parameters.values()
-            if p.kind in (
-                inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                inspect.Parameter.POSITIONAL_ONLY,
-            )
-        ])
+        n_args = len(
+            [
+                p
+                for p in sig.parameters.values()
+                if p.kind
+                in (
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    inspect.Parameter.POSITIONAL_ONLY,
+                )
+            ]
+        )
         # Check if already registered (e.g. after a hot-reload)
         for i, (n, _, _) in enumerate(_registry):
             if n == excel_name:

package/xll/modules/shortcut_xl/_threading.py

@@ -10,16 +10,31 @@ import ctypes
 import queue
 import threading
 from ctypes import wintypes
+from typing import TypedDict
 
 from shortcut_xl._log import xl_log
 
 # COM error code: Excel is busy (VBA_E_IGNORE = 0x800AC472)
 _VBA_E_IGNORE = -2146777998
 
-_MAX_ITEMS_PER_TICK = 64      # cap per timer tick to avoid starving Excel
-_MAX_BUSY_RETRIES = 2400      # ~120s at 50ms intervals before giving up
-_DRAIN_INTERVAL_MS = 50       # SetTimer interval for queue drain
-_DEFAULT_TIMEOUT_S = 30.0     # max wait for main-thread dispatch + execution
+_MAX_ITEMS_PER_TICK = 64  # cap per timer tick to avoid starving Excel
+_MAX_BUSY_RETRIES = 2400  # ~120s at 50ms intervals before giving up
+_DRAIN_INTERVAL_MS = 50  # SetTimer interval for queue drain
+_DEFAULT_TIMEOUT_S = 30.0  # max wait for main-thread dispatch + execution
+
+
+class _ResultBox(TypedDict, total=False):
+    """Typed dict for main-thread dispatch results.
+
+    All keys are optional (total=False) because the box starts nearly empty
+    and is populated progressively during dispatch.
+    """
+
+    result: object
+    error: Exception | None
+    _retries: int
+    _cancelled: bool
+    _running: bool
 
 
 class ExecutionTimeout(BaseException):
@@ -27,6 +42,7 @@ class ExecutionTimeout(BaseException):
 
     Inherits from BaseException (not Exception) so that user code's
     ``except Exception:`` blocks cannot swallow it."""
+
     pass
 
 
@@ -79,8 +95,7 @@ def _drain_queue():
                 result_box['error'] = None
                 done_event.set()
             except ExecutionTimeout:
-                result_box['error'] = RuntimeError(
-                    "Execution interrupted: caller timed out")
+                result_box['error'] = RuntimeError('Execution interrupted: caller timed out')
                 done_event.set()
             except Exception as e:
                 if _is_excel_busy(e):
@@ -88,7 +103,7 @@ def _drain_queue():
                     if result_box['_retries'] < _MAX_BUSY_RETRIES:
                         _work_queue.put((fn, result_box, done_event))
                         break
-                    xl_log(f"_drain_queue: Excel busy exceeded {_MAX_BUSY_RETRIES} retries")
+                    xl_log(f'_drain_queue: Excel busy exceeded {_MAX_BUSY_RETRIES} retries')
                 result_box['error'] = e
                 done_event.set()
     finally:
@@ -96,8 +111,7 @@ def _drain_queue():
 
 
 # SetTimer callback — called by Windows on the main thread during message pump
-_TIMERPROC = ctypes.WINFUNCTYPE(
-    None, wintypes.HWND, ctypes.c_uint, ctypes.c_size_t, wintypes.DWORD)
+_TIMERPROC = ctypes.WINFUNCTYPE(None, wintypes.HWND, ctypes.c_uint, ctypes.c_size_t, wintypes.DWORD)
 
 
 def _on_timer(hwnd, msg, id_event, dw_time):
@@ -114,13 +128,13 @@ def _start_drain_timer():
         old_id = getattr(builtins, '_shortcutxl_timer_id', None)
         if old_id:
             ctypes.windll.user32.KillTimer(None, ctypes.c_size_t(old_id))
-        timer_id = ctypes.windll.user32.SetTimer(
-            None, ctypes.c_size_t(0), _DRAIN_INTERVAL_MS, _timer_proc_ref)
+        timer_id = ctypes.windll.user32.SetTimer(None, ctypes.c_size_t(0), _DRAIN_INTERVAL_MS, _timer_proc_ref)
         builtins._shortcutxl_timer_id = timer_id
-        xl_log(f"_start_drain_timer: timer_id={timer_id}")
+        xl_log(f'_start_drain_timer: timer_id={timer_id}')
     except Exception as e:
-        xl_log(f"_start_drain_timer: FAILED — {e}")
+        xl_log(f'_start_drain_timer: FAILED — {e}')
         import traceback
+
         xl_log(traceback.format_exc())
 
 
@@ -134,7 +148,7 @@ def _run_on_main(fn, timeout=_DEFAULT_TIMEOUT_S):
     If already on the main thread, calls fn() directly."""
     if threading.current_thread().ident == _main_thread_id:
         return fn()
-    result_box = {'_retries': 0}
+    result_box: _ResultBox = {'_retries': 0}
     done_event = threading.Event()
     _work_queue.put((fn, result_box, done_event))
     if not done_event.wait(timeout=timeout):
@@ -144,21 +158,20 @@ def _run_on_main(fn, timeout=_DEFAULT_TIMEOUT_S):
             # bytecode boundary (won't interrupt a blocking C call, but
             # will fire between COM calls / sleep increments).
             ctypes.pythonapi.PyThreadState_SetAsyncExc(
-                ctypes.c_ulong(_main_thread_id),
-                ctypes.py_object(ExecutionTimeout))
+                ctypes.c_ulong(_main_thread_id), ctypes.py_object(ExecutionTimeout)
+            )
             # Wait for the main thread to handle the exception and finish.
             done_event.wait(timeout=5.0)
             # Always clear — if the exception already fired this is a
             # harmless no-op; if fn() completed in the race window between
             # injection and delivery, this prevents the exception from
             # leaking to the next work item.
-            ctypes.pythonapi.PyThreadState_SetAsyncExc(
-                ctypes.c_ulong(_main_thread_id), None)
+            ctypes.pythonapi.PyThreadState_SetAsyncExc(ctypes.c_ulong(_main_thread_id), None)
             if not done_event.is_set():
-                xl_log("_run_on_main: fn did not stop after async exception")
+                xl_log('_run_on_main: fn did not stop after async exception')
         else:
             result_box['_cancelled'] = True
-        raise RuntimeError("_run_on_main: timed out waiting for main thread")
+        raise RuntimeError('_run_on_main: timed out waiting for main thread')
     if result_box.get('error') is not None:
         raise result_box['error']
     return result_box.get('result')

package/xll/modules/shortcut_xl/_tracking.py

@@ -16,8 +16,9 @@ from shortcut_xl.api.utils.helpers import col_letter
 
 class _DirtyCellBase(TypedDict):
     """Required fields produced by _diff_snapshots for every changed cell."""
+
     sheet: str
-    address: str    # e.g. "B5" — bare cell address, no sheet prefix
+    address: str  # e.g. "B5" — bare cell address, no sheet prefix
     oldValue: Any
     value: Any
 
@@ -28,14 +29,16 @@ class DirtyCell(_DirtyCellBase, total=False):
     Required: sheet, address, oldValue, value
     Optional fields are added during the enrichment pass in collect_changes().
     """
-    formula: str       # new formula (if cell has one after the change)
-    oldFormula: str    # previous formula (if cell had one before)
-    workbook: str      # workbook name — added during enrichment
+
+    formula: str  # new formula (if cell has one after the change)
+    oldFormula: str  # previous formula (if cell had one before)
+    workbook: str  # workbook name — added during enrichment
     numberFormat: str  # Excel number format string — added during enrichment
 
 
 class _SheetSnapshot:
     """Immutable snapshot of a worksheet's UsedRange values and formulas."""
+
     __slots__ = ('top_row', 'left_col', 'rows', 'cols', 'data', 'formulas')
 
     def __init__(self, ws):
@@ -73,8 +76,12 @@ def _diff_snapshots(sheet_name: str, before: _SheetSnapshot, after: _SheetSnapsh
     """
     changes = []
     # Same geometry — fast path
-    if (before.top_row == after.top_row and before.left_col == after.left_col
-            and before.rows == after.rows and before.cols == after.cols):
+    if (
+        before.top_row == after.top_row
+        and before.left_col == after.left_col
+        and before.rows == after.rows
+        and before.cols == after.cols
+    ):
         for ri in range(before.rows):
             if before.data[ri] == after.data[ri]:
                 continue
@@ -83,10 +90,12 @@ def _diff_snapshots(sheet_name: str, before: _SheetSnapshot, after: _SheetSnapsh
                 old = before.data[ri][ci]
                 new = after.data[ri][ci]
                 if old != new:
-                    addr = f"{col_letter(before.left_col + ci - 1)}{row_num}"
+                    addr = f'{col_letter(before.left_col + ci - 1)}{row_num}'
                     entry = {
-                        'sheet': sheet_name, 'address': addr,
-                        'oldValue': old, 'value': new,
+                        'sheet': sheet_name,
+                        'address': addr,
+                        'oldValue': old,
+                        'value': new,
                     }
                     formula = _get_formula(after, ri, ci)
                     if formula:
@@ -122,10 +131,12 @@ def _diff_snapshots(sheet_name: str, before: _SheetSnapshot, after: _SheetSnapsh
             old = _get(before, row, col)
             new = _get(after, row, col)
             if old != new:
-                addr = f"{col_letter(col - 1)}{row}"
+                addr = f'{col_letter(col - 1)}{row}'
                 entry = {
-                    'sheet': sheet_name, 'address': addr,
-                    'oldValue': old, 'value': new,
+                    'sheet': sheet_name,
+                    'address': addr,
+                    'oldValue': old,
+                    'value': new,
                 }
                 formula = _get_formula_abs(after, row, col)
                 if formula:
@@ -139,6 +150,7 @@ def _diff_snapshots(sheet_name: str, before: _SheetSnapshot, after: _SheetSnapsh
 
 class DirtyTracker:
     """Snapshots sheets on first access, diffs after execution."""
+
     __slots__ = ('_app', '_snapshots')
 
     def __init__(self, app):
@@ -155,7 +167,7 @@ class DirtyTracker:
             try:
                 self._snapshots[name] = (ws, _SheetSnapshot(ws))
             except Exception as e:
-                xl_log(f"DirtyTracker.snapshot_sheet({name}): {e}")
+                xl_log(f'DirtyTracker.snapshot_sheet({name}): {e}')
 
     def collect_changes(self) -> list[DirtyCell]:
         """Re-read snapshotted sheets and return list of cell changes."""
@@ -180,7 +192,7 @@ class DirtyTracker:
                         pass
                 all_changes.extend(changes)
             except Exception as e:
-                xl_log(f"DirtyTracker.collect_changes({name}): {e}")
+                xl_log(f'DirtyTracker.collect_changes({name}): {e}')
         return all_changes
 
 
@@ -188,9 +200,11 @@ class DirtyTracker:
 # Thin proxy classes (Application → Workbook → Worksheet access only)
 # ---------------------------------------------------------------------------
 
+
 class TrackedApp:
     """Proxy around Application.  Wraps workbook/sheet access to trigger
     snapshots; everything else passes straight through to COM."""
+
     _WB_ATTRS = frozenset(('ActiveWorkbook', 'ThisWorkbook'))
     _SHEET_ACCESSORS = frozenset(('Worksheets', 'Sheets'))
     _SHEET_DIRECT = frozenset(('ActiveSheet',))
@@ -223,6 +237,7 @@ class TrackedApp:
 
 class _TrackedWorkbooks:
     """Proxy for Workbooks collection."""
+
     __slots__ = ('_obj', '_tracker')
 
     def __init__(self, obj, tracker):
@@ -244,6 +259,7 @@ class _TrackedWorkbooks:
 
 class _TrackedWorkbook:
     """Proxy for a Workbook — wraps Worksheet/Sheet access."""
+
     _SHEET_ACCESSORS = frozenset(('Worksheets', 'Sheets'))
     _SHEET_DIRECT = frozenset(('ActiveSheet',))
     __slots__ = ('_wb', '_tracker')
@@ -272,6 +288,7 @@ class _TrackedWorkbook:
 class _TrackedSheetAccessor:
     """Proxy for Worksheets/Sheets collection — snapshots each sheet
     the first time it is accessed, then returns the real COM Worksheet."""
+
     __slots__ = ('_obj', '_tracker')
 
     def __init__(self, obj, tracker):

package/xll/modules/shortcut_xl/api/categorize.py

@@ -7,7 +7,7 @@ and hardcoded numbers inside formulas.
 import re
 
 from shortcut_xl._tracking import DirtyCell
-from shortcut_xl.api.utils.numerical import NUMERIC_TYPES
+from shortcut_xl.api.utils.numerical import CURRENCY_CHARS, NUMERIC_TYPES
 
 # Issue types — also used as dict keys in categorize_cells() result
 GOOD = 'good'
@@ -20,10 +20,6 @@ ALL_PROBLEMS = 'all problems'
 # Number format characters that indicate date/time (skip these as hardcoded)
 _DATE_TIME_CHARS = ('d', 'm', 'y', 'h', 's')
 
-# Number format characters/strings that indicate currency/accounting (skip these)
-# Must stay in sync with _format.py currency regex.
-_CURRENCY_CHARS = ('$', '£', '€', '¥', '₹', '₩', '₪', '₱', '฿', 'kr')
-
 
 def _is_numeric(value):
     """Check if a value is numeric (int, float, Decimal, etc.)."""
@@ -61,14 +57,13 @@ def is_hardcoded_number(cell):
     if any(ch in fmt for ch in _DATE_TIME_CHARS):
         return False
     # Skip currency/accounting
-    if any(ch in fmt for ch in _CURRENCY_CHARS):
+    if any(ch in fmt for ch in CURRENCY_CHARS):
         return False
     return True
 
 
 # Matches standalone numbers in formulas, excluding cell refs / named ranges.
-_HARDCODED_NUM_RE = re.compile(
-    r'(?<![A-Z$!])(?<![A-Z]\d)\b\d+\.?\d*\b(?![A-Z])', re.IGNORECASE)
+_HARDCODED_NUM_RE = re.compile(r'(?<![A-Z$!])(?<![A-Z]\d)\b\d+\.?\d*\b(?![A-Z])', re.IGNORECASE)
 
 
 def has_hardcoded_numbers_in_formula(formula):
@@ -78,8 +73,22 @@ def has_hardcoded_numbers_in_formula(formula):
     return bool(_HARDCODED_NUM_RE.search(cleaned))
 
 
-_ERROR_PATTERNS = (
-    '#ERROR', '#REF', '#VALUE', '#DIV/0', '#NUM', '#N/A', '#NAME', '#NULL')
+# Canonical set of Excel error strings — the single source of truth.
+# Used for exact-match detection (e.g. values from COM .Value) and
+# prefix-match detection (e.g. formulas containing error text).
+_ERROR_VALUES = frozenset(
+    (
+        '#REF!',
+        '#NAME?',
+        '#VALUE!',
+        '#DIV/0!',
+        '#N/A',
+        '#NULL!',
+        '#NUM!',
+        '#GETTING_DATA',
+    )
+)
+_ERROR_PREFIXES = ('#ERROR', '#REF', '#VALUE', '#DIV/0', '#NUM', '#N/A', '#NAME', '#NULL')
 
 # COM returns Excel error values as negative integers (CVErr codes).
 # Map them to their string equivalents so categorization works.
@@ -95,15 +104,20 @@ _COM_ERROR_CODES = {
 }
 
 
-def _is_error_value(s):
-    """Check if a string is an Excel error value (e.g. '#REF!', '#N/A').
+def is_error_value(val) -> bool:
+    """Check if a value is an Excel error string (exact match)."""
+    return isinstance(val, str) and val in _ERROR_VALUES
+
 
-    Excel error values always start with '#' and may have a trailing '!'
-    or '?'.  We check that the string starts with a known error prefix
-    and contains no spaces (real errors never do)."""
+def _is_error_string(s):
+    """Check if a string starts with a known Excel error prefix.
+
+    Looser than is_error_value() — catches partial matches in formulas.
+    Excel error values always start with '#' and contain no spaces.
+    """
     if not s or ' ' in s:
         return False
-    return any(s.startswith(e) for e in _ERROR_PATTERNS)
+    return any(s.startswith(e) for e in _ERROR_PREFIXES)
 
 
 def is_com_error(value):
@@ -127,7 +141,7 @@ def has_formula_error(cell):
         return True
     value_str = str(value or '')
     formula_str = str(cell.get('formula') or '')
-    return _is_error_value(value_str) or _is_error_value(formula_str)
+    return _is_error_string(value_str) or _is_error_string(formula_str)
 
 
 def is_large_percentage(cell):

package/xll/modules/shortcut_xl/api/format.py

@@ -17,8 +17,8 @@ from shortcut_xl.api.categorize import (
     com_error_to_str,
     is_com_error,
 )
-from shortcut_xl.api.utils.helpers import col_letter
-from shortcut_xl.api.utils.numerical import NUMERIC_TYPES
+from shortcut_xl.api.utils.helpers import address_to_index, col_letter
+from shortcut_xl.api.utils.numerical import CURRENCY_RE, NUMERIC_TYPES
 
 # Display constants
 MAX_ROWS_TO_SHOW = 10
@@ -36,27 +36,10 @@ _PROBLEM_SECTIONS = (
     (INVALID_FORMULA, True),
 )
 
-# ---------- address parsing ----------
-
-_ADDR_RE = re.compile(r'^(\$?)([A-Z]+)(\$?)(\d+)$', re.IGNORECASE)
-
-
-def _parse_address(addr):
-    """Parse 'B12' -> (col_index_0based, row_0based)."""
-    m = _ADDR_RE.match(addr)
-    if not m:
-        return (0, 0)
-    letters = m.group(2).upper()
-    col = 0
-    for ch in letters:
-        col = col * 26 + (ord(ch) - 64)
-    return (col - 1, int(m.group(4)) - 1)
-
-
-
 
 # ---------- value formatting ----------
 
+
 def format_value(value, number_format=None):
     """Format a raw cell value for display."""
     if value is None:
@@ -79,7 +62,7 @@ def format_value(value, number_format=None):
 
     fmt = number_format
     is_pct = '%' in fmt
-    currency_m = re.search(r'[$\xa3\u20ac\xa5\u20b9\u20a9\u20aa\u20b1\u0e3f]|kr', fmt)
+    currency_m = re.search(CURRENCY_RE, fmt)
     currency = currency_m.group(0) if currency_m else None
     dec_m = re.search(r'\.([0#]+)', fmt)
     decimals = min(len(dec_m.group(1)), MAX_FORMAT_DECIMALS) if dec_m else MAX_FORMAT_DECIMALS
@@ -92,8 +75,7 @@ def format_value(value, number_format=None):
     if is_pct:
         return f'({abs_str}%)' if neg and use_parens else f'{"-" if neg else ""}{abs_str}%'
     if currency:
-        return (f'({currency}{abs_str})' if neg and use_parens
-                else f'{"-" if neg else ""}{currency}{abs_str}')
+        return f'({currency}{abs_str})' if neg and use_parens else f'{"-" if neg else ""}{currency}{abs_str}'
     return f'({abs_str})' if neg and use_parens else f'{"-" if neg else ""}{abs_str}'
 
 
@@ -107,6 +89,7 @@ def _display_value(cell):
 
 # ---------- sampling ----------
 
+
 def _sample_first_last(items, max_n):
     """Sample up to max_n items, always including first and last.
 
@@ -125,6 +108,7 @@ def _sample_first_last(items, max_n):
 
 # ---------- filtering ----------
 
+
 def _should_include(cell, issues):
     """Include all changes except trivial None↔None (no actual change)."""
     value = cell.get('value')
@@ -136,6 +120,7 @@ def _should_include(cell, issues):
 
 # ---------- grouping ----------
 
+
 def _group_by_sheet_row(entries):
     """Group (cell, issues) entries by sheet -> row.
     Returns {sheet: {row: [(cell, issues, col), ...]}}
@@ -144,7 +129,10 @@ def _group_by_sheet_row(entries):
     for cell, issues in entries:
         if not _should_include(cell, issues):
             continue
-        col, row = _parse_address(cell.get('address', 'A1'))
+        try:
+            row, col = address_to_index(cell.get('address', 'A1'))
+        except (ValueError, AttributeError):
+            row, col = 0, 0
         sheet = cell.get('sheet', 'Sheet1')
         grouped.setdefault(sheet, {}).setdefault(row, []).append((cell, issues, col))
     # Sort within each row by column
@@ -156,6 +144,7 @@ def _group_by_sheet_row(entries):
 
 # ---------- row formatting ----------
 
+
 def _format_row(sheet, row, entries, indent=2, show_issues=True, show_count=True):
     """Format a single row with sampled cells."""
     ind = ' ' * indent
@@ -164,8 +153,7 @@ def _format_row(sheet, row, entries, indent=2, show_issues=True, show_count=True
 
     cols = [e[2] for e in entries]
     min_c, max_c = min(cols), max(cols)
-    col_range = (col_letter(min_c) if min_c == max_c
-                 else f'{col_letter(min_c)}-{col_letter(max_c)}')
+    col_range = col_letter(min_c) if min_c == max_c else f'{col_letter(min_c)}-{col_letter(max_c)}'
 
     count_suffix = f': {len(entries)} cells' if show_count else ':'
     lines.append(f'{ind}{sheet}!Row {row + 1} ({col_range}){count_suffix}')
@@ -188,6 +176,7 @@ def _format_row(sheet, row, entries, indent=2, show_issues=True, show_count=True
 
 # ---------- section formatting ----------
 
+
 def _format_section(entries, title, must_fix=False):
     """Format a titled section of (cell, issues) entries."""
     filtered = [(c, iss) for c, iss in entries if _should_include(c, iss)]
@@ -216,6 +205,7 @@ def _format_section(entries, title, must_fix=False):
 
 # ---------- public API ----------
 
+
 def format_cell_diff(dirty_cells: list[DirtyCell]):
     """Format a list of dirty cell dicts into a human-readable summary.
 

package/xll/modules/shortcut_xl/api/named_ranges.py

@@ -14,10 +14,10 @@ def get_named_range_info(wb, max_count: int = 50) -> str:
         names = wb.Names
         total = names.Count
     except Exception:
-        return "No named ranges found."
+        return 'No named ranges found.'
 
     if total == 0:
-        return "No named ranges found."
+        return 'No named ranges found.'
 
     limit = min(total, max_count)
     lines: list[str] = []
@@ -30,21 +30,21 @@ def get_named_range_info(wb, max_count: int = 50) -> str:
             comment = n.Comment
 
             # Determine scope: sheet-scoped names contain '!'
-            if "!" in full_name:
-                scope = full_name.split("!")[0]
+            if '!' in full_name:
+                scope = full_name.split('!')[0]
             else:
-                scope = "workbook"
+                scope = 'workbook'
 
-            entry = f"  Name: {full_name} | Ref: {refers_to} | Scope: {scope}"
+            entry = f'  Name: {full_name} | Ref: {refers_to} | Scope: {scope}'
             if comment:
-                entry += f" | Comment: {comment}"
+                entry += f' | Comment: {comment}'
             lines.append(entry)
         except Exception:
             # Some Name objects may be broken/hidden — skip them
             continue
 
     if not lines:
-        return "No named ranges found."
+        return 'No named ranges found.'
 
-    header = f"Named Ranges ({len(lines)}):"
-    return "\n".join([header] + lines)
+    header = f'Named Ranges ({len(lines)}):'
+    return '\n'.join([header] + lines)

package/xll/modules/shortcut_xl/api/picture.py

@@ -14,7 +14,7 @@ def add_picture(ws, name: str, base64_data: str, anchor_cell: str):
     anchor_cell: cell address like "A1" where top-left corner is anchored
     """
     if not base64_data:
-        raise ValueError("base64_data must be non-empty")
+        raise ValueError('base64_data must be non-empty')
 
     image_bytes = base64.b64decode(base64_data)
 
@@ -24,7 +24,7 @@ def add_picture(ws, name: str, base64_data: str, anchor_cell: str):
     elif image_bytes[:2] == b'\xff\xd8':
         ext = '.jpg'
     else:
-        raise ValueError("Not a valid PNG or JPEG image")
+        raise ValueError('Not a valid PNG or JPEG image')
 
     # Remove existing shape with the same name
     for i in range(ws.Shapes.Count, 0, -1):
@@ -41,12 +41,12 @@ def add_picture(ws, name: str, base64_data: str, anchor_cell: str):
         cell = ws.Range(anchor_cell)
         shape = ws.Shapes.AddPicture(
             tmp_path,
-            False,   # LinkToFile
-            True,    # SaveWithDocument
+            False,  # LinkToFile
+            True,  # SaveWithDocument
             cell.Left,
             cell.Top,
-            -1,      # Width  — original size
-            -1,      # Height — original size
+            -1,  # Width  — original size
+            -1,  # Height — original size
         )
         # If Excel didn't honour -1, reset scale to original dimensions
         shape.ScaleWidth(1, True)