common-python-tasks 0.12.0__tar.gz → 0.13.0__tar.gz

{common_python_tasks-0.12.0 → common_python_tasks-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: common-python-tasks
-Version: 0.12.0
+Version: 0.13.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
@@ -35,14 +35,14 @@ Description-Content-Type: text/markdown
 
 `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.
+Read the [complete documentation](https://common-python-tasks.ci-sourcerer.com/) 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.12.0
+uv add --dev common-python-tasks==0.13.0
 ```
 
 Expose the default task set in `pyproject.toml`.
@@ -83,12 +83,12 @@ 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.
+The [documentation workflow guide](https://common-python-tasks.ci-sourcerer.com/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/)
+- [Getting started](https://common-python-tasks.ci-sourcerer.com/getting-started/)
+- [Task reference](https://common-python-tasks.ci-sourcerer.com/tasks/)
+- [Configuration reference](https://common-python-tasks.ci-sourcerer.com/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.12.0 → common_python_tasks-0.13.0}/README.md

@@ -2,14 +2,14 @@
 
 `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.
+Read the [complete documentation](https://common-python-tasks.ci-sourcerer.com/) 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.12.0
+uv add --dev common-python-tasks==0.13.0
 ```
 
 Expose the default task set in `pyproject.toml`.
@@ -50,12 +50,12 @@ 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.
+The [documentation workflow guide](https://common-python-tasks.ci-sourcerer.com/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/)
+- [Getting started](https://common-python-tasks.ci-sourcerer.com/getting-started/)
+- [Task reference](https://common-python-tasks.ci-sourcerer.com/tasks/)
+- [Configuration reference](https://common-python-tasks.ci-sourcerer.com/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.12.0 → common_python_tasks-0.13.0}/docs/configuration.md

@@ -43,7 +43,7 @@ Container variables are read by the host-side tasks unless their description exp
 | `WORKDIR_PATH` | Home and working directory for the non-root `py` user; defaults to `/workspace` |
 | `CONTAINER_APT_PACKAGES` | Space-delimited APT packages installed in the runtime stage |
 | `CONTAINER_CUSTOM_ENTRYPOINT` | `[project.scripts]` key selected as the image entrypoint command |
-| `CONTAINER_DOCKER_BUILD_ARGS` | Shell-tokenized arguments passed directly to `docker build`; task arguments after `--` take precedence |
+| `CONTAINER_DOCKER_BUILD_OPTIONS` | Shell-tokenized options passed directly to `docker build`; task options after `--` take precedence |
 | `CONTAINER_DOCKERFILE_PATH` | Project-owned application Dockerfile used by `build-image`, `build`, and `release` instead of the bundled template |
 | `CONTAINER_DOCKERFILE_HOOK_PATH` | Executable host script that modifies the selected Dockerfile before the build |
 | `CONTAINER_PRUNE_KEEP` | Prior images kept after a build; `-1` disables pruning, `0` keeps only the latest, and `N` keeps the latest plus `N` prior images |

common_python_tasks-0.13.0/docs/documentation-workflows.md

@@ -0,0 +1,183 @@
+# Documentation workflows
+
+Projects can use the packaged documentation tasks locally and the repository's reusable GitHub workflow in CI. The workflow builds the caller's repository, not `common-python-tasks`.
+
+## Configure a project
+
+Add a `zensical.toml` file and select the `docs` task group.
+
+```toml
+[tool.poe]
+include_script = "common_python_tasks:tasks(include_tags=['common', 'docs'])"
+```
+
+Build or serve the site locally.
+
+```shell
+poe docs-build
+poe docs-serve
+```
+
+## Build pull-request artifacts
+
+Keep event triggers and path filters in the consuming repository, then call the reusable workflow from a job.
+
+```yaml
+name: docs-preview
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'zensical.toml'
+      - 'pyproject.toml'
+      - 'uv.lock'
+
+jobs:
+  docs:
+    uses: ci-sourcerer/common-python-tasks/.github/workflows/docs.yml@v0.11.0
+    with:
+      python_version: '3.14'
+      dependency_group: dev
+    permissions:
+      contents: read
+```
+
+The workflow uploads the rendered site as a GitHub Actions artifact by default.
+
+## Run a client-owned generated-document check
+
+Some projects generate additional documentation from application code. Keep that generator in the consuming project and pass its Poe check task to the workflow.
+
+```yaml
+with:
+  python_version: '3.14'
+  dependency_group: dev
+  generated_docs_check_task: docs-cli-reference-check
+```
+
+Only task names containing letters, digits, underscores, and hyphens are accepted.
+
+## Enable Cloudflare Pages previews
+
+Cloudflare publication is optional. The workflow ensures that one Direct Upload Pages project exists for the consuming repository, then deploys previews to it with narrowly scoped credentials.
+
+```yaml
+jobs:
+  docs:
+    uses: ci-sourcerer/common-python-tasks/.github/workflows/docs.yml@v0.11.0
+    with:
+      python_version: '3.14'
+      dependency_group: dev
+      publish_cloudflare: true
+      cloudflare_project_name: stacksmith-docs
+      cloudflare_preview_domain: preview.example.com
+      cloudflare_preview_zone: example.com
+    permissions:
+      contents: read
+      deployments: write
+    secrets:
+      cloudflare_account_id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+      cloudflare_api_token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+```
+
+The project is created on the first trusted pull request, using `main` as its production branch by default. Set `cloudflare_production_branch` if the repository uses a different default branch. Set `cloudflare_preview_domain` to publish previews at `pr-42.preview.example.com`; leave it empty to use `pr-42.stacksmith-docs.pages.dev`. Set `cloudflare_preview_zone` when the preview domain is a subdomain of the DNS zone. The API token needs Pages Write, Zone Read, and Zone DNS Edit permissions when custom preview domains are enabled. Fork pull requests receive the build artifact but are not published because repository secrets are unavailable. A separate `pull_request`-closed workflow can remove the custom hostname, its matching DNS record, and older deployments for that preview branch while preserving the shared Pages project. Cloudflare retains the latest branch deployment.
+
+## Deploy documentation to GitHub Pages
+
+Enable GitHub Actions as the repository's Pages source. GitHub Pages deployments are versioned by default and publish the current checkout as `dev` unless the caller selects another version. The caller must grant `contents: write` so the workflow can update the versions branch.
+
+```yaml
+jobs:
+  docs:
+    uses: ci-sourcerer/common-python-tasks/.github/workflows/docs.yml@v0.11.0
+    with:
+      python_version: '3.14'
+      dependency_group: dev
+      deploy_github_pages: true
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+```
+
+This initial deployment creates `dev` and uses it as the site root when the versions branch does not already contain a root redirect. Pin the workflow to the release that matches the installed package. Pin an exact commit SHA when an immutable workflow reference is required.
+
+## Configure versioned documentation
+
+Versioned deployment uses the Zensical-compatible `mike` fork. The workflow keeps generated versions on a Git branch and publishes the assembled branch through GitHub Actions, so the repository's Pages source remains GitHub Actions. The fork is a transitional dependency until Zensical provides native versioning support.
+
+Enable the version selector in `zensical.toml`.
+
+```toml
+[project.extra.version]
+provider = "mike"
+default = ["latest", "dev"]
+
+[project.plugins.mike]
+alias_type = "redirect"
+```
+
+Pass a version identifier, title, aliases, and default version when publishing a release.
+
+```yaml
+jobs:
+  docs:
+    uses: ci-sourcerer/common-python-tasks/.github/workflows/docs.yml@v0.12.1
+    with:
+      python_version: '3.14'
+      dependency_group: dev
+      deploy_github_pages: true
+      docs_version: '2.4'
+      docs_version_title: '2.4.3'
+      docs_aliases: '["latest"]'
+      docs_default_version: latest
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+```
+
+`docs_aliases` must be a JSON array. Versions and aliases accept letters, digits, periods, underscores, and hyphens. The default versions branch is `gh-pages`; set `docs_versions_branch` to use another valid Git branch. The reusable workflow serializes updates to each repository and versions branch. Alias redirects are updated atomically with the version metadata, and versions not named by the current deployment remain unchanged.
+
+The workflow still performs the strict `poe docs-build` check and uploads the current checkout as the normal Actions artifact. It then builds through `mike`, updates the versions branch, and gives the complete assembled site to GitHub Pages.
+
+## Preview multiple versions locally
+
+`poe docs-serve` builds and watches only the current checkout. It is the quickest way to review content, but its version selector has no assembled `versions.json` to load.
+
+Install the same pinned Zensical-compatible `mike` fork used by the workflow, assemble two versions on a disposable local Git branch, and serve that branch.
+
+```shell
+uv pip install 'mike @ git+https://github.com/squidfunk/mike.git@2d4ad799442f4592db8ad53b179bfb33db8c69ac'
+uv run --no-sync mike deploy --branch local-docs --alias-type redirect --update-aliases --title Development dev
+uv run --no-sync mike deploy --branch local-docs --alias-type redirect --update-aliases --title 0.12.1 0.12 latest
+uv run --no-sync mike set-default --branch local-docs latest
+uv run --no-sync mike serve --branch local-docs
+```
+
+Open `http://localhost:8000/`. The root redirects to `latest`, and the selector switches between `0.12` and `dev`. These commands create only local commits on `local-docs`; they do not push anything. Stop the server before removing the disposable branch with `git branch -D local-docs`.
+
+## Publish development and release versions
+
+Use one serialized production workflow for default-branch and tag deployment. Publish the default branch as `dev`, and publish stable tags to a major/minor documentation series. For example, `v2.4.3` updates version `2.4`, uses `2.4.3` as its display title, moves the `latest` alias, and makes `latest` the site root. Later default-branch deployments update `dev` without moving the root away from `latest`.
+
+The repository's own deployment workflow demonstrates this policy. Pull requests continue to use the unversioned artifact and Cloudflare preview flow, so a pull request previews the next `dev` site without modifying the versions branch.
+
+## Backfill an existing release
+
+A repository can expose manual workflow inputs that pass an older tag through `checkout_ref` while deploying it under an explicit documentation version. For this repository, run `docs-deploy` manually with values such as the following.
+
+| Input | Value |
+| - | - |
+| `source_ref` | A tag that already enables the `mike` version selector, or empty to build the selected workflow ref |
+| `docs_version` | `0.12` |
+| `docs_version_title` | `0.12.1` |
+| `update_latest` | `true` |
+| `default_version` | `latest` |
+
+Backfill supported series from oldest to newest so the selector order and `latest` alias finish in the desired state. Historical refs created before versioning was configured cannot produce a working selector without a compatible configuration change; build those docs from a suitable maintenance branch or the current branch instead. A normal default-branch deployment uses `dev` as the initial site root only when the versions branch has no root redirect, which keeps the documentation reachable before the first release or backfill.
+
+## Maintain published versions
+
+The versions branch contains `versions.json`, the generated version directories, aliases, and the root redirect. Inspect a local checkout with the same pinned Zensical-compatible fork before deleting or retitling published versions. Since the fork is installed directly from GitHub, changes to its pinned commit require a versioned workflow update and a representative multi-version build test.

{common_python_tasks-0.12.0 → common_python_tasks-0.13.0}/docs/tasks/container-images.md

@@ -295,7 +295,7 @@ poe build --dockerfile-path docker/Dockerfile.ci
 poe release --dockerfile-path docker/Dockerfile.release
 ```
 
-The project root remains the Docker build context. Standard image naming, version and commit tags, metadata build arguments, `CONTAINER_DOCKER_BUILD_ARGS`, Dockerfile hooks, image pruning, and release-time image pushing continue to work. A normal custom build does not select a target stage, so the Dockerfile does not need the bundled `runtime` stage. A custom debug build selects a stage named `debug`.
+The project root remains the Docker build context. Standard image naming, version and commit tags, metadata build arguments, `CONTAINER_DOCKER_BUILD_OPTIONS`, Dockerfile hooks, image pruning, and release-time image pushing continue to work. A normal custom build does not select a target stage, so the Dockerfile does not need the bundled `runtime` stage. A custom debug build selects a stage named `debug`.
 
 Settings that render content into the bundled template do not alter a project-owned Dockerfile. This includes `CONTAINER_APT_PACKAGES`, `CONTAINER_CUSTOM_ENTRYPOINT`, `CONTAINER_ENV`, extensions, and dependency-image mappings. Declare equivalent instructions in the project-owned Dockerfile when they are needed. BuildKit secrets derived from `UV_INDEX_*` credentials remain available as Docker build secrets, but the custom Dockerfile must mount them explicitly.
 
@@ -344,6 +344,8 @@ poe run-container --privileged
 
 The image starts as root through Tini and the DinD supervisor. The supervisor prepares nested cgroups, starts a dedicated Docker daemon, and waits for `docker info` to succeed before launching the existing `/pkg/entrypoint.sh` as `py`. Application arguments and exit status are preserved. Signals reach the application, and shutdown stops the application before stopping Docker. Startup failure or loss of the daemon terminates the container with a nonzero status. `DIND_STARTUP_TIMEOUT` controls the readiness deadline in seconds (default `60`, accepted range `1`–`9999`). Each process group gets up to five seconds to stop before being killed; allow more than ten seconds for the outer container's stop timeout.
 
+Docker daemon output is written to `/var/log/docker.log` by default so it does not mix with application logs. Set `DIND_DOCKER_LOG_PATH` to choose another file path; inspect the file with `docker exec` or mount a log directory if the daemon logs need to be collected.
+
 Docker listens only on `unix:///var/run/docker.sock`. The image sets `DOCKER_HOST` accordingly, and startup clears Docker context and TLS environment overrides so the application uses its own daemon. Do not mount the host Docker socket. The `py` user belongs to the Docker group and can control the nested daemon; this is a privileged container, not a sandbox for untrusted workloads.
 
 The image declares volumes for `/var/lib/docker` and `/var/lib/containerd`. Docker creates anonymous volumes automatically. Use dedicated named volumes when state should survive container replacement, and never share them between concurrently running daemons. For example, when launching the built image directly, replace `your-image:tag` with its tag.
@@ -391,7 +393,16 @@ Arguments following Poe's `--` separator are passed directly to `docker build` w
 poe build-image --single-arch -- --secret id=pip_conf,env=PIP_CONF
 ```
 
-Set `CONTAINER_DOCKER_BUILD_ARGS` to persist the same options using shell quoting rules. Arguments supplied after `--` replace this setting for that invocation. Managed arguments are emitted before these native Docker arguments, so an explicit option such as `--build-arg WORKDIR_PATH=/app` can override its managed value.
+Set `CONTAINER_DOCKER_BUILD_OPTIONS` to persist the same options using shell quoting rules. Options supplied after `--` replace this setting for that invocation. Managed build arguments are emitted before these native Docker options, so an explicit option such as `--build-arg WORKDIR_PATH=/app` can override its managed value.
+
+For project-specific defaults, declare the options in Poe's environment. A name-only `--build-arg` reads its value from the current environment, while `env=` explicitly selects the host variable used for a BuildKit secret.
+
+```toml
+[tool.poe.env]
+CONTAINER_DOCKER_BUILD_OPTIONS = "--secret id=MY_TOKEN,env=MY_TOKEN --build-arg MY_SETTING"
+```
+
+The Dockerfile must consume `MY_TOKEN` with a secret mount. Do not pass sensitive values through `--build-arg`, because build arguments are not designed to protect secrets.
 
 See [Container settings](../configuration.md#container-settings) for the complete settings reference.
 

{common_python_tasks-0.12.0 → common_python_tasks-0.13.0}/docs/tasks/reference/build-deps-image.md

@@ -9,14 +9,14 @@ Build only the container dependency collector image for this project.
 ## Usage
 
 ```shell
-poe build-deps-image [DOCKER_BUILD_ARGS...] [--no-cache] [--plain] [--single-arch]
+poe build-deps-image [DOCKER_BUILD_OPTIONS...] [--no-cache] [--plain] [--single-arch]
 ```
 
 ## Arguments
 
 | Argument | Type | Description | Default |
 | - | - | - | - |
-| `docker_build_args...` | `string, repeatable` | Additional arguments passed directly to `docker build`. Provide them after the task's `--` separator. Overrides `CONTAINER_DOCKER_BUILD_ARGS` when provided. | — |
+| `docker_build_options...` | `string, repeatable` | Additional options passed directly to `docker build`. Provide them after the task's `--` separator. Overrides `CONTAINER_DOCKER_BUILD_OPTIONS` when provided. | — |
 | `--no-cache` | `boolean` | Do not use cache when building the deps image. | `false` |
 | `--plain` | `boolean` | Do not pretty-print output. | `false` |
 | `--single-arch` | `boolean` | Build images for a single architecture. | `false` |

{common_python_tasks-0.12.0 → common_python_tasks-0.13.0}/docs/tasks/reference/build-image.md

@@ -9,14 +9,14 @@ Build the container image using a project-owned or bundled Dockerfile.
 ## Usage
 
 ```shell
-poe build-image [DOCKER_BUILD_ARGS...] [--debug] [--no-cache] [--plain] [--single-arch] [--dockerfile-path DOCKERFILE_PATH] [--dockerfile-hook-path DOCKERFILE_HOOK_PATH] [--container-env CONTAINER_ENV...] [--container-envfile CONTAINER_ENVFILE...]
+poe build-image [DOCKER_BUILD_OPTIONS...] [--debug] [--no-cache] [--plain] [--single-arch] [--dockerfile-path DOCKERFILE_PATH] [--dockerfile-hook-path DOCKERFILE_HOOK_PATH] [--container-env CONTAINER_ENV...] [--container-envfile CONTAINER_ENVFILE...]
 ```
 
 ## Arguments
 
 | Argument | Type | Description | Default |
 | - | - | - | - |
-| `docker_build_args...` | `string, repeatable` | Additional arguments passed directly to `docker build`. Provide them after the task's `--` separator. Overrides `CONTAINER_DOCKER_BUILD_ARGS` when provided. | — |
+| `docker_build_options...` | `string, repeatable` | Additional options passed directly to `docker build`. Provide them after the task's `--` separator. Overrides `CONTAINER_DOCKER_BUILD_OPTIONS` when provided. | — |
 | `--debug` | `boolean` | Build the debug image. | `false` |
 | `--no-cache` | `boolean` | Do not use cache when building the image. | `false` |
 | `--plain` | `boolean` | Do not pretty-print output. | `false` |

{common_python_tasks-0.12.0 → common_python_tasks-0.13.0}/src/common_python_tasks/data/dockerfile_extensions/docker-in-docker/supervisor.sh

@@ -87,6 +87,7 @@ _main() {
         return 1
     fi
     export DIND_STARTUP_TIMEOUT=${DIND_STARTUP_TIMEOUT:-60}
+    export DIND_DOCKER_LOG_PATH=${DIND_DOCKER_LOG_PATH:-/var/log/docker.log}
     export DOCKER_HOST=unix:///var/run/docker.sock
     export container=docker
     unset DOCKER_CONTEXT DOCKER_TLS_VERIFY DOCKER_CERT_PATH
@@ -96,8 +97,8 @@ _main() {
     trap _shutdown EXIT
     trap 'exit 143' TERM
     trap 'exit 130' INT
-    # Keep daemon logs on stderr and expose only the local Unix socket.
-    setsid dockerd --host "$DOCKER_HOST" --group docker >&2 &
+    setsid dockerd --host "$DOCKER_HOST" --group docker \
+        >>"$DIND_DOCKER_LOG_PATH" 2>&1 &
     daemon_pid=$!
     _wait_for_docker
     setsid setpriv --reuid py --regid py --init-groups \

{common_python_tasks-0.12.0 → common_python_tasks-0.13.0}/src/common_python_tasks/docker.py

@@ -100,7 +100,7 @@ def _build_docker_build_command(
     plain: bool,
     target: BuildStage | None = None,
     tags: Sequence[str] | None = None,
-    docker_build_args: Sequence[str] | None = None,
+    docker_build_options: Sequence[str] | None = None,
 ) -> list[str]:
     build_cmd = [
         "docker",
@@ -123,8 +123,8 @@ def _build_docker_build_command(
             build_cmd += ["-t", tag]
     if plain:
         build_cmd += ["--progress", "plain"]
-    if docker_build_args:
-        build_cmd += [str(arg) for arg in docker_build_args]
+    if docker_build_options:
+        build_cmd += [str(option) for option in docker_build_options]
     build_cmd.append(str(context_path))
 
     return build_cmd
@@ -180,7 +180,7 @@ def render_build_image(
     omit_target: bool = False,
     image_name: str | None = None,
     extra_build_args: dict[str, str] | None = None,
-    docker_build_args: Sequence[str] | None = None,
+    docker_build_options: Sequence[str] | None = None,
     dockerfile_hook_path: Path | None = None,
     keep_generated_files: bool = True,
 ) -> RenderedBuildPlan:
@@ -197,7 +197,7 @@ def render_build_image(
         omit_target: Whether to omit the target stage from the command.
         image_name: Optional image name override.
         extra_build_args: Extra build-time arguments.
-        docker_build_args: Additional arguments passed directly to `docker build`.
+        docker_build_options: Additional options passed directly to `docker build`.
         dockerfile_hook_path: Optional executable script path that can mutate
             the generated Dockerfile in-place before build.
         keep_generated_files: Whether to leave the generated Dockerfile in place.
@@ -338,7 +338,7 @@ def render_build_image(
             plain,
             target=None if omit_target else target,
             tags=all_tags,
-            docker_build_args=docker_build_args,
+            docker_build_options=docker_build_options,
         )
         command_display = " ".join(quote(str(arg)) for arg in build_cmd)
         return RenderedBuildPlan(
@@ -473,7 +473,7 @@ def build_deps_image(
     plain: bool = False,
     single_arch: bool = False,
     extra_build_args: dict[str, str] | None = None,
-    docker_build_args: Sequence[str] | None = None,
+    docker_build_options: Sequence[str] | None = None,
     cache_id_suffix: str = "",
 ) -> str:
     """Build the dependency collector image and return its full tag.
@@ -486,7 +486,7 @@ def build_deps_image(
         plain: If `True`, use plain output mode for the Docker build.
         single_arch: If `True`, build the image for the current host architecture only.
         extra_build_args: Additional build arguments for the Docker build as a dictionary of `KEY: VALUE` pairs.
-        docker_build_args: Additional arguments passed directly to `docker build`.
+        docker_build_options: Additional options passed directly to `docker build`.
         cache_id_suffix: A suffix to append to the cache ID.
 
     Returns:
@@ -574,7 +574,7 @@ def build_deps_image(
         no_cache,
         plain,
         tags=[full_tag],
-        docker_build_args=docker_build_args,
+        docker_build_options=docker_build_options,
     )
 
     LOGGER.info("Building deps image: %s", full_tag)
@@ -597,7 +597,7 @@ def build_image(
     omit_target: bool = False,
     image_name: str | None = None,
     extra_build_args: dict[str, str] | None = None,
-    docker_build_args: Sequence[str] | None = None,
+    docker_build_options: Sequence[str] | None = None,
     dockerfile_hook_path: Path | None = None,
 ) -> tuple[str, str]:
     """Build the primary image and return its version and commit tags.
@@ -613,7 +613,7 @@ def build_image(
         omit_target: If `True`, omit the target stage.
         image_name: Name of the image to build.
         extra_build_args: Additional build arguments for the Docker build as a dictionary of `KEY: VALUE` pairs.
-        docker_build_args: Additional arguments passed directly to `docker build`.
+        docker_build_options: Additional options passed directly to `docker build`.
         dockerfile_hook_path: Optional executable script path that can mutate
             the generated Dockerfile in-place before build.
 
@@ -636,7 +636,7 @@ def build_image(
         omit_target=omit_target,
         image_name=image_name,
         extra_build_args=extra_build_args,
-        docker_build_args=docker_build_args,
+        docker_build_options=docker_build_options,
         dockerfile_hook_path=dockerfile_hook_path,
         keep_generated_files=True,
     )

{common_python_tasks-0.12.0 → common_python_tasks-0.13.0}/src/common_python_tasks/env.py

@@ -81,14 +81,16 @@ def uv_index_secret_mounts(credentials: list[dict[str, str | None]]) -> list[str
     ]
 
 
-def uv_index_secret_build_args(credentials: list[dict[str, str | None]]) -> list[str]:
-    """Return `docker build --secret` arg pairs for UV index credentials.
+def uv_index_secret_build_options(
+    credentials: list[dict[str, str | None]],
+) -> list[str]:
+    """Return `docker build --secret` option 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` option-value pairs for the Docker build command.
     """
     return [
         item
@@ -131,13 +133,13 @@ def get_python_variant() -> str:
 def inject_auto_build_args_from_env(
     build_args: dict[str, str] | None,
 ) -> dict[str, str]:
-    """Inject configured environment variables into managed Docker build args.
+    """Inject configured environment variables into managed Dockerfile build arguments.
 
     Environment-driven build args are only injected if they are set, and never
     override arguments already managed by the image builder.
 
     Args:
-        build_args: Existing managed Docker build arguments.
+        build_args: Existing managed Dockerfile build arguments.
 
     Returns:
         A build-arg dictionary with auto-injected env values merged in.
@@ -337,28 +339,29 @@ def split_colon_delimited_values(value: str) -> list[str]:
     return split_delimited_values(value, separators=":", allow_whitespace=True)
 
 
-def resolve_container_docker_build_args(
-    cli_docker_build_args: tuple[str, ...], env_docker_build_args: str | None
+def resolve_container_docker_build_options(
+    cli_docker_build_options: tuple[str, ...],
+    env_docker_build_options: str | None,
 ) -> list[str]:
-    """Resolve arguments passed directly to `docker build`.
+    """Resolve options passed directly to `docker build`.
 
     Args:
-        cli_docker_build_args: Free arguments provided after the task's `--`
+        cli_docker_build_options: Free options provided after the task's `--`
             separator.
-        env_docker_build_args: Shell-tokenized arguments from the environment.
+        env_docker_build_options: Shell-tokenized options from the environment.
 
     Returns:
-        The CLI arguments when provided, otherwise the environment arguments.
+        The CLI options when provided, otherwise the environment options.
     """
-    if cli_docker_build_args:
-        return list(cli_docker_build_args)
-    if not env_docker_build_args:
+    if cli_docker_build_options:
+        return list(cli_docker_build_options)
+    if not env_docker_build_options:
         return []
 
     try:
-        return shlex.split(env_docker_build_args)
+        return shlex.split(env_docker_build_options)
     except ValueError as error:
-        utils.fatal(f"Invalid CONTAINER_DOCKER_BUILD_ARGS: {error}")
+        utils.fatal(f"Invalid CONTAINER_DOCKER_BUILD_OPTIONS: {error}")
 
 
 def _resolve_optional_file_path(

{common_python_tasks-0.12.0 → common_python_tasks-0.13.0}/src/common_python_tasks/tasks.py

@@ -490,7 +490,7 @@ def docs_serve(
 
 @tasks.script(tags=["containers", "build"])
 def build_image(
-    *docker_build_args: str,
+    *docker_build_options: str,
     debug: bool = False,
     no_cache: bool = False,
     plain: bool = False,
@@ -503,9 +503,9 @@ def build_image(
     """Build the container image using a project-owned or bundled Dockerfile.
 
     Args:
-        *docker_build_args: Additional arguments passed directly to `docker build`.
+        *docker_build_options: Additional options passed directly to `docker build`.
             Provide them after the task's `--` separator. Overrides
-            `CONTAINER_DOCKER_BUILD_ARGS` when provided.
+            `CONTAINER_DOCKER_BUILD_OPTIONS` when provided.
         debug: Build the debug image.
         no_cache: Do not use cache when building the image.
         plain: Do not pretty-print output.
@@ -538,12 +538,12 @@ def build_image(
         parse_container_deps_source,
         parse_container_extensions,
         render_container_deps_move_script,
-        resolve_container_docker_build_args,
+        resolve_container_docker_build_options,
         resolve_container_dockerfile_hook_path,
         resolve_container_dockerfile_path,
         resolve_extension_build_context,
         resolve_extension_content,
-        uv_index_secret_build_args,
+        uv_index_secret_build_options,
         uv_index_secret_mounts,
     )
     from .project import (
@@ -578,9 +578,9 @@ def build_image(
         if (context := resolve_extension_build_context(desc)) is not None
     ]
 
-    resolved_docker_build_args = resolve_container_docker_build_args(
-        docker_build_args,
-        os.getenv("CONTAINER_DOCKER_BUILD_ARGS"),
+    resolved_docker_build_options = resolve_container_docker_build_options(
+        docker_build_options,
+        os.getenv("CONTAINER_DOCKER_BUILD_OPTIONS"),
     )
     uv_credentials = collect_uv_index_credentials()
     if uv_credentials:
@@ -588,9 +588,9 @@ def build_image(
             "Passing UV index credentials for: %s",
             ", ".join(c["index_name"] for c in uv_credentials),
         )
-        resolved_docker_build_args = uv_index_secret_build_args(uv_credentials) + list(
-            resolved_docker_build_args
-        )
+        resolved_docker_build_options = uv_index_secret_build_options(
+            uv_credentials
+        ) + list(resolved_docker_build_options)
     resolved_dockerfile_hook_path = resolve_container_dockerfile_hook_path(
         dockerfile_hook_path,
         os.getenv("CONTAINER_DOCKERFILE_HOOK_PATH"),
@@ -609,7 +609,7 @@ def build_image(
             single_arch=single_arch,
             omit_target=not debug,
             extra_build_args=top_level_build_args or None,
-            docker_build_args=resolved_docker_build_args,
+            docker_build_options=resolved_docker_build_options,
             dockerfile_hook_path=resolved_dockerfile_hook_path,
         )
         _prune_container_images(version_tag, commit_tag)
@@ -713,7 +713,7 @@ def build_image(
 
     if deps_content or deps_dockerfile_path:
         deps_image_tag = build_deps_image_task(
-            *resolved_docker_build_args,
+            *resolved_docker_build_options,
             no_cache=no_cache,
             plain=plain,
             single_arch=single_arch,
@@ -746,8 +746,8 @@ def build_image(
         plain=plain,
         single_arch=single_arch,
         extra_build_args=merged_build_args or None,
-        docker_build_args=[
-            *resolved_docker_build_args,
+        docker_build_options=[
+            *resolved_docker_build_options,
             *(
                 item
                 for name, path in extension_build_contexts
@@ -768,7 +768,7 @@ def build_image(
 
 @tasks.script(task_name="build-deps-image", tags=["containers", "build"])
 def build_deps_image_task(
-    *docker_build_args: str,
+    *docker_build_options: str,
     no_cache: bool = False,
     plain: bool = False,
     single_arch: bool = False,
@@ -776,9 +776,9 @@ def build_deps_image_task(
     """Build only the container dependency collector image for this project.
 
     Args:
-        *docker_build_args: Additional arguments passed directly to `docker build`.
+        *docker_build_options: Additional options passed directly to `docker build`.
             Provide them after the task's `--` separator. Overrides
-            `CONTAINER_DOCKER_BUILD_ARGS` when provided.
+            `CONTAINER_DOCKER_BUILD_OPTIONS` when provided.
         no_cache: Do not use cache when building the deps image.
         plain: Do not pretty-print output.
         single_arch: Build images for a single architecture.
@@ -791,7 +791,7 @@ def build_deps_image_task(
         get_cache_id_suffix,
         inject_auto_build_args_from_env,
         parse_container_deps_source,
-        resolve_container_docker_build_args,
+        resolve_container_docker_build_options,
     )
     from .utils import fatal
 
@@ -801,9 +801,9 @@ def build_deps_image_task(
             "No container dependency source found. Set CONTAINER_DEPS_CONTENT or CONTAINER_DEPS_FILE."
         )
 
-    resolved_docker_build_args = resolve_container_docker_build_args(
-        docker_build_args,
-        os.getenv("CONTAINER_DOCKER_BUILD_ARGS"),
+    resolved_docker_build_options = resolve_container_docker_build_options(
+        docker_build_options,
+        os.getenv("CONTAINER_DOCKER_BUILD_OPTIONS"),
     )
     extra_build_args = inject_auto_build_args_from_env({})
     cache_id_suffix = get_cache_id_suffix(no_cache)
@@ -817,7 +817,7 @@ def build_deps_image_task(
         plain=plain,
         single_arch=single_arch,
         extra_build_args=extra_build_args or None,
-        docker_build_args=resolved_docker_build_args,
+        docker_build_options=resolved_docker_build_options,
         cache_id_suffix=cache_id_suffix,
     )
 

{common_python_tasks-0.12.0 → common_python_tasks-0.13.0}/zensical.toml

@@ -1,10 +1,17 @@
 [project]
 site_name = "Common Python Tasks"
 site_description = "Opinionated Poe the Poet tasks for Python package development"
-site_url = "https://ci-sourcerer.github.io/common-python-tasks/"
+site_url = "https://common-python-tasks.ci-sourcerer.com/"
 repo_name = "ci-sourcerer/common-python-tasks"
 repo_url = "https://github.com/ci-sourcerer/common-python-tasks"
 
+[project.extra.version]
+provider = "mike"
+default = ["latest", "dev"]
+
+[project.plugins.mike]
+alias_type = "redirect"
+
 [project.theme]
 features = [
   "navigation.sections",

common_python_tasks-0.12.0/docs/documentation-workflows.md

@@ -1,104 +0,0 @@
-# Documentation workflows
-
-Projects can use the packaged documentation tasks locally and the repository's reusable GitHub workflow in CI. The workflow builds the caller's repository, not `common-python-tasks`.
-
-## Configure a project
-
-Add a `zensical.toml` file and select the `docs` task group.
-
-```toml
-[tool.poe]
-include_script = "common_python_tasks:tasks(include_tags=['common', 'docs'])"
-```
-
-Build or serve the site locally.
-
-```shell
-poe docs-build
-poe docs-serve
-```
-
-## Build pull-request artifacts
-
-Keep event triggers and path filters in the consuming repository, then call the reusable workflow from a job.
-
-```yaml
-name: docs-preview
-
-on:
-  pull_request:
-    paths:
-      - 'docs/**'
-      - 'zensical.toml'
-      - 'pyproject.toml'
-      - 'uv.lock'
-
-jobs:
-  docs:
-    uses: ci-sourcerer/common-python-tasks/.github/workflows/docs.yml@v0.11.0
-    with:
-      python_version: '3.14'
-      dependency_group: dev
-    permissions:
-      contents: read
-```
-
-The workflow uploads the rendered site as a GitHub Actions artifact by default.
-
-## Run a client-owned generated-document check
-
-Some projects generate additional documentation from application code. Keep that generator in the consuming project and pass its Poe check task to the workflow.
-
-```yaml
-with:
-  python_version: '3.14'
-  dependency_group: dev
-  generated_docs_check_task: docs-cli-reference-check
-```
-
-Only task names containing letters, digits, underscores, and hyphens are accepted.
-
-## Enable Cloudflare Pages previews
-
-Cloudflare publication is optional. The workflow ensures that one Direct Upload Pages project exists for the consuming repository, then deploys previews to it with narrowly scoped credentials.
-
-```yaml
-jobs:
-  docs:
-    uses: ci-sourcerer/common-python-tasks/.github/workflows/docs.yml@v0.11.0
-    with:
-      python_version: '3.14'
-      dependency_group: dev
-      publish_cloudflare: true
-      cloudflare_project_name: stacksmith-docs
-      cloudflare_preview_domain: preview.example.com
-      cloudflare_preview_zone: example.com
-    permissions:
-      contents: read
-      deployments: write
-    secrets:
-      cloudflare_account_id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-      cloudflare_api_token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-```
-
-The project is created on the first trusted pull request, using `main` as its production branch by default. Set `cloudflare_production_branch` if the repository uses a different default branch. Set `cloudflare_preview_domain` to publish previews at `pr-42.preview.example.com`; leave it empty to use `pr-42.stacksmith-docs.pages.dev`. Set `cloudflare_preview_zone` when the preview domain is a subdomain of the DNS zone. The API token needs Pages Write, Zone Read, and Zone DNS Edit permissions when custom preview domains are enabled. Fork pull requests receive the build artifact but are not published because repository secrets are unavailable. A separate `pull_request`-closed workflow can remove the custom hostname, its matching DNS record, and older deployments for that preview branch while preserving the shared Pages project. Cloudflare retains the latest branch deployment.
-
-## Deploy production documentation to GitHub Pages
-
-Enable GitHub Actions as the repository's Pages source. A default-branch caller can then select production deployment.
-
-```yaml
-jobs:
-  docs:
-    uses: ci-sourcerer/common-python-tasks/.github/workflows/docs.yml@v0.11.0
-    with:
-      python_version: '3.14'
-      dependency_group: dev
-      deploy_github_pages: true
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
-```
-
-Pin the workflow to the release that matches the installed package. Pin an exact commit SHA when an immutable workflow reference is required.