change 'args' to the more explicit 'dependencies'

Author: rmorshea

docs/source/reference-material/hooks-api.rst

@@ -124,7 +124,7 @@ then closing a connection:
 .. code-block::
 
     def establish_connection():
-        connection = open_connection(url)
+        connection = open_connection()
         return lambda: close_connection(connection)
 
     use_effect(establish_connection)
@@ -139,19 +139,21 @@ Conditional Effects
 ...................
 
 By default, effects are triggered after every successful render to ensure that all state
-referenced by the effect is up to date. However you can limit the number of times an
-effect is fired by specifying exactly what state the effect depends on. In doing so
-the effect will only occur when the given state changes:
+referenced by the effect is up to date. However, when an effect function references
+non-global variables, the effect will only if the value of that variable changes. For
+example, imagine that we had an effect that connected to a ``url`` state variable:
 
 .. code-block::
 
+    url, set_url = use_state("https://example.com")
+
     def establish_connection():
         connection = open_connection(url)
         return lambda: close_connection(connection)
 
-    use_effect(establish_connection, [url])
+    use_effect(establish_connection)
 
-Now a new connection will only be established if a new ``url`` is provided.
+Here, a new connection will be established whenever a new ``url`` is set.
 
 
 Async Effects
@@ -181,6 +183,20 @@ There are **three important subtleties** to note about using asynchronous effect
    and before the next effect following a subsequent update.
 
 
+Manual Effect Conditions
+........................
+
+In some cases, you may want to explicitely declare when an effect should be triggered.
+You can do this by passing ``dependencies`` to ``use_effect``. Each of the following values
+produce different effect behaviors:
+
+- ``use_effect(..., dependencies=None)`` - triggers and cleans up on every render.
+- ``use_effect(..., dependencies=[])`` - only triggers on the first and cleans up after
+  the last render.
+- ``use_effect(..., dependencies=[x, y])`` - triggers on the first render and on subsequent renders if
+  ``x`` or ``y`` have changed.
+
+
 Supplementary Hooks
 ===================
 
@@ -221,38 +237,32 @@ Use Callback
 
 .. code-block::
 
-    memoized_callback = use_callback(lambda: do_something(a, b), [a, b])
+    memoized_callback = use_callback(lambda: do_something(a, b))
 
 A derivative of :ref:`Use Memo`, the ``use_callback`` hook returns a
 `memoized <memoization>`_ callback. This is useful when passing callbacks to child
-components which check reference equality to prevent unnecessary renders. The of
-``memoized_callback`` will only change when the given dependencies do.
+components which check reference equality to prevent unnecessary renders. The
+``memoized_callback`` will only change when any local variables is references do.
 
 .. note::
 
-    The list of "dependencies" are not passed as arguments to the function. Ostensibly
-    though, that is what they represent. Thus any variable referenced by the function
-    must be listed as dependencies. We're
-    `working on a linter <https://github.com/idom-team/idom/issues/202>`_ to help
-    enforce this.
-
+    You may manually specify what values the callback depends on in the :ref:`same way
+    as effects <Manual Effect Conditions>` using the ``args`` parameter.
 
 
 Use Memo
 --------
 
 .. code-block::
 
-    memoized_value = use_memo(lambda: compute_something_expensive(a, b), [a, b])
+    memoized_value = use_memo(lambda: compute_something_expensive(a, b))
 
 Returns a `memoized <memoization>`_ value. By passing a constructor function accepting
 no arguments and an array of dependencies for that constructor, the ``use_callback``
 hook will return the value computed by the constructor. The ``memoized_value`` will only
-be recomputed when a value in the array of dependencies changes. This optimizes
-performance because you don't need to ``compute_something_expensive`` on every render.
-
-If the array of dependencies is ``None`` then the constructor will be called on every
-render.
+be recomputed if a local variable referenced by the constructor changes (e.g. ``a`` or
+``b`` here). This optimizes performance because you don't need to
+``compute_something_expensive`` on every render.
 
 Unlike ``use_effect`` the constructor function is called during each render (instead of
 after) and should not incur side effects.
