common-python-tasks 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

common_python_tasks/data/generic/.dockerignore

@@ -6,5 +6,3 @@
 !LICENSE
 
 !src
-
-!.git

common_python_tasks/data/generic/Dockerfile.j2

@@ -13,14 +13,18 @@ FROM python:${PYTHON_VERSION} AS builder
 ARG POETRY_VERSION
 ARG POETRY_DYNAMIC_VERSIONING_PLUGIN_VERSION
 ARG POETRY_PLUGIN_EXPORT_VERSION
-ARG TOMLKIT_VERSION
+ARG PACKAGE_VERSION
+
+# Bypass VCS-based version detection: use the host-computed version directly.
+# This avoids requiring a .git directory in the build context and prevents
+# false dirty-version detection from a partial working tree.
+ENV POETRY_DYNAMIC_VERSIONING_BYPASS=${PACKAGE_VERSION}
 
 # Install Poetry and required Poetry plugins for build
 RUN --mount=type=cache,target=/root/.cache/pip,id=pip-cache{{ CACHE_ID_SUFFIX }} pip install --root-user-action=ignore \
     "poetry==$POETRY_VERSION" \
     "poetry-dynamic-versioning[plugin]==$POETRY_DYNAMIC_VERSIONING_PLUGIN_VERSION" \
-    "poetry-plugin-export==$POETRY_PLUGIN_EXPORT_VERSION" \
-    "tomlkit==$TOMLKIT_VERSION"
+    "poetry-plugin-export==$POETRY_PLUGIN_EXPORT_VERSION"
 
 # Build package
 WORKDIR /tmp/build

common_python_tasks/docker.py

