From 03376f7ceac1f78706a1bdaa52fc37a82e6697e1 Mon Sep 17 00:00:00 2001
From: Kaustubh Maske Patil <37668193+nikochiko@users.noreply.github.com>
Date: Mon, 31 Mar 2025 22:07:54 +0530
Subject: [PATCH] Add docstring for `run_in_thread`

To:
- clarify the behavior
- add note that it won't work with inline functions - lambdas and closures.
---
 py/gooey_gui/core/state_interactions.py | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/py/gooey_gui/core/state_interactions.py b/py/gooey_gui/core/state_interactions.py
index 610043c..40c78c7 100644
--- a/py/gooey_gui/core/state_interactions.py
+++ b/py/gooey_gui/core/state_interactions.py
@@ -47,6 +47,21 @@ def run_in_thread(
     key: str | None = None,
     ex=60,
 ):
+    """
+    Creates a new thread to run `fn(*args, **kwargs)`.
+
+    Returns:
+    - `None` until the function call is executing.
+    - The returned value of `fn(*args, **kwargs)` on the next call.
+      If `cache=True`, the same value will be cached in the `session_state`.
+      Further calls to `run_in_thread(fn, ...)` will return the same value
+      until the `session_state` is reset (e.g. with a page refresh).
+
+    Note that `fn.__name__` is used in the cache key. Because of this,
+    it won't work with `lambda`s and closures that don't have a fixed
+    value for `__name__`.
+    """
+
     if key is None:
         key = f"{run_in_thread.__name__}/{fn}"