WIP: Help page customization low level api

Aperta
  • Qualcosa non va?
#3,097 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
20/100
Tipo di issue
Funzionalità
Chiarezza
Da chiarire
Stato di attività
Tranquilla
Stack tecnologico
python
Ambito
cli

Direzione di ricerca

Inizia con il flusso di invoke di Click e i percorsi esistenti di Command, Group, Context, help e gestione degli errori. Confronta questi punti di ingresso con le interfacce proposte CustomHelp, CustomHelpLoad e InvocationSource, quindi determina se l’API può supportare un annidamento arbitrario senza esporre eccessivamente i dettagli interni. Il lavoro è completato quando le questioni di progettazione sono risolte e viene concordato un ambito di implementazione concreto e verificabile.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

help output

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
Lingua principale
Python
Stelle
17.8k
Fork
3.3k
Merge medio
3g 3h
PR unite (30g)
13

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di pallets/click

Tutte le issue di pallets/click

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.