containers — Docker Containers Utilities

---

containers.get_ports(container: Container) → Mapping[int, int]

Get the exposed (published) ports of a container.

Parameters:

container – A running container object.

Returns:

A dictionary mapping all internal ports of the container to their external ports on the host machine.

Warning

container must be running and up to date when calling the function. Ensure the container is up to date by calling reload().

containers.get_aliases(container: Container, network: str | Network) → Sequence[str]

Get the aliases of a container within a network.

Parameters:

• container – A running container object.

• network – The name of the network, or a network object.

Returns:

A list of aliases of the container in the network.

Warning

container must be running and up to date when calling the function. Ensure the container is up to date by calling reload().

containers.is_removed(container: Container) → bool

Check if a container has been removed.

Parameters:

container – A container object.

Returns:

True if the container has been removed, False otherwise.

containers.is_alive(container: Container) → bool

Check if a container is alive.

Parameters:

container – A container object.

Returns:

True if the container is alive, False otherwise.

containers.killing(container: Container, *, timeout: float = 10, signal: str | int = 'SIGKILL') → AbstractContextManager[Container]

Create a context manager that ensures a container is not running when exiting.

Parameters:

• container – A container object.

• timeout – The timeout in seconds to wait for the container to stop (starting from the context exit).

• signal – The signal to send to the container to terminate it.

Raises:

requests.ReadTimeout if the container does not stop within the timeout.

Returns:

A context manager that yields container, and kills the container if it is still alive on exit.

containers.removing(container: Container, *, expected_exit_code: None | int | Container[int] = 0, force: bool = False) → AbstractContextManager[Container]

Create a context manager that ensures a container is removed when exiting.

Parameters:

• container – A container object.

• expected_exit_code – The expected exit code (or codes) of the container. If the container exits with a different code, an exception will be raised. If None, any exit code is accepted.

• force – If True, the container will be removed even if it is still running, or not yet started.

Raises:

requests.RuntimeError if the container has not completed with force=False, or if the container exited with an unexpected exit code. In these cases, the container is not removed.

Returns:

A context manager that yields container, and removes the container on exit.

containers.create_and_pull(docker_client: DockerClient, image: str, *args, **kwargs) → Container

Create a docker container, pulling the image from dockerhub if necessary.

Parameters:

• docker_client – A Docker client object.

• image – The tagged name of the image to pull.

• *args – Positional arguments to pass to create().

• **kwargs – Keyword arguments to pass to create().

Returns:

A container object.

containers.download_file(container: Container, path: str | PathLike) → IO[bytes]

Download a file from a container.

Parameters:

• container – A container object.

• path – The path to the file to download (in the container).

Returns:

An IO stream with the file content.

Raises:

FileNotFoundError if the file does not exist in the container.

Raises:

IsADirectoryError if the path leads to a directory.

containers.upload_file(container: Container, path: str | PathLike, data: bytes)

containers.upload_file(container: Container, path: str | PathLike, *, fileobj: IO[bytes])

Upload a file to a container.

Parameters:

• container – A container object.

• data – The file content to upload.

• fileobj – An IO with the file content.

Pram path:

The destination path to upload to (in the container).

class containers.SafeContainerCreator(client: DockerClient)

A utility class that can create containers and pull images, and can also remove them if subsequent creations fail.

Parameters:

client – A Docker client object to use for pulling images and creating containers.

create_and_pull(image: str, command: str | None = None, **kwargs) → Container

Create a container, pulling the image from dockerhub if necessary. If the Container creation fails, all containers previously created by the SafeContainerCreator are removed.

Parameters:

• image – The tagged name of the image to pull.

• command – The command to run in the container.

• **kwargs – Keyword arguments to pass to create().

Returns:

A container object.

Note

In case of failure, all previously created containers are removed in reverse order to the one they were created in.