solara-ui 1.45.0__py3-none-any.whl

solara/lifecycle.py

@@ -0,0 +1,46 @@
+from types import FrameType, ModuleType
+from typing import Callable, List, NamedTuple, Optional
+from pathlib import Path
+import inspect
+
+
+class _on_kernel_callback_entry(NamedTuple):
+    callback: Callable[[], Optional[Callable[[], None]]]
+    callpoint: Optional[Path]
+    module: Optional[ModuleType]
+    cleanup: Callable[[], None]
+
+
+_on_kernel_start_callbacks: List[_on_kernel_callback_entry] = []
+
+
+def _find_root_module_frame() -> Optional[FrameType]:
+    # basically the module where the call stack origined from
+    current_frame = inspect.currentframe()
+    root_module_frame = None
+
+    while current_frame is not None:
+        if current_frame.f_code.co_name == "<module>":
+            root_module_frame = current_frame
+            break
+        current_frame = current_frame.f_back
+
+    return root_module_frame
+
+
+def on_kernel_start(f: Callable[[], Optional[Callable[[], None]]]) -> Callable[[], None]:
+    root = _find_root_module_frame()
+    path: Optional[Path] = None
+    module: Optional[ModuleType] = None
+    if root is not None:
+        path_str = inspect.getsourcefile(root)
+        module = inspect.getmodule(root)
+        if path_str is not None:
+            path = Path(path_str)
+
+    def cleanup():
+        return _on_kernel_start_callbacks.remove(kce)
+
+    kce = _on_kernel_callback_entry(f, path, module, cleanup)
+    _on_kernel_start_callbacks.append(kce)
+    return cleanup

solara/minisettings.py

@@ -0,0 +1,141 @@
+import inspect
+import os
+from pathlib import Path
+from typing import Any, Optional, List, Type
+
+# similar API to pydantic/pydantic-settings but we prefer not to have a dependency on pydantic
+# since we cannot be compatible with pydantic1 and 2
+# NOTE: not a public api
+
+
+def _get_type(annotation):
+    check_optional_types = [str, int, float, bool, dict, list]
+    for check_type in check_optional_types:
+        if annotation == Optional[check_type]:
+            return check_type
+    if hasattr(annotation, "__origin__"):
+        if annotation.__origin__ is dict:
+            return dict
+    return annotation
+
+
+class _Field:
+    def __init__(self, default=None, env=None, title=None, default_factory=None, gt=None, alias=None) -> None:
+        self.default = default
+        self.env = env
+        self.fullenv = None
+        self.title = title
+        self.annotation = None
+        self.default_factory = default_factory
+        self.gt = gt
+        self.alias = alias
+        self.field_info = self
+        self.extra = {"env_names": [env] if env else []}
+
+    def __set_name__(self, owner, name):
+        prefix = "SOLARA_"
+        config = getattr(owner, "Config")
+        if config:
+            prefix = getattr(config, "env_prefix", prefix).upper()
+            if hasattr(config, "fields"):
+                fields = config.fields
+                if name in fields:
+                    self.alias = fields[name]
+        self.name = name
+        self.alias = self.alias or self.name
+        self.title = self.title or self.name
+        if self.env is None:
+            self.env = f"{prefix}{self.name.upper()}"
+        else:
+            self.env = self.env
+        self.annotation = owner.__annotations__.get(self.name)
+        assert self.annotation is not None, f"Field {self.name} must have a type annotation"
+        self.type_ = _get_type(self.annotation)
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        return instance._values[self.name]
+
+    def __set__(self, instance, value):
+        instance._values[self.name] = value
+
+
+def convert(annotation, value: str) -> Any:
+    check_sub_types: List[Type] = [str, int, float, bool, Path]
+    for sub_type in check_sub_types:
+        if annotation == Optional[sub_type]:
+            annotation = sub_type
+            return convert(annotation, value)
+    for sub_type in check_sub_types:
+        if annotation == List[sub_type]:  # type: ignore
+            annotation = sub_type
+            values = value.split(",")
+            return [convert(sub_type, k) for k in values]
+    if annotation is str:
+        return value
+    elif annotation is int:
+        return int(value)
+    elif annotation is float:
+        return float(value)
+    elif annotation is bool:
+        if value in ("True", "true", "1"):
+            return True
+        elif value in ("False", "false", "0"):
+            return False
+        else:
+            raise ValueError(f"Invalid boolean value {value}")
+    else:
+        # raise TypeError(f"Unsupported type {annotation}")
+        return annotation(value)
+
+
+def Field(*args, **kwargs) -> Any:
+    return _Field(*args, **kwargs)
+
+
+class BaseSettings:
+    __fields__: dict
+
+    def __init__(self, **kwargs) -> None:
+        cls = type(self)
+        self._values = {**kwargs}
+        keys = {k.upper() for k in os.environ.keys()}
+        for key, field in cls.__dict__.items():
+            if key in kwargs:
+                continue
+            if isinstance(field, _Field):
+                value = field.default
+                if field.default_factory:
+                    value = field.default_factory()
+
+                if field.env:
+                    env_key = field.env.upper()
+                    if env_key in keys:
+                        # do a case-insensitive lookup
+                        for env_var_cased in os.environ.keys():
+                            if env_key.upper() == env_var_cased.upper():
+                                value = convert(field.annotation, os.environ[env_var_cased])
+                self._values[key] = value
+
+    def __init_subclass__(cls) -> None:
+        cls.__fields__ = {}
+        for key, field in cls.__dict__.items():
+            if key.startswith("_"):
+                continue
+            if key == "Config":
+                continue
+            if not isinstance(field, _Field):
+                if inspect.isfunction(field):
+                    continue
+                field = Field(field)
+                setattr(cls, key, field)
+                field.__set_name__(cls, key)
+            cls.__fields__[key] = field
+
+    def dict(self, by_alias=True):
+        values = self._values.copy()
+        for key, value in values.items():
+            if isinstance(value, BaseSettings):
+                values[key] = value.dict(by_alias=by_alias)
+        return values

