reactpy 2.0.0b4__py3-none-any.whl → 2.0.0b6__py3-none-any.whl

reactpy/reactjs/__init__.py

@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any, overload
+
+from reactpy.reactjs.module import (
+    file_to_module,
+    import_reactjs,
+    module_to_vdom,
+    string_to_module,
+    url_to_module,
+)
+from reactpy.reactjs.types import (
+    NAME_SOURCE,
+    URL_SOURCE,
+)
+from reactpy.types import JavaScriptModule, VdomConstructor
+
+__all__ = [
+    "NAME_SOURCE",
+    "URL_SOURCE",
+    "component_from_file",
+    "component_from_npm",
+    "component_from_string",
+    "component_from_url",
+    "import_reactjs",
+]
+
+_URL_JS_MODULE_CACHE: dict[str, JavaScriptModule] = {}
+_FILE_JS_MODULE_CACHE: dict[str, JavaScriptModule] = {}
+_STRING_JS_MODULE_CACHE: dict[str, JavaScriptModule] = {}
+
+
+@overload
+def component_from_url(
+    url: str,
+    import_names: str,
+    resolve_imports: bool = ...,
+    resolve_imports_depth: int = ...,
+    fallback: Any | None = ...,
+    unmount_before_update: bool = ...,
+    allow_children: bool = ...,
+) -> VdomConstructor: ...
+
+
+@overload
+def component_from_url(
+    url: str,
+    import_names: list[str] | tuple[str, ...],
+    resolve_imports: bool = ...,
+    resolve_imports_depth: int = ...,
+    fallback: Any | None = ...,
+    unmount_before_update: bool = ...,
+    allow_children: bool = ...,
+) -> list[VdomConstructor]: ...
+
+
+def component_from_url(
+    url: str,
+    import_names: str | list[str] | tuple[str, ...],
+    resolve_imports: bool = False,
+    resolve_imports_depth: int = 5,
+    fallback: Any | None = None,
+    unmount_before_update: bool = False,
+    allow_children: bool = True,
+) -> VdomConstructor | list[VdomConstructor]:
+    """Import a component from a URL.
+
+    Parameters:
+        url:
+            The URL to import the component from.
+        import_names:
+            One or more component names to import. If given as a string, a single component
+            will be returned. If a list is given, then a list of components will be
+            returned.
+        resolve_imports:
+            Whether to try and find all the named imports of this module.
+        resolve_imports_depth:
+            How deeply to search for those imports.
+        fallback:
+            What to temporarily display while the module is being loaded.
+        unmount_before_update:
+            Cause the component to be unmounted before each update. This option should
+            only be used if the imported package fails to re-render when props change.
+            Using this option has negative performance consequences since all DOM
+            elements must be changed on each render. See :issue:`461` for more info.
+        allow_children:
+            Whether or not these components can have children.
+    """
+    key = f"{url}{resolve_imports}{resolve_imports_depth}{unmount_before_update}"
+    if key in _URL_JS_MODULE_CACHE:
+        module = _URL_JS_MODULE_CACHE[key]
+    else:
+        module = url_to_module(
+            url,
+            fallback=fallback,
+            resolve_imports=resolve_imports,
+            resolve_imports_depth=resolve_imports_depth,
+            unmount_before_update=unmount_before_update,
+        )
+        _URL_JS_MODULE_CACHE[key] = module
+    return module_to_vdom(module, import_names, fallback, allow_children)
+
+
+@overload
+def component_from_npm(
+    package: str,
+    import_names: str,
+    resolve_imports: bool = ...,
+    resolve_imports_depth: int = ...,
+    version: str = "latest",
+    cdn: str = "https://esm.sh",
+    fallback: Any | None = ...,
+    unmount_before_update: bool = ...,
+    allow_children: bool = ...,
+) -> VdomConstructor: ...
+
+
+@overload
+def component_from_npm(
+    package: str,
+    import_names: list[str] | tuple[str, ...],
+    resolve_imports: bool = ...,
+    resolve_imports_depth: int = ...,
+    version: str = "latest",
+    cdn: str = "https://esm.sh",
+    fallback: Any | None = ...,
+    unmount_before_update: bool = ...,
+    allow_children: bool = ...,
+) -> list[VdomConstructor]: ...
+
+
+def component_from_npm(
+    package: str,
+    import_names: str | list[str] | tuple[str, ...],
+    resolve_imports: bool = False,
+    resolve_imports_depth: int = 5,
+    version: str = "latest",
+    cdn: str = "https://esm.sh",
+    fallback: Any | None = None,
+    unmount_before_update: bool = False,
+    allow_children: bool = True,
+) -> VdomConstructor | list[VdomConstructor]:
+    """Import a component from an NPM package.
+
+    Is is mandatory to load `reactpy.reactjs.import_reactjs()` on your page before using this
+    function. It is recommended to put this within your HTML <head> content.
+
+    Parameters:
+        package:
+            The name of the NPM package.
+        import_names:
+            One or more component names to import. If given as a string, a single component
+            will be returned. If a list is given, then a list of components will be
+            returned.
+        resolve_imports:
+            Whether to try and find all the named imports of this module.
+        resolve_imports_depth:
+            How deeply to search for those imports.
+        version:
+            The version of the package to use. Defaults to "latest".
+        cdn:
+            The CDN to use. Defaults to "https://esm.sh".
+        fallback:
+            What to temporarily display while the module is being loaded.
+        unmount_before_update:
+            Cause the component to be unmounted before each update. This option should
+            only be used if the imported package fails to re-render when props change.
+            Using this option has negative performance consequences since all DOM
+            elements must be changed on each render. See :issue:`461` for more info.
+        allow_children:
+            Whether or not these components can have children.
+    """
+    url = f"{cdn}/{package}@{version}"
+
+    if "esm.sh" in cdn:
+        if "?" in url:
+            url += "&external=react,react-dom"
+        else:
+            url += "?external=react,react-dom"
+
+    return component_from_url(
+        url,
+        import_names,
+        fallback=fallback,
+        resolve_imports=resolve_imports,
+        resolve_imports_depth=resolve_imports_depth,
+        unmount_before_update=unmount_before_update,
+        allow_children=allow_children,
+    )
+
+
+@overload
+def component_from_file(
+    file: str | Path,
+    import_names: str,
+    resolve_imports: bool = ...,
+    resolve_imports_depth: int = ...,
+    name: str = "",
+    fallback: Any | None = ...,
+    unmount_before_update: bool = ...,
+    symlink: bool = ...,
+    allow_children: bool = ...,
+) -> VdomConstructor: ...
+
+
+@overload
+def component_from_file(
+    file: str | Path,
+    import_names: list[str] | tuple[str, ...],
+    resolve_imports: bool = ...,
+    resolve_imports_depth: int = ...,
+    name: str = "",
+    fallback: Any | None = ...,
+    unmount_before_update: bool = ...,
+    symlink: bool = ...,
+    allow_children: bool = ...,
+) -> list[VdomConstructor]: ...
+
+
+def component_from_file(
+    file: str | Path,
+    import_names: str | list[str] | tuple[str, ...],
+    resolve_imports: bool = False,
+    resolve_imports_depth: int = 5,
+    name: str = "",
+    fallback: Any | None = None,
+    unmount_before_update: bool = False,
+    symlink: bool = False,
+    allow_children: bool = True,
+) -> VdomConstructor | list[VdomConstructor]:
+    """Import a component from a file.
+
+    Parameters:
+        file:
+            The file from which the content of the web module will be created.
+        import_names:
+            One or more component names to import. If given as a string, a single component
+            will be returned. If a list is given, then a list of components will be
+            returned.
+        resolve_imports:
+            Whether to try and find all the named imports of this module.
+        resolve_imports_depth:
+            How deeply to search for those imports.
+        name:
+            The human-readable name of the ReactJS package
+        fallback:
+            What to temporarily display while the module is being loaded.
+        unmount_before_update:
+            Cause the component to be unmounted before each update. This option should
+            only be used if the imported package fails to re-render when props change.
+            Using this option has negative performance consequences since all DOM
+            elements must be changed on each render. See :issue:`461` for more info.
+        symlink:
+            Whether the web module should be saved as a symlink to the given ``file``.
+        allow_children:
+            Whether or not these components can have children.
+    """
+    name = name or hashlib.sha256(str(file).encode()).hexdigest()[:10]
+    key = f"{name}{resolve_imports}{resolve_imports_depth}{unmount_before_update}"
+    if key in _FILE_JS_MODULE_CACHE:
+        module = _FILE_JS_MODULE_CACHE[key]
+    else:
+        module = file_to_module(
+            name,
+            file,
+            fallback=fallback,
+            resolve_imports=resolve_imports,
+            resolve_imports_depth=resolve_imports_depth,
+            unmount_before_update=unmount_before_update,
+            symlink=symlink,
+        )
+        _FILE_JS_MODULE_CACHE[key] = module
+    return module_to_vdom(module, import_names, fallback, allow_children)
+
+
+@overload
+def component_from_string(
+    content: str,
+    import_names: str,
+    resolve_imports: bool = ...,
+    resolve_imports_depth: int = ...,
+    name: str = "",
+    fallback: Any | None = ...,
+    unmount_before_update: bool = ...,
+    allow_children: bool = ...,
+) -> VdomConstructor: ...
+
+
+@overload
+def component_from_string(
+    content: str,
+    import_names: list[str] | tuple[str, ...],
+    resolve_imports: bool = ...,
+    resolve_imports_depth: int = ...,
+    name: str = "",
+    fallback: Any | None = ...,
+    unmount_before_update: bool = ...,
+    allow_children: bool = ...,
+) -> list[VdomConstructor]: ...
+
+
+def component_from_string(
+    content: str,
+    import_names: str | list[str] | tuple[str, ...],
+    resolve_imports: bool = False,
+    resolve_imports_depth: int = 5,
+    name: str = "",
+    fallback: Any | None = None,
+    unmount_before_update: bool = False,
+    allow_children: bool = True,
+) -> VdomConstructor | list[VdomConstructor]:
+    """Import a component from a string.
+
+    Parameters:
+        content:
+            The contents of the web module
+        import_names:
+            One or more component names to import. If given as a string, a single component
+            will be returned. If a list is given, then a list of components will be
+            returned.
+        resolve_imports:
+            Whether to try and find all the named imports of this module.
+        resolve_imports_depth:
+            How deeply to search for those imports.
+        name:
+            The human-readable name of the ReactJS package
+        fallback:
+            What to temporarily display while the module is being loaded.
+        unmount_before_update:
+            Cause the component to be unmounted before each update. This option should
+            only be used if the imported package fails to re-render when props change.
+            Using this option has negative performance consequences since all DOM
+            elements must be changed on each render. See :issue:`461` for more info.
+        allow_children:
+            Whether or not these components can have children.
+    """
+    name = name or hashlib.sha256(content.encode()).hexdigest()[:10]
+    key = f"{name}{resolve_imports}{resolve_imports_depth}{unmount_before_update}"
+    if key in _STRING_JS_MODULE_CACHE:
+        module = _STRING_JS_MODULE_CACHE[key]
+    else:
+        module = string_to_module(
+            name,
+            content,
+            fallback=fallback,
+            resolve_imports=resolve_imports,
+            resolve_imports_depth=resolve_imports_depth,
+            unmount_before_update=unmount_before_update,
+        )
+        _STRING_JS_MODULE_CACHE[key] = module
+    return module_to_vdom(module, import_names, fallback, allow_children)

