gitmopy.utils
=============

.. py:module:: gitmopy.utils

.. autoapi-nested-parse::

   Utility functions and constants for ``gitmopy``.







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

.. py:function:: check_config(config)

   Check that the user configuration is valid.

   :param config: Current gitmopy configuration
                  that should be saved
   :type config: Dict[str, Union[bool, str]]

   :raises ValueError: Unknown config key
   :raises ValueError: Wrong config value type


.. py:function:: choice_separator(title = '', width = 30, sep = '─')

   Create an InquirerPy separator with a title.

   :param title: Title in-between separator characters.
                 Defaults to ``""``.
   :type title: str, optional
   :param width: Total length of sperator line. Defaults to 30.
   :type width: int, optional
   :param sep: Character to use around the ``title``. Defaults to ``"─"``.
   :type sep: str, optional

   :returns: _description_
   :rtype: Separator


.. py:function:: clear_line_and_move_up()

   Clear the current line and move up one line in the terminal.


.. py:function:: col(txt, color, bold=False)

   Return a coloured string with Rich.

   :param txt: String to colour.
   :type txt: str
   :param colour: Colour to use.
   :type colour: str
   :param bold: Whether to use bold font. Defaults to False.
   :type bold: bool, optional

   :returns: Coloured string.
   :rtype: str


.. py:function:: load_config()

   Load the configuration from ``${APP_PATH}/config.yaml``.

   Returns the default configuration if the file does not exist.

   :returns: User gitmopy configuration.
   :rtype: Dict[str, bool]


.. py:function:: load_user_gitmojis()

   Load custom gitmojis from ``${APP_PATH}/custom_gitmojis.yaml``.

   :returns: Custom gitmojis.
   :rtype: List[Dict[str, str]]


.. py:function:: message_from_commit_dict(commit_dict)

   Create a commit message from a commit dictionary.

   Depending on whether ``scope`` is set, will look like

   * ``{emoji} ({scope}): {title}``
   * ``{emoji}: {title}``

   Then ``\n\n{message}`` is appended if a message is specified.


   :param commit_dict: Commit specs from the prompt.
   :type commit_dict: Dict[str, str]

   :returns: formatted commit message.
   :rtype: str


.. py:function:: print_staged_files(staged)

   Print the currently staged files with Rich colours.

   :param staged: List of staged files paths.
   :type staged: List[str]


.. py:function:: resolve_path(path)

   Resolve a path with ``expandvars``, ``expanduser`` and ``resolve``.

   :param path: Path to resolve.
   :type path: Union[str, Path]

   :returns: Resolved (absolute) path.
   :rtype: Path


.. py:function:: safe_capitalize(s)

   Capitalize a string if it is not empty, but keeps all-caps words.

   Example:
   ..code-block:: python

       >>> safe_capitalize("hello")
       "Hello"
       >>> safe_capitalize("HELLO")
       "HELLO"
       >>> "HELLO".capitalize()
       "Hello"

   :param s: String to capitalize
   :type s: str


.. py:function:: save_config(config)

   Save the configuration to ``${APP_PATH}/config.yaml``.

   Creates the parent directory if it does not exist.

   :param config: Current gitmopy configuration.
   :type config: Dict[str, Union[bool, str]]


.. py:function:: set_start_options()

   Set the options for the default commit arguments automatically from the ``gitmopy commit`` command's signature.


.. py:function:: standard_width_emoji(emoji, to=2)

   Return a standard width emoji of width 2.


.. py:function:: terminal_separator(margin=10)

   Create a separator for the terminal.

   :returns: Terminal separator
   :rtype: str


.. py:function:: validate_user_emojis(custom_emos)

   Validate user emojis.

   * Must be a list of dictionaries (possibly empty)
   * Each dictionary must have an ``emoji`` key and a ``description`` key
   * Each key must be a string
   * Each key must be non-empty

   :raises ValueError: If any of the above conditions are not met.

   :param custom_emos: User defined emojis.
   :type custom_emos: Any

   :returns: Validated emojis.
   :rtype: List[Dict[str, str]]


.. py:data:: console

.. py:data:: print