Metadata-Version: 2.1
Name: cs.dockerutils
Version: 20231202
Summary: Docker related utilities.
Home-page: https://bitbucket.org/cameron_simpson/css/commits/all
Author: Cameron Simpson
Author-email: Cameron Simpson <cs@cskk.id.au>
License: GNU General Public License v3 or later (GPLv3+)
Project-URL: URL, https://bitbucket.org/cameron_simpson/css/commits/all
Keywords: python3
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+)
Description-Content-Type: text/markdown
Requires-Dist: cs.cmdutils>=20231129
Requires-Dist: cs.context>=20230331
Requires-Dist: cs.fs>=20231129
Requires-Dist: cs.pfx>=20230604
Requires-Dist: cs.psutils>=20231129
Requires-Dist: ffmpeg-python
Requires-Dist: typeguard

Docker related utilities.

*Latest release 20231202*:
Initial PyPI release.

## Function `default_docker_command()`

pylint: disable=unnecessary-lambda-assignment

## Function `default_docker_compose_command()`

pylint: disable=unnecessary-lambda-assignment

## Function `default_docker_compose_config()`

pylint: disable=unnecessary-lambda-assignment

## Function `docker(*dk_argv, exe=None, doit=True, quiet=True) -> subprocess.CompletedProcess`

Invoke `docker` with `dk_argv`.

## Function `docker_compose(*dc_argv, exe=None, config=None, doit=True, quiet=True) -> subprocess.CompletedProcess`

Invoke `docker-compose` with `dc_argv`.

## 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.

## Class `DockerUtilCommand(cs.cmdutils.BaseCommand)`

A command line mode for working with Docker et al.

Command line usage:

    Usage: dockerutil [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 [-l] [subcommand-names...]
          Print the full help for the named subcommands,
          or for all subcommands if no names are specified.
          -l  Long help even if no subcommand-names provided.
        ps
          Show the running docker containers.
        run [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)
          -I inputpath dockerpath
              Mount inputpath as /input/dockerpath
          --root
              Do not switch to the current effective uid:gid inside
              the container.
          -U  Update the local copy of image before running.
          Other options are passed to "docker run".
        shell
          Run a command prompt via cmd.Cmd using this command's subcommands.

## Class `DockerUtilCommandOptions(cs.cmdutils.BaseCommandOptions)`

Command line options for `DockerUtilCommand`.

## Function `main(argv=None, **run_kw)`

Invoke the `DockerUtilCommand` with `argv`.

## Function `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 20231202*:
Initial PyPI release.
