added docstrings

Author: AnnMarieW

dash/_callback_context.py

@@ -50,6 +50,18 @@ def states(self):
     @property
     @has_context
     def triggered(self):
+        """
+         Returns a list of all the Input props that changed and caused the callback to execute. It is empty when the callback is
+          called on initial load, unless an Input prop got its value from another initial callback. Callbacks triggered
+           by user actions typically have one item in triggered, unless the same action changes two props at once or
+            the callback has several Input props that are all modified by another callback based on a single user action.
+
+        Example:  To get the id of the component that triggered the callback:
+        `component_id = ctx.triggered[0]['prop_id'].split('.')[0]`
+
+        Example:  To detect initial call, empty triggered is not really empty, it's falsy so that you can use:
+        `if ctx.triggered:`
+        """
         # For backward compatibility: previously `triggered` always had a
         # value - to avoid breaking existing apps, add a dummy item but
         # make the list still look falsy. So `if ctx.triggered` will make it
@@ -59,6 +71,26 @@ def triggered(self):
     @property
     @has_context
     def triggered_prop_ids(self):
+        """
+        Returns a dictionary of all the Input props that changed and caused the callback to execute. It is empty when the callback is
+          called on initial load, unless an Input prop got its value from another initial callback. Callbacks triggered
+           by user actions typically have one item in triggered, unless the same action changes two props at once or
+            the callback has several Input props that are all modified by another callback based on a single user action.
+
+        triggered_prop_ids (dict):
+        - keys (str) : the triggered "prop_id" composed of "component_id.component_property"
+        - values (str or dict): the id of the component that triggered the callback. Will be the dict id for pattern matching callbacks
+
+        Example - regular callback
+        {"btn-1.n_clicks": "btn-1"}
+
+        Example - pattern matching callbacks:
+        {'{"index":0,"type":"filter-dropdown"}.value': {"index":0,"type":"filter-dropdown"}}
+
+        Example usage:
+        `if "btn-1.n_clicks" in ctx.triggered_prop_ids:
+            do_something()`
+        """
         triggered = getattr(flask.g, "triggered_inputs", [])
         ids = AttributeDict({})
         for item in triggered:
@@ -71,6 +103,17 @@ def triggered_prop_ids(self):
     @property
     @has_context
     def triggered_id(self):
+        """
+        Returns the component id (str or dict) of the Input component that triggered the callback.
+
+        Note - use `triggered_prop_ids` if you need both the component id and the prop that triggered the callback or if
+        multiple Inputs triggered the callback.
+
+        Example usage:
+        `if "btn-1" == ctx.triggered_id:
+            do_something()`
+
+        """
         component_id = None
         if self.triggered:
             prop_id = self.triggered_prop_ids.first()
@@ -80,6 +123,30 @@ def triggered_id(self):
     @property
     @has_context
     def args_grouping(self):
+        """
+        args_grouping is a dict of the inputs used with flexible callback signatures. The keys are the variable names
+        and the values are dictionaries containing:
+        - “id”: (string or dict) the component id. If it’s a pattern matching id, it will be a dict.
+        - “id_str”: (str) for pattern matching ids, it’s the strigified dict id with no white spaces.
+        - “property”: (str) The component property used in the callback.
+        - “value”: the value of the component property at the time the callback was fired.
+        - “triggered”: (bool)Whether this input triggered the callback.
+
+        Example usage:
+        @app.callback(
+            Output("container", "children"),
+            inputs=dict(btn1=Input("btn-1", "n_clicks"), btn2=Input("btn-2", "n_clicks")),
+        )
+        def display(btn1, btn2):
+            c = ctx.args_grouping
+            if c.btn1.triggered:
+                return f"Button 1 clicked {btn1} times"
+            elif c.btn2.triggered:
+                return f"Button 2 clicked {btn2} times"
+            else:
+               return "No clicks yet"
+
+        """
         triggered = getattr(flask.g, "triggered_inputs", [])
         triggered = [item["prop_id"] for item in triggered]
         grouping = getattr(flask.g, "args_grouping", {})