jupyter-builder 0.1.0a2__py3-none-any.whl

jupyter_builder/federated_extensions.py

@@ -0,0 +1,492 @@
+"""Utilities for installing Javascript extensions for the notebook"""
+
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import importlib
+import json
+import os
+import os.path as osp
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+except ImportError:
+    from importlib_metadata import PackageNotFoundError, version
+
+from os.path import basename, normpath
+from os.path import join as pjoin
+
+from jupyter_core.paths import ENV_JUPYTER_PATH, SYSTEM_JUPYTER_PATH, jupyter_data_dir
+from jupyter_core.utils import ensure_dir_exists
+from jupyter_server.extension.serverextension import ArgumentConflict
+
+# from jupyterlab_server.config import get_federated_extensions
+from .federated_extensions_requirements import get_federated_extensions
+
+try:
+    from tomllib import load  # Python 3.11+
+except ImportError:
+    from tomli import load
+
+# from .commands import _test_overlap  TO BE DONE -----------------------------
+
+DEPRECATED_ARGUMENT = object()
+
+HERE = osp.abspath(osp.dirname(__file__))
+
+
+# ------------------------------------------------------------------------------
+# Public API
+# ------------------------------------------------------------------------------
+
+
+def develop_labextension(  # noqa
+    path,
+    symlink=True,
+    overwrite=False,
+    user=False,
+    labextensions_dir=None,
+    destination=None,
+    logger=None,
+    sys_prefix=False,
+):
+    """Install a prebuilt extension for JupyterLab
+
+    Stages files and/or directories into the labextensions directory.
+    By default, this compares modification time, and only stages files that need updating.
+    If `overwrite` is specified, matching files are purged before proceeding.
+
+    Parameters
+    ----------
+
+    path : path to file, directory, zip or tarball archive, or URL to install
+        By default, the file will be installed with its base name, so '/path/to/foo'
+        will install to 'labextensions/foo'. See the destination argument below to change this.
+        Archives (zip or tarballs) will be extracted into the labextensions directory.
+    user : bool [default: False]
+        Whether to install to the user's labextensions directory.
+        Otherwise do a system-wide install (e.g. /usr/local/share/jupyter/labextensions).
+    overwrite : bool [default: False]
+        If True, always install the files, regardless of what may already be installed.
+    symlink : bool [default: True]
+        If True, create a symlink in labextensions, rather than copying files.
+        Windows support for symlinks requires a permission bit which only admin users
+        have by default, so don't rely on it.
+    labextensions_dir : str [optional]
+        Specify absolute path of labextensions directory explicitly.
+    destination : str [optional]
+        name the labextension is installed to.  For example, if destination is 'foo', then
+        the source file will be installed to 'labextensions/foo', regardless of the source name.
+    logger : Jupyter logger [optional]
+        Logger instance to use
+    """
+    # the actual path to which we eventually installed
+    full_dest = None
+
+    labext = _get_labextension_dir(
+        user=user, sys_prefix=sys_prefix, labextensions_dir=labextensions_dir
+    )
+    # make sure labextensions dir exists
+    ensure_dir_exists(labext)
+
+    if isinstance(path, (list, tuple)):
+        msg = "path must be a string pointing to a single extension to install; call this function multiple times to install multiple extensions"
+        raise TypeError(msg)
+
+    if not destination:
+        destination = basename(normpath(path))
+
+    full_dest = normpath(pjoin(labext, destination))
+    if overwrite and os.path.lexists(full_dest):
+        if logger:
+            logger.info("Removing: %s" % full_dest)
+        if os.path.isdir(full_dest) and not os.path.islink(full_dest):
+            shutil.rmtree(full_dest)
+        else:
+            os.remove(full_dest)
+
+    # Make sure the parent directory exists
+    os.makedirs(os.path.dirname(full_dest), exist_ok=True)
+
+    if symlink:
+        path = os.path.abspath(path)
+        if not os.path.exists(full_dest):
+            if logger:
+                logger.info(f"Symlinking: {full_dest} -> {path}")
+            try:
+                os.symlink(path, full_dest)
+            except OSError as e:
+                if platform.platform().startswith("Windows"):
+                    msg = (
+                        "Symlinks can be activated on Windows 10 for Python version 3.8 or higher"
+                        " by activating the 'Developer Mode'. That may not be allowed by your administrators.\n"
+                        "See https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development"
+                    )
+                    raise OSError(msg) from e
+                raise
+
+        elif not os.path.islink(full_dest):
+            raise ValueError("%s exists and is not a symlink" % full_dest)
+
+    elif os.path.isdir(path):
+        path = pjoin(os.path.abspath(path), "")  # end in path separator
+        for parent, _, files in os.walk(path):
+            dest_dir = pjoin(full_dest, parent[len(path) :])
+            if not os.path.exists(dest_dir):
+                if logger:
+                    logger.info("Making directory: %s" % dest_dir)
+                os.makedirs(dest_dir)
+            for file_name in files:
+                src = pjoin(parent, file_name)
+                dest_file = pjoin(dest_dir, file_name)
+                _maybe_copy(src, dest_file, logger=logger)
+    else:
+        src = path
+        _maybe_copy(src, full_dest, logger=logger)
+
+    return full_dest
+
+
+def develop_labextension_py(
+    module,
+    user=False,
+    sys_prefix=False,
+    overwrite=True,
+    symlink=True,
+    labextensions_dir=None,
+    logger=None,
+):
+    """Develop a labextension bundled in a Python package.
+
+    Returns a list of installed/updated directories.
+
+    See develop_labextension for parameter information."""
+    m, labexts = _get_labextension_metadata(module)
+    base_path = os.path.split(m.__file__)[0]
+
+    full_dests = []
+
+    for labext in labexts:
+        src = os.path.join(base_path, labext["src"])
+        dest = labext["dest"]
+        if logger:
+            logger.info(f"Installing {src} -> {dest}")
+
+        if not os.path.exists(src):
+            build_labextension(base_path, logger=logger)
+
+        full_dest = develop_labextension(
+            src,
+            overwrite=overwrite,
+            symlink=symlink,
+            user=user,
+            sys_prefix=sys_prefix,
+            labextensions_dir=labextensions_dir,
+            destination=dest,
+            logger=logger,
+        )
+        full_dests.append(full_dest)
+
+    return full_dests
+
+
+from .core_path import default_core_path
+
+
+def build_labextension(
+    path, logger=None, development=False, static_url=None, source_map=False, core_path=None
+):
+    """Build a labextension in the given path"""
+
+    core_path = default_core_path() if core_path is None else str(Path(core_path).resolve())
+
+    ext_path = str(Path(path).resolve())
+
+    if logger:
+        logger.info("Building extension in %s" % path)
+
+    builder = _ensure_builder(ext_path, core_path)
+
+    arguments = ["node", builder, "--core-path", core_path, ext_path]
+    if static_url is not None:
+        arguments.extend(["--static-url", static_url])
+    if development:
+        arguments.append("--development")
+    if source_map:
+        arguments.append("--source-map")
+
+    subprocess.check_call(arguments, cwd=ext_path)  # noqa S603
+
+
+def watch_labextension(
+    path, labextensions_path, logger=None, development=False, source_map=False, core_path=None
+):
+    """Watch a labextension in a given path"""
+    core_path = default_core_path() if core_path is None else str(Path(core_path).resolve())
+    ext_path = str(Path(path).resolve())
+
+    if logger:
+        logger.info("Building extension in %s" % path)
+
+    # Check to see if we need to create a symlink
+    federated_extensions = get_federated_extensions(labextensions_path)
+
+    with open(pjoin(ext_path, "package.json")) as fid:
+        ext_data = json.load(fid)
+
+    if ext_data["name"] not in federated_extensions:
+        develop_labextension_py(ext_path, sys_prefix=True)
+    else:
+        full_dest = pjoin(federated_extensions[ext_data["name"]]["ext_dir"], ext_data["name"])
+        output_dir = pjoin(ext_path, ext_data["jupyterlab"].get("outputDir", "static"))
+        if not osp.islink(full_dest):
+            shutil.rmtree(full_dest)
+            os.symlink(output_dir, full_dest)
+
+    builder = _ensure_builder(ext_path, core_path)
+    arguments = ["node", builder, "--core-path", core_path, "--watch", ext_path]
+    if development:
+        arguments.append("--development")
+    if source_map:
+        arguments.append("--source-map")
+
+    subprocess.check_call(arguments, cwd=ext_path)  # noqa S603
+
+
+# ------------------------------------------------------------------------------
+# Private API
+# ------------------------------------------------------------------------------
+
+
+def _ensure_builder(ext_path, core_path):
+    """Ensure that we can build the extension and return the builder script path"""
+    # Test for compatible dependency on @jupyterlab/builder
+    with open(osp.join(core_path, "package.json")) as fid:
+        core_data = json.load(fid)
+    with open(osp.join(ext_path, "package.json")) as fid:
+        ext_data = json.load(fid)
+    dep_version1 = core_data["devDependencies"]["@jupyterlab/builder"]
+    dep_version2 = ext_data.get("devDependencies", {}).get("@jupyterlab/builder")
+    dep_version2 = dep_version2 or ext_data.get("dependencies", {}).get("@jupyterlab/builder")
+    if dep_version2 is None:
+        raise ValueError(
+            "Extensions require a devDependency on @jupyterlab/builder@%s" % dep_version1
+        )
+
+    # if we have installed from disk (version is a path), assume we know what
+    # we are doing and do not check versions.
+    if "/" in dep_version2:
+        with open(osp.join(ext_path, dep_version2, "package.json")) as fid:
+            dep_version2 = json.load(fid).get("version")
+    if not osp.exists(osp.join(ext_path, "node_modules")):
+        subprocess.check_call(["jlpm"], cwd=ext_path)  # noqa S603 S607
+
+    # Find @jupyterlab/builder using node module resolution
+    # We cannot use a script because the script path is a shell script on Windows
+    target = ext_path
+    while not osp.exists(osp.join(target, "node_modules", "@jupyterlab", "builder")):
+        if osp.dirname(target) == target:
+            msg = "Could not find @jupyterlab/builder"
+            raise ValueError(msg)
+        target = osp.dirname(target)
+
+    # IGNORING Test Overlap ---------------------------------
+
+    # overlap = _test_overlap(
+    #     dep_version1, dep_version2, drop_prerelease1=True, drop_prerelease2=True
+    # )
+    # if not overlap:
+    #     with open(
+    #         osp.join(target, "node_modules", "@jupyterlab", "builder", "package.json")
+    #     ) as fid:
+    #         dep_version2 = json.load(fid).get("version")
+    #     overlap = _test_overlap(
+    #         dep_version1, dep_version2, drop_prerelease1=True, drop_prerelease2=True
+    #     )
+
+    # if not overlap:
+    #     msg = f"Extensions require a devDependency on @jupyterlab/builder@{dep_version1}, you have a dependency on {dep_version2}"
+    #     raise ValueError(msg)
+
+    return osp.join(
+        target, "node_modules", "@jupyterlab", "builder", "lib", "build-labextension.js"
+    )
+
+
+def _should_copy(src, dest, logger=None):
+    """Should a file be copied, if it doesn't exist, or is newer?
+
+    Returns whether the file needs to be updated.
+
+    Parameters
+    ----------
+
+    src : string
+        A path that should exist from which to copy a file
+    src : string
+        A path that might exist to which to copy a file
+    logger : Jupyter logger [optional]
+        Logger instance to use
+    """
+    if not os.path.exists(dest):
+        return True
+    if os.stat(src).st_mtime - os.stat(dest).st_mtime > 1e-6:  # noqa
+        # we add a fudge factor to work around a bug in python 2.x
+        # that was fixed in python 3.x: https://bugs.python.org/issue12904
+        if logger:
+            logger.warning("Out of date: %s" % dest)
+        return True
+    if logger:
+        logger.info("Up to date: %s" % dest)
+    return False
+
+
+def _maybe_copy(src, dest, logger=None):
+    """Copy a file if it needs updating.
+
+    Parameters
+    ----------
+
+    src : string
+        A path that should exist from which to copy a file
+    src : string
+        A path that might exist to which to copy a file
+    logger : Jupyter logger [optional]
+        Logger instance to use
+    """
+    if _should_copy(src, dest, logger=logger):
+        if logger:
+            logger.info(f"Copying: {src} -> {dest}")
+        shutil.copy2(src, dest)
+
+
+def _get_labextension_dir(user=False, sys_prefix=False, prefix=None, labextensions_dir=None):
+    """Return the labextension directory specified
+
+    Parameters
+    ----------
+
+    user : bool [default: False]
+        Get the user's .jupyter/labextensions directory
+    sys_prefix : bool [default: False]
+        Get sys.prefix, i.e. ~/.envs/my-env/share/jupyter/labextensions
+    prefix : str [optional]
+        Get custom prefix
+    labextensions_dir : str [optional]
+        Get what you put in
+    """
+    conflicting = [
+        ("user", user),
+        ("prefix", prefix),
+        ("labextensions_dir", labextensions_dir),
+        ("sys_prefix", sys_prefix),
+    ]
+    conflicting_set = [f"{n}={v!r}" for n, v in conflicting if v]
+    if len(conflicting_set) > 1:
+        msg = "cannot specify more than one of user, sys_prefix, prefix, or labextensions_dir, but got: {}".format(
+            ", ".join(conflicting_set)
+        )
+        raise ArgumentConflict(msg)
+    if user:
+        labext = pjoin(jupyter_data_dir(), "labextensions")
+    elif sys_prefix:
+        labext = pjoin(ENV_JUPYTER_PATH[0], "labextensions")
+    elif prefix:
+        labext = pjoin(prefix, "share", "jupyter", "labextensions")
+    elif labextensions_dir:
+        labext = labextensions_dir
+    else:
+        labext = pjoin(SYSTEM_JUPYTER_PATH[0], "labextensions")
+    return labext
+
+
+def _get_labextension_metadata(module):  # noqa
+    """Get the list of labextension paths associated with a Python module.
+
+    Returns a tuple of (the module path,             [{
+        'src': 'mockextension',
+        'dest': '_mockdestination'
+    }])
+
+    Parameters
+    ----------
+
+    module : str
+        Importable Python module exposing the
+        magic-named `_jupyter_labextension_paths` function
+    """
+    mod_path = osp.abspath(module)
+    if not osp.exists(mod_path):
+        msg = f"The path `{mod_path}` does not exist."
+        # breakpoint()
+        raise FileNotFoundError(msg)
+
+    errors = []
+
+    # Check if the path is a valid labextension
+    try:
+        m = importlib.import_module(module)
+        if hasattr(m, "_jupyter_labextension_paths"):
+            return m, m._jupyter_labextension_paths()
+    except Exception as exc:
+        errors.append(exc)
+
+    # Try to get the package name
+    package = None
+
+    # Try getting the package name from pyproject.toml
+    if os.path.exists(os.path.join(mod_path, "pyproject.toml")):
+        with open(os.path.join(mod_path, "pyproject.toml"), "rb") as fid:
+            data = load(fid)
+        package = data.get("project", {}).get("name")
+
+    # Try getting the package name from setup.py
+    if not package:
+        try:
+            package = (
+                subprocess.check_output(
+                    [sys.executable, "setup.py", "--name"],  # noqa S603
+                    cwd=mod_path,
+                )
+                .decode("utf8")
+                .strip()
+            )
+        except subprocess.CalledProcessError:
+            msg = (
+                f"The Python package `{module}` is not a valid package, "
+                "it is missing the `setup.py` file."
+            )
+            raise FileNotFoundError(msg) from None
+
+    # Make sure the package is installed
+    try:
+        version(package)
+    except PackageNotFoundError:
+        subprocess.check_call([sys.executable, "-m", "pip", "install", "-e", mod_path])  # noqa S603
+        sys.path.insert(0, mod_path)
+
+    from setuptools import find_namespace_packages, find_packages
+
+    package_candidates = [
+        package.replace("-", "_"),  # Module with the same name as package
+    ]
+    package_candidates.extend(find_packages(mod_path))  # Packages in the module path
+    package_candidates.extend(
+        find_namespace_packages(mod_path)
+    )  # Namespace packages in the module path
+
+    for package in package_candidates:
+        try:
+            m = importlib.import_module(package)
+            if hasattr(m, "_jupyter_labextension_paths"):
+                return m, m._jupyter_labextension_paths()
+        except Exception as exc:
+            errors.append(exc)
+
+    msg = f"There is no labextension at {module}. Errors encountered: {errors}"
+    raise ModuleNotFoundError(msg)

