subclasses — Specialized service ABCs

Yellowbox contains multiple YellowService subclasses for easier definition of services. Most of the subclasses deal with Docker containers required for running the service.

class subclasses.ContainerService(containers: Sequence[Container], remove: bool = True)[source]

Abstract base class for services using one or more docker containers.

Inherits from YellowService.

Provides basic functionality of turning on the containers on start(), shutting down and removing the containers on stop(), and connecting the containers to docker virtual networks using connect() and disconnect().

Parameters:

  • containers – A sequence of docker container objects, relevant for the service. The containers may be either stopped or started.

  • remove – Set remove

abstract start(retry_spec: RetrySpec | None = None)[source]

Start the service by turning on all stopped containers. Containers are started sequentially in the order provided.

Parameters:

retry_spec – specifies the internal retry semantics for the chosen “check” function. It allows specifying a timeout or maximum number of attempts before startup counts as a failure. Subclasses should block until the service is responsive using this RetrySpec. If None, subclasses should use the a custom default RetrySpec.

stop(signal: str | int = 'SIGTERM')[source]

Stop the service with the given signal. All containers in the service will receive the signal in reverse order. Any container not stopped within 10 seconds of receiving the signal will be forcibly closed.

If remove is true, all containers will be automatically deleted together with their respective volumes when the containers are stopped.

This method will block until all the containers are fully stopped.

Parameters:

signal – The signal to send to the containers.

Note

Some subclasses override the default signal with something better suited to a specific image (like 'SIGKILL' or 'SIGINT').

remove: bool[source]

If True (default) containers will be removed alongside with their respective volumes when the service is stopped. Can also be set through the constructor.

is_alive() → bool[source]

Returns whether all containers are currently running.

connect(network: Network)[source]

Connect all containers to the given docker network.

Parameters:

network – The network to connect to.

disconnect(network: Network, **kwargs)[source]

Disconnect the service from the given network.

Parameters:

  • network – The network to disconnect from.

  • kwargs – Forwarded to Network.disconnect of each container in the service.

class subclasses.SingleEndpointService(containers: Sequence[Container], remove: bool = True)[source]

Abstract Base Class for services that have only a single network endpoint.

One of the containers is used as the endpoint. The container is picked internally by the inheriting class.

Arguments are the same as ContainerService.

Inherits from ContainerService.

The following methods are modified:

connect(network: Network, **kwargs) → Sequence[str][source]

Connects the endpoint container to given network.

Parameters:

  • network – The network to connect to.

  • kwargs – Forwarded to Network.connect.

Returns:

A list of the container’s aliases within the network.

disconnect(network: Network, **kargs)[source]

Disconnect the endpoint container from the given network. of each container in the service.

Parameters:
class subclasses.SingleContainerService(container: Container, remove: bool = True)[source]

Abstract Base Class for services that use a single docker container.

Inherits from SingleEndpointService.

Parameters:

  • container – A single docker Container that implements the service. Accepts both a started and a stopped container.

  • remove – Same as in ContainerService.

property container[source]
Type:

docker.Container

Returns the docker Container implementing the service.

class subclasses.RunMixin[source]

Mixin class implementing a runnable ContainerService.

Adds the convenience method run().

classmethod service_name() → str[source]
Returns:

The name of the service. May be overridden by subclasses. Defaults to cls.__name__.

classmethod run(docker_client: DockerClient, *, spinner: bool = True, retry_spec: RetrySpec | None = None, **kwargs) → AbstractContextManager[Self][source]

Convenience method to run the service. Used as a context manager.

Upon context manager entry, creates the service and starts it. Upon exit, stops the service.

Parameters:

  • docker_client – The docker client to use to create the containers, or to pull the docker images from dockerhub if it does not exist on the local machine.

  • spinner – If True a spinner is printed to stdout while the image is being pulled and the service is starting.

  • retry_spec – Passed to start().

  • kwargs – Forwarded to the class constructor.

class subclasses.AsyncRunMixin[source]

Mixin class implementing a runnable ContainerService, whose startup is asynchronous.

Adds the convenience method arun().

Warning

Currently, all docker commands are executed synchronously. The only asynchronous part of startup is the time waiting between healthcheck attempts.

abstract async astart(retry_spec: RetrySpec | None = None)[source]

Start the service by turning on all stopped containers and waiting for startup. Similar to ContainerService.start(), but asynchronous.

classmethod service_name() → str[source]
Returns:

The name of the service. May be overridden by subclasses. Defaults to cls.__name__.

classmethod arun(docker_client: DockerClient, *, verbose: bool = True, retry_spec: RetrySpec | None = None, **kwargs) → AbstractAsyncContextManager[Self][source]

Convenience method to run the service asynchronously. Used as an async context manager.

Upon context manager entry, creates the service and starts it. Upon exit, stops the service.

Parameters:

  • docker_client – The docker client to use to create the containers, or to pull the docker images from dockerhub if it does not exist on the local machine.

  • verbose – If True a spinner is printed to stdout while the image is being pulled, and messages are printed while the service is starting.

  • retry_spec – Passed to start().

  • kwargs – Forwarded to the class constructor.