common-python-tasks 0.12.1__tar.gz → 0.13.1__tar.gz

{common_python_tasks-0.12.1 → common_python_tasks-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: common-python-tasks
-Version: 0.12.1
+Version: 0.13.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
@@ -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.1
+uv add --dev common-python-tasks==0.13.1
 ```
 
 Expose the default task set in `pyproject.toml`.
@@ -74,7 +74,6 @@ include_script = "common_python_tasks:tasks(include_tags=['common', 'docs', 'con
 | `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.
 
@@ -83,12 +82,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.1 → common_python_tasks-0.13.1}/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.1
+uv add --dev common-python-tasks==0.13.1
 ```
 
 Expose the default task set in `pyproject.toml`.
@@ -41,7 +41,6 @@ include_script = "common_python_tasks:tasks(include_tags=['common', 'docs', 'con
 | `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.
 
@@ -50,12 +49,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.1 → common_python_tasks-0.13.1}/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 |
@@ -70,19 +70,6 @@ Container variables are read by the host-side tasks unless their description exp
 | `CONTAINER_DEPS_MOVE_SCRIPT` | Inline script that distributes copied dependency artifacts and takes precedence over mappings |
 | `CONTAINER_DEPS_MOVE_SCRIPT_PATH` | Host path to a dependency move script; takes precedence over the inline script and mappings |
 
-## Development-stack settings
-
-Set `COMPOSE_TYPE=fastapi` to use the bundled FastAPI stack. Add PostgreSQL with `COMPOSE_ADDONS=db`.
-
-```toml
-[tool.poe.env]
-COMPOSE_TYPE = "fastapi"
-COMPOSE_ADDONS = "db"
-API_PORT = "8080"
-DB_PORT = "5432"
-```
-
-`COMPOSE_FILE` replaces automatic compose-file selection. `COMPOSE_OVERLAY_FILES` appends project-specific overlays to the automatically selected files.
 
 ## Diagnostics
 

common_python_tasks-0.13.1/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.1 → common_python_tasks-0.13.1}/docs/getting-started.md

@@ -36,7 +36,7 @@ Use `exclude_tags` when a project wants nearly every group.
 
 ```toml
 [tool.poe]
-include_script = "common_python_tasks:tasks(exclude_tags=['fastapi'])"
+include_script = "common_python_tasks:tasks(exclude_tags=['containers'])"
 ```
 
 Calling `tasks()` with no arguments selects only `common`. Passing an explicit empty `include_tags` sequence selects every task unless an exclusion removes it.

{common_python_tasks-0.12.1 → common_python_tasks-0.13.1}/docs/index.md

@@ -18,7 +18,6 @@ Tasks are organized by tags, so each project can select only the workflows it ne
 | `common` | Formatting, linting, testing, packaging, and releases |
 | `docs` | Build and locally serve Zensical documentation |
 | `containers` | Build, run, inspect, and publish container images |
-| `fastapi` | Run a local FastAPI and PostgreSQL development stack |
 
 The default task collection exposes the `common` group. Optional groups are enabled through the package's `include_script` expression.
 

{common_python_tasks-0.12.1 → common_python_tasks-0.13.1}/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.
 
@@ -393,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.
 
