dsco.commands package¶

Submodules¶

dsco.commands.build module¶

Build a container image

dsco build creates images by running docker-compose from the project root directory. By default dsco build will build the dev container.

Options

-- dev
-- prod
-- all
-- debug

The dev container will be built when:

-- dev == True
-- all == True
no flags are given

The prod container will be built when:

-- prod == True
-- all == True

The debug container will be built when:

-- debug == True
-- all == True

dsco.commands.build.add_dispatch(dispatcher)¶

dsco.commands.build.add_subparser(subparsers)¶

dsco.commands.code module¶

code: launch vs-code insiders with the appropriate environment

‘dsco code’ will launch vs-code locally. From there you can attach: to a locally running container.
‘dsco code -r [remote machine]’ or ‘dsco code –remote [remote machine]’: will launch vs-code with the appropriate environment variables to connect to the remote machine. You should then be able to connect to containers running there.

dsco.commands.code.add_dispatch(dispatcher)¶

dsco.commands.code.add_subparser(subparsers)¶

dsco.commands.code.run_cmd(args, conf)¶

dsco.commands.documentation module¶

reports: view and update files created in docs/documentation

Uses sphinx to (re)generate the documentation created in docs/documentation. This creates static html that can be viewed through the containers web page or github pages.

Currently this only targets the dev container.

Usage:: ‘dsco documentation’: open a webbrowser on localhost/documentation/ ‘dsco documentation [-g, –generate]’: update documentation

dsco.commands.documentation.add_dispatch(dispatcher)¶

dsco.commands.documentation.add_subparser(subparsers)¶

dsco.commands.documentation.run_cmd(args, conf)¶

dsco.commands.go module¶

go: A quickstart command to build a container and open a browser

‘dsco go’ is a quickstart method to create a container and open the web page interface to the container.

Options: –dev: dev container –prod: prod container –debug: debug container (unlikely to have a running server)

Options are cumulative, meaning –dev –prod will launch and open both the dev and prod containers.

dsco.commands.go.add_dispatch(dispatcher)¶

dsco.commands.go.add_subparser(subparsers)¶

dsco.commands.init module¶

This is the init parser

Use this to start a project. Uses the cookiecutter to create a project structure.

dsco.commands.init.add_dispatch(dispatcher)¶

dsco.commands.init.add_subparser(subparsers)¶

dsco.commands.init.run_cmd(args, conf)¶

dsco.commands.ls module¶

ls: information about images and containers

Use ‘dsco ls’ to get information about images and containers running on your localhost. Use ‘dsco ls -r’ to add information about machines listed in $HOME/.dsco/settings.json

class dsco.commands.ls.Colors¶

Bases: object

Define colors and methods to apply formatting to strings

Use the methods to apply formatting to the specified string type.

Methods: container (str): Add container formatting to input string. host (str): Add host formatting to input string. header (str): Add header formatting to input string.
Example: header = Colors.header(header_string) print(header)

BOLD = '\x1b[1m'¶

ENDC = '\x1b[0m'¶

FAIL = '\x1b[91m'¶

HEADER = '\x1b[95m'¶

OKBLUE = '\x1b[94m'¶

OKGREEN = '\x1b[92m'¶

REVERSED = '\x1b[7m'¶

UNDERLINE = '\x1b[4m'¶

WARNING = '\x1b[92m'¶

classmethod container(print_string)¶

classmethod header(print_string)¶

classmethod host(print_string)¶

class dsco.commands.ls.Container(properties, host)¶

Bases: object

Representation of a Docker container

name¶

Container name

Type: str

image¶

Image ID.

Type: str

properties¶

image (str): Image ID.
id (str): Container id.
name (str): Container name.
status (str): Container status.
created (str): Time when the container was created.
size (str): Size of container.
port (str): Exposed ports.

host¶

A reference to the container’s host.

Type: Host

inspect_dict¶

Information from docker inspect.

Type: dict

link¶

link to web server of container.

Type: str

image_id¶

full id of parent image.

Type: str

class dsco.commands.ls.Docker¶

Bases: object

Encapsulate all the interactions with docker

Attributes

images_docker_cmd (str): The ‘docker images’ command run to get: information about the docker images.
ps_docker_cmd (str): The ‘docker ps’ command run to get: information about the docker containers.

