WIP: Help page customization low level api

Đang mở
  • Có gì không ổn?
#3,097 2 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
20/100
Loại issue
Tính năng
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Ít trao đổi
Công nghệ
python
Lĩnh vực
cli

Hướng nghiên cứu

Bắt đầu với luồng invoke của Click và các đường dẫn hiện có của Command, Group, Context, help và xử lý lỗi. So sánh các điểm vào đó với các interface CustomHelp, CustomHelpLoad và InvocationSource được đề xuất, sau đó xác định liệu API có thể hỗ trợ việc lồng nhau tùy ý mà không để lộ quá nhiều chi tiết nội bộ hay không. Được coi là hoàn tất khi các câu hỏi về thiết kế đã được giải quyết và một phạm vi triển khai cụ thể, có thể kiểm thử đã được thống nhất.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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
Ngôn ngữ chính
Python
Star
17.8k
Fork
3.3k
Merge trung bình
3 ngày 3 giờ
Pull request đã merge (30 ngày)
13

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của pallets/click

Tất cả issue của pallets/click

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.