fix: disable tqdm in CI environments to prevent threading deadlock

This commit addresses the threading deadlock issue that occurs in headless
CI/CD environments (particularly on Linux) when tqdm's monitor thread
interacts with CZI file reading operations.

Changes:
- Added _should_use_tqdm() helper function to detect CI/headless environments
- Modified planetable.py to conditionally use tqdm based on environment
- Modified read_tools.py to conditionally use tqdm based on environment
- tqdm is disabled when CI=true, GITHUB_ACTIONS=true, TQDM_DISABLE=1, or QT_QPA_PLATFORM=offscreen
- Falls back to itertools.product and no-op tqdm wrapper when disabled
- Maintains full compatibility - progress bars work normally in interactive environments

Fixes: Threading deadlock on Linux CI when reading CZI files

Author: sebi06

src/czitools/read_tools/read_tools.py

@@ -13,6 +13,45 @@
 import gc
 import warnings
 import itertools
+import os
+
+
+def _should_use_tqdm() -> bool:
+    """
+    Determine if tqdm progress bars should be used.
+
+    Disables tqdm in headless CI/CD environments to avoid threading deadlocks
+    that occur when tqdm's monitor thread interacts with CZI file reading
+    on Linux systems.
+
+    Returns:
+        bool: True if tqdm should be used, False otherwise.
+    """
+    if os.environ.get("CI") == "true":
+        return False
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        return False
+    if os.environ.get("TQDM_DISABLE") == "1":
+        return False
+    if os.environ.get("QT_QPA_PLATFORM") == "offscreen":
+        return False
+    return True
+
+
+# Import tqdm based on environment
+if _should_use_tqdm():
+    try:
+        from tqdm import tqdm
+        from tqdm.contrib.itertools import product
+    except ImportError:
+        def tqdm(x, *args, **kwargs):
+            return x
+        product = itertools.product
+else:
+    def tqdm(x, *args, **kwargs):
+        return x
+    product = itertools.product
+
 from pylibCZIrw import czi as pyczi
 from aicspylibczi import CziFile
 from czitools.metadata_tools import czi_metadata as czimd
@@ -23,8 +62,6 @@
 import dask
 import dask.delayed
 import os
-from tqdm import tqdm
-from tqdm.contrib.itertools import product
 import tempfile
 import shutil
 from czitools.utils import logging_tools

src/czitools/utils/planetable.py

@@ -16,12 +16,43 @@
 import numpy as np
 from pathlib import Path
 import dateutil.parser as dt
-from tqdm.contrib.itertools import product
 from typing import Dict, Tuple, Any, Union, Optional
 import validators
 from aicspylibczi import CziFile
 from czitools.utils import logging_tools
 
+
+def _should_use_tqdm() -> bool:
+    """
+    Determine if tqdm progress bars should be used.
+
+    Disables tqdm in headless CI/CD environments to avoid threading deadlocks
+    that occur when tqdm's monitor thread interacts with CZI file reading
+    on Linux systems.
+
+    Returns:
+        bool: True if tqdm should be used, False otherwise.
+    """
+    if os.environ.get("CI") == "true":
+        return False
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        return False
+    if os.environ.get("TQDM_DISABLE") == "1":
+        return False
+    if os.environ.get("QT_QPA_PLATFORM") == "offscreen":
+        return False
+    return True
+
+
+# Import product based on environment
+if _should_use_tqdm():
+    try:
+        from tqdm.contrib.itertools import product
+    except ImportError:
+        from itertools import product
+else:
+    from itertools import product
+
 logger = logging_tools.set_logging()