WIP: Help page customization low level api

Click の invoke フローと、既存の Command、Group、Context、help、およびエラー処理のパスから始めます。これらのエントリポイントを、提案されている CustomHelp、CustomHelpLoad、InvocationSource インターフェースと比較し、そのうえで、過剰に内部実装を公開することなく API が任意のネストをサポートできるかどうかを判断します。設計上の疑問が解決され、具体的でテスト可能な実装スコープについて合意できれば完了です。

Work in Progress ...

General

• help kwarg stays as is.

• for Commands and Groups, there are new kwargs

  • custom_help : None | Subclass of CustomHelp = a custom help class
  • custom_help_settings : None | Subclass of CustomHelpLoad = for lightly customized custom help classes
  • custom_help_settings_call: None | function = for heavily customized help classes

• There are two general types of help page, Group help page and Command help page.

• Help pages may be invoked directly, or shown following an error.

  • ??? custom_help_cascade : bool = True whether or not a custom help formatter cascades to sub command or sub groups. I expect the normal usage pattern to be set one custom fomatter per command line application, so just set in one place, at the top group. However, I can see good reason to allow this to be turned off.

Questions

• How do we uphold arbitrary nesting guarantees while allowing for maximal customization?
• Is this general idea feasible with Clicks current internal design, that is, are we able to expose everything a custom help page creator might want without exposing too many internals? My first thought is to try fix some of the entangling in Click by having invoke(top level) call the command/group to see if help has been invoked, then in invoke tell command to dump relevant data in a very flat way. The data is passed in as kwarg to CustomHelp constructor. CustomHelp creates the help page in a very stand alone way. Invoke calls CustomHelp.render() and exits.
• How does this impact creating error messages?

Examples

In Click

# in click
class InvocationSource(Enum, auto):
    COMMAND = auto()
    GROUP = auto()
    BOTH = auto()

class CustomHelpLoad(ABC):
    """Customization available to User"""


    @abstractmethod
    def __init__(self, arg_1, arg_2,):
        """By having a separate class, instead of dict, user can see 
        customization available on hover in editor.
        """


    @abstractmethod
    def dump(self,) -> dict:
        """Dump everything given by user to dictionary.""" 


class CustomHelp(ABC):
    """ In a relatively standalone way, make a help page.
    Must handle help pages and errors. 
    """

    @abstractmethod
    def __init__(
            self, 
            ctx: Context, 
            # Not right but too sick to fix issue.
            invocation_source_info: dict, 
            invocation_source: InvocationSource,  
            error: None|dict = None
            ):
        """ Load needed properties. 
        
        To support truly dynamic customization, the help page might need 
        any number of things, so a basically everything is injected as a 
        kwarg. Identify, what your implementation actually needs and 
        store it in a property. 
        
        Set default settings dict.
        """
        

    @abstractmethod
    def inject_settings(self, settings: CustomHelpLoad):
        """Load in the customized settings by merging default settings dict 
        with customized one.
        """
        
        #self.settings.update(CustomHelpLoad.dump())


    @abstractmethod
    def create(self):
        """Actually make the help page. Recommended to break into create error
        and create help."""
        

    @abstractmethod
    def render(self):
        """"Render output to the terminal"""

# click plugin implementation
class _ClickBuiltInHelpLoad(CustomHelpLoad):
    """"Base implementation will likely offer no customization."""
    
    def dump(self):
        return dict()


class _ClickBuiltInHelp(CustomHelp): 
    """"Implementing this will guide data and signature of ABC constructor"""

    def __init__(self):
        self.settings = {}

    def inject_settings(self, settings: _ClickBuiltInHelpLoad):
        self.settings.update(_ClickBuiltInHelpLoad.dump())

Click's own plugin classes will be private. When custom help is released, then a guide will be made that uses this as an example. But that will be just an example of how to implement the ABC. We will not expose this, so we can evolve it freely.

Plugin

class RichHelp(CustomHelp):
    """Rich implementation of help page."""

# By convention, named <CustomHelpName>Load
class RichHelpLoad(CustomHelpLoad):
    """Settings available for user customization."""


    def __init__(self, color='blue', mode='normal'):
        pass

    def dump(self):
        return dict()

User Code

import click 
from click_help_rich import RichHelp
from click_help_rich import RichHelpLoad


# drop in help customization 
@click.command(
    'one', 
    custom_help=RichHelp,
    custom_help_settings=RichHelpLoad(color='red'),
)
def one():
    pass 

# help heavily customized
# Much nicer for readability to have the option to factor into a function  
# Also this limits import time side effects. 
def rich_help_very_custom():
    return RichHelpLoad(
        color='red',
        mode='sharp',
    )


@click.command(
    'two', 
    custom_help=RichHelp,
    custom_help_settings_call=rich_help_very_custom,
)
def two():
    pass