feat: Add shinylive url command

setup.cfg

@@ -36,6 +36,7 @@ install_requires =
     shiny
     click>=8.1.7
     appdirs>=1.4.4
+    lzstring>=1.0.4
 tests_require =
     pytest>=3
 zip_safe = False

shinylive/__init__.py

@@ -1,5 +1,11 @@
 """A package for packaging Shiny applications that run on Python in the browser."""
 
 from . import _version
+from ._url import decode_shinylive_url, encode_shinylive_url
 
 __version__ = _version.SHINYLIVE_PACKAGE_VERSION
+
+__all__ = (
+    "decode_shinylive_url",
+    "encode_shinylive_url",
+)

shinylive/_main.py

@@ -8,6 +8,7 @@
 import click
 
 from . import _assets, _deps, _export, _version
+from ._url import decode_shinylive_url, encode_shinylive_url
 from ._utils import print_as_json
 
 
@@ -59,6 +60,7 @@ def list_commands(self, ctx: click.Context) -> list[str]:
 #         * language-resources
 #         * app-resources
 #             * Options: --json-file / stdin (required)
+#     * url
 
 
 # #############################################################################
@@ -469,6 +471,154 @@ def defunct_help(cmd: str) -> str:
 """
 
 
+# #############################################################################
+# ## shinylive.io url
+# #############################################################################
+
+
+@main.group(
+    short_help="Create or decode a shinylive.io URL.",
+    help="Create or decode a shinylive.io URL.",
+    no_args_is_help=True,
+    cls=OrderedGroup,
+)
+def url() -> None:
+    pass
+
+
+@url.command(
+    short_help="Create a shinylive.io URL from local files.",
+    help="""
+Create a shinylive.io URL for a Shiny app from local files.
+
+APP is the path to the primary Shiny app file.
+
+FILES are additional supporting files for the app.
+
+On macOS, you can copy the URL to the clipboard with:
+
+    shinylive url encode app.py | pbcopy
+""",
+    no_args_is_help=True,
+)
+@click.option(
+    "-m",
+    "--mode",
+    type=click.Choice(["editor", "app"]),
+    required=True,
+    default="editor",
+    help="The shinylive mode: include the editor or show only the app.",
+)
+@click.option(
+    "-l",
+    "--language",
+    type=click.Choice(["python", "py", "R", "r"]),
+    required=False,
+    default=None,
+    help="The primary language used to run the app, by default inferred from the app file.",
+)
+@click.option(
+    "-v", "--view", is_flag=True, default=False, help="Open the link in a browser."
+)
+@click.option(
+    "--no-header", is_flag=True, default=False, help="Hide the Shinylive header."
+)
+@click.argument("app", type=str, nargs=1, required=True, default="-")
+@click.argument("files", type=str, nargs=-1, required=False)
+def encode(
+    app: str,
+    files: Optional[tuple[str, ...]] = None,
+    mode: str = "editor",
+    language: Optional[str] = None,
+    no_header: bool = False,
+    view: bool = False,
+) -> None:
+    if app == "-":
+        app_in = sys.stdin.read()
+    else:
+        app_in = app
+
+    url = encode_shinylive_url(
+        app=app_in,
+        files=files,
+        mode=mode,
+        language=language,
+        header=not no_header,
+    )
+
+    print(url)
+
+    if view:
+        import webbrowser
+
+        webbrowser.open(url)
+    return
+
+
+@url.command(
+    short_help="Decode a shinylive.io URL.",
+    help="""
+Decode a shinylive.io URL.
+
+URL is the shinylive editor or app URL. If not specified, the URL will be read from
+stdin, allowing you to read the URL from a file or the clipboard.
+
+On macOS, you can read the URL from the clipboard with:
+
+    pbpaste | shinylive url decode
+""",
+)
+@click.option(
+    "--out",
+    type=str,
+    default=None,
+    help="Output directory into which the app's files will be written. The directory is created if it does not exist. ",
+)
+@click.option(
+    "--json",
+    is_flag=True,
+    default=False,
+    help="Prints the decoded shinylive bundle as JSON to stdout, ignoring --out.",
+)
+@click.argument("url", type=str, nargs=1, default="-")
+def decode(url: str, out: Optional[str] = None, json: bool = False) -> None:
+    if url == "-":
+        url_in = sys.stdin.read()
+    else:
+        url_in = url
+    bundle = decode_shinylive_url(str(url_in))
+
+    if json:
+        print_as_json(bundle)
+        return
+
+    if out is not None:
+        import os
+
+        out_dir = Path(out)
+        os.makedirs(out_dir, exist_ok=True)
+        for file in bundle:
+            with open(out_dir / file["name"], "w") as f_out:
+                f_out.write(
+                    file["content"].encode("utf-8", errors="ignore").decode("utf-8")
+                )
+    else:
+        print("")
+        for file in bundle:
+            print(f"## file: {file['name']}")
+            if "type" in file and file["type"] == "binary":
+                print("## type: binary")
+            print("")
+            print(file["content"].encode("utf-8", errors="ignore").decode("utf-8"))
+
+    return
+
+
+# #############################################################################
+# ## Deprecated commands
+# #############################################################################
+
+
 def defunct_error_txt(cmd: str) -> str:
     return f"Error: { defunct_help(cmd) }"
 

shinylive/_url.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import List, Literal, Optional, TypedDict, cast
+
+
+class FileContentJson(TypedDict):
+    name: str
+    content: str
+    type: Literal["text", "binary"]
+
+
+def encode_shinylive_url(
+    app: str | Path,
+    files: Optional[tuple[str | Path, ...]] = None,
+    mode: str = "editor",
+    language: Optional[str] = None,
+    header: bool = True,
+) -> str:
+    """
+    Generate a URL for a [ShinyLive application](https://shinylive.io).
+
+    Parameters
+    ----------
+    app
+        The main app file of the ShinyLive application. This file should be a Python
+        `app.py` or an R `app.R`, `ui.R`, or `server.R` file. This file will be renamed
+         `app.py` or `app.R` for shinylive, unless it's named `ui.R` or `server.R`.
+    files
+        A tuple of file paths to include in the application. On shinylive, these files
+        will be given stored relative to the main `app` file.
+    mode
+        The mode of the application. Defaults to "editor".
+    language
+        The language of the application. Defaults to None.
+    header
+        Whether to include a header. Defaults to True.
+
+    Returns
+    -------
+        The generated URL for the ShinyLive application.
+    """
+    root_dir = Path(app).parent
+
+    # if app has a newline, then it's app content, not a path
+    if isinstance(app, str) and "\n" in app:
+        # now language is required
+        if language is None:
+            raise ValueError("If `app` is a string, then `language` must be specified.")
+        file_bundle = [
+            {
+                "name": f"app.{'py' if language == 'py' else 'R'}",
+                "content": app,
+                "type": "text",
+            }
+        ]
+    else:
+        file_bundle = [read_file(app, root_dir)]
+
+    if files is not None:
+        file_bundle = file_bundle + [read_file(file, root_dir) for file in files]
+
+    if language is None:
+        language = file_bundle[0]["name"].split(".")[-1].lower()
+    else:
+        language = "py" if language.lower() in ["py", "python"] else "r"
+
+    # if first file is not named either `ui.R` or `server.R`, then make it app.{language}
+    if file_bundle[0]["name"] not in ["ui.R", "server.R"]:
+        file_bundle[0]["name"] = f"app.{'py' if language == 'py' else 'R'}"
+
+    file_lz = lzstring_file_bundle(cast(List[FileContentJson], file_bundle))
+
+    base = "https://shinylive.io"
+
+    return f"{base}/{language}/{mode}/#{'h=0&' if not header else ''}code={file_lz}"
+
+
+def decode_shinylive_url(url: str) -> List[FileContentJson]:
+    from lzstring import LZString  # type: ignore[reportMissingTypeStubs]
+
+    url = url.strip()
+
+    try:
+        bundle_json = cast(
+            str,
+            LZString.decompressFromEncodedURIComponent(  # type: ignore
+                url.split("code=")[1]
+            ),
+        )
+        bundle = json.loads(bundle_json)
+    except Exception:
+        raise ValueError("Could not parse and decode the shinylive URL code payload.")
+
+    # bundle should be an array of FileContentJson objects, otherwise raise an error
+    if not isinstance(bundle, list):
+        raise ValueError(
+            "The shinylive URL was not formatted correctly: `code` did not decode to a list."
+        )
+
+    for file in bundle:  # type: ignore
+        if not isinstance(file, dict):
+            raise ValueError(
+                "Invalid shinylive URL: `code` did not decode to a list of dictionaries."
+            )
+        if not all(key in file for key in ["name", "content"]):
+            raise ValueError(
+                "Invalid shinylive URL: `code` included an object that was missing required fields `name` or `content`."
+            )
+        if "type" in file and file["type"] not in ["text", "binary"]:
+            raise ValueError(
+                f"Invalid shinylive URL: unexpected file type '{file['type']}' in '{file['name']}'."
+            )
+        elif "type" not in file:
+            file["type"] = "text"
+        if not all(isinstance(value, str) for value in file.values()):  # type: ignore
+            raise ValueError(
+                f"Invalid shinylive URL: not all items in '{file['name']}' were strings."
+            )
+
+    return cast(List[FileContentJson], bundle)
+
+
+# Copied from https://github.com/posit-dev/py-shiny/blob/main/docs/_renderer.py#L231
+def read_file(file: str | Path, root_dir: str | Path | None = None) -> FileContentJson:
+    file = Path(file)
+    if root_dir is None:
+        root_dir = Path("/")
+    root_dir = Path(root_dir)
+
+    type: Literal["text", "binary"] = "text"
+
+    try:
+        with open(file, "r") as f:
+            file_content = f.read()
+            type = "text"
+    except UnicodeDecodeError:
+        # If text failed, try binary.
+        with open(file, "rb") as f:
+            file_content_bin = f.read()
+            file_content = base64.b64encode(file_content_bin).decode("utf-8")
+            type = "binary"
+
+    return {
+        "name": str(file.relative_to(root_dir)),
+        "content": file_content,
+        "type": type,
+    }
+
+
+def lzstring_file_bundle(file_bundle: List[FileContentJson]) -> str:
+    from lzstring import LZString  # type: ignore[reportMissingTypeStubs]
+
+    file_json = json.dumps(file_bundle)
+    file_lz = LZString.compressToEncodedURIComponent(file_json)  # type: ignore[reportUnknownMemberType]
+    return cast(str, file_lz)