​
prefect.utilities.dockerutils

​
Functions

​
python_version_minor

python_version_minor() -> str

​
python_version_micro

python_version_micro() -> str

​
get_prefect_image_name

get_prefect_image_name(prefect_version: Optional[str] = None, python_version: Optional[str] = None, flavor: Optional[str] = None) -> str

Get the Prefect image name matching the current Prefect and Python versions.

Args:

  • prefect_version: An optional override for the Prefect version.
  • python_version: An optional override for the Python version; must be at the minor level e.g. ‘3.9’.
  • flavor: An optional alternative image flavor to build, like ‘conda’

​
silence_docker_warnings

silence_docker_warnings() -> Generator[None, None, None]

​
docker_client

docker_client() -> Generator['DockerClient', None, None]

Get the environmentally-configured Docker client

​
build_image

build_image(context: Path, dockerfile: str = 'Dockerfile', tag: Optional[str] = None, pull: bool = False, platform: Optional[str] = None, stream_progress_to: Optional[TextIO] = None, **kwargs: Any) -> str

Builds a Docker image, returning the image ID

Args:

  • context: the root directory for the Docker build context
  • dockerfile: the path to the Dockerfile, relative to the context
  • tag: the tag to give this image
  • pull: True to pull the base image during the build
  • stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO) that will collect the build output as it is reported by Docker

Returns:

  • The image ID

​
push_image

push_image(image_id: str, registry_url: str, name: str, tag: Optional[str] = None, stream_progress_to: Optional[TextIO] = None) -> str

Pushes a local image to a Docker registry, returning the registry-qualified tag for that image

This assumes that the environment’s Docker daemon is already authenticated to the given registry, and currently makes no attempt to authenticate.

Args:

  • image_id: a Docker image ID
  • registry_url: the URL of a Docker registry
  • name: the name of this image
  • tag: the tag to give this image (defaults to a short representation of the image’s ID)
  • stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO) that will collect the build output as it is reported by Docker

Returns:

  • A registry-qualified tag, like my-registry.example.com/my-image:abcdefg

​
to_run_command

to_run_command(command: list[str]) -> str

Convert a process-style list of command arguments to a single Dockerfile RUN instruction.

​
parse_image_tag

parse_image_tag(name: str) -> tuple[str, Optional[str]]

Parse Docker Image String

  • If a tag or digest exists, this function parses and returns the image registry and tag/digest, separately as a tuple.
    • Example 1: ‘prefecthq/prefect:latest’ -> (‘prefecthq/prefect’, ‘latest’)
    • Example 2: ‘hostname.io:5050/folder/subfolder:latest’ -> (‘hostname.io:5050/folder/subfolder’, ‘latest’)
    • Example 3: ‘prefecthq/prefect@sha256:abc123’ -> (‘prefecthq/prefect’, ‘sha256:abc123’)
  • Supports parsing Docker Image strings that follow Docker Image Specification v1.1.0
    • Image building tools typically enforce this standard

Args:

  • name: Name of Docker Image

​
split_repository_path

split_repository_path(repository_path: str) -> tuple[Optional[str], str]

Splits a Docker repository path into its namespace and repository components.

Args:

  • repository_path: The Docker repository path to split.

Returns:

  • Tuple[Optional[str], str]: A tuple containing the namespace and repository components.
  • namespace (Optional[str]): The Docker namespace, combining the registry and organization. None if not present.
  • repository (Optionals[str]): The repository name.

​
format_outlier_version_name

format_outlier_version_name(version: str) -> str

Formats outlier docker version names to pass packaging.version.parse validation

  • Current cases are simple, but creates stub for more complicated formatting if eventually needed.
  • Example outlier versions that throw a parsing exception:
    • “20.10.0-ce” (variant of community edition label)
    • “20.10.0-ee” (variant of enterprise edition label)

Args:

  • version: raw docker version value

Returns:

  • value that can pass packaging.version.parse validation

​
generate_default_dockerfile

generate_default_dockerfile(context: Optional[Path] = None)

Generates a default Dockerfile used for deploying flows. The Dockerfile is written to a temporary file and yielded. The temporary file is removed after the context manager exits.

Args:

  • -: The context to use for the Dockerfile. Defaults to the current working directory.

​
Classes

​
BuildError

Raised when a Docker build fails

​
ImageBuilder

An interface for preparing Docker build contexts and building images

Methods:

​
add_line

add_line(self, line: str) -> None

Add a line to this image’s Dockerfile

​
add_lines

add_lines(self, lines: Iterable[str]) -> None

Add lines to this image’s Dockerfile

​
copy

copy(self, source: Union[str, Path], destination: Union[str, PurePosixPath]) -> None

Copy a file to this image

​
write_text

write_text(self, text: str, destination: Union[str, PurePosixPath]) -> None

​
build

build(self, pull: bool = False, stream_progress_to: Optional[TextIO] = None) -> str

Build the Docker image from the current state of the ImageBuilder

Args:

  • pull: True to pull the base image during the build
  • stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO) that will collect the build output as it is reported by Docker

Returns:

  • The image ID

​
assert_has_line

assert_has_line(self, line: str) -> None

Asserts that the given line is in the Dockerfile

​
assert_line_absent

assert_line_absent(self, line: str) -> None

Asserts that the given line is absent from the Dockerfile

​
assert_line_before

assert_line_before(self, first: str, second: str) -> None

Asserts that the first line appears before the second line

​
assert_line_after

assert_line_after(self, second: str, first: str) -> None

Asserts that the second line appears after the first line

​
assert_has_file

assert_has_file(self, source: Path, container_path: PurePosixPath) -> None

Asserts that the given file or directory will be copied into the container at the given path

​
PushError

Raised when a Docker image push fails