common-python-tasks 0.10.3__py3-none-any.whl → 0.11.1__py3-none-any.whl

common_python_tasks/env.py

@@ -3,6 +3,7 @@ import os
 import re
 import secrets
 import shlex
+from collections.abc import Iterator
 from pathlib import Path
 
 from . import utils
@@ -53,51 +54,47 @@ def collect_uv_index_credentials() -> list[dict[str, str | None]]:
     ]
 
 
+def _iter_uv_index_secrets(
+    credentials: list[dict[str, str | None]],
+) -> Iterator[tuple[str, str]]:
+    for credential in credentials:
+        index_name = credential["index_name"].lower()
+        for credential_type in ("username", "password"):
+            environment_name = credential[f"{credential_type}_env"]
+            if environment_name:
+                yield f"uv_index_{index_name}_{credential_type}", environment_name
+
+
 def uv_index_secret_mounts(credentials: list[dict[str, str | None]]) -> list[str]:
-    """Return Dockerfile ``--mount`` strings for UV index credentials.
+    """Return Dockerfile `--mount` strings for UV index credentials.
 
     Args:
         credentials: Output of `collect_uv_index_credentials`.
 
     Returns:
-        A list of ``type=secret,...`` strings for Dockerfile ``RUN --mount=``
+        A list of `type=secret,...` strings for Dockerfile `RUN --mount=`
         directives.
     """
-    mounts = []
-    for cred in credentials:
-        name = cred["index_name"].lower()
-        if cred["username_env"]:
-            mounts.append(
-                f"type=secret,id=uv_index_{name}_username,env={cred['username_env']}"
-            )
-        if cred["password_env"]:
-            mounts.append(
-                f"type=secret,id=uv_index_{name}_password,env={cred['password_env']}"
-            )
-    return mounts
+    return [
+        f"type=secret,id={secret_id},env={environment_name}"
+        for secret_id, environment_name in _iter_uv_index_secrets(credentials)
+    ]
 
 
 def uv_index_secret_build_args(credentials: list[dict[str, str | None]]) -> list[str]:
-    """Return ``docker build --secret`` arg pairs for UV index credentials.
+    """Return `docker build --secret` arg pairs for UV index credentials.
 
     Args:
         credentials: Output of `collect_uv_index_credentials`.
 
     Returns:
-        A flat list of ``--secret`` flag-value pairs for the docker build command.
+        A flat list of `--secret` flag-value pairs for the docker build command.
     """
-    args = []
-    for cred in credentials:
-        name = cred["index_name"].lower()
-        if cred["username_env"]:
-            args.extend(
-                ["--secret", f"id=uv_index_{name}_username,env={cred['username_env']}"]
-            )
-        if cred["password_env"]:
-            args.extend(
-                ["--secret", f"id=uv_index_{name}_password,env={cred['password_env']}"]
-            )
-    return args
+    return [
+        item
+        for secret_id, environment_name in _iter_uv_index_secrets(credentials)
+        for item in ("--secret", f"id={secret_id},env={environment_name}")
+    ]
 
 
 def env_truthy(env_var: str) -> bool:
