tugboat-py 0.1.0__tar.gz

tugboat_py-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.3
+Name: tugboat-py
+Version: 0.1.0
+Summary: Simple utilities to generate a Dockerfile from a directory or project, build the corresponding Docker image, push the image to DockerHub, and publicly share the project via Binder.
+Author: Daniel Molitor
+Author-email: Daniel Molitor <molitdj97@gmail.com>
+Requires-Dist: pigar>=2.2.0
+Requires-Dist: pygit2>=1.19.3
+Requires-Dist: pyperclip>=1.11.0
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# tugboat <!-- <img src='man/figures/logo-no-bg.png' align="right" height="140"/> -->
+
+<!-- badges: start -->
+<!-- badges: end -->
+
+A simple Python package to generate a Dockerfile and corresponding Docker image
+from an analysis directory. tugboat also prepares your analysis repository to be
+shared via [Binder](https://mybinder.readthedocs.io/en/latest/index.html).
+
+tugboat uses the [pigar](https://github.com/damnever/pigar) package to automatically
+detect all the packages necessary to replicate your analysis and will generate
+a Dockerfile that contains an exact copy of your entire directory with all
+the packages installed. tugboat transforms an unstructured analysis folder into a `requirements.txt` file
+and constructs a Docker image that includes all your essential R packages
+based on this file. tugboat utilizes [uv](https://docs.astral.sh/uv/) under the hood;
+as a result, projects that already utilize uv should be directly compatible with no
+additional setup.
+
+tugboat may be of use, for example, when preparing a replication package for
+research. With tugboat, you can take a directory on your local computer
+and quickly generate a corresponding Dockerfile and Docker image that contains all the
+code and the necessary software to reproduce your findings.
+
+## Installation
+
+Install tugboat from GitHub:
+```r
+pip install git+https://github.com/dmolitor/tugboat-py
+```
+
+## Usage
+
+tugboat has three primary functions; one to create a Dockerfile from your
+analysis directory, one to build the corresponding Docker image, and one to make
+your project ready to share and run in an online, interactive compute environment
+via [Binder](https://mybinder.readthedocs.io/en/latest/index.html).
+
+### Create the Dockerfile
+
+The primary function from tugboat is `create()`. This function converts 
+your analysis directory into a Dockerfile that includes all your code 
+and essential Python packages.
+
+This function scans all files in the current analysis directory,
+attempts to detect all Python packages, and installs these packages in
+the resulting Docker image. It also copies the entire contents of the
+analysis directory into the Docker image. For example, if
+your analysis directory is named `incredible_analysis`, the corresponding
+location of your code and data files in the generated Docker image will
+be `/incredible_analysis`.
+
+For the most common use-cases, there are a couple of arguments in this
+function that are particularly important:
+
+- `project`: This argument tells tugboat which directory is the one to generate
+the Dockerfile from. You can set this value yourself, or you can just use
+the default value. By default, tugboat uses the working directory to
+determine the analysis directory.
+- `exclude`: A list of files or sub-directories in your analysis directory
+that should ***NOT*** be included in the Docker image. This is particularly
+important when you have, for example, a sub-directory with large data files
+that would make the resulting Docker image extremely large if included. You
+can tell tugboat to exclude this sub-directory and then simply mount it to
+a Docker container as needed.
+
+Below I'll outline a couple examples.
+```python
+from tugboat import create
+
+# The simplest scenario where your analysis directory is your current
+# working directory, you are fine with the default base "python:3.x-slim"
+# Docker image, and you want to include all files/directories:
+create()
+
+# Suppose your analysis directory is actually a sub-directory of your
+# main project directory:
+create(project="./sub-directory")
+
+# Suppose that you specifically need a Docker base image that has uv
+# installed. To do this, we will explicitly specify a different Docker
+# base image using the `FROM` argument.
+create(FROM="ghcr.io/astral-sh/uv:latest")
+
+# Finally, suppose that we want to include all files except a couple
+# particularly data-heavy sub-directories:
+create(exclude=["data/big_directory_1", "data/big_directory_2"])
+```
+
+### Build the Docker image
+
+Once the Dockerfile has been created, we can build the Docker image
+with the `build()` function. By default this will assume the Dockerfile
+is located in the current working directory. This function assumes a little knowledge
+about Docker; if you aren't sure where to start,
+[this is a great starting point](https://colinfay.me/docker-r-reproducibility/).
+
+The following example will do the simplest thing and will build the
+image locally.
+```python
+build(image_name="awesome_analysis")
+```
+
+Suppose that, like above, your analysis directory is a sub-directory of
+your main project directory:
+```r
+build(
+    dockerfile="./sub-directory",
+    build_context="./sub-directory",
+    image_name="awesome_analysis"
+)
+```
+
+### Push to DockerHub
+
+If, instead of just building the Docker image locally, you want to build
+the image and then push to DockerHub, you can make a couple small additions
+to the code above:
+```python
+import os
+import dotenv
+from tugboat import build
+
+load_dotenv()
+
+build(
+    dockerfile="./sub-directory",
+    build_context="./sub-directory",
+    image_name="awesome_analysis"
+    image_name="awesome_analysis",
+    push=True,
+    dh_username=os.environ["DOCKERHUB_USERNAME"],
+    dh_password=os.environ["DOCKERHUB_USERNAME"]
+)
+```
+
+Note: If you choose to push, you also need to provide your DockerHub
+username and password. Typically you don't want to pass these in
+directly and should instead use environment variables (or a similar
+method) instead.
+
+### Share your project via Binder
+
+Binder lets others instantly launch and interact with your R project in a
+live, cloud-based environment with no local setup required. tugboat will
+prepare your project to be shared with Binder. The process is simple:
+
+- First, create the Dockerfile from your analysis directory:
+
+    ``` python
+    create(
+        project=".",
+        exclude=["data/big_directory_1", "data/big_directory_2"]
+    )
+    ```
+
+- Then, prep your directory for Binder. Your analysis directory _must_ be
+a GitHub repository:
+
+    ``` python
+    binderize(branch="main")
+    ```
+By default this will add a Binder badge to your README.md file if it already has a section for badges:
+
+``` python
+Added badge to /.../README.md
+```
+If your README file does _not_ have a section for badges, it will automatically
+save the badge to your clipboard and you will need to manually insert it
+into the README.
+
+``` python
+Add the following to your README.md file:
+
+<!-- badges: start -->
+[![Launch RStudio Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/{username}/{repo}/{branch}?urlpath=rstudio)
+<!-- badges: end -->
+```
+
+After running `binderize()` you will see the following message:
+```
+Your repository has been configured for Binder.
+[x] Commit and push all changes
+[x] Launch Binder at: https://mybinder.org/v2/gh/{username}/{repo}/{branch}?urlpath=rstudio
+```
+
+You must commit and push all changes _before_ visiting the Binder link,
+otherwise it will likely fail. Binder can automatically detect changes 
+to the repository and will rebuild as necessary, ensuring that the Binder
+repository stays up to date.
+
+## R package
+
+This package has a sibling [R package](https://github.com/dmolitor/tugboat)!

tugboat_py-0.1.0/README.md

@@ -0,0 +1,193 @@
+# tugboat <!-- <img src='man/figures/logo-no-bg.png' align="right" height="140"/> -->
+
+<!-- badges: start -->
+<!-- badges: end -->
+
+A simple Python package to generate a Dockerfile and corresponding Docker image
+from an analysis directory. tugboat also prepares your analysis repository to be
+shared via [Binder](https://mybinder.readthedocs.io/en/latest/index.html).
+
+tugboat uses the [pigar](https://github.com/damnever/pigar) package to automatically
+detect all the packages necessary to replicate your analysis and will generate
+a Dockerfile that contains an exact copy of your entire directory with all
+the packages installed. tugboat transforms an unstructured analysis folder into a `requirements.txt` file
+and constructs a Docker image that includes all your essential R packages
+based on this file. tugboat utilizes [uv](https://docs.astral.sh/uv/) under the hood;
+as a result, projects that already utilize uv should be directly compatible with no
+additional setup.
+
+tugboat may be of use, for example, when preparing a replication package for
+research. With tugboat, you can take a directory on your local computer
+and quickly generate a corresponding Dockerfile and Docker image that contains all the
+code and the necessary software to reproduce your findings.
+
+## Installation
+
+Install tugboat from GitHub:
+```r
+pip install git+https://github.com/dmolitor/tugboat-py
+```
+
+## Usage
+
+tugboat has three primary functions; one to create a Dockerfile from your
+analysis directory, one to build the corresponding Docker image, and one to make
+your project ready to share and run in an online, interactive compute environment
+via [Binder](https://mybinder.readthedocs.io/en/latest/index.html).
+
+### Create the Dockerfile
+
+The primary function from tugboat is `create()`. This function converts 
+your analysis directory into a Dockerfile that includes all your code 
+and essential Python packages.
+
+This function scans all files in the current analysis directory,
+attempts to detect all Python packages, and installs these packages in
+the resulting Docker image. It also copies the entire contents of the
+analysis directory into the Docker image. For example, if
+your analysis directory is named `incredible_analysis`, the corresponding
+location of your code and data files in the generated Docker image will
+be `/incredible_analysis`.
+
+For the most common use-cases, there are a couple of arguments in this
+function that are particularly important:
+
+- `project`: This argument tells tugboat which directory is the one to generate
+the Dockerfile from. You can set this value yourself, or you can just use
+the default value. By default, tugboat uses the working directory to
+determine the analysis directory.
+- `exclude`: A list of files or sub-directories in your analysis directory
+that should ***NOT*** be included in the Docker image. This is particularly
+important when you have, for example, a sub-directory with large data files
+that would make the resulting Docker image extremely large if included. You
+can tell tugboat to exclude this sub-directory and then simply mount it to
+a Docker container as needed.
+
+Below I'll outline a couple examples.
+```python
+from tugboat import create
+
+# The simplest scenario where your analysis directory is your current
+# working directory, you are fine with the default base "python:3.x-slim"
+# Docker image, and you want to include all files/directories:
+create()
+
+# Suppose your analysis directory is actually a sub-directory of your
+# main project directory:
+create(project="./sub-directory")
+
+# Suppose that you specifically need a Docker base image that has uv
+# installed. To do this, we will explicitly specify a different Docker
+# base image using the `FROM` argument.
+create(FROM="ghcr.io/astral-sh/uv:latest")
+
+# Finally, suppose that we want to include all files except a couple
+# particularly data-heavy sub-directories:
+create(exclude=["data/big_directory_1", "data/big_directory_2"])
+```
+
+### Build the Docker image
+
+Once the Dockerfile has been created, we can build the Docker image
+with the `build()` function. By default this will assume the Dockerfile
+is located in the current working directory. This function assumes a little knowledge
+about Docker; if you aren't sure where to start,
+[this is a great starting point](https://colinfay.me/docker-r-reproducibility/).
+
+The following example will do the simplest thing and will build the
+image locally.
+```python
+build(image_name="awesome_analysis")
+```
+
+Suppose that, like above, your analysis directory is a sub-directory of
+your main project directory:
+```r
+build(
+    dockerfile="./sub-directory",
+    build_context="./sub-directory",
+    image_name="awesome_analysis"
+)
+```
+
+### Push to DockerHub
+
+If, instead of just building the Docker image locally, you want to build
+the image and then push to DockerHub, you can make a couple small additions
+to the code above:
+```python
+import os
+import dotenv
+from tugboat import build
+
+load_dotenv()
+
+build(
+    dockerfile="./sub-directory",
+    build_context="./sub-directory",
+    image_name="awesome_analysis"
+    image_name="awesome_analysis",
+    push=True,
+    dh_username=os.environ["DOCKERHUB_USERNAME"],
+    dh_password=os.environ["DOCKERHUB_USERNAME"]
+)
+```
+
+Note: If you choose to push, you also need to provide your DockerHub
+username and password. Typically you don't want to pass these in
+directly and should instead use environment variables (or a similar
+method) instead.
+
+### Share your project via Binder
+
+Binder lets others instantly launch and interact with your R project in a
+live, cloud-based environment with no local setup required. tugboat will
+prepare your project to be shared with Binder. The process is simple:
+
+- First, create the Dockerfile from your analysis directory:
+
+    ``` python
+    create(
+        project=".",
+        exclude=["data/big_directory_1", "data/big_directory_2"]
+    )
+    ```
+
+- Then, prep your directory for Binder. Your analysis directory _must_ be
+a GitHub repository:
+
+    ``` python
+    binderize(branch="main")
+    ```
+By default this will add a Binder badge to your README.md file if it already has a section for badges:
+
+``` python
+Added badge to /.../README.md
+```
+If your README file does _not_ have a section for badges, it will automatically
+save the badge to your clipboard and you will need to manually insert it
+into the README.
+
+``` python
+Add the following to your README.md file:
+
+<!-- badges: start -->
+[![Launch RStudio Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/{username}/{repo}/{branch}?urlpath=rstudio)
+<!-- badges: end -->
+```
+
+After running `binderize()` you will see the following message:
+```
+Your repository has been configured for Binder.
+[x] Commit and push all changes
+[x] Launch Binder at: https://mybinder.org/v2/gh/{username}/{repo}/{branch}?urlpath=rstudio
+```
+
+You must commit and push all changes _before_ visiting the Binder link,
+otherwise it will likely fail. Binder can automatically detect changes 
+to the repository and will rebuild as necessary, ensuring that the Binder
+repository stays up to date.
+
+## R package
+
+This package has a sibling [R package](https://github.com/dmolitor/tugboat)!

tugboat_py-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "tugboat-py"
+version = "0.1.0"
+description = "Simple utilities to generate a Dockerfile from a directory or project, build the corresponding Docker image, push the image to DockerHub, and publicly share the project via Binder."
+readme = "README.md"
+authors = [
+    { name = "Daniel Molitor", email = "molitdj97@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "pigar>=2.2.0",
+    "pygit2>=1.19.3",
+    "pyperclip>=1.11.0",
+    "python-dotenv>=1.2.2",
+]
+
+[project.scripts]
+tugboat-py = "tugboat:main"
+
+[build-system]
+requires = ["uv_build>=0.9.22,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tugboat"
+
+[dependency-groups]
+dev = [
+    "black>=26.5.1",
+]

tugboat_py-0.1.0/src/tugboat/__init__.py

@@ -0,0 +1,8 @@
+from .build import build
+from .create import create
+from .binderize import binderize
+
+# read version from installed package
+from importlib.metadata import version
+
+__version__ = version(__name__)

tugboat_py-0.1.0/src/tugboat/binderize.py

@@ -0,0 +1,100 @@
+from pathlib import Path
+import pyperclip
+from pygit2 import Repository
+import re
+
+BADGE_URL = "https://mybinder.org/badge_logo.svg"
+DEFAULT_IMAGE = "rocker/binder:4"
+
+
+def _use_badge(
+    label: str,
+    href: str,
+    image_url: str,
+    readme: str | Path = "README.md",
+    add_readme_badge: bool = True,
+) -> str:
+    readme = Path(readme)
+    badge = f"[![{label}]({image_url})]({href})"
+    start = "<!-- badges: start -->"
+    end = "<!-- badges: end -->"
+    instructions = f"{start}\n" f"{badge}\n" f"{end}"
+
+    # Copy instructions to the clipboard and also print them
+    def copy_instructions() -> None:
+        pyperclip.copy(instructions)
+        print("Add the following to your README.md file:\n\n" + instructions)
+        print("\nCopied to clipboard.")
+
+    # Determine whether to modify README.md or just return instructions
+    if not add_readme_badge:
+        return copy_instructions()
+    if not readme.exists():
+        return copy_instructions()
+    # Modify README.md
+    text = readme.read_text()
+    if badge in text:
+        print(f"Badge already exists in {readme}")
+        return badge
+    if start not in text or end not in text:
+        return copy_instructions()
+    before, rest = text.split(start, maxsplit=1)
+    badges, after = rest.split(end, maxsplit=1)
+    badges = badges.rstrip() + f"\n{badge}\n"
+    readme.write_text(f"{before}{start}{badges}{end}{after}")
+    print(f"Added badge to {readme}")
+    return badge
+
+
+def _binder_dockerfile() -> str:
+    dock = f"""FROM {DEFAULT_IMAGE}""" + """
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+COPY --chown=${NB_USER} . /home/rstudio
+WORKDIR /home/rstudio
+USER root
+RUN printf "RETICULATE_PYTHON_ENV=/home/rstudio/.venv\\nVIRTUAL_ENV=/home/rstudio/.venv\\n" >> /usr/local/lib/R/etc/Renviron.site
+USER ${NB_USER}
+RUN test -f pyproject.toml || uv init --app . || true
+RUN uv sync --all-groups --all-extras
+RUN uv add -r requirements-tugboat.txt"""
+    return dock
+
+
+def binderize(
+    project: Path | str = Path("."),
+    branch: str = "main",
+    urlpath: str = "rstudio",
+    add_readme_badge: bool = True,
+    overwrite: bool = True,
+    verbose: bool = False,
+) -> None:
+    # Create repo object and extract url, username, repo name, etc.
+    repo = Repository(project)
+    git_remote = repo.remotes["origin"].url
+    local_repo = Path(repo.workdir)
+    username_repo = re.sub(r".*github\.com[:/](.*)\.git$", r"\1", git_remote).split("/")
+    if git_remote.find("github.com") == -1:
+        raise ValueError("Only GitHub repositories are currently supported.")
+    # Generate Dockerfile
+    dock = _binder_dockerfile()
+    if verbose:
+        print(dock)
+    binder_dir = local_repo / ".binder"
+    if not binder_dir.is_dir():
+        binder_dir.mkdir()
+    dockerfile_path = binder_dir / "Dockerfile"
+    if overwrite:
+        dockerfile_path.write_text(dock)
+    # Construct Binder badge and insert into README (if possible)
+    binder_url = f"https://mybinder.org/v2/gh/{'/'.join(username_repo)}/{branch}?urlpath={urlpath}"
+    _use_badge(
+        label="Launch RStudio Binder",
+        href=binder_url,
+        image_url=BADGE_URL,
+        readme=local_repo / "README.md",
+        add_readme_badge=add_readme_badge,
+    )
+    # Give the user final instructions
+    print("Your repository has been configured for Binder.")
+    print("[x] Commit and push all changes")
+    print("[x] Launch Binder at: ", binder_url)

tugboat_py-0.1.0/src/tugboat/build.py

@@ -0,0 +1,109 @@
+from pathlib import Path
+import shutil
+import subprocess as sp
+import tempfile
+from typing import List
+
+from .utils import is_windows, stop_if_docker_not_installed
+
+
+def _copy_build_context_to_temp(build_context: str) -> str | None:
+    if not is_windows():
+        return None
+    tmp = tempfile.TemporaryDirectory()
+    tmp_path = Path(tmp.name)
+    build_context = Path(build_context)
+    for item in build_context.iterdir():
+        dest = tmp_path / item.name
+        if item.is_dir():
+            shutil.copytree(item, dest)
+        else:
+            shutil.copy2(item, dest)
+    return tmp.name
+
+
+def _build_image(
+    dockerfile: str,
+    platforms: List[str] | str,
+    repository: str,
+    tag: str,
+    build_args: List[str] | None,
+    build_context: str,
+    push: bool,
+    verbose: bool,
+) -> None:
+    tmp = _copy_build_context_to_temp(build_context)
+    if not isinstance(platforms, list):
+        platforms = [platforms]
+    try:
+        if tmp is not None:
+            build_context = tmp
+        exec_args = [
+            "docker",
+            "buildx",
+            "build",
+            "-f",
+            str(Path(dockerfile).resolve()),
+            "--platform",
+            ",".join(platforms),
+            "-t",
+            f"{repository}:{tag}",
+        ]
+        if build_args:
+            exec_args.extend(build_args)
+        exec_args.append(str(build_context))
+        if push:
+            exec_args.append("--push")
+        if verbose:
+            print("Building:")
+            print(" ".join(exec_args))
+        result = sp.run(exec_args)
+        if result.returncode != 0:
+            raise RuntimeError(f"Build failed with status: {result.returncode}")
+    finally:
+        if tmp is not None:
+            tmp.cleanup()
+
+
+def build(
+    dockerfile: str = Path(".") / "Dockerfile",
+    image_name: str = "tugboat",
+    tag: str = "latest",
+    platforms: List[str] | str = ["linux/amd64", "linux/arm64"],
+    build_args: List[str] | None = None,
+    build_context: str = str(Path(".").resolve()),
+    push: bool = False,
+    dh_username: str | None = None,
+    dh_password: str | None = None,
+    verbose: bool = False,
+) -> str:
+    """Build a Docker image from a Dockerfile"""
+    stop_if_docker_not_installed()
+    if push:
+        if dh_username is None or dh_password is None:
+            raise RuntimeError("Both `dh_username` and `dh_password` must be provided")
+        login_result = sp.run(
+            ["docker", "login", "-u", dh_username, "--password-stdin"],
+            input=dh_password,
+            text=True,
+            check=True,
+        )
+        if login_result.returncode != 0:
+            raise RuntimeError(
+                f"Docker login failed with status: {login_result.returncode}"
+            )
+    if dh_username is None:
+        repository = image_name
+    else:
+        repository = f"{dh_username}/{image_name}"
+    _build_image(
+        dockerfile=dockerfile,
+        platforms=platforms,
+        repository=repository,
+        tag=tag,
+        build_args=build_args,
+        build_context=build_context,
+        push=push,
+        verbose=verbose,
+    )
+    return f"{repository}:{tag}"

tugboat_py-0.1.0/src/tugboat/create.py

@@ -0,0 +1,61 @@
+import os
+from pathlib import Path
+import sys
+from typing import List
+
+from .utils import _generate
+
+PY_VERSION = f"{sys.version_info.major}.{sys.version_info.minor}"
+DEFAULT_IMAGE = f"python:{PY_VERSION}-slim"
+
+
+def _dockerfile(
+    project_name: str | None = None,
+    project: str = str(Path(".").resolve()),
+    FROM: str | None = None,
+) -> str:
+    if project_name is None:
+        project_dir = f"/{Path(project).name}"
+    else:
+        project_dir = f"/{project_name}"
+    if not FROM:
+        FROM = DEFAULT_IMAGE
+    dock = f"""FROM {FROM}
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+COPY . {project_dir}
+WORKDIR {project_dir}
+RUN test -f pyproject.toml || uv init --app . || true
+RUN uv sync --all-groups --all-extras
+RUN uv add -r requirements-tugboat.txt"""
+    return dock
+
+
+def _dockerignore(project: str, exclude: List[str] | str | None = None) -> None:
+    if not isinstance(exclude, List) and exclude:
+        exclude = [exclude]
+    elif not exclude:
+        exclude = []
+    exclude = list(set(exclude + ["Dockerfile", ".dockerignore", "**/.DS_Store"]))
+    dockerignore_path = str(Path(project) / ".dockerignore")
+    with open(dockerignore_path, "w") as path:
+        path.writelines(f"{item}\n" for item in exclude)
+
+
+def create(
+    project: str = str(Path(".").resolve()),
+    FROM: str | None = None,
+    exclude: List[str] | str | None = None,
+    verbose: bool = False,
+    **kwargs,
+) -> None:
+    project = os.path.abspath(project)
+    # Scan for dependencies and generate requirements.txt
+    _generate(project_path=project, **kwargs)
+    # Generate .dockerignore
+    _dockerignore(project=project, exclude=exclude)
+    # Generate Dockerfile
+    dock = _dockerfile(project=project, FROM=FROM)
+    if verbose:
+        print(dock)
+    dockerfile_path = Path(project) / "Dockerfile"
+    dockerfile_path.write_text(dock)

tugboat_py-0.1.0/src/tugboat/utils.py

@@ -0,0 +1,69 @@
+from concurrent.futures import ThreadPoolExecutor
+import os
+from pigar.dist import DEFAULT_PYPI_INDEX_URL
+from pigar.parser import DEFAULT_GLOB_EXCLUDE_PATTERNS
+from pigar.__main__ import generate as generate_cli
+import platform
+import shutil
+from typing import List
+
+
+class DockerNotFoundError(Exception):
+    pass
+
+
+def _run_in_thread(fn, *args, **kwargs):
+    """Execute a function in a separate thread"""
+    with ThreadPoolExecutor(max_workers=1) as executor:
+        return executor.submit(fn, *args, **kwargs).result()
+
+
+def is_windows() -> bool:
+    return platform.system() == "Windows"
+
+
+def stop_if_docker_not_installed() -> None:
+    """Ensure Docker is installed"""
+    if not shutil.which("docker"):
+        raise DockerNotFoundError(
+            "Visit https://docs.docker.com/get-docker/ to get started!"
+        )
+
+
+# `generate` is a Click (https://click.palletsprojects.com/en/stable/)
+# cli object. The underlying `generate` function is stored at `generate.callback`
+def _generate(
+    requirement_file: str = "requirements-tugboat.txt",
+    with_referenced_comments: bool = False,
+    comparison_specifier: str = list(("==", "~=", ">=", ">", "-"))[4],
+    show_differences: bool = True,
+    visit_doc_string: bool = False,
+    exclude_glob: List[str] = list(DEFAULT_GLOB_EXCLUDE_PATTERNS),
+    follow_symbolic_links: bool = True,
+    dry_run: bool = False,
+    index_url: str = DEFAULT_PYPI_INDEX_URL,
+    include_prereleases: bool = False,
+    question_answer: str = "yes",
+    auto_select: bool = False,
+    experimental_features: List[str] = [],
+    project_path: str = os.curdir,
+) -> None:
+    """Recreate an internal API for pigar's `generate` CLI function"""
+    kwargs = dict(
+        requirement_file=requirement_file,
+        with_referenced_comments=with_referenced_comments,
+        comparison_specifier=comparison_specifier,
+        show_differences=show_differences,
+        visit_doc_string=visit_doc_string,
+        exclude_glob=exclude_glob,
+        follow_symbolic_links=follow_symbolic_links,
+        dry_run=dry_run,
+        index_url=index_url,
+        include_prereleases=include_prereleases,
+        question_answer=question_answer,
+        auto_select=auto_select,
+        experimental_features=experimental_features,
+        project_path=project_path,
+    )
+    # Run in separate thread so this does NOT fail when run in Jupyter environment
+    _run_in_thread(generate_cli.callback, **kwargs)