Skip to main content

Image

This class is a representation of Container Images, used for programmatically creating layered images. It provides methods to construct images from various sources like base images, Dockerfiles, or UV scripts, and allows for incremental modification through adding layers for dependencies, environment variables, and source code. The class ensures that image objects can be instantiated even if underlying resources are not immediately available, with validation occurring at build time.

Attributes​

  • base_image: Optional[str] = None

    • These are base properties of an image

  • dockerfile: Optional[Path] = None

    • These are base properties of an image

  • registry: Optional[str] = None

    • These are base properties of an image

  • name: Optional[str] = None

    • These are base properties of an image

  • platform: Tuple[Architecture, ...] = ('linux/amd64',)

    • These are base properties of an image

  • python_version: Tuple[int, int] = _detect_python_version()

    • These are base properties of an image

Constructors​

  • Initializes a new Image object. This constructor is intended for internal use only and should not be called directly. Use the class methods like from_debian_base, from_base, from_uv_script, or from_dockerfile to create Image instances.

  • Parameters

    • base_image: Optional[str]
      • The base image URI (e.g., 'python:3.10-slim').
    • dockerfile: Optional[Path]
      • Path to a Dockerfile to build the image from.
    • registry: Optional[str]
      • The registry where the image is stored (e.g., 'docker.io').
    • name: Optional[str]
      • The name of the image.
    • platform: Tuple[Architecture, ...]
      • The target platform(s) for the image (e.g., 'linux/amd64', 'linux/arm64').
    • python_version: Tuple[int, int]
      • The Python version to use for the image.
    • _layers: Tuple[Layer, ...]
      • Internal use only. A tuple of layers to be added to the image.

Methods​

def identifier()

  • Computes and returns a unique identifier for the image. This identifier is a hash derived from the image's layers and properties. It's used for efficient lookup of previously built images in a cache. If an identifier override is set, it returns that instead. The hashing process excludes None values for properties and incorporates a string representation of all layers.

  • Return Value: string

    • A unique identifier string for the image.
def validate()
  • Validates each layer of the image by calling its respective validate method. This method is intended to be called at build time to ensure the integrity and correctness of all image layers.
def from_debian_base(python_version: Optional[Tuple[int, int]], flyte_version: Optional[str], install_flyte: bool = True, registry: Optional[str], name: Optional[str], platform: Optional[Tuple[Architecture, ...]]) - > [Image](src_flyte__image_image)

  • A class method to create an Image instance starting from a default Debian-based base image provided by the library. It utilizes _get_default_image_for to configure the base image and can optionally install the Flyte library. It supports specifying the Python version, Flyte version, registry, image name, and target platform.

  • Parameters

    • python_version: Optional[Tuple[int, int]]
      • The desired Python version (major, minor). Defaults to the current Python version.
    • flyte_version: Optional[str]
      • The Flyte version to install. If None, the currently installed Flyte version is used.
    • install_flyte: bool
      • Whether to install the Flyte library in the image.
    • registry: Optional[str]
      • The registry to use for the image. If provided, it overrides the default.
    • name: Optional[str]
      • The name of the image. If provided, it overrides the default.
    • platform: Optional[Tuple[Architecture, ...]]
      • The target platform(s) for the image (e.g., ('linux/amd64', 'linux/arm64')). Defaults to ('linux/amd64', 'linux/arm64').

  • Return Value: Image

    • An Image object initialized with a default Debian base.
def from_base(image_uri: string) - > [Image](src_flyte__image_image)

  • A class method to create an Image instance starting from a specified base image URI. This is useful when you want to use a pre-existing image from a registry as the foundation for your new image.

  • Parameters

    • image_uri: string
      • The full URI of the base image (e.g., 'registry/name:tag').

  • Return Value: Image

    • An Image object initialized with the provided base image URI.
