khard.helpers
*************

Some helper functions for khard


Submodules
==========

* khard.helpers.interactive

* khard.helpers.typing


Attributes
==========

+------------+--------------------------------------------------------------------------------------------+
| "PostAddr  |                                                                                            |
| ess"       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "YamlPost  |                                                                                            |
| Addresses" |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


Functions
=========

+------------+--------------------------------------------------------------------------------------------+
| "list_to_  | converts list to string recursively so that nested lists are supported                     |
| string"(→  |                                                                                            |
| str)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "pretty_p  | Converts a list of lists into a string formatted like a table                              |
| rint"(→    |                                                                                            |
| str)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "get_rand  |                                                                                            |
| om_uid"(→  |                                                                                            |
| str)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "yaml_cle  | sanitize yaml values according to some simple principles:                                  |
| an"(→ Uni  |                                                                                            |
| on[Sequen  |                                                                                            |
| ce, str,   |                                                                                            |
| dict[str,  |                                                                                            |
| Any], ...) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "yaml_dic  | format a dict according to template, if empty use specified defaults                       |
| ts"(→ Opt  |                                                                                            |
| ional[dic  |                                                                                            |
| t[str,     |                                                                                            |
| Any]])     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "yaml_add  | build a dict from an address, using a list of properties, an address has.                  |
| resses"(→  |                                                                                            |
| Optional[  |                                                                                            |
| YamlPostA  |                                                                                            |
| ddresses]) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "yaml_ann  | format an anniversary according to its contents and the vCard version.                     |
| iversary"  |                                                                                            |
| (→ Option  |                                                                                            |
| al[str])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "convert_  | converts a value list into yaml syntax                                                     |
| to_yaml"(→ |                                                                                            |
| list[str]) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "indent_m  |                                                                                            |
| ultiline_  |                                                                                            |
| string"(→  |                                                                                            |
| str)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "get_new_  |                                                                                            |
| contact_t  |                                                                                            |
| emplate"(→ |                                                                                            |
| str)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


Package Contents
================

khard.helpers.list_to_string(input: str | list, delimiter: str) -> str

   converts list to string recursively so that nested lists are
   supported

   Parameters:
      * **input** -- a list of strings and lists of strings (and so on
        recursive)

      * **delimiter** -- the delimiter to use when joining the items

   Returns:
      the recursively joined list

khard.helpers.PostAddress

khard.helpers.YamlPostAddresses

khard.helpers.pretty_print(table: list[list[str]], justify: str = 'L') -> str

   Converts a list of lists into a string formatted like a table with
   spaces separating fields and newlines separating rows

khard.helpers.get_random_uid() -> str

khard.helpers.yaml_clean(value: str | Sequence | dict[str, Any] | None) -> Sequence | str | dict[str, Any] | ruamel.yaml.scalarstring.LiteralScalarString | None

   sanitize yaml values according to some simple principles:
      1. empty values are none, so ruamel does not print an empty
         list/str

      2. list with only one item become this item

      3. multiline strings use the YAML literal style:
         https://yaml.org/spec/1.2.2/#literal-style

   Parameters:
      **value** -- the value to be sanitized

   Returns:
      the sanitized value

khard.helpers.yaml_dicts(data: dict[str, Any] | None, defaults: dict[str, Any] | list[str] | None = None) -> dict[str, Any] | None

   format a dict according to template, if empty use specified
   defaults

   Parameters:
      * **data** -- dict of contact data with keys as types and values
        as values.

      * **defaults** -- default dict to be used if data is empty.

   Returns:
      dict of types and values.

khard.helpers.yaml_addresses(addresses: dict[str, list[PostAddress]] | None, address_properties: list[str], defaults: list[str] | None = None) -> YamlPostAddresses | None

   build a dict from an address, using a list of properties, an
   address has.

   Parameters:
      * **addresses** -- dict of addresses with existing properties

      * **address_properties** -- list of properties that make up an
        address

      * **defaults** -- list of address types

   Returns:
      dict of address types with all properties

khard.helpers.yaml_anniversary(anniversary: str | datetime.datetime | None, version: str) -> str | None

   format an anniversary according to its contents and the vCard
   version.

   Parameters:
      * **anniversary** -- a string or a datetime object, that is the
        anniversary

      * **version** -- the vCard version to format for

   Returns:
      the formatted date string

khard.helpers.convert_to_yaml(name: str, value: None | str | list, indentation: int, index_of_colon: int, show_multi_line_character: bool) -> list[str]

   converts a value list into yaml syntax

   Parameters:
      * **name** -- name of object (example: phone)

      * **value** (*str**, **list**(**str**)**,
        **list**(**list**(**str**)**)**, **list**(**dict**)*) --
        object contents

      * **indentation** -- indent all by number of spaces

      * **index_of_colon** -- use to position : at the name string (-1
        for no space)

      * **show_multi_line_character** -- option to hide "|"

   Returns:
      yaml formatted string array of name, value pair

khard.helpers.indent_multiline_string(input: str | list, indentation: int, show_multi_line_character: bool) -> str

khard.helpers.get_new_contact_template(supported_private_objects: list[str] | None = None) -> str
