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

common_python_tasks/data/fastapi/compose-base.yml.j2

@@ -9,7 +9,8 @@ x-common-environment: &common-environment
 x-common-build-args: &common-build-args
   PACKAGE_NAME: ${PACKAGE_NAME}
   PYTHON_VERSION: ${PYTHON_VERSION}
-  POETRY_VERSION: ${POETRY_VERSION}
+  PACKAGE_MANAGER: ${PACKAGE_MANAGER}
+  PACKAGE_MANAGER_VERSION: ${PACKAGE_MANAGER_VERSION}
 
 services:
   api:

common_python_tasks/data/fastapi/compose-db.yml.j2

@@ -8,7 +8,8 @@ x-common-environment: &common-environment
 x-common-build-args: &common-build-args
   PACKAGE_NAME: ${PACKAGE_NAME}
   PYTHON_VERSION: ${PYTHON_VERSION}
-  POETRY_VERSION: ${POETRY_VERSION}
+  PACKAGE_MANAGER: ${PACKAGE_MANAGER}
+  PACKAGE_MANAGER_VERSION: ${PACKAGE_MANAGER_VERSION}
   WORKDIR_PATH: ${WORKDIR_PATH}
 
 services:

common_python_tasks/data/generic/Dockerfile.j2

@@ -7,24 +7,48 @@ ARG PYTHON_VERSION=3
 # See https://hub.docker.com/_/python for available variants
 ARG PYTHON_VARIANT=slim
 ARG WORKDIR_PATH=/workspace
+{% set package_manager = PACKAGE_MANAGER|default('poetry') %}
 
 FROM python:${PYTHON_VERSION} AS builder
 
+ARG PACKAGE_VERSION
+
+{% if package_manager == 'poetry' %}
 ARG POETRY_VERSION
 ARG POETRY_DYNAMIC_VERSIONING_PLUGIN_VERSION
 ARG POETRY_PLUGIN_EXPORT_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"
+# Install Poetry and required Poetry plugins for package build
+RUN --mount=type=cache,target=/root/.cache/pip,id=pip-cache{{ CACHE_ID_SUFFIX }} \
+    sh -c 'set -eu; \
+    poetry_spec="poetry"; \
+    if [ -n "${POETRY_VERSION:-}" ]; then poetry_spec="poetry==$POETRY_VERSION"; fi; \
+    dynamic_spec="poetry-dynamic-versioning[plugin]"; \
+    if [ -n "${POETRY_DYNAMIC_VERSIONING_PLUGIN_VERSION:-}" ]; then dynamic_spec="poetry-dynamic-versioning[plugin]==$POETRY_DYNAMIC_VERSIONING_PLUGIN_VERSION"; fi; \
+    export_spec="poetry-plugin-export"; \
+    if [ -n "${POETRY_PLUGIN_EXPORT_VERSION:-}" ]; then export_spec="poetry-plugin-export==$POETRY_PLUGIN_EXPORT_VERSION"; fi; \
+    pip install --root-user-action=ignore "$poetry_spec" "$dynamic_spec" "$export_spec"'
+{% else %}
+ARG UV_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 UV_DYNAMIC_VERSIONING_BYPASS=${PACKAGE_VERSION}
+
+# Install uv for package build and dependency export steps
+RUN --mount=type=cache,target=/root/.cache/pip,id=pip-cache{{ CACHE_ID_SUFFIX }} \
+    sh -c 'if [ -n "${UV_VERSION:-}" ]; then \
+        pip install --root-user-action=ignore "uv==$UV_VERSION"; \
+    else \
+        pip install --root-user-action=ignore uv; \
+    fi'
+{% endif %}
 
 # Build package
 WORKDIR /tmp/build
@@ -32,15 +56,24 @@ COPY . /tmp/build/
 
 {% if HAS_DEBUG_DEPS %}
 # Export debug requirements when the project defines a debug dependency group
+{% if package_manager == 'poetry' %}
 RUN --mount=type=cache,target=/root/.cache/pip,id=pip-cache{{ CACHE_ID_SUFFIX }} \
     poetry export --only debug --without-hashes -f requirements.txt --output requirements-debug.txt