reactpy/reactjs/module.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from reactpy import config
+from reactpy.config import REACTPY_WEB_MODULES_DIR
+from reactpy.core.vdom import Vdom
+from reactpy.reactjs.types import NAME_SOURCE, URL_SOURCE
+from reactpy.reactjs.utils import (
+    are_files_identical,
+    copy_file,
+    module_name_suffix,
+    resolve_from_module_file,
+    resolve_from_module_url,
+)
+from reactpy.types import ImportSourceDict, JavaScriptModule, VdomConstructor
+
+logger = logging.getLogger(__name__)
+
+
+def url_to_module(
+    url: str,
+    fallback: Any | None = None,
+    resolve_imports: bool = True,
+    resolve_imports_depth: int = 5,
+    unmount_before_update: bool = False,
+) -> JavaScriptModule:
+    return JavaScriptModule(
+        source=url,
+        source_type=URL_SOURCE,
+        default_fallback=fallback,
+        file=None,
+        import_names=(
+            resolve_from_module_url(url, resolve_imports_depth)
+            if resolve_imports
+            else None
+        ),
+        unmount_before_update=unmount_before_update,
+    )
+
+
+def file_to_module(
+    name: str,
+    file: str | Path,
+    fallback: Any | None = None,
+    resolve_imports: bool = True,
+    resolve_imports_depth: int = 5,
+    unmount_before_update: bool = False,
+    symlink: bool = False,
+) -> JavaScriptModule:
+    name += module_name_suffix(name)
+
+    source_file = Path(file).resolve()
+    target_file = get_module_path(name)
+    if not source_file.exists():
+        msg = f"Source file does not exist: {source_file}"
+        raise FileNotFoundError(msg)
+
+    if not target_file.exists():
+        copy_file(target_file, source_file, symlink)
+    elif not are_files_identical(source_file, target_file):
+        logger.info(
+            f"Existing web module {name!r} will "
+            f"be replaced with {target_file.resolve()}"
+        )
+        target_file.unlink()
+        copy_file(target_file, source_file, symlink)
+
+    return JavaScriptModule(
+        source=name,
+        source_type=NAME_SOURCE,
+        default_fallback=fallback,
+        file=target_file,
+        import_names=(
+            resolve_from_module_file(source_file, resolve_imports_depth)
+            if resolve_imports
+            else None
+        ),
+        unmount_before_update=unmount_before_update,
+    )
+
+
+def string_to_module(
+    name: str,
+    content: str,
+    fallback: Any | None = None,
+    resolve_imports: bool = True,
+    resolve_imports_depth: int = 5,
+    unmount_before_update: bool = False,
+) -> JavaScriptModule:
+    name += module_name_suffix(name)
+
+    target_file = get_module_path(name)
+
+    if target_file.exists() and target_file.read_text(encoding="utf-8") != content:
+        logger.info(
+            f"Existing web module {name!r} will "
+            f"be replaced with {target_file.resolve()}"
+        )
+        target_file.unlink()
+
+    target_file.parent.mkdir(parents=True, exist_ok=True)
+    target_file.write_text(content)
+
+    return JavaScriptModule(
+        source=name,
+        source_type=NAME_SOURCE,
+        default_fallback=fallback,
+        file=target_file,
+        import_names=(
+            resolve_from_module_file(target_file, resolve_imports_depth)
+            if resolve_imports
+            else None
+        ),
+        unmount_before_update=unmount_before_update,
+    )
+
+
+def module_to_vdom(
+    web_module: JavaScriptModule,
+    import_names: str | list[str] | tuple[str, ...],
+    fallback: Any | None = None,
+    allow_children: bool = True,
+) -> VdomConstructor | list[VdomConstructor]:
+    """Return one or more VDOM constructors from a :class:`JavaScriptModule`
+
+    Parameters:
+        import_names:
+            One or more names to import. If given as a string, a single component
+            will be returned. If a list is given, then a list of components will be
+            returned.
+        fallback:
+            What to temporarily display while the module is being loaded.
+        allow_children:
+            Whether or not these components can have children.
+    """
+    if isinstance(import_names, str):
+        if (
+            web_module.import_names is not None
+            and import_names.split(".")[0] not in web_module.import_names
+        ):
+            msg = f"{web_module.source!r} does not contain {import_names!r}"
+            raise ValueError(msg)
+        return make_module(web_module, import_names, fallback, allow_children)
+    else:
+        if web_module.import_names is not None:
+            missing = sorted(
+                {e.split(".")[0] for e in import_names}.difference(
+                    web_module.import_names
+                )
+            )
+            if missing:
+                msg = f"{web_module.source!r} does not contain {missing!r}"
+                raise ValueError(msg)
+        return [
+            make_module(web_module, name, fallback, allow_children)
+            for name in import_names
+        ]
+
+
+def make_module(
+    web_module: JavaScriptModule,
+    name: str,
+    fallback: Any | None,
+    allow_children: bool,
+) -> VdomConstructor:
+    return Vdom(
+        name,
+        allow_children=allow_children,
+        import_source=ImportSourceDict(
+            source=web_module.source,
+            sourceType=web_module.source_type,
+            fallback=(fallback or web_module.default_fallback),
+            unmountBeforeUpdate=web_module.unmount_before_update,
+        ),
+    )
+
+
+def get_module_path(name: str) -> Path:
+    directory = REACTPY_WEB_MODULES_DIR.current
+    path = directory.joinpath(*name.split("/"))
+    return path.with_suffix(path.suffix)
+
+
+def import_reactjs():
+    from reactpy import html
+
+    base_url = config.REACTPY_PATH_PREFIX.current.strip("/")
+    return html.script(
+        {"type": "importmap"},
+        f"""
+        {{
+            "imports": {{
+                "react": "/{base_url}/static/react.js",
+                "react-dom": "/{base_url}/static/react-dom.js",
+                "react-dom/client": "/{base_url}/static/react-dom.js",
+                "react/jsx-runtime": "/{base_url}/static/react-jsx-runtime.js"
+            }}
+        }}
+        """,
+    )

reactpy/reactjs/types.py

@@ -0,0 +1,7 @@
+from reactpy.types import SourceType
+
+NAME_SOURCE = SourceType("NAME")
+"""A named source - usually a Javascript package name"""
+
+URL_SOURCE = SourceType("URL")
+"""A source loaded from a URL, usually a CDN"""