jupyter_builder/federated_extensions_requirements.py

@@ -0,0 +1,74 @@
+"""JupyterLab Server config"""
+
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+from __future__ import annotations
+
+import json
+import os.path as osp
+from glob import iglob
+from itertools import chain
+
+# from logging import Logger
+from os.path import join as pjoin
+from typing import Any
+
+# import json5  # type:ignore[import-untyped]
+# from jupyter_core.paths import SYSTEM_CONFIG_PATH, jupyter_config_dir, jupyter_path
+# from jupyter_server.services.config.manager import ConfigManager, recursive_update
+# from jupyter_server.utils import url_path_join as ujoin
+# from traitlets import Bool, HasTraits, List, Unicode, default
+
+# -----------------------------------------------------------------------------
+# Module globals
+# -----------------------------------------------------------------------------
+
+DEFAULT_TEMPLATE_PATH = osp.join(osp.dirname(__file__), "templates")
+
+
+def get_package_url(data: dict[str, Any]) -> str:
+    """Get the url from the extension data"""
+    # homepage, repository  are optional
+    if "homepage" in data:
+        url = data["homepage"]
+    elif "repository" in data and isinstance(data["repository"], dict):
+        url = data["repository"].get("url", "")
+    else:
+        url = ""
+    return url
+
+
+def get_federated_extensions(labextensions_path: list[str]) -> dict[str, Any]:
+    """Get the metadata about federated extensions"""
+    federated_extensions = {}
+    for ext_dir in labextensions_path:
+        # extensions are either top-level directories, or two-deep in @org directories
+        for ext_path in chain(
+            iglob(pjoin(ext_dir, "[!@]*", "package.json")),
+            iglob(pjoin(ext_dir, "@*", "*", "package.json")),
+        ):
+            with open(ext_path, encoding="utf-8") as fid:
+                pkgdata = json.load(fid)
+            if pkgdata["name"] not in federated_extensions:
+                data = dict(
+                    name=pkgdata["name"],
+                    version=pkgdata["version"],
+                    description=pkgdata.get("description", ""),
+                    url=get_package_url(pkgdata),
+                    ext_dir=ext_dir,
+                    ext_path=osp.dirname(ext_path),
+                    is_local=False,
+                    dependencies=pkgdata.get("dependencies", dict()),
+                    jupyterlab=pkgdata.get("jupyterlab", dict()),
+                )
+
+                # Add repository info if available
+                if "repository" in pkgdata and "url" in pkgdata.get("repository", {}):
+                    data["repository"] = dict(url=pkgdata.get("repository").get("url"))
+
+                install_path = osp.join(osp.dirname(ext_path), "install.json")
+                if osp.exists(install_path):
+                    with open(install_path, encoding="utf-8") as fid:
+                        data["install"] = json.load(fid)
+                federated_extensions[data["name"]] = data
+    return federated_extensions