+{% else %}
+RUN --mount=type=cache,target=/root/.cache/uv,id=uv-cache{{ CACHE_ID_SUFFIX }} \
+    uv export --group debug --no-hashes --format requirements-txt --output-file requirements-debug.txt
+{% endif %}
 {% endif %}
 
-# Build the wheel, caching Poetry's cache directory to speed up subsequent builds.
+# Build the wheel, caching the package-manager cache directory to speed up subsequent builds.
 # If running this in a CI system, you must be using a persistent builder to take
 # advantage of the cache mount, and you should configure your CI to persist the
 # cache directory between builds
+{% if package_manager == 'poetry' %}
 RUN --mount=type=cache,target=/root/.cache/pypoetry,id=pypoetry-cache{{ CACHE_ID_SUFFIX }} poetry build --format=wheel
+{% else %}
+RUN --mount=type=cache,target=/root/.cache/uv,id=uv-cache{{ CACHE_ID_SUFFIX }} uv build --wheel
+{% endif %}
 
 FROM python:${PYTHON_VERSION}-${PYTHON_VARIANT} AS runtime
 ARG WORKDIR_PATH=/workspace

common_python_tasks/docker.py

@@ -93,7 +93,6 @@ def _safe_unlink(path: Path | str | None) -> None:
 
 
 def _build_docker_build_command(
-    *,
     context_path: Path,
     dockerfile_path: Path,
     build_args: dict[str, str],
@@ -331,12 +330,12 @@ def build_deps_image(
 
     full_tag = f"{deps_image_name}:{deps_tag}"
     build_cmd = _build_docker_build_command(
-        context_path=context_path,
-        dockerfile_path=dockerfile_path,
-        build_args=build_args,
-        archs=archs,
-        no_cache=no_cache,
-        plain=plain,
+        context_path,
+        dockerfile_path,
+        build_args,
+        archs,
+        no_cache,
+        plain,
         tags=[full_tag],
     )
 
@@ -451,24 +450,37 @@ def build_image(
             commit_tag = version_tag
 
         python_version = platform.python_version()
-        poetry_version = project.get_poetry_version()
+        package_manager = project.get_package_manager()
+        package_manager_version = project.get_package_manager_version(package_manager)
 
-        build_args = _merge_build_args(
-            {
-                "PYTHON_VERSION": python_version,
-                "POETRY_VERSION": poetry_version,
+        manager_build_args: dict[str, str | None]
+        if package_manager == project.PackageManager.POETRY:
+            manager_build_args = {
+                "POETRY_VERSION": package_manager_version,
                 "POETRY_DYNAMIC_VERSIONING_PLUGIN_VERSION": project.get_installed_requirement_version(
                     "poetry-dynamic-versioning[plugin]"
                 ),
                 "POETRY_PLUGIN_EXPORT_VERSION": project.get_installed_requirement_version(
                     "poetry-plugin-export"
                 ),
+            }
+        else:
+            manager_build_args = {
+                "UV_VERSION": package_manager_version,
+            }
+
+        build_args = _merge_build_args(
+            {
+                "PYTHON_VERSION": python_version,
+                "PACKAGE_MANAGER": package_manager,
+                "PACKAGE_MANAGER_VERSION": package_manager_version,
                 "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()]
                 ),
                 "GIT_COMMIT": commit_tag,
+                **manager_build_args,
             },
             extra_build_args,
         )
@@ -503,12 +515,12 @@ def build_image(
                 all_tags.append(resolved_tag)
 
         build_cmd = _build_docker_build_command(
-            context_path=context_path,
-            dockerfile_path=dockerfile_path,
-            build_args=build_args,
-            archs=archs,
-            no_cache=no_cache,
-            plain=plain,
+            context_path,
+            dockerfile_path,
+            build_args,
+            archs,
+            no_cache,
+            plain,
             target=None if omit_target else target,
             tags=all_tags,
         )

common_python_tasks/docker_compose.py

@@ -14,7 +14,7 @@ from poethepoet_tasks import TaskCollection
 
 from . import utils
 from .env import get_workdir_path
-from .project import get_poetry_version
+from .project import get_package_manager, get_package_manager_version
 
 LOGGER = logging.getLogger(__name__)
 
@@ -232,7 +232,8 @@ _COMPOSE_VAR_REQUIREMENTS: dict[str, dict[str, set[str]]] = {
             "ENVIRONMENT",
             "IMAGE_TAG",
             "PYTHON_VERSION",
-            "POETRY_VERSION",
+            "PACKAGE_MANAGER",
+            "PACKAGE_MANAGER_VERSION",
         },
         "compose-db": {
             "PACKAGE_NAME",
@@ -242,7 +243,8 @@ _COMPOSE_VAR_REQUIREMENTS: dict[str, dict[str, set[str]]] = {
             "DB_PORT",
             "IMAGE_TAG",
             "PYTHON_VERSION",
-            "POETRY_VERSION",
+            "PACKAGE_MANAGER",
+            "PACKAGE_MANAGER_VERSION",
             "POSTGRES_VERSION",
             "WORKDIR_PATH",
         },
@@ -328,9 +330,10 @@ def get_compose_env(
         "ENVIRONMENT": os.getenv("ENVIRONMENT", "production"),
         "IMAGE_TAG": image_tag or "latest",
         "PACKAGE_NAME": package_name,
+        "PACKAGE_MANAGER": get_package_manager(),
+        "PACKAGE_MANAGER_VERSION": get_package_manager_version(),
         "PACKAGE_UNDERSCORE_NAME": utils.package_name_to_underscore(package_name),
         "WORKDIR_PATH": get_workdir_path(),
-        "POETRY_VERSION": get_poetry_version(),
         "POSTGRES_VERSION": os.getenv("POSTGRES_VERSION", "17"),
         "PYTHON_VERSION": platform.python_version(),
         "SECRET_KEY": os.getenv("SECRET_KEY", ""),

common_python_tasks/env.py

@@ -186,11 +186,12 @@ def split_delimited_values(
     separators: str = ":",
     allow_whitespace: bool = False,
 ) -> list[str]:
-    """Split a delimited string while preserving quoted substrings.
+    """Split a delimited string while preserving quoted or escaped separators.
 
     Args:
         value: The string to split.
-        separators: Explicit separator characters to use.
+        separators: Explicit separator characters to use. Prefix a separator with
+            a backslash to include it literally in a token.
         allow_whitespace: Treat whitespace as additional separators.
 
     Returns:
@@ -207,7 +208,7 @@ def split_delimited_values(
 
 
 def split_colon_delimited_values(value: str) -> list[str]:
-    """Split a colon- or whitespace-delimited string while preserving quoted substrings."""
+    """Split colon-delimited values while preserving quoted or escaped colons."""
     return split_delimited_values(value, separators=":", allow_whitespace=True)
 
 
@@ -221,7 +222,7 @@ def parse_container_build_args(
     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:
+    if cli_build_args and any(token.strip() for token in cli_build_args):
         build_arg_tokens = [
             token.strip() for token in cli_build_args if token and token.strip()
         ]
@@ -233,10 +234,15 @@ def parse_container_build_args(
     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
+            utils.fatal(
+                f"Invalid build-arg token {token!r}; expected KEY=VALUE. "
+                "Escape literal colons in values as \\: or quote the value."
+            )
         key, value = token.split("=", 1)
-        parsed_build_args[key.strip()] = value.strip()
+        key = key.strip()
+        if not key:
+            utils.fatal(f"Invalid build-arg token {token!r}; the key must not be empty")
+        parsed_build_args[key] = value.strip()
 
     return parsed_build_args or None
 
@@ -254,13 +260,20 @@ def parse_container_env_tokens(value: str | list[str] | None) -> list[str]:
         return []
 
     if isinstance(value, list):
-        return [token.strip() for token in value if token and token.strip()]
-
-    if not value.strip():
+        tokens = [token.strip() for token in value if token and token.strip()]
+    elif not value.strip():
         return []
+    else:
+        tokens = split_colon_delimited_values(value)
 
-    tokens = split_colon_delimited_values(value)
-    return [token for token in tokens if token.strip()]
+    for token in tokens:
+        if "=" not in token or not token.split("=", 1)[0].strip():
+            utils.fatal(
+                f"Invalid container env token {token!r}; expected KEY=VALUE. "
+                "Escape literal colons in values as \\: or quote the value."
+            )
+
+    return tokens
 
 
 def _parse_container_envfile_paths(

common_python_tasks/git.py

@@ -96,7 +96,7 @@ def compute_next_release_version(
     Returns:
         A `NextReleaseVersion` with the serialized new version and normalized component.
     """
-    current_version_text = project.get_project_version_from_poetry()
+    current_version_text = project.get_project_version()
     release_component = (
         infer_bump_component_from_git_cliff() if component is None else component
     )
@@ -181,14 +181,11 @@ def infer_bump_component_from_git_cliff() -> ReleaseComponent:
     except Exception:
         utils.fatal(f"Unable to parse bumped version from git-cliff: {version_text!r}")
 
-    current_version = project.get_project_version_from_poetry()
+    current_version = project.get_project_version()
     try:
         current = Version.parse(current_version)
     except Exception:
-        utils.fatal(
-            "Unable to parse current version from Poetry output: "
-            f"{current_version!r}"
-        )
+        utils.fatal("Unable to parse current project version: " f"{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

@@ -3,6 +3,8 @@ import logging
 import mimetypes
 import os
 import re
+from collections.abc import Callable
+from functools import lru_cache
 from pathlib import Path
 from typing import Any, Literal
 
@@ -39,7 +41,7 @@ def should_publish_github_release() -> bool:
     """Return whether GitHub Releases publication is enabled.
 
     Returns:
-        True if GitHub Release publishing is enabled, False if it is skipped.
+        `True` if GitHub Release publishing is enabled, `False` if it is skipped.
     """
     return not env_truthy("SKIP_GITHUB_RELEASE")
 
@@ -51,13 +53,25 @@ def get_github_repository() -> str | None:
         The GitHub repository slug in the form `owner/repo`, or `None` if it
         cannot be determined.
     """
-    repository = os.getenv("GITHUB_REPOSITORY", "").strip()
+    return _get_github_repository(
+        os.getenv("GITHUB_REPOSITORY", "").strip(),
+        Path.cwd(),
+        utils.run_command,
+    )
+
+
+@lru_cache(maxsize=32)
+def _get_github_repository(
+    repository: str,
+    _working_directory: Path,
+    run_command: Callable[..., Any],
+) -> str | None:
     if repository:
         if re.fullmatch(r"[^/]+/[^/]+", repository):
             return repository
         LOGGER.warning("Ignoring invalid GITHUB_REPOSITORY value: %s", repository)
 
-    result = utils.run_command(
+    result = run_command(
         ["git", "remote", "get-url", "origin"],
         capture_output=True,
         acceptable_returncodes={0, 128},
@@ -94,8 +108,13 @@ def get_github_token() -> str | None:
     if token:
         return token
 
+    return _get_github_cli_token(utils.run_command)
+
+
+@lru_cache(maxsize=8)
+def _get_github_cli_token(run_command: Callable[..., Any]) -> str | None:
     try:
-        result = utils.run_command(
+        result = run_command(
             ["gh", "auth", "token"],
             capture_output=True,
             acceptable_returncodes={0, 1},
@@ -132,13 +151,18 @@ def get_github_api_base_url() -> str:
         The base URL for GitHub API requests, defaulting to GitHub.com API or
         GitHub Enterprise API if configured.
     """
-    api_url = os.getenv("GITHUB_API_URL", "").strip()
+    return _get_github_api_base_url(
+        os.getenv("GITHUB_API_URL", "").strip(),
+        os.getenv("GITHUB_SERVER_URL", "https://github.com").strip(),
+    )
+
+
+@lru_cache(maxsize=32)
+def _get_github_api_base_url(api_url: str, server_url: str) -> str:
     if api_url:
         return api_url.rstrip("/")
 
-    server_url = (
-        os.getenv("GITHUB_SERVER_URL", "https://github.com").strip().rstrip("/")
-    )
+    server_url = server_url.rstrip("/")
     if server_url.endswith("github.com"):
         return "https://api.github.com"
     return f"{server_url}/api/v3"
@@ -156,7 +180,11 @@ def get_github_upload_api_base_url(api_base_url: str | None = None) -> str:
     Returns:
         The upload base URL for GitHub API requests.
     """
-    api_base = api_base_url or get_github_api_base_url()
+    return _get_github_upload_api_base_url(api_base_url or get_github_api_base_url())
+
+
+@lru_cache(maxsize=32)
+def _get_github_upload_api_base_url(api_base: str) -> str:
     if api_base == "https://api.github.com":
         return "https://uploads.github.com"
     return api_base