Added the "insert" command and associated functionality and tests. (#5)

* Added the "insert" command and associated functionality and tests.

* Removed an unused line from test_docker_insert

* Renamed the default directory copy image.

* Added a custom target path to the  copydir command

~ insert command changed to "copydir"
~ Added the custom target path option to the command
~ Changed some wording and naming conventions, added some descriptive comments

* Updated the comment on init_build_parsers to match the naming change

* Added CLI no-cache option for get_archive and copy_dir

~ Also changed references to "lowest level directory" to instad say "base name"

* Last bits of documentation change

---------

Co-authored-by: tyler-g-hudson <[email protected]>

Author: Tyler-g-hudson

docker_cli/_docker_insert.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import os
+from textwrap import dedent
+
+
+def insert_dir_dockerfile(
+    base: str,
+    target_dir: str | os.PathLike[str],
+    source_dir: str | os.PathLike[str] = ".",
+) -> str:
+    """
+    Returns a Dockerfile-formatted string which inserts a given directory on the
+    host machine into the image.
+
+    This Dockerfile also changes the working directory to the copied directory.
+
+    Parameters
+    ----------
+    base : str
+        The base image tag.
+    target_dir : str | os.PathLike[str]
+        The path in the image filesystem to copy to.
+    source_dir : str | os.PathLike[str]
+        The local directory to be copied onto the image, relative to the build context.
+         Defaults to "."
+
+    Returns
+    -------
+    dockerfile : str
+        The generated Dockerfile.
+    """
+    # Arguments to the COPY command are devolved into this variable in order to keep the
+    # code lines brief.
+    copy_args = "--chown=$DEFAULT_GID:$DEFAULT_UID --chmod=755"
+
+    return dedent(
+        f"""
+            FROM {base}
+
+            COPY {copy_args} {source_dir} {target_dir}
+
+            WORKDIR {target_dir}
+            USER $DEFAULT_USER
+        """
+    ).strip()

docker_cli/cli/build_commands.py

@@ -2,7 +2,7 @@
 from pathlib import Path
 from typing import List
 
-from ..commands import get_archive
+from ..commands import copy_dir, get_archive
 from ._utils import add_tag_argument, help_formatter
 
 
@@ -13,7 +13,8 @@ def init_build_parsers(subparsers: argparse._SubParsersAction) -> None:
     The build commands are the group of commands to be completed after the CUDA and
     conda environments have been installed to the image, with the purpose of acquiring
     and building the ISCE3 repository and any further repositories.
-    These commands consist of the "get-archive" command, and more are being added.
+    These commands consist of the "get-archive" and "copydir" commands, and more are
+    being added.
 
     Parameters
     -----------
@@ -54,13 +55,48 @@ def init_build_parsers(subparsers: argparse._SubParsersAction) -> None:
         formatter_class=help_formatter,
     )
     add_tag_argument(parser=archive_parser, default="repo")
+    archive_parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help="Run Docker build with no cache if used.",
+    )
+
+    copy_dir_parser = subparsers.add_parser(
+        "copydir",
+        parents=[setup_parse],
+        help="Insert the contents of a directory at the given path.",
+        formatter_class=help_formatter,
+    )
+    add_tag_argument(parser=copy_dir_parser, default="dir-copy")
+    copy_dir_parser.add_argument(
+        "--directory",
+        "-d",
+        type=Path,
+        required=True,
+        help="The directory to be copied to the image.",
+    )
+    copy_dir_parser.add_argument(
+        "--target-path",
+        "-p",
+        type=Path,
+        default=None,
+        help="The path on the image to copy the source directory to. If not given, "
+        "the base name of the path given by the directory argument will be used.",
+    )
+    copy_dir_parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help="Run Docker build with no cache if used.",
+    )
 
 
 def build_command_names() -> List[str]:
     """Returns a list of all build command names."""
-    return ["get-archive"]
+    return ["get-archive", "copydir"]
 
 
 def run_build(args: argparse.Namespace, command: str) -> None:
     if command == "get-archive":
         get_archive(**vars(args))
+    if command == "copydir":
+        copy_dir(**vars(args))

docker_cli/commands.py

@@ -6,6 +6,7 @@
 from typing import Iterable, List
 
 from ._docker_git import git_extract_dockerfile
+from ._docker_insert import insert_dir_dockerfile
 from ._docker_mamba import mamba_lockfile_command
 from ._image import Image
 from ._url_reader import URLReader
