pyclack-lib 1.0.0__py3-none-any.whl

pyclack/__init__.py

@@ -0,0 +1,7 @@
+from .config import set_print_mode_ascii as set_print_mode_ascii
+from .config import set_active_theme as set_active_theme
+from .config import get_active_theme as get_active_theme
+from .prompts import CancelException as CancelException
+from .prompts import ClackOption as ClackOption
+from .prompts import Alignment as Alignment
+from .renderer import Themes as Themes

pyclack/config/__init__.py

@@ -0,0 +1,3 @@
+from .theme_conf import set_active_theme as set_active_theme
+from .theme_conf import get_active_theme as get_active_theme
+from .theme_conf import set_print_mode_ascii as set_print_mode_ascii

pyclack/config/theme_conf.py

@@ -0,0 +1,32 @@
+from ..renderer import Theme, Themes
+from ..renderer import symbols
+
+active_theme: Theme = Themes.DEFAULT
+
+def set_active_theme(theme: Theme) -> None:
+    '''
+    Set the active theme for the application. This function updates the global variable `active_theme` to the provided theme.
+
+    Args:
+        theme (Theme): The theme to set as active.
+    '''
+
+    global active_theme
+    active_theme = theme
+
+def get_active_theme() -> Theme:
+    '''
+    Get the currently active theme for the application.
+
+    Returns:
+        Theme: The currently active theme.
+    '''
+
+    return active_theme
+
+def set_print_mode_ascii():
+    '''
+    Set the print mode to always use ASCII symbols. This function updates the global variable `always_use_ascii` to True.
+    '''
+
+    symbols.always_use_ascii = True

pyclack/prompts/__init__.py

@@ -0,0 +1,19 @@
+from .prompt_base import CancelException as CancelException
+from .prompt_base import PromptState as PromptState
+from .prompt_base import PromptBase as PromptBase
+from .prompt_base import ClackOption as ClackOption
+from .prompt_base import Alignment
+from . import util as util
+
+# Prompts
+from .ask import ask as ask
+from .password import password as password
+from .confirm import confirm as confirm
+from .pick_date import pick_date as pick_date
+from .multiline import multiline as multiline
+from .select import select as select
+from .multiselect import multiselect as multiselect
+from .autocomplete import autocomplete as autocomplete
+from .autocomplete_multiselect import autocomplete_multiselect as autocomplete_multiselect
+from .select_key import select_key as select_key
+from .select_path import select_path as select_path

pyclack/prompts/ask.py