Methods

run_docker_cmd (cmd, env): Convenience function to run: docker commands.
images (Host): Return information on all docker images on the: given host.
ps (Container): Return information on all docker containers on: the given host.
inspect_container (Container): Return detailed information on: the given container.

classmethod images(host)¶

Get a list of image properties on the specified host

Parameters

host (Host) – A host object with the attribute “docker_env”.

Returns

A list containing a dictionary for: each image on the host. The dictionary is keyed from the name property of the _image_format_list.

Return type

image_list (list[dict])

images_docker_cmd = "docker images --no-trunc --format '{{.Repository}}:&:{{.Tag}}:&:{{.ID}}:&:{{.CreatedSince}}:&:{{.Size}}'"¶

classmethod inspect_container(container)¶

Get detailed information about a container

This information is used to augment the information from the ps command.

Parameters: container (Container) – Container needs a property “name” that corresponds to the name of the container and can be used in the docker inspect command.
Returns: A dictionary of container properties.
Return type: docker_inspect_dict(dict)

classmethod ps(host)¶

Get a list of container properties on the specified host

Parameters

host (Host) – A host object with the attribute “docker_env”.

Returns

A list containing a dictionary: for each image on the host. The dictionary is keyed from the name property of the _ps_format_list.

Return type

container_list (list[dict])

ps_docker_cmd = "docker ps --all --format '{{.Image}}:&:{{.ID}}:&:{{.Names}}:&:{{.Status}}:&:{{.CreatedAt}}:&:{{.Size}}:&:{{.Ports}}'"¶

classmethod run_docker_cmd(cmd, env=None)¶

Convenience function to run docker commands

Adds try/except, and the following options:

shell=True
capture_output=True
timeout=15

Args

cmd (str):: The docker command to be run.
env (dict):: A dictionary containing all the necessary environment variables to run the docker command.

Returns

completed_process (subprocess.CompletedProcess):: Information about the output of the command.

class dsco.commands.ls.Format(name, format_string)¶

Bases: object

Facilitate building and parsing docker format strings

The formatting option (–format) will pretty print some of the docker commands output using a Go template.

For example:

docker images –format ‘{{.Repository}}:&:{{.Tag}}’

will print images with the repository name and image tag seperated by ‘:&:’:

“foo_dev:&:latest”

There are many cases where we want to build these format strings and then collect the output in a dictionary. To continue with the example, we would like to process the output string into the following dictionary:

dict(name = foo_dev, tag=latest)

This class facilitates the building of the format strings and the parsing of corresponding docker output.

Methods

join_format_list (format_list): Given a list of Format objects: return a docker ‘–format’ string.
format_output_to_dict (format_list, format_output): Convert: output of a docker –format command to a dictionary.

classmethod format_output_to_dict(format_list, format_output)¶

Convert output of a docker –format command to a dictionary

Args

format_list (List[Format]):: A list of Format objects. Each one corresponds to a different piece of information about the docker object
format_output (str):: One line from the output of the ‘docker –format’ command.

Returns

A dictionary where keys = [key.name for key in format_list] and values are equal to the corresponding fields from the ‘docker –format’ command.

Example

Continuing from the example in join_format_list() we had:

format_list:

format_list = [
    Format(name="image", format_string="{{.Repository}}"),
    Format(name="tag", format_string="{{.Tag}}")
]

docker command:

docker images --format '{{.Repository}}:&:{{.Tag}}'

Sample output:

foo:&:latest
bar:&:4.8

would return

dict(image="foo", tag="latest")

classmethod join_format_list(format_list)¶

Return a docker ‘–format’ string from a list of Format objects.

Args

format_list (List[Format]):: A list of Format objects. Each one corresponds to a different piece of information about the docker object

Returns

A format string to be used with the –format options of a docker command.

Example

The docker command to return ‘Image Repository’ and ‘Image Tag’ information is:

docker images –format ‘{{.Repository}}:&:{{.Tag}}’

To use this method to generate that string we would create the list:

format_list = [
    Format(name="image", format_string="{{.Repository}}"),
    Format(name="tag", format_string="{{.Tag}}")
]

The method would then return:

“’{{.Repository}}:&:{{.Tag}}’”

class dsco.commands.ls.Host(kernel, images=True, containers=True, inventory=True)¶

