Skip to content

Image

Represents a container image for a job.

The image is defined based on Python dependencies and two build scripts expressed as Dockerfile commands.

Python dependencies and version can come from a project's pyproject.toml: pass its path, or pass "auto" to use the pyproject.toml of the project that contains the job's module.

Parameters:

  • python_version

    (str, default: 'auto' ) –

    Python version string, path to a pyproject.toml, or "auto".

  • python_requirements

    (str | list[str], default: '' ) –

    Requirements spec, file path, list, or "auto".

  • build_script_pre

    (str, default: '' ) –

    Pre-build Dockerfile commands or file path.

  • build_script_post

    (str, default: '' ) –

    Post-build Dockerfile commands or file path.

  • build_secret_keys

    (list[str] | None, default: None ) –

    Names of build secrets to expose to the build scripts and the Python requirements.

  • branch_name

    (str | None, default: None ) –

    Git branch name for the repo, if applicable.

  • commit_hash

    (str | None, default: None ) –

    Git commit hash for the repo, if applicable.

  • path_to_repo

    (str | None, default: None ) –

    Path to the repository root, if applicable.

  • path_to_module

    (str | None, default: None ) –

    Path to the Python module, if applicable.

Attributes:

  • python_version (str) –

    Resolved Python version string.

  • python_requirements (str) –

    Requirements string (newline-delimited).

  • build_script_pre (str) –

    Pre-build Dockerfile commands.

  • build_script_post (str) –

    Post-build Dockerfile commands.

  • build_secret_keys (list[str]) –

    Names of build secrets exposed to the build scripts and the Python requirements.

  • branch_name (str | None) –

    Git branch name.

  • commit_hash (str | None) –

    Git commit hash.

  • path_to_repo (str | None) –

    Path to the repository root.

  • path_to_module (str | None) –

    Path to the Python module.

  • build_stdout (str | None) –

    Stdout captured from the last build, if any.

  • build_stderr (str | None) –

    Stderr captured from the last build, if any.

  • name (str | None) –

    Built image name, if any.

  • last_build_succeeded (bool | None) –

    Whether the last build succeeded.

  • bundle_name (str | None) –

    Bundle name, if any.

  • registry (str | None) –

    Registry URL or name, if any.

  • run_after_build (bool | None) –

    Whether to run after build.

  • tag (str | None) –

    Image tag, if any.

Parameters:

  • python_version

    (str, default: 'auto' ) –

    Python version for the container (e.g. "3.12"). Accepts a path to a pyproject.toml file, in which case the version comes from the .python-version file next to it or from requires-python (see below). Use "auto" to read it from the job's project pyproject.toml, falling back to the current interpreter version.

  • python_requirements

    (str | list[str], default: '' ) –

    Python dependencies. Accepts a pip-freeze string, a list of package specifiers, a path to a requirements.txt file, a path to a pyproject.toml file (its [project].dependencies are used), or "auto". "auto" uses the dependencies of the job's project pyproject.toml, falling back to freezing the current interpreter (python -m pip freeze). Requirements are resolved on every build, so unpinned ones pick up new releases; unchanged versions reuse the previous build's packages. A package re-uploaded under the same version is not picked up.

  • build_script_pre

    (str, default: '' ) –

    Dockerfile commands to execute before installing Python requirements. Can be a string or a file path.

  • build_script_post

    (str, default: '' ) –

    Dockerfile commands to execute after installing Python requirements. Can be a string or a file path.

  • build_secret_keys

    (list[str] | None, default: None ) –

    Names of build secrets that the build scripts or the Python requirements need. Values are stored in the Secret Keys Manager under Build Secrets (or with dt kv put -s build/<key>) and are read with the job's run_as user's permissions when the image is built. Each one is available to build_script_pre and build_script_post as the environment variable DT_BUILD_SECRET_<key>, with /, . and - in the key replaced by _. A line of python_requirements can use the variable too, with the whole name in upper case, as ${DT_BUILD_SECRET_<KEY>}, but only as the user or the password of a URL, for example the URL of a private package index. The values are never stored in the image. The build fails if a secret is missing or not accessible.

  • branch_name

    (str | None, default: None ) –

    Git branch name (populated automatically during build).

  • commit_hash

    (str | None, default: None ) –

    Git commit hash (populated automatically during build).

  • path_to_repo

    (str | None, default: None ) –

    Absolute path to the source repository root.

  • path_to_module

    (str | None, default: None ) –

    Relative path from the repository root to the Python module containing the entrypoint.

"auto" looks for a pyproject.toml with a [project] table in the job's module directory and its parents, up to the repository root. It takes effect once path_to_repo and path_to_module are known, which happens automatically when the image belongs to a job. From requires-python the image uses an exact pin such as ==3.11.5 as is, otherwise the current interpreter version if it satisfies the constraint, and else the newest supported version that does (see :func:datatailr.build.pyproject.read_python_version).

Example

Image(python_requirements=["pandas", "numpy"]).python_requirements 'pandas\nnumpy'

from_dict

Create an Image instance from a dictionary representation.

to_dict

Convert the Image instance to a dictionary representation.

to_json

Convert the Image instance to a JSON string representation.

update

Update one or more Image attributes.

Parameters:

  • **kwargs

    (Any, default: {} ) –

    Attribute names and their new values.

Raises:

  • TypeError –

    If a string-only attribute receives a non-string value.

  • AttributeError –

    If an attribute name does not exist on the Image.