Metadata-Version: 2.4
Name: common-python-tasks
Version: 0.7.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
Description-Content-Type: text/markdown

# Common Python Tasks

`common-python-tasks` provides reusable, opinionated [Poe the Poet](https://poethepoet.natn.io/guides/packaged_tasks.html) tasks for common Python development workflows.

It supplies sensible defaults for formatting, linting, testing, packaging, releases, and container workflows while allowing projects to override configuration when needed.

## Quick start

### Manual setup

Add `common-python-tasks` as a development dependency from your project root.

```shell
uv add --dev common-python-tasks==0.7.0
# or, for Poetry projects
poetry add --group dev common-python-tasks==0.7.0
```

Configure Poe the Poet to expose the default `common` task set.

```toml
[tool.poe]
include_script = "common_python_tasks:tasks()"
```

Run the common development tasks.

```shell
poe format
poe lint
poe test
```

### Automated setup

The helper script performs the same development-dependency installation and Poe configuration. Download the script for the exact release you want, review it, then run it from your project root.

```shell
curl --fail --silent --show-error --location \
  --output /tmp/add_common_python_tasks.py \
  https://raw.githubusercontent.com/ci-sourcerer/common-python-tasks/v0.7.0/scripts/add_common_python_tasks.py
```

Review the downloaded script before executing it.

```shell
less /tmp/add_common_python_tasks.py
```

Run the reviewed script with the same pinned package version.

```shell
COMMON_PYTHON_TASKS_VERSION=0.7.0 python3 /tmp/add_common_python_tasks.py
```

To install another release, replace both occurrences of `0.7.0` with that release's version.

## Available tasks

The generated tables below list public tasks only. Tags identify which tasks are selected by `include_tags` and `exclude_tags`.

<!-- tasks-table -->

### Daily development

| Task | Description | Tags |
| --- | --- | --- |
| `test` | Run the test suite with coverage (if pytest-cov is installed). | common, test |
| `clean` | Clean up temporary files and directories. | clean, common |
| `format` | Fix import issues and format Python code with Ruff. | common, format |
| `lint` | Check Python lint and formatting with Ruff. | common, lint |

### Packaging and releases

| Task | Description | Tags |
| --- | --- | --- |
| `publish-package` | Publish the package to the PyPI server. | common, packaging |
| `publish-github-release` | Publish or update a GitHub Release for the current repository. | common, packaging, release |
| `update-dependencies` | Update project dependencies with Poetry or uv. | common, packaging |
| `build-package` | Build the package (wheel and sdist). | build, common, packaging |
| `bump-version` | Bump the project version. | common, packaging |
| `changelog` | Print the changelog for the current version based on git history and git-cliff. | common, packaging, release |
| `release` | Run a full release flow for package and containers. | common, containers, packaging, release |

### Container images

| Task | Description | Tags |
| --- | --- | --- |
| `build-image` | Build the container image for this project using the Dockerfile template. | build, containers |
| `build-deps-image` | Build only the container dependency collector image for this project. | build, containers |
| `run-container` | Run the Docker image as a container for this project. By default, this will run the most-recently-built tag for the project's image. | containers |
| `push-image` | Push the Docker image for this project to the container registry. | containers, packaging, release |
| `build` | Build the project and its containers. | common, containers, packaging |
| `container-shell` | Run the debug image with an interactive shell. | containers, debug |

### Development stacks

| Task | Description | Tags |
| --- | --- | --- |
| `stack-up` | Bring up the development stack for the application. | containers, fastapi, web |
| `stack-down` | Bring down the development stack for the application. | containers, fastapi, web |
| `reset-db` | Reset the database by deleting the database volume. | containers, database, fastapi, web |
| `run-db-migrations` | Run database migrations. | containers, database, fastapi, web |
| `db-shell` | Open a psql shell to the database container. | containers, database, fastapi, web |

<!-- end-tasks-table -->

## Configuration and requirements

### Requirements

Every project needs a `pyproject.toml` file at its root and Poe the Poet available in its development environment.

Tasks that install, build, publish, or update dependencies also require either Poetry or uv. Package and release tasks need a resolvable project version from `project.version`, Poetry's version resolution, or Git tags. Dynamic-versioning plugins are supported but are not a baseline requirement.

### Task selection

Calling `tasks()` without arguments exposes the default `common` task set.

```toml
[tool.poe]
include_script = "common_python_tasks:tasks()"
```

Select optional task groups with tags when your project needs them.

```toml
[tool.poe]
include_script = "common_python_tasks:tasks(include_tags=['common', 'containers'])"
```

The `containers` tag also includes container-based development-stack tasks. Use the tags in the task tables to tailor a smaller task set.

### Package manager backend selection

Packaging-related tasks, including `build-package`, `publish-package`, release version resolution, and container build metadata, support Poetry and uv.

Backend selection uses this precedence.

1. `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`
2. `COMMON_PYTHON_TASKS_BUILD_TOOL`
3. `PACKAGE_MANAGER`
4. Auto-discovery (`auto`) based on installed tools and project metadata

Supported values are `poetry`, `uv`, and `auto`.

### Configuration precedence

For pytest and coverage, configuration resolves in the following order.

1. Matching `pyproject.toml` sections such as `[tool.pytest.ini_options]` and `[tool.coverage]`
2. Environment variables that specify a configuration path
3. Local configuration files in the project root
4. Bundled defaults from [`src/common_python_tasks/data`](src/common_python_tasks/data)

Ruff uses `RUFF_CONFIG` when set. Otherwise it discovers `.ruff.toml`, `ruff.toml`, or a `[tool.ruff]` section in `pyproject.toml`. When no project configuration is available, the tasks use the bundled Ruff defaults. Ruff configuration follows Ruff's native file precedence, so `.ruff.toml` takes precedence over `ruff.toml`, which takes precedence over `pyproject.toml` in the same directory.

The `format` task first applies safe fixes for unused imports and import sorting, then runs the Ruff formatter. The `lint` task checks both Ruff lint rules and formatting without changing files.

### Configuration examples

After installing the package, a minimal project configuration looks like this.

```toml
[project]
name = "simple-cli-tool"
version = "0.7.0"

[tool.poe]
include_script = "common_python_tasks:tasks()"
```

A container-based project can select the container task group and set its image details.

```toml
[tool.poe]
include_script = "common_python_tasks:tasks(include_tags=['common', 'containers'])"

[tool.poe.env]
CONTAINER_REGISTRY_USERNAME = "myusername"
PACKAGE_NAME = "containerized-app"
```

The `test` task automatically uses pytest configuration in `pyproject.toml`.

```toml
[tool.pytest.ini_options]
testpaths = ["tests", "integration"]
addopts = "-ra"
```

### Environment variables

#### Task configuration files

- `PYTEST_CONFIG`: Path to the pytest configuration file
- `COVERAGE_RCFILE`: Path to the coverage configuration file
- `RUFF_CONFIG`: Path to a Ruff TOML configuration file

#### Project and package settings

- `PACKAGE_NAME`: Overrides the package name inferred from `pyproject.toml`
- `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`: Selects the package-manager backend as `poetry`, `uv`, or `auto`
- `COMMON_PYTHON_TASKS_BUILD_TOOL`: Alias for `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`
- `PACKAGE_MANAGER`: Alias for `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`

#### Container image settings

- `CONTAINER_REGISTRY_USERNAME`: Container-registry username for image tagging; the default is the current local user
- `CONTAINER_REGISTRY_URL`: Registry URL with a default of `docker.io/{username}`
- `CONTAINER_BUILD_ARGS`: Additional Docker build arguments in `KEY=VALUE:OTHER=VALUE` format. Escape literal colons as `\:` or quote the complete value.
- `CONTAINER_EXTENSION_FILES`: Colon-delimited local extension Dockerfile paths. Escape literal colons as `\:` or quote the complete path.
- `CONTAINER_EXTENSIONS`: Colon-delimited extension-bundle names or parameterized values. Escape literal colons as `\:` or quote the complete value.
- `CONTAINER_ENV`: Colon-delimited `KEY=VALUE` declarations injected into the rendered Dockerfile's builder stage. Escape literal colons as `\:` or quote the complete value.
- `.containerenv`: A project-root file that can supply the same declarations. It is loaded before the `container_envfile` task argument, `CONTAINER_ENV`, and the `container_env` task argument.
- `CONTAINER_PRUNE_KEEP`: Image-pruning policy after builds. `-1` keeps all images, `0` keeps only the latest, and `N` keeps the latest plus `N` prior images.
- `CUSTOM_ENTRYPOINT`: Custom container entrypoint script. The value must match a key in `[project].scripts`.
- `CONTAINER_DEPS_CONTENT`: Inline Dockerfile instructions for a dependency image that installs artifacts into `/tmp/deps`
- `CONTAINER_DEPS_FILE`: One or more dependency-image Dockerfiles. It accepts colon-delimited paths with literal colons escaped as `\:` and is used only when `CONTAINER_DEPS_CONTENT` is unset.
- `CONTAINER_DEPS_MAPPINGS`: Space-delimited `name:/target/path` entries for copying items from `/tmp/deps`. It is used only when no dependency move script is set.
- `CONTAINER_DEPS_MOVE_SCRIPT`: Raw executable script to run after `/tmp/deps` is copied into the image
- `CONTAINER_DEPS_MOVE_SCRIPT_PATH`: Host path to a dependency move script. This takes precedence over `CONTAINER_DEPS_MOVE_SCRIPT`.

#### Release settings

- `GITHUB_RELEASE_ASSETS`: Colon-delimited file paths or glob patterns to attach to a GitHub Release. The default is `dist/*`; escape literal colons as `\:` or quote the complete path.
- `SKIP_GITHUB_RELEASE`: Truthy value that skips GitHub Release publication
- `GITHUB_TOKEN` or `GH_TOKEN`: GitHub authentication token for releases and assets
- `GITHUB_REPOSITORY`: Optional repository-slug override for GitHub Release publication
- `GITHUB_API_URL` and `GITHUB_SERVER_URL`: GitHub Enterprise API-host settings
- `GITHUB_RELEASE_TAG`: Optional release tag name
- `GITHUB_RELEASE_NAME`: Optional release title
- `GITHUB_RELEASE_BODY`: Optional release body
- `RELEASE_UPDATE_CHANGELOG`: Truthy value that prepends `git-cliff --unreleased --tag "$RELEASE_TAG"` output to `CHANGELOG.md` before the release tag is created. It is enabled by default.
- `RELEASE_PRE_SCRIPT`: Optional shell command to run before release steps
- `RELEASE_POST_SCRIPT`: Optional shell command to run after release completion
- Release hooks receive `RELEASE_SCRIPT_PHASE`, `RELEASE_TAG`, `RELEASE_VERSION`, `RELEASE_STAGE`, `RELEASE_COMPONENT`, and `RELEASE_DRY_RUN`.

#### Docker Compose settings

- `COMPOSE_TYPE`: Application-stack type, such as `fastapi`
- `COMPOSE_ADDONS`: Colon-delimited services to include, such as `db`
- `COMPOSE_FILE`: Override for all compose files with colon-delimited paths
- `COMPOSE_OVERLAY_FILES`: Additional compose files to merge with colon-delimited paths
- `API_PORT`: API server port with a default of `8080`
- `SECRET_KEY`: Application secret key generated automatically when unset
- `ENVIRONMENT`: Environment name with a default of `production`
- `DEBUG_PORT`: Python debugger port in debug mode with a default of `5678`
- `DB_PORT`: PostgreSQL port with a default of `5432`
- `DB_USER`: Database user with a default of the package name
- `DB_BASE`: Database name with a default of the package name
- `DB_PASS`: Database password generated automatically when unset
- `POSTGRES_VERSION`: PostgreSQL version with a default of `17`
- `ADMINER_PORT`: Adminer web UI port with a default of `8081`

#### Debugging

- `COMMON_PYTHON_TASKS_LOG_LEVEL`: Set to `DEBUG` to show detailed configuration resolution

## Containers and development stacks

Docker Compose development-stack tasks are available when the `containers` tag is selected. The current stack supports FastAPI applications and an optional PostgreSQL database.

### Stack configuration

Set `COMPOSE_TYPE` to select the application stack. `fastapi` is currently supported and includes optional database support and Alembic migrations.

```toml
[tool.poe.env]
COMPOSE_TYPE = "fastapi"
```

Set `COMPOSE_ADDONS` to select extra services. Addon names are colon-delimited, and `db` is the currently available addon.

```toml
[tool.poe.env]
COMPOSE_ADDONS = "db"
```

### Compose-file customization

The compose setup resolves files in this precedence order.

1. **Environment override** uses `COMPOSE_FILE` with colon-delimited paths.
2. **Automatically loaded files** are based on `COMPOSE_TYPE` and `COMPOSE_ADDONS`.
   - `compose-base.yml` provides the core application service.
   - `compose-{addon}.yml` adds one file per addon, such as `compose-db.yml`.
   - `compose-debug.yml` is used when the `--debug` flag is present.
   - `compose-{addon}-debug.yml` provides debug overlays for addons.
3. **Additional overlays** use `COMPOSE_OVERLAY_FILES` with colon-delimited paths.

You can provide local compose files or allow the tasks to use bundled templates.

### FastAPI stack

The FastAPI stack uses the standard Dockerfile supplied by this package. Configure its ports, credentials, and database settings through the [Docker Compose settings](#docker-compose-settings) reference.

## Troubleshooting

### Tasks not showing up with `poe --help`

Check the `[tool.poe]` configuration in `pyproject.toml` and use `include_script`.

```toml
# Correct
[tool.poe]
include_script = "common_python_tasks:tasks(exclude_tags=['internal'])"

# Incorrect
[tool.poe]
includes = "common_python_tasks:tasks"
```

### Config files not being used

Review the [configuration precedence](#configuration-precedence) and enable debug logging to see the selected configuration.

```shell
COMMON_PYTHON_TASKS_LOG_LEVEL=DEBUG poe test
```

### GitHub Release assets not uploading

Confirm that `dist/` contains the built wheels and source distributions. You can override the default asset selection with `GITHUB_RELEASE_ASSETS`.

```shell
GITHUB_RELEASE_ASSETS="dist/*.whl:dist/*.tar.gz" poe publish-github-release
```

### Container build fails with "unable to find package"

Check that `pyproject.toml` has a correct package name and the package-discovery settings required by its build backend. For Poetry projects, this commonly includes `[tool.poetry] packages = [{ include = "your_package", from = "src" }]`.

### Stack fails to start or services cannot connect

Check the following conditions.

- `COMPOSE_TYPE` is set and the required addon is selected.
- Default ports are available, including `8080` for the API, `5432` for PostgreSQL, and `8081` for Adminer.
- The Docker daemon is running, as verified with `docker info`.
- Service logs are available through `docker compose logs` in the project directory.

### Database migrations fail

Verify that the `db` addon is selected, Alembic is configured at the expected location, and its credentials match the generated `.env` values. Use `poe db-shell` to inspect the database manually.

### Secrets are not generated

Ensure the project-root `.env` file is writable and inspect its permissions with `ls -la .env`. You can also generate a value manually with `python -c "import secrets; print(secrets.token_hex(32))"`.

## Design choices

### Dockerfile design

See the [standard Dockerfile template](src/common_python_tasks/data/generic/Dockerfile.j2) for the implementation.

- Multi-stage build: The build stage installs the selected package-manager backend and builds a wheel. The runtime stage installs only the wheel to keep the final image slim and reproducible.
- Cache mounts: Pip and package-manager cache mounts speed up iterative builds without bloating the final image.
- Explicit build arguments: `PYTHON_VERSION`, `PACKAGE_MANAGER`, `PACKAGE_MANAGER_VERSION`, `PACKAGE_NAME`, `AUTHORS`, `GIT_COMMIT`, and `CUSTOM_ENTRYPOINT` make image metadata and behavior predictable and auditable.
- Optional debug stage: The image exports and installs the `debug` dependency group only when present and does not include it in the default final image.
- Stable package path: Symlinks give entrypoints and consumers consistent `/pkg` and `/_$PACKAGE_NAME` paths regardless of wheel layout.
- Safe entrypoint selection: The default entrypoint resolves the console script matching the package name and falls back to `python`. `CUSTOM_ENTRYPOINT` is validated against `[project].scripts`.
- Minimal final image: The standard slim Python base, cache cleanup, and explicit `runtime` final target keep the default image small.

## Project notes

- This project dogfoods itself. Set `PYTHONPATH=src` when running its tasks locally so Poe uses the local package rather than the installed version.
- `RELEASE_UPDATE_CHANGELOG` is enabled by default and prepends the generated changelog section before the release tag is created. Set it to a falsy value to manage changelog commits yourself.
- `RELEASE_PRE_SCRIPT` and `RELEASE_POST_SCRIPT` are advanced hooks for release-specific work, such as updating a version reference in another file.
- The project is in alpha status, so breaking changes may occur between minor versions before 1.0.0.

## Contributing

Contributions and feedback are welcome. Please open an issue or discussion to talk through a change before submitting a pull request.