solara/reactive.py

@@ -0,0 +1,99 @@
+from typing import Any, Callable, TypeVar
+
+from solara.toestand import Reactive
+import solara.util
+
+__all__ = ["reactive", "Reactive"]
+
+T = TypeVar("T")
+
+
+def reactive(value: T, equals: Callable[[Any, Any], bool] = solara.util.equals_extra) -> Reactive[T]:
+    """Creates a new Reactive object with the given initial value.
+
+    Reactive objects are mostly used to manage global or application-wide state in
+    Solara web applications. They provide an easy-to-use mechanism for keeping
+    track of the changing state of data and for propagating those changes to
+    the appropriate UI components. For managing local or component-specific
+    state, consider using the [`solara.use_state()`](/documentation/api/hooks/use_state) function.
+
+
+    Reactive variables can be accessed using the `.value` attribute. To modify
+    the value, you can either set the `.value` property directly or use the
+    `.set()` method. While both approaches are equivalent, the `.set()` method
+    is particularly useful when you need to pass it as a callback function to
+    other components, such as a slider's `on_value` callback.
+
+    When a component uses a reactive variable, it
+    automatically listens for changes to the variable's value. If the value
+    changes, the component will automatically re-render to reflect the updated
+    state, without the need to explicitly subscribe to the variable.
+
+    Reactive objects in Solara are also context-aware, meaning that they can
+    maintain separate values for each browser tab or user session. This enables
+    each user to have their own independent state, allowing them to interact
+    with the web application without affecting the state of other users.
+
+    Args:
+        value (T): The initial value of the reactive variable.
+        equals: A function that returns True if two values are considered equal, and False otherwise.
+            The default function is `solara.util.equals`, which performs a deep comparison of the two values
+            and is more forgiving than the default `==` operator.
+            You can provide a custom function if you need to define a different notion of equality.
+
+
+    Returns:
+        Reactive[T]: A new Reactive object with the specified initial value.
+
+    Example:
+
+    ```python
+    >>> counter = solara.reactive(0)
+    >>> counter.value
+    0
+    >>> counter.set(1)
+    >>> counter.value
+    1
+    >>> counter.value += 1
+    >>> counter.value
+    2
+    ```
+
+
+    ## Solara example
+
+    Here's an example that demonstrates the use of reactive variables in Solara components:
+
+    ```solara
+    import solara
+
+    counter = solara.reactive(0)
+
+    def increment():
+        counter.value += 1
+
+
+    @solara.component
+    def CounterDisplay():
+        solara.Info(f"Counter: {counter.value}")
+
+
+    @solara.component
+    def IncrementButton():
+
+        solara.Button("Increment", on_click=increment)
+
+
+    @solara.component
+    def Page():
+        IncrementButton()
+        CounterDisplay()
+    ```
+
+    In this example, we create a reactive variable counter with an initial value of 0.
+    We define two components: `CounterDisplay` and `IncrementButton`. `CounterDisplay` renders the current value of counter,
+    while `IncrementButton` increments the value of counter when clicked.
+    Whenever the counter value changes, `CounterDisplay` automatically updates to display the new value.
+
+    """
+    return Reactive(value, equals=equals)

