common-python-tasks 0.0.2__py3-none-any.whl → 0.1.0__py3-none-any.whl

common_python_tasks/__init__.py

@@ -1,18 +1,27 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from typing import Sequence
 
 from poethepoet_tasks import TaskCollection
 
-__version__ = "0.0.0"
-
 __all__ = ["TaskCollection"]
 
 
 def tasks(
-    include_tags: "Sequence[str]" = tuple(), exclude_tags: "Sequence[str]" = tuple()
-):
-    from .tasks import tasks
+    include_tags: "Sequence[str] | None" = None,
+    exclude_tags: "Sequence[str]" = tuple(),
+) -> dict:
+    from .tasks import tasks as task_collection
+
+    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
+
 
-    return tasks(include_tags=include_tags, exclude_tags=exclude_tags)
+_TASKS_ENTRYPOINT = tasks

common_python_tasks/__main__.py

@@ -0,0 +1,108 @@
+import importlib
+import inspect
+import os
+import re
+import sys
+
+from .tasks import tasks
+
+__all__ = ["get_available_tasks", "print_available_tasks"]
+
+
+def get_available_tasks(internal: bool = False) -> list[str]:
+    """Return available task names for this package.
+
+    Args:
+        internal: When True, include internal task names starting with '_'.
+
+    Returns:
+        A list of task names.
+    """
+    return [
+        task_name
+        for task_name in tasks()["tasks"]
+        if internal or not task_name.startswith("_")
+    ]
+
+
+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.",
+        file=sys.stderr if len(sys.argv) > 1 else sys.stdout,
+    )
+
+    if len(sys.argv) == 1:
+        debug = os.getenv("COMMON_PYTHON_TASKS_LOG_LEVEL", "info").lower() == "debug"
+        print_available_tasks(include_docs=debug)
+    else:
+        sys.exit(1)