poethepoet.ui

  1import os
  2import sys
  3from typing import IO, TYPE_CHECKING, List, Mapping, Optional, Sequence, Tuple, Union
  4
  5from .__version__ import __version__
  6from .exceptions import ConfigValidationError, ExecutionError, PoeException
  7
  8if TYPE_CHECKING:
  9    from argparse import ArgumentParser, Namespace
 10
 11    from pastel import Pastel
 12
 13
 14def guess_ansi_support(file):
 15    if os.environ.get("NO_COLOR", "0")[0] != "0":
 16        # https://no-color.org/
 17        return False
 18
 19    if (
 20        os.environ.get("GITHUB_ACTIONS", "false") == "true"
 21        and "PYTEST_CURRENT_TEST" not in os.environ
 22    ):
 23        return True
 24
 25    return (
 26        (sys.platform != "win32" or "ANSICON" in os.environ)
 27        and hasattr(file, "isatty")
 28        and file.isatty()
 29    )
 30
 31
 32STDOUT_ANSI_SUPPORT = guess_ansi_support(sys.stdout)
 33
 34
 35class PoeUi:
 36    args: "Namespace"
 37    _color: "Pastel"
 38
 39    def __init__(self, output: IO, program_name: str = "poe"):
 40        self.output = output
 41        self.program_name = program_name
 42        self._init_colors()
 43
 44    def _init_colors(self):
 45        from pastel import Pastel
 46
 47        self._color = Pastel(guess_ansi_support(self.output))
 48        self._color.add_style("u", "default", options="underline")
 49        self._color.add_style("hl", "light_gray")
 50        self._color.add_style("em", "cyan")
 51        self._color.add_style("em2", "cyan", options="italic")
 52        self._color.add_style("em3", "blue")
 53        self._color.add_style("h2", "default", options="bold")
 54        self._color.add_style("h2-dim", "default", options="dark")
 55        self._color.add_style("action", "light_blue")
 56        self._color.add_style("error", "light_red", options="bold")
 57
 58    def __getitem__(self, key: str):
 59        """Provide easy access to arguments"""
 60        return getattr(self.args, key, None)
 61
 62    def build_parser(self) -> "ArgumentParser":
 63        import argparse
 64
 65        parser = argparse.ArgumentParser(
 66            prog=self.program_name,
 67            description="Poe the Poet: A task runner that works well with poetry.",
 68            add_help=False,
 69            allow_abbrev=False,
 70        )
 71
 72        parser.add_argument(
 73            "-h",
 74            "--help",
 75            dest="help",
 76            action="store_true",
 77            default=False,
 78            help="Show this help page and exit",
 79        )
 80
 81        parser.add_argument(
 82            "--version",
 83            dest="version",
 84            action="store_true",
 85            default=False,
 86            help="Print the version and exit",
 87        )
 88
 89        parser.add_argument(
 90            "-v",
 91            "--verbose",
 92            dest="increase_verbosity",
 93            action="count",
 94            default=0,
 95            help="Increase command output (repeatable)",
 96        )
 97
 98        parser.add_argument(
 99            "-q",
100            "--quiet",
101            dest="decrease_verbosity",
102            action="count",
103            default=0,
104            help="Decrease command output (repeatable)",
105        )
106
107        parser.add_argument(
108            "-d",
109            "--dry-run",
110            dest="dry_run",
111            action="store_true",
112            default=False,
113            help="Print the task contents but don't actually run it",
114        )
115
116        parser.add_argument(
117            "-C",
118            "--directory",
119            dest="project_root",
120            metavar="PATH",
121            type=str,
122            default=os.environ.get("POE_PROJECT_DIR", None),
123            help="Specify where to find the pyproject.toml",
124        )
125
126        parser.add_argument(
127            "-e",
128            "--executor",
129            dest="executor",
130            metavar="EXECUTOR",
131            type=str,
132            default="",
133            help="Override the default task executor",
134        )
135
136        # legacy --root parameter, keep for backwards compatibility but help output is
137        # suppressed
138        parser.add_argument(
139            "--root",
140            dest="project_root",
141            metavar="PATH",
142            type=str,
143            default=None,
144            help=argparse.SUPPRESS,
145        )
146
147        ansi_group = parser.add_mutually_exclusive_group()
148        ansi_group.add_argument(
149            "--ansi",
150            dest="ansi",
151            action="store_true",
152            default=STDOUT_ANSI_SUPPORT,
153            help="Force enable ANSI output",
154        )
155        ansi_group.add_argument(
156            "--no-ansi",
157            dest="ansi",
158            action="store_false",
159            default=STDOUT_ANSI_SUPPORT,
160            help="Force disable ANSI output",
161        )
162
163        parser.add_argument("task", default=tuple(), nargs=argparse.REMAINDER)
164
165        return parser
166
167    def parse_args(self, cli_args: Sequence[str]):
168        self.parser = self.build_parser()
169        self.args = self.parser.parse_args(cli_args)
170        self.verbosity: int = self["increase_verbosity"] - self["decrease_verbosity"]
171        self._color.with_colors(self.args.ansi)
172
173    def set_default_verbosity(self, default_verbosity: int):
174        self.verbosity += default_verbosity
175
176    def print_help(
177        self,
178        tasks: Optional[
179            Mapping[str, Tuple[str, Sequence[Tuple[Tuple[str, ...], str, str]]]]
180        ] = None,
181        info: Optional[str] = None,
182        error: Optional[PoeException] = None,
183    ):
184        # TODO: See if this can be done nicely with a custom HelpFormatter
185
186        # Ignore verbosity mode if help flag is set
187        verbosity = 0 if self["help"] else self.verbosity
188
189        result: List[Union[str, Sequence[str]]] = []
190        if verbosity >= 0:
191            result.append(
192                (
193                    "Poe the Poet - A task runner that works well with poetry.",
194                    f"version <em>{__version__}</em>",
195                )
196            )
197
198        if info:
199            result.append(f"{f'<em2>Result: {info}</em2>'}")
200
201        if error:
202            # TODO: send this to stderr instead?
203            error_lines = []
204            if isinstance(error, ConfigValidationError):
205                if error.task_name:
206                    if error.context:
207                        error_lines.append(
208                            f"{error.context} in task {error.task_name!r}"
209                        )
210                    else:
211                        error_lines.append(f"Invalid task {error.task_name!r}")
212                    if error.filename:
213                        error_lines[-1] += f" in file {error.filename}"
214                elif error.global_option:
215                    error_lines.append(f"Invalid global option {error.global_option!r}")
216                    if error.filename:
217                        error_lines[-1] += f" in file {error.filename}"
218            error_lines.extend(error.msg.split("\n"))
219            if error.cause:
220                error_lines.append(error.cause)
221            if error.__cause__:
222                error_lines.append(f"From: {error.__cause__!r}")
223
224            result.append(self._format_error_lines(error_lines))
225
226        if verbosity >= 0:
227            result.append(
228                (
229                    "<h2>Usage:</h2>",
230                    f"  <u>{self.program_name}</u>"
231                    " [global options]"
232                    " task [task arguments]",
233                )
234            )
235
236            # Use argparse for optional args
237            formatter = self.parser.formatter_class(prog=self.parser.prog)
238            action_group = self.parser._action_groups[1]
239            formatter.start_section(action_group.title)
240            formatter.add_arguments(action_group._group_actions)
241            formatter.end_section()
242            result.append(
243                ("<h2>Global options:</h2>", *formatter.format_help().split("\n")[1:])
244            )
245
246            if tasks:
247                max_task_len = max(
248                    max(
249                        len(task),
250                        max(
251                            [
252                                len(", ".join(str(opt) for opt in opts))
253                                for (opts, _, _) in args
254                            ]
255                            or (0,)
256                        )
257                        + 2,
258                    )
259                    for task, (_, args) in tasks.items()
260                )
261                col_width = max(20, min(30, max_task_len))
262
263                tasks_section = ["<h2>Configured tasks:</h2>"]
264                for task, (help_text, args_help) in tasks.items():
265                    if task.startswith("_"):
266                        continue
267                    tasks_section.append(
268                        f"  <em>{self._padr(task, col_width)}</em>  "
269                        f"{self._align(help_text, col_width)}"
270                    )
271                    for options, arg_help_text, default in args_help:
272                        formatted_options = ", ".join(str(opt) for opt in options)
273                        task_arg_help = [
274                            "   ",
275                            f"<em3>{self._padr(formatted_options, col_width-1)}</em3>",
276                        ]
277                        if arg_help_text:
278                            task_arg_help.append(self._align(arg_help_text, col_width))
279                        if default:
280                            if "\n" in (arg_help_text or ""):
281                                task_arg_help.append(
282                                    self._align(f"\n{default}", col_width, strip=False)
283                                )
284                            else:
285                                task_arg_help.append(default)
286                        tasks_section.append(" ".join(task_arg_help))
287
288                result.append(tasks_section)
289
290            else:
291                result.append("<h2-dim>NO TASKS CONFIGURED</h2-dim>")
292
293        if error and os.environ.get("POE_DEBUG", "0") == "1":
294            import traceback
295
296            result.append("".join(traceback.format_exception(error)).strip())
297
298        self._print(
299            "\n\n".join(
300                section if isinstance(section, str) else "\n".join(section).strip("\n")
301                for section in result
302            )
303            + "\n"
304            + ("\n" if verbosity >= 0 else "")
305        )
306
307    @staticmethod
308    def _align(text: str, width: int, *, strip: bool = True) -> str:
309        text = text.replace("\n", "\n" + " " * (width + 4))
310        return text.strip() if strip else text
311
312    @staticmethod
313    def _padr(text: str, width: int):
314        if len(text) >= width:
315            return text
316        return text + " " * (width - len(text))
317
318    def print_msg(self, message: str, verbosity=0, end="\n"):
319        if verbosity <= self.verbosity:
320            self._print(message, end=end)
321
322    def print_error(self, error: Union[PoeException, ExecutionError]):
323        error_lines = error.msg.split("\n")
324        if error.cause:
325            error_lines.append(f"From: {error.cause}")
326        if error.__cause__:
327            error_lines.append(f"From: {error.__cause__!r}")
328
329        for line in self._format_error_lines(error_lines):
330            self._print(line)
331
332        if os.environ.get("POE_DEBUG", "0") == "1":
333            import traceback
334
335            self._print("".join(traceback.format_exception(error)).strip())
336
337    def _format_error_lines(self, lines: Sequence[str]):
338        return (
339            f"<error>Error: {lines[0]}</error>",
340            *(f"<error>     | {line}</error>" for line in lines[1:]),
341        )
342
343    def print_version(self):
344        if self.verbosity >= 0:
345            result = f"Poe the Poet - version: <em>{__version__}</em>\n"
346        else:
347            result = f"{__version__}\n"
348        self._print(result)
349
350    def _print(self, message: str, *, end: str = "\n"):
351        print(self._color.colorize(message), end=end, file=self.output, flush=True)