From 2cdf8f62f59359e15efc1d32df99a00295977dcb Mon Sep 17 00:00:00 2001 From: guillemdb Date: Fri, 20 Sep 2024 09:58:35 +0200 Subject: [PATCH] Fix typos. Add docs to terminal_effects Signed-off-by: guillemdb --- src/hydraclick/terminal_effects.py | 140 +++++++++++++++++++++++++---- 1 file changed, 121 insertions(+), 19 deletions(-) diff --git a/src/hydraclick/terminal_effects.py b/src/hydraclick/terminal_effects.py index 8271f38..3270423 100644 --- a/src/hydraclick/terminal_effects.py +++ b/src/hydraclick/terminal_effects.py @@ -7,8 +7,22 @@ from click import Context, Option -def get_no_terminal_efects() -> bool: - """Get the no terminal effects environment variable.""" +def get_no_terminal_effects() -> bool: + """ + Check if terminal effects should be disabled by looking at environment variables. + + This function checks the environment variables `OMEGACLICK_NO_TERMINAL_EFFECTS` + and `NO_TERMINAL_EFFECTS` to determine if terminal effects should be disabled. + If no environment variable is set, it returns `False`. + + Returns: + bool: `True` if terminal effects should be disabled, `False` otherwise. + + Example: + >>> os.environ["NO_TERMINAL_EFFECTS"] = "true" + >>> get_no_terminal_effects() + True + """ val = os.environ.get("OMEGACLICK_NO_TERMINAL_EFFECTS", os.environ.get("NO_TERMINAL_EFFECTS")) if val is None: return False @@ -16,7 +30,23 @@ def get_no_terminal_efects() -> bool: def config_effect(effect): - """Configure the terminal effect.""" + """ + Configure terminal effects such as print speed and gradient colors. + + This function adjusts the terminal effect's configuration, such as print speed, + return speed, and gradient colors for rendering. + + Args: + effect: The terminal effect object to be configured. + + Returns: + The modified terminal effect object. + + Example: + >>> effect = SomeEffect() + >>> config_effect(effect) + + """ from terminaltexteffects.utils.graphics import Color # noqa: PLC0415 effect.effect_config.print_speed = 15 @@ -26,17 +56,39 @@ def config_effect(effect): def remove_lines(num_lines: int): - """Remove the last `num_lines` printed lines from the terminal.""" + """ + Remove the last `num_lines` lines printed in the terminal. + + This function sends ANSI escape codes to move the terminal cursor up and clear + the last `num_lines` lines from the terminal. + + Args: + num_lines (int): The number of lines to remove. + + Example: + >>> remove_lines(3) # Removes the last 3 printed lines + """ for _ in range(num_lines): - # Move the cursor up one line - sys.stdout.write("\x1b[1A") - # Clear the entire line - sys.stdout.write("\x1b[2K") + sys.stdout.write("\x1b[1A") # Move the cursor up one line + sys.stdout.write("\x1b[2K") # Clear the entire line sys.stdout.flush() -def count_wrapped_lines(text: str, terminal_width: int): - """Count the number of lines that the text will take when wrapped.""" +def count_wrapped_lines(text: str, terminal_width: int) -> int: + """ + Calculate the number of lines the given text will take when wrapped in the terminal. + + Args: + text (str): The text to be wrapped. + terminal_width (int): The width of the terminal in characters. + + Returns: + int: The number of lines the text will occupy in the terminal. + + Example: + >>> count_wrapped_lines("This is a long line of text.", 10) + 3 + """ lines = text.splitlines() total_lines = 0 for line in lines: @@ -48,33 +100,61 @@ def count_wrapped_lines(text: str, terminal_width: int): return total_lines -def display_terminal_effect(value, effect_cls=None): - """Display the terminal effect.""" +def display_terminal_effect(value: str, effect_cls=None): + """ + Display a terminal effect animation for a given text. + + This function displays a text-based terminal effect using the provided effect class. + The effect is rendered with custom configurations, and once the animation is complete, + the effect is cleaned up from the terminal. + + Args: + value (str): The text to display with the terminal effect. + effect_cls (optional): The class of the terminal effect to use. Defaults to `Print`. + + Example: + >>> display_terminal_effect("Hello World!") + """ from terminaltexteffects.effects.effect_print import Print # noqa: PLC0415 effect_cls = effect_cls or Print effect = effect_cls(value) effect = config_effect(effect) + with effect.terminal_output() as terminal: for frame in effect: terminal.print(frame) + terminal_width = shutil.get_terminal_size().columns n_lines_last_rendered_frame = count_wrapped_lines(frame, terminal_width) remove_lines(n_lines_last_rendered_frame) + last_effect = effect_cls(value) last_effect = config_effect(last_effect) last_effect.terminal_config.ignore_terminal_dimensions = True last_frame = list(last_effect)[-1] + sys.stdout.write(last_frame.lstrip()) sys.stdout.write("\n") sys.stdout.flush() def patch_parse_args(terminal_effect: Callable): - """Patch the click `get_help_option` function with a custom terminal effect.""" + """ + Patch the Click `parse_args` function to display a terminal effect when no arguments are provided. + + This function overrides the `parse_args` method of Click's `MultiCommand` to + display a custom terminal effect for the help message when no arguments are passed. + + Args: + terminal_effect (Callable): A callable that renders the terminal effect. + + Example: + >>> patch_parse_args(display_terminal_effect) + """ def parse_args(self, ctx: Context, args: list[str]) -> list[str]: - """Display the help message when no arguments are provided.""" + """Display the help message with terminal effects when no arguments are provided.""" if not args and self.no_args_is_help and not ctx.resilient_parsing: terminal_effect(ctx.get_help()) ctx.exit() @@ -91,10 +171,21 @@ def parse_args(self, ctx: Context, args: list[str]) -> list[str]: def patch_get_help_option(terminal_effect: Callable): - """Patch the click `get_help_option` function with a custom terminal effect.""" + """ + Patch the Click `get_help_option` function to display a terminal effect for the help option. + + This function overrides Click's `get_help_option` method to display a terminal + effect whenever the help message is requested. + + Args: + terminal_effect (Callable): A callable that renders the terminal effect. + + Example: + >>> patch_get_help_option(display_terminal_effect) + """ def get_help_option(self, ctx: Context) -> Optional["Option"]: - """Return the help option object.""" + """Return the help option with a terminal effect callback.""" from gettext import gettext # noqa: PLC0415 help_options = self.get_help_option_names(ctx) @@ -119,8 +210,19 @@ def show_help(ctx: Context, param: "click.Parameter", value: str) -> None: # no click.core.Command.get_help_option = get_help_option -def set_terminal_effect(terminal_effect): - """Set the terminal effect animation to appear when displaying the help.""" - if not get_no_terminal_efects(): +def set_terminal_effect(terminal_effect: Callable): + """ + Set a terminal effect animation for displaying help in Click commands. + + This function applies a patch to the Click `parse_args` and `get_help_option` + methods, so the help message is displayed with the specified terminal effect. + + Args: + terminal_effect (Callable): A callable that renders the terminal effect. + + Example: + >>> set_terminal_effect(display_terminal_effect) + """ + if not get_no_terminal_effects(): patch_parse_args(terminal_effect) patch_get_help_option(terminal_effect)