reflex 0.5.0.post1__py3-none-any.whl → 0.5.1a1__py3-none-any.whl

reflex/testing.py

@@ -26,6 +26,7 @@ from typing import (
     AsyncIterator,
     Callable,
     Coroutine,
+    List,
     Optional,
     Type,
     TypeVar,
@@ -513,12 +514,19 @@ class AppHarness:
             raise TimeoutError("Backend is not listening.")
         return backend.servers[0].sockets[0]
 
-    def frontend(self, driver_clz: Optional[Type["WebDriver"]] = None) -> "WebDriver":
+    def frontend(
+        self,
+        driver_clz: Optional[Type["WebDriver"]] = None,
+        driver_kwargs: dict[str, Any] | None = None,
+        driver_option_args: List[str] | None = None,
+    ) -> "WebDriver":
         """Get a selenium webdriver instance pointed at the app.
 
         Args:
             driver_clz: webdriver.Chrome (default), webdriver.Firefox, webdriver.Safari,
                 webdriver.Edge, etc
+            driver_kwargs: additional keyword arguments to pass to the webdriver constructor
+            driver_option_args: additional arguments for the webdriver options
 
         Returns:
             Instance of the given webdriver navigated to the frontend url of the app.
@@ -541,19 +549,30 @@ class AppHarness:
             requested_driver = os.environ.get("APP_HARNESS_DRIVER", "Chrome")
             driver_clz = getattr(webdriver, requested_driver)
             options = getattr(webdriver, f"{requested_driver}Options")()
-        if driver_clz is webdriver.Chrome and want_headless:
+        if driver_clz is webdriver.Chrome:
             options = webdriver.ChromeOptions()
-            options.add_argument("--headless=new")
-        elif driver_clz is webdriver.Firefox and want_headless:
+            options.add_argument("--class=AppHarness")
+            if want_headless:
+                options.add_argument("--headless=new")
+        elif driver_clz is webdriver.Firefox:
             options = webdriver.FirefoxOptions()
-            options.add_argument("-headless")
-        elif driver_clz is webdriver.Edge and want_headless:
+            if want_headless:
+                options.add_argument("-headless")
+        elif driver_clz is webdriver.Edge:
             options = webdriver.EdgeOptions()
-            options.add_argument("headless")
-        if options and (args := os.environ.get("APP_HARNESS_DRIVER_ARGS")):
+            if want_headless:
+                options.add_argument("headless")
+        if options is None:
+            raise RuntimeError(f"Could not determine options for {driver_clz}")
+        if args := os.environ.get("APP_HARNESS_DRIVER_ARGS"):
             for arg in args.split(","):
                 options.add_argument(arg)
-        driver = driver_clz(options=options)  # type: ignore
+        if driver_option_args is not None:
+            for arg in driver_option_args:
+                options.add_argument(arg)
+        if driver_kwargs is None:
+            driver_kwargs = {}
+        driver = driver_clz(options=options, **driver_kwargs)  # type: ignore
         driver.get(self.frontend_url)
         self._frontends.append(driver)
         return driver

reflex/utils/exceptions.py

@@ -1,21 +1,77 @@
 """Custom Exceptions."""
 
 
-class InvalidStylePropError(TypeError):
-    """Custom Type Error when style props have invalid values."""
+class ReflexError(Exception):
+    """Base exception for all Reflex exceptions."""
+
+
+class ReflexRuntimeError(ReflexError, RuntimeError):
+    """Custom RuntimeError for Reflex."""
+
+
+class UploadTypeError(ReflexError, TypeError):
+    """Custom TypeError for upload related errors."""
+
+
+class EnvVarValueError(ReflexError, ValueError):
+    """Custom ValueError raised when unable to convert env var to expected type."""
+
+
+class ComponentTypeError(ReflexError, TypeError):
+    """Custom TypeError for component related errors."""
+
+
+class EventHandlerTypeError(ReflexError, TypeError):
+    """Custom TypeError for event handler related errors."""
+
+
+class EventHandlerValueError(ReflexError, ValueError):
+    """Custom ValueError for event handler related errors."""
+
+
+class StateValueError(ReflexError, ValueError):
+    """Custom ValueError for state related errors."""
+
 
-    pass
+class VarNameError(ReflexError, NameError):
+    """Custom NameError for when a state var has been shadowed by a substate var."""
 
 
-class ImmutableStateError(AttributeError):
+class VarTypeError(ReflexError, TypeError):
+    """Custom TypeError for var related errors."""
+
+
+class VarValueError(ReflexError, ValueError):
+    """Custom ValueError for var related errors."""
+
+
+class VarAttributeError(ReflexError, AttributeError):
+    """Custom AttributeError for var related errors."""
+
+
+class UploadValueError(ReflexError, ValueError):
+    """Custom ValueError for upload related errors."""
+
+
+class RouteValueError(ReflexError, ValueError):
+    """Custom ValueError for route related errors."""
+
+
+class VarOperationTypeError(ReflexError, TypeError):
+    """Custom TypeError for when unsupported operations are performed on vars."""
+
+
+class InvalidStylePropError(ReflexError, TypeError):
+    """Custom Type Error when style props have invalid values."""
+
+
+class ImmutableStateError(ReflexError):
     """Raised when a background task attempts to modify state outside of context."""
 
 
-class LockExpiredError(Exception):
+class LockExpiredError(ReflexError):
     """Raised when the state lock expires while an event is being processed."""
 
 
-class MatchTypeError(TypeError):
+class MatchTypeError(ReflexError, TypeError):
     """Raised when the return types of match cases are different."""
-
-    pass

reflex/utils/format.py

@@ -6,7 +6,7 @@ import inspect
 import json
 import os
 import re
-from typing import TYPE_CHECKING, Any, List, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Union
 
 from reflex import constants
 from reflex.utils import exceptions, serializers, types
@@ -15,7 +15,7 @@ from reflex.vars import BaseVar, Var
 
 if TYPE_CHECKING:
     from reflex.components.component import ComponentStyle
-    from reflex.event import EventChain, EventHandler, EventSpec
+    from reflex.event import ArgsSpec, EventChain, EventHandler, EventSpec
 
 WRAP_MAP = {
     "{": "}",
@@ -590,6 +590,77 @@ def format_event_chain(
     )
 
 
+def format_queue_events(
+    events: EventSpec
+    | EventHandler
+    | Callable
+    | List[EventSpec | EventHandler | Callable]
+    | None = None,
+    args_spec: Optional[ArgsSpec] = None,
+) -> Var[EventChain]:
+    """Format a list of event handler / event spec as a javascript callback.
+
+    The resulting code can be passed to interfaces that expect a callback
+    function and when triggered it will directly call queueEvents.
+
+    It is intended to be executed in the rx.call_script context, where some
+    existing API needs a callback to trigger a backend event handler.
+
+    Args:
+        events: The events to queue.
+        args_spec: The argument spec for the callback.
+
+    Returns:
+        The compiled javascript callback to queue the given events on the frontend.
+    """
+    from reflex.event import (
+        EventChain,
+        EventHandler,
+        EventSpec,
+        call_event_fn,
+        call_event_handler,
+    )
+
+    if not events:
+        return Var.create_safe(
+            "() => null", _var_is_string=False, _var_is_local=False
+        ).to(EventChain)
+
+    # If no spec is provided, the function will take no arguments.
+    def _default_args_spec():
+        return []
+
+    # Construct the arguments that the function accepts.
+    sig = inspect.signature(args_spec or _default_args_spec)  # type: ignore
+    if sig.parameters:
+        arg_def = ",".join(f"_{p}" for p in sig.parameters)
+        arg_def = f"({arg_def})"
+    else:
+        arg_def = "()"
+
+    payloads = []
+    if not isinstance(events, list):
+        events = [events]
+
+    # Process each event/spec/lambda (similar to Component._create_event_chain).
+    for spec in events:
+        specs: list[EventSpec] = []
+        if isinstance(spec, (EventHandler, EventSpec)):
+            specs = [call_event_handler(spec, args_spec or _default_args_spec)]
+        elif isinstance(spec, type(lambda: None)):
+            specs = call_event_fn(spec, args_spec or _default_args_spec)
+        payloads.extend(format_event(s) for s in specs)
+
+    # Return the final code snippet, expecting queueEvents, processEvent, and socket to be in scope.
+    # Typically this snippet will _only_ run from within an rx.call_script eval context.
+    return Var.create_safe(
+        f"{arg_def} => {{queueEvents([{','.join(payloads)}], {constants.CompileVars.SOCKET}); "
+        f"processEvent({constants.CompileVars.SOCKET})}}",
+        _var_is_string=False,
+        _var_is_local=False,
+    ).to(EventChain)
+
+
 def format_query_params(router_data: dict[str, Any]) -> dict[str, str]:
     """Convert back query params name to python-friendly case.
 

reflex/utils/prerequisites.py

@@ -233,28 +233,35 @@ def get_app(reload: bool = False) -> ModuleType:
 
     Raises:
         RuntimeError: If the app name is not set in the config.
+        exceptions.ReflexError: Reflex specific errors.
     """
-    os.environ[constants.RELOAD_CONFIG] = str(reload)
-    config = get_config()
-    if not config.app_name:
-        raise RuntimeError(
-            "Cannot get the app module because `app_name` is not set in rxconfig! "
-            "If this error occurs in a reflex test case, ensure that `get_app` is mocked."
-        )
-    module = config.module
-    sys.path.insert(0, os.getcwd())
-    app = __import__(module, fromlist=(constants.CompileVars.APP,))
+    from reflex.utils import exceptions, telemetry
+
+    try:
+        os.environ[constants.RELOAD_CONFIG] = str(reload)
+        config = get_config()
+        if not config.app_name:
+            raise RuntimeError(
+                "Cannot get the app module because `app_name` is not set in rxconfig! "
+                "If this error occurs in a reflex test case, ensure that `get_app` is mocked."
+            )
+        module = config.module
+        sys.path.insert(0, os.getcwd())
+        app = __import__(module, fromlist=(constants.CompileVars.APP,))
 
-    if reload:
-        from reflex.state import reload_state_module
+        if reload:
+            from reflex.state import reload_state_module
 
-        # Reset rx.State subclasses to avoid conflict when reloading.
-        reload_state_module(module=module)
+            # Reset rx.State subclasses to avoid conflict when reloading.
+            reload_state_module(module=module)
 
-        # Reload the app module.
-        importlib.reload(app)
+            # Reload the app module.
+            importlib.reload(app)
 
-    return app
+        return app
+    except exceptions.ReflexError as ex:
+        telemetry.send("error", context="frontend", detail=str(ex))
+        raise
 
 
 def get_compiled_app(reload: bool = False, export: bool = False) -> ModuleType:
@@ -406,7 +413,7 @@ def initialize_gitignore(
     # Write files to the .gitignore file.
     with open(gitignore_file, "w", newline="\n") as f:
         console.debug(f"Creating {gitignore_file}")
-        f.write(f"{(path_ops.join(sorted(files_to_ignore))).lstrip()}")
+        f.write(f"{(path_ops.join(sorted(files_to_ignore))).lstrip()}\n")
 
 
 def initialize_requirements_txt():
@@ -879,6 +886,7 @@ def install_frontend_packages(packages: set[str], config: Config):
     processes.run_process_with_fallback(
         [get_install_package_manager(), "install"],  # type: ignore
         fallback=fallback_command,
+        analytics_enabled=True,
         show_status_message="Installing base frontend packages",
         cwd=constants.Dirs.WEB,
         shell=constants.IS_WINDOWS,
@@ -894,6 +902,7 @@ def install_frontend_packages(packages: set[str], config: Config):
                 *((config.tailwind or {}).get("plugins", [])),
             ],
             fallback=fallback_command,
+            analytics_enabled=True,
             show_status_message="Installing tailwind",
             cwd=constants.Dirs.WEB,
             shell=constants.IS_WINDOWS,
@@ -904,6 +913,7 @@ def install_frontend_packages(packages: set[str], config: Config):
         processes.run_process_with_fallback(
             [get_install_package_manager(), "add", *packages],
             fallback=fallback_command,
+            analytics_enabled=True,
             show_status_message="Installing frontend packages from config and components",
             cwd=constants.Dirs.WEB,
             shell=constants.IS_WINDOWS,

reflex/utils/processes.py

@@ -211,6 +211,7 @@ def stream_logs(
     process: subprocess.Popen,
     progress=None,
     suppress_errors: bool = False,
+    analytics_enabled: bool = False,
 ):
     """Stream the logs for a process.
 
@@ -219,6 +220,7 @@ def stream_logs(
         process: The process.
         progress: The ongoing progress bar if one is being used.
         suppress_errors: If True, do not exit if errors are encountered (for fallback).
+        analytics_enabled: Whether analytics are enabled for this command.
 
     Yields:
         The lines of the process output.
@@ -226,6 +228,8 @@ def stream_logs(
     Raises:
         Exit: If the process failed.
     """
+    from reflex.utils import telemetry
+
     # Store the tail of the logs.
     logs = collections.deque(maxlen=512)
     with process:
@@ -246,6 +250,8 @@ def stream_logs(
         console.error(f"{message} failed with exit code {process.returncode}")
         for line in logs:
             console.error(line, end="")
+        if analytics_enabled:
+            telemetry.send("error", context=message)
         console.error("Run with [bold]--loglevel debug [/bold] for the full log.")
         raise typer.Exit(1)
 
@@ -261,16 +267,27 @@ def show_logs(message: str, process: subprocess.Popen):
         pass
 
 
-def show_status(message: str, process: subprocess.Popen, suppress_errors: bool = False):
+def show_status(
+    message: str,
+    process: subprocess.Popen,
+    suppress_errors: bool = False,
+    analytics_enabled: bool = False,
+):
     """Show the status of a process.
 
     Args:
         message: The initial message to display.
         process: The process.
         suppress_errors: If True, do not exit if errors are encountered (for fallback).
+        analytics_enabled: Whether analytics are enabled for this command.
     """
     with console.status(message) as status:
-        for line in stream_logs(message, process, suppress_errors=suppress_errors):
+        for line in stream_logs(
+            message,
+            process,
+            suppress_errors=suppress_errors,
+            analytics_enabled=analytics_enabled,
+        ):
             status.update(f"{message} {line}")
 
 
@@ -319,19 +336,31 @@ def get_command_with_loglevel(command: list[str]) -> list[str]:
     return command
 
 
-def run_process_with_fallback(args, *, show_status_message, fallback=None, **kwargs):
+def run_process_with_fallback(
+    args,
+    *,
+    show_status_message,
+    fallback=None,
+    analytics_enabled: bool = False,
+    **kwargs,
+):
     """Run subprocess and retry using fallback command if initial command fails.
 
     Args:
         args: A string, or a sequence of program arguments.
         show_status_message: The status message to be displayed in the console.
         fallback: The fallback command to run.
+        analytics_enabled: Whether analytics are enabled for this command.
         kwargs: Kwargs to pass to new_process function.
     """
     process = new_process(get_command_with_loglevel(args), **kwargs)
     if fallback is None:
         # No fallback given, or this _is_ the fallback command.
-        show_status(show_status_message, process)
+        show_status(
+            show_status_message,
+            process,
+            analytics_enabled=analytics_enabled,
+        )
     else:
         # Suppress errors for initial command, because we will try to fallback
         show_status(show_status_message, process, suppress_errors=True)
@@ -345,6 +374,7 @@ def run_process_with_fallback(args, *, show_status_message, fallback=None, **kwa
                 fallback_args,
                 show_status_message=show_status_message,
                 fallback=None,
+                analytics_enabled=analytics_enabled,
                 **kwargs,
             )
 

reflex/utils/telemetry.py

@@ -126,6 +126,10 @@ def _prepare_event(event: str, **kwargs) -> dict:
 
     cpuinfo = get_cpu_info()
 
+    additional_keys = ["template", "context", "detail"]
+    additional_fields = {
+        key: value for key in additional_keys if (value := kwargs.get(key)) is not None
+    }
     return {
         "api_key": "phc_JoMo0fOyi0GQAooY3UyO9k0hebGkMyFJrrCw1Gt5SGb",
         "event": event,
@@ -139,11 +143,7 @@ def _prepare_event(event: str, **kwargs) -> dict:
             "cpu_count": get_cpu_count(),
             "memory": get_memory(),
             "cpu_info": dict(cpuinfo) if cpuinfo else {},
-            **(
-                {"template": template}
-                if (template := kwargs.get("template")) is not None
-                else {}
-            ),
+            **additional_fields,
         },
         "timestamp": stamp,
     }

reflex/utils/types.py

@@ -44,6 +44,22 @@ from reflex import constants
 from reflex.base import Base
 from reflex.utils import console, serializers
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+
+    def override(func: Callable) -> Callable:
+        """Fallback for @override decorator.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            The unmodified function.
+        """
+        return func
+
+
 # Potential GenericAlias types for isinstance checks.
 GenericAliasTypes = [_GenericAlias]