common-python-tasks 0.7.0__tar.gz → 0.8.0__tar.gz

{common_python_tasks-0.7.0 → common_python_tasks-0.8.0}/.gitignore

@@ -214,3 +214,5 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+.serena

{common_python_tasks-0.7.0 → common_python_tasks-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: common-python-tasks
-Version: 0.7.0
+Version: 0.8.0
 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
@@ -43,9 +43,9 @@ It supplies sensible defaults for formatting, linting, testing, packaging, relea
 Add `common-python-tasks` as a development dependency from your project root.
 
 ```shell
-uv add --dev common-python-tasks==0.7.0
+uv add --dev common-python-tasks==0.8.0
 # or, for Poetry projects
-poetry add --group dev common-python-tasks==0.7.0
+poetry add --group dev common-python-tasks==0.8.0
 ```
 
 Configure Poe the Poet to expose the default `common` task set.
@@ -70,7 +70,7 @@ The helper script performs the same development-dependency installation and Poe
 ```shell
 curl --fail --silent --show-error --location \
   --output /tmp/add_common_python_tasks.py \
-  https://raw.githubusercontent.com/ci-sourcerer/common-python-tasks/v0.7.0/scripts/add_common_python_tasks.py
+  https://raw.githubusercontent.com/ci-sourcerer/common-python-tasks/v0.8.0/scripts/add_common_python_tasks.py
 ```
 
 Review the downloaded script before executing it.
@@ -82,10 +82,10 @@ less /tmp/add_common_python_tasks.py
 Run the reviewed script with the same pinned package version.
 
 ```shell
-COMMON_PYTHON_TASKS_VERSION=0.7.0 python3 /tmp/add_common_python_tasks.py
+COMMON_PYTHON_TASKS_VERSION=0.8.0 python3 /tmp/add_common_python_tasks.py
 ```
 
-To install another release, replace both occurrences of `0.7.0` with that release's version.
+To install another release, replace both occurrences of `0.8.0` with that release's version.
 
 ## Available tasks
 
@@ -196,7 +196,7 @@ After installing the package, a minimal project configuration looks like this.
 ```toml
 [project]
 name = "simple-cli-tool"
-version = "0.7.0"
+version = "0.8.0"
 
 [tool.poe]
 include_script = "common_python_tasks:tasks()"
@@ -240,13 +240,16 @@ addopts = "-ra"
 
 - `CONTAINER_REGISTRY_USERNAME`: Container-registry username for image tagging; the default is the current local user
 - `CONTAINER_REGISTRY_URL`: Registry URL with a default of `docker.io/{username}`
-- `CONTAINER_BUILD_ARGS`: Additional Docker build arguments in `KEY=VALUE:OTHER=VALUE` format. Escape literal colons as `\:` or quote the complete value.
+- `CONTAINER_DOCKER_BUILD_ARGS`: Additional arguments passed directly to `docker build`, parsed using shell quoting rules. Free arguments provided to the task after `--` take precedence.
+- `CONTAINER_DOCKERFILE_HOOK_PATH`: Optional host path to an executable hook script that receives the generated Dockerfile path and can modify the file before `docker build` runs.
+- `CONTAINER_APT_PACKAGES`: Space-delimited system packages installed in the generated image
+- `CONTAINER_CUSTOM_ENTRYPOINT`: Custom container entrypoint script. The value must match a key in `[project].scripts`.
+- `CONTAINER_DEPS_IMAGE`: Existing dependency image used when neither `CONTAINER_DEPS_CONTENT` nor `CONTAINER_DEPS_FILE` is configured
 - `CONTAINER_EXTENSION_FILES`: Colon-delimited local extension Dockerfile paths. Escape literal colons as `\:` or quote the complete path.
 - `CONTAINER_EXTENSIONS`: Colon-delimited extension-bundle names or parameterized values. Escape literal colons as `\:` or quote the complete value.
 - `CONTAINER_ENV`: Colon-delimited `KEY=VALUE` declarations injected into the rendered Dockerfile's builder stage. Escape literal colons as `\:` or quote the complete value.
 - `.containerenv`: A project-root file that can supply the same declarations. It is loaded before the `container_envfile` task argument, `CONTAINER_ENV`, and the `container_env` task argument.
 - `CONTAINER_PRUNE_KEEP`: Image-pruning policy after builds. `-1` keeps all images, `0` keeps only the latest, and `N` keeps the latest plus `N` prior images.
-- `CUSTOM_ENTRYPOINT`: Custom container entrypoint script. The value must match a key in `[project].scripts`.
 - `CONTAINER_DEPS_CONTENT`: Inline Dockerfile instructions for a dependency image that installs artifacts into `/tmp/deps`
 - `CONTAINER_DEPS_FILE`: One or more dependency-image Dockerfiles. It accepts colon-delimited paths with literal colons escaped as `\:` and is used only when `CONTAINER_DEPS_CONTENT` is unset.
 - `CONTAINER_DEPS_MAPPINGS`: Space-delimited `name:/target/path` entries for copying items from `/tmp/deps`. It is used only when no dependency move script is set.
@@ -293,6 +296,28 @@ addopts = "-ra"
 
 Docker Compose development-stack tasks are available when the `containers` tag is selected. The current stack supports FastAPI applications and an optional PostgreSQL database.
 
+### Native Docker build arguments
+
+Arguments after the task's `--` separator are passed directly to `docker build`. Docker performs option validation, so any supported build option and its value can be used without a package-specific allowlist.
+
+```shell
+poe build-image --single-arch -- \
+  --secret id=pip_conf,env=PIP_CONF \
+  --ssh default \
+  --add-host example:127.0.0.1
+```
+
+Set `CONTAINER_DOCKER_BUILD_ARGS` to provide the same arguments through the environment. The value uses shell quoting rules, and task arguments provided after `--` take precedence.
+
+Settings that affect generated Dockerfile content or dependency-image orchestration can be persisted directly in the project configuration.
+
+```toml
+[tool.poe.env]
+CONTAINER_APT_PACKAGES = "curl jq"
+CONTAINER_CUSTOM_ENTRYPOINT = "serve"
+CONTAINER_DEPS_IMAGE = "example/dependencies:latest"
+```
+
 ### Stack configuration
 
 Set `COMPOSE_TYPE` to select the application stack. `fastapi` is currently supported and includes optional database support and Alembic migrations.
@@ -388,10 +413,11 @@ See the [standard Dockerfile template](src/common_python_tasks/data/generic/Dock
 
 - Multi-stage build: The build stage installs the selected package-manager backend and builds a wheel. The runtime stage installs only the wheel to keep the final image slim and reproducible.
 - Cache mounts: Pip and package-manager cache mounts speed up iterative builds without bloating the final image.
-- Explicit build arguments: `PYTHON_VERSION`, `PACKAGE_MANAGER`, `PACKAGE_MANAGER_VERSION`, `PACKAGE_NAME`, `AUTHORS`, `GIT_COMMIT`, and `CUSTOM_ENTRYPOINT` make image metadata and behavior predictable and auditable.
+- Explicit build metadata: `PYTHON_VERSION`, `PACKAGE_MANAGER`, `PACKAGE_MANAGER_VERSION`, `PACKAGE_NAME`, `AUTHORS`, and `GIT_COMMIT` make image metadata predictable and auditable.
+- Project-level build settings: `CONTAINER_APT_PACKAGES`, `CONTAINER_CUSTOM_ENTRYPOINT`, and `CONTAINER_DEPS_IMAGE` configure generated image behavior without being encoded as generic Docker arguments.
 - Optional debug stage: The image exports and installs the `debug` dependency group only when present and does not include it in the default final image.
 - Stable package path: Symlinks give entrypoints and consumers consistent `/pkg` and `/_$PACKAGE_NAME` paths regardless of wheel layout.
-- Safe entrypoint selection: The default entrypoint resolves the console script matching the package name and falls back to `python`. `CUSTOM_ENTRYPOINT` is validated against `[project].scripts`.
+- Safe entrypoint selection: The default entrypoint resolves the console script matching the package name and falls back to `python`. `CONTAINER_CUSTOM_ENTRYPOINT` is validated against `[project].scripts`.
 - Minimal final image: The standard slim Python base, cache cleanup, and explicit `runtime` final target keep the default image small.
 
 ## Project notes

{common_python_tasks-0.7.0 → common_python_tasks-0.8.0}/README.md

@@ -11,9 +11,9 @@ It supplies sensible defaults for formatting, linting, testing, packaging, relea
 Add `common-python-tasks` as a development dependency from your project root.
 
 ```shell
-uv add --dev common-python-tasks==0.7.0
+uv add --dev common-python-tasks==0.8.0
 # or, for Poetry projects
-poetry add --group dev common-python-tasks==0.7.0
+poetry add --group dev common-python-tasks==0.8.0
 ```
 
 Configure Poe the Poet to expose the default `common` task set.
@@ -38,7 +38,7 @@ The helper script performs the same development-dependency installation and Poe
 ```shell
 curl --fail --silent --show-error --location \
   --output /tmp/add_common_python_tasks.py \
-  https://raw.githubusercontent.com/ci-sourcerer/common-python-tasks/v0.7.0/scripts/add_common_python_tasks.py
+  https://raw.githubusercontent.com/ci-sourcerer/common-python-tasks/v0.8.0/scripts/add_common_python_tasks.py
 ```
 
 Review the downloaded script before executing it.
@@ -50,10 +50,10 @@ less /tmp/add_common_python_tasks.py
 Run the reviewed script with the same pinned package version.
 
 ```shell
-COMMON_PYTHON_TASKS_VERSION=0.7.0 python3 /tmp/add_common_python_tasks.py
+COMMON_PYTHON_TASKS_VERSION=0.8.0 python3 /tmp/add_common_python_tasks.py
 ```
 
-To install another release, replace both occurrences of `0.7.0` with that release's version.
+To install another release, replace both occurrences of `0.8.0` with that release's version.
 
 ## Available tasks
 
@@ -164,7 +164,7 @@ After installing the package, a minimal project configuration looks like this.
 ```toml
 [project]
 name = "simple-cli-tool"
-version = "0.7.0"
+version = "0.8.0"
 
 [tool.poe]
 include_script = "common_python_tasks:tasks()"
@@ -208,13 +208,16 @@ addopts = "-ra"
 
 - `CONTAINER_REGISTRY_USERNAME`: Container-registry username for image tagging; the default is the current local user
 - `CONTAINER_REGISTRY_URL`: Registry URL with a default of `docker.io/{username}`
-- `CONTAINER_BUILD_ARGS`: Additional Docker build arguments in `KEY=VALUE:OTHER=VALUE` format. Escape literal colons as `\:` or quote the complete value.
+- `CONTAINER_DOCKER_BUILD_ARGS`: Additional arguments passed directly to `docker build`, parsed using shell quoting rules. Free arguments provided to the task after `--` take precedence.
+- `CONTAINER_DOCKERFILE_HOOK_PATH`: Optional host path to an executable hook script that receives the generated Dockerfile path and can modify the file before `docker build` runs.
+- `CONTAINER_APT_PACKAGES`: Space-delimited system packages installed in the generated image
+- `CONTAINER_CUSTOM_ENTRYPOINT`: Custom container entrypoint script. The value must match a key in `[project].scripts`.
+- `CONTAINER_DEPS_IMAGE`: Existing dependency image used when neither `CONTAINER_DEPS_CONTENT` nor `CONTAINER_DEPS_FILE` is configured
 - `CONTAINER_EXTENSION_FILES`: Colon-delimited local extension Dockerfile paths. Escape literal colons as `\:` or quote the complete path.
 - `CONTAINER_EXTENSIONS`: Colon-delimited extension-bundle names or parameterized values. Escape literal colons as `\:` or quote the complete value.
 - `CONTAINER_ENV`: Colon-delimited `KEY=VALUE` declarations injected into the rendered Dockerfile's builder stage. Escape literal colons as `\:` or quote the complete value.
 - `.containerenv`: A project-root file that can supply the same declarations. It is loaded before the `container_envfile` task argument, `CONTAINER_ENV`, and the `container_env` task argument.
 - `CONTAINER_PRUNE_KEEP`: Image-pruning policy after builds. `-1` keeps all images, `0` keeps only the latest, and `N` keeps the latest plus `N` prior images.
-- `CUSTOM_ENTRYPOINT`: Custom container entrypoint script. The value must match a key in `[project].scripts`.
 - `CONTAINER_DEPS_CONTENT`: Inline Dockerfile instructions for a dependency image that installs artifacts into `/tmp/deps`
 - `CONTAINER_DEPS_FILE`: One or more dependency-image Dockerfiles. It accepts colon-delimited paths with literal colons escaped as `\:` and is used only when `CONTAINER_DEPS_CONTENT` is unset.
 - `CONTAINER_DEPS_MAPPINGS`: Space-delimited `name:/target/path` entries for copying items from `/tmp/deps`. It is used only when no dependency move script is set.
@@ -261,6 +264,28 @@ addopts = "-ra"
 
 Docker Compose development-stack tasks are available when the `containers` tag is selected. The current stack supports FastAPI applications and an optional PostgreSQL database.
 
+### Native Docker build arguments
+
+Arguments after the task's `--` separator are passed directly to `docker build`. Docker performs option validation, so any supported build option and its value can be used without a package-specific allowlist.
+
+```shell
+poe build-image --single-arch -- \
+  --secret id=pip_conf,env=PIP_CONF \
+  --ssh default \
+  --add-host example:127.0.0.1
+```
+
+Set `CONTAINER_DOCKER_BUILD_ARGS` to provide the same arguments through the environment. The value uses shell quoting rules, and task arguments provided after `--` take precedence.
+
+Settings that affect generated Dockerfile content or dependency-image orchestration can be persisted directly in the project configuration.
+
+```toml
+[tool.poe.env]
+CONTAINER_APT_PACKAGES = "curl jq"
+CONTAINER_CUSTOM_ENTRYPOINT = "serve"
+CONTAINER_DEPS_IMAGE = "example/dependencies:latest"
+```
+
 ### Stack configuration
 
 Set `COMPOSE_TYPE` to select the application stack. `fastapi` is currently supported and includes optional database support and Alembic migrations.
@@ -356,10 +381,11 @@ See the [standard Dockerfile template](src/common_python_tasks/data/generic/Dock
 
 - Multi-stage build: The build stage installs the selected package-manager backend and builds a wheel. The runtime stage installs only the wheel to keep the final image slim and reproducible.
 - Cache mounts: Pip and package-manager cache mounts speed up iterative builds without bloating the final image.
-- Explicit build arguments: `PYTHON_VERSION`, `PACKAGE_MANAGER`, `PACKAGE_MANAGER_VERSION`, `PACKAGE_NAME`, `AUTHORS`, `GIT_COMMIT`, and `CUSTOM_ENTRYPOINT` make image metadata and behavior predictable and auditable.
+- Explicit build metadata: `PYTHON_VERSION`, `PACKAGE_MANAGER`, `PACKAGE_MANAGER_VERSION`, `PACKAGE_NAME`, `AUTHORS`, and `GIT_COMMIT` make image metadata predictable and auditable.
+- Project-level build settings: `CONTAINER_APT_PACKAGES`, `CONTAINER_CUSTOM_ENTRYPOINT`, and `CONTAINER_DEPS_IMAGE` configure generated image behavior without being encoded as generic Docker arguments.
 - Optional debug stage: The image exports and installs the `debug` dependency group only when present and does not include it in the default final image.
 - Stable package path: Symlinks give entrypoints and consumers consistent `/pkg` and `/_$PACKAGE_NAME` paths regardless of wheel layout.
-- Safe entrypoint selection: The default entrypoint resolves the console script matching the package name and falls back to `python`. `CUSTOM_ENTRYPOINT` is validated against `[project].scripts`.
+- Safe entrypoint selection: The default entrypoint resolves the console script matching the package name and falls back to `python`. `CONTAINER_CUSTOM_ENTRYPOINT` is validated against `[project].scripts`.
 - Minimal final image: The standard slim Python base, cache cleanup, and explicit `runtime` final target keep the default image small.
 
 ## Project notes

{common_python_tasks-0.7.0 → common_python_tasks-0.8.0}/pyproject.toml

@@ -37,12 +37,16 @@ Source = "http://github.com/ci-sourcerer/common-python-tasks.git"
 Issues = "http://github.com/ci-sourcerer/common-python-tasks/issues"
 
 [tool.poe]
-include_script = "common_python_tasks:tasks(exclude_tags=['containers'])"
+include_script = "common_python_tasks:tasks(exclude_tags=['containers', 'fastapi'])"
 
 [tool.poe.env]
 PYTHONPATH = "src"
 RELEASE_UPDATE_CHANGELOG = "1"
-RELEASE_PRE_SCRIPT = "RELEASE_SCRIPT_PHASE=pre python scripts/release_script.py"
+RELEASE_PRE_SCRIPT = "RELEASE_SCRIPT_PHASE=pre python -m scripts.release_script"
+CONTAINER_APT_PACKAGES = "jq"
+
+[tool.poe.tasks]
+update-readme-tasks-table = { cmd = "python -m scripts.update_readme_tasks_table" }
 
 [tool.hatch.version]
 source = "uv-dynamic-versioning"

common_python_tasks-0.8.0/scripts/readme_tasks_table.py

@@ -0,0 +1,78 @@
+import re
+
+from common_python_tasks.__main__ import (
+    _get_task_docstring,
+    get_available_tasks,
+    get_task_tags,
+)
+
+TASKS_TABLE_PATTERN = r"(?ms)<!-- tasks-table -->.*?<!-- end-tasks-table -->"
+TASK_CATEGORY_ORDER = (
+    "Daily development",
+    "Packaging and releases",
+    "Container images",
+    "Development stacks",
+)
+
+
+def _get_task_category(task_name: str) -> str:
+    tags = get_task_tags(task_name) or []
+    if "web" in tags or "database" in tags:
+        return "Development stacks"
+    if task_name == "release":
+        return "Packaging and releases"
+    if "containers" in tags:
+        return "Container images"
+    if "packaging" in tags or "release" in tags:
+        return "Packaging and releases"
+    return "Daily development"
+
+
+def _get_task_description(task_name: str) -> str:
+    return " ".join(
+        line.strip()
+        for line in (_get_task_docstring(task_name) or "").splitlines()
+        if line.strip()
+    )
+
+
+def build_tasks_table() -> str:
+    """Build the markdown task table for README insertion."""
+    tasks_by_category = {category: [] for category in TASK_CATEGORY_ORDER}
+    for task_name in get_available_tasks(internal=False):
+        tasks_by_category[_get_task_category(task_name)].append(task_name)
+
+    lines = ["<!-- tasks-table -->"]
+    for category in TASK_CATEGORY_ORDER:
+        if not tasks_by_category[category]:
+            continue
+
+        lines.extend(
+            [
+                "",
+                f"### {category}",
+                "",
+                "| Task | Description | Tags |",
+                "| --- | --- | --- |",
+            ]
+        )
+        lines.extend(
+            f"| `{task_name}` | {_get_task_description(task_name)} | "
+            f"{', '.join(get_task_tags(task_name) or [])} |"
+            for task_name in tasks_by_category[category]
+        )
+
+    lines.extend(["", "<!-- end-tasks-table -->"])
+    return "\n".join(lines)
+
+
+def replace_tasks_table(readme_text: str) -> str:
+    """Replace the task table in the README text with the generated task table.
+
+    Args:
+        readme_text: The text of the README.md file to update.
+
+    Returns:
+        The updated README.md text with the task table replaced.
+    """
+    return re.sub(TASKS_TABLE_PATTERN, build_tasks_table(), readme_text)

common_python_tasks-0.8.0/scripts/release_script.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+
+import os
+import subprocess
+import sys
+from enum import StrEnum
+from pathlib import Path
+
+from .readme_tasks_table import replace_tasks_table
+from .utils import commit_readme_update, configure_logger, get_logger, log_dry_run
+
+LOGGER = get_logger(__name__)
+
+
+class ReleasePhase(StrEnum):
+    PRE = "pre"
+
+
+RELEASE_SCRIPT_PHASE = "RELEASE_SCRIPT_PHASE"
+
+
+def _get_latest_release_version() -> str:
+    completed_process = subprocess.run(
+        ["git", "tag", "--sort=-version:refname"],
+        capture_output=True,
+        check=True,
+        text=True,
+    )
+    latest_tag = next(
+        (
+            line.strip()
+            for line in completed_process.stdout.splitlines()
+            if line.strip()
+        ),
+        None,
+    )
+    if latest_tag is None:
+        sys.exit("Unable to determine the latest Git tag for README updates")
+
+    return latest_tag.removeprefix("v")
+
+
+def _resolve_release_phase(phase: ReleasePhase | None = None) -> ReleasePhase:
+    if phase is not None:
+        return phase
+
+    phase_value = os.environ.get(RELEASE_SCRIPT_PHASE)
+    if phase_value is None:
+        sys.exit(f"{RELEASE_SCRIPT_PHASE} must be set to 'pre'.")
+
+    if phase_value.lower() != "pre":
+        sys.exit(f"Invalid {RELEASE_SCRIPT_PHASE!r}: {phase_value!r}. Expected 'pre'.")
+    return ReleasePhase.PRE
+
+
+def _update_readme_for_pre_release(
+    readme_text: str, current_version: str, release_version: str
+) -> str:
+    if current_version not in readme_text:
+        sys.exit(
+            "README.md does not contain the latest tagged version "
+            f"{current_version!r} to update"
+        )
+
+    return replace_tasks_table(readme_text.replace(current_version, release_version))
+
+
+def main() -> None:
+    """Update README release content during release hook execution."""
+    _resolve_release_phase()
+    release_version = os.environ["RELEASE_VERSION"]
+
+    configure_logger(LOGGER)
+
+    if os.environ.get("RELEASE_SCRIPT_DRY_RUN") == "1":
+        current_version = _get_latest_release_version()
+        log_dry_run(
+            LOGGER,
+            "Would modify: README.md (replace %r with %r)",
+            current_version,
+            release_version,
+        )
+        return
+
+    readme_path = Path("README.md")
+    readme_text = readme_path.read_text(encoding="utf-8")
+
+    updated_text = _update_readme_for_pre_release(
+        readme_text,
+        _get_latest_release_version(),
+        release_version,
+    )
+
+    if updated_text == readme_text:
+        sys.exit("README.md was not changed")
+
+    readme_path.write_text(updated_text, encoding="utf-8")
+    commit_readme_update(f"chore(release): set README version {release_version}")
+
+
+if __name__ == "__main__":
+    main()

common_python_tasks-0.8.0/scripts/update_readme_tasks_table.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+from pathlib import Path
+
+from .readme_tasks_table import replace_tasks_table
+from .utils import commit_readme_update, configure_logger, get_logger, log_dry_run
+
+LOGGER = get_logger(__name__)
+
+
+def main() -> None:
+    """Update the README task table from the current task definitions."""
+    configure_logger(LOGGER)
+
+    readme_path = Path("README.md")
+    readme_text = readme_path.read_text(encoding="utf-8")
+
+    if os.environ.get("RELEASE_SCRIPT_DRY_RUN") == "1":
+        updated_text = replace_tasks_table(readme_text)
+        if updated_text == readme_text:
+            log_dry_run(LOGGER, "README.md task table is already up to date")
+        else:
+            log_dry_run(LOGGER, "Would update README.md task table")
+        return
+
+    updated_text = replace_tasks_table(readme_text)
+    if updated_text == readme_text:
+        sys.exit("README.md task table was not changed")
+
+    readme_path.write_text(updated_text, encoding="utf-8")
+    commit_readme_update("chore(docs): refresh README task table")
+
+
+if __name__ == "__main__":
+    main()

common_python_tasks-0.8.0/scripts/utils.py

@@ -0,0 +1,76 @@
+import logging
+import subprocess
+
+
+class ColoredFormatter(logging.Formatter):
+    """Format warning and error log levels with ANSI color codes."""
+
+    COLORS = {
+        "WARNING": "\033[93m",
+        "ERROR": "\033[91m",
+        "CRITICAL": "\033[91m",
+        "RESET": "\033[0m",
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format a log record with a colored level name.
+
+        Args:
+            record: The log record to format.
+
+        Returns:
+            The formatted log message.
+        """
+        log_color = self.COLORS.get(record.levelname, "")
+        record.levelname = f"\033[1m{log_color}{record.levelname}{self.COLORS['RESET'] if log_color else ''}\033[0m"
+        return super().format(record)
+
+
+def configure_logger(logger: logging.Logger) -> None:
+    """Configure a logger with the standard colored console formatter.
+
+    Args:
+        logger: Logger to configure.
+    """
+    while logger.handlers:
+        logger.removeHandler(logger.handlers[0])
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(ColoredFormatter("[%(asctime)s] %(levelname)s: %(message)s"))
+    logger.addHandler(handler)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Create a standard logger for a repository maintenance script.
+
+    Args:
+        name: Logger name, usually the script's `__name__` value.
+
+    Returns:
+        A configured logger without parent propagation.
+    """
+    logger = logging.getLogger(name)
+    logger.propagate = False
+    logger.setLevel(logging.INFO)
+    return logger
+
+
+def log_dry_run(logger: logging.Logger, message: str, *args: object) -> None:
+    """Log a dry-run informational message with a yellow prefix.
+
+    Args:
+        logger: Logger used to emit the message.
+        message: Log message template.
+        *args: Values interpolated into `message`.
+    """
+    logger.info("\033[93m[DRY RUN]\033[0m " + message, *args)
+
+
+def commit_readme_update(commit_message: str) -> None:
+    """Commit the current README changes.
+
+    Args:
+        commit_message: Message for the README update commit.
+    """
+    subprocess.run(["git", "add", "README.md"], check=True)
+    subprocess.run(["git", "commit", "-m", commit_message], check=True)

{common_python_tasks-0.7.0 → common_python_tasks-0.8.0}/src/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-0.7.0 → common_python_tasks-0.8.0}/src/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-0.7.0 → common_python_tasks-0.8.0}/src/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-0.8.0/src/common_python_tasks/data/generic/ruff.toml

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