@@ -265,11 +275,8 @@ after) and should not incur side effects.
 
 .. note::
 
-    The list of "dependencies" are not passed as arguments to the function ostensibly
-    though, that is what they represent. Thus any variable referenced by the function
-    must be listed as dependencies. We're
-    `working on a linter <https://github.com/idom-team/idom/issues/202>`_
-    to help enforce this.
+    You may manually specify what values the callback depends on in the :ref:`same way
+    as effects <Manual Effect Conditions>` using the ``args`` parameter.
 
 
 Use Ref

src/idom/core/hooks.py

@@ -109,39 +109,41 @@ def dispatch(
 @overload
 def use_effect(
     function: None = None,
-    args: Sequence[Any] | ellipsis | None = ...,
+    dependencies: Sequence[Any] | ellipsis | None = ...,
 ) -> Callable[[_EffectApplyFunc], None]:
     ...
 
 
 @overload
 def use_effect(
     function: _EffectApplyFunc,
-    args: Sequence[Any] | ellipsis | None = ...,
+    dependencies: Sequence[Any] | ellipsis | None = ...,
 ) -> None:
     ...
 
 
 def use_effect(
     function: Optional[_EffectApplyFunc] = None,
-    args: Sequence[Any] | ellipsis | None = ...,
+    dependencies: Sequence[Any] | ellipsis | None = ...,
 ) -> Optional[Callable[[_EffectApplyFunc], None]]:
     """See the full :ref:`Use Effect` docs for details
 
     Parameters:
         function:
             Applies the effect and can return a clean-up function
-        args:
-            Dependencies for the effect. If provided the effect will only trigger when
-            these args change.
+        dependencies:
+            Dependencies for the effect. The effect will only trigger if the identity
+            of any value in the given sequence changes (i.e. their :func:`id` is
+            different). By default these are inferred based on local variables that are
+            referenced by the given function.
 
     Returns:
         If not function is provided, a decorator. Otherwise ``None``.
     """
     hook = current_hook()
 
-    args = _try_to_infer_closure_args(function, args)
-    memoize = use_memo(args=args)
+    dependencies = _try_to_infer_closure_values(function, dependencies)
+    memoize = use_memo(dependencies=dependencies)
     last_clean_callback: Ref[Optional[_EffectCleanFunc]] = use_ref(None)
 
     def add_effect(function: _EffectApplyFunc) -> None:
@@ -221,34 +223,39 @@ def dispatch(action: _ActionType) -> None:
 @overload
 def use_callback(
     function: None = None,
-    args: Sequence[Any] | ellipsis | None = ...,
+    dependencies: Sequence[Any] | ellipsis | None = ...,
 ) -> Callable[[_CallbackFunc], _CallbackFunc]:
     ...
 
 
 @overload
 def use_callback(
     function: _CallbackFunc,
-    args: Sequence[Any] | ellipsis | None = ...,
+    dependencies: Sequence[Any] | ellipsis | None = ...,
 ) -> _CallbackFunc:
     ...
 
 
 def use_callback(
     function: Optional[_CallbackFunc] = None,
-    args: Sequence[Any] | ellipsis | None = ...,
+    dependencies: Sequence[Any] | ellipsis | None = ...,
 ) -> Union[_CallbackFunc, Callable[[_CallbackFunc], _CallbackFunc]]:
     """See the full :ref:`Use Callback` docs for details
 
     Parameters:
-        function: the function whose identity will be preserved
-        args: The identity the ``function`` will be udpated when these ``args`` change.
+        function:
+            The function whose identity will be preserved
+        dependencies:
+            Dependencies of the callback. The identity the ``function`` will be udpated
+            if the identity of any value in the given sequence changes (i.e. their
+            :func:`id` is different). By default these are inferred based on local
+            variables that are referenced by the given function.
 
     Returns:
         The current function
     """
-    args = _try_to_infer_closure_args(function, args)
-    memoize = use_memo(args=args)
+    dependencies = _try_to_infer_closure_values(function, dependencies)
+    memoize = use_memo(dependencies=dependencies)
 
     def setup(function: _CallbackFunc) -> _CallbackFunc:
         return memoize(lambda: function)
@@ -269,49 +276,54 @@ def __call__(self, func: Callable[[], _StateType]) -> _StateType:
 @overload
 def use_memo(
     function: None = None,
-    args: Sequence[Any] | ellipsis | None = ...,
+    dependencies: Sequence[Any] | ellipsis | None = ...,
 ) -> _LambdaCaller:
     ...
 
 
 @overload
 def use_memo(
     function: Callable[[], _StateType],
-    args: Sequence[Any] | ellipsis | None = ...,
+    dependencies: Sequence[Any] | ellipsis | None = ...,
 ) -> _StateType:
     ...
 
 
 def use_memo(
     function: Optional[Callable[[], _StateType]] = None,
-    args: Sequence[Any] | ellipsis | None = ...,
+    dependencies: Sequence[Any] | ellipsis | None = ...,
 ) -> Union[_StateType, Callable[[Callable[[], _StateType]], _StateType]]:
     """See the full :ref:`Use Memo` docs for details
 
     Parameters:
-        function: The function to be memoized.
-        args: The ``function`` will be recomputed when these args change.
+        function:
+            The function to be memoized.
+        dependencies:
+            Dependencies for the memoized function. The memo will only be recomputed if
+            the identity of any value in the given sequence changes (i.e. their
+            :func:`id` is different). By default these are inferred based on local
+            variables that are referenced by the given function.
 
     Returns:
         The current state
     """
-    args = _try_to_infer_closure_args(function, args)
+    dependencies = _try_to_infer_closure_values(function, dependencies)
 
     memo: _Memo[_StateType] = _use_const(_Memo)
 
     if memo.empty():
         # we need to initialize on the first run
         changed = True
-        memo.args = () if args is None else args
-    elif args is None:
+        memo.deps = () if dependencies is None else dependencies
+    elif dependencies is None:
         changed = True
-        memo.args = ()
+        memo.deps = ()
     elif (
-        len(memo.args) != len(args)
-        # if args are same length check identity for each item
-        or any(current is not new for current, new in zip(memo.args, args))
+        len(memo.deps) != len(dependencies)
+        # if deps are same length check identity for each item
+        or any(current is not new for current, new in zip(memo.deps, dependencies))
     ):
-        memo.args = args
+        memo.deps = dependencies
         changed = True
     else:
         changed = False
@@ -338,10 +350,10 @@ def setup(function: Callable[[], _StateType]) -> _StateType:
 class _Memo(Generic[_StateType]):
     """Simple object for storing memoization data"""
 
-    __slots__ = "value", "args"
+    __slots__ = "value", "deps"
 
     value: _StateType
-    args: Sequence[Any]
+    deps: Sequence[Any]
 
     def empty(self) -> bool:
         try:
@@ -368,11 +380,11 @@ def _use_const(function: Callable[[], _StateType]) -> _StateType:
     return current_hook().use_state(function)
 
 
-def _try_to_infer_closure_args(
+def _try_to_infer_closure_values(
     func: Callable[..., Any] | None,
-    args: Sequence[Any] | ellipsis | None,
+    values: Sequence[Any] | ellipsis | None,
 ) -> Sequence[Any] | None:
-    if args is ...:
+    if values is ...:
         if isinstance(func, FunctionType):
             return (
                 [cell.cell_contents for cell in func.__closure__]
@@ -382,7 +394,7 @@ def _try_to_infer_closure_args(
         else:
             return None
     else:
-        return cast("Sequence[Any] | None", args)
+        return cast("Sequence[Any] | None", values)
 
 
 _current_life_cycle_hook: Dict[int, "LifeCycleHook"] = {}