Image

The targon.Image class is your primary tool for defining the software environment for your remote functions.

Every function on Targon runs inside a container image. The Image class provides a Python-native way to construct this environment, much like writing a Dockerfile. You start from a base image and chain methods to install packages, copy files, and set configuration. This creates a reproducible and version-controlled definition of your function's runtime.

Example: Chaining Methods

Most methods on the Image class return a new Image object, allowing you to chain calls together to build up your environment step-by-step.

import targon

# Define a custom image for a machine learning task
ml_image = (
    targon.Image.debian_slim()
    .pip_install("numpy", "pandas", "scikit-learn")
    .apt_install("git")
    .env({"MY_ENV_VAR": "my-value"})
    .run_commands("echo 'Image setup complete!'")
)

Base Images

All custom images must start from a base image. Targon provides helpers for common use cases.

Image.debian_slim

Creates a minimal Debian-based image with Python pre-installed.

@staticmethod
def debian_slim(python_version: Optional[str] = None) -> "_Image":

Arguments:

Name	Type	Description
python_version	str, optional	The Python version to use.

Example:

import targon

# Use the default Python version (3.11)
image = targon.Image.debian_slim()

# Specify a different Python version
py310_image = targon.Image.debian_slim(python_version="3.10")

Image.from_registry

Builds an image from a tag in a public or private container registry (like Docker Hub). This is useful for starting with a pre-configured environment, such as a specific CUDA version for GPU tasks.

@staticmethod
def from_registry(
    tag: str,
    *,
    setup_dockerfile_commands: list[str] = [],
    force_build: bool = False,
    add_python: Optional[str] = None,
) -> "_Image":

Arguments:

Name	Type	Description
tag	str	The image tag from the registry.
setup_dockerfile_commands	list[str], optional	Additional Dockerfile commands to run before Python installation.
force_build	bool, optional	Force a rebuild of the image.
add_python	str, optional	The Python version to add to the image.

Example:

If the base image does not have Python, you can use add_python to install it.

import targon

# Start from a minimal Debian image and add Python 3.11
debian_image = targon.Image.from_registry(
    "debian:stable-slim",
    add_python="3.11"
)

Image.from_dockerfile

Builds an image from a local Dockerfile. This is useful for migrating existing services or for complex setups that are easier to express in a Dockerfile.

@staticmethod
def from_dockerfile(
    path: Union[str, Path],
    *,
    context_dir: Optional[Union[Path, str]] = None,
    ignore: Union[Sequence[str], Callable[[Path], bool]] = [],
) -> "_Image":

Arguments:

Name	Type	Description
path	str | Path	The path to the Dockerfile.
context_dir	str | Path, optional	The path to the build context directory. Defaults to the directory containing the Dockerfile.
ignore	Sequence[str] | Callable[[Path], bool], optional	A list of file patterns or a function to ignore files in the context.

Example:

Assume you have a Dockerfile in your project root:

# ./Dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y git

You can build an image from it like this:

import targon

# Build the image from the local Dockerfile
image = targon.Image.from_dockerfile("./Dockerfile")

Customization Methods

These methods allow you to modify a base image by adding packages, files, and configuration.

Image.apt_install

Installs system packages into the image using apt-get. This is for Debian-based images (like debian_slim).

def apt_install(
    self,
    *packages: Union[str, List[str]]
) -> "_Image":

Arguments:

Name	Type	Description
*packages	str | List[str]	A list of packages to install.

Example:

import targon

image = targon.Image.debian_slim().apt_install("git", "ffmpeg")

Image.pip_install

Installs Python packages into the image's environment using pip.

def pip_install(
    self,
    *packages: Union[str, List[str]],
    find_links: Optional[str] = None,
    index_url: Optional[str] = None,
    extra_index_url: Optional[str] = None,
    pre: bool = False,
    extra_options: str = "",
) -> "_Image":

Arguments:

Name	Type	Description
*packages	str | List[str]	A list of Python packages to install.
find_links	str, optional	URL to search for packages.
index_url	str, optional	Base URL of the Python Package Index.
extra_index_url	str, optional	Extra URLs of package indexes.
pre	bool, optional	Allow pre-release packages.
extra_options	str, optional	Additional pip install options.

Example:

import targon

image = (
    targon.Image.debian_slim()
    .pip_install(
        "numpy",
        "pandas>=2.0.0",
        "scikit-learn"
    )
)

Image.pip_install_from_requirements

Installs Python packages from a local requirements.txt file.

def pip_install_from_requirements(
    self,
    requirements_txt: str,
    find_links: Optional[str] = None,
    *,
    index_url: Optional[str] = None,
    extra_index_url: Optional[str] = None,
    pre: bool = False,
    extra_options: str = "",
) -> "_Image":

Arguments:

Name	Type	Description
requirements_txt	str	Path to the requirements.txt file.
find_links	str, optional	URL to search for packages.
index_url	str, optional	Base URL of the Python Package Index.
extra_index_url	str, optional	Extra URLs of package indexes.
pre	bool, optional	Allow pre-release packages.
extra_options	str, optional	Additional pip install options.

