common-python-tasks 0.0.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

common_python_tasks/__init__.py

@@ -9,8 +9,19 @@ __all__ = ["TaskCollection"]
 
 
 def tasks(
-    include_tags: "Sequence[str]" = tuple(), exclude_tags: "Sequence[str]" = tuple()
+    include_tags: "Sequence[str] | None" = None,
+    exclude_tags: "Sequence[str]" = tuple(),
 ) -> dict:
-    from .tasks import tasks
+    from .tasks import tasks as task_collection
 
-    return tasks(include_tags=include_tags, exclude_tags=exclude_tags)
+    if include_tags is None and not exclude_tags:
+        include_tags = ("common",)
+    elif include_tags is None:
+        include_tags = tuple()
+
+    result = task_collection(include_tags=include_tags, exclude_tags=exclude_tags)
+    globals()["tasks"] = _TASKS_ENTRYPOINT
+    return result
+
+
+_TASKS_ENTRYPOINT = tasks

common_python_tasks/__main__.py

@@ -1,6 +1,12 @@
+import importlib
+import inspect
+import os
+import re
 import sys
 
-__all__ = ["get_available_tasks"]
+from .tasks import tasks
+
+__all__ = ["get_available_tasks", "print_available_tasks"]
 
 
 def get_available_tasks(internal: bool = False) -> list[str]:
@@ -12,8 +18,6 @@ def get_available_tasks(internal: bool = False) -> list[str]:
     Returns:
         A list of task names.
     """
-    from .tasks import tasks
-
     return [
         task_name
         for task_name in tasks()["tasks"]
@@ -21,6 +25,76 @@ def get_available_tasks(internal: bool = False) -> list[str]:
     ]
 
 
+def _extract_docstring_excerpt(doc: str) -> str:
+    excerpt = []
+    for line in doc.strip().splitlines():
+        if re.match(r"^(Args?|Arguments?|Parameters?):\s*$", line):
+            break
+        excerpt.append(line)
+
+    while excerpt and excerpt[-1].strip() == "":
+        excerpt.pop()
+
+    return "\n".join(excerpt)
+
+
+def _get_task_docstring(task_name: str) -> str | None:
+
+    task_config = tasks()["tasks"].get(task_name)
+    if not isinstance(task_config, dict):
+        return None
+
+    script = task_config.get("script")
+    if not isinstance(script, str) or ":" not in script:
+        return None
+
+    module_name, func_name = script.split(":", 1)
+
+    try:
+        module = importlib.import_module(module_name)
+        func = getattr(module, func_name)
+    except (ImportError, AttributeError):
+        return None
+
+    doc = inspect.getdoc(func)
+    if not doc:
+        return None
+
+    return _extract_docstring_excerpt(doc)
+
+
+def _get_task_tags(task_name: str) -> list[str] | None:
+    task_variants = getattr(tasks, "_tasks", {}).get(task_name)
+    if not task_variants:
+        return None
+
+    tags = {
+        tag
+        for variant in task_variants
+        for tag in getattr(variant, "tags", ())
+        if isinstance(tag, str) and not tag.startswith("task-")
+    }
+    return sorted(tags) or None
+
+
+def print_available_tasks(internal: bool = False, include_docs: bool = False) -> None:
+    """Print available tasks.
+
+    Args:
+        internal: Whether or not to include internal task names starting with '_'.
+        include_docs: Whether or not to include task docstrings.
+    """
+    print("\nAvailable tasks in this release:\n")
+    for task_name in get_available_tasks(internal=internal):
+        print(f" - {task_name}")
+        if include_docs:
+            doc = _get_task_docstring(task_name)
+            if doc:
+                for line in doc.splitlines():
+                    print(f"     {line}")
+                print()
+
+
 if __name__ == "__main__":
     print(
         "common_python_tasks is not intended to be run as a standalone script. Invoke a task via poethepoet.",
@@ -28,8 +102,7 @@ if __name__ == "__main__":
     )
 
     if len(sys.argv) == 1:
-        print("\nAvailable tasks in this release:\n")
-        for task_name in get_available_tasks():
-            print(f" - {task_name}")
+        debug = os.getenv("COMMON_PYTHON_TASKS_LOG_LEVEL", "info").lower() == "debug"
+        print_available_tasks(include_docs=debug)
     else:
         sys.exit(1)

common_python_tasks/git.py

@@ -1,39 +1,44 @@
 import re
 import shutil
 from pathlib import Path
-from typing import Any
+from typing import Any, NamedTuple
 
 from dunamai import Style, Version
 
 from . import project, utils
 
 
-def build_release_hook_environment(
-    component: str,
-    stage: str | None,
-    dry_run: bool,
-) -> dict[str, str]:
-    """Build the environment variables passed into release hook scripts.
+class NextReleaseVersion(NamedTuple):
+    """The computed next release version and normalized component."""
+
+    version: str
+    component: str
+
+
+def compute_next_release_version(
+    component: str, stage: str | None
+) -> NextReleaseVersion:
+    """Compute the next release version based on the given component and stage.
 
     Args:
-        component: The component to bump (major, minor, patch, or auto).
-        stage: The release stage (alpha, beta, rc, or None).
-        dry_run: Whether this is a dry run.
+        component: The version component to bump (major, minor, patch, or auto).
+        stage: Optional pre-release stage (alpha, beta, rc, or None).
 
     Returns:
-        A dictionary of environment variables for the release hook.
+        A `NextReleaseVersion` with the serialized new version and normalized component.
     """
     component = component.lower()
     normalized_stage = stage.lower() if stage is not None else None
 
