common-python-tasks 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

common_python_tasks/__init__.py

@@ -11,6 +11,15 @@ __all__ = ["TaskCollection"]
 def tasks(
     include_tags: "Sequence[str] | None" = None, exclude_tags: "Sequence[str]" = tuple()
 ) -> dict:
+    """Return the task collection filtered by the requested tags.
+
+    Args:
+        include_tags: Tags that selected tasks must have. Defaults to `common`.
+        exclude_tags: Tags that selected tasks must not have.
+
+    Returns:
+        The filtered Poe task collection configuration.
+    """
     from .tasks import tasks as task_collection
 
     if include_tags is None and not exclude_tags:

common_python_tasks/__main__.py

@@ -9,6 +9,19 @@ from .tasks import tasks
 __all__ = ["get_available_tasks", "print_available_tasks"]
 
 
+def _is_package_task(task_name: str) -> bool:
+    task_config = tasks()["tasks"].get(task_name)
+    if not isinstance(task_config, dict):
+        return False
+
+    script = task_config.get("script")
+    if not isinstance(script, str) or ":" not in script:
+        return False
+
+    module_name, _ = script.split(":", 1)
+    return module_name.startswith("common_python_tasks.")
+
+
 def get_available_tasks(internal: bool = False) -> list[str]:
     """Return available task names for this package.
 
@@ -21,7 +34,7 @@ def get_available_tasks(internal: bool = False) -> list[str]:
     return [
         task_name
         for task_name in tasks()["tasks"]
-        if internal or not task_name.startswith("_")
+        if _is_package_task(task_name) and (internal or not task_name.startswith("_"))
     ]
 
 
@@ -49,8 +62,11 @@ def _get_task_docstring(task_name: str) -> str | None:
 
     module_name, func_name = script.split(":", 1)
 
-    module = importlib.import_module(module_name)
-    func = getattr(module, func_name)
+    try:
+        module = importlib.import_module(module_name)
+        func = getattr(module, func_name)
+    except (ImportError, AttributeError):
+        return None
 
     doc = inspect.getdoc(func)
     if not doc:

common_python_tasks/data/fastapi/alembic.ini.j2

@@ -5,16 +5,15 @@ prepend_sys_path = .
 output_encoding = utf-8
 
 [post_write_hooks]
-hooks = black,isort
+hooks = ruff_check,ruff_format
 
-black.type = console_scripts
-black.entrypoint = black
+ruff_check.type = exec
+ruff_check.executable = ruff
+ruff_check.options = check --fix-only --select F401,I REVISION_SCRIPT_FILENAME
 
-autoflake.type = console_scripts
-autoflake.entrypoint = autoflake
-
-isort.type = console_scripts
-isort.entrypoint = isort
+ruff_format.type = exec
+ruff_format.executable = ruff
+ruff_format.options = format REVISION_SCRIPT_FILENAME
 
 # Logging configuration
 [loggers]

common_python_tasks/data/generic/Dockerfile.j2

@@ -93,17 +93,17 @@ ENV {{ env_var }}
 {%- endif %}
 
 ENV DEBIAN_FRONTEND=noninteractive
-{% if APT_PACKAGES %}
+{% if CONTAINER_APT_PACKAGES %}
 # Install optional runtime apt packages selected by Python-side template rendering
 RUN --mount=type=cache,target=/var/cache/apt,id=apt-cache{{ CACHE_ID_SUFFIX }} \
     --mount=type=cache,target=/var/lib/apt/lists,sharing=locked,id=apt-lists{{ CACHE_ID_SUFFIX }} \
-    apt-get update && apt-get install -y --no-install-recommends {{ APT_PACKAGES }}
+    apt-get update && apt-get install -y --no-install-recommends {{ CONTAINER_APT_PACKAGES }}
 {% endif %}
-{% if DEPS_IMAGE %}
+{% if CONTAINER_DEPS_IMAGE %}
 
 # Pull external dependencies from the pre-built deps image
-ARG DEPS_IMAGE
-COPY --from={{ DEPS_IMAGE }} /tmp/deps /tmp/deps
+ARG CONTAINER_DEPS_IMAGE
+COPY --from={{ CONTAINER_DEPS_IMAGE }} /tmp/deps /tmp/deps
 {% endif %}
 {% if CONTAINER_DEPS_MOVE_SCRIPT %}
 RUN set -eux; \

common_python_tasks/data/generic/ruff.toml

@@ -0,0 +1,2 @@
+line-length = 88
+extend-exclude = [".dist", ".poetry", "build"]

common_python_tasks/docker.py

@@ -3,8 +3,10 @@ import logging
 import platform
 import re
 import tempfile
+from dataclasses import dataclass
 from enum import IntEnum, StrEnum
 from pathlib import Path
+from shlex import quote
 from typing import Sequence
 
 from . import git, project, utils
@@ -65,10 +67,7 @@ def _merge_build_args(
     return build_args
 
 
-def _create_temp_dockerfile(
-    dockerfile_text: str,
-    prefix: str,
-) -> tuple[Path, str]:
+def _create_temp_dockerfile(dockerfile_text: str, prefix: str) -> tuple[Path, str]:
     with tempfile.NamedTemporaryFile(
         mode="w",
         encoding="utf-8",
@@ -101,11 +100,11 @@ def _build_docker_build_command(
     plain: bool,
     target: BuildStage | None = None,
     tags: Sequence[str] | None = None,
+    docker_build_args: Sequence[str] | None = None,
 ) -> list[str]:
     build_cmd = [
         "docker",
         "build",
-        str(context_path),
         "-f",
         str(dockerfile_path),
     ]
@@ -124,10 +123,267 @@ def _build_docker_build_command(
             build_cmd += ["-t", tag]
     if plain:
         build_cmd += ["--progress", "plain"]
+    if docker_build_args:
+        build_cmd += [str(arg) for arg in docker_build_args]
+    build_cmd.append(str(context_path))
 
     return build_cmd
 
 
+def _run_dockerfile_hook(
+    hook_path: Path,
+    dockerfile_path: Path,
+    context_path: Path,
+    debug: bool,
+    no_cache: bool,
+    plain: bool,
+    single_arch: bool,
+) -> None:
+    utils.run_command(
+        [hook_path, dockerfile_path],
+        env={
+            "COMMON_PYTHON_TASKS_DOCKERFILE_PATH": str(dockerfile_path),
+            "COMMON_PYTHON_TASKS_DOCKER_CONTEXT": str(context_path),
+            "COMMON_PYTHON_TASKS_DOCKER_DEBUG": "1" if debug else "0",
+            "COMMON_PYTHON_TASKS_DOCKER_NO_CACHE": "1" if no_cache else "0",
+            "COMMON_PYTHON_TASKS_DOCKER_PLAIN": "1" if plain else "0",
+            "COMMON_PYTHON_TASKS_DOCKER_SINGLE_ARCH": "1" if single_arch else "0",
+        },
+        always_show_command=True,
+    )
+
+
+@dataclass(frozen=True)
+class RenderedBuildPlan:
+    """Canonical render of a Docker image build command and generated artifacts."""
+
+    dockerfile_text: str
+    dockerfile_path: Path
+    context_path: Path
+    build_args: dict[str, str]
+    tags: list[str]
+    version_tag: str
+    commit_tag: str
+    command: list[str]
+    command_display: str
+    target: BuildStage | None = None
+
+
+def render_build_image(
+    dockerfile_path: Path | None = None,
+    dockerfile_text: str | None = None,
+    context_path: Path | None = None,
+    debug: bool = False,
+    no_cache: bool = False,
+    plain: bool = False,
+    single_arch: bool = False,
+    omit_target: bool = False,
+    image_name: str | None = None,
+    extra_build_args: dict[str, str] | None = None,
+    docker_build_args: Sequence[str] | None = None,
+    dockerfile_hook_path: Path | None = None,
+    keep_generated_files: bool = True,
+) -> RenderedBuildPlan:
+    """Render the canonical Docker build command without executing it.
+
+    Args:
+        dockerfile_path: Existing Dockerfile path to build from.
+        dockerfile_text: Dockerfile content to render into a temporary file.
+        context_path: Build context directory.
+        debug: Whether the debug image target should be used.
+        no_cache: Whether the Docker build should bypass cache.
+        plain: Whether Docker output should be plain text.
+        single_arch: Whether to limit the build to the current architecture.
+        omit_target: Whether to omit the target stage from the command.
+        image_name: Optional image name override.
+        extra_build_args: Extra build-time arguments.
+        docker_build_args: Additional arguments passed directly to `docker build`.
+        dockerfile_hook_path: Optional executable script path that can mutate
+            the generated Dockerfile in-place before build.
+        keep_generated_files: Whether to leave the generated Dockerfile in place.
+
+    Returns:
+        The rendered build plan that contains the command and generated artifacts.
+    """
+    dist_path = Path("dist")
+    if utils.directory_has_contents(dist_path):
+        utils.remove_path(dist_path)
+
+    context_path = _resolve_context_path(context_path)
+
+    temp_file_path = None
+    temp_dockerignore_created = False
+    dockerignore_path = context_path / ".dockerignore"
+    if dockerfile_path is None:
+        if dockerfile_text is None:
+            utils.fatal("Either dockerfile_path or dockerfile_text must be provided.")
+        dockerfile_path, temp_file_path = _create_temp_dockerfile(
+            dockerfile_text,
+            prefix="Dockerfile.",
+        )
+
+    if not dockerignore_path.exists():
+        LOGGER.debug("No .dockerignore found; using built-in .dockerignore")
+        builtin_dockerignore_content = utils.load_data_file(".dockerignore")[1]
+        dockerignore_path.write_text(builtin_dockerignore_content, encoding="utf-8")
+        temp_dockerignore_created = True
+
+    try:
+        if dockerfile_hook_path is not None:
+            if temp_file_path is None:
+                dockerfile_path, temp_file_path = _create_temp_dockerfile(
+                    dockerfile_path.read_text(encoding="utf-8"),
+                    prefix="Dockerfile.hooked.",
+                )
+            _run_dockerfile_hook(
+                dockerfile_hook_path,
+                dockerfile_path,
+                context_path,
+                debug,
+                no_cache,
+                plain,
+                single_arch,
+            )
+
+        archs = _resolve_archs(single_arch)
+        files_to_ignore = [Path(".dockerignore")] if temp_dockerignore_created else []
+        package_version = git.get_version(ignore=files_to_ignore)
+        version_string = git.get_image_tag(ignore=files_to_ignore)
+
+        dockerfile_source = dockerfile_path.read_text(encoding="utf-8")
+        if (
+            debug
+            and not omit_target
+            and not re.search(
+                rf"^\s*FROM\s+\S+\s+AS\s+{BuildStage.DEBUG}\s*$",
+                dockerfile_source,
+                re.IGNORECASE | re.MULTILINE,
+            )
+        ):
+            utils.fatal(
+                "Debug build requested, but the rendered Dockerfile has no debug stage. "
+                "Add a non-empty [dependency-groups].debug in pyproject.toml or build without debug."
+            )
+
+        if debug:
+            suffix = BuildSuffix.DEBUG
+            target = BuildStage.DEBUG
+            tag = BuildTag.DEBUG
+        else:
+            suffix = BuildSuffix.NONE
+            target = BuildStage.RUNTIME
+            tag = BuildTag.LATEST if not git.has_tags_later_in_history() else None
+
+        version_tag = f"{version_string}{suffix}"
+        if git.git_available():
+            commit_hash = utils.run_command(
+                ["git", "rev-parse", "--short", "HEAD"],
+                capture_output=True,
+                acceptable_returncodes={0},
+            ).stdout.strip()
+            dirty_suffix = (
+                "-dirty" if git.get_dirty_files(ignore=files_to_ignore) else ""
+            )
+            commit_tag = f"{commit_hash}{dirty_suffix}{suffix}"
+        else:
+            commit_tag = version_tag
+
+        python_version = platform.python_version()
+        package_manager = project.get_package_manager()
+        package_manager_version = project.get_package_manager_version(package_manager)
+
+        manager_build_args: dict[str, str | None]
+        if package_manager == project.PackageManager.POETRY:
+            manager_build_args = {
+                "POETRY_VERSION": package_manager_version,
+                "POETRY_DYNAMIC_VERSIONING_PLUGIN_VERSION": project.get_installed_requirement_version(
+                    "poetry-dynamic-versioning[plugin]"
+                ),
+                "POETRY_PLUGIN_EXPORT_VERSION": project.get_installed_requirement_version(
+                    "poetry-plugin-export"
+                ),
+            }
+        else:
+            manager_build_args = {
+                "UV_VERSION": package_manager_version,
+            }
+
+        build_args = _merge_build_args(
+            {
+                "PYTHON_VERSION": python_version,
+                "PACKAGE_MANAGER": package_manager,
+                "PACKAGE_MANAGER_VERSION": package_manager_version,
+                "PACKAGE_VERSION": package_version,
+                "PACKAGE_NAME": utils.get_package_name(use_underscores=True),
+                "AUTHORS": ",".join(
+                    [f"{name} <{email}>" for name, email in project.get_authors()]
+                ),
+                "GIT_COMMIT": commit_tag,
+                **manager_build_args,
+            },
+            extra_build_args,
+        )
+
+        build_args.setdefault("WORKDIR_PATH", get_workdir_path())
+
+        tags_to_use = [t for t in (tag, version_tag, commit_tag) if t is not None]
+        LOGGER.debug("Building image with tags: %s", ", ".join(tags_to_use))
+        image_short_name = (
+            image_name if image_name is not None else utils.get_package_name()
+        )
+        orig_full_name = utils.get_full_image_name()
+
+        parsed_full_name = utils.parse_image_reference(orig_full_name)
+        short_tags = [
+            utils.compose_image_name(image_short_name, tag=t, fully_qualified=False)
+            for t in tags_to_use
+        ]
+        full_tags = [
+            utils.compose_image_name(
+                image_short_name,
+                tag=t,
+                registry=parsed_full_name["registry"],
+                namespace=parsed_full_name["namespace"],
+            )
+            for t in tags_to_use
+        ]
+
+        all_tags = []
+        for resolved_tag in [*short_tags, *full_tags]:
+            if resolved_tag not in all_tags:
+                all_tags.append(resolved_tag)
+
+        build_cmd = _build_docker_build_command(
+            context_path,
+            dockerfile_path,
+            build_args,
+            archs,
+            no_cache,
+            plain,
+            target=None if omit_target else target,
+            tags=all_tags,
+            docker_build_args=docker_build_args,
+        )
+        command_display = " ".join(quote(str(arg)) for arg in build_cmd)
+        return RenderedBuildPlan(
+            dockerfile_text=dockerfile_source,
+            dockerfile_path=dockerfile_path,
+            context_path=context_path,
+            build_args=build_args,
+            tags=all_tags,
+            version_tag=version_tag,
+            commit_tag=commit_tag,
+            command=build_cmd,
+            command_display=command_display,
+            target=None if omit_target else target,
+        )
+    finally:
+        if not keep_generated_files:
+            _safe_unlink(temp_file_path)
+            if temp_dockerignore_created:
+                _safe_unlink(dockerignore_path)
+
+
 def prune_images_keep(
     full_name: str,
     package_name: str,
@@ -241,6 +497,7 @@ def build_deps_image(
     plain: bool = False,
     single_arch: bool = False,
     extra_build_args: dict[str, str] | None = None,
+    docker_build_args: Sequence[str] | None = None,
     cache_id_suffix: str = "",
 ) -> str:
     """Build the dependency collector image and return its full tag.