Bases: object

The representation of a single machine

Encompasses all the information regarding images and their associated containers on a single machine. This information is accessed by the string representation of Host, e.g. str(Host).

name¶

Arbitrary name for the machine

Type: str

properties¶

Other relevant information about the machine.

Type: dict

docker_env¶

Environment variable necessary to run docker commands on the machine.

Type: dict

image_list¶

A list of Image objects. The image objects have information about that image.

Type: List[Image]

container_list¶

A list of Container objects. The container objects have information about that container.

Type: List[Container]

host_inventory¶

The host_inventory relates the images on a host to the containers created from that image.

Type: OrderedDict

class dsco.commands.ls.Image(image_properties)¶

Bases: object

Representation of a Docker image

name¶

Combination of image and tag, {image:tag}.

Type: str

properties¶: image (str): Image repository. tag (str): Image tag. id (str): Image ID created (str): Elapsed time since the image was created size (str): Image disk size name (str): Combination of image and tag, {image:tag}.

class dsco.commands.ls.Inventory(localhost=True, remote=False)¶

Bases: object

Create a list of all images and containers

Tool to list all containers and images on your localhost and the remote hosts listed in $HOME/.vscode/settings.json. The list is built by the string representation of the object, i.e. str(Inventory).

Attributes

columns (OrderedDict):: A mapping of column name to column length. Determines the output of str(Inventory)
header (str):: Formats the columns into a single output string
line_len (int):: Total length of header.
hosts (List[Host]):: A list of host objects. The host objects have information about images and containers on that host.

Methods

remote_list (List[Dict]):: Static method that returns the remote machines listed in $HOME/.dsco/settings.json

columns = {'ID': 17, 'LINK': 43, 'NAME': 34, 'SIZE': 10, 'STATUS': 30}¶

header = 'NAME LINK ID STATUS SIZE '¶

line_len = 134¶

static remote_list()¶

Get configuration information on remote machines

Retrieves the list of remote machines from $HOME/.dsco/settings.json. Each item in the list is expected to include:

name (str)

ip (str)

env (dict)

dsco.commands.ls.add_dispatch(dispatcher)¶

dsco.commands.ls.add_subparser(subparsers)¶

dsco.commands.ls.main(localhost=True, remote=True)¶

dsco.commands.ls.run_cmd(args, conf)¶

dsco.commands.reports module¶

reports: view and update reports created in docs/reports

Uses sphinx to (re)generate the reports created in docs/reports. This creates static html that can be viewed through the containers web page or github pages.

Currently this only targets the dev container.

Usage:: ‘dsco reports’: open a webbrowser on localhost/reports/ ‘dsco reports [-g, –generate]’: update reports

dsco.commands.reports.add_dispatch(dispatcher)¶

dsco.commands.reports.add_subparser(subparsers)¶

dsco.commands.reports.run_cmd(args, conf)¶

dsco.commands.restart module¶

restart: Restart nginx or flask in the dev container

‘dsco restart’ will restart both the nginx service and the flask service running inside the development container. To restart just one of those use the corresponding flag: –nginx or –flask

dsco.commands.restart.add_dispatch(dispatcher)¶

dsco.commands.restart.add_subparser(subparsers)¶

dsco.commands.restart.run_cmd(args, conf)¶

dsco.commands.rm module¶

Remove a running or stopped container with ‘docker rm -f …’

With no flags, ‘dsco rm’ will remove the dev container. To remove a specific container add the appropriate flag:

--dev

--prod

--debug

Remove all the containers with –all.

dsco.commands.rm.add_dispatch(dispatcher)¶

dsco.commands.rm.add_subparser(subparsers)¶

dsco.commands.rm.run_cmd(args, conf)¶

dsco.commands.rmi module¶

Remove a docker image with ‘docker rmi …’

With no flags, ‘dsco rmi’ will remove the dev image. To remove a specific image add the appropriate flag:

--dev

--prod

--debug

Remove all the images with --all.

Before an image can be removed, all containers created from that image need to be deleted. To force the deletion of all associated containers, you can add the --force option.

dsco.commands.rmi.add_dispatch(dispatcher)¶

dsco.commands.rmi.add_subparser(subparsers)¶

dsco.commands.rmi.run_cmd(args, conf)¶

dsco.commands.shell module¶