def from_uv_script(script: Path | str, name: string, registry: str | None, python_version: Optional[Tuple[int, int]], index_url: Optional[str], extra_index_urls: Union[str, List[str], Tuple[str, ...], None], pre: bool = False, extra_args: Optional[str], platform: Optional[Tuple[Architecture, ...]], secret_mounts: Optional[SecretRequest]) - > [Image](src_flyte__image_image)

  • A class method to create a new Image instance from a uv script file. This method parses the script's header to determine Python version and dependencies. It uses a Debian base image and adds the uv script as a layer. It supports specifying index URLs, pre-release versions, extra arguments, and secret mounts for the build process.

  • Parameters

    • script: Path | str
      • Path to the uv script file.
    • name: string
      • Name of the image.
    • registry: str | None
      • Registry to use for the image.
    • python_version: Optional[Tuple[int, int]]
      • Python version for the image. Defaults to the current Python version.
    • index_url: Optional[str]
      • Index URL to use for installing dependencies.
    • extra_index_urls: Union[str, List[str], Tuple[str, ...], None]
      • Extra index URLs to use for installing dependencies.
    • pre: bool
      • Whether to allow pre-release versions.
    • extra_args: Optional[str]
      • Extra arguments to pass to the uv install command.
    • platform: Optional[Tuple[Architecture, ...]]
      • Architecture to use for the image. Defaults to 'linux/amd64'.
    • secret_mounts: Optional[SecretRequest]
      • Secret mounts to use for the image.

  • Return Value: Image

    • An Image object created from a uv script.
def clone(registry: Optional[str], name: Optional[str], python_version: Optional[Tuple[int, int]], addl_layer: Optional[Layer]) - > [Image](src_flyte__image_image)

  • Creates a new Image object that is a copy of the current image, with optional modifications to the registry, name, Python version, or by adding an additional layer. This method is used internally to build up image configurations immutably.

  • Parameters

    • registry: Optional[str]
      • The registry to use for the cloned image. If None, the current registry is used.
    • name: Optional[str]
      • The name of the cloned image. If None, the current name is used.
    • python_version: Optional[Tuple[int, int]]
      • The Python version for the cloned image. If None, the current Python version is used.
    • addl_layer: Optional[Layer]
      • An additional layer to append to the cloned image's layers.

  • Return Value: Image

    • A new Image object, cloned from the current one with specified modifications.
def from_dockerfile(file: Path, registry: string, name: string, platform: Union[Architecture, Tuple[Architecture, ...], None]) - > [Image](src_flyte__image_image)

  • A class method to create an Image instance directly from a Dockerfile. This method takes the path to the Dockerfile, along with the desired image name and registry. It's important to note that once an image is created from a Dockerfile, additional layers cannot be added using with_* methods, as the system does not parse the Dockerfile content. The context for building the Dockerfile is the directory containing the Dockerfile itself.

  • Parameters

    • file: Path
      • The path to the Dockerfile.
    • registry: string
      • The registry to use for the image.
    • name: string
      • The name of the image.
    • platform: Union[Architecture, Tuple[Architecture, ...], None]
      • The target architecture(s) for the image. Defaults to 'linux/amd64'.

  • Return Value: Image

    • An Image object created from the specified Dockerfile.
def uri()

  • Returns the full URI of the image, formatted as '< registry >/< name >:< tag >'. It constructs this URI using the image's registry, name, and its final tag (determined by _final_tag). If the registry or name is not set, it adjusts the format accordingly. If only the base image is defined, it returns the base image URI.

  • Return Value: string

    • The complete URI of the image.
def with_workdir(workdir: string) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding a WorkDir layer to the current image. This layer sets the working directory within the container. Any previously set working directory will be overridden.

  • Parameters

    • workdir: string
      • The path to the desired working directory.

  • Return Value: Image

    • A new Image object with the specified working directory.
def with_requirements(file: str | Path, secret_mounts: Optional[SecretRequest]) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding a Requirements layer. This layer installs Python packages from a specified requirements file (.txt). It ensures the file has the correct extension and allows for optional secret mounts during the build process.

  • Parameters

    • file: str | Path
      • Path to the requirements file (must be a .txt file).
    • secret_mounts: Optional[SecretRequest]
      • Optional list of secrets to mount for the build process.

  • Return Value: Image

    • A new Image object with the specified requirements installed.
def with_pip_packages(packages: str, index_url: Optional[str], extra_index_urls: Union[str, List[str], Tuple[str, ...], None], pre: bool = False, extra_args: Optional[str], secret_mounts: Optional[SecretRequest]) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding a PipPackages layer, which installs specified pip packages. It supports custom index URLs, pre-release versions, extra installation arguments, and secret mounts for accessing private repositories. This method is useful for adding specific Python dependencies to the image.

  • Parameters

    • packages: str
      • List of pip packages to install (follows pip install syntax).
    • index_url: Optional[str]
      • Index URL to use for pip install.
    • extra_index_urls: Union[str, List[str], Tuple[str, ...], None]
      • Extra index URLs to use for pip install.
    • pre: bool
      • Whether to allow pre-release versions.
    • extra_args: Optional[str]
      • Extra arguments to pass to pip install.
    • secret_mounts: Optional[SecretRequest]
      • List of secrets to mount for the build process.

  • Return Value: Image

    • A new Image object with the specified pip packages installed.
