📝 review

Author: jonasvdd

plotly_resampler/__init__.py

@@ -15,7 +15,6 @@
     "EfficientLTTB",
     "LTTB",
     "EveryNthPoint",
-    "FuncAggregator",
     "register_plotly_resampler",
     "unregister_plotly_resampler",
 ]

plotly_resampler/registering.py

@@ -1,3 +1,5 @@
+"""Register plotly-resampler to (un)wrap plotly-graph-objects."""
+
 __author__ = "Jeroen Van Der Donckt, Jonas Van Der Donckt, Emiel Deprost"
 
 from plotly_resampler import FigureResampler, FigureWidgetResampler
@@ -23,7 +25,21 @@ def _already_wrapped(constr):
     return constr.__name__.startswith(WRAPPED_PREFIX)
 
 
-def get_plotly_constr(constr):
+def _get_plotly_constr(constr):
+    """Return the constructor of the underlying plotly graph object and thus omit the
+    possibly wrapped :class:`AbstractFigureAggregator <plotly_resampler.figure_resampler.figure_resampler_interface.AbstractFigureAggregator>`
+    instance.
+
+    Parameters
+    ----------
+    constr : callable
+        The constructor of a instantiatedplotly-object.
+
+    Returns
+    -------
+    callable
+        The constructor of a ``go.FigureWidget`` or a ``go.Figure``.
+    """
     if _already_wrapped(constr):
         return constr.__wrapped__  # get the original constructor
     return constr
@@ -49,7 +65,7 @@ def _register_wrapper(
     **aggregator_kwargs,
 ):
     constr = getattr(module, constr_name)
-    constr = get_plotly_constr(constr)  # get the original plotly constructor
+    constr = _get_plotly_constr(constr)  # get the original plotly constructor
 
     # print(f"Wrapping {constr_name} with {pr_class}")
 
@@ -62,13 +78,19 @@ def wrapped_constr(*args, **kwargs):
     setattr(module, constr_name, wrapped_constr)
 
 
-def register_plotly_resampler(mode="auto", **aggregator_kwargs):  # TODO: show kwargs (e.g., port)?
+def register_plotly_resampler(mode="auto", **aggregator_kwargs):
     """Register plotly-resampler to plotly.graph_objects.
 
     This function results in the use of plotly-resampler under the hood.
 
     .. Note::
-        We advise to
+        We advise to use mode= ``widget`` when working in an IPython based environment
+        as this will just behave as a ``go.FigureWidget``, but with dynamic aggregation.
+        When using mode= ``auto`` or ``figure``; most figures will be wrapped as
+        :class:`FigureResampler <plotly_resampler.figure_resampler.FigureResampler>`,
+        on which
+        :func:`show_dash <plotly_resampler.figure_resampler.FigureResampler.show_dash>`
+        needs to be called.
 
     Parameters
     ----------
@@ -78,14 +100,14 @@ def register_plotly_resampler(mode="auto", **aggregator_kwargs):  # TODO: show k
         If 'auto' is used, the mode is determined based on the environment; if it is in
         an ipython environment, the mode is 'widget', otherwise it is 'figure'.
         If 'figure' is used, all plotly figures are wrapped as FigureResampler objects.
-        If 'widget' is used, all plotly figure widgets are wrapped as 
+        If 'widget' is used, all plotly figure widgets are wrapped as
         FigureWidgetResampler objects (we advise to use this mode in ipython environment
         with a kernel).
         If None is used, wrapping is done as expected (go.Figure -> FigureResampler,
         go.FigureWidget -> FigureWidgetResampler).
     aggregator_kwargs : dict, optional
         The keyword arguments to pass to the plotly-resampler decorator its constructor.
-        See more details in :class:`FigureResampler <FigureResampler>` and 
+        See more details in :class:`FigureResampler <FigureResampler>` and
         :class:`FigureWidgetResampler <FigureWidgetResampler>`.
 
     """

tests/test_registering.py

@@ -9,7 +9,7 @@
 from plotly_resampler.registering import (
     register_plotly_resampler,
     unregister_plotly_resampler,
-    get_plotly_constr,
+    _get_plotly_constr,
 )
 
 from .conftest import registering_cleanup
@@ -25,24 +25,24 @@ def test_get_plotly_const(registering_cleanup):
     assert not (isfunction(go.Figure) or isfunction(go.FigureWidget))
     assert not issubclass(go.Figure, AbstractFigureAggregator)
     assert not issubclass(go.FigureWidget, AbstractFigureAggregator)
-    assert not issubclass(get_plotly_constr(go.Figure), AbstractFigureAggregator)
-    assert not issubclass(get_plotly_constr(go.FigureWidget), AbstractFigureAggregator)
+    assert not issubclass(_get_plotly_constr(go.Figure), AbstractFigureAggregator)
+    assert not issubclass(_get_plotly_constr(go.FigureWidget), AbstractFigureAggregator)
 
     register_plotly_resampler()
     assert isfunction(go.Figure) and isfunction(go.FigureWidget)
     assert isinstance(go.Figure(), AbstractFigureAggregator)
     assert isinstance(go.FigureWidget(), AbstractFigureAggregator)
     assert issubclass(FigureResampler, AbstractFigureAggregator)
     assert issubclass(FigureWidgetResampler, AbstractFigureAggregator)
-    assert not issubclass(get_plotly_constr(go.Figure), AbstractFigureAggregator)
-    assert not issubclass(get_plotly_constr(go.FigureWidget), AbstractFigureAggregator)
+    assert not issubclass(_get_plotly_constr(go.Figure), AbstractFigureAggregator)
+    assert not issubclass(_get_plotly_constr(go.FigureWidget), AbstractFigureAggregator)
 
     unregister_plotly_resampler()
     assert not (isfunction(go.Figure) or isfunction(go.FigureWidget))
     assert not issubclass(go.Figure, AbstractFigureAggregator)
     assert not issubclass(go.FigureWidget, AbstractFigureAggregator)
-    assert not issubclass(get_plotly_constr(go.Figure), AbstractFigureAggregator)
-    assert not issubclass(get_plotly_constr(go.FigureWidget), AbstractFigureAggregator)
+    assert not issubclass(_get_plotly_constr(go.Figure), AbstractFigureAggregator)
+    assert not issubclass(_get_plotly_constr(go.FigureWidget), AbstractFigureAggregator)
 
 
 def test_register_and_unregister_graph_objects(registering_cleanup):