common-python-tasks 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

common_python_tasks/data/fastapi/alembic.ini.j2

@@ -5,16 +5,15 @@ prepend_sys_path = .
 output_encoding = utf-8
 
 [post_write_hooks]
-hooks = black,isort
+hooks = ruff_check,ruff_format
 
-black.type = console_scripts
-black.entrypoint = black
+ruff_check.type = exec
+ruff_check.executable = ruff
+ruff_check.options = check --fix-only --select F401,I REVISION_SCRIPT_FILENAME
 
-autoflake.type = console_scripts
-autoflake.entrypoint = autoflake
-
-isort.type = console_scripts
-isort.entrypoint = isort
+ruff_format.type = exec
+ruff_format.executable = ruff
+ruff_format.options = format REVISION_SCRIPT_FILENAME
 
 # Logging configuration
 [loggers]

common_python_tasks/data/generic/ruff.toml

@@ -0,0 +1,6 @@
+line-length = 88
+extend-exclude = [".dist", ".poetry", "build"]
+
+[lint]
+select = ["E4", "E7", "E9", "F", "I", "W"]
+ignore = ["W191"]

common_python_tasks/git.py

@@ -185,7 +185,7 @@ def infer_bump_component_from_git_cliff() -> ReleaseComponent:
     try:
         current = Version.parse(current_version)
     except Exception:
-        utils.fatal("Unable to parse current project version: " f"{current_version!r}")
+        utils.fatal(f"Unable to parse current project version: {current_version!r}")
 
     def _parse_semver(version_value: str | Any) -> tuple[int, int, int]:
         if not isinstance(version_value, str):

common_python_tasks/github.py

