common-python-tasks 0.10.2__tar.gz → 0.11.0__tar.gz

{common_python_tasks-0.10.2 → common_python_tasks-0.11.0}/.gitignore

@@ -164,7 +164,7 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# Generated documentation site
 /site
 
 # mypy

common_python_tasks-0.11.0/PKG-INFO

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

common_python_tasks-0.11.0/README.md

@@ -0,0 +1,61 @@
+# Common Python Tasks
+
+`common-python-tasks` provides reusable, opinionated [Poe the Poet](https://poethepoet.natn.io/guides/packaged_tasks.html) tasks for Python development, packaging, releases, containers, and documentation.
+
+Read the [complete documentation](https://ci-sourcerer.github.io/common-python-tasks/) for the task reference, configuration options, and deployment guidance.
+
+## Quick start
+
+Add the package as a development dependency.
+
+```shell
+uv add --dev common-python-tasks==0.11.0
+```
+
+Expose the default task set in `pyproject.toml`.
+
+```toml
+[tool.poe]
+include_script = "common_python_tasks:tasks()"
+```
+
+Run the everyday development tasks.
+
+```shell
+poe format
+poe lint
+poe test
+```
+
+## Optional workflows
+
+Select additional task groups with `include_tags`.
+
+```toml
+[tool.poe]
+include_script = "common_python_tasks:tasks(include_tags=['common', 'docs', 'containers'])"
+```
+
+| Tag | Purpose |
+| - | - |
+| `common` | Formatting, linting, testing, packaging, and releases |
+| `docs` | Build and serve Zensical documentation |
+| `containers` | Build, run, inspect, and publish container images |
+| `fastapi` | Run the FastAPI and PostgreSQL development stack |
+
+Documentation projects can build locally or start a development server.
+
+```shell
+poe docs-build
+poe docs-serve
+```
+
+The [documentation workflow guide](https://ci-sourcerer.github.io/common-python-tasks/documentation-workflows/) covers GitHub Actions artifacts, optional Cloudflare Pages previews, and GitHub Pages deployment.
+
+## Learn more
+
+- [Getting started](https://ci-sourcerer.github.io/common-python-tasks/getting-started/)
+- [Task reference](https://ci-sourcerer.github.io/common-python-tasks/tasks/)
+- [Configuration reference](https://ci-sourcerer.github.io/common-python-tasks/configuration/)
+
+The project is in alpha, so minor releases may contain breaking changes. It is distributed under the [MIT license](LICENSE).

common_python_tasks-0.11.0/docs/configuration.md

@@ -0,0 +1,94 @@
+# Configuration
+
+Every consuming project needs `pyproject.toml` and Poe the Poet. Tasks that build, publish, install, or update packages use uv.
+
+## Configuration precedence
+
+Pytest and coverage configuration is resolved in this order.
+
+1. Matching `pyproject.toml` sections
+2. Environment variables naming configuration files
+3. Project-root configuration files
+4. Defaults bundled with `common-python-tasks`
+
+Ruff uses `RUFF_CONFIG` when set. Otherwise, it discovers `.ruff.toml`, `ruff.toml`, or `[tool.ruff]` in `pyproject.toml`. The bundled configuration is used when the project has no Ruff configuration.
+
+## Project and publishing settings
+
+| Setting | Purpose |
+| - | - |
+| `PACKAGE_NAME` | Override the package name inferred from `pyproject.toml` |
+| `COMMON_PYTHON_TASKS_PUBLISH_REPOSITORY` | Select a named uv publish index |
+| `COMMON_PYTHON_TASKS_PUBLISH_URL` | Select a uv upload URL |
+| `GITHUB_RELEASE_ASSETS` | Select GitHub Release asset paths or glob patterns |
+| `SKIP_GITHUB_RELEASE` | Disable GitHub Release publication |
+| `RELEASE_UPDATE_CHANGELOG` | Generate and commit release changelog content |
+| `RELEASE_PRE_SCRIPT` | Run a command before the release steps |
+| `RELEASE_POST_SCRIPT` | Run a command after the release steps |
+
+The package also recognizes uv's `UV_PUBLISH_INDEX` and `UV_PUBLISH_URL` settings. Explicit task arguments take precedence over environment values and project configuration.
+
+## Container settings
+
+Container variables are read by the host-side tasks unless their description explicitly says that they persist in the image. See [Container images](tasks/container-images.md) for the generated Dockerfile lifecycle, environment precedence, extensions, and dependency images.
+
+### Image and build settings
+
+| Setting | Purpose |
+| - | - |
+| `CONTAINER_REGISTRY_USERNAME` | Registry username used for image tags |
+| `CONTAINER_REGISTRY_URL` | Registry hostname and optional namespace path; defaults to `docker.io/<username>` |
+| `CONTAINER_REGISTRY_NAMESPACE` | Namespace appended when the registry URL contains only a hostname |
+| `CONTAINER_PYTHON_VARIANT` | Python base-image variant; defaults to `slim`, while an empty value disables the suffix |
+| `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_DOCKERFILE_HOOK_PATH` | Executable host script that modifies the rendered 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 |
+
+### Environment and extension settings
+
+| Setting | Purpose |
+| - | - |
+| `CONTAINER_ENV` | Colon-delimited `KEY=VALUE` declarations persisted in the builder, runtime, final, and debug images |
+| `.containerenv` | Project-root file containing the same declarations, at the lowest precedence |
+| `UV_INDEX_<NAME>_USERNAME` | Private uv index username passed to BuildKit as a secret rather than persisted in the image |
+| `UV_INDEX_<NAME>_PASSWORD` | Private uv index password passed to BuildKit as a secret rather than persisted in the image |
+| `CONTAINER_EXTENSION_FILES` | Colon-delimited local Dockerfile fragments appended to the runtime stage |
+| `CONTAINER_EXTENSIONS` | Colon-delimited installed extension bundles, optionally written as `bundle=value` |
+
+### Dependency-image settings
+
+| Setting | Purpose |
+| - | - |
+| `CONTAINER_DEPS_CONTENT` | Inline instructions for the bundled dependency-image Dockerfile; takes precedence over dependency files |
+| `CONTAINER_DEPS_FILE` | Colon-delimited complete dependency Dockerfiles used when inline content is unset |
+| `CONTAINER_DEPS_IMAGE` | Existing image that exports artifacts through `/tmp/deps` |
+| `CONTAINER_DEPS_MAPPINGS` | Whitespace-delimited `name:/destination/path` moves for content copied from `/tmp/deps` |
+| `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
+
+Set `COMMON_PYTHON_TASKS_LOG_LEVEL=DEBUG` to show configuration resolution and subprocess commands.
+
+```shell
+COMMON_PYTHON_TASKS_LOG_LEVEL=DEBUG poe test
+```
+
+The complete environment-variable inventory remains available in the repository [README](https://github.com/ci-sourcerer/common-python-tasks#environment-variables).

common_python_tasks-0.11.0/docs/documentation-workflows.md

@@ -0,0 +1,104 @@
+# 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.

common_python_tasks-0.11.0/docs/getting-started.md

@@ -0,0 +1,72 @@
+# Getting started
+
+## Add the development dependency
+
+Add a released version of `common-python-tasks` from the root of a Python project.
+
+```shell
+uv add --dev common-python-tasks==0.10.3
+```
+
+Configure Poe to expose the standard task set.
+
+```toml
+[tool.poe]
+include_script = "common_python_tasks:tasks()"
+```
+
+The default selection provides formatting, linting, testing, package builds, dependency updates, and release tasks.
+
+```shell
+poe format
+poe lint
+poe test
+```
+
+## Select optional task groups
+
+Pass `include_tags` when a project needs optional workflows.
+
+```toml
+[tool.poe]
+include_script = "common_python_tasks:tasks(include_tags=['common', 'docs', 'containers'])"
+```
+
+Use `exclude_tags` when a project wants nearly every group.
+
+```toml
+[tool.poe]
+include_script = "common_python_tasks:tasks(exclude_tags=['fastapi'])"
+```
+
+Calling `tasks()` with no arguments selects only `common`. Passing an explicit empty `include_tags` sequence selects every task unless an exclusion removes it.
+
+## Automated setup
+
+The release helper adds the dependency and configures Poe. Download the helper for the exact release being installed, review it, and run it with the same version.
+
+```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
+```
+
+```shell
+COMMON_PYTHON_TASKS_VERSION=0.10.3 python3 /tmp/add_common_python_tasks.py
+```
+
+## Inspect available tasks
+
+Poe displays the tasks selected by the project.
+
+```shell
+poe --help
+```
+
+The package module also lists its public default tasks. Set the log level to include their descriptions.
+
+```shell
+COMMON_PYTHON_TASKS_LOG_LEVEL=DEBUG python -m common_python_tasks
+```
+
+Continue with the [task reference](tasks/index.md) for task-specific behavior and requirements.

common_python_tasks-0.11.0/docs/index.md

@@ -0,0 +1,34 @@
+# Common Python Tasks
+
+`common-python-tasks` is a reusable collection of opinionated [Poe the Poet](https://poethepoet.natn.io/guides/packaged_tasks.html) tasks for Python projects. It gives projects one shared implementation for everyday development, packaging, releases, container images, development stacks, and documentation.
+
+## Choose where to begin
+
+- **Adding the package to a project?** Follow [Getting started](getting-started.md).
+- **Looking for a command?** Browse the [task reference](tasks/index.md).
+- **Customizing behavior?** Use the [configuration reference](configuration.md).
+- **Publishing documentation like this?** See the [documentation workflows](documentation-workflows.md).
+
+## Task groups
+
+Tasks are organized by tags, so each project can select only the workflows it needs.
+
+| Group | Purpose |
+| - | - |
+| `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.
+
+```toml
+[tool.poe]
+include_script = "common_python_tasks:tasks(include_tags=['common', 'docs'])"
+```
+
+## Design approach
+
+The package supplies executable workflows and conservative defaults. Project-specific source files remain in the consuming repository, including application code, documentation content, Zensical configuration, Docker extensions, and environment settings.
+
+Commands run in the consuming project's environment, so the same task definitions work locally and in CI without hiding the underlying tools.