🚨 Make linter happy, more syntax forms for category color

Author: phoenixr-codes

CHANGELOG.md

@@ -15,6 +15,8 @@
 ### Changed
 
 - Require Python 3.13 or greater.
+- Categories now support all syntax for colors supported by the `adorable2`
+  package.
 - Deprecate `powercli.utils.static` in favor of `powercli.static.Static`.
 - Better support for inspecting subcommand arguments (via
   `powercli.parser.ParsedCommand.subcommand()`).

examples/compiler.py

@@ -1,6 +1,7 @@
 import sys
 from typing import Any
 
+from adorable.common import YELLOW, AQUA, GREEN
 from loguru import logger
 from rich import print
 
@@ -10,15 +11,15 @@
 logger.enable("powercli.command")
 logger.add(sys.stdout, level="TRACE")
 
-category_pm = Category("package management")
-category_build = Category("build")
-category_output = Category("output")
+category_pm = Category("package management", color=AQUA)
+category_build = Category("build", color=GREEN)
+category_output = Category("output", color=YELLOW)
 
 cmd: Command[Any, Any] = Command(
     name="nullc",
     description="The C compiler that does not actually do anything at all",
     examples=[
-        Example(["run main.c"], "Compile and run a C program"),
+        Example(["run", "main.c"], "Compile and run a C program"),
         Example(["compile", "main.c", "-o", "main"], "Compile a C program"),
     ],
 )

examples/deprecation.py

@@ -1,7 +1,6 @@
 import sys
 
 from loguru import logger
-from rich import print
 
 from powercli import Command, Static
 from powercli.deprecation import Deprecation

powercli/_help_utils.py

@@ -18,6 +18,7 @@
 ]
 
 import builtins
+import shlex
 import shutil
 from collections.abc import Collection
 from functools import partial
@@ -27,6 +28,7 @@
 
 import wraptext
 from adorable import ansi, color
+from adorable.color import Color, RGB
 from adorable.common import BLACK, BOLD, MAROON, NAVY
 
 from .static import Static
@@ -40,6 +42,17 @@
 PROMPT_PREFIX = "$"
 
 
+def _color_for_category(category: Category | None) -> Color[Any]:
+    if category is None:
+        return color.Colorless.from_rgb(0)
+    elif isinstance(category.color, Color):
+        return category.color
+    else:
+        return color.from_rgb(
+            category.color or blake2s(category.title.encode()).digest()[0]
+        )
+
+
 # See also: https://phoenixr-codes.github.io/adorable/caution-ansi-strings.html#getting-the-visible-length-of-a-string
 def len(x: Any, /) -> int:
     """Returns the length of an object.
@@ -196,9 +209,8 @@ def examples(cmd: Command[Any, Any]) -> str:
             lines.append(
                 f"{BOLD:{_indent_text(example.description, indent='  ', indent_initial=True)}}"
             )
-        # TODO: shlex escape args
         command_line = (
-            f"{PROMPT_PREFIX} {cmd._subcommand_path()} {' '.join(example.args)}"
+            f"{PROMPT_PREFIX} {cmd._subcommand_path()} {' '.join(shlex.quote(arg) for arg in example.args)}"
         )
         # TODO: syntax highlighting
         lines.append(_indent_text(command_line, indent="  ", indent_initial=True))
@@ -210,13 +222,7 @@ def pretty_flag(cmd: Command[Any, Any], flag: Flag[Any, Any, Any]) -> str:
     """Returns a descriptive information for a flag."""
     parts = []
     category = flag.category
-    clr = (
-        ansi.empty()
-        if category is None
-        else color.from_rgb(
-            category.color or blake2s(category.title.encode()).digest()[0]
-        )
-    )
+    clr = _color_for_category(category)
     if flag.short is not None and cmd.prefix_short is not None:
         parts.extend(
             [f"{clr:{cmd.prefix_short + name}}" for name in flag.visible_short_names()]
@@ -264,13 +270,7 @@ def commands(cmd: Command[Any, Any]) -> str:
         cmds = categories.setdefault(command.category, [])
         cmds.append(command)
     for category, commands in categories.items():
-        clr = (
-            ansi.empty()
-            if category is None
-            else color.from_rgb(
-                category.color or blake2s(category.title.encode()).digest()[0]
-            )
-        )
+        clr = _color_for_category(category)
         for command in commands:
             lines.extend(
                 _add_description(

powercli/category.py

@@ -3,13 +3,11 @@
 from __future__ import annotations
 
 __all__ = ["Color", "Category"]
-from typing import TypeAlias
+from typing import Any
 
+from adorable.color import RGB, Color
 from attrs import define, field
 
-Color: TypeAlias = int
-"""A RGB color."""
-
 
 @define(hash=True, eq=True)
 class Category:
@@ -18,5 +16,5 @@ class Category:
     title: str
     """The title of the category."""
 
-    color: Color | None = field(default=None, kw_only=True)
+    color: RGB | Color[Any] | None = field(default=None, kw_only=True)
     """An optional color for the category."""

powercli/common.py

@@ -17,7 +17,6 @@
 import sys
 from typing import Any, Never, cast
 
-from . import parser
 from ._help_utils import _add_description, help_message
 from .args import Flag
 from .command import Command
@@ -71,9 +70,7 @@ def _subcommand_of_parent(self, name: str) -> Command[Never, Never]:
                 return cmd
         raise RuntimeError(f"no command name {name!r}")
 
-    def parse_args(
-        self, args: list[str] | None = None
-    ) -> Never:
+    def parse_args(self, args: list[str] | None = None) -> Never:
         """Parses arguments like {py:meth}`powercli.command.Command.parse_args`.
 
         This function will print a help message and exit.
@@ -154,9 +151,7 @@ def __init__(
         super().__init__(name=name, description=description, **kwargs)
         self.version = version
 
-    def parse_args(
-        self, args: list[str] | None = None
-    ) -> Never:
+    def parse_args(self, args: list[str] | None = None) -> Never:
         """Parses arguments like {py:meth}`powercli.command.Command.parse_args`.
 
         This function will print the version and exit.
@@ -231,9 +226,7 @@ def __init__(
         """Initializes the list command."""
         super().__init__(name=name, description=description, **kwargs)
 
-    def parse_args(
-        self, args: list[str] | None = None
-    ) -> Never:
+    def parse_args(self, args: list[str] | None = None) -> Never:
         """Parses arguments like {py:meth}`powercli.command.Command.parse_args`.
 
         This function will print a list of subcommands and exit.

powercli/utils.py

@@ -2,13 +2,13 @@
 
 from __future__ import annotations
 
-__all__ = ["static", "one_of", "ArgIterator"]
+__all__ = ["static", "member_of", "one_of", "ArgIterator"]
 import difflib
 from collections import deque
-from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
+from collections.abc import Iterable, Iterator, Sequence
 from enum import StrEnum
-from typing import TYPE_CHECKING, Any
-from warnings import deprecated, warn
+from typing import TYPE_CHECKING
+from warnings import deprecated
 
 from attrs import define
 

powerdoc/cli.py

@@ -1,4 +1,3 @@
-from copy import deepcopy
 from pathlib import Path
 from typing import Any