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

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

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

{common_python_tasks-0.7.0 → common_python_tasks-0.9.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.9.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,7 @@ 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
-# or, for Poetry projects
-poetry add --group dev common-python-tasks==0.7.0
+uv add --dev common-python-tasks==0.9.0
 ```
 
 Configure Poe the Poet to expose the default `common` task set.
@@ -70,7 +68,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.9.0/scripts/add_common_python_tasks.py
 ```
 
 Review the downloaded script before executing it.
@@ -82,10 +80,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.9.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.9.0` with that release's version.
 
 ## Available tasks
 
@@ -108,7 +106,7 @@ The generated tables below list public tasks only. Tags identify which tasks are
 | --- | --- | --- |
 | `publish-package` | Publish the package to the PyPI server. | common, packaging |
 | `publish-github-release` | Publish or update a GitHub Release for the current repository. | common, packaging, release |
-| `update-dependencies` | Update project dependencies with Poetry or uv. | common, packaging |
+| `update-dependencies` | Update project dependencies with uv. | common, packaging |
 | `build-package` | Build the package (wheel and sdist). | build, common, packaging |
 | `bump-version` | Bump the project version. | common, packaging |
 | `changelog` | Print the changelog for the current version based on git history and git-cliff. | common, packaging, release |
@@ -143,7 +141,7 @@ The generated tables below list public tasks only. Tags identify which tasks are
 
 Every project needs a `pyproject.toml` file at its root and Poe the Poet available in its development environment.
 
-Tasks that install, build, publish, or update dependencies also require either Poetry or uv. Package and release tasks need a resolvable project version from `project.version`, Poetry's version resolution, or Git tags. Dynamic-versioning plugins are supported but are not a baseline requirement.
+Tasks that install, build, publish, or update dependencies require uv. Package and release tasks need a resolvable project version from `project.version` or Git tags. Dynamic versioning is supported but is not a baseline requirement.
 
 ### Task selection
 
@@ -163,18 +161,27 @@ include_script = "common_python_tasks:tasks(include_tags=['common', 'containers'
 
 The `containers` tag also includes container-based development-stack tasks. Use the tags in the task tables to tailor a smaller task set.
 
-### Package manager backend selection
+### Package management
 
-Packaging-related tasks, including `build-package`, `publish-package`, release version resolution, and container build metadata, support Poetry and uv.
+Packaging-related tasks, including `build-package`, `publish-package`, dependency updates, release version resolution, and container build metadata, use uv exclusively. The `uv` executable must be available on `PATH`.
 
-Backend selection uses this precedence.
+### Publish target selection
 
-1. `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`
-2. `COMMON_PYTHON_TASKS_BUILD_TOOL`
-3. `PACKAGE_MANAGER`
-4. Auto-discovery (`auto`) based on installed tools and project metadata
+The `publish-package` task resolves publish targets with this precedence.
 
-Supported values are `poetry`, `uv`, and `auto`.
+1. Explicit task arguments (`repository` or `repository_url`)
+2. Environment-variable fallback
+3. uv project configuration fallback from `[[tool.uv.index]]`
+4. The `uv publish` default
+
+uv prefers named publish indexes.
+
+- `COMMON_PYTHON_TASKS_PUBLISH_REPOSITORY`
+- `UV_PUBLISH_INDEX`
+- `COMMON_PYTHON_TASKS_PUBLISH_URL`
+- `UV_PUBLISH_URL`
+
+When using uv project configuration fallback, `[[tool.uv.index]]` must include both `name` and `publish-url` for publish selection. If multiple publishable indexes exist, set exactly one `default = true` or pass an explicit repository.
 
 ### Configuration precedence
 
@@ -196,7 +203,7 @@ After installing the package, a minimal project configuration looks like this.
 ```toml
 [project]
 name = "simple-cli-tool"
-version = "0.7.0"
+version = "0.9.0"
 
 [tool.poe]
 include_script = "common_python_tasks:tasks()"
@@ -232,21 +239,25 @@ addopts = "-ra"
 #### Project and package settings
 
 - `PACKAGE_NAME`: Overrides the package name inferred from `pyproject.toml`
-- `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`: Selects the package-manager backend as `poetry`, `uv`, or `auto`
-- `COMMON_PYTHON_TASKS_BUILD_TOOL`: Alias for `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`
-- `PACKAGE_MANAGER`: Alias for `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`
+- `COMMON_PYTHON_TASKS_PUBLISH_REPOSITORY`: Preferred publish repository/index name for `publish-package`
+- `COMMON_PYTHON_TASKS_PUBLISH_URL`: Preferred uv publish upload URL for `publish-package` when no repository/index is selected
+- `UV_PUBLISH_INDEX`: uv publish-index fallback for `publish-package`
+- `UV_PUBLISH_URL`: uv publish upload-url fallback for `publish-package`
 
 #### Container image settings
 
 - `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 +304,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.
@@ -361,7 +394,7 @@ GITHUB_RELEASE_ASSETS="dist/*.whl:dist/*.tar.gz" poe publish-github-release
 
 ### Container build fails with "unable to find package"
 
-Check that `pyproject.toml` has a correct package name and the package-discovery settings required by its build backend. For Poetry projects, this commonly includes `[tool.poetry] packages = [{ include = "your_package", from = "src" }]`.
+Check that `pyproject.toml` has a correct package name and the package-discovery settings required by its build backend. For a `src` layout built with Hatch, configure `[tool.hatch.build.targets.wheel] packages = ["src/your_package"]`.
 
 ### Stack fails to start or services cannot connect
 
@@ -386,12 +419,13 @@ Ensure the project-root `.env` file is writable and inspect its permissions with
 
 See the [standard Dockerfile template](src/common_python_tasks/data/generic/Dockerfile.j2) for the implementation.
 
-- 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.
+- Multi-stage build: The build stage installs uv and builds a wheel. The runtime stage installs only the wheel to keep the final image slim and reproducible.
+- Cache mounts: Pip and uv cache mounts speed up iterative builds without bloating the final image.
+- Explicit build metadata: `PYTHON_VERSION`, `UV_VERSION`, `PACKAGE_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.9.0}/README.md