@@ -405,7 +414,7 @@ See [Container settings](../configuration.md#container-settings) for the complet
 | [`build-deps-image`](reference/build-deps-image.md) | Build only the container dependency collector image for this project. |
 | [`run-container`](reference/run-container.md) | Run the Docker image as a container for this project. |
 | [`push-image`](reference/push-image.md) | Push the Docker image for this project to the container registry. |
-| [`build`](reference/build.md) | Build the project and its containers. |
 | [`container-shell`](reference/container-shell.md) | Run the debug image with an interactive shell. |
+| [`build`](reference/build.md) | Build the project and its containers. |
 
 <!-- end-generated-task-reference -->

{common_python_tasks-0.12.1 → common_python_tasks-0.13.1}/docs/tasks/index.md

@@ -10,7 +10,6 @@ The task reference is divided by workflow. Each category page includes a table l
 | [Documentation](documentation.md) | Build and locally serve a Zensical site |
 | [Packaging and releases](packaging-and-releases.md) | Build, version, publish, and release packages |
 | [Container images](container-images.md) | Build, run, inspect, and publish images |
-| [Development stacks](development-stacks.md) | Operate the FastAPI and PostgreSQL Compose stack |
 
 Individual task reference pages are also available in the sidebar under the "reference" section.
 

{common_python_tasks-0.12.1 → common_python_tasks-0.13.1}/docs/tasks/packaging-and-releases.md

@@ -10,12 +10,14 @@ Publish targets and release hooks are described in [Configuration](../configurat
 
 | Task | Description |
 | - | - |
+| [`update-dependencies`](reference/update-dependencies.md) | Update project dependencies with uv. |
 | [`publish-package`](reference/publish-package.md) | Publish the package to the PyPI server. |
 | [`publish-github-release`](reference/publish-github-release.md) | Publish or update a GitHub Release for the current repository. |
-| [`update-dependencies`](reference/update-dependencies.md) | Update project dependencies with uv. |
 | [`build-package`](reference/build-package.md) | Build the package (wheel and sdist). |
 | [`bump-version`](reference/bump-version.md) | Bump the project version. |
 | [`changelog`](reference/changelog.md) | Print the changelog for the current version based on git history and git-cliff. |
 | [`release`](reference/release.md) | Run a full release flow for package and containers. |
 
 <!-- end-generated-task-reference -->
+
+Automatic releases default to a patch bump when no version bump is inferred, including when there are no new commits. Empty generated release notes use “No conventional commit messages found.” No synthetic commits are created for version inference.

{common_python_tasks-0.12.1 → common_python_tasks-0.13.1}/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.1 → common_python_tasks-0.13.1}/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.1 → common_python_tasks-0.13.1}/pyproject.toml

@@ -38,13 +38,11 @@ Source = "http://github.com/ci-sourcerer/common-python-tasks.git"
 Issues = "http://github.com/ci-sourcerer/common-python-tasks/issues"
 
 [tool.poe]
-include_script = "common_python_tasks:tasks(exclude_tags=['containers', 'fastapi'])"
+include_script = "common_python_tasks:tasks(exclude_tags=['containers'])"
 
 [tool.poe.tasks]
 update-docs-references = { cmd = "python -m scripts.update_docs_tasks_reference" }
 check-docs-references = { cmd = "python -m scripts.update_docs_tasks_reference --check" }
-update-docs-tasks-reference = { cmd = "python -m scripts.update_docs_tasks_reference" }
-check-docs-tasks-reference = { cmd = "python -m scripts.update_docs_tasks_reference --check" }
 
 [tool.poe.env]
 PYTHONPATH = "src"

{common_python_tasks-0.12.1 → common_python_tasks-0.13.1}/scripts/docs_tasks_reference.py

