solara-ui 1.45.0__py3-none-any.whl

solara/util.py

@@ -0,0 +1,348 @@
+import base64
+import contextlib
+import functools
+import gzip
+import hashlib
+import json
+import os
+import sys
+import threading
+from collections import abc
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Union
+from urllib.parse import urlencode
+
+if TYPE_CHECKING:
+    import numpy as np
+
+import ipyvuetify
+import ipywidgets
+import reacton
+
+import solara
+
+SOLARA_ALLOW_OTHER_TRACER = os.environ.get("SOLARA_ALLOW_OTHER_TRACER", False) in (True, "True", "true", "1")
+ipyvuetify_major_version = int(ipyvuetify.__version__.split(".")[0])
+ipywidgets_major = int(ipywidgets.__version__.split(".")[0])
+
+try:
+    threading.Thread(target=lambda: None).start()
+    has_threads = True
+except RuntimeError:
+    has_threads = False
+
+
+from reacton.utils import equals as equals_extra
+
+
+def equals_pickle(a, b):
+    """Compare two values for equality.
+
+    Avoid false negative, e.g. when comparing dataframes, we want to compare
+    the data, not the object identity.
+
+    """
+    if equals_extra(a, b):
+        return True
+    import pickle
+
+    try:
+        if pickle.dumps(a) == pickle.dumps(b):
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def github_url(file):
+    rel_path = os.path.relpath(file, Path(solara.__file__).parent.parent)
+    github_url = solara.github_url + f"/blob/{solara.git_branch}/" + rel_path
+    return github_url
+
+
+def pycafe_url(*, path: Path, requirements: Optional[List[str]] = None):
+    json_object = {"code": path.read_text("utf8")}
+    if requirements:
+        json_object["requirements"] = "\n".join(requirements)
+    json_text = json.dumps(json_object)
+    # gzip -> base64
+    compressed_json_text = gzip.compress(json_text.encode("utf8"))
+    base64_text = base64.b64encode(compressed_json_text).decode("utf8")
+    query = urlencode({"c": base64_text})
+    base_url = "https://app.py.cafe"
+    return f"{base_url}/snippet/solara?{query}"
+
+
+def github_edit_url(file):
+    # e.g. https://github.com/widgetti/solara/edit/master/solara/__init__.py
+    rel_path = os.path.relpath(file, Path(solara.__file__).parent.parent)
+    github_url = solara.github_url + f"/edit/{solara.git_branch}/" + rel_path
+    return github_url
+
+
+def load_file_as_data_url(file_name, mime):
+    with open(file_name, "rb") as f:
+        data = f.read()
+    return f"data:{mime};base64," + base64.b64encode(data).decode("utf-8")
+
+
+def isinstanceof(object, spec: str):
+    """Check if object is instance of type '<modulename>:<classname>'
+
+    This can avoid a runtime dependency, since we do not need to import `modulename`.
+
+    >>> import numpy as np
+    >>> isinstanceof(np.arange(2), "numpy:ndarray")
+    True
+    """
+    module_name, classname = spec.split(":")
+    module = sys.modules.get(module_name)
+    if module:
+        cls = getattr(module, classname)
+        return isinstance(object, cls)
+    return False
+
+
+def numpy_to_image(data: "np.ndarray", format="png"):
+    import io
+
+    if data.ndim == 3:
+        try:
+            import PIL.Image
+        except ModuleNotFoundError:
+            raise ModuleNotFoundError("Pillow is required to convert numpy array to image, use pip install pillow to install it.")
+        if data.shape[2] == 3:
+            im = PIL.Image.fromarray(data[::], "RGB")
+        elif data.shape[2] == 4:
+            im = PIL.Image.fromarray(data[::], "RGBA")
+        else:
+            raise ValueError(f"Expected last dimension to have 3 or 4 dimensions, total shape we got was {data.shape}")
+        f = io.BytesIO()
+        im.save(f, format)
+        return f.getvalue()
+    else:
+        raise ValueError(f"Expected an image with 3 dimensions (height, width, channel), not {data.shape}")
+
+
+@contextlib.contextmanager
+def cwd(path):
+    cwd = os.getcwd()
+    try:
+        os.chdir(path)
+        yield
+    finally:
+        os.chdir(cwd)
+
+
+def numpy_equals(a, b):
+    import numpy as np
+
+    if a is b:
+        return True
+    if a is None or b is None:
+        return False
+    if np.all(a == b):
+        return True
+    return False
+
+
+def _combine_classes(class_list: List[str]) -> str:
+    return " ".join(class_list)
+
+
+def _flatten_style(style: Union[str, Dict, None] = None) -> str:
+    if style is None:
+        return ""
+    elif isinstance(style, str):
+        return style
+    elif isinstance(style, dict):
+        return ";".join(f"{k}:{v}" for k, v in style.items()) + ";"
+    else:
+        raise ValueError(f"Expected style to be a string or dict, got {type(style)}")
+
+
+def import_item(name: str):
+    """Import an object by name like solara.cache.LRU"""
+    parts = name.rsplit(".", 2)
+    if len(parts) == 1:
+        return __import__(name)
+    else:
+        module = __import__(".".join(parts[:-1]), fromlist=[parts[-1]])
+        return getattr(module, parts[-1])
+
+
+def get_solara_home() -> Path:
+    """Get solara home directory, defaults to ~/.solara.
+
+    The $SOLARA_HOME environment variable can be set to override this default.
+
+    If $SOLARA_HOME is not defined and ~ cannot be expanded, the current working directory + ".solara" is used.
+    """
+    os_home = None
+    try:
+        os_home = Path.home()
+    except Exception:
+        pass
+    if "SOLARA_HOME" in os.environ:
+        return Path(os.environ["SOLARA_HOME"])
+    elif os_home:
+        return os_home / ".solara"
+    else:
+        return Path(os.getcwd()) / ".solara"
+
+
+def parse_size(size: str) -> int:
+    """Given a human readable size, return the number of bytes.
+
+    Supports GB, MB, KB, and bytes. E.g. 10GB, 500MB, 1KB, 1000
+
+    Commas and _ are ignored, e.g. 1,000,000 is the same as 1000000.
+    """
+    size = size.replace(",", "").replace("_", "").upper()
+    if size.endswith("GB"):
+        return int(float(size[:-2]) * 1024 * 1024 * 1024)
+    elif size.endswith("MB"):
+        return int(float(size[:-2]) * 1024 * 1024)
+    elif size.endswith("KB"):
+        return int(float(size[:-2]) * 1024)
+    elif size.endswith("B"):
+        return int(float(size[:-1]))
+    else:
+        return int(size)
+
+
+def nested_get(object, dotted_name: str, default=None):
+    names = dotted_name.split(".")
+    for name in names:
+        if isinstance(object, abc.Mapping):
+            if name == names[-1]:
+                object = object.get(name, default)
+            else:
+                object = object.get(name)
+        else:
+            if name == names[-1]:
+                object = getattr(object, name, default)
+            else:
+                object = getattr(object, name)
+    return object
+
+
+# inherit from BaseException so less change of being caught
+# in an except
+class CancelledError(BaseException):
+    pass
+
+
+# not available in python 3.6
+class nullcontext(contextlib.AbstractContextManager):
+    def __init__(self, enter_result=None):
+        self.enter_result = enter_result
+
+    def __enter__(self):
+        return self.enter_result
+
+    def __exit__(self, *excinfo):
+        pass
+
+
+@contextlib.contextmanager
+def cancel_guard(cancelled: threading.Event):
+    def tracefunc(frame, event, arg):
+        # this gets called at least for every line executed
+        if cancelled.is_set():
+            rc = reacton.core.get_render_context(required=False)
+            # we do not want to cancel the rendering cycle
+            if rc is None or not rc._is_rendering:
+                # this will bubble up
+                raise CancelledError()
+        if prev and SOLARA_ALLOW_OTHER_TRACER:
+            prev(frame, event, arg)
+        # keep tracing:
+        return tracefunc
+
+    # see https://docs.python.org/3/library/sys.html#sys.settrace
+    # it is for the calling thread only
+    # not every Python implementation has it
+    prev = None
+    if hasattr(sys, "gettrace"):
+        prev = sys.gettrace()
+    if hasattr(sys, "settrace"):
+        sys.settrace(tracefunc)
+    try:
+        yield
+    finally:
+        if hasattr(sys, "settrace"):
+            sys.settrace(prev)
+
+
+def parse_timedelta(size: str) -> float:
+    """Turn a human readable time delta into seconds.
+    Supports days(d), hours (h), minutes (m) and seconds (s).
+    If not unit is specified, seconds is assumed.
+    >>> parse_timedelta("1d")
+    86400
+    >>> parse_timedelta("1h")
+    3600
+    >>> parse_timedelta("30m")
+    1800
+    >>> parse_timedelta("10s")
+    10
+    >>> parse_timedelta("10")
+    10
+    """
+    if size.endswith("d"):
+        return float(size[:-1]) * 24 * 60 * 60
+    elif size.endswith("h"):
+        return float(size[:-1]) * 60 * 60
+    elif size.endswith("m"):
+        return float(size[:-1]) * 60
+    elif size.endswith("s"):
+        return float(size[:-1])
+    else:
+        return float(size)
+
+
+def get_file_hash(path: Path, algorithm="md5") -> Tuple[bytes, str]:
+    """Compute the hash of a file. Note that we also return the file content as bytes."""
+    data = path.read_bytes()
+    if sys.version_info[:2] < (3, 9):
+        # usedforsecurity is only available in Python 3.9+
+        h = hashlib.new(algorithm)
+    else:
+        h = hashlib.new(algorithm, usedforsecurity=False)  # type: ignore
+    h.update(data)
+    return data, h.hexdigest()
+
+
+def is_running_in_colab():
+    try:
+        import google.colab  # noqa
+
+        return True
+    except ImportError:
+        return False
+
+
+def is_running_in_vscode():
+    return "VSCODE_PID" in os.environ or "VSCODE_CWD" in os.environ
+
+
+def is_running_in_voila():
+    return os.environ.get("SERVER_SOFTWARE", "").startswith("voila")
+
+
+def once(f):
+    called = False
+    return_value = None
+
+    @functools.wraps(f)
+    def wrapper():
+        nonlocal called
+        nonlocal return_value
+        if called:
+            return return_value
+        called = True
+        return_value = f()
+        return return_value
+
+    return wrapper

solara/validate_hooks.py

@@ -0,0 +1,258 @@
+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
+        id_ = None
+        if isinstance(func, ast.Name):
+            id_ = func.id
+        elif isinstance(func, ast.Attribute):
+            id_ = func.attr
+        if id_ is not None and 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
+"""