@@ -11,9 +11,7 @@ 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
-# or, for Poetry projects
-poetry add --group dev common-python-tasks==0.7.0
+uv add --dev common-python-tasks==0.9.0
 ```
 
 Configure Poe the Poet to expose the default `common` task set.
@@ -38,7 +36,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.9.0/scripts/add_common_python_tasks.py
 ```
 
 Review the downloaded script before executing it.
@@ -50,10 +48,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.9.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.9.0` with that release's version.
 
 ## Available tasks
 
@@ -76,7 +74,7 @@ The generated tables below list public tasks only. Tags identify which tasks are
 | --- | --- | --- |
 | `publish-package` | Publish the package to the PyPI server. | common, packaging |
 | `publish-github-release` | Publish or update a GitHub Release for the current repository. | common, packaging, release |
-| `update-dependencies` | Update project dependencies with Poetry or uv. | common, packaging |
+| `update-dependencies` | Update project dependencies with uv. | common, packaging |
 | `build-package` | Build the package (wheel and sdist). | build, common, packaging |
 | `bump-version` | Bump the project version. | common, packaging |
 | `changelog` | Print the changelog for the current version based on git history and git-cliff. | common, packaging, release |
@@ -111,7 +109,7 @@ The generated tables below list public tasks only. Tags identify which tasks are
 
 Every project needs a `pyproject.toml` file at its root and Poe the Poet available in its development environment.
 
-Tasks that install, build, publish, or update dependencies also require either Poetry or uv. Package and release tasks need a resolvable project version from `project.version`, Poetry's version resolution, or Git tags. Dynamic-versioning plugins are supported but are not a baseline requirement.
+Tasks that install, build, publish, or update dependencies require uv. Package and release tasks need a resolvable project version from `project.version` or Git tags. Dynamic versioning is supported but is not a baseline requirement.
 
 ### Task selection
 
@@ -131,18 +129,27 @@ include_script = "common_python_tasks:tasks(include_tags=['common', 'containers'
 
 The `containers` tag also includes container-based development-stack tasks. Use the tags in the task tables to tailor a smaller task set.
 
-### Package manager backend selection
+### Package management
 
-Packaging-related tasks, including `build-package`, `publish-package`, release version resolution, and container build metadata, support Poetry and uv.
+Packaging-related tasks, including `build-package`, `publish-package`, dependency updates, release version resolution, and container build metadata, use uv exclusively. The `uv` executable must be available on `PATH`.
 
-Backend selection uses this precedence.
+### Publish target selection
 
-1. `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`
-2. `COMMON_PYTHON_TASKS_BUILD_TOOL`
-3. `PACKAGE_MANAGER`
-4. Auto-discovery (`auto`) based on installed tools and project metadata
+The `publish-package` task resolves publish targets with this precedence.
 
-Supported values are `poetry`, `uv`, and `auto`.
+1. Explicit task arguments (`repository` or `repository_url`)
+2. Environment-variable fallback
+3. uv project configuration fallback from `[[tool.uv.index]]`
+4. The `uv publish` default
+
+uv prefers named publish indexes.
+
+- `COMMON_PYTHON_TASKS_PUBLISH_REPOSITORY`
+- `UV_PUBLISH_INDEX`
+- `COMMON_PYTHON_TASKS_PUBLISH_URL`
+- `UV_PUBLISH_URL`
+
+When using uv project configuration fallback, `[[tool.uv.index]]` must include both `name` and `publish-url` for publish selection. If multiple publishable indexes exist, set exactly one `default = true` or pass an explicit repository.
 
 ### Configuration precedence
 
@@ -164,7 +171,7 @@ After installing the package, a minimal project configuration looks like this.
 ```toml
 [project]
 name = "simple-cli-tool"