@@ -17,7 +17,6 @@ TASK_CATEGORY_FILES = {
     "documentation": Path("docs/tasks/documentation.md"),
     "packaging-and-releases": Path("docs/tasks/packaging-and-releases.md"),
     "container-images": Path("docs/tasks/container-images.md"),
-    "development-stacks": Path("docs/tasks/development-stacks.md"),
 }
 DOCKERFILE_REFERENCE_FILE = Path("docs/tasks/container-images.md")
 DOCKERFILE_TEMPLATE_FILES = (
@@ -36,8 +35,6 @@ def _get_task_category(task_name: str) -> str:
     tags = get_task_tags(task_name) or []
     if "docs" in tags:
         return "documentation"
-    if "web" in tags or "database" in tags:
-        return "development-stacks"
     if task_name == "release":
         return "packaging-and-releases"
     if "containers" in tags:

common_python_tasks-0.13.1/src/common_python_tasks/_task_registry.py

@@ -0,0 +1,163 @@
+import contextvars
+import inspect
+import logging
+import os
+import shlex
+from collections.abc import Callable
+from functools import partial, wraps
+from pathlib import Path
+from typing import ClassVar
+
+from poethepoet_tasks import TaskCollection
+
+
+class _ColoredFormatter(logging.Formatter):
+    COLORS: ClassVar = {
+        "WARNING": "\033[93m",
+        "ERROR": "\033[91m",
+        "CRITICAL": "\033[91m",
+        "RESET": "\033[0m",
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_color = self.COLORS.get(record.levelname, "")
+        record.levelname = f"\033[1m{log_color}{record.levelname}{self.COLORS['RESET'] if log_color else ''}\033[0m"
+        return super().format(record)
+
+
+LOGGER = logging.getLogger("common_python_tasks")
+handler = logging.StreamHandler()
+handler.setFormatter(_ColoredFormatter("[%(asctime)s] %(levelname)s: %(message)s"))
+LOGGER.addHandler(handler)
+LOGGER.setLevel(
+    {
+        "DEBUG": logging.DEBUG,
+        "INFO": logging.INFO,
+        "WARNING": logging.WARNING,
+        "ERROR": logging.ERROR,
+        "CRITICAL": logging.CRITICAL,
+    }[os.getenv("COMMON_PYTHON_TASKS_LOG_LEVEL", "INFO").upper()]
+)
+
+
+tasks = TaskCollection(
+    envfile=[
+        f
+        for f in [
+            ".env.defaults",
+            "project.properties",
+            ".env",
+        ]
+        if Path(f).exists()
+    ]
+)
+
+_task_call_depth: contextvars.ContextVar[int] = contextvars.ContextVar(
+    "common_python_tasks_task_call_depth", default=0
+)
+
+_original_script = tasks.script
+
+
+def _make_var_positional_task_args_optional(
+    func: callable, resolved_task_name: str
+) -> None:
+    var_positional_arg_names = {
+        param.name
+        for param in inspect.signature(func).parameters.values()
+        if param.kind == inspect.Parameter.VAR_POSITIONAL
+    }
+    if not var_positional_arg_names:
+        return
+
+    for task_config in tasks._tasks.get(resolved_task_name, []):
+        for arg_config in task_config.options.get("args", []):
+            if arg_config.get("name") in var_positional_arg_names:
+                arg_config["required"] = False
+
+
+def _wrap_task_function(func: callable, task_name: str | None) -> callable:
+    resolved_task_name = task_name or func.__name__.replace("_", "-").lower()
+    var_positional_arg_names = [
+        param.name
+        for param in inspect.signature(func).parameters.values()
+        if param.kind == inspect.Parameter.VAR_POSITIONAL
+    ]
+
+    @wraps(func)
+    def wrapped(*args, **kwargs):
+        for arg_name in var_positional_arg_names:
+            if arg_name not in kwargs:
+                continue
+            values = kwargs.pop(arg_name)
+            if values is None:
+                continue
+            if isinstance(values, list | tuple):
+                args = (*args, *values)
+            else:
+                args = (*args, values)
+
+        if var_positional_arg_names and (
+            poe_extra_args := os.environ.pop("POE_EXTRA_ARGS", None)
+        ):
+            args = (*args, *shlex.split(poe_extra_args))
+
+        current_depth = _task_call_depth.get()
+        if current_depth > 0:
+            LOGGER.log(
+                (
+                    logging.INFO
+                    if not resolved_task_name.startswith("_")
+                    else logging.DEBUG
+                ),
+                "Running task %s",
+                resolved_task_name,
+            )
+        token = _task_call_depth.set(current_depth + 1)
+        try:
+            return func(*args, **kwargs)
+        finally:
+            _task_call_depth.reset(token)
+
+    return wrapped
+
+
+def _script(
+    func: Callable | None = None,
+    task_name: str | None = None,
+    help: str | None = None,
+    task_args: bool = True,
+    options: dict | None = None,
+    tags: tuple[str, ...] | None = None,
+):
+
+    if tags is None:
+        tags = ()
+
+    if func is None:
+        return partial(
+            _script,
+            task_name=task_name,
+            help=help,
+            task_args=task_args,
+            options=options,
+            tags=tags,
+        )
+
+    resolved_task_name = task_name or func.__name__.replace("_", "-").lower()
+    wrapped = _wrap_task_function(func, resolved_task_name)
+    decorated = _original_script(
+        wrapped,
+        task_name=resolved_task_name,
+        help=help,
+        task_args=task_args,
+        options=options,
+        tags=tags,
+    )
+    _make_var_positional_task_args_optional(wrapped, resolved_task_name)
+    return decorated
+
+
+tasks.script = _script
+
+NO_PROMPT_ENV_VAR = "COMMON_PYTHON_TASKS_NO_PROMPT"