Move to rx.asset, retain old API in rx._x.asset

reflex/__init__.py

@@ -264,6 +264,7 @@ _MAPPING: dict = {
     "experimental": ["_x"],
     "admin": ["AdminDash"],
     "app": ["App", "UploadFile"],
+    "assets": ["asset"],
     "base": ["Base"],
     "components.component": [
         "Component",

reflex/__init__.pyi

@@ -19,6 +19,7 @@ from . import vars as vars
 from .admin import AdminDash as AdminDash
 from .app import App as App
 from .app import UploadFile as UploadFile
+from .assets import asset as asset
 from .base import Base as Base
 from .components import el as el
 from .components import lucide as lucide

reflex/assets.py

@@ -0,0 +1,95 @@
+"""Helper functions for adding assets to the app."""
+
+import inspect
+from pathlib import Path
+from typing import Optional
+
+from reflex import constants
+from reflex.utils.exec import is_backend_only
+
+
+def asset(
+    path: str,
+    shared: bool = False,
+    subfolder: Optional[str] = None,
+    _stack_level: int = 1,
+) -> str:
+    """Add an asset to the app, either shared as a symlink or local.
+
+    Shared/External/Library assets:
+        Place the file next to your including python file.
+        Links the file to the app's external assets directory.
+
+    Example:
+    ```python
+    # my_custom_javascript.js is a shared asset located next to the including python file.
+    rx.script(src=rx.asset(path="my_custom_javascript.js", shared=True))
+    rx.image(src=rx.asset(path="test_image.png", shared=True, subfolder="subfolder"))
+    ```
+
+    Local/Internal assets:
+        Place the file in the app's assets/ directory.
+
+    Example:
+    ```python
+    # local_image.png is an asset located in the app's assets/ directory. It cannot be shared when developing a library.
+    rx.image(src=rx.asset(path="local_image.png"))
+    ```
+
+    Args:
+        path: The relative path of the asset.
+        subfolder: The directory to place the shared asset in.
+        shared: Whether to expose the asset to other apps.
+        _stack_level: The stack level to determine the calling file, defaults to
+            the immediate caller 1. When using rx.asset via a helper function,
+            increase this number for each helper function in the stack.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If subfolder is provided for local assets.
+
+    Returns:
+        The relative URL to the asset.
+    """
+    assets = constants.Dirs.APP_ASSETS
+    backend_only = is_backend_only()
+
+    # Local asset handling
+    if not shared:
+        cwd = Path.cwd()
+        src_file_local = cwd / assets / path
+        if subfolder is not None:
+            raise ValueError("Subfolder is not supported for local assets.")
+        if not backend_only and not src_file_local.exists():
+            raise FileNotFoundError(f"File not found: {src_file_local}")
+        return f"/{path}"
+
+    # Shared asset handling
+    # Determine the file by which the asset is exposed.
+    frame = inspect.stack()[_stack_level]
+    calling_file = frame.filename
+    module = inspect.getmodule(frame[0])
+    assert module is not None
+
+    external = constants.Dirs.EXTERNAL_APP_ASSETS
+    src_file_shared = Path(calling_file).parent / path
+    if not src_file_shared.exists():
+        raise FileNotFoundError(f"File not found: {src_file_shared}")
+
+    caller_module_path = module.__name__.replace(".", "/")
+    subfolder = f"{caller_module_path}/{subfolder}" if subfolder else caller_module_path
+
+    # Symlink the asset to the app's external assets directory if running frontend.
+    if not backend_only:
+        # Create the asset folder in the currently compiling app.
+        asset_folder = Path.cwd() / assets / external / subfolder
+        asset_folder.mkdir(parents=True, exist_ok=True)
+
+        dst_file = asset_folder / path
+
+        if not dst_file.exists() and (
+            not dst_file.is_symlink() or dst_file.resolve() != src_file_shared.resolve()
+        ):
+            dst_file.symlink_to(src_file_shared)
+
+    return f"/{external}/{subfolder}/{path}"

reflex/experimental/assets.py

@@ -1,90 +1,37 @@
 """Helper functions for adding assets to the app."""
 
-import inspect
-from pathlib import Path
 from typing import Optional
 
-from reflex import constants
+from reflex import assets
-from reflex.utils.exec import is_backend_only
+from reflex.utils import console
 
 
-def asset(
+def asset(relative_filename: str, subfolder: Optional[str] = None) -> str:
-    path: str,
+    """DEPRECATED: use `rx.asset` with `shared=True` instead.
-    shared: bool = False,
-    subfolder: Optional[str] = None,
-) -> str:
-    """Add an asset to the app, either shared as a symlink or local.
 
-    Shared/External/Library assets:
+    Add an asset to the app.
     Place the file next to your including python file.
-    Links the file to the app's external assets directory.
+    Copies the file to the app's external assets directory.
 
     Example:
     ```python
-    # my_custom_javascript.js is a shared asset located next to the including python file.
+    rx.script(src=rx._x.asset("my_custom_javascript.js"))
-    rx.script(src=rx._x.asset(path="my_custom_javascript.js", shared=True))
+    rx.image(src=rx._x.asset("test_image.png","subfolder"))
-    rx.image(src=rx._x.asset(path="test_image.png", shared=True, subfolder="subfolder"))
-    ```
-
-    Local/Internal assets:
-    Place the file in the app's assets/ directory.
-
-    Example:
-    ```python
-    # local_image.png is an asset located in the app's assets/ directory. It cannot be shared when developing a library.
-    rx.image(src=rx._x.asset(path="local_image.png"))
     ```
 
     Args:
-        path: The relative path of the asset.
+        relative_filename: The relative filename of the asset.
-        subfolder: The directory to place the shared asset in.
+        subfolder: The directory to place the asset in.
-        shared: Whether to expose the asset to other apps.
-
-    Raises:
-        FileNotFoundError: If the file does not exist.
-        ValueError: If subfolder is provided for local assets.
 
     Returns:
-        The relative URL to the asset.
+        The relative URL to the copied asset.
     """
-    assets = constants.Dirs.APP_ASSETS
+    console.deprecate(
-    backend_only = is_backend_only()
+        feature_name="rx._x.asset",
-
+        reason="Use `rx.asset` with `shared=True` instead of `rx._x.asset`.",
-    # Local asset handling
+        deprecation_version="0.6.6",
-    if not shared:
+        removal_version="0.7.0",
-        cwd = Path.cwd()
+    )
-        src_file_local = cwd / assets / path
+    return assets.asset(
-        if subfolder is not None:
+        relative_filename, shared=True, subfolder=subfolder, _stack_level=2
-            raise ValueError("Subfolder is not supported for local assets.")
+    )
-        if not backend_only and not src_file_local.exists():
-            raise FileNotFoundError(f"File not found: {src_file_local}")
-        return f"/{path}"
-
-    # Shared asset handling
-    # Determine the file by which the asset is exposed.
-    calling_file = inspect.stack()[1].filename
-    module = inspect.getmodule(inspect.stack()[1][0])
-    assert module is not None
-
-    external = constants.Dirs.EXTERNAL_APP_ASSETS
-    src_file_shared = Path(calling_file).parent / path
-    if not src_file_shared.exists():
-        raise FileNotFoundError(f"File not found: {src_file_shared}")
-
-    caller_module_path = module.__name__.replace(".", "/")
-    subfolder = f"{caller_module_path}/{subfolder}" if subfolder else caller_module_path
-
-    # Symlink the asset to the app's external assets directory if running frontend.
-    if not backend_only:
-        # Create the asset folder in the currently compiling app.
-        asset_folder = Path.cwd() / assets / external / subfolder
-        asset_folder.mkdir(parents=True, exist_ok=True)
-
-        dst_file = asset_folder / path
-
-        if not dst_file.exists() and (
-            not dst_file.is_symlink() or dst_file.resolve() != src_file_shared.resolve()
-        ):
-            dst_file.symlink_to(src_file_shared)
-
-    return f"/{external}/{subfolder}/{path}"

tests/units/assets/test_assets.py

@@ -11,7 +11,7 @@ import reflex.constants as constants
 def test_shared_asset() -> None:
     """Test shared assets."""
     # The asset function copies a file to the app's external assets directory.
-    asset = rx._x.asset(path="custom_script.js", shared=True, subfolder="subfolder")
+    asset = rx.asset(path="custom_script.js", shared=True, subfolder="subfolder")
     assert asset == "/external/test_assets/subfolder/custom_script.js"
     result_file = Path(
         Path.cwd(), "assets/external/test_assets/subfolder/custom_script.js"
@@ -19,10 +19,10 @@ def test_shared_asset() -> None:
     assert result_file.exists()
 
     # Running a second time should not raise an error.
-    asset = rx._x.asset(path="custom_script.js", shared=True, subfolder="subfolder")
+    asset = rx.asset(path="custom_script.js", shared=True, subfolder="subfolder")
 
     # Test the asset function without a subfolder.
-    asset = rx._x.asset(path="custom_script.js", shared=True)
+    asset = rx.asset(path="custom_script.js", shared=True)
     assert asset == "/external/test_assets/custom_script.js"
     result_file = Path(Path.cwd(), "assets/external/test_assets/custom_script.js")
     assert result_file.exists()
@@ -31,12 +31,25 @@ def test_shared_asset() -> None:
     shutil.rmtree(Path.cwd() / "assets/external")
 
     with pytest.raises(FileNotFoundError):
-        asset = rx._x.asset("non_existent_file.js")
+        asset = rx.asset("non_existent_file.js")
 
     # Nothing is done to assets when file does not exist.
     assert not Path(Path.cwd() / "assets/external").exists()
 
 
+def test_deprecated_x_asset(capsys) -> None:
+    """Test that the deprecated asset function raises a warning.
+
+    Args:
+        capsys: Pytest fixture that captures stdout and stderr.
+    """
+    assert rx.asset("custom_script.js", shared=True) == rx._x.asset("custom_script.js")
+    assert (
+        "DeprecationWarning: rx._x.asset has been deprecated in version 0.6.6"
+        in capsys.readouterr().out
+    )
+
+
 @pytest.mark.parametrize(
     "path,shared",
     [
@@ -52,7 +65,7 @@ def test_invalid_assets(path: str, shared: bool) -> None:
         shared: Whether the asset should be shared.
     """
     with pytest.raises(FileNotFoundError):
-        _ = rx._x.asset(path, shared=shared)
+        _ = rx.asset(path, shared=shared)
 
 
 @pytest.fixture
@@ -77,5 +90,5 @@ def test_local_asset(custom_script_in_asset_dir: Path) -> None:
         custom_script_in_asset_dir: Fixture that creates a custom_script.js file in the app's assets directory.
 
     """
-    asset = rx._x.asset("custom_script.js", shared=False)
+    asset = rx.asset("custom_script.js", shared=False)
     assert asset == "/custom_script.js"