@@ -0,0 +1,258 @@
+from .util import build_wrapped_lines, build_message_header, build_message_close, apply_cursor_style, TextBoxController
+from ..renderer import RenderFrame, Text, FrameBuilder, Style, Theme
+from .prompt_base import PromptBase, CancelException
+from ..terminal import CursorController as cc
+from typing import Callable, override
+from ..config import get_active_theme
+from ..terminal import Stdout
+from copy import copy
+
+def ask(message: str, 
+        placeholder: str | None = None, 
+        initial_value: str | None = None, 
+        validate: Callable[[str], str | None] | None = None,
+        abort_time: float | None = None) -> str:
+    '''
+    Ask the user for input with a message, placeholder, initial value, and validation function.
+    Controls are as follows:
+    - Use the arrow keys to move the cursor within the input.
+    - Press 'Enter' to submit the input.
+    - Press 'Backspace' to delete the character before the cursor.
+    - Press 'Ctrl+C' or 'esc' to cancel the operation.
+
+    Args:
+        message (str): The message to display to the user.
+        placeholder (str, optional): The placeholder text to display when the input is empty.
+        initial_value (str, optional): The initial value of the input.
+        validate (Callable[[str], str | None], optional): A function to validate the input.
+        abort_time (float, optional): Floating point number representing seconds in time before the prompt is auto-cancelled, if set to None the prompt will never auto-cancel. Defaults to None.
+
+    Returns:
+        str: The user's input.
+
+    Raises:
+        CancelException: If the user cancels the operation.
+    '''
+    
+    prompt: Ask = Ask(message, placeholder, initial_value, validate, abort_time)
+    return prompt.text_box_controller.get_input()
+
+class Ask(PromptBase):
+    '''
+    A prompt for asking the user for text input.
+    '''
+
+    def __init__(self,
+            message: str,
+            placeholder: str | None,
+            initial_value: str | None,
+            validate: Callable[[str], str | None] | None,
+            abort_time: float | None):
+        '''
+        Initialize an Ask prompt.
+
+        Args:
+            message (str): The message to display to the user.
+            placeholder (str, optional): The placeholder text to display when the input is empty.
+            initial_value (str, optional): The initial value of the input.
+            validate (Callable[[str], str | None], optional): A function to validate the input.
+            abort_time (float, optional): Floating point number representing seconds in time before the prompt is auto-cancelled, if set to None the prompt will never auto-cancel. Defaults to None.
+
+        Raises:
+            CancelException: If the user cancels the operation.
+        '''
+
+        super().__init__()
+
+        self.message: str = message
+        self.placeholder: str | None = placeholder
+        self.initial_value: str | None = initial_value
+        self.validate: Callable[[str], str | None] | None = validate
+
+        self.render_frame: RenderFrame = RenderFrame()
+        self.text_box_controller: TextBoxController = TextBoxController()
+        if initial_value: 
+            self.text_box_controller.set_input(initial_value, 0)
+            self.text_box_controller.cursor_end()
+        
+        self.propagate_key_after_error = True
+        self.abort_time = abort_time
+        
+        self.allowed_inputs: tuple[str, ...] = self._construct_allowed_inputs()
+
+        super().activate()
+
+    def _construct_allowed_inputs(self) -> tuple[str, ...]:
+        '''
+        Construct a tuple of allowed inputs for the prompt.
+
+        Returns:
+            tuple[str]: A tuple of allowed input keys.
+        '''
+
+        allowed_chars: tuple[str, ...] = tuple(chr(i) for i in range(32, 127))
+        return ('BACKSPACE', 'ENTER', 'LEFT', 'RIGHT', 'TAB', 'SPACE') + allowed_chars
+
+    @override
+    def handle_active(self, key: str | None) -> bool:
+        Stdout.put(cc.hide_cursor())
+
+        if key not in self.allowed_inputs: key = ''
+
+        theme: Theme = get_active_theme()
+        step_marker_active: str = theme.symbols.step_marker_active.resolve()
+        connector_bar_vertical: str = theme.symbols.connector_bar_vertical.resolve()
+        connector_bar_end: str = theme.symbols.connector_bar_end.resolve()
+        prefix_active: Text = Text(f'{connector_bar_vertical}  ', theme.active)
+        prefix_muted: Text = Text(f'{connector_bar_vertical}  ', theme.muted)
+
+        match key:
+            case 'BACKSPACE': self.text_box_controller.delete()
+            case 'ENTER': return True # Advance to the next state (submit)
+            case 'LEFT': self.text_box_controller.cursor_left()
+            case 'RIGHT': self.text_box_controller.cursor_right()
+            case _:
+                map: dict[str, str] = {
+                    'SPACE': ' ',
+                    'TAB': '\t'}  
+                char: str = map.get(key, key) # Translate key to character (if applicable)
+                if key != '': self.text_box_controller.insert(char)
+
+        # Create and render next frame based on the current input buffer and state
+        input_buffer: str = self.text_box_controller.get_input()
+        input_index: int = self.text_box_controller.get_cursor_position()
+
+        frame_builder: FrameBuilder = FrameBuilder()
+        frame_builder.add_line(prefix_muted)
+        message_lines: list[Text] = build_message_header(
+            self.message, 
+            theme.text, 
+            f'{step_marker_active}  ', 
+            theme.active, 
+            prefix_active)
+        frame_builder.add_lines(*message_lines)
+ 
+        if self.placeholder and len(input_buffer) <= 0:
+            placeholder_text: Text = Text(self.placeholder, theme.muted)
+            placeholder_text = apply_cursor_style(placeholder_text, 0, theme.cursor)
+            frame_builder.add_lines(*build_wrapped_lines(placeholder_text, prefix_active))
+        else:
+            input_buffer_text: Text = Text(input_buffer, theme.text)
+            input_buffer_text = apply_cursor_style(input_buffer_text, input_index, theme.cursor)
+            frame_builder.add_lines(*build_wrapped_lines(input_buffer_text, prefix_active))
+ 
+        frame_builder.add_line(Text(connector_bar_end, theme.active))
+ 
+        frame: tuple[Text, ...] = frame_builder.build()
+        self.render_frame.draw_frame(*frame)
+        return False
+
+    @override
+    def handle_submit(self) -> bool:
+        theme: Theme = get_active_theme()
+        step_marker_submit: str = theme.symbols.step_marker_submit.resolve()
+        connector_bar_vertical: str = theme.symbols.connector_bar_vertical.resolve()
+        prefix_muted: Text = Text(f'{connector_bar_vertical}  ', theme.muted)
+
+        # Create and render next frame based on the current input buffer and state
+        input_buffer: str = self.text_box_controller.get_input()
+
+        frame_builder: FrameBuilder = FrameBuilder()
+        frame_builder.add_line(prefix_muted)
+        message_lines: list[Text] = build_message_header(
+            self.message,
+            theme.text,
+            f'{step_marker_submit}  ',
+            theme.submit,
+            prefix_muted)
+        frame_builder.add_lines(*message_lines)
+        
+        input_buffer_text: Text = Text(input_buffer, theme.muted)
+        frame_builder.add_lines(*build_wrapped_lines(input_buffer_text, prefix_muted))
+        
+        frame: tuple[Text, ...] = frame_builder.build()
+        self.render_frame.draw_frame(*frame)
+
+        Stdout.put(cc.show_cursor())
+        return False if self.validate and self.validate(input_buffer) else True
+
+    @override
+    def handle_error(self, key: str | None) -> bool:
+        Stdout.put(cc.hide_cursor())
+
+        theme: Theme = get_active_theme()
+        step_marker_error: str = theme.symbols.step_marker_error.resolve()
+        connector_bar_vertical: str = theme.symbols.connector_bar_vertical.resolve()
+        connector_bar_end: str = theme.symbols.connector_bar_end.resolve()
+        prefix_muted: Text = Text(f'{connector_bar_vertical}  ', theme.muted)
+        prefix_error: Text = Text(f'{connector_bar_vertical}  ', theme.error)
+        closing_prefix_error: Text = Text(f'{connector_bar_end}  ', theme.error)
+
+        # Create and render next frame based on the current input buffer and state
+        input_buffer: str = self.text_box_controller.get_input()
+        input_index: int = self.text_box_controller.get_cursor_position()
+
+        frame_builder: FrameBuilder = FrameBuilder()
+        frame_builder.add_line(prefix_muted)
+        message_lines: list[Text] = build_message_header(
+            self.message,
+            theme.text,
+            f'{step_marker_error}  ',
+            theme.error,
+            prefix_error)
+        frame_builder.add_lines(*message_lines)
+        
+        if self.placeholder and len(input_buffer) <= 0:
+            placeholder_text: Text = Text(self.placeholder, theme.muted)
+            placeholder_text = apply_cursor_style(placeholder_text, 0, theme.cursor)
+            frame_builder.add_lines(*build_wrapped_lines(placeholder_text, prefix_error))
+        else:
+            input_buffer_text: Text = Text(input_buffer, theme.text)
+            input_buffer_text = apply_cursor_style(input_buffer_text, input_index, theme.cursor)
+            frame_builder.add_lines(*build_wrapped_lines(input_buffer_text, prefix_error))
+
+        validation_error_message: str = self.validate(input_buffer) # self.validate must be defined if we are in the error state, and it must return something
+        error_lines: list[Text] = build_message_close(
+            validation_error_message,
+            theme.error,
+            prefix_error,
+            closing_prefix_error)
+        frame_builder.add_lines(*error_lines)
+
+        frame: tuple[Text, ...] = frame_builder.build()
+        self.render_frame.draw_frame(*frame)
+
+        if key == 'ENTER' or key is None: return False
+        else: return True
+
+    @override
+    def handle_cancel(self) -> None:
+        theme: Theme = get_active_theme()
+        step_marker_cancel: str = theme.symbols.step_marker_cancel.resolve()
+        connector_bar_vertical: str = theme.symbols.connector_bar_vertical.resolve()
+        prefix_muted: Text = Text(f'{connector_bar_vertical}  ', theme.muted)
+
+        # Create and render next frame based on the current input buffer and state
+        input_buffer: str = self.text_box_controller.get_input()
+
+        frame_builder: FrameBuilder = FrameBuilder()
+        frame_builder.add_line(prefix_muted)
+        message_lines: list[Text] = build_message_header(
+            self.message,
+            theme.text,
+            f'{step_marker_cancel}  ',
+            theme.cancel,
+            prefix_muted)
+        frame_builder.add_lines(*message_lines)
+
+        text_style: Style = copy(theme.muted)
+        text_style.strikethrough = True
+        if len(input_buffer) > 0:
+            input_buffer_text: Text = Text(input_buffer, text_style)
+            frame_builder.add_lines(*build_wrapped_lines(input_buffer_text, prefix_muted))  
+        
+        frame: tuple[Text, ...] = frame_builder.build()
+        self.render_frame.draw_frame(*frame)
+
+        Stdout.put(cc.show_cursor())
+        raise CancelException(input_buffer)