@@ -253,6 +510,7 @@ def build_deps_image(
         plain: If `True`, use plain output mode for the Docker build.
         single_arch: If `True`, build the image for the current host architecture only.
         extra_build_args: Additional build arguments for the Docker build as a dictionary of `KEY: VALUE` pairs.
+        docker_build_args: Additional arguments passed directly to `docker build`.
         cache_id_suffix: A suffix to append to the cache ID.
 
     Returns:
@@ -337,6 +595,7 @@ def build_deps_image(
         no_cache,
         plain,
         tags=[full_tag],
+        docker_build_args=docker_build_args,
     )
 
     LOGGER.info("Building deps image: %s", full_tag)
@@ -359,6 +618,8 @@ def build_image(
     omit_target: bool = False,
     image_name: str | None = None,
     extra_build_args: dict[str, str] | None = None,
+    docker_build_args: Sequence[str] | None = None,
+    dockerfile_hook_path: Path | None = None,
 ) -> tuple[str, str]:
     """Build the primary image and return its version and commit tags.
 
@@ -373,165 +634,44 @@ def build_image(
         omit_target: If `True`, omit the target stage.
         image_name: Name of the image to build.
         extra_build_args: Additional build arguments for the Docker build as a dictionary of `KEY: VALUE` pairs.
+        docker_build_args: Additional arguments passed directly to `docker build`.
+        dockerfile_hook_path: Optional executable script path that can mutate
+            the generated Dockerfile in-place before build.
 
     Returns:
         A tuple containing the version tag and commit tag of the built image.
     """
-    dist_path = Path("dist")
-    if utils.directory_has_contents(dist_path):
-        utils.remove_path(dist_path)
-
     context_path = _resolve_context_path(context_path)
-
-    temp_file_path = None
-    if dockerfile_path is None:
-        if dockerfile_text is None:
-            utils.fatal("Either dockerfile_path or dockerfile_text must be provided.")
-        dockerfile_path, temp_file_path = _create_temp_dockerfile(
-            dockerfile_text,
-            prefix="Dockerfile.",
-        )
-
     dockerignore_path = context_path / ".dockerignore"
-    temp_dockerignore_created = False
-    if not dockerignore_path.exists():
-        LOGGER.debug("No .dockerignore found; using built-in .dockerignore")
-        builtin_dockerignore_content = utils.load_data_file(".dockerignore")[1]
-        dockerignore_path.write_text(builtin_dockerignore_content, encoding="utf-8")
-        temp_dockerignore_created = True
+    dockerignore_existed = dockerignore_path.exists()
+    temp_dockerfile_created = dockerfile_path is None
 
-    delete_temp_file = False
+    plan = render_build_image(
+        dockerfile_path=dockerfile_path,
+        dockerfile_text=dockerfile_text,
+        context_path=context_path,
+        debug=debug,
+        no_cache=no_cache,
+        plain=plain,
+        single_arch=single_arch,
+        omit_target=omit_target,
+        image_name=image_name,
+        extra_build_args=extra_build_args,
+        docker_build_args=docker_build_args,
+        dockerfile_hook_path=dockerfile_hook_path,
+        keep_generated_files=True,
+    )
     try:
-        archs = _resolve_archs(single_arch)
-        files_to_ignore = [Path(".dockerignore")] if temp_dockerignore_created else []
-        package_version = git.get_version(ignore=files_to_ignore)
-        version_string = git.get_image_tag(ignore=files_to_ignore)
-
-        dockerfile_source = (
-            dockerfile_text
-            if dockerfile_text is not None
-            else dockerfile_path.read_text(encoding="utf-8")
-        )
-        if (
-            debug
-            and not omit_target
-            and not re.search(
-                rf"^\s*FROM\s+\S+\s+AS\s+{BuildStage.DEBUG}\s*$",
-                dockerfile_source,
-                re.IGNORECASE | re.MULTILINE,
-            )
-        ):
-            utils.fatal(
-                "Debug build requested, but the rendered Dockerfile has no debug stage. "
-                "Add a non-empty [dependency-groups].debug in pyproject.toml or build without debug."
-            )
-
-        if debug:
-            suffix = BuildSuffix.DEBUG
-            target = BuildStage.DEBUG
-            tag = BuildTag.DEBUG
-        else:
-            suffix = BuildSuffix.NONE
-            target = BuildStage.RUNTIME
-            tag = BuildTag.LATEST if not git.has_tags_later_in_history() else None
-
-        version_tag = f"{version_string}{suffix}"
-        if git.git_available():
-            commit_hash = utils.run_command(
-                ["git", "rev-parse", "--short", "HEAD"],
-                capture_output=True,
-                acceptable_returncodes={0},
-            ).stdout.strip()
-            dirty_suffix = (
-                "-dirty" if git.get_dirty_files(ignore=files_to_ignore) else ""
-            )
-            commit_tag = f"{commit_hash}{dirty_suffix}{suffix}"
-        else:
-            commit_tag = version_tag
-
-        python_version = platform.python_version()
-        package_manager = project.get_package_manager()
-        package_manager_version = project.get_package_manager_version(package_manager)
-
-        manager_build_args: dict[str, str | None]
-        if package_manager == project.PackageManager.POETRY:
-            manager_build_args = {
-                "POETRY_VERSION": package_manager_version,
-                "POETRY_DYNAMIC_VERSIONING_PLUGIN_VERSION": project.get_installed_requirement_version(
-                    "poetry-dynamic-versioning[plugin]"
-                ),
-                "POETRY_PLUGIN_EXPORT_VERSION": project.get_installed_requirement_version(
-                    "poetry-plugin-export"
-                ),
-            }
-        else:
-            manager_build_args = {
-                "UV_VERSION": package_manager_version,
-            }
-
-        build_args = _merge_build_args(
-            {
-                "PYTHON_VERSION": python_version,
-                "PACKAGE_MANAGER": package_manager,
-                "PACKAGE_MANAGER_VERSION": package_manager_version,
-                "PACKAGE_VERSION": package_version,
-                "PACKAGE_NAME": utils.get_package_name(use_underscores=True),
-                "AUTHORS": ",".join(
-                    [f"{name} <{email}>" for name, email in project.get_authors()]
-                ),
-                "GIT_COMMIT": commit_tag,
-                **manager_build_args,
-            },
-            extra_build_args,
-        )
-
-        build_args.setdefault("WORKDIR_PATH", get_workdir_path())
-
-        tags_to_use = [t for t in (tag, version_tag, commit_tag) if t is not None]
-        LOGGER.debug("Building image with tags: %s", ", ".join(tags_to_use))
-        image_short_name = (
-            image_name if image_name is not None else utils.get_package_name()
-        )
-        orig_full_name = utils.get_full_image_name()
-
-        parsed_full_name = utils.parse_image_reference(orig_full_name)
-        short_tags = [
-            utils.compose_image_name(image_short_name, tag=t, fully_qualified=False)
-            for t in tags_to_use
-        ]
-        full_tags = [
-            utils.compose_image_name(
-                image_short_name,
-                tag=t,
-                registry=parsed_full_name["registry"],
-                namespace=parsed_full_name["namespace"],
-            )
-            for t in tags_to_use
-        ]
-
-        all_tags = []
-        for resolved_tag in [*short_tags, *full_tags]:
-            if resolved_tag not in all_tags:
-                all_tags.append(resolved_tag)
-
-        build_cmd = _build_docker_build_command(
-            context_path,
-            dockerfile_path,
-            build_args,
-            archs,
-            no_cache,
-            plain,
-            target=None if omit_target else target,
-            tags=all_tags,
-        )
-        utils.run_command(build_cmd)
-        delete_temp_file = True
+        utils.run_command(plan.command)
     finally:
-        if temp_file_path is not None and delete_temp_file:
-            _safe_unlink(dockerfile_path)
-        if temp_dockerignore_created:
+        if temp_dockerfile_created or (
+            dockerfile_path is not None and plan.dockerfile_path != dockerfile_path
+        ):
+            _safe_unlink(plan.dockerfile_path)
+        if not dockerignore_existed:
             _safe_unlink(dockerignore_path)
-    return version_tag, commit_tag
+
+    return plan.version_tag, plan.commit_tag
 
 
 def build_extension_image(

common_python_tasks/docker_compose.py

@@ -35,6 +35,13 @@ def ensure_alembic_config(compose_type: str) -> tuple[Path | None, bool]:
         LOGGER.debug("Using existing alembic.ini")
         return alembic_ini_path, False
 
+    generated_alembic_ini_path = Path(
+        f".{compose_type}.alembic.ini.common-python-tasks"
+    )
+    if generated_alembic_ini_path.exists():
+        LOGGER.debug("Using generated alembic.ini at %s", generated_alembic_ini_path)
+        return generated_alembic_ini_path, True
+
     result = utils.load_data_file(
         "alembic.ini.j2", type_identifier=compose_type, fatal_on_missing=False
     )
@@ -45,9 +52,9 @@ def ensure_alembic_config(compose_type: str) -> tuple[Path | None, bool]:
     rendered = Template(template_content).render(
         package_name=utils.get_package_name(use_underscores=True),
     )
-    alembic_ini_path.write_text(rendered, encoding="utf-8")
-    LOGGER.debug("Rendered bundled alembic.ini.j2 to %s", alembic_ini_path)
-    return alembic_ini_path, True
+    generated_alembic_ini_path.write_text(rendered, encoding="utf-8")
+    LOGGER.debug("Rendered bundled alembic.ini.j2 to %s", generated_alembic_ini_path)
+    return generated_alembic_ini_path, True
 
 
 def render_file(
@@ -217,7 +224,7 @@ def get_or_generate_secret(
 
 
 def ensure_secrets_generated() -> None:
-    """Ensure required secrets exist (generate once and persist to `.env`)."""
+    """Ensure required secrets exist and persist them to `.env`."""
     get_or_generate_secret("SECRET_KEY")
     get_or_generate_secret("DB_PASS")
 
@@ -514,6 +521,7 @@ def run_docker_compose_command(
         *args: Command arguments (None values are filtered out).
         compose_files: List of compose file paths.
         compose_env: Environment variables for the command.
+        tasks: Poe task collection that supplies configured env files.
     """
 
     utils.run_command(