jupyter_builder/jlpm.py

@@ -0,0 +1,43 @@
+"""A Jupyter-aware wrapper for the yarn package manager"""
+
+import os
+
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+import sys
+
+from jupyterlab_server.process import subprocess, which
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+YARN_PATH = os.path.join(HERE, "yarn.js")
+
+
+def execvp(cmd, argv):
+    """Execvp, except on Windows where it uses Popen.
+
+    The first argument, by convention, should point to the filename
+    associated with the file being executed.
+
+    Python provides execvp on Windows, but its behavior is problematic
+    (Python bug#9148).
+    """
+    cmd = which(cmd)
+    if os.name == "nt":
+        import signal
+        import sys
+
+        p = subprocess.Popen([cmd] + argv[1:])
+        # Don't raise KeyboardInterrupt in the parent process.
+        # Set this after spawning, to avoid subprocess inheriting handler.
+        signal.signal(signal.SIGINT, signal.SIG_IGN)
+        p.wait()
+        sys.exit(p.returncode)
+    else:
+        os.execvp(cmd, argv)  # noqa S606
+
+
+def main(argv=None):
+    """Run node and return the result."""
+    # Make sure node is available.
+    argv = argv or sys.argv[1:]
+    execvp("node", ["node", YARN_PATH, *argv])