solara/routing.py

@@ -0,0 +1,268 @@
+import abc
+import logging
+from typing import Callable, List, Optional, Tuple, Union, cast
+
+import solara
+from solara import _using_solara_server
+
+logger = logging.getLogger("solara.router")
+
+
+class _LocationBase(abc.ABC):
+    @property
+    def pathname(self):
+        pass
+
+    @pathname.setter
+    # mypy does not accept this
+    # @abc.abstractmethod
+    def pathname(self):
+        pass
+
+
+class _Location(_LocationBase):
+    def __init__(self, pathname, setter: Callable[[str], None]) -> None:
+        self._pathname = pathname
+        self.setter = setter
+
+    @property
+    def pathname(self):
+        return self._pathname
+
+    @pathname.setter
+    def pathname(self, value):
+        # import pdb
+
+        # pdb.set_trace()
+        self._pathname = value
+        self.setter(self._pathname)
+
+
+class Router:
+    search: Optional[str]
+
+    def __init__(self, path: str, routes: List[solara.Route], set_path: Callable[[str], None] = None):
+        # see https://developer.mozilla.org/en-US/docs/Web/API/Location for anatomy/nomenclature
+        if "?" in path:
+            self.path, self.search = path.split("?", 1)
+        else:
+            self.path = path
+            self.search = None
+        del path
+        self.set_path = set_path
+        self.parts = (self.path or "").strip("/").split("/")
+        self.routes = routes
+        self.root_path = ""
+        if _using_solara_server():
+            import solara.server.settings
+
+            self.root_path = solara.server.settings.main.root_path or ""
+        # each route in this list corresponds to a part in self.parts
+        self.path_routes: List["solara.Route"] = []
+        self.path_routes_siblings: List[List["solara.Route"]] = []  # siblings including itself
+        # routes = routes.copy()
+        route = None
+        for part in self.parts:
+            for route in routes:
+                if (route.path == part) or (route.path == "/" and not part):
+                    self.path_routes.append(route)
+                    self.path_routes_siblings.append(routes)
+                    routes = route.children
+                    break
+        if len(self.parts) == len(self.path_routes):
+            # e.g. '/foo/bar' -> ['foo', 'bar'] and bar has a default route
+            # but if '' -> [''] we should not
+            route = self.path_routes[-1]
+            if route:
+                default_routes = [k for k in route.children if k.path == "/"]
+                if self.parts and self.parts[0] and default_routes:
+                    self.path_routes.append(default_routes[0])
+                    self.path_routes_siblings.append(route.children)
+
+        assert len(self.path_routes) == len(self.path_routes_siblings)
+        self.possible_match = (len(self.path_routes[-1].children) == 0) if self.path_routes else False
+
+    def push(self, path: str):
+        assert self.set_path is not None
+        self.set_path(path)
+
+
+router_context = solara.create_context(Router("", []))
+_location_context = solara.create_context(cast(_LocationBase, _Location("", lambda x: None)))
+
+route_level_context = solara.create_context(0)
+
+
+def use_route_level():
+    route_level = solara.use_context(route_level_context)
+    return route_level
+
+
+def use_router() -> Router:
+    """Returns the current router object.
+
+    See also [Understanding Routing](/documentation/advanced/understanding/routing).
+
+    `use_router` returns the current router object. This is useful to build custom routing.
+
+    the router object contains the following properties/methods:
+
+     * `path` - the current pathname (e.g. `/fruit/banana`)
+     * `parts` - the current pathname split into parts (e.g. `['fruit', 'banana']`)
+     * `search` - the query parameters string (e.g. `color=yellow`).
+     * `push(path: str)` - navigate to path (e.g. `router.push('/fruit/banana')`)
+
+    ## Typical usage:
+
+    ```python
+    import solara
+
+
+    @solara.component
+    def Page():
+        router = solara.use_router()
+
+        def redirect():
+            router.push(f"/documentation/api/routing/use_route")
+
+        solara.Button("Navigate using an event", on_click=redirect)
+    ```
+
+    """
+    return solara.use_context(router_context)
+
+
+def use_route(
+    level=0,
+    peek=False,
+) -> Tuple[Optional[solara.Route], List[solara.Route]]:
+    """Returns (if found) the current route that matches the pathname, or None
+
+    See also [Understanding Routing](/documentation/advanced/understanding/routing).
+
+    `use_route` returns (if found) the current route that matches the pathname, or None. It also returns all resolved routes of that level
+    (i.e. all siblings and itself). This return tuple is useful to build custom navigation (e.g. using tabs or buttons).
+
+
+    Routing starts with declaring a set of `routes` in your app (solara picks up the `routes` variable if it exists,
+    and it should be in the same namespace as `Page`).
+    In the demo below, we declared the following routes.
+
+    ```python
+    routes = [
+        solara.Route(path="/"),
+        solara.Route(
+            path="fruit",
+            component=Fruit,
+            children=[
+                solara.Route(path="/"),
+                solara.Route(path="kiwi"),
+                solara.Route(path="banana"),
+                solara.Route(path="apple"),
+            ],
+        ),
+    ]
+    ```
+
+    Note that all routes are relative, since a component does not know if it is embedded into a larger application, which may also do routing.
+    Therefore you should never use the `route.path` for navigation since the route object has no knowledge of the full url
+    (e.g. `/documentation/api/routing/use_route/fruit/banana`) but only knows its small piece of the pathname (e.g. `banana`)
+
+    Use [`resolve_path`](/documentation/api/routing/resolve_path) to request the full url for navigation,
+        or simply use the `Link` component that can do this for us.
+
+    If the current route has children, any child component that calls `use_route` will return the matched route and its siblings of our children.
+
+
+    ## Arguments
+
+    * `level`: the level of the route to return. 0 is the current route, -1 is the parent route, 1 the child route, etc.
+    * `peek`: if True, the route level is not incremented. This is useful to peek at the next route level without changing the current route level.
+    """
+
+    router = solara.use_context(router_context)
+    route_level = solara.use_context(route_level_context)
+    if not peek:
+        route_level_context.provide(route_level + 1)
+    route_level += level
+    if route_level < len(router.path_routes):
+        return router.path_routes[route_level], router.path_routes_siblings[route_level]
+    else:
+        return None, []
+
+
+def find_route(path: str) -> Optional[solara.Route]:
+    router = solara.get_context(router_context)
+    route_level = min(solara.get_context(route_level_context), len(router.path_routes_siblings) - 1)
+    for route in router.path_routes_siblings[route_level]:
+        if path.startswith(route.path) or (not path and route.path == "/"):
+            return route
+    return None
+
+
+def use_pathname():
+    location_proxy = solara.use_context(_location_context)
+
+    def setter(value):
+        location_proxy.pathname = value
+
+    return location_proxy.pathname, setter
+
+
+def resolve_path(path_or_route: Union[str, solara.Route], level=0) -> str:
+    """Resolve a relative path or a route to an absolute path.
+
+    If the path is a string and starts with a `/'`, it is returned as is.
+
+
+    ## Typical usage:
+
+    ```python
+    ...
+    route_current, routes_current_level = solara.routes()
+    # route_current.path == "banana"
+    path = solara.resolve_path(route_current)
+    # path == "/fruit/banana"
+    path_same = solara.resolve_path("banana")
+    # path_same == path == "/fruit/banana"
+    ...
+    ```
+
+    ## Arguments
+
+     * path_or_route: a path string or a [`solara.Route`](/documentation/api/routing/route) object to resolve.
+
+    ## See also
+
+     * [Multipage](/documentation/advanced/howto/multipage).
+     * [Understanding Routing](/documentation/advanced/understanding/routing).
+
+
+    """
+    router = solara.get_context(router_context)
+    if isinstance(path_or_route, str):
+        path = path_or_route
+        if path.startswith("/"):
+            return path
+        route_level = solara.get_context(route_level_context) + level
+        parts = [*router.parts[:route_level], path]
+        path = "/" + "/".join(parts)
+        if path.startswith("//"):
+            path = path[1:]
+        return path
+    elif isinstance(path_or_route, solara.Route):
+        route: solara.Route = path_or_route
+        path = _resolve_path("/", route, router.routes)
+        if path.startswith("//"):
+            path = path[1:]
+        return path
+
+
+def _resolve_path(prefix: str, findroute: solara.Route, routes: List[solara.Route]):
+    for route in routes:
+        path = (prefix + "/" + route.path) if route.path != "/" else prefix
+        if findroute is route:
+            return path
+        possible_path = _resolve_path(path, findroute=findroute, routes=route.children)
+        if possible_path is not None:
+            return possible_path

