common-python-tasks 0.10.2__py3-none-any.whl → 0.11.0__py3-none-any.whl

common_python_tasks/data/fastapi/compose-db.yml.j2

@@ -1,7 +1,7 @@
 x-common-environment: &common-environment
   {{ ENV_PREFIX }}_DB_BASE: ${DB_BASE}
   {{ ENV_PREFIX }}_DB_HOST: db
-  {{ ENV_PREFIX }}_DB_PORT: ${DB_PORT}
+  {{ ENV_PREFIX }}_DB_PORT: 5432
   {{ ENV_PREFIX }}_DB_PASS: ${DB_PASS}
   {{ ENV_PREFIX }}_DB_USER: ${DB_USER}
 

common_python_tasks/data/generic/Dockerfile.j2

@@ -12,6 +12,13 @@ FROM python:${PYTHON_VERSION} AS builder
 ARG PACKAGE_VERSION
 ARG UV_VERSION
 
+{% if CONTAINER_ENV_VARS %}
+# Make configured variables available to package build commands.
+{% for env_var in CONTAINER_ENV_VARS -%}
+ENV {{ env_var }}
+{% endfor %}
+{%- endif %}
+
 # Bypass VCS-based version detection: use the host-computed version directly.
 # This avoids requiring a .git directory in the build context and prevents
 # false dirty-version detection from a partial working tree.
@@ -60,7 +67,7 @@ ARG NONROOT_UID=1000
 ARG NONROOT_GID=1000
 
 {% if CONTAINER_ENV_VARS %}
-# Inject custom builder stage environment variables
+# Persist the same variables for runtime build commands and running containers.
 {% for env_var in CONTAINER_ENV_VARS -%}
 ENV {{ env_var }}
 {% endfor %}

common_python_tasks/docker_compose.py

@@ -606,6 +606,7 @@ def build_exec_script(
         "trap 'rm -f \"$SCRIPT_PATH\"' EXIT",
         "",
         " ".join(quote(str(arg)) for arg in command),
+        "command_status=$?",
     ]
 
     if teardown_command:
