Metadata-Version: 2.4
Name: cs-dockerutils
Version: 20260531
Summary: Docker related utilities.
Keywords: python3
Author-email: Cameron Simpson <cs@cskk.id.au>
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Dist: cs.cmdutils>=20260531
Requires-Dist: cs.context>=20250528
Requires-Dist: cs.pfx>=20250914
Requires-Dist: cs.psutils>=20260531
Requires-Dist: typeguard
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/dockerutils.py

Docker related utilities.

*Latest release 20260531*:
* DockerUtilCommand.cmd_run: give a more informative name to the temporary directory for mounts.
* DockerRun: build the docker command more nicely, call run(...,fold=True) for more readable tracing.
* DockerRun: add .docker_exe as a field, run as the current user by default, drop .as_root and replace with .user, honour $DK_COMMAND as the default docker command name, adjust option usage on that basis.

Short summary:
* `docker`: Invoke `docker` with `dk_argv`.
* `docker_compose`: Invoke `docker-compose` with `dc_argv`.
* `DockerRun`: A `DockerRun` specifies how to prepare docker to execute a command.
* `DockerUtilCommand`: A command line mode for working with Docker et al.
* `DockerUtilCommandOptions`: Command line options for `DockerUtilCommand`.
* `main`: Invoke the `DockerUtilCommand` with `argv`.
* `mount_escape`: Escape the strings in `args` for us in the `docker run --mount` option.