@@ -23,6 +24,7 @@ def get_archive(
     archive_url: str,
     directory: os.PathLike[str],
     url_reader: URLReader | None = None,
+    no_cache: bool = False,
 ):
     """
     Builds a docker image containing the requested Git archive.
@@ -43,6 +45,8 @@ def get_archive(
     url_reader : URLReader | None, optional
         If given, will use the given URL reader to acquire the Git archive. If None,
         will check the base image and use whichever one it can find. Defaults to None.
+    no_cache : bool, optional
+        Run Docker build with no cache if True. Defaults to False.
 
     Returns
     -------
@@ -63,7 +67,86 @@ def get_archive(
         url_reader=url_reader,
     )
 
-    return Image.build(tag=img_tag, dockerfile_string=dockerfile, no_cache=True)
+    return Image.build(tag=img_tag, dockerfile_string=dockerfile, no_cache=no_cache)
+
+
+def copy_dir(
+    tag: str,
+    base: str,
+    directory: str | os.PathLike[str],
+    target_path: str | os.PathLike[str] | None = None,
+    no_cache: bool = False,
+):
+    """
+    Builds a Docker image with the contents of the given directory copied onto it.
+
+    The directory path on the image has the same name as the topmost directory
+    of the given path. e.g. giving path "/tmp/dir/subdir" will result in the contents of
+    this path being saved in "/subdir" on the generated image.
+
+    This Dockerfile also changes the working directory of the image to the copied
+    directory.
+
+    Parameters
+    ----------
+    tag : str
+        The image tag.
+    base : str
+        The base image tag.
+    directory : path-like
+        The directory to be copied.
+    target_path : path-like or None
+        The directory to copy to, on the image, or None. If given, the contents of the
+        source directory will be copied to the given path. If None, the target path will
+        default to the base name of the path given by the `directory` argument.
+        Defaults to None.
+    no_cache : bool, optional
+        Run Docker build with no cache if True. Defaults to False.
+
+    Returns
+    -------
+    Image
+        The generated image.
+    """
+
+    prefix = universal_tag_prefix()
+    img_tag = tag if tag.startswith(prefix) else f"{prefix}-{tag}"
+
+    dir_str = os.fspath(directory)
+
+    # The absolute path of the given directory will be the build context.
+    # This is necessary because otherwise docker may be unable to find the directory if
+    # the build context is at the current working directory.
+    path_absolute = os.path.abspath(dir_str)
+
+    if target_path is None:
+        # No argument was passed to target_path, so the lowest-level directory of the
+        # input path will be the name of the directory in the image.
+        if os.path.isdir(dir_str):
+            target_dir = os.path.basename(path_absolute)
+        else:
+            raise ValueError(f"{dir_str} is not a valid directory on this machine.")
+    else:
+        target_dir = os.fspath(target_path)
+
+    # Generate the dockerfile. The source directory will be "." since the build context
+    # will be at the source path when the image is built.
+    dockerfile: str = insert_dir_dockerfile(
+        base=base,
+        target_dir=target_dir,
+        source_dir=".",
+    )
+
+    # Build the image with the context at the absolute path of the given path. This
+    # allows a directory to be copied from anywhere that is visible to this user on
+    # the machine, whereas a context at "." would be unable to see any directory that is
+    # not downstream of the working directory from which the program is called.
+    return Image.build(
+        tag=img_tag,
+        context=path_absolute,
+        dockerfile_string=dockerfile,
+        no_cache=no_cache,
+    )
 
 
 def dropin(tag: str) -> None:

pytest.ini

@@ -2,8 +2,9 @@
 log_cli = 0
 log_cli_level = WARNING
 markers =
+    build: mark a test as a build command test.
+    cuda: mark a test as a CUDA test.
+    dockerfiles: mark a test as a dockerfile test.
+    git: mark a test as a Git test.
     images: mark a test as an image test.
-    dockerfiles: mark a test as a dockerfile test
-    mamba: mark a test as a mamba test
-    cuda: mark a test as a CUDA test
-    git: mark a test as a Git test
+    mamba: mark a test as a mamba test.

test/dummy_dir/dummy_file.txt

@@ -1,5 +1,4 @@
 from pathlib import Path
-from subprocess import PIPE
 from typing import Any, Tuple
 
 from pytest import mark
@@ -13,8 +12,9 @@
 
 @mark.dockerfiles
 @mark.git
+@mark.build
 def test_git_dockerfile():
-    """Performs a rough validity check of the Git dockerfile"""
+    """Performs a rough validity check of the Git Dockerfile."""
     for supported_reader in get_supported_url_readers():
         url_reader = get_url_reader(supported_reader)
         dockerfile = git_extract_dockerfile(
@@ -28,11 +28,13 @@ def test_git_dockerfile():
 
 @mark.images
 @mark.git
+@mark.build
 def test_docker_git(
     init_tag: str,
     init_image: Image,  # type: ignore
     base_properties: Tuple[Any, URLReader],
 ):
+    """Tests the image generated by the Git Dockerfile for a given archive."""
     # This is a basic github archive from octocat's test-repo1 archive.
     # If this test fails, one thing to do is check that this archive exists.
     archive = "https://github.com/octocat/test-repo1/archive/refs/tags/1.0.tar.gz"

test/dummy_dir/dummy_subdir/dummy_file.txt

@@ -0,0 +1,39 @@
+from pytest import mark
+
+from docker_cli._docker_insert import insert_dir_dockerfile
+from docker_cli._image import Image
+
+from .utils import generate_tag, rough_dockerfile_validity_check
+
+
+@mark.dockerfiles
+@mark.build
+def test_insert_dockerfile():
+    """Performs a rough validity check of the directory insert Dockerfile."""
+    dockerfile = insert_dir_dockerfile(
+        base="base",
+        target_dir=".",
+    )
+    rough_dockerfile_validity_check(dockerfile=dockerfile)
+
+
+@mark.images
+@mark.build
+def test_docker_insert(base_tag: str):
+    """Tests the image generated by the directory insert Dockerfile."""
+    img_tag = generate_tag("insert-dir")
+
+    # Insert the contents of the dummy directory inside of this test directory into
+    # the image.
+    dockerfile = insert_dir_dockerfile(
+        base=base_tag,
+        source_dir="dummy_dir",
+        target_dir="/dummy_dir",
+    )
+
+    image = Image.build(tag=img_tag, dockerfile_string=dockerfile, no_cache=True)
+
+    # Test that the files in the dummy directory and subdirectories are present on the
+    # image.
+    image.run("test -f /dummy_dir/dummy_file.txt")
+    image.run("test -f /dummy_dir/dummy_subdir/dummy_file.txt")