solara/scope/__init__.py

@@ -0,0 +1,88 @@
+import re
+import sys
+import threading
+from typing import MutableMapping
+
+from .types import ObservableMutableMapping
+
+
+def _in_solara_server():
+    return "solara.server" in sys.modules
+
+
+class ConnectionScope(ObservableMutableMapping):
+    def __init__(self, name="connection"):
+        super().__init__()
+        self._global_dict = {}
+        self.name = name
+        self.lock = threading.Lock()
+
+    def _get_dict(self) -> MutableMapping:
+        if _in_solara_server():
+            import solara.server.kernel_context
+
+            context = solara.server.kernel_context.get_current_context()
+            if self.name not in context.user_dicts:
+                with self.lock:
+                    if self.name not in context.user_dicts:
+                        context.user_dicts[self.name] = {}
+            return context.user_dicts[self.name]
+        else:
+            return self._global_dict
+
+
+class ObservableDict(ObservableMutableMapping):
+    def __init__(self):
+        super().__init__()
+        self._global_dict = {}
+
+    def _get_dict(self) -> MutableMapping:
+        return self._global_dict
+
+
+worker = ObservableDict()
+connection = ConnectionScope()
+
+
+def get_kernel_id(ipython_fallback=True) -> str:
+    """Returns the kernel id, a unique string for each virtual kernel.
+
+    See [Understanding solara server](/docs/understanding/solara-server) for understanding the concept of virtual kernels
+    and their lifetime.
+
+    This unique ID can be useful to to implement storing state, scoped to a kernel. See [the scope example](/examples/general/custom_storage) for an example.
+
+    If `ipython_fallback` is `True` (default), this function will also work in IPython notebooks, where it will return the IPython kernel id.
+
+    """
+    import solara.server.kernel_context
+
+    try:
+        context = solara.server.kernel_context.get_current_context()
+    except RuntimeError as e:
+        if not ipython_fallback:
+            raise
+        import IPython
+
+        ipython = IPython.get_ipython()
+        if not ipython or not hasattr(ipython, "kernel"):
+            raise RuntimeError("Not in a kernel") from e
+        kernel = ipython.kernel
+        regex = r"[\\/]kernel-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.json$"
+        connection_file = kernel.config["IPKernelApp"]["connection_file"]
+        return re.compile(regex).search(connection_file).group(1)  # type: ignore
+    return context.id
+
+
+def get_session_id() -> str:
+    """Returns the session id, which is stored using a browser cookie.
+
+    See [Understanding solara server](/docs/understanding/solara-server#session) for more information about the Solara sessions.
+
+    This unique ID can be useful to to implement storing state, scoped to a browser session. See [the scope example](/examples/general/custom_storage)
+    for an example.
+    """
+    import solara.server.kernel_context
+
+    context = solara.server.kernel_context.get_current_context()
+    return context.session_id