+    current_version_text = project.get_project_version_from_poetry()
     if component == "auto":
         component = infer_bump_component_from_git_cliff()
-
-    current_version_text = project.get_project_version_from_poetry()
-    current_version = Version.parse(current_version_text)
-
-    if component == "auto" and re.match(r"^0\.", str(current_version.base)):
-        component = "patch"
+        if re.match(r"^0\.", str(Version.parse(current_version_text).base)):
+            utils.LOGGER.info(
+                "Current version %s is pre-production; using patch bump.",
+                current_version_text,
+            )
+            component = "patch"
 
     valid_components = {"major": 0, "minor": 1, "patch": 2}
     if component not in valid_components:
@@ -61,13 +66,47 @@ def build_release_hook_environment(
         )
         bumped.revision = 1
 
-    release_version = bumped.serialize()
+    return NextReleaseVersion(version=bumped.serialize(), component=component)
+
+
+def build_release_hook_environment(
+    component: str,
+    stage: str | None,
+    dry_run: bool,
+) -> dict[str, str]:
+    """Build the environment variables passed into release hook scripts.
+
+    The following variables are set and available to all hook scripts:
+
+    - `RELEASE_COMPONENT`: The version component being bumped.
+    - `RELEASE_STAGE`: The pre-release stage, or an empty string for a stable release.
+    - `RELEASE_VERSION`: The computed next version (e.g. `"1.2.3"`).
+    - `RELEASE_TAG`: The Git tag for the release (e.g. `"v1.2.3"`).
+    - `RELEASE_DRY_RUN`: `"1"` if this is a dry run, `"0"` otherwise.
+    - `RELEASE_SCRIPT_DRY_RUN`: `"1"` if this is a dry run, `"0"` otherwise.
+      Hook scripts should check this variable and, when set to `"1"`, print
+      what they would do without making any changes, then exit successfully.
+      This allows the release dry-run to show a complete preview of all
+      side effects, including those performed by hook scripts.
+
+    Args:
+        component: The component to bump (major, minor, patch, or auto).
+        stage: The release stage (alpha, beta, rc, or None).
+        dry_run: Whether this is a dry run.
+
+    Returns:
+        A dictionary of environment variables for the release hook.
+    """
+    normalized_stage = stage.lower() if stage is not None else None
+    result = compute_next_release_version(component, stage)
+    dry_run_flag = "1" if dry_run else "0"
     return {
-        "RELEASE_COMPONENT": component,
+        "RELEASE_COMPONENT": result.component,
         "RELEASE_STAGE": normalized_stage or "",
-        "RELEASE_VERSION": release_version,
-        "RELEASE_TAG": f"v{release_version}",
-        "RELEASE_DRY_RUN": "1" if dry_run else "0",
+        "RELEASE_VERSION": result.version,
+        "RELEASE_TAG": f"v{result.version}",
+        "RELEASE_DRY_RUN": dry_run_flag,
+        "RELEASE_SCRIPT_DRY_RUN": dry_run_flag,
     }
 
 

