fix(packaging): suppress ERROR logging for optional feature checks

When checking for tidy3d-extras availability using
check_tidy3d_extras_licensed_feature, ERROR messages were logged to
console even when the caller intended to catch and handle the exception
gracefully. This caused confusing UX in the supports_local_subpixel
decorator when use_local_subpixel=None (the default).

Add a quiet parameter to suppress logging when the check is speculative.
The Tidy3dError base class now accepts log_error=True parameter,
allowing exceptions to be constructed without automatic error logging.

Fixes FXC-4374

Author: yaugenst-flex

tests/test_components/test_packaging.py

@@ -154,5 +154,45 @@ def get_flag():
         reload_config(profile="default")
 
 
+def test_supports_local_subpixel_no_error_logged_when_optional(monkeypatch, caplog):
+    """Regression test for FXC-4374: no ERROR should be logged when preference=None
+    and tidy3d-extras is unavailable, since the decorator handles it gracefully."""
+    import logging
+
+    reload_config(profile="default")
+    tidy3d_extras["mod"] = None
+    tidy3d_extras["use_local_subpixel"] = None
+
+    real_import = builtins.__import__
+
+    def fake_import(name, globals=None, locals=None, fromlist=(), level=0):
+        if name == "tidy3d_extras":
+            raise ImportError("forced failure")
+        return real_import(name, globals, locals, fromlist, level)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    try:
+        # preference=None is the default - feature is optional
+        config.update_section("simulation", use_local_subpixel=None)
+
+        @supports_local_subpixel
+        def get_flag():
+            return tidy3d_extras["use_local_subpixel"]
+
+        with caplog.at_level(logging.ERROR):
+            result = get_flag()
+
+        # Should fall back gracefully without logging errors
+        assert result is False
+        assert not any("tidy3d-extras" in record.message for record in caplog.records), (
+            "ERROR was logged but should have been suppressed for optional feature check"
+        )
+    finally:
+        tidy3d_extras["mod"] = None
+        tidy3d_extras["use_local_subpixel"] = None
+        reload_config(profile="default")
+
+
 if __name__ == "__main__":
     pytest.main()

tidy3d/exceptions.py

@@ -10,10 +10,11 @@
 class Tidy3dError(ValueError):
     """Any error in tidy3d"""
 
-    def __init__(self, message: Optional[str] = None) -> None:
+    def __init__(self, message: Optional[str] = None, log_error: bool = True) -> None:
         """Log just the error message and then raise the Exception."""
         super().__init__(message)
-        log.error(message)
+        if log_error:
+            log.error(message)
 
 
 class ConfigError(Tidy3dError):

tidy3d/packaging.py

@@ -183,9 +183,14 @@ def get_numpy_major_version(module=np):
     return major_version
 
 
-def _check_tidy3d_extras_available():
+def _check_tidy3d_extras_available(quiet: bool = False):
     """Helper function to check if 'tidy3d-extras' is available and version matched.
 
+    Parameters
+    ----------
+    quiet : bool
+        If True, suppress error logging when raising exceptions.
+
     Raises
     ------
     Tidy3dImportError
@@ -199,49 +204,56 @@ def _check_tidy3d_extras_available():
         raise Tidy3dImportError(
             "The package 'tidy3d-extras' is absent. "
             "Please install the 'tidy3d-extras' package using, for "
-            r"example, 'pip install tidy3d\[extras]'."
+            r"example, 'pip install tidy3d\[extras]'.",
+            log_error=not quiet,
         )
 
     try:
         import tidy3d_extras as tidy3d_extras_mod
 
     except ImportError as exc:
         raise Tidy3dImportError(
-            "The package 'tidy3d-extras' did not initialize correctly."
+            "The package 'tidy3d-extras' did not initialize correctly.",
+            log_error=not quiet,
         ) from exc
 
     if not hasattr(tidy3d_extras_mod, "__version__"):
         raise Tidy3dImportError(
             "The package 'tidy3d-extras' did not initialize correctly. "
             "Please install the 'tidy3d-extras' package using, for "
-            r"example, 'pip install tidy3d\[extras]'."
+            r"example, 'pip install tidy3d\[extras]'.",
+            log_error=not quiet,
         )
 
     version = tidy3d_extras_mod.__version__
 
     if version is None:
         raise Tidy3dImportError(
             "The package 'tidy3d-extras' did not initialize correctly, "
-            "likely due to an invalid API key."
+            "likely due to an invalid API key.",
+            log_error=not quiet,
         )
 
     if version != __version__:
         raise Tidy3dImportError(
             f"The version of 'tidy3d-extras' is {version}, but the version of 'tidy3d' is {__version__}. "
             "They must match. You can install the correct "
-            r"version using 'pip install tidy3d\[extras]'."
+            r"version using 'pip install tidy3d\[extras]'.",
+            log_error=not quiet,
         )
 
     tidy3d_extras["mod"] = tidy3d_extras_mod
 
 
-def check_tidy3d_extras_licensed_feature(feature_name: str):
+def check_tidy3d_extras_licensed_feature(feature_name: str, quiet: bool = False):
     """Helper function to check if a specific feature is licensed in 'tidy3d-extras'.
 
     Parameters
     ----------
     feature_name : str
         The name of the feature to check for.
+    quiet : bool
+        If True, suppress error logging when raising exceptions.
 
     Raises
     ------
@@ -250,17 +262,19 @@ def check_tidy3d_extras_licensed_feature(feature_name: str):
     """
 
     try:
-        _check_tidy3d_extras_available()
+        _check_tidy3d_extras_available(quiet=quiet)
     except Tidy3dImportError as exc:
         raise Tidy3dImportError(
-            f"The package 'tidy3d-extras' is required for this feature '{feature_name}'."
+            f"The package 'tidy3d-extras' is required for this feature '{feature_name}'.",
+            log_error=not quiet,
         ) from exc
 
     features = tidy3d_extras["mod"].extension._features()
     if feature_name not in features:
         raise Tidy3dImportError(
             f"The feature '{feature_name}' is not available with your license. "
-            "Please contact Tidy3D support, or upgrade your license."
+            "Please contact Tidy3D support, or upgrade your license.",
+            log_error=not quiet,
         )
 
 
@@ -277,7 +291,7 @@ def _fn(*args: Any, **kwargs: Any):
             return fn(*args, **kwargs)
 
         try:
-            check_tidy3d_extras_licensed_feature("local_subpixel")
+            check_tidy3d_extras_licensed_feature("local_subpixel", quiet=True)
         except Tidy3dImportError as exc:
             tidy3d_extras["use_local_subpixel"] = False
             if preference is True: