common-python-tasks 0.3.1__tar.gz → 0.4.0__tar.gz

{common_python_tasks-0.3.1 → common_python_tasks-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: common-python-tasks
-Version: 0.3.1
+Version: 0.4.0
 Summary: Opinionated Poe the Poet tasks for Python package development.
 License-Expression: MIT
 License-File: LICENSE
@@ -17,14 +17,17 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Build Tools
 Requires-Dist: autoflake (>=2.3.1,<3.0.0)
 Requires-Dist: black (>=26.3.1,<27.0.0)
+Requires-Dist: docker (>=7.1.0,<8.0.0)
 Requires-Dist: dunamai (>=1.25.0,<2.0.0)
 Requires-Dist: flake8 (>=7.3.0,<8.0.0)
 Requires-Dist: git-cliff (>=2.12.0,<3.0.0)
 Requires-Dist: isort (>=8.0.1,<9.0.0)
 Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
+Requires-Dist: packaging (>=26.2,<27.0)
 Requires-Dist: poethepoet-tasks (>=0.3.0,<0.4.0)
 Requires-Dist: pytest (>=9.0.3,<10.0.0)
 Requires-Dist: pytest-cov (>=7.0.0,<8.0.0)
+Requires-Dist: requests (>=2.34.2,<3.0.0)
 Requires-Dist: tomlkit (>=0.13.3,<0.14.0)
 Project-URL: Homepage, http://github.com/ci-sourcerer/common-python-tasks
 Project-URL: Issues, http://github.com/ci-sourcerer/common-python-tasks/issues
@@ -35,7 +38,7 @@ Description-Content-Type: text/markdown
 
 This package is a collection of (very) opinionated [Poe the Poet](https://poethepoet.natn.io/guides/packaged_tasks.html) Python tasks for common Python development workflows.
 
-Instead of writing your own tasks for formatting, linting, testing, packaging, and more, you can use these pre-built tasks that work out of the box with reasonable defaults and support configuration overrides when needed. In the past, I found myself copying and pasting the same task definitions across projects, and this package is my attempt to DRY up that workflow and provide a single source of truth for common Python development tasks. I hope you can use them too.
+Instead of writing your own tasks for formatting, linting, testing, packaging, and more, you can use these prebuilt tasks that work immediately with reasonable defaults and support configuration overrides when needed. In the past, I found myself copying and pasting the same task definitions across projects, and this package is my attempt to DRY up that workflow and provide a single source of truth for common Python development tasks. I hope you can use them too.
 
 ## Quick start
 
@@ -50,7 +53,7 @@ curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents
 To install a specific release, set the environment variable `COMMON_PYTHON_TASKS_VERSION`.
 
 ```shell
-COMMON_PYTHON_TASKS_VERSION=0.3.1 \
+COMMON_PYTHON_TASKS_VERSION=0.4.0 \
   sh -c "$(curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add-common-python-tasks.sh | jq -r '.content' | base64 -d)"
 ```
 
@@ -70,10 +73,8 @@ There's no real reason to run the automated script; I just like automating every
 
     ```toml
     [project]
-    name = "my-awesome-project"
-    version = "0.3.1"
     dependencies = [
-        "common-python-tasks==0.3.1",  # Always pin to a specific version
+        "common-python-tasks==0.4.0"  # Always pin to a specific version
     ]
 
     [tool.poe]
@@ -106,6 +107,7 @@ Internal tasks are used by other tasks and are not meant to be run directly.
 | `format` | Format Python code with autoflake, black, and isort. | common, format |
 | `lint` | Lint Python code with autoflake, black, isort, and flake8. | common, lint |
 | `build-image` | Build the container image for this project using the Dockerfile template. | build, containers |
+| `build-deps-image` | Build only the container dependency collector image for this project. | build, containers |
 | `run-container` | Run the Docker image as a container for this project.  By default (when `tag` is `None`) this will run the most-recently-built tag for the project's image. | containers |
 | `push-image` | Push the Docker image for this project to the container registry. | containers, packaging, release |
 | `publish-package` | Publish the package to the PyPI server. | common, packaging |
@@ -133,7 +135,7 @@ Some tasks of certain tags provide Docker Compose-based development stacks for r
 
 Specifies the type of application stack. Currently supported:
 
-- `fastapi` - FastAPI application with optional database, Alembic migrations
+- `fastapi`: FastAPI application with optional database support and Alembic migrations
 
 Set via environment variable:
 
@@ -146,7 +148,7 @@ COMPOSE_TYPE = "fastapi"
 
 Colon-separated list of additional services to include. Available addons:
 
-- `db` - PostgreSQL database with Alembic migration support and Adminer web UI
+- `db`: PostgreSQL database with Alembic migration support and Adminer web UI
 
 Example:
 
@@ -161,13 +163,13 @@ For multiple addons (future): `COMPOSE_ADDONS = "db:redis:cache"`
 
 The compose setup follows this precedence.
 
-1. **Environment override** - `COMPOSE_FILE` environment variable with colon-separated paths
-2. **Auto-loaded files** - Based on `COMPOSE_TYPE` and `COMPOSE_ADDONS`:
-   - `compose-base.yml` - Core application service
-   - `compose-{addon}.yml` - For each addon (e.g., `compose-db.yml`)
-   - `compose-debug.yml` - When `--debug` flag is used
-   - `compose-{addon}-debug.yml` - Debug overlays for addons
-3. **Additional overlays** - `COMPOSE_OVERLAY_FILES` with colon-separated paths
+1. **Environment override**: `COMPOSE_FILE` environment variable with colon separated paths
+2. **Automatically loaded files**: Based on `COMPOSE_TYPE` and `COMPOSE_ADDONS`
+    - `compose-base.yml`: Core application service
+    - `compose-{addon}.yml`: One file for each addon; for example, `compose-db.yml`
+    - `compose-debug.yml`: Used when the `--debug` flag is present
+    - `compose-{addon}-debug.yml`: Debug overlays for addons
+3. **Additional overlays**: `COMPOSE_OVERLAY_FILES` with colon separated paths
 
 You can provide local compose files or let the tasks use bundled templates.
 
@@ -177,16 +179,16 @@ The `fastapi` stack includes a service for your FastAPI application. It uses the
 
 #### Environment variables
 
-- `API_PORT` - Port for the API server (default: `8080`)
-- `SECRET_KEY` - Application secret key (auto-generated and stored in `.env` if not set)
-- `ENVIRONMENT` - Environment name like `development` or `production` (default: `production`)
-- `DEBUG_PORT` - Port for the Python debugger when using `--debug` (default: `5678`)
-- `DB_PORT` - PostgreSQL port (default: `5432`)
-- `DB_USER` - Database user (default: package name)
-- `DB_BASE` - Database name (default: package name)
-- `DB_PASS` - Database password (auto-generated and stored in `.env` if not set)
-- `POSTGRES_VERSION` - PostgreSQL Docker image version (default: `17`)
-- `ADMINER_PORT` - Adminer web UI port (default: `8081`)
+- `API_PORT`: Port for the API server (default: `8080`)
+- `SECRET_KEY`: Application secret key; generated automatically and stored in `.env` if not set
+- `ENVIRONMENT`: Environment name such as `development` or `production` (default: `production`)
+- `DEBUG_PORT`: Port for the Python debugger when using `--debug` (default: `5678`)
+- `DB_PORT`: PostgreSQL port (default: `5432`)
+- `DB_USER`: Database user (default: package name)
+- `DB_BASE`: Database name (default: package name)
+- `DB_PASS`: Database password; generated automatically and stored in `.env` if not set
+- `POSTGRES_VERSION`: PostgreSQL Docker image version (default: `17`)
+- `ADMINER_PORT`: Adminer web UI port (default: `8081`)
 
 ## How it works
 
@@ -202,10 +204,10 @@ Your project must meet the following requirements.
 
 Tasks that need configuration files (`pytest`, `coverage`, `flake8`, `isort`) follow this order of precedence.
 
-1. **`pyproject.toml` sections** - `[tool.pytest]`, `[tool.coverage]`, `[tool.isort]` take priority
-2. **Environment variables** - Override config paths (see [Environment Variables](#environment-variables))
-3. **Local config files** - `pytest.ini`, `.coveragerc`, `.flake8`, `.isort.cfg` in project root
-4. **Bundled defaults** - Sensible defaults included with this package, found in the [`src/common_python_tasks/data`](src/common_python_tasks/data) directory
+1. **`pyproject.toml` sections**: `[tool.pytest]`, `[tool.coverage]`, `[tool.isort]` take priority
+2. **Environment variables**: Override config paths; see [Environment Variables](#environment-variables)
+3. **Local config files**: `pytest.ini`, `.coveragerc`, `.flake8`, `.isort.cfg` in the project root
+4. **Bundled defaults**: Sensible defaults included with this package, found in the [`src/common_python_tasks/data`](src/common_python_tasks/data) directory
 
 You can start with zero configuration and customize as needed.
 
@@ -215,68 +217,68 @@ You can start with zero configuration and customize as needed.
 
 The following environment variables configure the paths to configuration files.
 
-- `PYTEST_CONFIG` specifies the path to the pytest configuration file
-- `COVERAGE_RCFILE` specifies the path to the coverage configuration file  
-- `FLAKE8_CONFIG` specifies the path to the flake8 configuration file
-- `ISORT_CONFIG` specifies the path to the isort configuration file
+- `PYTEST_CONFIG`: Specifies the path to the pytest configuration file
+- `COVERAGE_RCFILE`: Specifies the path to the coverage configuration file
+- `FLAKE8_CONFIG`: Specifies the path to the flake8 configuration file
+- `ISORT_CONFIG`: Specifies the path to the isort configuration file
 
 #### Package/Container settings
 
 The following environment variables configure package and container behavior.
 
-- `PACKAGE_NAME` overrides the package name (default is from `pyproject.toml`)
-- `POETRY_VERSION` overrides the Poetry version for container builds
-- `DOCKERHUB_USERNAME` specifies the Docker Hub username for image tagging (default is current local user)
-- `CONTAINER_REGISTRY_URL` specifies the registry URL (default is `docker.io/{username}`)
-- `CONTAINER_BUILD_ARGS` provides additional Docker build arguments in `KEY=VALUE:OTHER=VALUE` format
-- `CONTAINER_EXTENSION_FILES` specifies colon-delimited local extension Dockerfile paths to include in the rendered build.
-- `CONTAINER_EXTENSIONS` specifies colon-delimited extension bundle names or parameterized bundle values to include in the rendered build.
-- `CONTAINER_ENV` provides colon-delimited `KEY=VALUE` declarations to inject into the builder stage of the rendered Dockerfile.
-- `.containerenv` can also supply the same declarations from a file in the project root. It is the fallback source when neither `container_envfile` nor `CONTAINER_ENV` is provided.
-- `CONTAINER_PRUNE_KEEP` controls image pruning after builds (`-1` keep all, `0` keep latest only, `N` keep latest + `N` previous)
-- `CUSTOM_IMAGE_ENTRYPOINT` specifies a custom entrypoint script name for containers
-- `CONTAINER_DEPS_CONTENT` supplies inline Dockerfile instructions for a dependency image that installs artifacts into `/tmp/deps`
-- `CONTAINER_DEPS_FILE` points to one or more explicit Dockerfiles to build the dependency image. It may be a colon-delimited list of file paths and is used only when `CONTAINER_DEPS_CONTENT` is unset.
-- `CONTAINER_DEPS_MAPPINGS` maps copied dependency names from `/tmp/deps` into destination paths, as whitespace-separated `name:/target/path` entries. This is only used when `CONTAINER_DEPS_MOVE_SCRIPT` or `CONTAINER_DEPS_MOVE_SCRIPT_PATH` is not set.
-- `CONTAINER_DEPS_MOVE_SCRIPT` supplies a raw executable script to run after `/tmp/deps` is copied into the image. The script is written to `/tmp/container-deps-move-script` and executed with its own shebang.
-- `CONTAINER_DEPS_MOVE_SCRIPT_PATH` supplies a host path to a script file to run after `/tmp/deps` is copied into the image. This path takes precedence over `CONTAINER_DEPS_MOVE_SCRIPT` when both are set.
-- `GITHUB_RELEASE_ASSETS` colon-separated list of file paths or glob patterns to attach to the GitHub Release (default: `dist/*`)
-- `SKIP_GITHUB_RELEASE` truthy value to skip GitHub Release publication.
-- `GITHUB_TOKEN` or `GH_TOKEN` GitHub authentication token used to publish releases and upload assets.
-- `GITHUB_REPOSITORY` optional override for the repository slug used when publishing a GitHub Release.
-- `GITHUB_API_URL` and `GITHUB_SERVER_URL` configure the GitHub API host for GitHub Enterprise environments.
-- `GITHUB_RELEASE_TAG` optional tag name to publish for the GitHub Release.
-- `GITHUB_RELEASE_NAME` optional release title to use for the GitHub Release.
-- `GITHUB_RELEASE_BODY` optional release body text to use for the GitHub Release.
-- `RELEASE_UPDATE_CHANGELOG` truthy value to update `CHANGELOG.md` by prepending the `git-cliff --unreleased --tag "$RELEASE_TAG"` output before the release tag is created. This is enabled by default; set it to a falsy value to disable changelog commits during release.
-- `RELEASE_PRE_SCRIPT` optional shell command to run before the release steps.
-- `RELEASE_POST_SCRIPT` optional shell command to run after the release completes.
-- Hook commands receive the following env vars: `RELEASE_SCRIPT_PHASE`, `RELEASE_TAG`, `RELEASE_VERSION`, `RELEASE_STAGE`, `RELEASE_COMPONENT`, and `RELEASE_DRY_RUN`.
+- `PACKAGE_NAME`: Overrides the package name; the default comes from `pyproject.toml`
+- `POETRY_VERSION`: Overrides the Poetry version for container builds
+- `CONTAINER_REGISTRY_USERNAME`: Specifies the container registry username for image tagging; the default is the current local user
+- `CONTAINER_REGISTRY_URL`: Specifies the registry URL (default: `docker.io/{username}`)
+- `CONTAINER_BUILD_ARGS`: Provides additional Docker build arguments in `KEY=VALUE:OTHER=VALUE` format
+- `CONTAINER_EXTENSION_FILES`: Specifies colon delimited local extension Dockerfile paths to include in the rendered build
+- `CONTAINER_EXTENSIONS`: Specifies colon delimited extension bundle names or parameterized bundle values to include in the rendered build
+- `CONTAINER_ENV`: Provides colon delimited `KEY=VALUE` declarations to inject into the builder stage of the rendered Dockerfile
+- `.containerenv`: Can also supply the same declarations from a file in the project root. It is loaded first, then `container_envfile`, then `CONTAINER_ENV`, and finally `container_env`.
+- `CONTAINER_PRUNE_KEEP`: Controls image pruning after builds (`-1` keeps all, `0` keeps the latest only, `N` keeps the latest plus `N` previous)
+- `CUSTOM_ENTRYPOINT`: Specifies a custom entrypoint script name for containers
+- `CONTAINER_DEPS_CONTENT`: Supplies inline Dockerfile instructions for a dependency image that installs artifacts into `/tmp/deps`
+- `CONTAINER_DEPS_FILE`: Points to one or more explicit Dockerfiles to build the dependency image. It may be a colon delimited list of file paths and is used only when `CONTAINER_DEPS_CONTENT` is unset
+- `CONTAINER_DEPS_MAPPINGS`: Maps copied dependency names from `/tmp/deps` into destination paths as space separated `name:/target/path` entries. This is used only when `CONTAINER_DEPS_MOVE_SCRIPT` or `CONTAINER_DEPS_MOVE_SCRIPT_PATH` is not set
+- `CONTAINER_DEPS_MOVE_SCRIPT`: Supplies a raw executable script to run after `/tmp/deps` is copied into the image. The script is written to `/tmp/container-deps-move-script` and executed with its own shebang
+- `CONTAINER_DEPS_MOVE_SCRIPT_PATH`: Supplies a host path to a script file to run after `/tmp/deps` is copied into the image. This path takes precedence over `CONTAINER_DEPS_MOVE_SCRIPT` when both are set
+- `GITHUB_RELEASE_ASSETS`: Colon separated list of file paths or glob patterns to attach to the GitHub Release (default: `dist/*`)
+- `SKIP_GITHUB_RELEASE`: Truthy value to skip GitHub Release publication
+- `GITHUB_TOKEN` or `GH_TOKEN`: GitHub authentication token used to publish releases and upload assets
+- `GITHUB_REPOSITORY`: Optional override for the repository slug used when publishing a GitHub Release
+- `GITHUB_API_URL` and `GITHUB_SERVER_URL`: Configure the GitHub API host for GitHub Enterprise environments
+- `GITHUB_RELEASE_TAG`: Optional tag name to publish for the GitHub Release
+- `GITHUB_RELEASE_NAME`: Optional release title to use for the GitHub Release
+- `GITHUB_RELEASE_BODY`: Optional release body text to use for the GitHub Release
+- `RELEASE_UPDATE_CHANGELOG`: Truthy value to update `CHANGELOG.md` by prepending the `git-cliff --unreleased --tag "$RELEASE_TAG"` output before the release tag is created. This is enabled by default; set it to a falsy value if you want to disable changelog commits during release
+- `RELEASE_PRE_SCRIPT`: Optional shell command to run before the release steps
+- `RELEASE_POST_SCRIPT`: Optional shell command to run after the release completes
+- Hook commands: Receive the following env vars; `RELEASE_SCRIPT_PHASE`, `RELEASE_TAG`, `RELEASE_VERSION`, `RELEASE_STAGE`, `RELEASE_COMPONENT`, and `RELEASE_DRY_RUN`
 
 #### Docker Compose settings
 
 The following environment variables configure Docker Compose stacks (when using the `web` tag).
 
-- `COMPOSE_TYPE` specifies the type of application stack (e.g., `fastapi`)
-- `COMPOSE_ADDONS` colon-separated list of services to include (e.g., `db` for database)
-- `COMPOSE_FILE` overrides all compose files with colon-separated paths
-- `COMPOSE_OVERLAY_FILES` additional compose files to merge (colon-separated paths)
-- `API_PORT` port for the API server (default: `8080`)
-- `SECRET_KEY` application secret key (auto-generated if not set)
-- `ENVIRONMENT` environment name (default: `production`)
-- `DEBUG_PORT` port for Python debugger in debug mode (default: `5678`)
-- `DB_PORT` PostgreSQL port (default: `5432`)
-- `DB_USER` database user (default: package name)
-- `DB_BASE` database name (default: package name)
-- `DB_PASS` database password (auto-generated if not set)
-- `POSTGRES_VERSION` PostgreSQL version (default: `17`)
-- `ADMINER_PORT` Adminer web UI port (default: `8081`)
+- `COMPOSE_TYPE`: Specifies the type of application stack; for example, `fastapi`
+- `COMPOSE_ADDONS`: Colon separated list of services to include; for example, `db` for database support
+- `COMPOSE_FILE`: Overrides all compose files with colon separated paths
+- `COMPOSE_OVERLAY_FILES`: Additional compose files to merge; uses colon separated paths
+- `API_PORT`: Port for the API server (default: `8080`)
+- `SECRET_KEY`: Application secret key; generated automatically if not set
+- `ENVIRONMENT`: Environment name (default: `production`)
+- `DEBUG_PORT`: Port for the Python debugger in debug mode (default: `5678`)
+- `DB_PORT`: PostgreSQL port (default: `5432`)
+- `DB_USER`: Database user (default: package name)
+- `DB_BASE`: Database name (default: package name)
+- `DB_PASS`: Database password; generated automatically if not set
+- `POSTGRES_VERSION`: PostgreSQL version (default: `17`)
+- `ADMINER_PORT`: Adminer web UI port (default: `8081`)
 
 #### Debugging
 
 The following environment variable enables debugging output.
 
-- `COMMON_PYTHON_TASKS_LOG_LEVEL` should be set to `DEBUG` to see detailed configuration resolution
+- `COMMON_PYTHON_TASKS_LOG_LEVEL`: Set this to `DEBUG` to see detailed configuration resolution
 
 ### Usage examples
 
@@ -287,8 +289,8 @@ By default, `tasks()` exposes the common task set. You can still include or excl
 ```toml
 [project]
 name = "simple-cli-tool"
-version = "0.3.1"
-dependencies = ["common-python-tasks==0.3.1"]
+version = "0.4.0"
+dependencies = ["common-python-tasks==0.4.0"]
 
 [tool.poe]
 include_script = "common_python_tasks:tasks()"
@@ -300,15 +302,13 @@ Available tasks: common defaults such as `format`, `lint`, `test`, and `build`.
 
 ```toml
 [project]
-name = "containerized-app"
-version = "0.3.1"
-dependencies = ["common-python-tasks==0.3.1"]
+dependencies = ["common-python-tasks==0.4.0"]
 
 [tool.poe]
 include_script = "common_python_tasks:tasks(include_tags=['common', 'containers'])"
 
 [tool.poe.env]
-DOCKERHUB_USERNAME = "myusername"
+CONTAINER_REGISTRY_USERNAME = "myusername"
 PACKAGE_NAME = "containerized-app"
 ```
 
@@ -318,9 +318,7 @@ Available tasks: All tasks including `build-image` and `push-image`.
 
 ```toml
 [project]
-name = "custom-test-setup"
-dependencies = ["common-python-tasks==0.3.1"]
-dynamic = ["version"]
+dependencies = ["common-python-tasks==0.4.0"]
 
 [tool.poe]
 include_script = "common_python_tasks:tasks()"
@@ -348,13 +346,6 @@ include_script = "common_python_tasks:tasks(exclude_tags=['internal'])"
 includes = "common_python_tasks:tasks"
 ```
 
-### Version bump fails with "no changes since last tag"
-
-This is expected behavior. The `bump-version` task requires commits between the last tag and HEAD. You can resolve this in one of the following ways.
-
-- Make changes and commit them first
-- Delete the old tag (for example, `git tag -d v0.0.1`). This is not recommended. Versions should be immutable, and if you need to fix something, you should create a new patch version instead. Rarely do you want to pass off new code as an old version
-
 ### Config files not being used
 
 Check the configuration precedence (see [How it works](#how-it-works)). Use debug logging to see which config is selected.
@@ -385,7 +376,7 @@ If `stack-up` builds successfully but services can't connect:
 - Check that required environment variables are set (`COMPOSE_TYPE` at minimum)
 - Verify ports aren't already in use (defaults: 8080 for API, 5432 for database, 8081 for Adminer)
 - Check Docker daemon is running: `docker info`
-- View service logs: `docker-compose logs` in your project directory
+- View service logs: `docker compose logs` in your project directory
 
 ### Database migrations fail
 
@@ -406,21 +397,21 @@ If `SECRET_KEY` or `DB_PASS` aren't auto-generated:
 
 ## Design choices
 
-### Dockerfile (see [src/common_python_tasks/data/Dockerfile](src/common_python_tasks/data/Dockerfile))
+### Dockerfile (see [`src/common_python_tasks/data/generic/Dockerfile.j2`](src/common_python_tasks/data/generic/Dockerfile.j2))
 
 The standard Python Dockerfile incorporates several intentional design choices.
 
 - Multi-stage build: The build stage installs Poetry and builds a wheel while the runtime stage installs only the wheel to keep the final image slim and reproducible
-- Pip and Poetry cache mounts speed up iterative builds without bloating the final image
-- Explicit inputs through build args (`PYTHON_VERSION`, `POETRY_VERSION`, `PACKAGE_NAME`, `AUTHORS`, `GIT_COMMIT`, `CUSTOM_ENTRYPOINT`) make image metadata and behavior predictable and auditable
-- Optional debug stage exports and installs the `debug` dependency group only when present without failing otherwise and is not part of the default final image
-- Stable package path creates symlinks to the installed package so entrypoints and consumers have a consistent `/pkg` and `/_$PACKAGE_NAME` path regardless of wheel layout, which ensures that the package can be reliably imported and executed from a known location, and allows for the less common use case of reading files directly from the package path
-- Safe entrypoint selection means the default entrypoint resolves the console script matching the package name while `CUSTOM_ENTRYPOINT` allows overriding at build time while keeping runtime behavior predictable
-- Minimal final image uses the slim Python base by default, cleans wheel artifacts and caches, and sets `runtime` as the explicit final target so the debug stage is opt-in
+- Pip and Poetry cache mounts: Speed up iterative builds without bloating the final image
+- Explicit inputs through build args: `PYTHON_VERSION`, `POETRY_VERSION`, `PACKAGE_NAME`, `AUTHORS`, `GIT_COMMIT`, and `CUSTOM_ENTRYPOINT` make image metadata and behavior predictable and auditable
+- Optional debug stage: Exports and installs the `debug` dependency group only when present, without failing otherwise, and is not part of the default final image
+- Stable package path: Creates symlinks to the installed package so entrypoints and consumers have a consistent `/pkg` and `/_$PACKAGE_NAME` path regardless of wheel layout. This ensures that the package can be imported and executed from a known location and supports the less common case of reading files directly from the package path
+- Safe entrypoint selection: The default entrypoint resolves the console script matching the package name, while `CUSTOM_ENTRYPOINT` allows an override at build time and keeps runtime behavior predictable
+- Minimal final image: Uses the slim Python base by default, cleans wheel artifacts and caches, and sets `runtime` as the explicit final target so the debug stage remains optional
 
 ## Notes
 
-- This project dogfoods itself - it uses `common-python-tasks` for its own development. **That said, you must set the environment variable `PYTHONPATH=src` when running tasks locally to ensure you are using the local version of the package instead of the installed version**
+- This project dogfoods itself; it uses `common-python-tasks` for its own development. **That said, you must set the environment variable `PYTHONPATH=src` when running tasks locally to ensure you are using the local version of the package instead of the installed version**
 - `RELEASE_UPDATE_CHANGELOG` is enabled by default for releases and prepends a tagged section into `CHANGELOG.md` before the release tag is created. Set it to a falsy value if you prefer to manage changelog commits yourself.
 - `RELEASE_PRE_SCRIPT` and `RELEASE_POST_SCRIPT` hooks may not be necessary for most users, as this package promotes the use of `poetry-dynamic-versioning` and `git-cliff` to automate versioning and changelog generation based on git history. One advanced use case for the `RELEASE_PRE_SCRIPT` hook is to edit another file before release, such as a README that references the current stable version number. This allows you to keep the README up to date with the latest version without hardcoding it.
 - Contributions welcome! Open an issue/discussion to discuss changes before submitting a PR. I do not claim to have all the answers, and you can help determine the future of low-code solutions for Python. I am very interested in your feedback as I don't want to work in a vacuum