Docker related utilities.
*Latest release 20240519*:
DockerRun.outputpath: rename to output_hostdir, less confusing.
## 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.
*Method `DockerRun.add_input(self, infspath: str) -> str`*:
Add a host filesystem path to the `input_map`
and return the corresponding container filesystem path.
*Method `DockerRun.add_output(self, outfspath: str) -> str`*:
Add a host filesystem path to the `output_map`
and return the corresponding container filesystem path.
*Method `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)
--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".
*Method `DockerRun.run(self, *argv, doit=None, quiet=None, docker_exe=None)`*:
Run a command via `docker run`.
Return the `CompletedProcess` result or `None` if `doit` is false.
## Class `DockerUtilCommand(cs.cmdutils.BaseCommand)`
A command line mode for working with Docker et al.
Command line implementation.
Usage summary:
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 help for subcommands.
This outputs the full help for the named subcommands,
or the short help 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)
--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.
*`DockerUtilCommand.Options`*
*Method `DockerUtilCommand.apply_preargv(self, argv)`*:
Consume a leading @container_name if present.
*Method `DockerUtilCommand.cmd_ps(self, argv)`*:
Usage: {cmd}
Show the running docker containers.
*Method `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)
--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".
*Method `DockerUtilCommand.docker(self, *dk_argv) -> subprocess.CompletedProcess`*:
Invoke `docker`.
*Method `DockerUtilCommand.docker_compose(self, *dc_argv) -> subprocess.CompletedProcess`*:
Invoke `docker-compose`.
## 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 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "cs.dockerutils",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python3",
"author": null,
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/c1/ae/72d913212eaf4a85f95c017ad1b659a6d66e1a1fde9bd139e2a7bed36c56/cs.dockerutils-20240519.tar.gz",
"platform": null,
"description": "Docker related utilities.\n\n*Latest release 20240519*:\nDockerRun.outputpath: rename to output_hostdir, less confusing.\n\n## Function `default_docker_command()`\n\npylint: disable=unnecessary-lambda-assignment\n\n## Function `default_docker_compose_command()`\n\npylint: disable=unnecessary-lambda-assignment\n\n## Function `default_docker_compose_config()`\n\npylint: disable=unnecessary-lambda-assignment\n\n## Function `docker(*dk_argv, exe=None, doit=True, quiet=True) -> subprocess.CompletedProcess`\n\nInvoke `docker` with `dk_argv`.\n\n## Function `docker_compose(*dc_argv, exe=None, config=None, doit=True, quiet=True) -> subprocess.CompletedProcess`\n\nInvoke `docker-compose` with `dc_argv`.\n\n## Class `DockerRun`\n\nA `DockerRun` specifies how to prepare docker to execute a command.\n\nThis is a generic wrapper for invoking a docker image and\ninternal executable to process data from the host system,\nessentially a flexible and cleaned up version of the wrappers\nused to invoke things like the `linuxserver:*` utility docker\nimages.\n\nInput paths for the executable will be presented in a read\nonly directory, by default `/input' inside the container.\n\nAn output directory (default '.', the current durectory) will\nbe mounted read/write inside the container, by default `/output`\ninside the container.\n\n_Unlike_ a lot of docker setups, the default mode runs as the\ninvoking user's UID/GID inside the container and expects the\n`s6-setuidgid` utility to be present in the image.\n\nSee the `ffmpeg_docker` function from `cs.ffmpegutils` for\nan example invocation of this class.\n\n*Method `DockerRun.add_input(self, infspath: str) -> str`*:\nAdd a host filesystem path to the `input_map`\nand return the corresponding container filesystem path.\n\n*Method `DockerRun.add_output(self, outfspath: str) -> str`*:\nAdd a host filesystem path to the `output_map`\nand return the corresponding container filesystem path.\n\n*Method `DockerRun.popopts(self, argv: List[str]) -> None`*:\nPop options from the list `argv`.\n\nThe command's working directory will be /output.\n-i inputpath\n Mount inputpath as /input/basename(inputpath)\n--root\n Do not switch to the current effective uid:gid inside\n the container.\n-U Update the local copy of image before running.\nOther options are passed to \"docker run\".\n\n*Method `DockerRun.run(self, *argv, doit=None, quiet=None, docker_exe=None)`*:\nRun a command via `docker run`.\nReturn the `CompletedProcess` result or `None` if `doit` is false.\n\n## Class `DockerUtilCommand(cs.cmdutils.BaseCommand)`\n\nA command line mode for working with Docker et al.\n\nCommand line implementation.\n\nUsage summary:\n\n Usage: dockerutil [options...] [@container] subcommand...\n -f docker-compose.yml\n Specify ['docker', 'compose'] YAML file.\n Default: 'docker-compose.yml', overridden by $DK_COMPOSE_YML\n @container Specify a target container.\n\n Subcommands:\n help [-l] [subcommand-names...]\n Print help for subcommands.\n This outputs the full help for the named subcommands,\n or the short help for all subcommands if no names are specified.\n -l Long help even if no subcommand-names provided.\n ps\n Show the running docker containers.\n run [options] image [command] [arg...]\n Invoke command in an instance of image.\n A read only directory for input data will be present as /input.\n A read/write directory for output data will be present at /output.\n The command's working directory will be /output.\n -i inputpath\n Mount inputpath as /input/basename(inputpath)\n --root\n Do not switch to the current effective uid:gid inside\n the container.\n -U Update the local copy of image before running.\n Other options are passed to \"docker run\".\n shell\n Run a command prompt via cmd.Cmd using this command's subcommands.\n\n*`DockerUtilCommand.Options`*\n\n*Method `DockerUtilCommand.apply_preargv(self, argv)`*:\nConsume a leading @container_name if present.\n\n*Method `DockerUtilCommand.cmd_ps(self, argv)`*:\nUsage: {cmd}\nShow the running docker containers.\n\n*Method `DockerUtilCommand.cmd_run(self, argv)`*:\nUsage: {cmd} [options] image [command] [arg...]\nInvoke command in an instance of image.\nA read only directory for input data will be present as /input.\nA read/write directory for output data will be present at /output.\nThe command's working directory will be /output.\n-i inputpath\n Mount inputpath as /input/basename(inputpath)\n--root\n Do not switch to the current effective uid:gid inside\n the container.\n-U Update the local copy of image before running.\nOther options are passed to \"docker run\".\n\n*Method `DockerUtilCommand.docker(self, *dk_argv) -> subprocess.CompletedProcess`*:\nInvoke `docker`.\n\n*Method `DockerUtilCommand.docker_compose(self, *dc_argv) -> subprocess.CompletedProcess`*:\nInvoke `docker-compose`.\n\n## Class `DockerUtilCommandOptions(cs.cmdutils.BaseCommandOptions)`\n\nCommand line options for `DockerUtilCommand`.\n\n## Function `main(argv=None, **run_kw)`\n\nInvoke the `DockerUtilCommand` with `argv`.\n\n## Function `mount_escape(*args) -> str`\n\nEscape the strings in `args` for us in the `docker run --mount` option.\n\nApparently the arguments to `docker run --mount` are in fact\na CSV data line.\n(Of course you need to find this allusion in the bug tracker,\nheaven forfend that the docs actually detail this kind of\nthing.)\n\nRather that try to enumerate what needs escaping, here we use\nthe `csv` module to escape using the default \"excel\" dialect.\n\n# Release Log\n\n\n\n*Release 20240519*:\nDockerRun.outputpath: rename to output_hostdir, less confusing.\n\n*Release 20240305*:\nDockerRun: new \"network\" attribute, default \"none\", for the --network CLI option.\n\n*Release 20240201*:\n* mount_escape: strip trailing carriage return also.\n* DockerRun: new output_map attribute much like input_map; also mount existing outputs within the container.\n\n*Release 20231202*:\nInitial PyPI release.\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Docker related utilities.",
"version": "20240519",
"project_urls": {
"URL": "https://bitbucket.org/cameron_simpson/css/commits/all"
},
"split_keywords": [
"python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3435eebb00959cbe34c7c0637d86cc2540eeefae451189302cc02e8c8828b9c5",
"md5": "c58a1c9304704a8e5e41cec72bdac162",
"sha256": "086f6d86728c361ceef1c7db043426bb0241dc7a9dcbaa1419c7659e2e5c9c48"
},
"downloads": -1,
"filename": "cs.dockerutils-20240519-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c58a1c9304704a8e5e41cec72bdac162",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7637,
"upload_time": "2024-05-19T02:30:40",
"upload_time_iso_8601": "2024-05-19T02:30:40.642057Z",
"url": "https://files.pythonhosted.org/packages/34/35/eebb00959cbe34c7c0637d86cc2540eeefae451189302cc02e8c8828b9c5/cs.dockerutils-20240519-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c1ae72d913212eaf4a85f95c017ad1b659a6d66e1a1fde9bd139e2a7bed36c56",
"md5": "678b7c469e100f1cf7a14117ea5b9f12",
"sha256": "01fb0423f3d2ee0d1e37d0605a3ca703e681cb0649201abdebd72b788520b812"
},
"downloads": -1,
"filename": "cs.dockerutils-20240519.tar.gz",
"has_sig": false,
"md5_digest": "678b7c469e100f1cf7a14117ea5b9f12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7231,
"upload_time": "2024-05-19T02:30:43",
"upload_time_iso_8601": "2024-05-19T02:30:43.399626Z",
"url": "https://files.pythonhosted.org/packages/c1/ae/72d913212eaf4a85f95c017ad1b659a6d66e1a1fde9bd139e2a7bed36c56/cs.dockerutils-20240519.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-19 02:30:43",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "cameron_simpson",
"bitbucket_project": "css",
"lcname": "cs.dockerutils"
}
JSON