Module contents:
- <a name="default_docker_command"></a>`default_docker_command()`: pylint: disable=unnecessary-lambda-assignment
- <a name="default_docker_compose_command"></a>`default_docker_compose_command()`: pylint: disable=unnecessary-lambda-assignment
- <a name="default_docker_compose_config"></a>`default_docker_compose_config()`: pylint: disable=unnecessary-lambda-assignment
- <a name="docker"></a>`docker(*dk_argv, exe=None, doit=True, quiet=True) -> subprocess.CompletedProcess`: Invoke `docker` with `dk_argv`.
- <a name="docker_compose"></a>`docker_compose(*dc_argv, exe=None, config=None, doit=True, quiet=True) -> subprocess.CompletedProcess`: Invoke `docker-compose` with `dc_argv`.
- <a name="DockerRun"></a>`class DockerRun`: A `DockerRun` specifies how to prepare docker to execute a command.

  This is a generic wrapper for invoking a docker image and
  internal executable to process data from the host system,
  essentially a flexible and cleaned up version of the wrappers
  used to invoke things like the `linuxserver:*` utility docker
  images.

  Input paths for the executable will be presented in a read
  only directory, by default `/input' inside the container.

  An output directory (default '.', the current durectory) will
  be mounted read/write inside the container, by default `/output`
  inside the container.

  _Unlike_ a lot of docker setups, the default mode runs as the
  invoking user's UID/GID inside the container and expects the
  `s6-setuidgid` utility to be present in the image.

  See the `ffmpeg_docker` function from `cs.ffmpegutils` for
  an example invocation of this class.

*`DockerRun.add_input(self, infspath: str) -> str`*:
Add a host filesystem path to the `input_map`
and return the corresponding container filesystem path.

*`DockerRun.add_output(self, outfspath: str) -> str`*:
Add a host filesystem path to the `output_map`
and return the corresponding container filesystem path.

*`DockerRun.popopts(self, argv: List[str]) -> None`*:
Pop options from the list `argv`.

The command's working directory will be /output.
-i inputpath
    Mount inputpath as /input/basename(inputpath)
-U  Update the local copy of image before running.
Other options are passed to "docker run".

*`DockerRun.run(self, *argv, doit=None, quiet=None)`*:
Run a command via `docker run`.
Return the `CompletedProcess` result or `None` if `doit` is false.
- <a name="DockerUtilCommand"></a>`class DockerUtilCommand(cs.cmdutils.BaseCommand)`: A command line mode for working with Docker et al.

  Usage summary:

      Usage: dockerutil [common-options...] [options...] [@container] subcommand...
        -f docker-compose.yml
          Specify ['docker', 'compose'] YAML file.
          Default: 'docker-compose.yml', overridden by $DK_COMPOSE_YML
        @container  Specify a target container.
        Subcommands:
          help [common-options...] [-l] [-s] [subcommand-names...]
            Print help for subcommands.
            This outputs the full help for the named subcommands,
            or the short help for all subcommands if no names are specified.
            Options:
              -l  Long listing.
              -r  Recurse into subcommands.
              -s  Short listing.
          info [common-options...] [field-names...]
            Recite general information.
            Explicit field names may be provided to override the default listing.
          ps [common-options...]
            Show the running docker containers.
          repl [common-options...]
            Run a REPL (Read Evaluate Print Loop), an interactive Python prompt.
            Options:
              --banner banner  Banner.
          run [common-options...] [options] image [command] [arg...]
            Invoke command in an instance of image.
            A read only directory for input data will be present as /input.
            A read/write directory for output data will be present at /output.
            The command's working directory will be /output.
            -i inputpath
                Mount inputpath as /input/basename(inputpath)
            -U  Update the local copy of image before running.
            Other options are passed to "docker run".
          shell [common-options...]
            Run a command prompt via cmd.Cmd using this command's subcommands.

*`DockerUtilCommand.Options`*

*`DockerUtilCommand.apply_preargv(self, argv)`*:
Consume a leading @container_name if present.

*`DockerUtilCommand.cmd_ps(self, argv)`*:
Usage: {cmd}
Show the running docker containers.

*`DockerUtilCommand.cmd_run(self, argv)`*:
Usage: {cmd} [options] image [command] [arg...]
Invoke command in an instance of image.
A read only directory for input data will be present as /input.
A read/write directory for output data will be present at /output.
The command's working directory will be /output.
-i inputpath
    Mount inputpath as /input/basename(inputpath)
-U  Update the local copy of image before running.
Other options are passed to "docker run".

*`DockerUtilCommand.docker(self, *dk_argv) -> subprocess.CompletedProcess`*:
Invoke `docker`.

*`DockerUtilCommand.docker_compose(self, *dc_argv) -> subprocess.CompletedProcess`*:
Invoke `docker-compose`.
- <a name="DockerUtilCommandOptions"></a>`class DockerUtilCommandOptions(cs.cmdutils.BaseCommandOptions)`: Command line options for `DockerUtilCommand`.
- <a name="main"></a>`main(argv=None, **run_kw)`: Invoke the `DockerUtilCommand` with `argv`.
- <a name="mount_escape"></a>`mount_escape(*args) -> str`: Escape the strings in `args` for us in the `docker run --mount` option.

  Apparently the arguments to `docker run --mount` are in fact
  a CSV data line.
  (Of course you need to find this allusion in the bug tracker,
  heaven forfend that the docs actually detail this kind of
  thing.)

  Rather that try to enumerate what needs escaping, here we use
  the `csv` module to escape using the default "excel" dialect.

# Release Log



*Release 20260531*:
* DockerUtilCommand.cmd_run: give a more informative name to the temporary directory for mounts.
* DockerRun: build the docker command more nicely, call run(...,fold=True) for more readable tracing.
* DockerRun: add .docker_exe as a field, run as the current user by default, drop .as_root and replace with .user, honour $DK_COMMAND as the default docker command name, adjust option usage on that basis.

*Release 20240519*:
DockerRun.outputpath: rename to output_hostdir, less confusing.

*Release 20240305*:
DockerRun: new "network" attribute, default "none", for the --network CLI option.

*Release 20240201*:
* mount_escape: strip trailing carriage return also.
* DockerRun: new output_map attribute much like input_map; also mount existing outputs within the container.

*Release 20231202*:
Initial PyPI release.