shell: Open a shell inside the specified container

If not container is specified,

dsco.commands.shell.add_dispatch(dispatcher)¶

dsco.commands.shell.add_subparser(subparsers)¶

dsco.commands.shell.run_cmd(args, conf)¶

dsco.commands.up module¶

up: Create and launch specified containers

Runs ‘docker-compose up -d …’ for the specified process. Options: –dev, –prod, –all

If the –debug flag is provided, only the debug container is launched. Even if –dev or –prod flags are provided.

Otherwise (i.e. no –debug):: – dev, all, or no flags | dev container is launched – prod or all | prod container is launched

dsco.commands.up.add_dispatch(dispatcher)¶

dsco.commands.up.add_subparser(subparsers)¶

dsco.commands.update_port module¶

update_port: Update the ports of the specified container

Each container on a host needs to have a unique port. This method will make the appropriate updates in the project docker-compose file.

If we just enter one port number (e.g. ‘dsco update_port 8000’):

the dev port will be set to 8000
the prod port will be set to 8000 + 1000 = 9000
the debug port will be set to 8000 - 500 = 7500

If we want more control we can use the flag options to set those ports to specific values.

Examples

dsco update_port 8000: dev: 8000, prod: 9000, debug: 7500
dsco update_port 8000 –prod 9400: dev: 8000, prod: 9400, debug: 7500
dsco update_port –debug 7630: dev: unchanged, prod: unchanged, debug: 7630
dsco update_port 8200 –prod 9400 –debug 7630: dev: 8200, prod: 9400, debug: 7630
dsco update_port –dev 8200 –debug 7620: dev: 8200, prod: unchanged, debug: 7620

dsco.commands.update_port.add_dispatch(dispatcher)¶

dsco.commands.update_port.add_subparser(subparsers)¶

dsco.commands.update_port.run_cmd(args, conf)¶

Module contents¶

Create subparsers

See the dsco.options module to find an explanation of how the subparsers defined here are added to the main parser.

Each module defined here is expected to declare the following:

cmd_name(str)
The name of the sub-command

add_subparser(subparsers)

Args:

subparsers (argparse._SubParsersAction)
The subparser object to which all sub-commands will be assigned.

Returns:
None

add_dispatch(dispatcher)

Args:

dispatcher (dict)
Dictionary mapping cmd --> run_cmd.

cmd (string)
This is the name of the subparser

run_cmd(args, conf)
Executes the desired action.

Args

args (argParse.Namespace)
This contains the command line arguments as parsed by the appropriate subparser.

conf (dict)
This dictionary contains project specific settings such as the project root directory, settings from the pyproject.toml file (if it exists) etc.

Returns
None

Example

Let’s look at a simple example. Say we wanted to create a subparser called project_info such that when we run the command dsco project_info we get the directory name of the project root directory, or None if we were not in a project directory tree. We also want to be able to add a -v, or --verbose option to get the information in the pyproject file.

We would create a file called project_info.py and it would contain the following:

# Assign the file name without extension to cmd_name.
# Naming the command in this way ensures the file name
# and command name stay in sync.
from pathlib import Path
cmd_name = Path(__file__).stem

def add_subparser(subparsers):
    # create the basic command
    sub = subparsers.add_parser(
        cmd_name, help="list the project root dir"
    )
    # add the -v option
    sub.add_argument(
        "-v",
        "--verbose",
        action="store_true",
        help="Also show information in pyproject file",
    )

def run_cmd(args, conf):
    # Only return a value if dsco is run within a project tree
    # conf["proj_root"] is defined in application.py
    if conf["proj_root"]:
        print(conf["proj_root"])

        if args.verbose:
            print(conf["pyproject"])
    else:
        print("None")


def add_dispatch(dispatcher):
    dispatcher[cmd_name] = run_cmd

Table Of Contents

dsco.commands package¶

Submodules¶

dsco.commands.build module¶

dsco.commands.code module¶

dsco.commands.documentation module¶

dsco.commands.go module¶

dsco.commands.init module¶

dsco.commands.ls module¶

dsco.commands.reports module¶

dsco.commands.restart module¶

dsco.commands.rm module¶

dsco.commands.rmi module¶

dsco.commands.shell module¶

dsco.commands.up module¶

dsco.commands.update_port module¶

Module contents¶