Merge pull request #58 from bcdev/forman-x-fix_py_api_and_docs

Updated API + Docs

Author: forman

chartlets.py/chartlets/callback.py

@@ -22,7 +22,7 @@ def from_decorator(
         decorator_name: str,
         decorator_args: tuple[Any, ...],
         function: Any,
-        outputs_allowed: bool = False,
+        states_only: bool = False,
     ) -> "Callback":
         try:
             signature = inspect.signature(function)
@@ -45,22 +45,22 @@ def from_decorator(
         inputs: list[Input | State] = []
         outputs: list[Output] = []
         for arg in decorator_args:
-            if isinstance(arg, (Input, State)):
-                inputs.append(arg)
-            elif outputs_allowed and isinstance(arg, Output):
-                outputs.append(arg)
-            elif outputs_allowed:
+            if states_only and not isinstance(arg, State):
                 raise TypeError(
                     f"arguments for decorator {decorator_name!r}"
-                    f" must be of type Input, State, Output, AppInput,"
-                    f" or AppOutput, but got {arg.__class__.__name__!r}"
+                    f" must be of type State,"
+                    f" but got {arg.__class__.__name__!r}"
                 )
-            else:
+            if not isinstance(arg, (Input, State, Output)):
                 raise TypeError(
                     f"arguments for decorator {decorator_name!r}"
-                    f" must be of type Input,"
+                    f" must be of type Input, State, or Output,"
                     f" but got {arg.__class__.__name__!r}"
                 )
+            if isinstance(arg, Output):
+                outputs.append(arg)
+            else:
+                inputs.append(arg)
 
         num_params = len(signature.parameters) - 1
         num_inputs = len(inputs)

chartlets.py/chartlets/contribution.py

@@ -2,7 +2,7 @@
 from abc import ABC
 
 from .callback import Callback
-from .channel import Channel
+from .channel import Input, State, Output
 
 
 class Contribution(ABC):
@@ -20,7 +20,7 @@ class Contribution(ABC):
     """
 
     # noinspection PyShadowingBuiltins
-    def __init__(self, name: str, **initial_state):
+    def __init__(self, name: str, **initial_state: Any):
         self.name = name
         self.initial_state = initial_state
         self.extension: str | None = None
@@ -47,7 +47,7 @@ def to_dict(self) -> dict[str, Any]:
             d.update(callbacks=[cb.to_dict() for cb in self.callbacks])
         return d
 
-    def layout(self, *args) -> Callable[[Callable], Callable]:
+    def layout(self, *args: State) -> Callable[[Callable], Callable]:
         """Provides a decorator for a user-provided function that
         returns the initial user interface layout.
 
@@ -65,13 +65,12 @@ def layout(self, *args) -> Callable[[Callable], Callable]:
         called `ctx`.
 
         Other parameters of the decorated function are user-defined
-        and must have a corresponding `chartlets.Input` or
-        `chartlets.State` arguments in the `layout` decorator in the
-        same order.
+        and must have a corresponding `chartlets.State` arguments
+        in the `layout` decorator in the same order.
 
         Args:
             args:
-                `chartlets.Input` or `chartlets.State` objects that
+                `chartlets.State` objects that
                 define the source of the value for the corresponding
                 parameter of the decorated function. Optional.
 
@@ -81,13 +80,13 @@ def layout(self, *args) -> Callable[[Callable], Callable]:
 
         def decorator(function: Callable) -> Callable:
             self.layout_callback = Callback.from_decorator(
-                "layout", args, function, outputs_allowed=False
+                "layout", args, function, states_only=True
             )
             return function
 
         return decorator
 
-    def callback(self, *args: Channel) -> Callable[[Callable], Callable]:
+    def callback(self, *args: Input | State | Output) -> Callable[[Callable], Callable]:
         """Provide a decorator for a user-provided callback function.
 
         Callback functions are event handlers that react
@@ -125,7 +124,7 @@ def callback(self, *args: Channel) -> Callable[[Callable], Callable]:
         def decorator(function: Callable) -> Callable:
             self.callbacks.append(
                 Callback.from_decorator(
-                    "callback", args, function, outputs_allowed=True
+                    "callback", args, function, states_only=False
                 )
             )
             return function

chartlets.py/my_extension/my_panel_2.py

@@ -1,7 +1,7 @@
 import altair as alt
 import pandas as pd
 
-from chartlets import Component, Input, Output
+from chartlets import Component, Input, State, Output
 from chartlets.components import Plot, Box, Select
 from chartlets.demo.contribs import Panel
 from chartlets.demo.context import Context
@@ -10,7 +10,7 @@
 panel = Panel(__name__, title="Panel B")
 
 
-@panel.layout(Input("@app", "selectedDatasetId"))
+@panel.layout(State("@app", "selectedDatasetId"))
 def render_panel(
     ctx: Context,
     selected_dataset_id: str = "",

chartlets.py/my_extension/my_panel_3.py

@@ -11,7 +11,7 @@
 
 
 @panel.layout(
-    Input("@app", "selectedDatasetId"),
+    State("@app", "selectedDatasetId"),
 )
 def render_panel(
     ctx: Context,

chartlets.py/tests/callback_test.py

@@ -158,16 +158,17 @@ def test_decorator_target(self):
     def test_decorator_args(self):
         with pytest.raises(
             TypeError,
-            match="arguments for decorator 'test' must be of"
-            " type Input, but got 'int'",
+            match=(
+                "arguments for decorator 'test' must be of type"
+                " Input, State, or Output, but got 'int'"
+            ),
         ):
             Callback.from_decorator("test", (13,), my_callback)
 
         with pytest.raises(
             TypeError,
             match=(
-                "arguments for decorator 'test' must be of type Input,"
-                " State, Output, AppInput, or AppOutput, but got 'int'"
+                "arguments for decorator 'test' must be of type State, but got 'int'"
             ),
         ):
-            Callback.from_decorator("test", (13,), my_callback, outputs_allowed=True)
+            Callback.from_decorator("test", (13,), my_callback, states_only=True)

docs/api/components.md

@@ -18,10 +18,12 @@ and providers:
 
 ::: chartlets.components.Checkbox
 
-::: chartlets.components.Dropdown
+::: chartlets.components.IconButton
 
 ::: chartlets.components.Plot
 
+::: chartlets.components.Select
+
 ::: chartlets.components.Typography
 
 ## Base classes