reflex 0.6.4a3__py3-none-any.whl → 0.6.5a1__py3-none-any.whl

reflex/reflex.py

@@ -11,6 +11,7 @@ import typer
 import typer.core
 from reflex_cli.deployments import deployments_cli
 from reflex_cli.utils import dependency
+from reflex_cli.v2.deployments import hosting_cli
 
 from reflex import constants
 from reflex.config import environment, get_config
@@ -160,7 +161,7 @@ def _run(
     console.set_log_level(loglevel)
 
     # Set env mode in the environment
-    os.environ[constants.ENV_MODE_ENV_VAR] = env.value
+    environment.REFLEX_ENV_MODE.set(env)
 
     # Show system info
     exec.output_system_info()
@@ -277,13 +278,13 @@ def run(
         False,
         "--frontend-only",
         help="Execute only frontend.",
-        envvar=constants.ENV_FRONTEND_ONLY_ENV_VAR,
+        envvar=environment.REFLEX_FRONTEND_ONLY.name,
     ),
     backend: bool = typer.Option(
         False,
         "--backend-only",
         help="Execute only backend.",
-        envvar=constants.ENV_BACKEND_ONLY_ENV_VAR,
+        envvar=environment.REFLEX_BACKEND_ONLY.name,
     ),
     frontend_port: str = typer.Option(
         config.frontend_port, help="Specify a different frontend port."
@@ -302,8 +303,8 @@ def run(
     if frontend and backend:
         console.error("Cannot use both --frontend-only and --backend-only options.")
         raise typer.Exit(1)
-    os.environ[constants.ENV_BACKEND_ONLY_ENV_VAR] = str(backend).lower()
-    os.environ[constants.ENV_FRONTEND_ONLY_ENV_VAR] = str(frontend).lower()
+    environment.REFLEX_BACKEND_ONLY.set(backend)
+    environment.REFLEX_FRONTEND_ONLY.set(frontend)
 
     _run(env, frontend, backend, frontend_port, backend_port, backend_host, loglevel)
 
@@ -363,7 +364,7 @@ def _login() -> str:
     access_token = hosting.authenticate_on_browser(invitation_code)
 
     if not access_token:
-        console.error(f"Unable to authenticate. Please try again or contact support.")
+        console.error("Unable to authenticate. Please try again or contact support.")
         raise typer.Exit(1)
 
     console.print("Successfully logged in.")
@@ -383,6 +384,14 @@ def login(
     _login()
 
 
+@cli.command()
+def loginv2(loglevel: constants.LogLevel = typer.Option(config.loglevel)):
+    """Authenicate with experimental Reflex hosting service."""
+    from reflex_cli.v2 import cli as hosting_cli
+
+    hosting_cli.login()
+
+
 @cli.command()
 def logout(
     loglevel: constants.LogLevel = typer.Option(
@@ -399,13 +408,29 @@ def logout(
     hosting.delete_token_from_config(include_invitation_code=True)
 
 
+@cli.command()
+def logoutv2(
+    loglevel: constants.LogLevel = typer.Option(
+        config.loglevel, help="The log level to use."
+    ),
+):
+    """Log out of access to Reflex hosting service."""
+    from reflex_cli.v2.utils import hosting
+
+    console.set_log_level(loglevel)
+
+    hosting.log_out_on_browser()
+    console.debug("Deleting access token from config locally")
+    hosting.delete_token_from_config(include_invitation_code=True)
+
+
 db_cli = typer.Typer()
 script_cli = typer.Typer()
 
 
 def _skip_compile():
     """Skip the compile step."""
-    os.environ[constants.SKIP_COMPILE_ENV_VAR] = "yes"
+    environment.REFLEX_SKIP_COMPILE.set(True)
 
 
 @db_cli.command(name="init")
@@ -420,7 +445,7 @@ def db_init():
         return
 
     # Check the alembic config.
-    if environment.ALEMBIC_CONFIG.exists():
+    if environment.ALEMBIC_CONFIG.get().exists():
         console.error(
             "Database is already initialized. Use "
             "[bold]reflex db makemigrations[/bold] to create schema change "
@@ -599,6 +624,110 @@ def deploy(
     )
 
 
+@cli.command()
+def deployv2(
+    app_name: str = typer.Option(
+        config.app_name,
+        "--app-name",
+        help="The name of the App to deploy under.",
+        hidden=True,
+    ),
+    regions: List[str] = typer.Option(
+        list(),
+        "-r",
+        "--region",
+        help="The regions to deploy to. For multiple envs, repeat this option, e.g. --region sjc --region iad",
+    ),
+    envs: List[str] = typer.Option(
+        list(),
+        "--env",
+        help="The environment variables to set: <key>=<value>. For multiple envs, repeat this option, e.g. --env k1=v2 --env k2=v2.",
+    ),
+    vmtype: Optional[str] = typer.Option(
+        None,
+        "--vmtype",
+        help="Vm type id. Run reflex apps vmtypes list to get options.",
+    ),
+    hostname: Optional[str] = typer.Option(
+        None,
+        "--hostname",
+        help="The hostname of the frontend.",
+        hidden=True,
+    ),
+    interactive: bool = typer.Option(
+        True,
+        help="Whether to list configuration options and ask for confirmation.",
+    ),
+    envfile: Optional[str] = typer.Option(
+        None,
+        "--envfile",
+        help="The path to an env file to use. Will override any envs set manually.",
+        hidden=True,
+    ),
+    loglevel: constants.LogLevel = typer.Option(
+        config.loglevel, help="The log level to use."
+    ),
+    project: Optional[str] = typer.Option(
+        None,
+        "--project",
+        help="project to deploy to",
+        hidden=True,
+    ),
+    token: Optional[str] = typer.Option(
+        None,
+        "--token",
+        help="token to use for auth",
+        hidden=True,
+    ),
+):
+    """Deploy the app to the Reflex hosting service."""
+    from reflex_cli.v2 import cli as hosting_cli
+    from reflex_cli.v2.utils import dependency
+
+    from reflex.utils import export as export_utils
+    from reflex.utils import prerequisites
+
+    # Set the log level.
+    console.set_log_level(loglevel)
+
+    # Only check requirements if interactive.
+    # There is user interaction for requirements update.
+    if interactive:
+        dependency.check_requirements()
+
+    # Check if we are set up.
+    if prerequisites.needs_reinit(frontend=True):
+        _init(name=config.app_name, loglevel=loglevel)
+    prerequisites.check_latest_package_version(constants.ReflexHostingCLI.MODULE_NAME)
+
+    hosting_cli.deploy(
+        app_name=app_name,
+        export_fn=lambda zip_dest_dir,
+        api_url,
+        deploy_url,
+        frontend,
+        backend,
+        zipping: export_utils.export(
+            zip_dest_dir=zip_dest_dir,
+            api_url=api_url,
+            deploy_url=deploy_url,
+            frontend=frontend,
+            backend=backend,
+            zipping=zipping,
+            loglevel=loglevel.subprocess_level(),
+        ),
+        regions=regions,
+        envs=envs,
+        vmtype=vmtype,
+        envfile=envfile,
+        hostname=hostname,
+        interactive=interactive,
+        loglevel=loglevel.subprocess_level(),
+        token=token,
+        project=project,
+    )
+
+
 cli.add_typer(db_cli, name="db", help="Subcommands for managing the database schema.")
 cli.add_typer(script_cli, name="script", help="Subcommands running helper scripts.")
 cli.add_typer(
@@ -606,6 +735,11 @@ cli.add_typer(
     name="deployments",
     help="Subcommands for managing the Deployments.",
 )
+cli.add_typer(
+    hosting_cli,
+    name="apps",
+    help="Subcommands for managing the Deployments.",
+)
 cli.add_typer(
     custom_components_cli,
     name="component",

reflex/state.py

@@ -8,8 +8,10 @@ import copy
 import dataclasses
 import functools
 import inspect
+import json
 import pickle
 import sys
+import typing
 import uuid
 from abc import ABC, abstractmethod
 from collections import defaultdict
@@ -43,9 +45,7 @@ from typing_extensions import Self
 from reflex import event
 from reflex.config import get_config
 from reflex.istate.data import RouterData
-from reflex.istate.storage import (
-    ClientStorageBase,
-)
+from reflex.istate.storage import ClientStorageBase
 from reflex.vars.base import (
     ComputedVar,
     DynamicRouteVar,
@@ -91,7 +91,13 @@ from reflex.utils.exceptions import (
 )
 from reflex.utils.exec import is_testing_env
 from reflex.utils.serializers import serializer
-from reflex.utils.types import get_origin, override
+from reflex.utils.types import (
+    _isinstance,
+    get_origin,
+    is_union,
+    override,
+    value_inside_optional,
+)
 from reflex.vars import VarData
 
 if TYPE_CHECKING:
@@ -104,6 +110,17 @@ var = computed_var
 
 # If the state is this large, it's considered a performance issue.
 TOO_LARGE_SERIALIZED_STATE = 100 * 1024  # 100kb
+# Only warn about each state class size once.
+_WARNED_ABOUT_STATE_SIZE: Set[str] = set()
+
+# Errors caught during pickling of state
+HANDLED_PICKLE_ERRORS = (
+    pickle.PicklingError,
+    AttributeError,
+    IndexError,
+    TypeError,
+    ValueError,
+)
 
 
 def _no_chain_background_task(
@@ -344,7 +361,6 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
 
     def __init__(
         self,
-        *args,
         parent_state: BaseState | None = None,
         init_substates: bool = True,
         _reflex_internal_init: bool = False,
@@ -355,11 +371,10 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         DO NOT INSTANTIATE STATE CLASSES DIRECTLY! Use StateManager.get_state() instead.
 
         Args:
-            *args: The args to pass to the Pydantic init method.
             parent_state: The parent state.
             init_substates: Whether to initialize the substates in this instance.
             _reflex_internal_init: A flag to indicate that the state is being initialized by the framework.
-            **kwargs: The kwargs to pass to the Pydantic init method.
+            **kwargs: The kwargs to set as attributes on the state.
 
         Raises:
             ReflexRuntimeError: If the state is instantiated directly by end user.
@@ -372,7 +387,9 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
                 "See https://reflex.dev/docs/state/ for further information."
             )
         kwargs["parent_state"] = parent_state
-        super().__init__(*args, **kwargs)
+        super().__init__()
+        for name, value in kwargs.items():
+            setattr(self, name, value)
 
         # Setup the substates (for memory state manager only).
         if init_substates:
@@ -636,7 +653,7 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         def computed_var_func(state: Self):
             result = f(state)
 
-            if not isinstance(result, of_type):
+            if not _isinstance(result, of_type):
                 console.warn(
                     f"Inline ComputedVar {f} expected type {of_type}, got {type(result)}. "
                     "You can specify expected type with `of_type` argument."
@@ -1026,9 +1043,9 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         Args:
             prop: The var to create a setter for.
         """
-        setter_name = prop.get_setter_name(include_state=False)
+        setter_name = prop._get_setter_name(include_state=False)
         if setter_name not in cls.__dict__:
-            event_handler = cls._create_event_handler(prop.get_setter())
+            event_handler = cls._create_event_handler(prop._get_setter())
             cls.event_handlers[setter_name] = event_handler
             setattr(cls, setter_name, event_handler)
 
@@ -1042,7 +1059,7 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         # Get the pydantic field for the var.
         field = cls.get_fields()[prop._var_field_name]
         if field.required:
-            default_value = prop.get_default_value()
+            default_value = prop._get_default_value()
             if default_value is not None:
                 field.required = False
                 field.default = default_value
@@ -1069,7 +1086,7 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
             return getattr(cls, name)
         except AttributeError:
             try:
-                return Var("", _var_type=annotation_value).get_default_value()
+                return Var("", _var_type=annotation_value)._get_default_value()
             except TypeError:
                 pass
         return None
@@ -1274,6 +1291,22 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
                 f"All state variables must be declared before they can be set."
             )
 
+        fields = self.get_fields()
+
+        if name in fields:
+            field = fields[name]
+            field_type = field.outer_type_
+            if field.allow_none:
+                field_type = Union[field_type, None]
+            if not _isinstance(value, field_type):
+                console.deprecate(
+                    "mismatched-type-assignment",
+                    f"Tried to assign value {value} of type {type(value)} to field {type(self).__name__}.{name} of type {field_type}."
+                    " This might lead to unexpected behavior.",
+                    "0.6.5",
+                    "0.7.0",
+                )
+
         # Set the attribute.
         super().__setattr__(name, value)
 
@@ -1687,6 +1720,35 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         # Get the function to process the event.
         fn = functools.partial(handler.fn, state)
 
+        try:
+            type_hints = typing.get_type_hints(handler.fn)
+        except Exception:
+            type_hints = {}
+
+        for arg, value in list(payload.items()):
+            hinted_args = type_hints.get(arg, Any)
+            if hinted_args is Any:
+                continue
+            if is_union(hinted_args):
+                if value is None:
+                    continue
+                hinted_args = value_inside_optional(hinted_args)
+            if (
+                isinstance(value, dict)
+                and inspect.isclass(hinted_args)
+                and (
+                    dataclasses.is_dataclass(hinted_args)
+                    or issubclass(hinted_args, Base)
+                )
+            ):
+                payload[arg] = hinted_args(**value)
+            if isinstance(value, list) and (hinted_args is set or hinted_args is Set):
+                payload[arg] = set(value)
+            if isinstance(value, list) and (
+                hinted_args is tuple or hinted_args is Tuple
+            ):
+                payload[arg] = tuple(value)
+
         # Wrap the function in a try/except block.
         try:
             # Handle async functions.
@@ -2024,6 +2086,27 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
             state["__dict__"].pop(inherited_var_name, None)
         return state
 
+    def _warn_if_too_large(
+        self,
+        pickle_state_size: int,
+    ):
+        """Print a warning when the state is too large.
+
+        Args:
+            pickle_state_size: The size of the pickled state.
+        """
+        state_full_name = self.get_full_name()
+        if (
+            state_full_name not in _WARNED_ABOUT_STATE_SIZE
+            and pickle_state_size > TOO_LARGE_SERIALIZED_STATE
+            and self.substates
+        ):
+            console.warn(
+                f"State {state_full_name} serializes to {pickle_state_size} bytes "
+                "which may present performance issues. Consider reducing the size of this state."
+            )
+            _WARNED_ABOUT_STATE_SIZE.add(state_full_name)
+
     @classmethod
     @functools.lru_cache()
     def _to_schema(cls) -> str:
@@ -2062,8 +2145,10 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
             The serialized state.
         """
         try:
-            return pickle.dumps((self._to_schema(), self))
-        except (pickle.PicklingError, AttributeError) as og_pickle_error:
+            pickle_state = pickle.dumps((self._to_schema(), self))
+            self._warn_if_too_large(len(pickle_state))
+            return pickle_state
+        except HANDLED_PICKLE_ERRORS as og_pickle_error:
             error = (
                 f"Failed to serialize state {self.get_full_name()} due to unpicklable object. "
                 "This state will not be persisted. "
@@ -2077,7 +2162,7 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
                     f"Pickle error: {og_pickle_error}. "
                     "Consider `pip install 'dill>=0.3.8'` for more exotic serialization support."
                 )
-            except (pickle.PicklingError, TypeError, ValueError) as ex:
+            except HANDLED_PICKLE_ERRORS as ex:
                 error += f"Dill was also unable to pickle the state: {ex}"
         console.warn(error)
         return b""
@@ -2346,7 +2431,7 @@ class StateProxy(wrapt.ObjectProxy):
         class State(rx.State):
             counter: int = 0
 
-            @rx.background
+            @rx.event(background=True)
             async def bg_increment(self):
                 await asyncio.sleep(1)
                 async with self:
@@ -3053,9 +3138,6 @@ class StateManagerRedis(StateManager):
         b"evicted",
     }
 
-    # Only warn about each state class size once.
-    _warned_about_state_size: ClassVar[Set[str]] = set()
-
     async def _get_parent_state(
         self, token: str, state: BaseState | None = None
     ) -> BaseState | None:
@@ -3199,29 +3281,6 @@ class StateManagerRedis(StateManager):
             return state._get_root_state()
         return state
 
-    def _warn_if_too_large(
-        self,
-        state: BaseState,
-        pickle_state_size: int,
-    ):
-        """Print a warning when the state is too large.
-
-        Args:
-            state: The state to check.
-            pickle_state_size: The size of the pickled state.
-        """
-        state_full_name = state.get_full_name()
-        if (
-            state_full_name not in self._warned_about_state_size
-            and pickle_state_size > TOO_LARGE_SERIALIZED_STATE
-            and state.substates
-        ):
-            console.warn(
-                f"State {state_full_name} serializes to {pickle_state_size} bytes "
-                "which may present performance issues. Consider reducing the size of this state."
-            )
-            self._warned_about_state_size.add(state_full_name)
-
     @override
     async def set_state(
         self,
@@ -3248,7 +3307,7 @@ class StateManagerRedis(StateManager):
             raise LockExpiredError(
                 f"Lock expired for token {token} while processing. Consider increasing "
                 f"`app.state_manager.lock_expiration` (currently {self.lock_expiration}) "
-                "or use `@rx.background` decorator for long-running tasks."
+                "or use `@rx.event(background=True)` decorator for long-running tasks."
             )
         client_token, substate_name = _split_substate_key(token)
         # If the substate name on the token doesn't match the instance name, it cannot have a parent.
@@ -3272,7 +3331,6 @@ class StateManagerRedis(StateManager):
         # Persist only the given state (parents or substates are excluded by BaseState.__getstate__).
         if state._get_was_touched():
             pickle_state = state._serialize()
-            self._warn_if_too_large(state, len(pickle_state))
             if pickle_state:
                 await self.redis.set(
                     _substate_key(client_token, state),
@@ -3353,7 +3411,7 @@ class StateManagerRedis(StateManager):
             )
         except ResponseError:
             # Some redis servers only allow out-of-band configuration, so ignore errors here.
-            if not environment.REFLEX_IGNORE_REDIS_CONFIG_ERROR:
+            if not environment.REFLEX_IGNORE_REDIS_CONFIG_ERROR.get():
                 raise
         async with self.redis.pubsub() as pubsub:
             await pubsub.psubscribe(lock_key_channel)
@@ -3693,6 +3751,29 @@ def serialize_mutable_proxy(mp: MutableProxy):
     return mp.__wrapped__
 
 
+_orig_json_JSONEncoder_default = json.JSONEncoder.default
+
+
+def _json_JSONEncoder_default_wrapper(self: json.JSONEncoder, o: Any) -> Any:
+    """Wrap JSONEncoder.default to handle MutableProxy objects.
+
+    Args:
+        self: the JSONEncoder instance.
+        o: the object to serialize.
+
+    Returns:
+        A JSON-able object.
+    """
+    try:
+        return o.__wrapped__
+    except AttributeError:
+        pass
+    return _orig_json_JSONEncoder_default(self, o)
+
+
+json.JSONEncoder.default = _json_JSONEncoder_default_wrapper
+
+
 class ImmutableMutableProxy(MutableProxy):
     """A proxy for a mutable object that tracks changes.
 

reflex/testing.py

@@ -43,6 +43,7 @@ import reflex.utils.exec
 import reflex.utils.format
 import reflex.utils.prerequisites
 import reflex.utils.processes
+from reflex.config import environment
 from reflex.state import (
     BaseState,
     StateManager,
@@ -117,7 +118,7 @@ class AppHarness:
 
     app_name: str
     app_source: Optional[
-        types.FunctionType | types.ModuleType | str | functools.partial[Any]
+        Callable[[], None] | types.ModuleType | str | functools.partial[Any]
     ]
     app_path: pathlib.Path
     app_module_path: pathlib.Path
@@ -137,7 +138,7 @@ class AppHarness:
         cls,
         root: pathlib.Path,
         app_source: Optional[
-            types.FunctionType | types.ModuleType | str | functools.partial[Any]
+            Callable[[], None] | types.ModuleType | str | functools.partial[Any]
         ] = None,
         app_name: Optional[str] = None,
     ) -> "AppHarness":
@@ -250,6 +251,7 @@ class AppHarness:
 
     def _initialize_app(self):
         # disable telemetry reporting for tests
+
         os.environ["TELEMETRY_ENABLED"] = "false"
         self.app_path.mkdir(parents=True, exist_ok=True)
         if self.app_source is not None:
@@ -615,10 +617,10 @@ class AppHarness:
         if self.frontend_url is None:
             raise RuntimeError("Frontend is not running.")
         want_headless = False
-        if os.environ.get("APP_HARNESS_HEADLESS"):
+        if environment.APP_HARNESS_HEADLESS.get():
             want_headless = True
         if driver_clz is None:
-            requested_driver = os.environ.get("APP_HARNESS_DRIVER", "Chrome")
+            requested_driver = environment.APP_HARNESS_DRIVER.get()
             driver_clz = getattr(webdriver, requested_driver)
             if driver_options is None:
                 driver_options = getattr(webdriver, f"{requested_driver}Options")()
@@ -640,7 +642,7 @@ class AppHarness:
                 driver_options.add_argument("headless")
         if driver_options is None:
             raise RuntimeError(f"Could not determine options for {driver_clz}")
-        if args := os.environ.get("APP_HARNESS_DRIVER_ARGS"):
+        if args := environment.APP_HARNESS_DRIVER_ARGS.get():
             for arg in args.split(","):
                 driver_options.add_argument(arg)
         if driver_option_args is not None:
@@ -944,7 +946,7 @@ class AppHarnessProd(AppHarness):
     def _start_backend(self):
         if self.app_instance is None:
             raise RuntimeError("App was not initialized.")
-        os.environ[reflex.constants.SKIP_COMPILE_ENV_VAR] = "yes"
+        environment.REFLEX_SKIP_COMPILE.set(True)
         self.backend = uvicorn.Server(
             uvicorn.Config(
                 app=self.app_instance,
@@ -961,7 +963,7 @@ class AppHarnessProd(AppHarness):
         try:
             return super()._poll_for_servers(timeout)
         finally:
-            os.environ.pop(reflex.constants.SKIP_COMPILE_ENV_VAR, None)
+            environment.REFLEX_SKIP_COMPILE.set(None)
 
     def stop(self):
         """Stop the frontend python webserver."""

reflex/utils/console.py

@@ -191,7 +191,6 @@ def ask(
 def progress():
     """Create a new progress bar.
 
-
     Returns:
         A new progress bar.
     """

reflex/utils/exceptions.py

@@ -1,5 +1,7 @@
 """Custom Exceptions."""
 
+from typing import NoReturn
+
 
 class ReflexError(Exception):
     """Base exception for all Reflex exceptions."""
@@ -89,12 +91,12 @@ class MatchTypeError(ReflexError, TypeError):
     """Raised when the return types of match cases are different."""
 
 
-class EventHandlerArgMismatch(ReflexError, TypeError):
-    """Raised when the number of args accepted by an EventHandler is differs from that provided by the event trigger."""
+class EventHandlerArgTypeMismatch(ReflexError, TypeError):
+    """Raised when the annotations of args accepted by an EventHandler differs from the spec of the event trigger."""
 
 
 class EventFnArgMismatch(ReflexError, TypeError):
-    """Raised when the number of args accepted by a lambda differs from that provided by the event trigger."""
+    """Raised when the number of args required by an event handler is more than provided by the event trigger."""
 
 
 class DynamicRouteArgShadowsStateVar(ReflexError, NameError):
@@ -143,3 +145,29 @@ class EnvironmentVarValueError(ReflexError, ValueError):
 
 class DynamicComponentInvalidSignature(ReflexError, TypeError):
     """Raised when a dynamic component has an invalid signature."""
+
+
+class InvalidPropValueError(ReflexError):
+    """Raised when a prop value is invalid."""
+
+
+class SystemPackageMissingError(ReflexError):
+    """Raised when a system package is missing."""
+
+
+def raise_system_package_missing_error(package: str) -> NoReturn:
+    """Raise a SystemPackageMissingError.
+
+    Args:
+        package: The name of the missing system package.
+
+    Raises:
+        SystemPackageMissingError: The raised exception.
+    """
+    from reflex.constants import IS_MACOS
+
+    raise SystemPackageMissingError(
+        f"System package '{package}' is missing."
+        " Please install it through your system package manager."
+        + (f" You can do so by running 'brew install {package}'." if IS_MACOS else "")
+    )