common-python-tasks 0.11.0__tar.gz → 0.11.1__tar.gz

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: common-python-tasks
-Version: 0.11.0
+Version: 0.11.1
 Summary: Opinionated Poe the Poet tasks for Python package development.
 Project-URL: Homepage, http://github.com/ci-sourcerer/common-python-tasks
 Project-URL: Source, http://github.com/ci-sourcerer/common-python-tasks.git
@@ -42,7 +42,7 @@ Read the [complete documentation](https://ci-sourcerer.github.io/common-python-t
 Add the package as a development dependency.
 
 ```shell
-uv add --dev common-python-tasks==0.11.0
+uv add --dev common-python-tasks==0.11.1
 ```
 
 Expose the default task set in `pyproject.toml`.

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/README.md

@@ -9,7 +9,7 @@ Read the [complete documentation](https://ci-sourcerer.github.io/common-python-t
 Add the package as a development dependency.
 
 ```shell
-uv add --dev common-python-tasks==0.11.0
+uv add --dev common-python-tasks==0.11.1
 ```
 
 Expose the default task set in `pyproject.toml`.

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/docs/configuration.md

@@ -44,7 +44,8 @@ Container variables are read by the host-side tasks unless their description exp
 | `CONTAINER_APT_PACKAGES` | Space-delimited APT packages installed in the runtime stage |
 | `CONTAINER_CUSTOM_ENTRYPOINT` | `[project.scripts]` key selected as the image entrypoint command |
 | `CONTAINER_DOCKER_BUILD_ARGS` | Shell-tokenized arguments passed directly to `docker build`; task arguments after `--` take precedence |
-| `CONTAINER_DOCKERFILE_HOOK_PATH` | Executable host script that modifies the rendered Dockerfile before the build |
+| `CONTAINER_DOCKERFILE_PATH` | Project-owned application Dockerfile used by `build-image`, `build`, and `release` instead of the bundled template |
+| `CONTAINER_DOCKERFILE_HOOK_PATH` | Executable host script that modifies the selected Dockerfile before the build |
 | `CONTAINER_PRUNE_KEEP` | Prior images kept after a build; `-1` disables pruning, `0` keeps only the latest, and `N` keeps the latest plus `N` prior images |
 
 ### Environment and extension settings

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/docs/tasks/container-images.md

@@ -1,6 +1,6 @@
 # Container images
 
-Container tasks are selected with the optional `containers` tag. They generate a multi-stage Dockerfile from the project metadata and container settings, build the application wheel, and install it in a non-root runtime image. A consuming project does not need to maintain its own application Dockerfile.
+Container tasks are selected with the optional `containers` tag. By default, they generate a multi-stage Dockerfile from the project metadata and container settings, build the application wheel, and install it in a non-root runtime image. A project can instead select a complete application Dockerfile that it owns.
 
 ```toml
 [tool.poe]
@@ -277,7 +277,28 @@ Do not use these declarations for secrets because their values persist in the im
 
 The `--env` and `--envfile` options on `run-container` and `container-shell` have ordinary `docker run` semantics. They affect only that container invocation and can override environment values embedded during the build.
 
-## Extending the runtime image
+## Using a project-owned Dockerfile
+
+Set `CONTAINER_DOCKERFILE_PATH` when a project owns its complete application Dockerfile. `build-image` and every aggregate task that invokes it, including `build` and `release`, use the same file instead of rendering the bundled template.
+
+```toml
+[tool.poe.env]
+CONTAINER_DOCKERFILE_PATH = "docker/Dockerfile"
+```
+
+The `--dockerfile-path` option overrides the environment setting for one invocation. The option is available on both the individual and aggregate tasks.
+
+```shell
+poe build-image --dockerfile-path docker/Dockerfile.ci
+poe build --dockerfile-path docker/Dockerfile.ci
+poe release --dockerfile-path docker/Dockerfile.release
+```
+
+The project root remains the Docker build context. Standard image naming, version and commit tags, metadata build arguments, `CONTAINER_DOCKER_BUILD_ARGS`, Dockerfile hooks, image pruning, and release-time image pushing continue to work. A normal custom build does not select a target stage, so the Dockerfile does not need the bundled `runtime` stage. A custom debug build selects a stage named `debug`.
+
+Settings that render content into the bundled template do not alter a project-owned Dockerfile. This includes `CONTAINER_APT_PACKAGES`, `CONTAINER_CUSTOM_ENTRYPOINT`, `CONTAINER_ENV`, extensions, and dependency-image mappings. Declare equivalent instructions in the project-owned Dockerfile when they are needed. BuildKit secrets derived from `UV_INDEX_*` credentials remain available as Docker build secrets, but the custom Dockerfile must mount them explicitly.
+
+## Extending the generated runtime image
 
 Use `CONTAINER_EXTENSION_FILES` to append project-owned Dockerfile fragments without replacing the generic Dockerfile. Its value is a colon-delimited list of paths, such as `Dockerfile.system:docker/Dockerfile.browser`.
 
@@ -295,11 +316,11 @@ Extension content is treated as raw Dockerfile syntax, not as a Jinja template.
 
 `CONTAINER_EXTENSIONS` selects extension bundles shipped in the installed package's `data/dockerfile_extensions/` directory. Bundle names are colon-delimited and are applied after local extension files. A bundle may accept one value with `bundle=value`; that value is passed to the first `ARG` declared by the bundle that has not already been assigned to another extension. Arguments are ignored with a warning when the bundle declares no `ARG`.
 
-Use an extension for additive runtime instructions. Use `CONTAINER_DOCKERFILE_HOOK_PATH` only when a change must rewrite another part of the generated Dockerfile. The hook must be an executable host-side script; it receives the generated Dockerfile path as its first argument and must edit that file in place. The hook also receives the following context variables.
+Use an extension for additive runtime instructions. Use `CONTAINER_DOCKERFILE_HOOK_PATH` only when a change must rewrite another part of the selected Dockerfile. The hook must be an executable host-side script; it receives a temporary copy of the selected Dockerfile as its first argument and must edit that file in place. The hook also receives the following context variables.
 
 | Variable | Meaning |
 | - | - |
-| `COMMON_PYTHON_TASKS_DOCKERFILE_PATH` | Generated Dockerfile path, matching the first script argument |
+| `COMMON_PYTHON_TASKS_DOCKERFILE_PATH` | Temporary selected Dockerfile path, matching the first script argument |
 | `COMMON_PYTHON_TASKS_DOCKER_CONTEXT` | Docker build context path |
 | `COMMON_PYTHON_TASKS_DOCKER_DEBUG` | `1` for a debug build, otherwise `0` |
 | `COMMON_PYTHON_TASKS_DOCKER_NO_CACHE` | `1` when `--no-cache` is active, otherwise `0` |
@@ -344,7 +365,7 @@ See [Container settings](../configuration.md#container-settings) for the complet
 
 | Task | Description |
 | - | - |
-| [`build-image`](reference/build-image.md) | Build the container image for this project using the Dockerfile template. |
+| [`build-image`](reference/build-image.md) | Build the container image using a project-owned or bundled Dockerfile. |
 | [`build-deps-image`](reference/build-deps-image.md) | Build only the container dependency collector image for this project. |
 | [`run-container`](reference/run-container.md) | Run the Docker image as a container for this project. |
 | [`push-image`](reference/push-image.md) | Push the Docker image for this project to the container registry. |

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/docs/tasks/reference/build-image.md

@@ -1,6 +1,6 @@
 # `poe build-image`
 
-Build the container image for this project using the Dockerfile template.
+Build the container image using a project-owned or bundled Dockerfile.
 
 **Category:** [`container-images`](../container-images.md)
 
@@ -9,7 +9,7 @@ Build the container image for this project using the Dockerfile template.
 ## Usage
 
 ```shell
-poe build-image [DOCKER_BUILD_ARGS...] [--debug] [--no-cache] [--plain] [--single-arch] [--dockerfile-hook-path DOCKERFILE_HOOK_PATH] [--container-env CONTAINER_ENV...] [--container-envfile CONTAINER_ENVFILE...]
+poe build-image [DOCKER_BUILD_ARGS...] [--debug] [--no-cache] [--plain] [--single-arch] [--dockerfile-path DOCKERFILE_PATH] [--dockerfile-hook-path DOCKERFILE_HOOK_PATH] [--container-env CONTAINER_ENV...] [--container-envfile CONTAINER_ENVFILE...]
 ```
 
 ## Arguments
@@ -21,6 +21,7 @@ poe build-image [DOCKER_BUILD_ARGS...] [--debug] [--no-cache] [--plain] [--singl
 | `--no-cache` | `boolean` | Do not use cache when building the image. | `false` |
 | `--plain` | `boolean` | Do not pretty-print output. | `false` |
 | `--single-arch` | `boolean` | Build images for a single architecture. | `false` |
-| `--dockerfile-hook-path` | `string` | Optional executable script path that can mutate the generated Dockerfile before build. Overrides CONTAINER_DOCKERFILE_HOOK_PATH if provided. | — |
+| `--dockerfile-path` | `string` | Optional project-owned Dockerfile. Overrides CONTAINER_DOCKERFILE_PATH if provided. | — |
+| `--dockerfile-hook-path` | `string` | Optional executable script path that can mutate the selected Dockerfile before build. Overrides CONTAINER_DOCKERFILE_HOOK_PATH if provided. | — |
 | `--container-env` | `string, repeatable` | Builder and runtime environment declarations as repeated KEY=VALUE values. | — |
 | `--container-envfile` | `string, repeatable` | Optional repeated list of files containing builder and runtime environment declarations. | — |

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/docs/tasks/reference/build.md

@@ -9,7 +9,7 @@ Build the project and its containers.
 ## Usage
 
 ```shell
-poe build [--debug] [--no-cache] [--plain] [--single-arch] [--container-env CONTAINER_ENV...] [--container-envfile CONTAINER_ENVFILE...]
+poe build [--debug] [--no-cache] [--plain] [--single-arch] [--dockerfile-path DOCKERFILE_PATH] [--container-env CONTAINER_ENV...] [--container-envfile CONTAINER_ENVFILE...]
 ```
 
 ## Arguments
@@ -20,5 +20,6 @@ poe build [--debug] [--no-cache] [--plain] [--single-arch] [--container-env CONT
 | `--no-cache` | `boolean` | Do not use cache when building the image. | `false` |
 | `--plain` | `boolean` | Do not pretty-print output. | `false` |
 | `--single-arch` | `boolean` | Build images for a single architecture. | `false` |
+| `--dockerfile-path` | `string` | Optional project-owned Dockerfile used for the image build. Overrides CONTAINER_DOCKERFILE_PATH if provided. | — |
 | `--container-env` | `string, repeatable` | Inline container environment variables as repeated KEY=VALUE values. | — |
 | `--container-envfile` | `string, repeatable` | Repeated list of container environment files. | — |

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/docs/tasks/reference/release.md

@@ -9,7 +9,7 @@ Run a full release flow for package and containers.
 ## Usage
 
 ```shell
-poe release [--component COMPONENT] [--stage STAGE] [--dry-run] [--debug] [--no-cache] [--plain] [--single-arch] [--container-env CONTAINER_ENV...] [--container-envfile CONTAINER_ENVFILE...] [--assets ASSETS...] [--repository REPOSITORY] [--repository-url REPOSITORY_URL] [--pre-script PRE_SCRIPT] [--post-script POST_SCRIPT]
+poe release [--component COMPONENT] [--stage STAGE] [--dry-run] [--debug] [--no-cache] [--plain] [--single-arch] [--dockerfile-path DOCKERFILE_PATH] [--container-env CONTAINER_ENV...] [--container-envfile CONTAINER_ENVFILE...] [--assets ASSETS...] [--repository REPOSITORY] [--repository-url REPOSITORY_URL] [--pre-script PRE_SCRIPT] [--post-script POST_SCRIPT]
 ```
 
 ## Arguments
@@ -23,6 +23,7 @@ poe release [--component COMPONENT] [--stage STAGE] [--dry-run] [--debug] [--no-
 | `--no-cache` | `boolean` | Do not use cache when building container images. | `false` |
 | `--plain` | `boolean` | Do not pretty-print container build output. | `false` |
 | `--single-arch` | `boolean` | Build container image for a single architecture. | `false` |
+| `--dockerfile-path` | `string` | Optional project-owned Dockerfile used for the image build. Overrides CONTAINER_DOCKERFILE_PATH if provided. | — |
 | `--container-env` | `string, repeatable` | Inline container environment variables as repeated KEY=VALUE values. | — |
 | `--container-envfile` | `string, repeatable` | Repeated list of container environment files. | — |
 | `--assets` | `string, repeatable` | Optional repeated list of release asset patterns or paths. | — |

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/scripts/docs_tasks_reference.py

@@ -111,46 +111,6 @@ def _escape_table_text(value: str) -> str:
     return value.replace("|", "\\|")
 
 
-def _render_task_full(task_name: str) -> list[str]:
-    task_config = _get_task_config(task_name)
-    arguments = task_config.get("args", [])
-    lines = [
-        f"## `{task_name}`",
-        "",
-        task_config.get("help", "No description is available."),
-        "",
-        f"**Tags:** {', '.join(f'`{tag}`' for tag in get_task_tags(task_name) or [])}",
-        "",
-        "```shell",
-        " ".join(
-            [f"poe {task_name}", *[_format_usage_argument(arg) for arg in arguments]]
-        ),
-        "```",
-    ]
-    if not arguments:
-        return lines
-
-    docstring_help = _get_docstring_argument_help(task_config)
-    lines.extend(
-        [
-            "",
-            "### Arguments",
-            "",
-            "| Argument | Type | Description | Default |",
-            "| - | - | - | - |",
-        ]
-    )
-    lines.extend(
-        "| "
-        f"{_format_argument_name(argument)} | "
-        f"{_format_argument_type(argument)} | "
-        f"{_escape_table_text(argument.get('help') or docstring_help.get(argument['name'], 'Additional value passed to the task.'))} | "
-        f"{_format_default(argument)} |"
-        for argument in arguments
-    )
-    return lines
-
-
 def build_task_reference(category: str) -> str:
     """Build the generated Markdown reference for a task category (link table).
 

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/src/common_python_tasks/env.py

@@ -3,6 +3,7 @@ import os
 import re
 import secrets
 import shlex
+from collections.abc import Iterator
 from pathlib import Path
 
 from . import utils
@@ -53,51 +54,47 @@ def collect_uv_index_credentials() -> list[dict[str, str | None]]:
     ]
 
 
+def _iter_uv_index_secrets(
+    credentials: list[dict[str, str | None]],
+) -> Iterator[tuple[str, str]]:
+    for credential in credentials:
+        index_name = credential["index_name"].lower()
+        for credential_type in ("username", "password"):
+            environment_name = credential[f"{credential_type}_env"]
+            if environment_name:
+                yield f"uv_index_{index_name}_{credential_type}", environment_name
+
+
 def uv_index_secret_mounts(credentials: list[dict[str, str | None]]) -> list[str]:
-    """Return Dockerfile ``--mount`` strings for UV index credentials.
+    """Return Dockerfile `--mount` strings for UV index credentials.
 
     Args:
         credentials: Output of `collect_uv_index_credentials`.
 
     Returns:
-        A list of ``type=secret,...`` strings for Dockerfile ``RUN --mount=``
+        A list of `type=secret,...` strings for Dockerfile `RUN --mount=`
         directives.
     """
-    mounts = []
-    for cred in credentials:
-        name = cred["index_name"].lower()
-        if cred["username_env"]:
-            mounts.append(
-                f"type=secret,id=uv_index_{name}_username,env={cred['username_env']}"
-            )
-        if cred["password_env"]:
-            mounts.append(
-                f"type=secret,id=uv_index_{name}_password,env={cred['password_env']}"
-            )
-    return mounts
+    return [
+        f"type=secret,id={secret_id},env={environment_name}"
+        for secret_id, environment_name in _iter_uv_index_secrets(credentials)
+    ]
 
 
 def uv_index_secret_build_args(credentials: list[dict[str, str | None]]) -> list[str]:
-    """Return ``docker build --secret`` arg pairs for UV index credentials.
+    """Return `docker build --secret` arg pairs for UV index credentials.
 
     Args:
         credentials: Output of `collect_uv_index_credentials`.
 
     Returns:
-        A flat list of ``--secret`` flag-value pairs for the docker build command.
+        A flat list of `--secret` flag-value pairs for the docker build command.
     """
-    args = []
-    for cred in credentials:
-        name = cred["index_name"].lower()
-        if cred["username_env"]:
-            args.extend(
-                ["--secret", f"id=uv_index_{name}_username,env={cred['username_env']}"]
-            )
-        if cred["password_env"]:
-            args.extend(
-                ["--secret", f"id=uv_index_{name}_password,env={cred['password_env']}"]
-            )
-    return args
+    return [
+        item
+        for secret_id, environment_name in _iter_uv_index_secrets(credentials)
+        for item in ("--secret", f"id={secret_id},env={environment_name}")
+    ]
 
 
 def env_truthy(env_var: str) -> bool:
@@ -330,6 +327,28 @@ def resolve_container_docker_build_args(
         utils.fatal(f"Invalid CONTAINER_DOCKER_BUILD_ARGS: {error}")
 
 
+def _resolve_optional_file_path(
+    cli_path: str | None,
+    environment_path: str | None,
+    description: str,
+) -> Path | None:
+    resolved_path = next(
+        (
+            Path(value.strip())
+            for value in (cli_path, environment_path)
+            if value and value.strip()
+        ),
+        None,
+    )
+    if resolved_path is None:
+        return None
+    if not resolved_path.exists():
+        utils.fatal(f"{description} not found: {resolved_path}")
+    if not resolved_path.is_file():
+        utils.fatal(f"{description} is not a file: {resolved_path}")
+    return resolved_path
+
+
 def resolve_container_dockerfile_hook_path(
     cli_hook_path: str | None, env_hook_path: str | None
 ) -> Path | None:
@@ -342,17 +361,13 @@ def resolve_container_dockerfile_hook_path(
     Returns:
         The validated hook path, or `None` when unset.
     """
-    raw_value = (
-        cli_hook_path if cli_hook_path and cli_hook_path.strip() else env_hook_path
+    hook_path = _resolve_optional_file_path(
+        cli_hook_path,
+        env_hook_path,
+        "Dockerfile hook script",
     )
-    if raw_value is None or not raw_value.strip():
+    if hook_path is None:
         return None
-
-    hook_path = Path(raw_value.strip())
-    if not hook_path.exists():
-        utils.fatal(f"Dockerfile hook script not found: {hook_path}")
-    if not hook_path.is_file():
-        utils.fatal(f"Dockerfile hook path is not a file: {hook_path}")
     if not os.access(hook_path, os.X_OK):
         utils.fatal(f"Dockerfile hook script must be executable: {hook_path}")
 
@@ -594,6 +609,28 @@ def get_container_deps_move_script() -> str | None:
     return inline_script if inline_script else None
 
 
+def resolve_container_dockerfile_path(
+    dockerfile_path: str | None,
+    environment_dockerfile_path: str | None,
+) -> Path | None:
+    """Resolve and validate a project-owned application Dockerfile.
+
+    Args:
+        dockerfile_path: Dockerfile path supplied directly to a task.
+        environment_dockerfile_path: Dockerfile path supplied through the
+            environment.
+
+    Returns:
+        The configured Dockerfile path, or `None` when the bundled template
+        should be used.
+    """
+    return _resolve_optional_file_path(
+        dockerfile_path,
+        environment_dockerfile_path,
+        "Container Dockerfile",
+    )
+
+
 def get_prune_keep() -> int:
     """Return the integer value of CONTAINER_PRUNE_KEEP.
 

{common_python_tasks-0.11.0 → common_python_tasks-0.11.1}/src/common_python_tasks/tasks.py

@@ -70,6 +70,28 @@ class _ContainerBuild(NamedTuple):
     commit_tag: str
 
 
+def _prune_container_images(version_tag: str, commit_tag: str) -> None:
+    from .docker import prune_images_keep
+    from .env import get_prune_keep
+    from .utils import get_full_image_name, get_package_name
+
+    keep = get_prune_keep()
+    if keep < 0:
+        return
+
+    LOGGER.debug(
+        "Pruning old images; keeping %d and protecting tags: %s",
+        keep,
+        [version_tag, commit_tag],
+    )
+    prune_images_keep(
+        get_full_image_name(),
+        get_package_name(),
+        keep,
+        protect_tags=[version_tag, commit_tag],
+    )
+
+
 def _make_var_positional_task_args_optional(
     func: callable, resolved_task_name: str
 ) -> None:
@@ -367,11 +389,19 @@ def clean(dist_only: bool = False) -> None:
         return
     else:
         to_clean = [
-            *[Path(p) for p in [".pytest_cache", "dist", ".mypy_cache"]],
+            *[
+                Path(p)
+                for p in [
+                    ".pytest_cache",
+                    "dist",
+                    ".mypy_cache",
+                    ".coverage",
+                    "coverage.xml",
+                    ".ruff_cache",
+                ]
+            ],
             *Path(".").rglob("__pycache__"),
             *Path(".").rglob("*.pyc"),
-            Path(".coverage"),
-            Path("coverage.xml"),
         ]
 
     for item in to_clean:
@@ -465,11 +495,12 @@ def build_image(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     dockerfile_hook_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
 ) -> _ContainerBuild:
-    """Build the container image for this project using the Dockerfile template.
+    """Build the container image using a project-owned or bundled Dockerfile.
 
     Args:
         *docker_build_args: Additional arguments passed directly to `docker build`.
@@ -479,8 +510,10 @@ def build_image(
         no_cache: Do not use cache when building the image.
         plain: Do not pretty-print output.
         single_arch: Build images for a single architecture.
+        dockerfile_path: Optional project-owned Dockerfile. Overrides
+            CONTAINER_DOCKERFILE_PATH if provided.
         dockerfile_hook_path: Optional executable script path that can mutate
-            the generated Dockerfile before build. Overrides
+            the selected Dockerfile before build. Overrides
             CONTAINER_DOCKERFILE_HOOK_PATH if provided.
         container_env: Builder and runtime environment declarations as repeated
             KEY=VALUE values.
@@ -494,14 +527,10 @@ def build_image(
         The generated Dockerfile text and image tags.
     """
     from .docker import build_image as _build_image
-    from .docker import (
-        prune_images_keep,
-    )
     from .env import (
         collect_uv_index_credentials,
         get_cache_id_suffix,
         get_container_deps_move_script,
-        get_prune_keep,
         get_python_variant,
         inject_auto_build_args_from_env,
         load_container_env_tokens,
@@ -511,6 +540,7 @@ def build_image(
         render_container_deps_move_script,
         resolve_container_docker_build_args,
         resolve_container_dockerfile_hook_path,
+        resolve_container_dockerfile_path,
         resolve_extension_content,
         uv_index_secret_build_args,
         uv_index_secret_mounts,
@@ -521,14 +551,17 @@ def build_image(
     )
     from .utils import (
         fatal,
-        get_full_image_name,
-        get_package_name,
         load_data_file,
         render_template_text,
     )
 
+    resolved_dockerfile_path = resolve_container_dockerfile_path(
+        dockerfile_path,
+        os.getenv("CONTAINER_DOCKERFILE_PATH"),
+    )
+
     # Determine extensions up-front so we can log a single, accurate message
-    extensions = parse_container_extensions()
+    extensions = [] if resolved_dockerfile_path else parse_container_extensions()
     extension_ids = [desc.get("id") for desc in extensions if desc.get("id")]
     if extension_ids:
         LOGGER.info("Building image (with extensions: %s)", ", ".join(extension_ids))
@@ -556,6 +589,29 @@ def build_image(
         dockerfile_hook_path,
         os.getenv("CONTAINER_DOCKERFILE_HOOK_PATH"),
     )
+    top_level_build_args = inject_auto_build_args_from_env(
+        {"PYTHON_VARIANT": get_python_variant()}
+    )
+
+    if resolved_dockerfile_path:
+        version_tag, commit_tag = _build_image(
+            dockerfile_path=resolved_dockerfile_path,
+            context_path=Path("."),
+            debug=debug,
+            no_cache=no_cache,
+            plain=plain,
+            single_arch=single_arch,
+            omit_target=not debug,
+            extra_build_args=top_level_build_args or None,
+            docker_build_args=resolved_docker_build_args,
+            dockerfile_hook_path=resolved_dockerfile_hook_path,
+        )
+        _prune_container_images(version_tag, commit_tag)
+        return _ContainerBuild(
+            dockerfile_text=resolved_dockerfile_path.read_text(encoding="utf-8"),
+            version_tag=version_tag,
+            commit_tag=commit_tag,
+        )
 
     has_debug_deps = has_debug_dependency_group()
     if debug and not has_debug_deps:
@@ -579,9 +635,6 @@ def build_image(
             "Injecting builder and runtime env vars: %s",
             ", ".join(container_env_vars),
         )
-    top_level_build_args = inject_auto_build_args_from_env(
-        {"PYTHON_VARIANT": get_python_variant()}
-    )
     external_deps_image = _get_container_build_setting("CONTAINER_DEPS_IMAGE")
     if external_deps_image:
         top_level_build_args["CONTAINER_DEPS_IMAGE"] = external_deps_image
@@ -691,16 +744,7 @@ def build_image(
         dockerfile_hook_path=resolved_dockerfile_hook_path,
     )
 
-    keep = get_prune_keep()
-    if keep >= 0:
-        # Protect the tags created by this build
-        protect = [t for t in (version_tag, commit_tag) if t is not None]
-        LOGGER.debug(
-            "Pruning old images; keeping %d and protecting tags: %s", keep, protect
-        )
-        prune_images_keep(
-            get_full_image_name(), get_package_name(), keep, protect_tags=protect
-        )
+    _prune_container_images(version_tag, commit_tag)
 
     return _ContainerBuild(
         dockerfile_text=dockerfile_text,
@@ -1320,6 +1364,7 @@ def _run_release_flow(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
     assets: list[str] | None = None,
@@ -1426,6 +1471,7 @@ def _run_release_flow(
             no_cache=no_cache,
             plain=plain,
             single_arch=single_arch,
+            dockerfile_path=dockerfile_path,
             container_env=container_env,
             container_envfile=container_envfile,
         )
@@ -1444,6 +1490,7 @@ def release(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
     assets: list[str] | None = None,
@@ -1462,6 +1509,8 @@ def release(
         no_cache: Do not use cache when building container images.
         plain: Do not pretty-print container build output.
         single_arch: Build container image for a single architecture.
+        dockerfile_path: Optional project-owned Dockerfile used for the image
+            build. Overrides CONTAINER_DOCKERFILE_PATH if provided.
         container_env: Inline container environment variables as repeated
             KEY=VALUE values.
         container_envfile: Repeated list of container environment files.
@@ -1480,6 +1529,7 @@ def release(
         no_cache=no_cache,
         plain=plain,
         single_arch=single_arch,
+        dockerfile_path=dockerfile_path,
         container_env=container_env,
         container_envfile=container_envfile,
         assets=assets,
@@ -1532,6 +1582,7 @@ def build(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
 ) -> None:
@@ -1544,6 +1595,8 @@ def build(
         no_cache: Pass `--no-cache` to the Docker build command.
         plain: Pass `--progress plain` to the Docker build command.
         single_arch: Build the container for the current host architecture only.
+        dockerfile_path: Optional project-owned Dockerfile used for the image
+            build. Overrides CONTAINER_DOCKERFILE_PATH if provided.
         container_env: Inline container environment variables as repeated
             `KEY=VALUE` values.
         container_envfile: Repeated list of container environment files.
@@ -1558,6 +1611,7 @@ def build(
             no_cache=no_cache,
             plain=plain,
             single_arch=single_arch,
+            dockerfile_path=dockerfile_path,
             container_env=container_env,
             container_envfile=container_envfile,
         )
@@ -1572,6 +1626,7 @@ def build_with_containers(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
 ) -> None:
@@ -1582,6 +1637,8 @@ def build_with_containers(
         no_cache: Do not use cache when building the image.
         plain: Do not pretty-print output.
         single_arch: Build images for a single architecture.
+        dockerfile_path: Optional project-owned Dockerfile used for the image
+            build. Overrides CONTAINER_DOCKERFILE_PATH if provided.
         container_env: Inline container environment variables as repeated KEY=VALUE
             values.
         container_envfile: Repeated list of container environment files.
@@ -1593,6 +1650,7 @@ def build_with_containers(
         no_cache=no_cache,
         plain=plain,
         single_arch=single_arch,
+        dockerfile_path=dockerfile_path,
         container_env=container_env,
         container_envfile=container_envfile,
     )