hydraclick.terminal_effects
===========================

.. py:module:: hydraclick.terminal_effects


Functions
---------

.. autoapisummary::

   hydraclick.terminal_effects.get_no_terminal_effects
   hydraclick.terminal_effects.config_effect
   hydraclick.terminal_effects.remove_lines
   hydraclick.terminal_effects.count_wrapped_lines
   hydraclick.terminal_effects.display_terminal_effect
   hydraclick.terminal_effects.patch_parse_args
   hydraclick.terminal_effects.patch_get_help_option
   hydraclick.terminal_effects.set_terminal_effect


Module Contents
---------------

.. py:function:: get_no_terminal_effects()

   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: `True` if terminal effects should be disabled, `False` otherwise.
   :rtype: bool

   .. rubric:: Example

   >>> os.environ["NO_TERMINAL_EFFECTS"] = "true"
   >>> get_no_terminal_effects()
   True


.. py:function:: config_effect(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.

   :param effect: The terminal effect object to be configured.

   :returns: The modified terminal effect object.

   .. rubric:: Example

   >>> effect = SomeEffect()
   >>> config_effect(effect)
   <configured effect>


.. py:function:: remove_lines(num_lines)

   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.

   :param num_lines: The number of lines to remove.
   :type num_lines: int

   .. rubric:: Example

   >>> remove_lines(3)  # Removes the last 3 printed lines


.. py:function:: count_wrapped_lines(text, terminal_width)

   Calculate the number of lines the given text will take when wrapped in the terminal.

   :param text: The text to be wrapped.
   :type text: str
   :param terminal_width: The width of the terminal in characters.
   :type terminal_width: int

   :returns: The number of lines the text will occupy in the terminal.
   :rtype: int

   .. rubric:: Example

   >>> count_wrapped_lines("This is a long line of text.", 10)
   3


.. py:function:: display_terminal_effect(value, 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.

   :param value: The text to display with the terminal effect.
   :type value: str
   :param effect_cls: The class of the terminal effect to use. Defaults to `Print`.
   :type effect_cls: optional

   .. rubric:: Example

   >>> display_terminal_effect("Hello World!")


.. py:function:: patch_parse_args(terminal_effect)

   Patch the Click `parse_args` function to display a terminal effect.

   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.

   :param terminal_effect: A callable that renders the terminal effect.
   :type terminal_effect: Callable

   .. rubric:: Example

   >>> patch_parse_args(display_terminal_effect)


.. py:function:: patch_get_help_option(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.

   :param terminal_effect: A callable that renders the terminal effect.
   :type terminal_effect: Callable

   .. rubric:: Example

   >>> patch_get_help_option(display_terminal_effect)


.. py:function:: set_terminal_effect(terminal_effect)

   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.

   :param terminal_effect: A callable that renders the terminal effect.
   :type terminal_effect: Callable

   .. rubric:: Example

   >>> set_terminal_effect(display_terminal_effect)