@@ -619,7 +620,7 @@ def build_exec_script(
         for path in cleanup_paths:
             lines.append(f"rm -f {quote(str(path))}")
 
-    lines.append("")
+    lines.extend(['exit "$command_status"', ""])
 
     script_path.write_text("\n".join(lines), encoding="utf-8")
     script_path.chmod(0o700)

common_python_tasks/env.py

@@ -537,6 +537,7 @@ def render_container_deps_move_script(mappings: dict[str, str]) -> str:
     import textwrap
 
     script_lines = [
+        "#!/usr/bin/env python3",
         "import pathlib",
         "import shutil",
         "import sys",

common_python_tasks/git.py

@@ -335,7 +335,14 @@ def has_tags_later_in_history() -> bool:
             capture_output=True,
             acceptable_returncodes={0, 1},
         )
-        if check_result.returncode == 1:
+        if (
+            check_result.returncode == 0
+            and utils.run_command(
+                ["git", "rev-list", "--count", f"HEAD..{tag}"],
+                capture_output=True,
+            ).stdout.strip()
+            != "0"
+        ):
             return True
 
     return False

common_python_tasks/project.py

@@ -154,7 +154,9 @@ def get_dependency_update_command(
     if dependencies is None:
         dependencies = []
 
-    command = ["uv", "sync", "--upgrade"]
+    command = ["uv", "sync"]
+    if not dependencies:
+        command.append("--upgrade")
     for dependency in dependencies:
         command.extend(["--upgrade-package", dependency])
     return command

common_python_tasks/tasks.py

@@ -406,6 +406,58 @@ def lint_all() -> None:
     run_command(_get_ruff_command("format", "--check", Path(".")))
 
 
+@tasks.script(task_name="docs-build", tags=["docs"])
+def docs_build(config_file: str | None = None, clean: bool = False) -> None:
+    """Build the Zensical documentation site in strict mode.
+
+    Args:
+        config_file: Optional path to a Zensical configuration file.
+        clean: Remove cached files before building the site.
+    """
+    from .utils import require_package, run_command
+
+    require_package("zensical")
+    run_command(
+        [
+            "zensical",
+            "build",
+            "--strict",
+            "--clean" if clean else None,
+            "--config-file" if config_file else None,
+            config_file,
+        ]
+    )
+
+
+@tasks.script(task_name="docs-serve", tags=["docs"])
+def docs_serve(
+    config_file: str | None = None,
+    dev_addr: str | None = None,
+    open_browser: bool = False,
+) -> None:
+    """Serve the Zensical documentation site for local preview.
+
+    Args:
+        config_file: Optional path to a Zensical configuration file.
+        dev_addr: Optional development server address in `IP:PORT` form.
+        open_browser: Open the preview in the default browser.
+    """
+    from .utils import require_package, run_command
+
+    require_package("zensical")
+    run_command(
+        [
+            "zensical",
+            "serve",
+            "--config-file" if config_file else None,
+            config_file,
+            "--dev-addr" if dev_addr else None,
+            dev_addr,
+            "--open" if open_browser else None,
+        ]
+    )
+
+
 @tasks.script(tags=["containers", "build"])
 def build_image(
     *docker_build_args: str,
@@ -430,9 +482,9 @@ def build_image(
         dockerfile_hook_path: Optional executable script path that can mutate
             the generated Dockerfile before build. Overrides
             CONTAINER_DOCKERFILE_HOOK_PATH if provided.
-        container_env: Builder-stage environment declarations as repeated
+        container_env: Builder and runtime environment declarations as repeated
             KEY=VALUE values.
-        container_envfile: Optional repeated list of files containing builder-stage
+        container_envfile: Optional repeated list of files containing builder and runtime
             environment declarations.
 
     Precedence for container env declarations is: .containerenv, container_envfile,
@@ -524,7 +576,7 @@ def build_image(
     )
     if container_env_vars:
         LOGGER.debug(
-            "Injecting builder-stage env vars: %s",
+            "Injecting builder and runtime env vars: %s",
             ", ".join(container_env_vars),
         )
     top_level_build_args = inject_auto_build_args_from_env(
@@ -1731,26 +1783,49 @@ def fastapi_run_db_migrations() -> None:
     """Run database migrations."""
     from .docker_compose import (
         cleanup_temp_files,
+        ensure_secrets_generated,
         load_and_prepare_compose,
         run_docker_compose_command,
     )
 
-    services = ["db", "migrator"]
-    fastapi_stack_up(debug=False, detach=True, services=services)
+    container_build = build_image(single_arch=True)
+    ensure_secrets_generated()
+    compose_files, temp_compose_files, temp_config_files, compose_env = (
+        load_and_prepare_compose(image_tag=container_build.commit_tag)
+    )
     try:
-        compose_files, temp_compose_files, _, compose_env = load_and_prepare_compose()
+        run_docker_compose_command(
+            "up",
+            "-d",
+            "--no-build",
+            "db",
+            compose_files=compose_files,
+            compose_env=compose_env,
+            tasks=tasks,
+        )
+        run_docker_compose_command(
+            "run",
+            "--rm",
+            "migrator",
+            compose_files=compose_files,
+            compose_env=compose_env,
+            tasks=tasks,
+        )
+    finally:
         try:
             run_docker_compose_command(
-                "logs",
+                "rm",
+                "-f",
+                "-s",
+                "-v",
+                "db",
                 "migrator",
                 compose_files=compose_files,
                 compose_env=compose_env,
                 tasks=tasks,
             )
         finally:
-            cleanup_temp_files(temp_compose_files)
-    finally:
-        fastapi_stack_down()
+            cleanup_temp_files(temp_compose_files, temp_config_files)
 
 
 @tasks.script(task_name="db-shell", tags=["web", "containers", "database", "fastapi"])

common_python_tasks-0.11.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: common-python-tasks
+Version: 0.11.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
+Project-URL: Issues, http://github.com/ci-sourcerer/common-python-tasks/issues
+Author-email: Joseph Asbury <ci_sourcerer@yahoo.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: <4.0,>=3.11
+Requires-Dist: docker<8.0.0,>=7.1.0
+Requires-Dist: dunamai<2.0.0,>=1.25.0
+Requires-Dist: git-cliff<3.0.0,>=2.12.0
+Requires-Dist: jinja2<4.0.0,>=3.1.6
+Requires-Dist: packaging<27.0,>=26.2
+Requires-Dist: poethepoet-tasks<0.4.0,>=0.3.0
+Requires-Dist: pytest-cov<8.0.0,>=7.0.0
+Requires-Dist: pytest<10.0.0,>=9.0.3
+Requires-Dist: requests<3.0.0,>=2.34.2
+Requires-Dist: ruff<0.17.0,>=0.16.1
+Requires-Dist: tomlkit<0.14.0,>=0.13.3
+Requires-Dist: zensical<0.1.0,>=0.0.59
+Description-Content-Type: text/markdown
+
+# Common Python Tasks
+
+`common-python-tasks` provides reusable, opinionated [Poe the Poet](https://poethepoet.natn.io/guides/packaged_tasks.html) tasks for Python development, packaging, releases, containers, and documentation.
+
+Read the [complete documentation](https://ci-sourcerer.github.io/common-python-tasks/) for the task reference, configuration options, and deployment guidance.
+
+## Quick start
+
+Add the package as a development dependency.
+
+```shell
+uv add --dev common-python-tasks==0.11.0
+```
+
+Expose the default task set in `pyproject.toml`.
+
+```toml
+[tool.poe]
+include_script = "common_python_tasks:tasks()"
+```
+
+Run the everyday development tasks.
+
+```shell
+poe format
+poe lint
+poe test
+```
+
+## Optional workflows
+
+Select additional task groups with `include_tags`.
+
+```toml
+[tool.poe]
+include_script = "common_python_tasks:tasks(include_tags=['common', 'docs', 'containers'])"
+```
+
+| Tag | Purpose |
+| - | - |
+| `common` | Formatting, linting, testing, packaging, and releases |
+| `docs` | Build and serve Zensical documentation |
+| `containers` | Build, run, inspect, and publish container images |
+| `fastapi` | Run the FastAPI and PostgreSQL development stack |
+
+Documentation projects can build locally or start a development server.
+
+```shell
+poe docs-build
+poe docs-serve
+```
+
+The [documentation workflow guide](https://ci-sourcerer.github.io/common-python-tasks/documentation-workflows/) covers GitHub Actions artifacts, optional Cloudflare Pages previews, and GitHub Pages deployment.
+
+## Learn more
+
+- [Getting started](https://ci-sourcerer.github.io/common-python-tasks/getting-started/)
+- [Task reference](https://ci-sourcerer.github.io/common-python-tasks/tasks/)
+- [Configuration reference](https://ci-sourcerer.github.io/common-python-tasks/configuration/)
+
+The project is in alpha, so minor releases may contain breaking changes. It is distributed under the [MIT license](LICENSE).

{common_python_tasks-0.10.2.dist-info → common_python_tasks-0.11.0.dist-info}/RECORD

@@ -1,27 +1,27 @@
 common_python_tasks/__init__.py,sha256=tqRLgOwmMQHDb1A84XbML9sWfzMymkSPhJjoF6aCHgA,916
 common_python_tasks/__main__.py,sha256=GpgSd_toMbEaWA_cZvgsZE7jo4XpzuI-awBVm2uhVyw,3512
 common_python_tasks/docker.py,sha256=_YW-hyHWlUK-kMCvI6QTgxSfmXQQKhYLOKRBPfUmtHA,24176
-common_python_tasks/docker_compose.py,sha256=tEChLNxlcBMQXy2wjZrVsmFxFrvt3CmJYBpc-7Q4bK0,21281
-common_python_tasks/env.py,sha256=QSSu4NbnV5oKqMBDBAXPh6oJHYmumoAZRRpRmSQsmvk,19662
-common_python_tasks/git.py,sha256=znfLSEwAUYL6nFK4fjLhzdjFu9Pc3ppPdU9m2QCHaKw,11511
+common_python_tasks/docker_compose.py,sha256=NGgMei3oCYS0RbNaQXE-2veXFylO3XtZ7lU-PTtocik,21338
+common_python_tasks/env.py,sha256=1YLSxsUP9lPn51_zraM3nAiN1J7aKdUHzjzDzxXLo34,19696
+common_python_tasks/git.py,sha256=0X472w_vHdtbrHHxCmJ85NoQjjogEEDs_0SRXfxbWi0,11719
 common_python_tasks/github.py,sha256=_LVanl-z4PsdLM94L8y7tkX-AZO2n3Qy39FRY7reDhA,21589
-common_python_tasks/project.py,sha256=B3uHA5wgSLfeYVYDQJCCSCr323IX_VpcDILsOxBU7hs,17329
-common_python_tasks/tasks.py,sha256=sTG4GtUXVxQ8ZWKWGuWdghI03DFyXLbSee8Xc6g0nv0,59519
+common_python_tasks/project.py,sha256=PQ_GQicTrSQgVDB9cJ9E6pU0UhLPom2xou1sGFscr3E,17377
+common_python_tasks/tasks.py,sha256=Ajqw7mnfMwfiOdTuVGvGJQAp_DQxEnqDc9e8y3VFcT8,61636
 common_python_tasks/utils.py,sha256=hR7w0Cb7uQ7ILyIegTQ4znWHVoWANlCgxrOnO-Rh5oE,20798
 common_python_tasks/data/dockerfile_extensions/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 common_python_tasks/data/fastapi/alembic.ini.j2,sha256=dOiAmZngzX6eyVXeM6BhzgQmes2zwUEdKwOgm8mxjMs,985
 common_python_tasks/data/fastapi/compose-base.yml.j2,sha256=vDLPAdRJ66lsWZdsKbYqEvY_liXaHZ0ly4ljzqmJsyY,910
 common_python_tasks/data/fastapi/compose-db-debug.yml.j2,sha256=iREdSy4F8tJ5m9rlB6CROBkj9OtDFVuGphqIuDvHhww,1193
-common_python_tasks/data/fastapi/compose-db.yml.j2,sha256=16i2rrsYPIJIQn4gpopr5-8KBirMS7OwpXHPaAC03k8,1777
+common_python_tasks/data/fastapi/compose-db.yml.j2,sha256=G1vdAqy8Cxa-8DDz6eHNuD2xigpTxINACxrs2eY4KkU,1771
 common_python_tasks/data/fastapi/compose-debug.yml.j2,sha256=sIH9IFvmRAszN6wSejpGVQygXh1g2lVmlzOgPhTx5CY,661
 common_python_tasks/data/generic/.coveragerc,sha256=8zXwDq18wIKQV4NtW2NJYpo3nxCO4LsAChyluYTUoJc,85
 common_python_tasks/data/generic/.dockerignore,sha256=8kHwNa6Ct-6y3EvRjNuhOKfquuGEywq3P2BHIbG4uXo,53
 common_python_tasks/data/generic/Dockerfile.deps.j2,sha256=fBmcytyUd4LsC26y0IgZ09QPxrFp0gx0d3OlKNqZ-KM,663
-common_python_tasks/data/generic/Dockerfile.j2,sha256=0K_gNC35wiP1-yOO2UB2WoeCoz0iW5pS7walajsXFPE,6016
+common_python_tasks/data/generic/Dockerfile.j2,sha256=hgLrIRU5xvS2xqw9Xm4kfkcBGHH-mghFPlWv3KSNaz4,6223
 common_python_tasks/data/generic/cliff.toml,sha256=po1MnEGEEgrpyBz3XLWr0h7emXb6ASX63lrU2r6o240,77
 common_python_tasks/data/generic/pytest.ini,sha256=RHak5QrLzKHvUBjFmaaiOYFrd_8YBRQubXEOT0NJfco,134
 common_python_tasks/data/generic/ruff.toml,sha256=njvd-5inSGmgY865SWCT4SR9IrKlzS7JQFZmAG2UT_E,53
-common_python_tasks-0.10.2.dist-info/METADATA,sha256=0dWkJuwdXMGU7CzQEHtzyRvZ47JKdUBbhXEjRhKoMkE,22028
-common_python_tasks-0.10.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-common_python_tasks-0.10.2.dist-info/licenses/LICENSE,sha256=RsSweM-DyzxFPx38fQOJqHrKyeT9Fiz8rO7yox-fOsw,1070
-common_python_tasks-0.10.2.dist-info/RECORD,,
+common_python_tasks-0.11.0.dist-info/METADATA,sha256=00ugE5R39fK6NpEH2LDIaUm87vNhxC2jVTGoa_FI4aI,3307
+common_python_tasks-0.11.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+common_python_tasks-0.11.0.dist-info/licenses/LICENSE,sha256=RsSweM-DyzxFPx38fQOJqHrKyeT9Fiz8rO7yox-fOsw,1070
+common_python_tasks-0.11.0.dist-info/RECORD,,

common_python_tasks-0.10.2.dist-info/METADATA

@@ -1,442 +0,0 @@
-Metadata-Version: 2.5
-Name: common-python-tasks
-Version: 0.10.2
-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
-Project-URL: Issues, http://github.com/ci-sourcerer/common-python-tasks/issues
-Author-email: Joseph Asbury <ci_sourcerer@yahoo.com>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: Build Tools
-Requires-Python: <4.0,>=3.11
-Requires-Dist: docker<8.0.0,>=7.1.0
-Requires-Dist: dunamai<2.0.0,>=1.25.0
-Requires-Dist: git-cliff<3.0.0,>=2.12.0
-Requires-Dist: jinja2<4.0.0,>=3.1.6
-Requires-Dist: packaging<27.0,>=26.2
-Requires-Dist: poethepoet-tasks<0.4.0,>=0.3.0
-Requires-Dist: pytest-cov<8.0.0,>=7.0.0
-Requires-Dist: pytest<10.0.0,>=9.0.3
-Requires-Dist: requests<3.0.0,>=2.34.2
-Requires-Dist: ruff<0.17.0,>=0.16.1
-Requires-Dist: tomlkit<0.14.0,>=0.13.3
-Description-Content-Type: text/markdown
-
-# Common Python Tasks
-
-`common-python-tasks` provides reusable, opinionated [Poe the Poet](https://poethepoet.natn.io/guides/packaged_tasks.html) tasks for common Python development workflows.
-
-It supplies sensible defaults for formatting, linting, testing, packaging, releases, and container workflows while allowing projects to override configuration when needed.
-
-## Quick start
-
-### Manual setup
-
-Add `common-python-tasks` as a development dependency from your project root.
-
-```shell
-uv add --dev common-python-tasks==0.10.2
-```
-
-Configure Poe the Poet to expose the default `common` task set.
-
-```toml
-[tool.poe]
-include_script = "common_python_tasks:tasks()"
-```
-
-Run the common development tasks.
-
-```shell
-poe format
-poe lint
-poe test
-```
-
-### Automated setup
-
-The helper script performs the same development-dependency installation and Poe configuration. Download the script for the exact release you want, review it, then run it from your project root.
-
-```shell
-curl --fail --silent --show-error --location \
-  --output /tmp/add_common_python_tasks.py \
-  https://raw.githubusercontent.com/ci-sourcerer/common-python-tasks/v0.10.2/scripts/add_common_python_tasks.py
-```
-
-Review the downloaded script before executing it.
-
-```shell
-less /tmp/add_common_python_tasks.py
-```
-
-Run the reviewed script with the same pinned package version.
-
-```shell
-COMMON_PYTHON_TASKS_VERSION=0.10.2 python3 /tmp/add_common_python_tasks.py
-```
-
-To install another release, replace both occurrences of `0.10.2` with that release's version.
-
-## Available tasks
-
-The generated tables below list public tasks only. Tags identify which tasks are selected by `include_tags` and `exclude_tags`.
-
-<!-- tasks-table -->
-
-### Daily development
-
-| Task | Description | Tags |
-| --- | --- | --- |
-| `test` | Run the test suite with coverage (if pytest-cov is installed). | common, test |
-| `clean` | Clean up temporary files and directories. | clean, common |
-| `format` | Fix import issues and format Python code with Ruff. | common, format |
-| `lint` | Check Python lint and formatting with Ruff. | common, lint |
-
-### Packaging and releases
-
-| Task | Description | Tags |
-| --- | --- | --- |
-| `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 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 |
-| `release` | Run a full release flow for package and containers. | common, containers, packaging, release |
-
-### Container images
-
-| Task | Description | Tags |
-| --- | --- | --- |
-| `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, 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 |
-| `build` | Build the project and its containers. | common, containers, packaging |
-| `container-shell` | Run the debug image with an interactive shell. | containers, debug |
-
-### Development stacks
-
-| Task | Description | Tags |
-| --- | --- | --- |
-| `stack-up` | Bring up the development stack for the application. | containers, fastapi, web |
-| `stack-down` | Bring down the development stack for the application. | containers, fastapi, web |
-| `reset-db` | Reset the database by deleting the database volume. | containers, database, fastapi, web |
-| `run-db-migrations` | Run database migrations. | containers, database, fastapi, web |
-| `db-shell` | Open a psql shell to the database container. | containers, database, fastapi, web |
-
-<!-- end-tasks-table -->
-
-## Configuration and requirements
-
-### Requirements
-
-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 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
-
-Calling `tasks()` without arguments exposes the default `common` task set.
-
-```toml
-[tool.poe]
-include_script = "common_python_tasks:tasks()"
-```
-
-Select optional task groups with tags when your project needs them.
-
-```toml
-[tool.poe]
-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 management
-
-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`.
-
-### Publish target selection
-
-The `publish-package` task resolves publish targets with this precedence.
-
-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
-
-For pytest and coverage, configuration resolves in the following order.
-
-1. Matching `pyproject.toml` sections such as `[tool.pytest.ini_options]` and `[tool.coverage]`
-2. Environment variables that specify a configuration path
-3. Local configuration files in the project root
-4. Bundled defaults from [`src/common_python_tasks/data`](src/common_python_tasks/data)
-
-Ruff uses `RUFF_CONFIG` when set. Otherwise it discovers `.ruff.toml`, `ruff.toml`, or a `[tool.ruff]` section in `pyproject.toml`. When no project configuration is available, the tasks use the bundled Ruff defaults. Ruff configuration follows Ruff's native file precedence, so `.ruff.toml` takes precedence over `ruff.toml`, which takes precedence over `pyproject.toml` in the same directory.
-
-The `format` task first applies safe fixes for unused imports and import sorting, then runs the Ruff formatter. The `lint` task checks both Ruff lint rules and formatting without changing files.
-
-### Configuration examples
-
-After installing the package, a minimal project configuration looks like this.
-
-```toml
-[project]
-name = "simple-cli-tool"
-version = "0.10.2"
-
-[tool.poe]
-include_script = "common_python_tasks:tasks()"
-```
-
-A container-based project can select the container task group and set its image details.
-
-```toml
-[tool.poe]
-include_script = "common_python_tasks:tasks(include_tags=['common', 'containers'])"
-
-[tool.poe.env]
-CONTAINER_REGISTRY_USERNAME = "myusername"
-PACKAGE_NAME = "containerized-app"
-```
-
-The `test` task automatically uses pytest configuration in `pyproject.toml`.
-
-```toml
-[tool.pytest.ini_options]
-testpaths = ["tests", "integration"]
-addopts = "-ra"
-```
-
-### Environment variables
-
-#### Task configuration files
-
-- `PYTEST_CONFIG`: Path to the pytest configuration file
-- `COVERAGE_RCFILE`: Path to the coverage configuration file
-- `RUFF_CONFIG`: Path to a Ruff TOML configuration file
-
-#### Project and package settings
-
-- `PACKAGE_NAME`: Overrides the package name inferred from `pyproject.toml`
-- `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_PYTHON_VARIANT`: Python base-image variant such as `slim`, `alpine`, etc. See <https://hub.docker.com/_/python> for available options. Defaults to `slim`; set to empty string for no variant (e.g., `FROM python:3.11`). The value is passed as the `PYTHON_VARIANT` Docker build argument and recorded in the `org.opencontainers.image.python.variant` image label.
-- `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.
-- `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.
-- `CONTAINER_DEPS_MOVE_SCRIPT`: Raw executable script to run after `/tmp/deps` is copied into the image
-- `CONTAINER_DEPS_MOVE_SCRIPT_PATH`: Host path to a dependency move script. This takes precedence over `CONTAINER_DEPS_MOVE_SCRIPT`.
-- `UV_INDEX_{name}_USERNAME` and `UV_INDEX_{name}_PASSWORD`: Private Python index credentials consumed by uv during the Docker build. When any of these are set, the task automatically passes them as BuildKit secrets (`--secret id=uv_index_{name}_username,env=...`) and renders matching `--mount=type=secret` directives in the builder stage so uv can authenticate without baking credentials into the image. Multiple indices are supported; replace `{name}` with the uppercase index name (hyphens as underscores). These can be set in `tool.poe.env` for CI/CD or in the local environment for development.
-
-#### Release settings
-
-- `GITHUB_RELEASE_ASSETS`: Colon-delimited file paths or glob patterns to attach to a GitHub Release. The default is `dist/*`; escape literal colons as `\:` or quote the complete path.
-- `SKIP_GITHUB_RELEASE`: Truthy value that skips GitHub Release publication
-- `GITHUB_TOKEN` or `GH_TOKEN`: GitHub authentication token for releases and assets
-- `GITHUB_REPOSITORY`: Optional repository-slug override for GitHub Release publication
-- `GITHUB_API_URL` and `GITHUB_SERVER_URL`: GitHub Enterprise API-host settings
-- `GITHUB_RELEASE_TAG`: Optional release tag name
-- `GITHUB_RELEASE_NAME`: Optional release title
-- `GITHUB_RELEASE_BODY`: Optional release body
-- `RELEASE_UPDATE_CHANGELOG`: Truthy value that prepends `git-cliff --unreleased --tag "$RELEASE_TAG"` output to `CHANGELOG.md` before the release tag is created. It is enabled by default.
-- `RELEASE_PRE_SCRIPT`: Optional shell command to run before release steps
-- `RELEASE_POST_SCRIPT`: Optional shell command to run after release completion
-- Release hooks receive `RELEASE_SCRIPT_PHASE`, `RELEASE_TAG`, `RELEASE_VERSION`, `RELEASE_STAGE`, `RELEASE_COMPONENT`, and `RELEASE_DRY_RUN`.
-
-#### Docker Compose settings
-
-- `COMPOSE_TYPE`: Application-stack type, such as `fastapi`
-- `COMPOSE_ADDONS`: Colon-delimited services to include, such as `db`
-- `COMPOSE_FILE`: Override for all compose files with colon-delimited paths
-- `COMPOSE_OVERLAY_FILES`: Additional compose files to merge with colon-delimited paths
-- `API_PORT`: API server port with a default of `8080`
-- `SECRET_KEY`: Application secret key generated automatically when unset
-- `ENVIRONMENT`: Environment name with a default of `production`
-- `DEBUG_PORT`: Python debugger port in debug mode with a default of `5678`
-- `DB_PORT`: PostgreSQL port with a default of `5432`
-- `DB_USER`: Database user with a default of the package name
-- `DB_BASE`: Database name with a default of the package name
-- `DB_PASS`: Database password generated automatically when unset
-- `POSTGRES_VERSION`: PostgreSQL version with a default of `17`
-- `ADMINER_PORT`: Adminer web UI port with a default of `8081`
-
-#### Debugging
-
-- `COMMON_PYTHON_TASKS_LOG_LEVEL`: Set to `DEBUG` to show detailed configuration resolution
-
-## Containers and development stacks
-
-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.
-
-```toml
-[tool.poe.env]
-COMPOSE_TYPE = "fastapi"
-```
-
-Set `COMPOSE_ADDONS` to select extra services. Addon names are colon-delimited, and `db` is the currently available addon.
-
-```toml
-[tool.poe.env]
-COMPOSE_ADDONS = "db"
-```
-
-### Compose-file customization
-
-The compose setup resolves files in this precedence order.
-
-1. **Environment override** uses `COMPOSE_FILE` with colon-delimited paths.
-2. **Automatically loaded files** are based on `COMPOSE_TYPE` and `COMPOSE_ADDONS`.
-   - `compose-base.yml` provides the core application service.
-   - `compose-{addon}.yml` adds one file per addon, such as `compose-db.yml`.
-   - `compose-debug.yml` is used when the `--debug` flag is present.
-   - `compose-{addon}-debug.yml` provides debug overlays for addons.
-3. **Additional overlays** use `COMPOSE_OVERLAY_FILES` with colon-delimited paths.
-
-You can provide local compose files or allow the tasks to use bundled templates.
-
-### FastAPI stack
-
-The FastAPI stack uses the standard Dockerfile supplied by this package. Configure its ports, credentials, and database settings through the [Docker Compose settings](#docker-compose-settings) reference.
-
-## Troubleshooting
-
-### Tasks not showing up with `poe --help`
-
-Check the `[tool.poe]` configuration in `pyproject.toml` and use `include_script`.
-
-```toml
-# Correct
-[tool.poe]
-include_script = "common_python_tasks:tasks(exclude_tags=['internal'])"
-
-# Incorrect
-[tool.poe]
-includes = "common_python_tasks:tasks"
-```
-
-### Config files not being used
-
-Review the [configuration precedence](#configuration-precedence) and enable debug logging to see the selected configuration.
-
-```shell
-COMMON_PYTHON_TASKS_LOG_LEVEL=DEBUG poe test
-```
-
-### GitHub Release assets not uploading
-
-Confirm that `dist/` contains the built wheels and source distributions. You can override the default asset selection with `GITHUB_RELEASE_ASSETS`.
-
-```shell
-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 a `src` layout built with Hatch, configure `[tool.hatch.build.targets.wheel] packages = ["src/your_package"]`.
-
-### Stack fails to start or services cannot connect
-
-Check the following conditions.
-
-- `COMPOSE_TYPE` is set and the required addon is selected.
-- Default ports are available, including `8080` for the API, `5432` for PostgreSQL, and `8081` for Adminer.
-- The Docker daemon is running, as verified with `docker info`.
-- Service logs are available through `docker compose logs` in the project directory.
-
-### Database migrations fail
-
-Verify that the `db` addon is selected, Alembic is configured at the expected location, and its credentials match the generated `.env` values. Use `poe db-shell` to inspect the database manually.
-
-### Secrets are not generated
-
-Ensure the project-root `.env` file is writable and inspect its permissions with `ls -la .env`. You can also generate a value manually with `python -c "import secrets; print(secrets.token_hex(32))"`.
-
-## Design choices
-
-### Dockerfile design
-
-See the [standard Dockerfile template](src/common_python_tasks/data/generic/Dockerfile.j2) for the implementation.
-
-- 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`. `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
-
-- This project dogfoods itself. Set `PYTHONPATH=src` when running its tasks locally so Poe uses the local package rather than the installed version.
-- `RELEASE_UPDATE_CHANGELOG` is enabled by default and prepends the generated changelog section before the release tag is created. Set it to a falsy value to manage changelog commits yourself.
-- `RELEASE_PRE_SCRIPT` and `RELEASE_POST_SCRIPT` are advanced hooks for release-specific work, such as updating a version reference in another file.
-- The project is in alpha status, so breaking changes may occur between minor versions before 1.0.0.
-
-## Contributing
-
-Contributions and feedback are welcome. Please open an issue or discussion to talk through a change before submitting a pull request.