Example:

Given a requirements.txt file:

# ./requirements.txt
requests
beautifulsoup4

You can install these packages like this:

import targon

image = targon.Image.debian_slim().pip_install_from_requirements("./requirements.txt")

Image.dockerfile_commands

Injects raw Dockerfile commands into the image build process. This is an escape hatch for advanced use cases where a Python method isn't available for a specific Dockerfile instruction.

def dockerfile_commands(
    self,
    *dockerfile_commands: Union[str, List[str]],
    context_files: Dict[str, str] = {},
) -> "_Image":

Arguments:

Name	Type	Description
*dockerfile_commands	str | List[str]	Dockerfile commands to add.
context_files	Dict[str, str], optional	A dictionary mapping context file names to their local paths.

Example:

import targon

image = (
    targon.Image.debian_slim()
    .dockerfile_commands(
        "ENV DEBIAN_FRONTEND=noninteractive",
        "RUN echo 'A custom command was ran'"
    )
)

Image.run_commands

Runs one or more shell commands during the image build. Each command is executed with RUN.

def run_commands(
    self,
    *commands: Union[str, list[str]],
) -> "_Image":

Arguments:

Name	Type	Description
*commands	str | List[str]	Shell commands to run.

Example:

import targon

image = (
    targon.Image.debian_slim()
    .run_commands(
        "apt-get update",
        "apt-get install -y curl",
        "curl -sL https://example.com/install.sh | bash"
    )
)

Image.env

Sets environment variables that will be available inside the running container.

def env(self, vars: dict[str, str]) -> "_Image":

Arguments:

Name	Type	Description
vars	dict[str, str]	A dictionary of environment variables to set.

Example:

import targon

image = targon.Image.debian_slim().env({
    "API_KEY": "dummy-key-for-build",
    "LOG_LEVEL": "info",
})

Image.workdir

Sets the working directory for subsequent commands in the image build and for the function at runtime.

def workdir(self, path: Union[str, PurePosaxPath]) -> "_Image":

Arguments:

Name	Type	Description
path	str | PurePosixPath	The absolute path to set as the working directory.

Example:

import targon

# Sets the working directory to /app
image = targon.Image.debian_slim().workdir("/app")

Image.add_local_file

Copies a local file into the image at a specified absolute path.

def add_local_file(
    self,
    local_path: Union[str, Path],
    remote_path: str,
    *,
    copy: bool = True
) -> "_Image":

Arguments:

Name	Type	Description
local_path	str | Path	The path to the local file.
remote_path	str	The absolute path in the container where the file will be placed.
copy	bool, optional	Targon copies files into the image. (Will change)

Example:

import targon

# Copies ./config.json to /app/config.json inside the container
image = targon.Image.debian_slim().add_local_file("./config.json", "/app/config.json")

Image.add_local_dir

Copies the contents of a local directory into the image at a specified absolute path.

def add_local_dir(
    self,
    local_path: Union[str, Path],
    remote_path: str,
    *,
    copy: bool = True,
    ignore: Union[Sequence[str], Callable[[Path], bool]] = [],
) -> "_Image":

Arguments:

Name	Type	Description
local_path	str | Path	The path to the local directory.
remote_path	str	The absolute path in the container where the directory will be placed.
copy	bool, optional	Targon copies files into the image. (Will change)
ignore	Sequence[str] | Callable[[Path], bool], optional	A list of file patterns or a function to ignore files.

Example:

import targon

# Copies the contents of ./src to /app in the container
image = targon.Image.debian_slim().add_local_dir("./src", "/app")

Image.entrypoint

Sets the ENTRYPOINT of the container image which specifies the main executable to run when a container starts.

note

The Targon runtime system automatically sets an entrypoint to manage the lifecycle of your remote function. Overriding it can prevent your function from running correctly and should only be done if you need to run a custom wrapper script before the Targon runtime is invoked.

def entrypoint(
    self,
    entrypoint_commands: list[str],
) -> "_Image":

Arguments:

Name	Type	Description
entrypoint_commands	list[str]	A list of strings for the entrypoint command.

Image.cmd

Sets the default command (CMD) for the container image. CMD provides default arguments for the ENTRYPOINT.

def cmd(self, cmd: list[str]) -> "_Image":

Arguments:

Name	Type	Description
cmd	list[str]	A list of strings for the default command.

Image.with_runtime

Manually injects the Targon runtime environment into an image. This gives you direct control over a process that normally happens automatically during app.deploy().

The runtime includes the necessary gRPC servers and web servers to execute your functions. This method is primarily useful for advanced CI/CD workflows where you might want to build and test a Targon-compatible image without performing a full deployment.

caution

Calling this method manually can interfere with the automatic runtime injection that happens during app.deploy(). A misconfigured runtime will cause your deployment to fail.

def with_runtime(
    self,
    app_file: Union[str, Path],
    app_module_name: str = "app"
) -> "_Image":

Arguments:

Name	Type	Description
app_file	str | Path	Path to the user's app file.
app_module_name	str, optional	The name of the module without the .py extension.