def with_env_vars(env_vars: Dict[str, str]) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding an Env layer, which sets environment variables within the image. This is useful for configuring the runtime environment of the container.

  • Parameters

    • env_vars: Dict[str, str]
      • A dictionary of environment variables to set (key-value pairs).

  • Return Value: Image

    • A new Image object with the specified environment variables set.
def with_source_folder(src: Path, dst: str = &#x27;.&#x27;) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding a CopyConfig layer to copy a local directory into the image. The src parameter specifies the source directory in the build context, and dst specifies the destination directory within the image. If dst is omitted, it defaults to the current working directory.

  • Parameters

    • src: Path
      • The source directory path from the build context.
    • dst: str
      • The destination directory path within the image.

  • Return Value: Image

    • A new Image object with the source folder copied into it.
def with_source_file(src: Path, dst: str = &#x27;.&#x27;) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding a CopyConfig layer to copy a local file into the image. The src parameter specifies the source file in the build context, and dst specifies the destination path within the image. If dst is omitted, it defaults to the current working directory.

  • Parameters

    • src: Path
      • The source file path from the build context.
    • dst: str
      • The destination path within the image.

  • Return Value: Image

    • A new Image object with the source file copied into it.
def with_dockerignore(path: Path) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding a DockerIgnore layer, which specifies a .dockerignore file. This file controls which files and directories are excluded from the build context sent to the Docker daemon.

  • Parameters

    • path: Path
      • The path to the .dockerignore file.

  • Return Value: Image

    • A new Image object with the specified .dockerignore file.
def with_uv_project(pyproject_file: str | Path, uvlock: Path | None, index_url: Optional[str], extra_index_urls: Union[List[str], Tuple[str, ...], None], pre: bool = False, extra_args: Optional[str], secret_mounts: Optional[SecretRequest]) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding a UVProject layer, which installs dependencies defined in a pyproject.toml file and its corresponding uv.lock file. This method is designed for projects managed with uv and pyproject.toml, and it ensures that the virtual environment is set up correctly within the image.

  • Parameters

    • pyproject_file: str | Path
      • Path to the pyproject.toml file.
    • uvlock: Path | None
      • Path to the uv.lock file. Defaults to pyproject.parent / 'uv.lock'.
    • index_url: Optional[str]
      • Index URL to use for installing dependencies.
    • extra_index_urls: Union[List[str], Tuple[str, ...], None]
      • Extra index URLs to use for installing dependencies.
    • pre: bool
      • Whether to allow pre-release versions.
    • extra_args: Optional[str]
      • Extra arguments to pass to the uv install command.
    • secret_mounts: Optional[SecretRequest]
      • List of secret mounts to use for the build process.

  • Return Value: Image

    • A new Image object with dependencies from a uv project installed.
def with_apt_packages(packages: str, secret_mounts: Optional[SecretRequest]) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding an AptPackages layer, which installs specified packages using the apt package manager. This is typically used for installing system-level dependencies required by the application.

  • Parameters

    • packages: str
      • List of apt packages to install.
    • secret_mounts: Optional[SecretRequest]
      • List of secret mounts to use for the build process.

  • Return Value: Image

    • A new Image object with the specified apt packages installed.
def with_commands(commands: List[str], secret_mounts: Optional[SecretRequest]) - > [Image](src_flyte__image_image)

  • Creates a new Image object by adding a Commands layer, which executes a list of shell commands during the image build process. It's important not to use the RUN instruction within these commands, as they are executed in the context of building the layer.

  • Parameters

    • commands: List[str]
      • List of shell commands to execute.
    • secret_mounts: Optional[SecretRequest]
      • List of secret mounts to use for the build process.

  • Return Value: Image

    • A new Image object with the specified commands executed.
def with_local_v2()

  • Creates a new Image object configured to use the local v2 builder. This method is used internally to set up the build environment, potentially overriding existing builder configurations. It adds a PythonWheels layer to include local distribution files.

  • Return Value: Image

    • A new Image object configured with the local v2 builder.