@@ -434,7 +434,7 @@ def publish_github_release(
     release_name = release_name or tag_name
     release_body = body if body is not None else _changelog()
     if release_body is not None and _is_unreleased_placeholder(release_body):
-        LOGGER.info(
+        LOGGER.debug(
             "git-cliff returned an unreleased placeholder; using latest tagged release notes instead"
         )
         release_body = _latest_tagged_changelog()

common_python_tasks/project.py

@@ -10,7 +10,7 @@ from importlib import metadata
 from pathlib import Path
 from typing import Any, Sequence
 
-from packaging.specifiers import SpecifierSet
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
 from packaging.version import Version
 
 from . import utils
@@ -123,7 +123,7 @@ def get_package_manager() -> PackageManager:
     override = _find_package_manager_override()
     if override is None:
         package_manager, reason = _resolve_package_manager_auto()
-        LOGGER.info(
+        LOGGER.debug(
             "Using package manager backend: %s (%s)",
             package_manager,
             reason,
@@ -133,12 +133,12 @@ def get_package_manager() -> PackageManager:
     env_var, raw_value = override
     if raw_value not in PackageManager:
         utils.fatal(
-            f"Invalid {env_var} value {raw_value!r}. " "Use one of: poetry, uv, auto."
+            f"Invalid {env_var} value {raw_value!r}. Use one of: poetry, uv, auto."
         )
 
     if raw_value == PackageManager.AUTO:
         package_manager, reason = _resolve_package_manager_auto()
-        LOGGER.info(
+        LOGGER.debug(
             "Using package manager backend: %s (%s via %s=%s)",
             package_manager,
             reason,
@@ -149,7 +149,7 @@ def get_package_manager() -> PackageManager:
 
     package_manager = PackageManager(raw_value)
     _ensure_package_manager_available(package_manager)
-    LOGGER.info(
+    LOGGER.debug(
         "Using package manager backend: %s (from %s)",
         package_manager,
         env_var,
@@ -179,7 +179,9 @@ def get_package_manager_build_command(wheel_only: bool = False) -> list[str]:
     return command
 
 
-def get_package_manager_update_command(dependencies: Sequence[str] | None = None) -> list[str]:
+def get_package_manager_update_command(
+    dependencies: Sequence[str] | None = None,
+) -> list[str]:
     """Return the dependency update command for the selected package manager.
 
     Args:
@@ -427,7 +429,7 @@ def read_pyproject_toml() -> dict[str, Any]:
     return tomllib.loads(Path("pyproject.toml").read_text())
 
 
-BLACK_TARGET_PYTHON_MINORS = range(7, 17)
+RUFF_TARGET_PYTHON_MINORS = range(7, 16)
 
 
 def _specifier_supports_python_minor(specifier_set: SpecifierSet, minor: int) -> bool:
@@ -436,11 +438,11 @@ def _specifier_supports_python_minor(specifier_set: SpecifierSet, minor: int) ->
     )
 
 
-def get_black_target_version() -> str | None:
-    """Return the Black target-version token based on `project.requires-python`.
+def get_ruff_target_version() -> str | None:
+    """Return the Ruff target-version token based on `project.requires-python`.
 
     Returns:
-        The lowest supported Python version in Black format, such as
+        The lowest supported Python version in Ruff format, such as
         `py311`, or `None` when the project metadata is missing or invalid.
     """
     requires_python = read_pyproject_toml().get("project", {}).get("requires-python")
@@ -449,13 +451,13 @@ def get_black_target_version() -> str | None:
 
     try:
         specifier_set = SpecifierSet(requires_python)
-    except Exception:
+    except InvalidSpecifier:
         LOGGER.warning("Unable to parse requires-python specifier: %s", requires_python)
         return None
 
-    for minor in BLACK_TARGET_PYTHON_MINORS:
+    for minor in RUFF_TARGET_PYTHON_MINORS:
         if _specifier_supports_python_minor(specifier_set, minor):
-            return f"py3{minor:02d}"
+            return f"py3{minor}"
     return None
 
 
@@ -638,7 +640,7 @@ def get_project_version_from_poetry() -> str:
     parts = poetry_version_output.rsplit(" ", 1)
     if len(parts) != 2 or not parts[1].strip():
         utils.fatal(
-            "Unexpected poetry version output format: " f"{poetry_version_output!r}"
+            f"Unexpected poetry version output format: {poetry_version_output!r}"
         )
     return parts[1].strip()
 

common_python_tasks/tasks.py

@@ -7,9 +7,10 @@ from functools import partial, wraps
 from pathlib import Path
 from typing import Callable
 
-from common_python_tasks.utils import confirm
 from poethepoet_tasks import TaskCollection
 
+from common_python_tasks.utils import confirm
+
 
 class _ColoredFormatter(logging.Formatter):
     COLORS = {
@@ -246,149 +247,33 @@ def _update_release_changelog(release_tag: str, dry_run: bool = False) -> None:
     )
 
 
-@tasks.script(task_name="_black", tags=["format", "internal", "common"])
-def black() -> None:
-    """Run black formatting."""
-    from .project import get_black_target_version
-    from .utils import require_package, run_command
-
-    require_package("black")
-    target_version = get_black_target_version()
-    command = ["black", "--quiet"]
-    if target_version:
-        command.extend(["--target-version", target_version])
-    command.append(".")
-
-    run_command(command)
-
-
-@tasks.script(task_name="_isort", tags=["format", "internal", "common"])
-def isort() -> None:
-    """Run isort formatting."""
-    from .utils import get_config_path, require_package, run_command
-
-    require_package("isort")
-    isort_config_path = get_config_path(
-        "ISORT_CONFIG",
-        ".isort.cfg",
-        ".isort.cfg",
-        tool_name="isort",
-    )
+def _get_ruff_command(*args: str | Path) -> list[str | Path]:
+    from .project import get_ruff_target_version
+    from .utils import get_ruff_config_path
 
-    run_command(
-        [
-            "isort",
-            "--quiet",
-            ".",
-            "--settings-path" if isort_config_path else None,
-            isort_config_path,
+    config_path, is_bundled = get_ruff_config_path()
+    target_version = get_ruff_target_version() if is_bundled else None
+    return [
+        arg
+        for arg in [
+            "ruff",
+            *args,
+            "--config" if config_path else None,
+            config_path,
+            "--target-version" if target_version else None,
+            target_version,
         ]
-    )
-
-
-@tasks.script(task_name="_autoflake", tags=["format", "internal", "common"])
-def autoflake() -> None:
-    """Run autoflake to remove unused imports."""
-    from .utils import require_package, run_command
-
-    require_package("autoflake")
-    run_command(
-        [
-            "autoflake",
-            "--quiet",
-            "--remove-all-unused-imports",
-            "--recursive",
-            "-i",
-            Path("."),
-        ]
-    )
-
-
-@tasks.script(task_name="_black_check", tags=["lint", "internal", "common"])
-def black_check() -> None:
-    """Run black in check mode."""
-    from .project import get_black_target_version
-    from .utils import require_package, run_command
-
-    require_package("black")
-    target_version = get_black_target_version()
-    command = ["black", "--quiet"]
-    if target_version:
-        command.extend(["--target-version", target_version])
-    command.extend(["--diff", Path("."), "--check"])
-
-    run_command(command)
-
-
-@tasks.script(task_name="_isort_check", tags=["lint", "common"])
-def isort_check() -> None:
-    """Run isort linting."""
-    from .utils import get_config_path, require_package, run_command
-
-    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" if isort_config_path else None,
-            isort_config_path,
-        ]
-    )
-
-
-@tasks.script(task_name="_autoflake_check", tags=["lint", "internal", "common"])
-def autoflake_check() -> None:
-    """Run autoflake in check mode."""
-    from .utils import require_package, run_command
-
-    require_package("autoflake")
-    run_command(
-        [
-            "autoflake",
-            "--quiet",
-            "--remove-all-unused-imports",
-            "--recursive",
-            "-cd",
-            Path("."),
-        ]
-    )
-
-
-@tasks.script(task_name="_flake8_check", tags=["lint", "common"])
-def flake8_check() -> None:
-    """Run flake8 linting."""
-    from .utils import get_config_path, require_package, run_command
-
-    require_package("flake8")
-
-    flake8_config_path = get_config_path("FLAKE8_CONFIG", ".flake8", ".flake8")
-
-    run_command(
-        [
-            "flake8",
-            Path("."),
-            "--config" if flake8_config_path else None,
-            flake8_config_path,
-        ]
-    )
+        if arg is not None
+    ]
 
 
 @tasks.script(tags=["test", "common"])
 def test(*paths: str, quiet: bool = False) -> None:
-    """Run the test suite with coverage (if `pytest-cov` is installed).
+    """Run the test suite with coverage (if pytest-cov is installed).
 
 
     Args:
-        quiet: If `True`, run tests in a quieter mode.
+        quiet: Run tests in a quieter mode.
         *paths: Optional test file paths or directories to pass through to pytest.
     """
     from .utils import (
@@ -454,8 +339,7 @@ def clean(dist_only: bool = False) -> None:
     """Clean up temporary files and directories.
 
     Args:
-        dist_only: If `True`, only clean the `dist` directory (and related build
-            artifacts)
+        dist_only: Only clean the dist directory (and related build artifacts)
     """
     from .utils import remove_path
 
@@ -477,33 +361,30 @@ def clean(dist_only: bool = False) -> None:
 
 @tasks.script(task_name="format", tags=["format", "common"])
 def format_all() -> None:
-    """Format Python code with autoflake, black, and isort."""
-    from .utils import run_available_tools
+    """Fix import issues and format Python code with Ruff."""
+    from .utils import require_package, run_command
 
-    run_available_tools(
-        [
-            (autoflake, "autoflake"),
-            (black, "black"),
-            (isort, "isort"),
-        ],
-        "No formatting tools are installed. Install one or more of: autoflake, black, isort",
+    require_package("ruff")
+    run_command(
+        _get_ruff_command(
+            "check",
+            "--fix-only",
+            "--select",
+            "F401,I",
+            Path("."),
+        )
     )
+    run_command(_get_ruff_command("format", Path(".")))
 
 
 @tasks.script(task_name="lint", tags=["lint", "common"])
 def lint_all() -> None:
-    """Lint Python code with autoflake, black, isort, and flake8."""
-    from .utils import run_available_tools
+    """Check Python lint and formatting with Ruff."""
+    from .utils import require_package, run_command
 
-    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",
-    )
+    require_package("ruff")
+    run_command(_get_ruff_command("check", Path(".")))
+    run_command(_get_ruff_command("format", "--check", Path(".")))
 
 
 @tasks.script(tags=["containers", "build"])
@@ -523,15 +404,15 @@ def build_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_args: Additional build arguments as repeated `KEY=VALUE` values.
-            Overrides `CONTAINER_BUILD_ARGS` if provided.
+        build_args: Additional build arguments as repeated KEY=VALUE values.
+            Overrides CONTAINER_BUILD_ARGS if provided.
         container_env: Builder-stage environment declarations as repeated
-            `KEY=VALUE` values.
+            KEY=VALUE values.
         container_envfile: Optional repeated list of files containing builder-stage
             environment declarations.
 
-    Precedence for container env declarations is: `.containerenv`, `container_envfile`, `CONTAINER_ENV`, then `container_env`.
-    All supported sources are stacked in that order.
+    Precedence for container env declarations is: .containerenv, container_envfile,
+    CONTAINER_ENV, then container_env. All supported sources are stacked in that order.
     """
     from .docker import build_image as _build_image
     from .docker import (
@@ -735,8 +616,8 @@ def build_deps_image_task(
         no_cache: Do not use cache when building the deps image.
         plain: Do not pretty-print output.
         single_arch: Build images for a single architecture.
-        build_args: Additional build arguments as repeated `KEY=VALUE` values.
-            Overrides `CONTAINER_BUILD_ARGS` if provided.
+        build_args: Additional build arguments as repeated KEY=VALUE values.
+            Overrides CONTAINER_BUILD_ARGS if provided.
     """
     from .docker import build_deps_image
     from .env import (
@@ -787,19 +668,18 @@ def run_container(
 ) -> None:
     """Run the Docker image as a container for this project.
 
-    By default (when `tag` is `None`) this will run the most-recently-built tag for
-    the project's image.
+    By default, this will run the most-recently-built tag for the project's image.
 
     Args:
-        tag: Image tag to run. If `None`, use the most-recently-built tag.
+        tag: Image tag to run. Default: Use the most-recently-built tag.
         entrypoint: Optional entrypoint override.
         command: Optional command to pass to the entrypoint.
         root: Whether to run as root (only relevant with a shell entrypoint).
         echo_env: Whether to prepend an env dump to the command.
-        env: Repeated `KEY=VALUE` or `KEY` values to pass with `-e`.
-        envfile: Repeated envfile paths to pass with `--env-file`.
-        privileged: Whether to run the container with `--privileged`.
-        volumes: Repeated volume mounts to pass with `-v`.
+        env: Repeated KEY=VALUE or KEY values to pass with -e.
+        envfile: Repeated envfile paths to pass with --env-file.
+        privileged: Whether to run the container with --privileged.
+        volumes: Repeated volume mounts to pass with -v.
     """
     from .utils import (
         compose_image_name,
@@ -970,7 +850,7 @@ def publish_package(
     """Publish the package to the PyPI server.
 
     Args:
-        build_first: If `True`, build the package before publishing.
+        build_first: Build the package before publishing.
         repository: Optional configured repository name to publish to.
         repository_url: Optional repository upload URL to publish to.
     """
@@ -1016,7 +896,7 @@ def publish_github_release(
         release_name or os.getenv("GITHUB_RELEASE_NAME") or resolved_tag_name
     )
     resolved_body = body or os.getenv("GITHUB_RELEASE_BODY")
-    # Poe supplies `[]` when an optional repeated CLI argument is omitted.
+    # Poe supplies an empty list when an optional repeated CLI argument is omitted.
     asset_paths = get_github_release_asset_paths(assets or None)
 
     return publish_github_release_helper(
@@ -1159,13 +1039,13 @@ def update_dependencies(
     Args:
         *dependencies: Optional dependency names to update. When omitted, update
             all dependencies.
-        branch: If `True`, create a dependency update branch after updating.
+        branch: Create a dependency update branch after updating.
         branch_name: Optional branch name to use instead of generating one.
-        commit: If `True`, commit the dependency update files.
-        pr: If `True`, create and push a branch, commit the changes, and open
-            a GitHub pull request.
-        draft: If `True`, create the pull request as a draft.
-        run_tests: If `True`, run the test task before committing.
+        commit: Commit the dependency update files.
+        pr: Create and push a branch, commit the changes, and open a GitHub pull
+            request.
+        draft: Create the pull request as a draft.
+        run_tests: Run the test task before committing.
     """
     from .github import create_pull_request
     from .project import get_package_manager_update_command
@@ -1252,11 +1132,11 @@ def bump_version(
     """Bump the project version.
 
     Args:
-        component: The version component to bump: `major`, `minor`, `patch`, or
-            `auto` to infer the bump from git history using git-cliff.
-        stage: Optional pre-release stage to apply: `alpha`, `beta`, or `rc`.
-        dry_run: If `True`, print what would happen without making changes.
-        allow_dirty: If `True`, allow version bumping with uncommitted changes.
+        component: The version component to bump: major, minor, patch, or auto to
+            infer the bump from git history using git-cliff.
+        stage: Optional pre-release stage to apply: alpha, beta, or rc.
+        dry_run: Print what would happen without making changes.
+        allow_dirty: Allow version bumping with uncommitted changes.
 
     Returns:
         The new version string that was/would be set.
@@ -1479,17 +1359,17 @@ def release(
     """Run a full release flow for package and containers.
 
     Args:
-        component: The version component to bump: `major`, `minor`, or `patch`.
-        stage: Optional pre-release stage to apply: `alpha`, `beta`, or `rc`.
-        dry_run: If `True`, only perform a dry-run version bump.
+        component: The version component to bump: major, minor, or patch.
+        stage: Optional pre-release stage to apply: alpha, beta, or rc.
+        dry_run: Only perform a dry-run version bump.
         debug: Build/push debug container image tags when releasing containers.
         no_cache: Do not use cache when building container images.
         plain: Do not pretty-print container build output.
         single_arch: Build container image for a single architecture.
         build_args: Additional build arguments for the Docker build as repeated
-            `KEY=VALUE` values.
+            KEY=VALUE values.
         container_env: Inline container environment variables as repeated
-            `KEY=VALUE` values.
+            KEY=VALUE values.
         container_envfile: Repeated list of container environment files.
         assets: Optional repeated list of release asset patterns or paths.
         repository: Optional configured repository name to publish to.
@@ -1531,9 +1411,9 @@ def release_without_containers(
     """Run a full release flow for package artifacts without container publishing.
 
     Args:
-        component: The version component to bump: `major`, `minor`, or `patch`.
-        stage: Optional pre-release stage to apply: `alpha`, `beta`, or `rc`.
-        dry_run: If `True`, only perform a dry-run version bump.
+        component: The version component to bump: major, minor, or patch.
+        stage: Optional pre-release stage to apply: alpha, beta, or rc.
+        dry_run: Only perform a dry-run version bump.
         assets: Optional repeated list of release asset patterns or paths.
         repository: Optional configured repository name to publish to.
         repository_url: Optional repository upload URL to publish to.
@@ -1615,9 +1495,9 @@ def build_with_containers(
         plain: Do not pretty-print output.
         single_arch: Build images for a single architecture.
         build_args: Additional build arguments for the Docker build as repeated
-            `KEY=VALUE` values.
-        container_env: Inline container environment variables as repeated
-            `KEY=VALUE` values.
+            KEY=VALUE values.
+        container_env: Inline container environment variables as repeated KEY=VALUE
+            values.
         container_envfile: Repeated list of container environment files.
     """
 
@@ -1653,15 +1533,15 @@ def fastapi_stack_up(
     """Bring up the development stack for the application.
 
     Args:
-        debug: Enable debug mode (auto-loads all `*-debug.yml` compose files).
+        debug: Enable debug mode (auto-loads all *-debug.yml compose files).
         no_cache: Do not use cache when building the image.
         detach: Run the stack in detached mode.
         services: Optional repeated list of services to start. If not provided,
             all services will be started.
         build_args: Additional build arguments for the Docker build as repeated
-            `KEY=VALUE` values.
-        container_env: Inline container environment variables as repeated
-            `KEY=VALUE` values.
+            KEY=VALUE values.
+        container_env: Inline container environment variables as repeated KEY=VALUE
+            values.
         container_envfile: Repeated list of container environment files.
     """
     from .docker_compose import (
@@ -1741,8 +1621,8 @@ def fastapi_stack_up(
     )
     api_port = int(compose_env["API_PORT"])
 
-    # When watch mode is active, `docker compose` needs the Dockerfile present
-    # in the project directory so that watch-triggered rebuilds can find it.
+    # When watch mode is active, docker compose needs the Dockerfile present in the
+    # project directory so that watch-triggered rebuilds can find it.
     watch_mode = debug and not detach
     local_dockerfile = Path("Dockerfile")
     wrote_dockerfile = False
@@ -1763,7 +1643,8 @@ def fastapi_stack_up(
     try:
         LOGGER.info("Building and starting the application stack...")
         LOGGER.info(
-            "Starting application. Once the stack is up, check the API docs at http://localhost:%i/api/docs",
+            "Starting application. Once the stack is up, check the API docs at "
+            "http://localhost:%i/api/docs",
             api_port,
         )
         if detach:
@@ -1929,15 +1810,15 @@ def container_shell(
     """Run the debug image with an interactive shell.
 
     Args:
-        tag: Image tag to use. If `None`, use the most-recently-built tag.
-        shell: Preferred shell name or path. If `None`, use the first available from
-            `zsh`, `fish`, `ksh`, `bash`, and `sh`.
+        tag: Image tag to use. Default: Use the most-recently-built tag.
+        shell: Preferred shell name or path. Default: Use the first available from zsh,
+            fish, ksh, bash, and sh.
         root: Whether to run the shell as root.
         no_echo_env: Whether to suppress printing environment variables on startup for debugging.
-        env: Repeated `KEY=VALUE` or `KEY` values to pass with `-e`.
-        envfile: Repeated envfile paths to pass with `--env-file`.
-        privileged: Whether to run the container with `--privileged`.
-        volumes: Repeated volume mounts to pass with `-v`.
+        env: Repeated KEY=VALUE or KEY values to pass with -e.
+        envfile: Repeated envfile paths to pass with --env-file.
+        privileged: Whether to run the container with --privileged.
+        volumes: Repeated volume mounts to pass with -v.
     """
     from shlex import quote