Add column-aligned output support

Author: yzx9

CHANGELOG.rst

@@ -11,6 +11,7 @@ v4.6.0
 * The default value for ``path`` is now ``~/calendars/*``. Previously this
   value was required. This change is non-breaking; all existing valid
   configurations define this value.
+* Add a new `columns` option to enable column-aligned output.
 
 v4.5.0
 ------

docs/source/usage.rst

@@ -7,11 +7,11 @@ intentions is to also provide a fully `TUI`_-based interface).
 The default action is ``list``, which outputs all tasks for all calendars, each
 with a semi-permanent unique id::
 
-    1 [ ] !!! 2015-04-30 Close bank account @work (0%)
-    2 [ ] !              Send minipimer back for warranty replacement @home (0%)
-    3 [X]     2015-03-29 Buy soy milk @home (100%)
-    4 [ ] !!             Fix the iPad's screen @home (0%)
-    5 [ ] !!             Fix the Touchpad battery @work (0%)
+    [ ] 1 !!! 2015-04-30 Close bank account @work
+    [ ] 2   !            Send minipimer back for warranty replacement @home
+    [X] 3     2015-03-29 Buy soy milk @home
+    [ ] 4  !!            Fix the iPad's screen @home
+    [ ] 5  !!            Fix the Touchpad battery @work
 
 The columns, in order, are:
 

todoman/cli.py

@@ -12,6 +12,7 @@
 from typing import Callable
 from typing import Literal
 from typing import ParamSpec
+from typing import TextIO
 from typing import TypeVar
 
 import click
@@ -256,13 +257,15 @@ class AppContext:
     config: dict  # TODO: better typing
     db: Database
     formatter_class: type[formatters.Formatter]
+    columns: bool
 
     @cached_property
     def ui_formatter(self) -> formatters.Formatter:
         return formatters.DefaultFormatter(
             self.config["date_format"],
             self.config["time_format"],
             self.config["dt_separator"],
+            self.columns,
         )
 
     @cached_property
@@ -271,6 +274,7 @@ def formatter(self) -> formatters.Formatter:
             self.config["date_format"],
             self.config["time_format"],
             self.config["dt_separator"],
+            self.columns,
         )
 
 
@@ -300,6 +304,16 @@ def formatter(self) -> formatters.Formatter:
         "regardless."
     ),
 )
+@click.option(
+    "--columns",
+    default=None,
+    type=click.Choice(["always", "auto", "never"]),
+    help=(
+        "By default todoman will disable column-aligned output entirely (value "
+        "`never`). Set to `auto` to enable column-aligned output if stdout is a TTY, "
+        "or `always` to enable it regardless."
+    ),
+)
 @click.option(
     "--porcelain",
     is_flag=True,
@@ -328,10 +342,11 @@ def formatter(self) -> formatters.Formatter:
 @catch_errors
 def cli(
     click_ctx: click.Context,
-    colour: Literal["always"] | Literal["auto"] | Literal["never"],
+    columns: Literal["always", "auto", "never"] | None,
+    colour: Literal["always", "auto", "never"] | None,
     porcelain: bool,
-    humanize: bool,
-    config: str,
+    humanize: bool | None,
+    config: str | None,
 ) -> None:
     ctx = click_ctx.ensure_object(AppContext)
     try:
@@ -354,6 +369,11 @@ def cli(
     else:
         ctx.formatter_class = formatters.DefaultFormatter
 
+    if columns == "auto":
+        ctx.columns = isinstance(sys.stdout, TextIO) and sys.stdout.isatty()
+    else:
+        ctx.columns = columns == "always"
+
     colour = colour or ctx.config["color"]
     if colour == "always":
         click_ctx.color = True

todoman/formatters.py

@@ -11,6 +11,8 @@
 from datetime import timezone
 from datetime import tzinfo
 from time import mktime
+from typing import Callable
+from typing import Literal
 
 import click
 import humanize
@@ -36,13 +38,30 @@ def rgb_to_ansi(colour: str | None) -> str | None:
     return f"\33[38;2;{int(r, 16)!s};{int(g, 16)!s};{int(b, 16)!s}m"
 
 
+class Column:
+    format: Callable[[Todo], str]
+    style: Callable[[Todo, str], str] | None
+    align_direction: Literal["left", "right"] = "left"
+
+    def __init__(
+        self,
+        format: Callable[[Todo], str],
+        style: Callable[[Todo, str], str] | None = None,
+        align_direction: Literal["left", "right"] = "left",
+    ) -> None:
+        self.format = format
+        self.style = style
+        self.align_direction = align_direction
+
+
 class Formatter(ABC):
     @abstractmethod
     def __init__(
         self,
         date_format: str = "%Y-%m-%d",
         time_format: str = "%H:%M",
         dt_separator: str = " ",
+        align: bool = False,
     ) -> None:
         """Create a new formatter instance."""
 
@@ -56,7 +75,7 @@ def compact_multiple(self, todos: Iterable[Todo], hide_list: bool = False) -> st
 
     @abstractmethod
     def simple_action(self, action: str, todo: Todo) -> str:
-        """Render an action related to a todo (e.g.: compelete, undo, etc)."""
+        """Render an action related to a todo (e.g.: complete, undo, etc)."""
 
     @abstractmethod
     def parse_priority(self, priority: str | None) -> int | None:
@@ -97,6 +116,7 @@ def __init__(
         date_format: str = "%Y-%m-%d",
         time_format: str = "%H:%M",
         dt_separator: str = " ",
+        align: bool = False,
         tz_override: tzinfo | None = None,
     ) -> None:
         self.date_format = date_format
@@ -105,6 +125,7 @@ def __init__(
         self.datetime_format = dt_separator.join(
             filter(bool, (date_format, time_format))
         )
+        self.align = align
 
         self.tz = tz_override or tzlocal()
         self.now = datetime.now().replace(tzinfo=self.tz)
@@ -123,48 +144,94 @@ def compact_multiple(self, todos: Iterable[Todo], hide_list: bool = False) -> st
         # TODO: format lines fuidly and drop the table
         # it can end up being more readable when too many columns are empty.
         # show dates that are in the future in yellow (in 24hs) or grey (future)
-        table = []
-        for todo in todos:
-            completed = "X" if todo.is_completed else " "
-            percent = todo.percent_complete or ""
-            if percent:
-                percent = f" ({percent}%)"
 
-            if todo.categories:
-                categories = " [" + ", ".join(todo.categories) + "]"
-            else:
-                categories = ""
+        columns = {
+            "completed": Column(
+                format=lambda todo: "[X]" if todo.is_completed else "[ ]"
+            ),
+            "id": Column(lambda todo: str(todo.id), align_direction="right"),
+            "priority": Column(
+                format=lambda todo: self.format_priority_compact(todo.priority),
+                style=lambda todo, value: click.style(value, fg="magenta"),
+                align_direction="right",
+            ),
+            "due": Column(
+                format=lambda todo: str(
+                    self.format_datetime(todo.due) or "(no due date)"
+                ),
+                style=lambda todo, value: click.style(value, fg=c)
+                if (c := self._due_colour(todo))
+                else value,
+            ),
+            "report": Column(format=self.format_report),
+        }
+
+        table = self.format_rows(columns, todos)
+        if self.align:
+            table = self.align_rows(columns, table)
 
-            priority = click.style(
-                self.format_priority_compact(todo.priority),
-                fg="magenta",
+        table = self.style_rows(columns, table)
+        return "\n".join(table)
+
+    def format_rows(
+        self, columns: dict[str, Column], todos: Iterable[Todo]
+    ) -> Iterable[tuple[Todo, list[str]]]:
+        for todo in todos:
+            yield (todo, [columns[col].format(todo) for col in columns])
+
+    def align_rows(
+        self,
+        columns: dict[str, Column],
+        rows: Iterable[tuple[Todo, list[str]]],
+    ) -> Iterable[tuple[Todo, list[str]]]:
+        max_lengths = [0 for _ in columns]
+        rows = list(rows)  # materialize the iterator
+        for _, cols in rows:
+            for i, col in enumerate(cols):
+                if len(col) > max_lengths[i]:
+                    max_lengths[i] = len(col)
+
+        for todo, cols in rows:
+            yield (
+                todo,
+                [
+                    col.ljust(max_lengths[i])
+                    if conf.align_direction == "left"
+                    else col.rjust(max_lengths[i])
+                    for i, (col, conf) in enumerate(zip(cols, columns.values()))
+                ],
             )
 
-            due = self.format_datetime(todo.due) or "(no due date)"
-            due_colour = self._due_colour(todo)
-            if due_colour:
-                due = click.style(str(due), fg=due_colour)
+    def style_rows(
+        self,
+        columns: dict[str, Column],
+        rows: Iterable[tuple[Todo, list[str]]],
+    ) -> Iterable[str]:
+        for todo, cols in rows:
+            yield " ".join(
+                conf.style(todo, col) if conf.style else col
+                for col, conf in zip(cols, columns.values())
+            )
 
-            recurring = "⟳" if todo.is_recurring else ""
+    def format_report(self, todo: Todo, hide_list: bool = False) -> str:
+        percent = todo.percent_complete or ""
+        if percent:
+            percent = f" ({percent}%)"
 
-            if hide_list:
-                summary = f"{todo.summary} {percent}"
-            else:
-                if not todo.list:
-                    raise ValueError("Cannot format todo without a list")
+        categories = " [" + ", ".join(todo.categories) + "]" if todo.categories else ""
 
-                summary = f"{todo.summary} {self.format_database(todo.list)}{percent}"
+        recurring = "⟳" if todo.is_recurring else ""
 
-            # TODO: add spaces on the left based on max todos"
+        if hide_list:
+            summary = f"{todo.summary} {percent}"
+        else:
+            if not todo.list:
+                raise ValueError("Cannot format todo without a list")
 
-            # FIXME: double space when no priority
-            # split into parts to satisfy linter line too long
-            table.append(
-                f"[{completed}] {todo.id} {priority} {due} "
-                f"{recurring}{summary}{categories}"
-            )
+            summary = f"{todo.summary} {self.format_database(todo.list)}{percent}"
 
-        return "\n".join(table)
+        # TODO: add spaces on the left based on max todos"
+        return f"{recurring}{summary}{categories}"
 
     def _due_colour(self, todo: Todo) -> str:
         now = self.now if isinstance(todo.due, datetime) else self.now.date()