-version = "0.7.0"
+version = "0.9.0"
 
 [tool.poe]
 include_script = "common_python_tasks:tasks()"
@@ -200,21 +207,25 @@ addopts = "-ra"
 #### Project and package settings
 
 - `PACKAGE_NAME`: Overrides the package name inferred from `pyproject.toml`
-- `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`: Selects the package-manager backend as `poetry`, `uv`, or `auto`
-- `COMMON_PYTHON_TASKS_BUILD_TOOL`: Alias for `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`
-- `PACKAGE_MANAGER`: Alias for `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`
+- `COMMON_PYTHON_TASKS_PUBLISH_REPOSITORY`: Preferred publish repository/index name for `publish-package`
+- `COMMON_PYTHON_TASKS_PUBLISH_URL`: Preferred uv publish upload URL for `publish-package` when no repository/index is selected
+- `UV_PUBLISH_INDEX`: uv publish-index fallback for `publish-package`
+- `UV_PUBLISH_URL`: uv publish upload-url fallback for `publish-package`
 
 #### Container image settings
 
 - `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 +272,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.
@@ -329,7 +362,7 @@ GITHUB_RELEASE_ASSETS="dist/*.whl:dist/*.tar.gz" poe publish-github-release
 
 ### Container build fails with "unable to find package"
 
-Check that `pyproject.toml` has a correct package name and the package-discovery settings required by its build backend. For Poetry projects, this commonly includes `[tool.poetry] packages = [{ include = "your_package", from = "src" }]`.
+Check that `pyproject.toml` has a correct package name and the package-discovery settings required by its build backend. For a `src` layout built with Hatch, configure `[tool.hatch.build.targets.wheel] packages = ["src/your_package"]`.
 
 ### Stack fails to start or services cannot connect
 
@@ -354,12 +387,13 @@ Ensure the project-root `.env` file is writable and inspect its permissions with
 
 See the [standard Dockerfile template](src/common_python_tasks/data/generic/Dockerfile.j2) for the implementation.
 
-- 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.
+- Multi-stage build: The build stage installs uv and builds a wheel. The runtime stage installs only the wheel to keep the final image slim and reproducible.
+- Cache mounts: Pip and uv cache mounts speed up iterative builds without bloating the final image.
+- Explicit build metadata: `PYTHON_VERSION`, `UV_VERSION`, `PACKAGE_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.9.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"
@@ -69,7 +73,7 @@ package = true
 
 [tool.ruff]
 line-length = 88
