common-python-tasks 0.4.1__py3-none-any.whl → 0.5.1__py3-none-any.whl

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/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
@@ -447,7 +475,8 @@ def get_github_release_asset_paths(
         asset_sources: Optional list of paths or glob patterns. When a string is
             provided (including via `GITHUB_RELEASE_ASSETS`), values are
             interpreted as colon-separated paths or glob patterns.
-            If not provided, the default value is `dist/*`.
+            If not provided, the default value is `dist/*`. An empty list
+            explicitly disables asset selection.
 
     Returns:
         A sorted list of existing asset paths.
@@ -485,7 +514,7 @@ def get_github_release_asset_paths(
         elif path.exists():
             LOGGER.warning("Ignoring non-file GitHub release asset path: %s", path)
 
-    if not asset_paths and explicit_assets:
+    if not asset_paths and explicit_assets and source_items:
         utils.fatal(
             "No GitHub Release assets were found for the configured asset paths: "
             + ":".join(source_items)

common_python_tasks/project.py

@@ -18,6 +18,11 @@ from . import utils
 LOGGER = logging.getLogger(__name__)
 
 PACKAGE_MANAGER_ENV_VAR = "COMMON_PYTHON_TASKS_PACKAGE_MANAGER"
+PACKAGE_MANAGER_ENV_VARS = (
+    PACKAGE_MANAGER_ENV_VAR,
+    "COMMON_PYTHON_TASKS_BUILD_TOOL",
+    "PACKAGE_MANAGER",
+)
 
 
 class PackageManager(StrEnum):
@@ -45,9 +50,10 @@ def _parse_tool_version_output(output: str, tool_name: str) -> str:
 
 
 def _find_package_manager_override() -> tuple[str, str] | None:
-    value = os.getenv(PACKAGE_MANAGER_ENV_VAR)
-    if value is not None and value.strip():
-        return PACKAGE_MANAGER_ENV_VAR, value.strip().lower()
+    for env_var in PACKAGE_MANAGER_ENV_VARS:
+        value = os.getenv(env_var)
+        if value is not None and value.strip():
+            return env_var, value.strip().lower()
     return None
 
 
@@ -105,7 +111,8 @@ def get_package_manager() -> PackageManager:
     """Resolve the package manager backend used for build and publish commands.
 
     Resolution order:
-    1. Environment override via `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`.
+    1. Environment overrides via `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`,
+       `COMMON_PYTHON_TASKS_BUILD_TOOL`, or `PACKAGE_MANAGER`, in that order.
     2. Auto-discovery from installed executables and project metadata.
 
     Supported values are `poetry`, `uv`, and `auto`.
@@ -374,7 +381,13 @@ 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)]
+BLACK_TARGET_PYTHON_MINORS = range(7, 17)
+
+
+def _specifier_supports_python_minor(specifier_set: SpecifierSet, minor: int) -> bool:
+    return any(
+        specifier_set.contains(Version(f"3.{minor}.{patch}")) for patch in range(1000)
+    )
 
 
 def get_black_target_version() -> str | None:
@@ -394,9 +407,9 @@ def get_black_target_version() -> str | None:
         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}"
+    for minor in BLACK_TARGET_PYTHON_MINORS:
+        if _specifier_supports_python_minor(specifier_set, minor):
+            return f"py3{minor:02d}"
     return None
 
 
@@ -413,22 +426,57 @@ def has_debug_dependency_group() -> bool:
     return bool(debug_group)
 
 
-def resolve_container_entrypoint_command(custom_entrypoint: str | None = None) -> str:
+def _get_project_scripts() -> dict[str, str]:
+    scripts = read_pyproject_toml().get("project", {}).get("scripts")
+    if not isinstance(scripts, dict):
+        return {}
+
+    normalized_scripts = {
+        str(script_name).strip(): str(script_target)
+        for script_name, script_target in scripts.items()
+        if str(script_name).strip()
+    }
+    return normalized_scripts
+
+
+def _get_available_container_entrypoint_scripts() -> tuple[str, ...]:
+    return tuple(sorted(_get_project_scripts().keys()))
+
+
+def resolve_container_entrypoint_command(entrypoint_script: str | None = None) -> str:
     """Resolve the command used in the generated container entrypoint script.
 
     Args:
-        custom_entrypoint: Optional explicit command override.
+        entrypoint_script: Optional explicit entrypoint script override.
 
     Returns:
         A command name to place in `/pkg/entrypoint.sh`.
     """
 
-    if custom_entrypoint is not None and custom_entrypoint.strip():
-        return custom_entrypoint.strip()
+    available_scripts = _get_available_container_entrypoint_scripts()
+    scripts_set = set(available_scripts)
+
+    if entrypoint_script is not None and entrypoint_script.strip():
+        selected_entrypoint = entrypoint_script.strip()
+        if selected_entrypoint in scripts_set:
+            return selected_entrypoint
+
+        if available_scripts:
+            utils.fatal(
+                "Invalid CUSTOM_ENTRYPOINT value "
+                f"{selected_entrypoint!r}. "
+                "It must match a key in [project].scripts. "
+                f"Available scripts: {', '.join(available_scripts)}"
+            )
+
+        utils.fatal(
+            "Invalid CUSTOM_ENTRYPOINT value "
+            f"{selected_entrypoint!r}. "
+            "No [project].scripts entries were found in pyproject.toml."
+        )
 
     script_name = utils.get_package_name(use_underscores=True)
-    scripts = read_pyproject_toml().get("project", {}).get("scripts")
-    if isinstance(scripts, dict) and script_name in scripts:
+    if script_name in scripts_set:
         return script_name
 
     return "python"

common_python_tasks/tasks.py

@@ -582,7 +582,7 @@ def build_image(
 
     apt_packages = (parsed_build_args or {}).get("APT_PACKAGES", "").strip()
     entrypoint_command = resolve_container_entrypoint_command(
-        (parsed_build_args or {}).get("CUSTOM_ENTRYPOINT")
+        entrypoint_script=(parsed_build_args or {}).get("CUSTOM_ENTRYPOINT")
     )
     container_env_vars = load_container_env_tokens(
         container_env,
@@ -884,7 +884,7 @@ def run_container(
                 f"No local images found for {package_name}. Build the image first or specify a tag."
             )
 
-    LOGGER.info("Running container %s", selected_image)
+    LOGGER.debug("Running container %s", selected_image)
     run_args = ["docker", "run", "--rm", "-i", "-t"]
     if privileged:
         run_args.append("--privileged")
@@ -1000,7 +1000,8 @@ 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")
-    asset_paths = get_github_release_asset_paths(assets)
+    # Poe supplies `[]` when an optional repeated CLI argument is omitted.
+    asset_paths = get_github_release_asset_paths(assets or None)
 
     return publish_github_release_helper(
         resolved_tag_name,
@@ -1088,6 +1089,26 @@ def changelog() -> None:
     print(_changelog())
 
 
+def _build_and_publish_release_package(release_tag: str) -> None:
+    from .utils import run_command
+
+    package_published = False
+    try:
+        build_package(clean_dist=True)
+        publish_package(build_first=False)
+        package_published = True
+    finally:
+        if not package_published:
+            LOGGER.warning(
+                "Package build or publication failed; deleting local release tag %s",
+                release_tag,
+            )
+            run_command(
+                ["git", "tag", "--delete", release_tag],
+                acceptable_returncodes={0, 1},
+            )
+
+
 def _run_release_flow(
     component: str = "auto",
     stage: str | None = None,
@@ -1167,8 +1188,7 @@ def _run_release_flow(
             run_command(["sh", "-lc", post_script], env=hook_env, dry_run=False)
         return
 
-    build_package(clean_dist=True)
-    publish_package(build_first=False)
+    _build_and_publish_release_package(hook_env["RELEASE_TAG"])
 
     if include_containers:
         build_image(
@@ -1410,6 +1430,7 @@ def fastapi_stack_up(
     from .env import (
         get_cache_id_suffix,
         load_container_env_tokens,
+        parse_container_build_args,
     )
     from .project import (
         get_package_manager,
@@ -1429,6 +1450,13 @@ def fastapi_stack_up(
         )
 
     container_env_vars = load_container_env_tokens(container_env, container_envfile)
+    parsed_build_args = parse_container_build_args(
+        build_args,
+        os.getenv("CONTAINER_BUILD_ARGS"),
+    )
+    entrypoint_command = resolve_container_entrypoint_command(
+        entrypoint_script=(parsed_build_args or {}).get("CUSTOM_ENTRYPOINT")
+    )
 
     cache_id_suffix = get_cache_id_suffix(no_cache)
 
@@ -1439,7 +1467,7 @@ def fastapi_stack_up(
             "EXTENSION_CONTENT": "",
             "HAS_DEBUG_DEPS": has_debug_deps,
             "APT_PACKAGES": "",
-            "ENTRYPOINT_COMMAND": resolve_container_entrypoint_command(),
+            "ENTRYPOINT_COMMAND": entrypoint_command,
             "CONTAINER_ENV_VARS": container_env_vars,
             "CACHE_ID_SUFFIX": cache_id_suffix,
         },

{common_python_tasks-0.4.1.dist-info → common_python_tasks-0.5.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: common-python-tasks
-Version: 0.4.1
+Version: 0.5.1
 Summary: Opinionated Poe the Poet tasks for Python package development.
 Project-URL: Homepage, http://github.com/ci-sourcerer/common-python-tasks
 Project-URL: Source, http://github.com/ci-sourcerer/common-python-tasks.git
@@ -46,14 +46,16 @@ Instead of writing your own tasks for formatting, linting, testing, packaging, a
 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 | jq -r '.content' | base64 -d | sh
+curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add_common_python_tasks.py | jq -r '.content' | base64 -d | python3
 ```
 
 To install a specific release, set the environment variable `COMMON_PYTHON_TASKS_VERSION`.
 
 ```shell
-COMMON_PYTHON_TASKS_VERSION=0.4.1 \
-  sh -c "$(curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add-common-python-tasks.sh | jq -r '.content' | base64 -d)"
+curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add_common_python_tasks.py \
+  | jq -r '.content' \
+  | base64 -d \
+  | COMMON_PYTHON_TASKS_VERSION=0.5.1 python3
 ```
 
 This will complete the following steps.
@@ -73,7 +75,7 @@ There's no real reason to run the automated script; I just like automating every
     ```toml
     [project]
     dependencies = [
-        "common-python-tasks==0.4.1"  # Always pin to a specific version
+        "common-python-tasks==0.5.1"  # Always pin to a specific version
     ]
 
     [tool.poe]
@@ -220,7 +222,7 @@ Supported values are `poetry`, `uv`, and `auto`.
 
 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
+1. **`pyproject.toml` sections**: `[tool.pytest.ini_options]`, `[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 the 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
@@ -248,19 +250,19 @@ The following environment variables configure package and container behavior.
 - `PACKAGE_MANAGER`: Alias for `COMMON_PYTHON_TASKS_PACKAGE_MANAGER`
 - `CONTAINER_REGISTRY_USERNAME`: Specifies the container registry username for image tagging; the default is the current local user
 - `CONTAINER_REGISTRY_URL`: Specifies the registry URL (default: `docker.io/{username}`)
-- `CONTAINER_BUILD_ARGS`: Provides additional Docker build arguments in `KEY=VALUE:OTHER=VALUE` format
-- `CONTAINER_EXTENSION_FILES`: Specifies colon delimited local extension Dockerfile paths to include in the rendered build
-- `CONTAINER_EXTENSIONS`: Specifies colon delimited extension bundle names or parameterized bundle values to include in the rendered build
-- `CONTAINER_ENV`: Provides colon delimited `KEY=VALUE` declarations to inject into the builder stage of the rendered Dockerfile
+- `CONTAINER_BUILD_ARGS`: Provides additional Docker build arguments in `KEY=VALUE:OTHER=VALUE` format. Escape literal colons in values as `\:` or quote the complete value
+- `CONTAINER_EXTENSION_FILES`: Specifies colon delimited local extension Dockerfile paths to include in the rendered build; escape literal colons as `\:` or quote the complete path
+- `CONTAINER_EXTENSIONS`: Specifies colon delimited extension bundle names or parameterized bundle values to include in the rendered build; escape literal colons as `\:` or quote the complete value
+- `CONTAINER_ENV`: Provides colon delimited `KEY=VALUE` declarations to inject into the builder stage of the rendered Dockerfile. Escape literal colons in values as `\:` or quote the complete value
 - `.containerenv`: Can also supply the same declarations from a file in the project root. It is loaded first, then `container_envfile`, then `CONTAINER_ENV`, and finally `container_env`.
 - `CONTAINER_PRUNE_KEEP`: Controls image pruning after builds (`-1` keeps all, `0` keeps the latest only, `N` keeps the latest plus `N` previous)
-- `CUSTOM_ENTRYPOINT`: Specifies a custom entrypoint script name for containers
+- `CUSTOM_ENTRYPOINT`: Specifies a custom entrypoint script name for containers. The value must match a key in `[project].scripts`; unknown values fail the build
 - `CONTAINER_DEPS_CONTENT`: Supplies inline Dockerfile instructions for a dependency image that installs artifacts into `/tmp/deps`
-- `CONTAINER_DEPS_FILE`: Points to one or more explicit Dockerfiles to build the dependency image. It may be a colon delimited list of file paths and is used only when `CONTAINER_DEPS_CONTENT` is unset
+- `CONTAINER_DEPS_FILE`: Points to one or more explicit Dockerfiles to build the dependency image. It may be a colon delimited list of file paths, with literal colons escaped as `\:`, and is used only when `CONTAINER_DEPS_CONTENT` is unset
 - `CONTAINER_DEPS_MAPPINGS`: Maps copied dependency names from `/tmp/deps` into destination paths as space separated `name:/target/path` entries. This is used only when `CONTAINER_DEPS_MOVE_SCRIPT` or `CONTAINER_DEPS_MOVE_SCRIPT_PATH` is not set
 - `CONTAINER_DEPS_MOVE_SCRIPT`: Supplies a raw executable script to run after `/tmp/deps` is copied into the image. The script is written to `/tmp/container-deps-move-script` and executed with its own shebang
 - `CONTAINER_DEPS_MOVE_SCRIPT_PATH`: Supplies a host path to a script file to run after `/tmp/deps` is copied into the image. This path takes precedence over `CONTAINER_DEPS_MOVE_SCRIPT` when both are set
-- `GITHUB_RELEASE_ASSETS`: Colon separated list of file paths or glob patterns to attach to the GitHub Release (default: `dist/*`)
+- `GITHUB_RELEASE_ASSETS`: Colon separated list of file paths or glob patterns to attach to the GitHub Release (default: `dist/*`); escape literal colons as `\:` or quote the complete path
 - `SKIP_GITHUB_RELEASE`: Truthy value to skip GitHub Release publication
 - `GITHUB_TOKEN` or `GH_TOKEN`: GitHub authentication token used to publish releases and upload assets
 - `GITHUB_REPOSITORY`: Optional override for the repository slug used when publishing a GitHub Release
@@ -307,8 +309,8 @@ By default, `tasks()` exposes the common task set. You can still include or excl
 ```toml
 [project]
 name = "simple-cli-tool"
-version = "0.4.1"
-dependencies = ["common-python-tasks==0.4.1"]
+version = "0.5.1"
+dependencies = ["common-python-tasks==0.5.1"]
 
 [tool.poe]
 include_script = "common_python_tasks:tasks()"
@@ -320,7 +322,7 @@ Available tasks: common defaults such as `format`, `lint`, `test`, and `build`.
 
 ```toml
 [project]
-dependencies = ["common-python-tasks==0.4.1"]
+dependencies = ["common-python-tasks==0.5.1"]
 
 [tool.poe]
 include_script = "common_python_tasks:tasks(include_tags=['common', 'containers'])"
@@ -336,7 +338,7 @@ Available tasks: All tasks including `build-image` and `push-image`.
 
 ```toml
 [project]
-dependencies = ["common-python-tasks==0.4.1"]
+dependencies = ["common-python-tasks==0.5.1"]
 
 [tool.poe]
 include_script = "common_python_tasks:tasks()"
@@ -424,7 +426,7 @@ The standard Python Dockerfile incorporates several intentional design choices.
 - Explicit inputs through build args: `PYTHON_VERSION`, `PACKAGE_MANAGER`, `PACKAGE_MANAGER_VERSION`, `PACKAGE_NAME`, `AUTHORS`, `GIT_COMMIT`, and `CUSTOM_ENTRYPOINT` make image metadata and behavior predictable and auditable
 - Optional debug stage: 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. This ensures that the package can be imported and executed from a known location and supports the less common case of reading files directly from the package path
-- Safe entrypoint selection: The default entrypoint resolves the console script matching the package name, while `CUSTOM_ENTRYPOINT` allows an override at build time and keeps runtime behavior predictable
+- Safe entrypoint selection: The default entrypoint resolves the console script matching the package name and falls back to `python` when no matching script exists. `CUSTOM_ENTRYPOINT` allows an override at build time, and the override is validated strictly against `[project].scripts`
 - Minimal final image: Uses the slim Python base by default, cleans wheel artifacts and caches, and sets `runtime` as the explicit final target so the debug stage remains optional
 
 ## Notes

{common_python_tasks-0.4.1.dist-info → common_python_tasks-0.5.1.dist-info}/RECORD

@@ -2,11 +2,11 @@ common_python_tasks/__init__.py,sha256=A-qMF818PGbDxM_DH9l1HwQMV-tXn8CZZiVQy-F_s
 common_python_tasks/__main__.py,sha256=AZiLLusMDs0rZIIBuCDbt6jABlQD-kEwIQIep7GxgEc,3019
 common_python_tasks/docker.py,sha256=KQ_Ym6tungnYqkf1EyXgdLpMjLNX879SWXKM9tIrfEg,19694
 common_python_tasks/docker_compose.py,sha256=UnTP5-Kw31ZzkMUeuml1GxHkHmNsX76-9uezq0qPVBQ,21057
-common_python_tasks/env.py,sha256=DNz-qpFnJ-41pHBb7MIJuemgLqn_rI3GUEZTfC2I4bQ,15064
+common_python_tasks/env.py,sha256=X-v2gX6SJluvkjU7M941UbrMZ73vHnxwLeaBWRUxeLc,15678
 common_python_tasks/git.py,sha256=wJ3gePpWE4fhNJYZCEWTDFrhHqaOVkaQveHeiGIbCHo,11188
-common_python_tasks/github.py,sha256=sABDB7BvrdWkpbh4u0-8OeAiu-jWUYfjre_nKOw15bI,18393
-common_python_tasks/project.py,sha256=zyhs1oqptxRALPCzJtNOsQJBeNEbWzKIWBG0BUoiXLg,19271
-common_python_tasks/tasks.py,sha256=P-T6UMhOyhOfOTG2M9EGiK4YfTm9l5mGplF6SnLt1vo,53926
+common_python_tasks/github.py,sha256=dLlHf6MYIrs0iTlBXtGm4yYgkzCZ0kJj4265ChH1O0U,19170
+common_python_tasks/project.py,sha256=5ZU1PxefUPaSjPEGhEW3kiBLGBgt6O0VGejmVEg486E,20769
+common_python_tasks/tasks.py,sha256=UIf6OX5C0MvZbIPTsLfR0Tr47TBtaiGLsJKbezabMq4,54906
 common_python_tasks/utils.py,sha256=ej4nKFPMFhu1wSgkL9x50DML_sPoPmR6aGcIMyAmfN8,19586
 common_python_tasks/data/dockerfile_extensions/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 common_python_tasks/data/fastapi/alembic.ini.j2,sha256=IVXmnF1pJvW3o8dXBLIVhmng7DyXu_sWXx_W3VlAcGE,910
@@ -22,7 +22,7 @@ common_python_tasks/data/generic/Dockerfile.deps.j2,sha256=rCGsBwLHQIRsGFzDbiRi_
 common_python_tasks/data/generic/Dockerfile.j2,sha256=UG-QxIuFT27j925LsghPl5Wqcw5wNsPPuqB6rcRngz0,7263
 common_python_tasks/data/generic/cliff.toml,sha256=po1MnEGEEgrpyBz3XLWr0h7emXb6ASX63lrU2r6o240,77
 common_python_tasks/data/generic/pytest.ini,sha256=RHak5QrLzKHvUBjFmaaiOYFrd_8YBRQubXEOT0NJfco,134
-common_python_tasks-0.4.1.dist-info/METADATA,sha256=p2tiuAPYuNHa8wx_m9NcgkEbfwQYO9lRY-ox71rOM8g,22054
-common_python_tasks-0.4.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-common_python_tasks-0.4.1.dist-info/licenses/LICENSE,sha256=RsSweM-DyzxFPx38fQOJqHrKyeT9Fiz8rO7yox-fOsw,1070
-common_python_tasks-0.4.1.dist-info/RECORD,,
+common_python_tasks-0.5.1.dist-info/METADATA,sha256=rfvEbPvkxBa35iWaLL0KfBDoIFWPjMpTOgjBbHfVTFE,22592
+common_python_tasks-0.5.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+common_python_tasks-0.5.1.dist-info/licenses/LICENSE,sha256=RsSweM-DyzxFPx38fQOJqHrKyeT9Fiz8rO7yox-fOsw,1070
+common_python_tasks-0.5.1.dist-info/RECORD,,