common-python-tasks 0.0.1__py3-none-any.whl

common_python_tasks/__init__.py

@@ -0,0 +1,16 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+from poethepoet_tasks import TaskCollection
+
+__version__ = "0.0.0"
+
+__all__ = ["TaskCollection"]
+
+
+def tasks(include_tags: Sequence[str] = tuple(), exclude_tags: Sequence[str] = tuple()):
+    from .tasks import tasks
+
+    return tasks(include_tags=include_tags, exclude_tags=exclude_tags)

common_python_tasks/data/.coveragerc

@@ -0,0 +1,8 @@
+[run]
+omit =
+    tests/*
+    */vendor/*
+    */__main__.py
+[paths]
+source =
+    src/*

common_python_tasks/data/.dockerignore

@@ -0,0 +1,10 @@
+*
+!dist/*.whl
+!pyproject.toml
+!poetry.lock
+!README.md
+!LICENSE
+
+!src
+
+!.git

common_python_tasks/data/.flake8

@@ -0,0 +1,9 @@
+[flake8]
+extend-ignore = E501,E203,W503
+max-line-length = 88
+select = B,C,E,F,W,T4,B9
+exclude =
+    .poetry
+    .venv
+    .dist
+    build

common_python_tasks/data/.isort.cfg

@@ -0,0 +1,4 @@
+[settings]
+profile=black
+multi_line_output=3
+extend_skip_glob=.poetry/*

common_python_tasks/data/Containerfile

@@ -0,0 +1,76 @@
+# syntax=docker/dockerfile:1
+
+ARG PYTHON_VERSION=3
+
+FROM python:${PYTHON_VERSION} AS builder
+
+ENV PYTHON_VERSION=${PYTHON_VERSION}
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+ARG POETRY_VERSION
+
+# Install Poetry and required Poetry plugins
+RUN --mount=type=cache,target=/root/.cache/pip pip install "poetry==$POETRY_VERSION" "poetry-dynamic-versioning[plugin]" poetry-plugin-export tomlkit
+
+# Build package
+WORKDIR /tmp/build
+COPY . /tmp/build/
+
+# Try to export debug requirements but don't fail the build if the group doesn't exist
+RUN --mount=type=cache,target=/root/.cache/pip \
+    if python -c "import tomlkit; t = tomlkit.load(open('pyproject.toml')); exit(0 if ('dependency-groups' in t and 'debug' in t['dependency-groups'] and t['dependency-groups']['debug']) else 1)"; then \
+        poetry export --only debug --without-hashes -f requirements.txt --output requirements-debug.txt; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/pypoetry poetry build --format=wheel
+
+FROM python:${PYTHON_VERSION}-slim AS runtime
+
+WORKDIR /
+
+# Grab package from builder image
+COPY --from=builder /tmp/build/dist/*.whl /tmp/
+
+# Install package
+RUN --mount=type=cache,target=/root/.cache/pip pip install /tmp/*.whl
+RUN rm -rf /tmp/*.whl \
+    && rm -rf /root/.cache/pip
+# Create symlinks for the package
+ARG PACKAGE_NAME
+ENV PACKAGE_NAME=${PACKAGE_NAME}
+RUN ln -s "$(python -c "import os; from importlib import resources; print(resources.files(os.environ['PACKAGE_NAME']))")" "/_$PACKAGE_NAME" \
+    && ln -s "/_$PACKAGE_NAME" "/pkg" \
+    && rm -rf "/_$PACKAGE_NAME/__pycache__"
+
+ENTRYPOINT ["/pkg/entrypoint.sh"]
+
+ARG AUTHORS
+ARG GIT_COMMIT
+LABEL org.opencontainers.image.authors=${AUTHORS}
+LABEL git.commit=${GIT_COMMIT}
+
+# Set custom entrypoint if provided
+# This entrypoint is deliberately not configurable via environment variables in order to
+# ensure that the container always uses the entrypoint selected at build time. If the
+# current package does not provide a console script, the entrypoint will default to python
+ARG CUSTOM_ENTRYPOINT
+RUN if [ -z "${CUSTOM_ENTRYPOINT}" ]; then cliScriptName=$(python -c "import os; from importlib import metadata as m; print(next((e.name for e in m.entry_points().select(group='console_scripts') if e.name==os.environ['PACKAGE_NAME'].replace('-','_')), ''))"); else cliScriptName=$CUSTOM_ENTRYPOINT; fi \
+    && echo "#!/bin/sh\n\n${cliScriptName:-python} \"\$@\"" >/pkg/entrypoint.sh \
+    && chmod +x /pkg/entrypoint.sh
+
+# Optional debug stage: only installs debug deps if they were exported. This stage will not
+# be built by default (the final stage below is the runtime image), and it will safely do
+# nothing if there are no debug requirements
+FROM runtime AS debug
+
+COPY --from=builder /tmp/build /tmp/build
+
+RUN --mount=type=cache,target=/root/.cache/pip if [ -f /tmp/build/requirements-debug.txt ] && [ -s /tmp/build/requirements-debug.txt ]; then pip install -r /tmp/build/requirements-debug.txt; fi
+RUN rm -rf /tmp/build /root/.cache/pip
+
+# Final (default) image: explicitly use runtime as the final target so debug is not used unless requested
+FROM runtime AS final
+
+RUN rm -rf /tmp/build /root/.cache/pip

common_python_tasks/data/pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+filterwarnings =
+    error::DeprecationWarning
+    ignore:unclosed database in <sqlite3.Connection object at:ResourceWarning

common_python_tasks/tasks.py

@@ -0,0 +1,870 @@
+import logging
+import os
+from collections.abc import Callable, Sequence
+from functools import lru_cache
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import subprocess
+    from typing import Literal
+
+from poethepoet_tasks import TaskCollection
+
+
+class _ColoredFormatter(logging.Formatter):
+    """Custom formatter with color codes for different log levels."""
+
+    COLORS = {
+        "WARNING": "\033[93m",  # Yellow
+        "ERROR": "\033[91m",  # Red
+        "CRITICAL": "\033[91m",  # Red
+        "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()]
+)
+
+
+def _env_truthy(env_var: str) -> bool:
+    return os.getenv(env_var, "").lower() in {
+        "1",
+        "true",
+        "yes",
+        "on",
+        "enabled",
+        "y",
+        "t",
+    }
+
+
+@lru_cache
+def _is_package_installed(package_name: str) -> bool:
+    """Check if a Python package is installed in the current environment."""
+    from importlib.util import find_spec
+
+    # Handle packages where import name differs from package name
+    import_name = package_name.replace("-", "_")
+    is_installed = find_spec(import_name) is not None
+    if not is_installed:
+        LOGGER.debug("%s is not installed, skipping", package_name)
+    return is_installed
+
+
+def _fatal(message: str, exit_code: int = 1) -> None:
+    import sys
+
+    LOGGER.error(message)
+    sys.exit(exit_code)
+
+
+def _require_package(package_name: str) -> None:
+    if not _is_package_installed(package_name):
+        _fatal(f"{package_name} is not installed")
+
+
+def _run_available_tools(
+    tools: list[tuple[Callable, str]], none_available_message: str
+) -> None:
+    ran_any = False
+    for fn, package in tools:
+        if _is_package_installed(package):
+            fn()
+            ran_any = True
+    if not ran_any:
+        _fatal(none_available_message)
+
+
+def _get_authors() -> list[tuple[str, str]]:
+    import tomllib
+
+    pyproject_data = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+
+    def _parse_author(author: dict[str, str]) -> tuple[str, str]:
+        return (author.get("name") or "").strip(), (
+            author.get("email") or ""
+        ).strip().strip("<>")
+
+    return [
+        _parse_author(author)
+        for author in (pyproject_data.get("project", {}).get("authors", []))
+    ]
+
+
+def _run_command(
+    command: Sequence[str],
+    *,
+    capture_output: bool = False,
+    acceptable_returncodes: Sequence[int] | None = None,
+) -> "subprocess.CompletedProcess":
+    import subprocess
+    from shlex import quote
+
+    if acceptable_returncodes is None:
+        acceptable_returncodes = {0}
+
+    command_display = " ".join([quote(arg) for arg in command])
+    LOGGER.debug("Running command: %s", command_display)
+    out = subprocess.run(
+        command,
+        capture_output=capture_output,
+        text=True,
+    )
+    if out.returncode not in acceptable_returncodes:
+        if capture_output:
+            stdout = out.stdout.strip() if out.stdout else ""
+            stderr = out.stderr.strip() if out.stderr else ""
+            details = ""
+            if stdout:
+                details += f"\nstdout: {stdout}"
+            if stderr:
+                details += f"\nstderr: {stderr}"
+        else:
+            details = ""
+        LOGGER.error(
+            "Command failed (exit code %d): %s%s",
+            out.returncode,
+            command_display,
+            details,
+        )
+
+        import sys
+
+        sys.exit(out.returncode)
+    return out
+
+
+def _load_data_file(file_name: str) -> tuple[str, str]:
+    from importlib.resources import files
+
+    try:
+        data_files = files("common_python_tasks") / "data"
+        data_file = data_files / file_name
+        return (str(data_file), data_file.read_text())
+    except FileNotFoundError as e:
+        _fatal(f"Data file not found: {file_name} ({e})")
+
+
+def _get_dirty_files(ignore: list[str] | None = None) -> list[str]:
+    if ignore is None:
+        ignore = []
+
+    return [
+        f
+        for f in [
+            line[3:]
+            for line in _run_command(
+                ["git", "status", "--porcelain"], capture_output=True
+            ).stdout.splitlines()
+            if line
+        ]
+        if f not in ignore
+    ]
+
+
+def _get_version(files_to_ignore_as_dirty: list[str] | None = None) -> str:
+    from dunamai import Style, Version
+
+    if files_to_ignore_as_dirty is None:
+        files_to_ignore_as_dirty = []
+
+    dirty_files = _get_dirty_files(ignore=files_to_ignore_as_dirty)
+    LOGGER.debug("Dirty files: %s", dirty_files)
+
+    return Version.from_git().serialize(
+        style=Style.Pep440,
+        dirty=bool(dirty_files),
+    )
+
+
+def _get_image_tag(files_to_ignore_as_dirty: list[str] | None = None) -> str:
+    if files_to_ignore_as_dirty is None:
+        files_to_ignore_as_dirty = []
+
+    return (
+        _get_version(files_to_ignore_as_dirty=files_to_ignore_as_dirty)
+        .replace(".post", "-post")
+        .replace(".dev", "-dev")
+        .replace("+", "-")
+    )
+
+
+def _has_tags_later_in_history() -> bool:
+    result = _run_command(
+        ["git", "tag"],
+        capture_output=True,
+        acceptable_returncodes={0, 128},
+    )
+    if result.returncode != 0 or not result.stdout.strip():
+        # No tags exist
+        return False
+
+    # Check each tag to see if it's reachable from HEAD
+    for tag in result.stdout.strip().split("\n"):
+        # Check if HEAD is an ancestor of the tag's commit
+        # If git merge-base --is-ancestor HEAD <tag> returns 0, then HEAD is an ancestor
+        # If it returns 1, then HEAD is NOT an ancestor (tag is in a different branch/future)
+        check_result = _run_command(
+            ["git", "merge-base", "--is-ancestor", "HEAD", tag],
+            capture_output=True,
+            acceptable_returncodes={0, 1},
+        )
+        if check_result.returncode == 1:
+            # HEAD is not an ancestor of this tag, meaning the tag is later in history
+            return True
+
+    return False
+
+
+def _get_dockerhub_username() -> str:
+
+    from getpass import getuser
+
+    return os.getenv("DOCKERHUB_USERNAME") or getuser()
+
+
+def _get_package_name(use_underscores: bool = False) -> str:
+    import tomllib
+
+    name = os.getenv("PACKAGE_NAME") or tomllib.loads(
+        Path("pyproject.toml").read_text()
+    ).get("project", {}).get("name")
+    if use_underscores and name:
+        name = name.replace("-", "_")
+    return name
+
+
+@lru_cache
+def _read_pyproject_toml() -> dict[str, Any]:
+    import tomllib
+
+    return tomllib.loads(Path("pyproject.toml").read_text())
+
+
+def get_config_path(
+    env_var_name: str,
+    local_config_filename: str,
+    data_config_filename: str,
+    *,
+    tool_name: str | None = None,
+) -> Path | None:
+    """Get the path to a configuration file.
+
+    Checks for configuration in the following order:
+    1. If tool_name provided, check if tool.{tool_name} exists in pyproject.toml
+       - If it exists, return None (use pyproject.toml config)
+    2. Check environment variable
+    3. Check for local config file
+    4. Fall back to bundled data file
+
+    Args:
+        env_var_name: Name of the environment variable to check
+        local_config_filename: Name of the local config file to look for
+        data_config_filename: Name of the bundled config file to use as fallback
+        tool_name: Optional tool name to check in pyproject.toml under [tool.{tool_name}]
+
+    Returns:
+        Path to config file, or None if config exists in pyproject.toml
+    """
+    # Check if config exists in pyproject.toml
+    if tool_name is not None:
+        pyproject_data = _read_pyproject_toml()
+        if pyproject_data.get("tool", {}).get(tool_name):
+            LOGGER.debug("Using [tool.%s] configuration from pyproject.toml", tool_name)
+            return None
+
+    # Check environment variable
+    if os.getenv(env_var_name):
+        config_path = Path(os.getenv(env_var_name))
+        LOGGER.debug("Using config from %s: %s", env_var_name, config_path)
+        return config_path
+
+    # Check for local config file
+    local_config_path = Path(local_config_filename)
+    if local_config_path.exists():
+        LOGGER.debug("Using local config file: %s", local_config_path)
+        return local_config_path
+
+    # Fall back to bundled data file
+    config_path = Path(_load_data_file(data_config_filename)[0])
+    LOGGER.debug("Using bundled config file: %s", config_path)
+    return config_path
+
+
+tasks = TaskCollection(
+    envfile=[
+        f
+        for f in [
+            "project.properties",
+            ".env",
+        ]
+        if Path(f).exists()
+    ]
+)
+
+
+@tasks.script(task_name="_black", tags=["format", "internal"])
+def black() -> None:
+    """Run black formatting."""
+    _require_package("black")
+    _run_command(["black", "--quiet", "."])
+
+
+@tasks.script(task_name="_isort", tags=["format", "internal"])
+def isort() -> None:
+    """Run isort formatting."""
+    _require_package("isort")
+    isort_config_path = get_config_path(
+        "ISORT_CONFIG",
+        ".isort.cfg",
+        ".isort.cfg",
+        tool_name="isort",
+    )
+
+    _run_command(
+        [
+            "isort",
+            "--quiet",
+            ".",
+            "--settings-path",
+        ]
+        + ([str(isort_config_path)] if isort_config_path else [])
+    )
+
+
+@tasks.script(task_name="_autoflake", tags=["format", "internal"])
+def autoflake() -> None:
+    """Run autoflake to remove unused imports."""
+    _require_package("autoflake")
+    _run_command(
+        [
+            "autoflake",
+            "--quiet",
+            "--remove-all-unused-imports",
+            "--recursive",
+            "-i",
+            ".",
+        ]
+    )
+
+
+@tasks.script(task_name="_black_check", tags=["lint", "internal"])
+def black_check() -> None:
+    """Run black in check mode."""
+    _require_package("black")
+    _run_command(["black", "--quiet", "--diff", ".", "--check"])
+
+
+@tasks.script(task_name="_isort_check", tags=["lint"])
+def isort_check() -> None:
+    """Run isort linting."""
+    _require_package("isort")
+    isort_config_path = get_config_path(
+        "ISORT_CONFIG",
+        ".isort.cfg",
+        ".isort.cfg",
+        tool_name="isort",
+    )
+
+    _run_command(
+        [
+            "isort",
+            "--quiet",
+            ".",
+            "--check-only",
+            "--settings-path",
+        ]
+        + ([str(isort_config_path)] if isort_config_path else [])
+    )
+
+
+@tasks.script(task_name="_autoflake_check", tags=["lint", "internal"])
+def autoflake_check() -> None:
+    """Run autoflake in check mode."""
+    _require_package("autoflake")
+    _run_command(
+        [
+            "autoflake",
+            "--quiet",
+            "--remove-all-unused-imports",
+            "--recursive",
+            "-cd",
+            ".",
+        ]
+    )
+
+
+@tasks.script(task_name="_flake8_check", tags=["lint"])
+def flake8_check() -> None:
+    """Run flake8 linting."""
+    _require_package("flake8")
+
+    flake8_config_path = get_config_path(
+        "FLAKE8_CONFIG",
+        ".flake8",
+        ".flake8",
+    )
+
+    _run_command(["flake8", ".", "--config", str(flake8_config_path)])
+
+
+@tasks.script(tags=["test"])
+def test() -> None:
+    """Run the test suite with coverage (if pytest-cov is installed)."""
+    coverage_config_path = get_config_path(
+        "COVERAGE_RCFILE",
+        ".coveragerc",
+        ".coveragerc",
+        tool_name="coverage",
+    )
+
+    pytest_config_path = get_config_path(
+        "PYTEST_CONFIG",
+        "pytest.ini",
+        "pytest.ini",
+        tool_name="pytest",
+    )
+
+    if _is_package_installed("pytest_cov"):
+        coverage_args = [
+            "--cov=" + _get_package_name(use_underscores=True),
+            "--cov-report=term-missing",
+            "--cov-report=xml:coverage.xml",
+        ] + (
+            [
+                "--cov-config=" + str(coverage_config_path),
+            ]
+            if coverage_config_path
+            else []
+        )
+    else:
+        coverage_args = []
+
+    exit_code = _run_command(
+        (
+            [
+                "pytest",
+                "-vv",
+            ]
+            + (
+                [
+                    "-c",
+                    str(pytest_config_path),
+                ]
+                if pytest_config_path
+                else []
+            )
+            + coverage_args
+        ),
+        acceptable_returncodes={0, 5},
+    ).returncode
+
+    if exit_code == 5:
+        LOGGER.warning("No tests were collected.")
+
+        import sys
+
+        sys.exit(5)
+
+
+@tasks.script(task_name="clean", tags=["clean"])
+def clean() -> None:
+    """Clean up temporary files and directories."""
+    import shutil
+
+    for item in [
+        *[Path(p) for p in [".pytest_cache", "dist", ".mypy_cache"]],
+        *Path(".").rglob("__pycache__"),
+        *Path(".").rglob("*.pyc"),
+        Path(".coverage"),
+        Path("coverage.xml"),
+    ]:
+        if item.is_dir():
+            shutil.rmtree(item, ignore_errors=True)
+        else:
+            item.unlink(missing_ok=True)
+
+
+@tasks.script(task_name="format", tags=["format"])
+def format_all() -> None:
+    """Format Python code with autoflake, black, and isort."""
+    _run_available_tools(
+        [
+            (autoflake, "autoflake"),
+            (black, "black"),
+            (isort, "isort"),
+        ],
+        "No formatting tools are installed. Install one or more of: autoflake, black, isort",
+    )
+
+
+@tasks.script(task_name="lint", tags=["lint"])
+def lint_all() -> None:
+    """Lint Python code with autoflake, black, isort, and flake8."""
+    _run_available_tools(
+        [
+            (autoflake_check, "autoflake"),
+            (black_check, "black"),
+            (isort_check, "isort"),
+            (flake8_check, "flake8"),
+        ],
+        "No linting tools are installed. Install one or more of: autoflake, black, isort, flake8",
+    )
+
+
+def _build_image(
+    containerfile_path: Path | None = None,
+    containerfile_text: str | None = None,
+    context_path: Path | None = None,
+    debug: bool = False,
+    no_cache: bool = False,
+    plain: bool = False,
+    single_arch: bool = False,
+) -> None:
+    import platform
+
+    if context_path is None:
+        context_path = Path(".")
+
+    temp_file_path: str | None = None
+    if containerfile_path is None:
+        if containerfile_text is None:
+            _fatal("Either containerfile_path or containerfile_text must be provided.")
+        import tempfile
+
+        tf = tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            delete=False,
+            prefix="Containerfile.",
+            suffix=".generated",
+        )
+        temp_file_path = tf.name
+        with open(temp_file_path, "w", encoding="utf-8") as f:
+            f.write(containerfile_text)
+        containerfile_path = Path(temp_file_path)
+
+    # Handle .dockerignore file
+    dockerignore_path = context_path / ".dockerignore"
+    temp_dockerignore_created = False
+    if not dockerignore_path.exists():
+        LOGGER.debug("No .dockerignore found, using built-in .dockerignore")
+        builtin_dockerignore_content = _load_data_file(".dockerignore")[1]
+        dockerignore_path.write_text(builtin_dockerignore_content, encoding="utf-8")
+        temp_dockerignore_created = True
+
+    delete_temp_file = False
+    try:
+        archs = ["linux/amd64", "linux/arm64"] if not single_arch else None
+        files_to_ignore = [".dockerignore"] if temp_dockerignore_created else []
+        version_string = _get_image_tag(files_to_ignore_as_dirty=files_to_ignore)
+
+        if debug:
+            suffix = "-debug"
+            target = "debug"
+            tag = "debug"
+        else:
+            suffix = ""
+            target = "runtime"
+            # Only tag as 'latest' if there are no tags later in history
+            tag = "latest" if not _has_tags_later_in_history() else None
+
+        version_tag = f"{version_string}{suffix}"
+        commit_tag = f"{_run_command(['git', 'rev-parse', '--short', 'HEAD'], capture_output=True).stdout.strip()}{'-dirty' if _get_dirty_files(ignore=files_to_ignore) else ''}{suffix}"
+        python_version = platform.python_version()
+        poetry_version = (
+            _run_command(["poetry", "--version"], capture_output=True)
+            .stdout.strip()
+            .split()[-1]
+        )[0:-1]
+
+        build_args = {
+            k: v
+            for k, v in {
+                "PYTHON_VERSION": python_version,
+                "POETRY_VERSION": poetry_version,
+                "PACKAGE_NAME": _get_package_name(use_underscores=True),
+                "AUTHORS": ",".join(
+                    [f"{name} <{email}>" for name, email in _get_authors()]
+                ),
+                "GIT_COMMIT": commit_tag,
+                "CUSTOM_ENTRYPOINT": os.getenv("CUSTOM_IMAGE_ENTRYPOINT"),
+            }.items()
+            if v is not None
+        }
+        tags_to_use = [t for t in (tag, version_tag, commit_tag) if t is not None]
+        LOGGER.info("Building image with tags: %s", ", ".join(tags_to_use))
+        build_cmd = (
+            [
+                "docker",
+                "build",
+                str(context_path),
+                "-f",
+                str(containerfile_path),
+                "--target",
+                target,
+            ]
+            + sum(
+                [
+                    ["--build-arg", f"{k}={v if v is not None else ''}"]
+                    for k, v in build_args.items()
+                ],
+                [],
+            )
+            + (["--platform", ",".join(archs)] if archs else [])
+            + (["--no-cache"] if no_cache else [])
+            + sum(
+                [["-t", f"{_get_package_name()}:{t}"] for t in tags_to_use],
+                [],
+            )
+        )
+        registry = os.environ.get(
+            "CONTAINER_REGISTRY_URL",
+            f"docker.io/{_get_dockerhub_username()}",
+        ).strip()
+        full_name = f"{registry}/{_get_package_name()}"
+        for t in tags_to_use:
+            build_cmd += ["-t", f"{full_name}:{t}"]
+
+        if plain:
+            build_cmd += ["--progress", "plain"]
+        _run_command(build_cmd)
+        delete_temp_file = True
+    finally:
+        if temp_file_path is not None and delete_temp_file:
+            try:
+                containerfile_path.unlink()
+            except FileNotFoundError:
+                pass
+        if temp_dockerignore_created:
+            try:
+                dockerignore_path.unlink()
+            except FileNotFoundError:
+                pass
+
+
+@tasks.script(tags=["containers", "build"])
+def build_image(
+    debug: bool = False,
+    no_cache: bool = False,
+    plain: bool = False,
+    single_arch: bool = False,
+) -> None:
+    """Build the container image for this project using the Containerfile template.
+
+    Args:
+        debug: Build the debug image.
+        no_cache: Do not use cache when building the image.
+        plain: Do not pretty-print output.
+        single_arch: Build images for a single architecture.
+    """
+    _build_image(
+        None,
+        _load_data_file("Containerfile")[1],
+        Path("."),
+        debug=debug,
+        no_cache=no_cache,
+        plain=plain,
+        single_arch=single_arch,
+    )
+
+
+@tasks.script(tags=["containers"])
+def run_container(tag: str = "latest") -> None:
+    """Run the Docker image as a container for this project.
+
+    Args:
+        tag: Image tag to run. Defaults to "latest".
+    """
+    _run_command(["docker", "run", "--rm", "-i", "-t", f"{_get_package_name()}:{tag}"])
+
+
+@tasks.script(tags=["containers", "packaging", "release"])
+def push_image(debug: bool = False) -> None:
+    """Push the Docker image for this project to the container registry.
+
+    Args:
+        debug: Push the debug image.
+    """
+
+    if debug:
+        suffix = "-debug"
+        tag = "debug"
+    else:
+        suffix = ""
+        # Only push 'latest' tag if there are no tags later in history
+        tag = "latest" if not _has_tags_later_in_history() else None
+    registry = os.environ.get(
+        "CONTAINER_REGISTRY_URL",
+        f"docker.io/{_get_dockerhub_username()}",
+    ).strip()
+    full_name = f"{registry}/{_get_package_name()}"
+    tags_to_push = [t for t in [tag, f"{_get_image_tag()}{suffix}"] if t is not None]
+    for t in tags_to_push:
+        full_tag = f"{full_name}:{t}"
+        LOGGER.info("Pushing image %s", full_tag)
+        _run_command(["docker", "push", full_tag])
+
+
+@tasks.script(task_name="publish-package", tags=["packaging"])
+def publish_package() -> None:
+    """Publish the package to the PyPI server."""
+    _run_command(["poetry", "publish"])
+
+
+@tasks.script(task_name="build-package", tags=["packaging", "build"])
+def build_package() -> None:
+    """Build the package (wheel and sdist)."""
+    _run_command(["poetry", "build"])
+
+
+@tasks.script(tags=["packaging"])
+def bump_version(
+    component: str = "patch",
+    *,
+    stage: str | None = None,
+) -> None:
+    """Bump the project version.
+
+    Args:
+        component: The version component to bump: "major", "minor", or "patch".".
+        stage: Optional pre-release stage to apply: "alpha", "beta", or "rc".
+    """
+    from dunamai import Style, Version
+
+    component = component.lower()
+    stage = stage.lower() if stage is not None else None
+
+    # Check if repository is dirty
+    if _run_command(
+        ["git", "status", "--porcelain"], capture_output=True
+    ).stdout.strip():
+        _fatal(
+            "Repository has uncommitted changes. Please commit or stash changes before bumping version."
+        )
+
+    # Try to get the latest tag; default to v0.0.0 if none exist
+    last_tag_result = _run_command(
+        ["git", "describe", "--tags", "--abbrev=0"],
+        capture_output=True,
+        acceptable_returncodes={0, 128},
+    )
+    last_tag = (
+        last_tag_result.stdout.strip() if last_tag_result.returncode == 0 else "v0.0.0"
+    )
+
+    # Check if current version equals the last tag, refuse to bump if so
+    current_version = _get_version()
+    # Normalize last tag by stripping leading 'v' if present
+    normalized_last_tag = last_tag[1:] if last_tag.startswith("v") else last_tag
+    if current_version == normalized_last_tag and last_tag != "v0.0.0":
+        _fatal(
+            "There have been no changes since the last version tag; cannot bump version as it would not change."
+        )
+
+    possible_components = ("major", "minor", "patch")
+    if component not in possible_components:
+        _fatal(
+            f'Invalid component "{component}". Must be one of: {"\n".join(possible_components)}'
+        )
+    component_index: "Literal[0, 1, 2]" = possible_components.index(component)
+
+    prerelease_options = {
+        "a": "alpha",
+        "alpha": "alpha",
+        "b": "beta",
+        "beta": "beta",
+        "rc": "rc",
+    }
+    normalized_stage = None
+    if stage is not None:
+        if stage not in prerelease_options:
+            _fatal(f'Invalid stage "{stage}". Must be one of: alpha, beta, rc')
+        normalized_stage = prerelease_options[stage]
+
+    # Bump version using dunamai
+    if last_tag == "v0.0.0":
+        # No real tags yet; bump from 0.0.0
+        base_version = Version.parse("0.0.0")
+        new_version = base_version.bump(component_index)
+    else:
+        new_version = Version.from_git().bump(component_index)
+
+    if normalized_stage is not None:
+        if new_version.stage != normalized_stage:
+            new_version.stage = normalized_stage
+            new_version.revision = 1
+        elif new_version.revision is None:
+            new_version.revision = 1
+
+    # Serialize without dirty flag for clean release tags
+    serialized = new_version.serialize(style=Style.Pep440)
+    LOGGER.info("Bumping version to %s", serialized)
+    _run_command(["git", "tag", f"v{serialized}"])
+
+
+def _build(
+    has_containers: bool,
+    debug: bool = False,
+    no_cache: bool = False,
+    plain: bool = False,
+    single_arch: bool = False,
+) -> None:
+    build_package()
+    if has_containers:
+        build_image(
+            debug=debug,
+            no_cache=no_cache,
+            plain=plain,
+            single_arch=single_arch,
+        )
+
+
+@tasks.script(
+    task_name="build",
+    tags=["packaging", "containers"],
+)
+def build_with_containers(
+    debug: bool = False,
+    no_cache: bool = False,
+    plain: bool = False,
+    single_arch: bool = False,
+) -> None:
+    """Build the project and its containers.
+
+    Args:
+        debug: Build the debug image.
+        no_cache: Do not use cache when building the image.
+        plain: Do not pretty-print output.
+        single_arch: Build images for a single architecture.
+    """
+    _build(
+        True,
+        debug=debug,
+        no_cache=no_cache,
+        plain=plain,
+        single_arch=single_arch,
+    )
+
+
+@tasks.script(task_name="build", tags=["packaging"])
+def build_without_containers() -> None:
+    """Build the project."""
+    _build(False)

common_python_tasks-0.0.1.dist-info/METADATA

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: common-python-tasks
+Version: 0.0.1
+Summary: Opinionated Poe the Poet tasks for Python package development.
+License-Expression: MIT
+License-File: LICENSE
+Author: Joseph Asbury
+Author-email: ci_sourcerer@yahoo.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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-Dist: autoflake (>=2.3.1,<3.0.0)
+Requires-Dist: black (>=25.11.0,<26.0.0)
+Requires-Dist: dunamai (>=1.25.0,<2.0.0)
+Requires-Dist: flake8 (>=7.3.0,<8.0.0)
+Requires-Dist: isort (>=7.0.0,<8.0.0)
+Requires-Dist: poethepoet-tasks (>=0.3.0,<0.4.0)
+Requires-Dist: pytest (>=9.0.1,<10.0.0)
+Requires-Dist: pytest-cov (>=7.0.0,<8.0.0)
+Requires-Dist: tomlkit (>=0.13.3,<0.14.0)
+Project-URL: Homepage, http://github.com/ci-sourcerer/common-python-tasks
+Project-URL: issues, http://github.com/ci-sourcerer/common-python-tasks/issues
+Project-URL: source, http://github.com/ci-sourcerer/common-python-tasks
+Description-Content-Type: text/markdown
+
+# Common Python tasks
+
+This package is a collection of (very) opinionated [Poe the Poet Python tasks](https://poethepoet.natn.io/guides/packaged_tasks.html) for common Python development workflows.
+
+## Quick start
+
+### Automated setup
+
+You can add `common-python-tasks` to a new project by using the handy automated installation script.
+
+```shell
+curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add-common-python-tasks.sh | TAGS_TO_INCLUDE="format lint test" sh
+```
+
+This will complete the following steps.
+
+1. Add the latest version of `common-python-tasks` to your `pyproject.toml` dependencies
+2. Configure Poe the Poet to include only the tasks with the specified tags
+3. Install the package using Poetry
+
+**Always review scripts before running them!** Even though I believe I write good software, it's best practice to verify any script you download from the Internet.
+
+### Manual setup
+
+1. Add `common-python-tasks` to your `pyproject.toml` and configure Poe the Poet to include the desired tasks
+
+    ```toml
+    [project]
+    name = "my-awesome-project"
+    version = "0.0.1"
+    dependencies = [
+        "common-python-tasks==0.0.1",  # Always pin to a specific version
+    ]
+
+    [tool.poe]
+    include_script = "common_python_tasks:tasks(include_tags=['format', 'lint', 'test'])"  # Include or exclude tasks by tags
+    ```
+
+2. Install the package
+
+    ```shell
+    poetry install
+    ```
+
+3. Run tasks
+
+    ```shell
+    poe format  # Format your code
+    poe lint    # Check code quality
+    poe test    # Run tests with coverage
+    ```
+
+## Available tasks
+
+Internal tasks are used by other tasks and are not meant to be run directly.
+
+| Task | Description | Tags |
+| - | - | - |
+| `build` | Build the project; also builds container images when the `containers` tag is included | packaging, containers |
+| `build-image` | Build a container image using the bundled Containerfile template | containers, build |
+| `build-package` | Build the package (wheel and sdist) | packaging, build |
+| `bump-version` | Bump project version and create a git tag | packaging |
+| `clean` | Remove build, cache, and coverage artifacts | clean |
+| `format` | Format code with autoflake, black, and isort | format |
+| `lint` | Run autoflake, black, isort checks, and flake8 linting | lint |
+| `publish-package` | Publish the package to PyPI via Poetry | packaging |
+| `push-image` | Push container images to the configured registry | containers, packaging, release |
+| `run-container` | Run the built container image with the selected tag | containers |
+| `test` | Run tests with pytest and generate coverage reports | test |
+
+## How it works
+
+### Prerequisites
+
+Your project must meet the following requirements.
+
+- Use Poetry for dependency management
+- Have a `pyproject.toml` file at the root
+- Have a package name (automatically inferred from `project.name` in `pyproject.toml`, or set via `PACKAGE_NAME` environment variable)
+
+### Configuration precedence
+
+Tasks that need configuration files (`pytest`, `coverage`, `flake8`, `isort`) follow this order of precedence.
+
+1. **`pyproject.toml` sections** - `[tool.pytest]`, `[tool.coverage]`, `[tool.isort]` take priority
+2. **Environment variables** - Override config paths (see [Environment Variables](#environment-variables))
+3. **Local config files** - `pytest.ini`, `.coveragerc`, `.flake8`, `.isort.cfg` in project root
+4. **Bundled defaults** - Sensible defaults included with this package, found in the [`src/common_python_tasks/data`](src/common_python_tasks/data) directory
+
+You can start with zero configuration and customize as needed.
+
+### Environment variables
+
+#### Configuration files
+
+The following environment variables configure the paths to configuration files.
+
+- `PYTEST_CONFIG` specifies the path to the pytest configuration file
+- `COVERAGE_RCFILE` specifies the path to the coverage configuration file  
+- `FLAKE8_CONFIG` specifies the path to the flake8 configuration file
+- `ISORT_CONFIG` specifies the path to the isort configuration file
+
+#### Package/Container settings
+
+The following environment variables configure package and container behavior.
+
+- `PACKAGE_NAME` overrides the package name (default is from `pyproject.toml`)
+- `POETRY_VERSION` overrides the Poetry version for container builds
+- `DOCKERHUB_USERNAME` specifies the Docker Hub username for image tagging (default is current local user)
+- `CONTAINER_REGISTRY_URL` specifies the registry URL (default is `docker.io/{username}`)
+- `CUSTOM_IMAGE_ENTRYPOINT` specifies a custom entrypoint script name for containers
+
+#### Debugging
+
+The following environment variable enables debugging output.
+
+- `COMMON_PYTHON_TASKS_LOG_LEVEL` should be set to `DEBUG` to see detailed configuration resolution
+
+### Usage examples
+
+You can include or exclude tasks by tags in your `pyproject.toml`
+
+#### Minimal setup
+
+```toml
+[project]
+name = "simple-cli-tool"
+version = "0.0.1"
+dependencies = ["common-python-tasks==0.0.1"]
+
+[tool.poe]
+include_script = "common_python_tasks:tasks(include_tags=['format', 'lint'])"
+```
+
+Available tasks: `format`, `lint`.
+
+#### Container-based project
+
+```toml
+[project]
+name = "containerized-app"
+version = "0.0.1"
+dependencies = ["common-python-tasks==0.0.1"]
+
+[tool.poe]
+include_script = "common_python_tasks:tasks(include_tags=['format', 'lint', 'test', 'containers'])"
+
+[tool.poe.env]
+DOCKERHUB_USERNAME = "myusername"
+PACKAGE_NAME = "containerized-app"
+```
+
+Available tasks: All tasks including `build-image` and `push-image`.
+
+#### Custom pytest configuration
+
+```toml
+[project]
+name = "custom-test-setup"
+dependencies = ["common-python-tasks==0.0.1"]
+dynamic = ["version"]
+
+[tool.poe]
+include_script = "common_python_tasks:tasks(include_tags=['test'])"
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "integration"]
+addopts = "-ra"
+```
+
+The `test` task will automatically use your `[tool.pytest.ini_options]` configuration.
+
+## Release workflow
+
+The `release` tag is used to identify tasks that are part of the release process. To perform a complete release, follow these steps.
+
+```shell
+# 1. Ensure all changes are committed
+git add .
+git commit -m "Prepare for release"  # You probably want a better commit message than this
+
+# 2. Bump the version (creates a git tag)
+poe bump-version patch  # or 'minor', 'major'; for pre-releases: poe bump-version patch --stage alpha
+
+# 3. Build the package
+poetry build
+
+# 4. Publish to PyPI
+poe publish-package
+
+# 5. (Optional) If using containers
+poe build-image
+poe push-image
+
+# 6. Push tags to remote
+git push --tags
+```
+
+## Troubleshooting
+
+### "No tests were collected"
+
+The `test` task exits with code 5 if no tests are found. You can address this in one of the following ways.
+
+- Add tests to your `tests/` directory
+- Exclude the `test` tag and simply do not run `poe test` with this configuration `include_script = "common_python_tasks:tasks(exclude_tags=['test', 'internal'])"`
+
+### Tasks not showing up with `poe --help`
+
+Check your `[tool.poe]` configuration in `pyproject.toml`. Make sure you're using `include_script`, not `includes`.
+
+```toml
+# Correct
+[tool.poe]
+include_script = "common_python_tasks:tasks(exclude_tags=['internal'])"
+
+# Incorrect
+[tool.poe]
+includes = "common_python_tasks:tasks"
+```
+
+### Version bump fails with "no changes since last tag"
+
+This is expected behavior. The `bump-version` task requires commits between the last tag and HEAD. You can resolve this in one of the following ways.
+
+- Make changes and commit them first
+- If you need to re-tag the same commit, delete the old tag (for example, `git tag -d v0.0.1`). This is not recommended. Versions should be immutable, and if you need to fix something, you should create a new patch version instead
+
+### Config files not being used
+
+Check the configuration precedence (see [How it works](#how-it-works)). Use debug logging to see which config is selected.
+
+```shell
+COMMON_PYTHON_TASKS_LOG_LEVEL=DEBUG poe test
+```
+
+### Container build fails with "unable to find package"
+
+Make sure your `pyproject.toml` contains the following.
+
+- A correct package name in `[project]`
+- A package location defined with this configuration `[tool.poetry] packages = [{ include = "your_package", from = "src" }]`
+
+## Design choices
+
+### Containerfile (see [src/common_python_tasks/data/Containerfile](src/common_python_tasks/data/Containerfile))
+
+The standard Python Containerfile incorporates several intentional design choices.
+
+- Multi-stage build: the build stage installs Poetry and builds a wheel while the runtime stage installs only the wheel to keep the final image slim and reproducible
+- Cache-aware installs mean pip and Poetry cache mounts speed up iterative builds without bloating the final image
+- Explicit inputs through build args (`PYTHON_VERSION`, `POETRY_VERSION`, `PACKAGE_NAME`, `AUTHORS`, `GIT_COMMIT`, `CUSTOM_ENTRYPOINT`) make image metadata and behavior predictable and auditable
+- Optional debug stage exports and installs the `debug` dependency group only when present without failing otherwise and is not part of the default final image
+- Stable package path creates symlinks to the installed package so entrypoints and consumers have a consistent `/pkg` and `/_$PACKAGE_NAME` path regardless of wheel layout, which ensures that the package can be reliably imported and executed from a known location, and allows for the less common use case of reading files directly from the package path
+- Safe entrypoint selection means the default entrypoint resolves the console script matching the package name while `CUSTOM_ENTRYPOINT` allows overriding at build time while keeping runtime behavior predictable
+- Minimal final image uses the slim Python base, cleans wheel artifacts and caches, and sets `runtime` as the explicit final target so the debug stage is opt-in
+
+## Notes
+
+- This project dogfoods itself - it uses `common-python-tasks` for its own development
+- Contributions welcome! Open an issue/discussion to discuss changes before submitting a PR. I do not claim to have all the answers, and you can help determine the future of low-code solutions for Python. I am very interested in your feedback as I don't want to work in a vacuum
+- Alpha status: expect breaking changes between minor versions until 1.0.0
+

common_python_tasks-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+common_python_tasks/__init__.py,sha256=jW_oC6mxA1rYTYICQZK-rwRmFTJRh5xU2KkY-LFff-E,383
+common_python_tasks/data/.coveragerc,sha256=8zXwDq18wIKQV4NtW2NJYpo3nxCO4LsAChyluYTUoJc,85
+common_python_tasks/data/.dockerignore,sha256=d2bDJajUbfSBcfG6WwfFaHZ-MfYKJaqGvLy6YbE5Ie4,76
+common_python_tasks/data/.flake8,sha256=PzH98ak-AKcENaBCzOhI2eHvLxrneklm7KaIWY9g4so,138
+common_python_tasks/data/.isort.cfg,sha256=P_hdco_n95VeXJjlUcXkChqNdct0SNDuk_n9ZaHzXPE,71
+common_python_tasks/data/Containerfile,sha256=RDmwzG75yiaYPDFEs3piRo9Bw1xyRJQ_QS6wdIMGD20,3173
+common_python_tasks/data/pytest.ini,sha256=RHak5QrLzKHvUBjFmaaiOYFrd_8YBRQubXEOT0NJfco,134
+common_python_tasks/tasks.py,sha256=XYieEM_GaJoV8Wv_klQbxMSotYNkuzNB5QoAELH0f9k,25545
+common_python_tasks-0.0.1.dist-info/METADATA,sha256=F0uVqBxJlei1G0fslzMZDDfPV4m7mWPWbfAsomJp6SU,11632
+common_python_tasks-0.0.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+common_python_tasks-0.0.1.dist-info/licenses/LICENSE,sha256=Z1X8kRRoTHQFP-gbmycMrLcfNn-2uUGmmIEH0vLbTZk,1070
+common_python_tasks-0.0.1.dist-info/RECORD,,

common_python_tasks-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

common_python_tasks-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joseph Asbury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.