solara-ui 1.36.0__tar.gz → 1.37.0__tar.gz

{solara_ui-1.36.0 → solara_ui-1.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: solara-ui
-Version: 1.36.0
+Version: 1.37.0
 Dynamic: Summary
 Project-URL: Home, https://www.github.com/widgetti/solara
 Project-URL: Documentation, https://solara.dev

{solara_ui-1.36.0 → solara_ui-1.37.0}/pyproject.toml

@@ -86,6 +86,9 @@ fix = false
 line-length = 160
 lint.ignore = ["E402"]
 
+[tool.black]
+line-length = 160
+
 [tool.pytest.ini_options]
 addopts = "--ignore=tests/integration/app_widget.py  --ignore=tests/unit/solara_test_apps"
 timeout = 180

{solara_ui-1.36.0 → solara_ui-1.37.0}/solara/__init__.py

@@ -1,6 +1,6 @@
 """Build webapps using IPywidgets"""
 
-__version__ = "1.36.0"
+__version__ = "1.37.0"
 github_url = "https://github.com/widgetti/solara"
 git_branch = "master"
 
@@ -21,7 +21,6 @@ def _using_solara_server():
 # isort: skip_file
 # ruff: noqa: F401 F403
 from reacton import (
-    component,
     component_interactive,
     value_component,
     create_context,
@@ -42,6 +41,7 @@ from reacton import (
     use_state_widget,
 )
 from reacton.core import Element
+from .core import component
 
 try:
     import ipyvuetify.components as v  # type: ignore

{solara_ui-1.36.0 → solara_ui-1.37.0}/solara/autorouting.py

@@ -4,6 +4,7 @@ import importlib
 import inspect
 import pkgutil
 import re
+import linecache
 import warnings
 from pathlib import Path
 from types import ModuleType
@@ -46,7 +47,17 @@ def source_to_module(path: Path, initial_namespace={}) -> ModuleType:
                 cell_index += 1  # used 1 based
                 if cell.cell_type == "code":
                     source = cell.source
-                    cell_path = f"{path} input cell {cell_index}"
+                    # similar to ipython/ipython/IPython/core/compilerop.py
+                    # inspect.py:findsource accepts non-filenames with '<' and '>' around it
+                    cell_path = f"<{str(path)} input cell {cell_index}>"
+                    # put an entry in linecache so that we can use inspect.getsource
+                    entry = (
+                        len(source),
+                        None,
+                        [line + "\n" for line in source.splitlines()],
+                        cell_path,
+                    )
+                    linecache.cache[cell_path] = entry
                     ast = compile(source, cell_path, "exec")
                     exec(ast, mod.__dict__)
     else:

solara_ui-1.37.0/solara/core.py

@@ -0,0 +1,42 @@
+import warnings
+from typing import Any, Callable, Dict, Union, overload, TypeVar
+import typing_extensions
+import reacton
+from . import validate_hooks
+
+
+P = typing_extensions.ParamSpec("P")
+FuncT = TypeVar("FuncT", bound=Callable[..., reacton.core.Element])
+
+
+@overload
+def component(obj: None = None, mime_bundle: Dict[str, Any] = ...) -> Callable[[FuncT], FuncT]: ...
+
+
+@overload
+def component(obj: FuncT, mime_bundle: Dict[str, Any] = ...) -> FuncT: ...
+
+
+@overload
+def component(obj: Callable[P, None], mime_bundle: Dict[str, Any] = ...) -> Callable[P, reacton.core.Element]: ...
+
+
+def component(
+    obj: Union[Callable[P, None], FuncT, None] = None, mime_bundle: Dict[str, Any] = reacton.core.mime_bundle_default
+) -> Union[Callable[[FuncT], FuncT], FuncT, Callable[P, reacton.core.Element]]:
+    def wrapper(obj: Union[Callable[P, None], FuncT]) -> FuncT:
+        try:
+            validate_hooks.HookValidator(obj).run()
+        except Exception as e:
+            if not isinstance(e, validate_hooks.HookValidationError):
+                # we probably failed because of a unknown reason, but we do not want to break the user's code
+                warnings.warn(f"Failed to validate hooks for component {obj.__qualname__}: {e}")
+            else:
+                raise
+
+        return reacton.component(obj, mime_bundle)  # type: ignore
+
+    if obj is not None:
+        return wrapper(obj)
+    else:
+        return wrapper

{solara_ui-1.36.0 → solara_ui-1.37.0}/solara/server/server.py

@@ -452,8 +452,9 @@ def get_nbextensions() -> Tuple[List[str], Dict[str, Optional[str]]]:
                 file_path = directory / (name + ".js")
                 if file_path.exists():
                     for file in directory.glob("**/*.*"):
-                        data = file.read_bytes()
-                        h.update(data)
+                        if file.is_file():  # Otherwise directories with a dot in the name are included
+                            data = file.read_bytes()
+                            h.update(data)
             except PermissionError:
                 logger.warning(f"Caught PermissionError while checking for existence of nbextension {name!r} at path: {file_path}. This path will be ignored.")
 

{solara_ui-1.36.0 → solara_ui-1.37.0}/solara/server/static/solara_bootstrap.py

@@ -119,7 +119,7 @@ async def main():
     ]
     for dep in requirements:
         await micropip.install(dep, keep_going=True)
-    await micropip.install("/wheels/solara-1.36.0-py2.py3-none-any.whl", keep_going=True)
+    await micropip.install("/wheels/solara-1.37.0-py2.py3-none-any.whl", keep_going=True)
     import solara
 
     el = solara.Warning("lala")

{solara_ui-1.36.0 → solara_ui-1.37.0}/solara/settings.py

@@ -52,5 +52,18 @@ class Assets(BaseSettings):
         env_file = ".env"
 
 
+class MainSettings(BaseSettings):
+    check_hooks: str = "warn"
+
+    class Config:
+        env_prefix = "solara_"
+        case_sensitive = False
+        env_file = ".env"
+
+
 assets: Assets = Assets()
 cache: Cache = Cache()
+main = MainSettings()
+
+if main.check_hooks not in ["off", "warn", "raise"]:
+    raise ValueError(f"Invalid value for check_hooks: {main.check_hooks}, expected one of ['off', 'warn', 'raise']")

solara_ui-1.37.0/solara/validate_hooks.py

@@ -0,0 +1,260 @@
+import ast
+import inspect
+import re
+import typing as t
+from enum import Enum
+import sys
+import warnings
+
+DEFAULT_USE_FUNCTIONS = ("^use_.*$",)
+
+
+class InvalidReactivityCause(Enum):
+    USE_AFTER_RETURN = "early return"
+    CONDITIONAL_USE = "conditional"
+    LOOP_USE = "loop"
+    NESTED_FUNCTION_USE = "nested function"
+    VARIABLE_ASSIGNMENT = "assignment"
+    EXCEPTION_USE = "exception"
+
+
+noqa_code_to_cause = {
+    "SH101": InvalidReactivityCause.USE_AFTER_RETURN,
+    "SH102": InvalidReactivityCause.CONDITIONAL_USE,
+    "SH103": InvalidReactivityCause.LOOP_USE,
+    "SH104": InvalidReactivityCause.NESTED_FUNCTION_USE,
+    "SH105": InvalidReactivityCause.VARIABLE_ASSIGNMENT,
+    "SH106": InvalidReactivityCause.EXCEPTION_USE,
+}
+cause_to_noqa_code = {v: k for k, v in noqa_code_to_cause.items()}
+noqa_pattern = re.compile(r".*# noqa(?::\s*([A-Z]{2,3}\d{2,3})(?:,\s*([A-Z]{2,3}\d{2,3}))*)?")
+
+
+if sys.version_info < (3, 11):
+    ScopeNodeType = t.Union[ast.For, ast.While, ast.If, ast.Try, ast.FunctionDef]
+    TryNodes = (ast.Try,)
+else:
+    # except* nodes are only standardized in 3.11+
+    ScopeNodeType = t.Union[ast.For, ast.While, ast.If, ast.Try, ast.TryStar, ast.FunctionDef]
+    TryNodes = (ast.Try, ast.TryStar)
+
+
+def line_to_noqa(line: str) -> t.Optional[t.Set[InvalidReactivityCause]]:
+    """Return set of noqa code for which to not do quality assurance checks, or None when to do all qa."""
+    if "#" in line:
+        no_qa = set()
+        match = noqa_pattern.match(line)
+        if match is not None:
+            # not sure why we get some None values
+            groups = [k for k in match.groups() if k is not None]
+            if groups:  # `noqa: SHXXX`` found
+                for group in groups:
+                    if group not in noqa_code_to_cause:
+                        if group.startswith("SH"):
+                            raise ValueError(f"Unknown noqa code {group}")
+                    else:
+                        no_qa.add(noqa_code_to_cause[group])
+            else:  # we found `noqa`
+                # skip all qa
+                no_qa = set(noqa_code_to_cause.values())
+            return no_qa
+        else:
+            return None  # no noqa found
+    return None  # fast path, no comment found
+
+
+def should_skip_qa(global_no_qa: t.Optional[t.Set[InvalidReactivityCause]], cause: InvalidReactivityCause, line: str) -> bool:
+    line_qa = line_to_noqa(line)
+    if global_no_qa is None and line_qa is None:
+        # there is not a noqa on the function or line
+        return False
+    else:
+        noqa = global_no_qa or set()
+        if line_qa is not None:
+            noqa |= line_qa
+        return cause in noqa
+
+
+class HookValidationError(Exception):
+    def __init__(self, cause: InvalidReactivityCause, message: str):
+        self.cause = cause
+        super().__init__(message)
+
+
+class HookValidator(ast.NodeVisitor):
+    def __init__(self, component: t.Callable, use_functions=DEFAULT_USE_FUNCTIONS):
+        self.use_functions = [re.compile(use_func) for use_func in use_functions]
+
+        self.root_function_return: t.Optional[ast.Return] = None
+        self.outer_scope: t.Optional[ScopeNodeType] = None
+
+        self.filename = component.__code__.co_filename
+        self.line_offset = component.__code__.co_firstlineno - 1
+        self.component = component
+
+        self.source = inspect.getsource(self.component)
+        # lines before we dedent
+        self.lines = self.source.split("\n")
+        # dedent the source code to avoid indentation errors
+        parsed_source = inspect.cleandoc(self.source)
+        parsed = ast.parse(parsed_source)
+        # Get nodes from inside the function body
+        func_definition = t.cast(ast.FunctionDef, parsed.body[0])
+        self.function_scope: ast.FunctionDef = func_definition
+        self._root_function_scope = self.function_scope
+        # None means, *DO* qa
+        self.no_qa: t.Optional[t.Set[InvalidReactivityCause]] = None
+
+    def run(self):
+        import solara.settings
+
+        if solara.settings.main.check_hooks == "off":
+            return
+        func_def_line = self.lines[self._root_function_scope.lineno - 1]
+        self.no_qa = line_to_noqa(func_def_line)
+        try:
+            for node in self._root_function_scope.body:
+                self.visit(node)
+        except HookValidationError as e:
+            if solara.settings.main.check_hooks == "error":
+                raise e
+            elif solara.settings.main.check_hooks == "warn":
+                warnings.warn(str(e))
+
+    def matches_use_function(self, name: str) -> bool:
+        return any(use_func.match(name) for use_func in self.use_functions)
+
+    def node_to_scope_cause(self, node: ScopeNodeType) -> InvalidReactivityCause:
+        if isinstance(node, ast.If):
+            return InvalidReactivityCause.CONDITIONAL_USE
+        elif isinstance(node, (ast.For, ast.While)):
+            return InvalidReactivityCause.LOOP_USE
+        elif isinstance(node, ast.FunctionDef):
+            return InvalidReactivityCause.NESTED_FUNCTION_USE
+        elif isinstance(node, TryNodes):
+            return InvalidReactivityCause.EXCEPTION_USE
+        else:
+            warnings.warn(f"Unexpected scope node type: {node}, line={node.lineno}")
+
+    def visit_Call(self, node: ast.Call):
+        """Records calls of use functions, i.e. solara.use_state(...)"""
+        func = node.func
+        if isinstance(func, ast.Call):
+            # Nested function, it will appear in another node later
+            return
+        if isinstance(func, ast.Name):
+            id_ = func.id
+        elif isinstance(func, ast.Attribute):
+            id_ = func.attr
+        else:
+            warnings.warn(f"Unexpected function node type: {func}, line={node.lineno}")
+            return
+        if self.matches_use_function(id_):
+            self.error_on_early_return(node, id_)
+            self.error_on_invalid_scope(node, id_)
+        self.generic_visit(node)
+
+    def visit_If(self, node: ast.If):
+        self._visit_children_using_scope(node)
+
+    def visit_For(self, node: ast.For):
+        self._visit_children_using_scope(node)
+
+    def visit_While(self, node: ast.While):
+        self._visit_children_using_scope(node)
+
+    def visit_Try(self, node: ast.Try) -> t.Any:
+        self._visit_children_using_scope(node)
+
+    if sys.version_info >= (3, 11):
+
+        def visit_TryStar(self, node: ast.TryStar) -> t.Any:
+            self._visit_children_using_scope(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        old_function_scope = self.function_scope
+        self.function_scope = node
+        self._visit_children_using_scope(node)
+        self.function_scope = old_function_scope
+
+    def _visit_children_using_scope(self, node: ScopeNodeType):
+        outer_scope = self.outer_scope
+        self.outer_scope = node
+        for child in node.body:
+            self.visit(child)
+        self.outer_scope = outer_scope
+
+    def visit_Assign(self, node: ast.Assign):
+        self.error_on_invalid_assign(node)
+        self.generic_visit(node)
+
+    def visit_Return(self, node: ast.Return):
+        """
+        Records the earliest return statement in the function
+        """
+        # Returns are valid in nested functions
+        if self.function_scope != self._root_function_scope:
+            return
+        self.root_function_return = node
+        self.generic_visit(node)
+
+    def error_on_invalid_assign(self, node: ast.Assign):
+        if isinstance(node.value, ast.Attribute) and self.matches_use_function(node.value.attr):
+            line = node.lineno + self.line_offset
+            cause = InvalidReactivityCause.VARIABLE_ASSIGNMENT
+            message = f"Assigning the hook `{node.value.attr}` to a variable is not allowed since it complicates the tracking of valid hook use {_hint_supress(line, cause)}"
+
+            raise HookValidationError(
+                cause,
+                f"{self.get_source_context(line)}: {message}",
+            )
+
+    def error_on_early_return(self, use_node: ast.Call, use_node_id: str):
+        """
+        Checks if the latest use of a reactive function occurs after the earliest return
+        """
+        if self.root_function_return and self.root_function_return.lineno <= use_node.lineno:
+            offset_return = self.root_function_return.lineno + self.line_offset
+            offset_use = use_node.lineno + self.line_offset
+            cause = InvalidReactivityCause.USE_AFTER_RETURN
+            line = self.lines[use_node.lineno - 1]
+            if should_skip_qa(self.no_qa, cause, line):
+                return
+
+            raise HookValidationError(
+                cause,
+                f"""{self.get_source_context(offset_use)}: `{use_node_id}` found despite early return on line {offset_return}
+{_hint_supress(line, cause)}""",
+            )
+
+    def error_on_invalid_scope(self, use_node: ast.Call, use_node_id: str):
+        """
+        Checks if the latest use of a reactive function occurs after the earliest return or in an invalid scope
+        such as try-except blocks.
+        """
+        if self.outer_scope is None:
+            return
+        offset_use = use_node.lineno + self.line_offset
+        cause = self.node_to_scope_cause(self.outer_scope)
+
+        scope_line = self.outer_scope.lineno + self.line_offset
+        line = self.lines[use_node.lineno - 1]
+        if should_skip_qa(self.no_qa, cause, line):
+            return
+        raise HookValidationError(
+            cause,
+            f"""{self.get_source_context(offset_use)}: `{use_node_id}` found within a {cause.value} created on line {scope_line}
+{_hint_supress(line, cause)}""",
+        )
+
+    def get_source_context(self, lineno):
+        return f"{self.filename}:{lineno}: {self.component.__qualname__}"
+
+
+def _hint_supress(line, cause):
+    return f"""To suppress this check, replace the line with:
+{line}  # noqa: {cause_to_noqa_code[cause]}
+
+Make sure you understand the consequences of this, by reading about the rules of hooks at:
+    https://solara.dev/documentation/advanced/understanding/rules-of-hooks
+"""

solara_ui-1.37.0/solara/website/pages/documentation/advanced/content/20-understanding/17-rules-of-hooks.md

@@ -0,0 +1,192 @@
+---
+title: The rules of hooks in Solara
+description: Learn the rules that govern the usage of hooks in your Solara application.
+----
+# Rules of hooks
+
+Hooks are Python function whose name start with `use_`. The most used hook is [use_state](https://solara.dev/documentation/api/hooks/use_state) which is used to manage the state of a component.
+
+Hooks can only be called at the top level of a function component or a custom hook. They cannot be called inside loops, conditions, or nested functions.
+The reason for this is that hooks rely on the order in which they are called to maintain state between renders. If a hook is called conditionally, it may not be called on every render, which can mix up the states.
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    x, set_x = solara.use_state(1)  # state 'slot' 1
+    if x < 10:
+        y, set_y = solara.use_state(2)  # state 'slot' 2
+    else:
+        y, set_y = solara.use_state("foo") # *also* state 'slot' 2
+    solara.Text("Done")
+```
+
+In the above example, the `use_state(2)` and `use_state("foo")` is called conditionally, which means that the state 'slot' 2 (meaning, `y` and `set_y`) sometimes refer to the integer `2` and sometimes to the string `"foo"`. This gives unexpected behavior and will lead to bugs.
+
+
+The rules of hooks are checked by Solara, if you break the rules, you will get a warning, and in the future (Solara v2.0) you will get an error (an exception is raised).
+
+## Example
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    for i in range(10):
+        solara.use_state(1)
+    solara.Text("Done")
+```
+
+Will give the warning:
+```
+/some/prefix/site-packages/solara/solara/validate_hooks.py:122: UserWarning: /my/app.py:56: Page: `use_state` found within a loop created on line 55
+To suppress this check, replace the line with:
+                solara.use_state(1)  # noqa: SH103
+
+Make sure you understand the consequences of this, by reading about the rules of hooks at:
+    https://solara.dev/documentation/advanced/understanding/rules-of-hooks
+```
+
+As the warning suggests, you can suppress the warning by adding `# noqa: SH103` to the line that breaks the rules.
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    for i in range(10):
+        solara.use_state(1)  # noqa: SH103
+
+    solara.Text("Done")
+```
+
+The warning can also be suppressed for the whole component by adding `# noqa: SH103` to the function definition.
+
+```python
+import solara
+
+
+@solara.component
+def Page():  # noqa: SH103
+    for i in range(10):
+        solara.use_state(1)
+
+    solara.Text("Done")
+```
+
+
+However, we strongly advise against this, and you should only use it if you know what you are doing (knowing the the loop will always run a fixed amount of times).
+
+If you want to have an error raised instead of a warning, you can set the environment variable `SOLARA_CHECK_HOOKS=raise`, this is
+planned to be the default in Solara v2.0.
+
+In that case, you should get an error like this:
+
+```
+
+solara.validate_hooks.HookValidationError: /my/app.py:56: Page: `use_state` found within a loop created on line 55
+To suppress this check, replace the line with:
+                solara.use_state(1)  # noqa: SH103
+
+Make sure you understand the consequences of this, by reading about the rules of hooks at:
+    https://solara.dev/documentation/advanced/understanding/rules-of-hooks
+```
+
+
+For convenience, you can also disable the check by setting the environment variable `SOLARA_CHECK_HOOKS=off`, but we strongly advise against this.
+
+## Types of error
+
+### Early return (SH101)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+     solara.Text("Done")
+    if x < 10:
+        return  # will cause the below use_state to not always be called
+    solara.use_state(1)
+```
+
+### Conditional use (SH102)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    if x < 10:
+        solara.use_state(1)  # will cause the use_state to not always be called
+    solara.Text("Done")
+```
+
+
+### Loop use (SH103)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    for i in range(x):
+        solara.use_state(1)  # will cause the use_state to not always be a constant number of times
+    solara.Text("Done")
+```
+
+### Nested function use (SH104)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    def inner():
+        solara.use_state(1)  # will use_state always be called? Difficult to analyze, so don't do it
+    inner()
+    solara.Text("Done")
+```
+
+
+### Variable assignment (SH105)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    x = solara.use_state
+    x(1)  # will use_state always be called? Difficult to analyze, so don't do it
+    solara.Text("Done")
+```
+
+
+### Exception use (SH106)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    try:
+        this_might_fail()
+        solara.use_state(1)  # will use_state always be called? Difficult to analyze, so don't do it
+    except:
+        pass
+    solara.Text("Done")
+```
+
+For this reason, it's also advised to always call hooks first, before doing anything else in a function component that might raise
+an exception.