-extend-exclude = [".dist", ".poetry", "build"]
+extend-exclude = [".dist", "build"]
 
 [tool.ruff.lint]
 select = ["E4", "E7", "E9", "F", "I", "W"]

{common_python_tasks-0.7.0 → common_python_tasks-0.9.0}/scripts/add_common_python_tasks.py

@@ -10,11 +10,6 @@ import tomllib
 from pathlib import Path
 
 PACKAGE_NAME = "common-python-tasks"
-PACKAGE_MANAGER_ENV_VARS = (
-    "COMMON_PYTHON_TASKS_PACKAGE_MANAGER",
-    "COMMON_PYTHON_TASKS_BUILD_TOOL",
-    "PACKAGE_MANAGER",
-)
 PYPROJECT_PATH = Path("pyproject.toml")
 TOOL_POE_PATTERN = re.compile(r"^\s*\[tool\.poe\]\s*(?:#.*)?$")
 TABLE_PATTERN = re.compile(r"^\s*\[")
@@ -26,47 +21,18 @@ def _require_command(command: str) -> None:
         sys.exit(f"Required command not found: {command}")
 
 
-def _get_requested_package_manager() -> str:
-    for env_var in PACKAGE_MANAGER_ENV_VARS:
-        if os.getenv(env_var, "").strip():
-            return os.environ[env_var].strip().lower()
-    return "auto"
-
-
-def _select_package_manager() -> str:
-    requested_manager = _get_requested_package_manager()
-    if requested_manager in {"poetry", "uv"}:
-        _require_command(requested_manager)
-        return requested_manager
-    if requested_manager != "auto":
-        sys.exit(f"Unsupported package manager: {requested_manager}")
-
-    for lock_file, package_manager in (
-        (Path("uv.lock"), "uv"),
-        (Path("poetry.lock"), "poetry"),
-    ):
-        if lock_file.is_file() and shutil.which(package_manager) is not None:
-            return package_manager
-
-    for package_manager in ("uv", "poetry"):
-        if shutil.which(package_manager) is not None:
-            return package_manager
-
-    sys.exit("Neither uv nor Poetry is installed.")
-
-
 def _get_package_requirement() -> str:
     if os.getenv("COMMON_PYTHON_TASKS_VERSION", "").strip():
         return f"{PACKAGE_NAME}=={os.environ['COMMON_PYTHON_TASKS_VERSION'].strip()}"
     return PACKAGE_NAME
 
 
-def _install_package(package_manager: str) -> None:
-    if package_manager == "uv":
-        command = ["uv", "add", "--dev", _get_package_requirement()]
-    else:
-        command = ["poetry", "add", "--group", "dev", _get_package_requirement()]
-    subprocess.run(command, check=True, shell=False)
+def _install_package() -> None:
+    subprocess.run(
+        ["uv", "add", "--dev", _get_package_requirement()],
+        check=True,
+        shell=False,
+    )
 
 
 def _get_include_script() -> str:
@@ -132,7 +98,8 @@ def _print_available_tasks() -> None:
 
 def main() -> None:
     """Install common tasks and configure Poe in the current project."""
-    _install_package(_select_package_manager())
+    _require_command("uv")
+    _install_package()
     _configure_poe()
     print("\n\033[1;32mCommon Python tasks added to project.\033[0m")
     print("\n\033[1mAvailable tasks:\033[0m")

common_python_tasks-0.9.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)