common_python_tasks/github.py

@@ -17,6 +17,26 @@ from .env import env_truthy
 LOGGER = logging.getLogger(__name__)
 
 
+def _is_unreleased_placeholder(notes: str) -> bool:
+    """Return whether release notes are only an unreleased placeholder."""
+    normalized_lines = [line.strip() for line in notes.splitlines() if line.strip()]
+    if not normalized_lines:
+        return True
+
+    normalized = "\n".join(normalized_lines).lower()
+    return normalized in {"[unreleased]", "## [unreleased]", "## unreleased"}
+
+
+def _latest_tagged_changelog() -> str | None:
+    """Return release notes for the latest tagged release from git-cliff."""
+    result = utils.run_git_cliff(["--latest"], capture_output=True)
+    changelog = result.stdout.strip()
+    if not changelog:
+        LOGGER.warning("git-cliff produced no release notes for the latest tag")
+        return None
+    return changelog
+
+
 def should_publish_github_release() -> bool:
     """Return whether GitHub Releases publication is enabled.
 
@@ -69,7 +89,39 @@ def get_github_token() -> str | None:
     Returns:
         The GitHub token from `GITHUB_TOKEN` or `GH_TOKEN`, or `None` if unset.
     """
-    return (os.getenv("GITHUB_TOKEN") or os.getenv("GH_TOKEN") or "").strip() or None
+    token = (os.getenv("GITHUB_TOKEN") or os.getenv("GH_TOKEN") or "").strip()
+    if token:
+        return token
+
+    try:
+        result = utils.run_command(
+            ["gh", "auth", "token"],
+            capture_output=True,
+            acceptable_returncodes={0, 1},
+        )
+    except FileNotFoundError:
+        LOGGER.warning(
+            "GitHub CLI not installed; cannot retrieve token via `gh auth token`"
+        )
+        return None
+
+    if result is None:
+        return None
+
+    if result.returncode != 0:
+        stderr = (result.stderr or "").strip()
+        message = "Failed to retrieve GitHub token via `gh auth token`"
+        if stderr:
+            message += f": {stderr}"
+        LOGGER.warning(message)
+        return None
+
+    token = (result.stdout or "").strip()
+    if not token:
+        LOGGER.warning("`gh auth token` returned an empty token")
+        return None
+
+    return token
 
 
 def get_github_api_base_url() -> str:
@@ -308,6 +360,11 @@ 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(
+            "git-cliff returned an unreleased placeholder; using latest tagged release notes instead"
+        )
+        release_body = _latest_tagged_changelog()
     if release_body is None:
         release_body = f"Release {tag_name}"
 

common_python_tasks/project.py

@@ -8,17 +8,17 @@ from typing import Any
 from . import utils
 
 
+@lru_cache
 def get_authors() -> list[tuple[str, str]]:
     """Return a list of authors from the pyproject.toml file.
 
     Returns:
         A list of tuples containing the name and email of each author.
     """
+    authors = read_pyproject_toml().get("project", {}).get("authors", [])
     return [
         ((a.get("name") or "").strip(), (a.get("email") or "").strip().strip("<>"))
-        for a in tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
-        .get("project", {})
-        .get("authors", [])
+        for a in authors
     ]