solara/scope/types.py

@@ -0,0 +1,55 @@
+import threading
+from abc import abstractmethod
+from typing import Any, Callable, Dict, List, MutableMapping
+from warnings import warn
+
+ObserverCallback = Callable[[Any, Any], None]
+
+
+class MutableMappingBase(MutableMapping):
+    @abstractmethod
+    def _get_dict(self) -> MutableMapping:
+        pass
+
+    def __delitem__(self, key) -> None:
+        self._get_dict().__delitem__(key)
+
+    def __getitem__(self, key):
+        return self._get_dict().__getitem__(key)
+
+    def __iter__(self):
+        return self._get_dict().__iter__()
+
+    def __len__(self):
+        return self._get_dict().__len__()
+
+    def __setitem__(self, key, value):
+        self._get_dict().__setitem__(key, value)
+
+
+class ObservableMutableMapping(MutableMappingBase):
+    # list of observers for each key
+    observers: Dict[Any, List[ObserverCallback]]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.observers = {}
+        self.lock = threading.Lock()
+
+    def subscribe_key(self, key, callback: ObserverCallback):
+        if key not in self.observers:
+            with self.lock:
+                if key not in self.observers:
+                    self.observers[key] = []
+        self.observers[key].append(callback)
+        if self.observers[key].count(callback) > 1:
+            warn("Callback already subscribed")
+
+        def unsubscribe():
+            self.observers[key].remove(callback)
+
+        return unsubscribe
+
+    def trigger_key(self, key):
+        for callback in self.observers[key]:
+            callback(key, self[key])