@@ -152,35 +152,60 @@ def prune_images_keep(
 
     retain_count = int(keep) + 1
 
-    res = utils.run_command(
-        [
-            "docker",
-            "image",
-            "ls",
-            "--format",
-            "{{.Repository}}:{{.Tag}}",
-            "--filter",
-            f"reference={full_name}:*",
-        ],
-        capture_output=True,
-        acceptable_returncodes={0, 1},
+    def _list_images_for_reference(reference: str) -> list[str]:
+        res = utils.run_command(
+            [
+                "docker",
+                "image",
+                "ls",
+                "--format",
+                "{{.Repository}}:{{.Tag}}",
+                "--filter",
+                f"reference={reference}:*",
+            ],
+            capture_output=True,
+            acceptable_returncodes={0, 1},
+        )
+        if res.returncode != 0:
+            LOGGER.warning("Failed to list images for pruning: %s", reference)
+            return []
+
+        return [
+            line.strip()
+            for line in res.stdout.splitlines()
+            if line.strip() and not line.strip().startswith("<none>")
+        ]
+
+    parsed_full_name = utils.parse_image_reference(full_name)
+    short_reference = utils.compose_image_name(package_name, fully_qualified=False)
+    full_reference = utils.compose_image_name(
+        package_name,
+        registry=parsed_full_name["registry"],
+        namespace=parsed_full_name["namespace"],
     )
-    if res.returncode != 0:
-        LOGGER.exception("Failed to list images for pruning: %s", full_name)
-        return
 
-    lines = [
-        line.strip()
-        for line in res.stdout.splitlines()
-        if line.strip() and not line.strip().startswith("<none>")
+    lines = _list_images_for_reference(full_reference)
+    lines += [
+        line
+        for line in _list_images_for_reference(short_reference)
+        if line not in lines
     ]
-    tags_in_order = []
+
+    tags_in_order: list[str] = []
+    seen_tags: set[str] = set()
     for entry in lines:
-        if ":" not in entry:
+        try:
+            parsed_entry = utils.parse_image_reference(entry)
+        except ValueError:
             continue
-        repo, tag = entry.rsplit(":", 1)
-        if entry.startswith(full_name) or repo.endswith(package_name):
-            tags_in_order.append(tag)
+
+        if (
+            parsed_entry["repository"] == package_name
+            and parsed_entry["tag"]
+            and parsed_entry["tag"] not in seen_tags
+        ):
+            tags_in_order.append(parsed_entry["tag"])
+            seen_tags.add(parsed_entry["tag"])
 
     candidates = [t for t in tags_in_order if t not in protect_tags]
     if len(candidates) <= retain_count:
@@ -188,7 +213,18 @@ def prune_images_keep(
 
     to_delete = candidates[retain_count:]
     for tag in to_delete:
-        for img in (f"{package_name}:{tag}", f"{full_name}:{tag}"):
+        short_image = utils.compose_image_name(
+            package_name,
+            tag=tag,
+            fully_qualified=False,
+        )
+        full_image = utils.compose_image_name(
+            package_name,
+            tag=tag,
+            registry=parsed_full_name["registry"],
+            namespace=parsed_full_name["namespace"],
+        )
+        for img in (short_image, full_image):
             try:
                 LOGGER.info("Pruning image %s", img)
                 utils.run_command(["docker", "rmi", img], acceptable_returncodes={0, 1})
@@ -369,6 +405,7 @@ def build_image(
     try:
         archs = _resolve_archs(single_arch)
         files_to_ignore = [Path(".dockerignore")] if temp_dockerignore_created else []
+        package_version = git.get_version(ignore=files_to_ignore)
         version_string = git.get_image_tag(ignore=files_to_ignore)
 
         dockerfile_source = (
@@ -400,7 +437,19 @@ def build_image(
             tag = BuildTag.LATEST if not git.has_tags_later_in_history() else None
 
         version_tag = f"{version_string}{suffix}"
-        commit_tag = f"{utils.run_command(['git', 'rev-parse', '--short', 'HEAD'], capture_output=True).stdout.strip()}{'-dirty' if git.get_dirty_files(ignore=files_to_ignore) else ''}{suffix}"
+        if git.git_available():
+            commit_hash = utils.run_command(
+                ["git", "rev-parse", "--short", "HEAD"],
+                capture_output=True,
+                acceptable_returncodes={0},
+            ).stdout.strip()
+            dirty_suffix = (
+                "-dirty" if git.get_dirty_files(ignore=files_to_ignore) else ""
+            )
+            commit_tag = f"{commit_hash}{dirty_suffix}{suffix}"
+        else:
+            commit_tag = version_tag
+
         python_version = platform.python_version()
         poetry_version = project.get_poetry_version()
 
@@ -414,7 +463,7 @@ def build_image(
                 "POETRY_PLUGIN_EXPORT_VERSION": project.get_installed_requirement_version(
                     "poetry-plugin-export"
                 ),
-                "TOMLKIT_VERSION": project.get_installed_requirement_version("tomlkit"),
+                "PACKAGE_VERSION": package_version,
                 "PACKAGE_NAME": utils.get_package_name(use_underscores=True),
                 "AUTHORS": ",".join(
                     [f"{name} <{email}>" for name, email in project.get_authors()]
@@ -432,14 +481,27 @@ def build_image(
             image_name if image_name is not None else utils.get_package_name()
         )
         orig_full_name = utils.get_full_image_name()
-        if image_name is None:
-            image_full_name = orig_full_name
-        else:
-            if "/" in orig_full_name:
-                prefix = orig_full_name.rsplit("/", 1)[0]
-                image_full_name = f"{prefix}/{image_name}"
-            else:
-                image_full_name = image_name
+
+        parsed_full_name = utils.parse_image_reference(orig_full_name)
+        short_tags = [
+            utils.compose_image_name(image_short_name, tag=t, fully_qualified=False)
+            for t in tags_to_use
+        ]
+        full_tags = [
+            utils.compose_image_name(
+                image_short_name,
+                tag=t,
+                registry=parsed_full_name["registry"],
+                namespace=parsed_full_name["namespace"],
+            )
+            for t in tags_to_use
+        ]
+
+        all_tags: list[str] = []
+        for resolved_tag in [*short_tags, *full_tags]:
+            if resolved_tag not in all_tags:
+                all_tags.append(resolved_tag)
+
         build_cmd = _build_docker_build_command(
             context_path=context_path,
             dockerfile_path=dockerfile_path,
@@ -448,10 +510,7 @@ def build_image(
             no_cache=no_cache,
             plain=plain,
             target=None if omit_target else target,
-            tags=[
-                *[f"{image_short_name}:{t}" for t in tags_to_use],
-                *[f"{image_full_name}:{t}" for t in tags_to_use],
-            ],
+            tags=all_tags,
         )
         utils.run_command(build_cmd)
         delete_temp_file = True

common_python_tasks/docker_compose.py

@@ -375,6 +375,8 @@ def load_compose_files(
         cleaned up **after** `docker compose` down`.
     """
 
+    from .env import split_colon_delimited_values
+
     compose_files_env = os.getenv("COMPOSE_FILE")
     if compose_files_env:
         LOGGER.debug(
@@ -382,14 +384,14 @@ def load_compose_files(
             compose_files_env,
         )
         return (
-            [Path(f.strip()) for f in compose_files_env.split(":") if f.strip()],
+            [Path(path) for path in split_colon_delimited_values(compose_files_env)],
             [],
             [],
         )
 
-    compose_type = os.environ["COMPOSE_TYPE"]
+    compose_type = get_compose_type()
     compose_addons_str = os.getenv("COMPOSE_ADDONS", "")
-    compose_addons = [a.strip() for a in compose_addons_str.split(":") if a.strip()]
+    compose_addons = split_colon_delimited_values(compose_addons_str)
 
     LOGGER.debug(
         "Loading compose files for type '%s' with addons: %s%s",
@@ -459,7 +461,7 @@ def load_compose_files(
 
     overlay_files_str = os.getenv("COMPOSE_OVERLAY_FILES", "")
     if overlay_files_str:
-        overlay_files = [f.strip() for f in overlay_files_str.split(":") if f.strip()]
+        overlay_files = split_colon_delimited_values(overlay_files_str)
         LOGGER.debug("Adding overlay compose files: %s", overlay_files)
         for overlay_file in overlay_files:
             files_and_cleanups.append((Path(overlay_file), False))
@@ -497,6 +499,7 @@ def run_docker_compose_command(
     *args: str | None,
     compose_files: list[Path],
     compose_env: dict[str, str],
+    tasks: TaskCollection,
 ) -> None:
     """Run `docker compose` with standard file and env-file arguments.
 
@@ -512,7 +515,7 @@ def run_docker_compose_command(
 
     utils.run_command(
         [
-            *compose_cmd_prefix(compose_files),
+            *compose_cmd_prefix(compose_files, tasks),
             *[arg for arg in args if arg is not None],
         ],
         env=compose_env,

common_python_tasks/env.py

@@ -1,8 +1,8 @@
 import logging
 import os
 import secrets
+import shlex
 from pathlib import Path
-from shlex import split as shlex_split
 
 from . import utils
 
@@ -14,6 +14,7 @@ TRUTHY_VALUES = {
     "yes",
     "on",
     "enabled",
+    "enable",
     "y",
     "t",
 }
@@ -75,7 +76,7 @@ def parse_container_extensions() -> list[dict]:
     exts: list[dict] = []
     files_raw = os.getenv("CONTAINER_EXTENSION_FILES")
     if files_raw:
-        for part in [p.strip() for p in files_raw.split(":") if p.strip()]:
+        for part in split_colon_delimited_values(files_raw):
             pth = Path(part)
             exts.append(
                 {
@@ -91,7 +92,7 @@ def parse_container_extensions() -> list[dict]:
             )
     bundles_raw = os.getenv("CONTAINER_EXTENSIONS")
     if bundles_raw:
-        for part in (p.strip() for p in bundles_raw.split(":")):
+        for part in split_colon_delimited_values(bundles_raw):
             if not part:
                 continue
             if "=" in part:
@@ -180,24 +181,64 @@ def load_container_env_file(path: str | None = None) -> str | None:
     return container_env if container_env else None
 
 
-def split_colon_delimited_values(value: str) -> list[str]:
-    """Split a colon-delimited string while preserving quoted substrings.
+def split_delimited_values(
+    value: str,
+    separators: str = ":",
+    allow_whitespace: bool = False,
+) -> list[str]:
+    """Split a delimited string while preserving quoted substrings.
 
     Args:
-        value: The colon-delimited string to split.
+        value: The string to split.
+        separators: Explicit separator characters to use.
+        allow_whitespace: Treat whitespace as additional separators.
 
     Returns:
-        A list of strings representing the split values.
+        A list of strings representing the parsed tokens.
     """
     if not value or not value.strip():
         return []
 
-    try:
-        tokens = shlex_split(value.replace(":", " "), comments=True)
-    except ValueError as exc:
-        raise ValueError(f"Unable to parse colon-delimited values: {exc}") from exc
+    lexer = shlex.shlex(value, posix=True)
+    lexer.whitespace = separators + (" \t\r\n" if allow_whitespace else "")
+    lexer.whitespace_split = True
+    lexer.commenters = "#"
+    return [token for token in lexer if token.strip()]
 
-    return [token for token in tokens if token.strip()]
+
+def split_colon_delimited_values(value: str) -> list[str]:
+    """Split a colon- or whitespace-delimited string while preserving quoted substrings."""
+    return split_delimited_values(value, separators=":", allow_whitespace=True)
+
+
+def split_colon_or_whitespace_delimited_values(value: str) -> list[str]:
+    """Split a colon- or whitespace-delimited string while preserving quoted substrings."""
+    return split_colon_delimited_values(value)
+
+
+def parse_container_build_args(
+    cli_build_args: list[str] | None,
+    env_build_args: str | None,
+) -> dict[str, str] | None:
+    """Parse container build args from CLI or environment input."""
+    if cli_build_args is not None:
+        build_arg_tokens = [
+            token.strip() for token in cli_build_args if token and token.strip()
+        ]
+    elif env_build_args:
+        build_arg_tokens = split_colon_delimited_values(env_build_args)
+    else:
+        return None
+
+    parsed_build_args: dict[str, str] = {}
+    for token in build_arg_tokens:
+        if "=" not in token:
+            LOGGER.warning("Ignoring invalid build-arg token: %s", token)
+            continue
+        key, value = token.split("=", 1)
+        parsed_build_args[key.strip()] = value.strip()
+
+    return parsed_build_args or None
 
 
 def parse_container_env_tokens(value: str | list[str] | None) -> list[str]:

common_python_tasks/git.py

@@ -220,6 +220,20 @@ def infer_bump_component_from_git_cliff() -> ReleaseComponent:
     )
 
 
+def git_available() -> bool:
+    """Return `True` if Git is installed and the current directory is a repository."""
+
+    if shutil.which("git") is None:
+        return False
+
+    result = utils.run_command(
+        ["git", "rev-parse", "--is-inside-work-tree"],
+        capture_output=True,
+        acceptable_returncodes={0, 1, 128},
+    )
+    return result.returncode == 0
+
+
 def get_dirty_files(ignore: list[Path] | None = None) -> list[Path]:
     """Get dirty git files excluding any specified paths.
 
@@ -233,6 +247,9 @@ def get_dirty_files(ignore: list[Path] | None = None) -> list[Path]:
     if ignore is None:
         ignore = []
 
+    if not git_available():
+        return []
+
     ignore_set = {Path(p) for p in ignore}
 
     return [
@@ -260,6 +277,10 @@ def get_version(ignore: list[Path] | None = None) -> str:
     if ignore is None:
         ignore = []
 
+    if not git_available():
+        LOGGER.warning("Git is unavailable. Falling back to placeholder version 0.0.0.")
+        return "0.0.0"
+
     dirty_files = get_dirty_files(ignore=ignore)
     LOGGER.debug("Dirty files: %s", dirty_files)
 
@@ -296,6 +317,9 @@ def has_tags_later_in_history() -> bool:
         `True` if tags are later in history, else `False`.
     """
 
+    if not git_available():
+        return False
+
     result = utils.run_command(
         ["git", "tag"],
         capture_output=True,

common_python_tasks/github.py

@@ -3,12 +3,11 @@ import logging
 import mimetypes
 import os
 import re
-import urllib.error
-import urllib.parse
-import urllib.request
 from pathlib import Path
 from typing import Any, Literal
 
+import requests
+
 from . import utils
 from .env import env_truthy
 from .utils import changelog as _changelog
@@ -210,21 +209,6 @@ class GitHubClient:
     def _build_url(self, path: str, endpoint: GitHubEndpoint = "api") -> str:
         return f"{self._get_base_url(endpoint)}/repos/{self.repository}{path}"
 
-    def _build_request(
-        self,
-        method: str,
-        path: str,
-        payload: bytes | None = None,
-        endpoint: GitHubEndpoint = "api",
-        content_type: str | None = None,
-    ) -> urllib.request.Request:
-        return urllib.request.Request(
-            self._build_url(path, endpoint=endpoint),
-            data=payload,
-            method=method,
-            headers=self._build_headers(content_type),
-        )
-
     def _request(
         self,
         method: str,
@@ -244,25 +228,22 @@ class GitHubClient:
                 )
             return None
 
-        request = self._build_request(
-            method,
-            path,
-            payload=payload,
-            endpoint=endpoint,
-            content_type=content_type,
+        response = requests.request(
+            method=method,
+            url=self._build_url(path, endpoint=endpoint),
+            data=payload,
+            headers=self._build_headers(content_type),
+            timeout=30,
         )
 
-        try:
-            with urllib.request.urlopen(request) as response:
-                body = response.read().decode("utf-8").strip()
-        except urllib.error.HTTPError:
-            if allow_404:
-                return None
-            raise
+        if allow_404 and response.status_code == 404:
+            return None
+        response.raise_for_status()
 
+        body = response.text.strip()
         if not body:
             return None
-        return json.loads(body)
+        return response.json()
 
     def api_request(
         self,
@@ -395,7 +376,7 @@ def publish_github_release(
     }
 
     client = GitHubClient(repository=repository, token=token)
-    encoded_tag_name = urllib.parse.quote(tag_name, safe="")
+    encoded_tag_name = requests.utils.quote(tag_name, safe="")
     existing_release = client.api_request(
         "GET",
         f"/releases/tags/{encoded_tag_name}",
@@ -471,21 +452,19 @@ def get_github_release_asset_paths(
     Returns:
         A sorted list of existing asset paths.
     """
+    from .env import split_colon_delimited_values
+
     if asset_sources is not None:
         explicit_assets = True
         if isinstance(asset_sources, list):
             source_items = [item.strip() for item in asset_sources if item.strip()]
         else:
-            source_items = [
-                item.strip() for item in asset_sources.split(":") if item.strip()
-            ]
+            source_items = split_colon_delimited_values(asset_sources)
     else:
         env_asset_sources = os.getenv("GITHUB_RELEASE_ASSETS")
         explicit_assets = bool(env_asset_sources)
         if env_asset_sources:
-            source_items = [
-                item.strip() for item in env_asset_sources.split(":") if item.strip()
-            ]
+            source_items = split_colon_delimited_values(env_asset_sources)
         else:
             source_items = ["dist/*"]
 
@@ -563,7 +542,7 @@ def upload_github_release_asset(
     content_type = content_type or "application/octet-stream"
     return github_upload_request(
         "POST",
-        f"/releases/{release_id}/assets?name={urllib.parse.quote(asset_path.name, safe='')}",
+        f"/releases/{release_id}/assets?name={requests.utils.quote(asset_path.name, safe='')}",
         payload=asset_path.read_bytes(),
         content_type=content_type,
     )

common_python_tasks/project.py

@@ -7,6 +7,9 @@ from importlib import metadata
 from pathlib import Path
 from typing import Any
 
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+
 from . import utils
 
 LOGGER = logging.getLogger(__name__)
@@ -180,6 +183,32 @@ def read_pyproject_toml() -> dict[str, Any]:
     return tomllib.loads(Path("pyproject.toml").read_text())
 
 
+BLACK_TARGET_PYTHON_CANDIDATES = [Version(f"3.{minor}") for minor in range(7, 17)]
+
+
+def get_black_target_version() -> str | None:
+    """Return the Black target-version token based on `project.requires-python`.
+
+    Returns:
+        The lowest supported Python version in Black format, such as
+        `py311`, or `None` when the project metadata is missing or invalid.
+    """
+    requires_python = read_pyproject_toml().get("project", {}).get("requires-python")
+    if not isinstance(requires_python, str):
+        return None
+
+    try:
+        specifier_set = SpecifierSet(requires_python)
+    except Exception:
+        LOGGER.warning("Unable to parse requires-python specifier: %s", requires_python)
+        return None
+
+    for candidate in BLACK_TARGET_PYTHON_CANDIDATES:
+        if specifier_set.contains(candidate):
+            return f"py{candidate.major}{candidate.minor:02d}"
+    return None
+
+
 @lru_cache
 def has_debug_dependency_group() -> bool:
     """Return whether `pyproject.toml` declares a non-empty debug dependency group.