revise recommendations.py

Author: emilykl

plotly/recommendations.py

@@ -16,6 +16,8 @@
     go.Figure(data=[go.Scatter(y=[1, 2, 3])])  # may emit recommendation warnings
 """
 
+from functools import partial
+import inspect
 import os
 import warnings
 
@@ -51,39 +53,102 @@ def enabled(self, value):
 
 
 # -----------------------------------------------------------------------------
-# Recommendation checkers (extensible list)
+# Property resolution (single place for "does this property exist")
 # -----------------------------------------------------------------------------
 
 
-def _check_scatter_xy_length(obj, context):
-    """Warn if a scatter trace has x or y with length >= 10."""
-    if context != "trace":
-        return
-    if getattr(obj, "plotly_name", None) != "scatter":
-        return
-    for prop in ("x", "y"):
+def _targets(obj, context, prefix):
+    """Yield each object (layout or trace) that this prefix applies to."""
+    if context == "figure":
+        if prefix == "layout" and hasattr(obj, "layout"):
+            yield obj.layout
+        if hasattr(obj, "data"):
+            for t in obj.data:
+                if prefix == "trace" or getattr(t, "plotly_name", None) == prefix:
+                    yield t
+    elif (context == "trace" or context == "layout") and (
+        prefix == "trace" or prefix == "layout" or getattr(obj, "plotly_name", None) == prefix
+    ):
+        yield obj
+
+
+def _get_stacklevel():
+    """Find the first frame outside the plotly package so the warning points at user code."""
+    plotly_dir = os.path.abspath(os.path.dirname(__file__))
+    stack = inspect.stack()
+    for i, frame in enumerate(stack):
         try:
-            val = obj[prop]
-            if val is not None and hasattr(val, "__len__") and len(val) >= 10:
-                warnings.warn(
-                    "Scatter trace '%s' has length %d (recommended < 10)."
-                    % (prop, len(val)),
-                    UserWarning,
-                    stacklevel=2,
-                )
-        except (KeyError, TypeError):
-            pass
+            frame_path = os.path.abspath(frame.filename)
+        except (AttributeError, TypeError):
+            frame_path = getattr(frame, "filename", "") or ""
+        if not frame_path.startswith(plotly_dir):
+            break
+    else:
+        i = len(stack) - 1
+    return i
+
+
+def _is_empty(obj):
+    """
+    Quick check if the object has no values assigned yet (e.g. just constructed).
+    Figure: no traces. Trace/layout: no properties in _props.
+    """
+    if hasattr(obj, "_data"):
+        return len(obj._data) == 0
+    if hasattr(obj, "_props"):
+        props = obj._props
+        return props is None or len(props) == 0
+    return False
+
+
+def _get_value(whole_obj, path, context):
+    """
+    Resolve a full path (e.g. "scatter.x", "layout.title.text") from the whole
+    object (figure, or current trace/layout). Returns a list of values, one per
+    applicable target; missing properties yield None.
+    """
+    prefix, suffix = path.split(".", 1) if "." in path else (path, "")
+    result = []
+    for target in _targets(whole_obj, context, prefix):
+        if not suffix:
+            result.append(target)
+            continue
+        try:
+            v = target
+            for p in suffix.split("."):
+                v = v[p]
+            result.append(v)
+        except (KeyError, TypeError, AttributeError):
+            result.append(None)
+    return result
+
+
+# -----------------------------------------------------------------------------
+# Recommendation checkers (extensible list)
+# -----------------------------------------------------------------------------
+
+
+def max_length(input_list, max_length):
+    """
+    Check if input_list has length >= max_length (e.g. recommended to keep shorter).
+    Returns a string describing the issue, or None if no issue was found.
+    """
+    if input_list is not None and hasattr(input_list, "__len__") and len(input_list) >= max_length:
+        return f"has length {len(input_list)} (recommended <= {max_length})."
+    return None
 
 
 def _recommendation_checkers():
     """
-    Return the list of (context_filter, checker_func) to run.
-    checker_func(obj, context) may call warnings.warn().
-    context is one of "figure", "trace", "layout".
-    context_filter: set of contexts this checker applies to, or None for all.
+    Return the list of (path_def, checker_func).
+
+    path_def: a dot-separated path string (e.g. "scatter.x") or list of same.
+    checker_func: called with one value per path (or None if missing). Returns
+        an issue string to warn about, or None.
     """
     return [
-        ({"trace"}, _check_scatter_xy_length),
+        ("scatter.x", partial(max_length, max_length=1000)),
+        ("scatter.y", partial(max_length, max_length=1000)),
     ]
 
 
@@ -93,32 +158,39 @@ def run_recommendations(obj, context):
     Called internally after Figure/trace/Layout construction when
     recommendations mode is enabled.
 
+    Property resolution is done here: for each checker we resolve the
+    path(s) on the applicable object(s), pass the values (or None) to the
+    checker, and catch exceptions so one checker cannot break others.
+
     Parameters
     ----------
     obj : BaseFigure | BasePlotlyType
         The constructed figure, trace, or layout.
     context : str
         One of "figure", "trace", "layout".
     """
-    if not config.enabled:
+
+    if (not config.enabled) or _is_empty(obj):
         return
+
     checkers = _recommendation_checkers()
-    # For figures, run trace checkers on each trace (traces have props set by then)
-    if context == "figure" and hasattr(obj, "data"):
-        for trace in obj.data:
-            for ctx_filter, checker in checkers:
-                if ctx_filter is not None and "trace" not in ctx_filter:
-                    continue
-                try:
-                    checker(trace, "trace")
-                except Exception:
-                    pass
-    # Run checkers for this context
-    for ctx_filter, checker in checkers:
-        if ctx_filter is not None and context not in ctx_filter:
+    stacklevel = 0
+
+    for path_def, checker in checkers:
+        if not path_def:
             continue
+        paths = [path_def] if isinstance(path_def, str) else path_def
+        value_lists = [_get_value(obj, p, context) for p in paths]
         try:
-            checker(obj, context)
+            for value_tuple in zip(*value_lists):
+                issue = checker(*value_tuple)
+                if issue:
+                    stacklevel = stacklevel or _get_stacklevel()
+                    warnings.warn(
+                        f"{path_def}: {issue}",
+                        UserWarning,
+                        stacklevel=stacklevel,
+                    )
         except Exception:
-            # Don't let a recommender break construction
             pass
+