@@ -330,6 +327,28 @@ def resolve_container_docker_build_args(
         utils.fatal(f"Invalid CONTAINER_DOCKER_BUILD_ARGS: {error}")
 
 
+def _resolve_optional_file_path(
+    cli_path: str | None,
+    environment_path: str | None,
+    description: str,
+) -> Path | None:
+    resolved_path = next(
+        (
+            Path(value.strip())
+            for value in (cli_path, environment_path)
+            if value and value.strip()
+        ),
+        None,
+    )
+    if resolved_path is None:
+        return None
+    if not resolved_path.exists():
+        utils.fatal(f"{description} not found: {resolved_path}")
+    if not resolved_path.is_file():
+        utils.fatal(f"{description} is not a file: {resolved_path}")
+    return resolved_path
+
+
 def resolve_container_dockerfile_hook_path(
     cli_hook_path: str | None, env_hook_path: str | None
 ) -> Path | None:
@@ -342,17 +361,13 @@ def resolve_container_dockerfile_hook_path(
     Returns:
         The validated hook path, or `None` when unset.
     """
-    raw_value = (
-        cli_hook_path if cli_hook_path and cli_hook_path.strip() else env_hook_path
+    hook_path = _resolve_optional_file_path(
+        cli_hook_path,
+        env_hook_path,
+        "Dockerfile hook script",
     )
-    if raw_value is None or not raw_value.strip():
+    if hook_path is None:
         return None
-
-    hook_path = Path(raw_value.strip())
-    if not hook_path.exists():
-        utils.fatal(f"Dockerfile hook script not found: {hook_path}")
-    if not hook_path.is_file():
-        utils.fatal(f"Dockerfile hook path is not a file: {hook_path}")
     if not os.access(hook_path, os.X_OK):
         utils.fatal(f"Dockerfile hook script must be executable: {hook_path}")
 
@@ -594,6 +609,28 @@ def get_container_deps_move_script() -> str | None:
     return inline_script if inline_script else None
 
 
+def resolve_container_dockerfile_path(
+    dockerfile_path: str | None,
+    environment_dockerfile_path: str | None,
+) -> Path | None:
+    """Resolve and validate a project-owned application Dockerfile.
+
+    Args:
+        dockerfile_path: Dockerfile path supplied directly to a task.
+        environment_dockerfile_path: Dockerfile path supplied through the
+            environment.
+
+    Returns:
+        The configured Dockerfile path, or `None` when the bundled template
+        should be used.
+    """
+    return _resolve_optional_file_path(
+        dockerfile_path,
+        environment_dockerfile_path,
+        "Container Dockerfile",
+    )
+
+
 def get_prune_keep() -> int:
     """Return the integer value of CONTAINER_PRUNE_KEEP.
 

common_python_tasks/tasks.py

@@ -70,6 +70,28 @@ class _ContainerBuild(NamedTuple):
     commit_tag: str
 
 
+def _prune_container_images(version_tag: str, commit_tag: str) -> None:
+    from .docker import prune_images_keep
+    from .env import get_prune_keep
+    from .utils import get_full_image_name, get_package_name
+
+    keep = get_prune_keep()
+    if keep < 0:
+        return
+
+    LOGGER.debug(
+        "Pruning old images; keeping %d and protecting tags: %s",
+        keep,
+        [version_tag, commit_tag],
+    )
+    prune_images_keep(
+        get_full_image_name(),
+        get_package_name(),
+        keep,
+        protect_tags=[version_tag, commit_tag],
+    )
+
+
 def _make_var_positional_task_args_optional(
     func: callable, resolved_task_name: str
 ) -> None:
@@ -367,11 +389,19 @@ def clean(dist_only: bool = False) -> None:
         return
     else:
         to_clean = [
-            *[Path(p) for p in [".pytest_cache", "dist", ".mypy_cache"]],
+            *[
+                Path(p)
+                for p in [
+                    ".pytest_cache",
+                    "dist",
+                    ".mypy_cache",
+                    ".coverage",
+                    "coverage.xml",
+                    ".ruff_cache",
+                ]
+            ],
             *Path(".").rglob("__pycache__"),
             *Path(".").rglob("*.pyc"),
-            Path(".coverage"),
-            Path("coverage.xml"),
         ]
 
     for item in to_clean:
@@ -406,6 +436,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,
@@ -413,11 +495,12 @@ def build_image(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     dockerfile_hook_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
 ) -> _ContainerBuild:
-    """Build the container image for this project using the Dockerfile template.
+    """Build the container image using a project-owned or bundled Dockerfile.
 
     Args:
         *docker_build_args: Additional arguments passed directly to `docker build`.
@@ -427,8 +510,10 @@ def build_image(
         no_cache: Do not use cache when building the image.
         plain: Do not pretty-print output.
         single_arch: Build images for a single architecture.
+        dockerfile_path: Optional project-owned Dockerfile. Overrides
+            CONTAINER_DOCKERFILE_PATH if provided.
         dockerfile_hook_path: Optional executable script path that can mutate
-            the generated Dockerfile before build. Overrides
+            the selected Dockerfile before build. Overrides
             CONTAINER_DOCKERFILE_HOOK_PATH if provided.
         container_env: Builder and runtime environment declarations as repeated
             KEY=VALUE values.
@@ -442,14 +527,10 @@ def build_image(
         The generated Dockerfile text and image tags.
     """
     from .docker import build_image as _build_image
-    from .docker import (
-        prune_images_keep,
-    )
     from .env import (
         collect_uv_index_credentials,
         get_cache_id_suffix,
         get_container_deps_move_script,
-        get_prune_keep,
         get_python_variant,
         inject_auto_build_args_from_env,
         load_container_env_tokens,
@@ -459,6 +540,7 @@ def build_image(
         render_container_deps_move_script,
         resolve_container_docker_build_args,
         resolve_container_dockerfile_hook_path,
+        resolve_container_dockerfile_path,
         resolve_extension_content,
         uv_index_secret_build_args,
         uv_index_secret_mounts,
@@ -469,14 +551,17 @@ def build_image(
     )
     from .utils import (
         fatal,
-        get_full_image_name,
-        get_package_name,
         load_data_file,
         render_template_text,
     )
 
+    resolved_dockerfile_path = resolve_container_dockerfile_path(
+        dockerfile_path,
+        os.getenv("CONTAINER_DOCKERFILE_PATH"),
+    )
+
     # Determine extensions up-front so we can log a single, accurate message
-    extensions = parse_container_extensions()
+    extensions = [] if resolved_dockerfile_path else parse_container_extensions()
     extension_ids = [desc.get("id") for desc in extensions if desc.get("id")]
     if extension_ids:
         LOGGER.info("Building image (with extensions: %s)", ", ".join(extension_ids))
@@ -504,6 +589,29 @@ def build_image(
         dockerfile_hook_path,
         os.getenv("CONTAINER_DOCKERFILE_HOOK_PATH"),
     )
+    top_level_build_args = inject_auto_build_args_from_env(
+        {"PYTHON_VARIANT": get_python_variant()}
+    )
+
+    if resolved_dockerfile_path:
+        version_tag, commit_tag = _build_image(
+            dockerfile_path=resolved_dockerfile_path,
+            context_path=Path("."),
+            debug=debug,
+            no_cache=no_cache,
+            plain=plain,
+            single_arch=single_arch,
+            omit_target=not debug,
+            extra_build_args=top_level_build_args or None,
+            docker_build_args=resolved_docker_build_args,
+            dockerfile_hook_path=resolved_dockerfile_hook_path,
+        )
+        _prune_container_images(version_tag, commit_tag)
+        return _ContainerBuild(
+            dockerfile_text=resolved_dockerfile_path.read_text(encoding="utf-8"),
+            version_tag=version_tag,
+            commit_tag=commit_tag,
+        )
 
     has_debug_deps = has_debug_dependency_group()
     if debug and not has_debug_deps:
@@ -527,9 +635,6 @@ def build_image(
             "Injecting builder and runtime env vars: %s",
             ", ".join(container_env_vars),
         )
-    top_level_build_args = inject_auto_build_args_from_env(
-        {"PYTHON_VARIANT": get_python_variant()}
-    )
     external_deps_image = _get_container_build_setting("CONTAINER_DEPS_IMAGE")
     if external_deps_image:
         top_level_build_args["CONTAINER_DEPS_IMAGE"] = external_deps_image
@@ -639,16 +744,7 @@ def build_image(
         dockerfile_hook_path=resolved_dockerfile_hook_path,
     )
 
-    keep = get_prune_keep()
-    if keep >= 0:
-        # Protect the tags created by this build
-        protect = [t for t in (version_tag, commit_tag) if t is not None]
-        LOGGER.debug(
-            "Pruning old images; keeping %d and protecting tags: %s", keep, protect
-        )
-        prune_images_keep(
-            get_full_image_name(), get_package_name(), keep, protect_tags=protect
-        )
+    _prune_container_images(version_tag, commit_tag)
 
     return _ContainerBuild(
         dockerfile_text=dockerfile_text,
@@ -1268,6 +1364,7 @@ def _run_release_flow(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
     assets: list[str] | None = None,
@@ -1374,6 +1471,7 @@ def _run_release_flow(
             no_cache=no_cache,
             plain=plain,
             single_arch=single_arch,
+            dockerfile_path=dockerfile_path,
             container_env=container_env,
             container_envfile=container_envfile,
         )
@@ -1392,6 +1490,7 @@ def release(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
     assets: list[str] | None = None,
@@ -1410,6 +1509,8 @@ def release(
         no_cache: Do not use cache when building container images.
         plain: Do not pretty-print container build output.
         single_arch: Build container image for a single architecture.
+        dockerfile_path: Optional project-owned Dockerfile used for the image
+            build. Overrides CONTAINER_DOCKERFILE_PATH if provided.
         container_env: Inline container environment variables as repeated
             KEY=VALUE values.
         container_envfile: Repeated list of container environment files.
@@ -1428,6 +1529,7 @@ def release(
         no_cache=no_cache,
         plain=plain,
         single_arch=single_arch,
+        dockerfile_path=dockerfile_path,
         container_env=container_env,
         container_envfile=container_envfile,
         assets=assets,
@@ -1480,6 +1582,7 @@ def build(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
 ) -> None:
@@ -1492,6 +1595,8 @@ def build(
         no_cache: Pass `--no-cache` to the Docker build command.
         plain: Pass `--progress plain` to the Docker build command.
         single_arch: Build the container for the current host architecture only.
+        dockerfile_path: Optional project-owned Dockerfile used for the image
+            build. Overrides CONTAINER_DOCKERFILE_PATH if provided.
         container_env: Inline container environment variables as repeated
             `KEY=VALUE` values.
         container_envfile: Repeated list of container environment files.
@@ -1506,6 +1611,7 @@ def build(
             no_cache=no_cache,
             plain=plain,
             single_arch=single_arch,
+            dockerfile_path=dockerfile_path,
             container_env=container_env,
             container_envfile=container_envfile,
         )
@@ -1520,6 +1626,7 @@ def build_with_containers(
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
+    dockerfile_path: str | None = None,
     container_env: list[str] | None = None,
     container_envfile: list[str] | None = None,
 ) -> None:
@@ -1530,6 +1637,8 @@ def build_with_containers(
         no_cache: Do not use cache when building the image.
         plain: Do not pretty-print output.
         single_arch: Build images for a single architecture.
+        dockerfile_path: Optional project-owned Dockerfile used for the image
+            build. Overrides CONTAINER_DOCKERFILE_PATH if provided.
         container_env: Inline container environment variables as repeated KEY=VALUE
             values.
         container_envfile: Repeated list of container environment files.
@@ -1541,6 +1650,7 @@ def build_with_containers(
         no_cache=no_cache,
         plain=plain,
         single_arch=single_arch,
+        dockerfile_path=dockerfile_path,
         container_env=container_env,
         container_envfile=container_envfile,
     )

common_python_tasks-0.11.1.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: common-python-tasks
+Version: 0.11.1
+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.1
+```
+
+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.3.dist-info → common_python_tasks-0.11.1.dist-info}/RECORD

@@ -2,11 +2,11 @@ common_python_tasks/__init__.py,sha256=tqRLgOwmMQHDb1A84XbML9sWfzMymkSPhJjoF6aCH
 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=NGgMei3oCYS0RbNaQXE-2veXFylO3XtZ7lU-PTtocik,21338
-common_python_tasks/env.py,sha256=1YLSxsUP9lPn51_zraM3nAiN1J7aKdUHzjzDzxXLo34,19696
+common_python_tasks/env.py,sha256=KxXyvQcSe_zMy4drTWPX3-R_q7u4jlwVNMDkRaTta-M,20666
 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=PQ_GQicTrSQgVDB9cJ9E6pU0UhLPom2xou1sGFscr3E,17377
-common_python_tasks/tasks.py,sha256=h-bPYwTZ3uct4dR8a-NUYKHhSB4EZ-J9iJyhaB3yJc4,60135
+common_python_tasks/tasks.py,sha256=U6CGlLVW_E-9Hofja21bUwiiISU05GdJbTTzI7Vwv2I,63796
 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
@@ -21,7 +21,7 @@ common_python_tasks/data/generic/Dockerfile.j2,sha256=hgLrIRU5xvS2xqw9Xm4kfkcBGH
 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.3.dist-info/METADATA,sha256=p9oMXue96WswNU4KsUoG8yBP8GZBsyQqqlFfpkMojHk,22464
-common_python_tasks-0.10.3.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-common_python_tasks-0.10.3.dist-info/licenses/LICENSE,sha256=RsSweM-DyzxFPx38fQOJqHrKyeT9Fiz8rO7yox-fOsw,1070
-common_python_tasks-0.10.3.dist-info/RECORD,,
+common_python_tasks-0.11.1.dist-info/METADATA,sha256=v1Gf_iMcyv-ZWpREpc9ji35TtQ9T8oyEmdKPga5yyak,3307
+common_python_tasks-0.11.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+common_python_tasks-0.11.1.dist-info/licenses/LICENSE,sha256=RsSweM-DyzxFPx38fQOJqHrKyeT9Fiz8rO7yox-fOsw,1070
+common_python_tasks-0.11.1.dist-info/RECORD,,

common_python_tasks-0.10.3.dist-info/METADATA

@@ -1,442 +0,0 @@
-Metadata-Version: 2.5
-Name: common-python-tasks
-Version: 0.10.3
-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.3
-```
-
-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.3/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.3 python3 /tmp/add_common_python_tasks.py
-```
-
-To install another release, replace both occurrences of `0.10.3` 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.3"
-
-[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 both the builder and runtime stages. These variables are available to package build commands and runtime-stage build commands, and persist in the final and debug images for running containers. The `container_env` and `container_envfile` task arguments use the same behavior. Escape literal colons as `\:` or quote the complete value. Use `run-container --env` or `--envfile` to override values when starting a container.
-- `.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`: Published host port for PostgreSQL, defaulting to `5432`. The API and migrator connect to the database container on port `5432` regardless of this setting.
-- `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.