khard.helpers
=============

.. py:module:: khard.helpers

.. autoapi-nested-parse::

   Some helper functions for khard



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/khard/helpers/interactive/index
   /autoapi/khard/helpers/typing/index


Attributes
----------

.. autoapisummary::

   khard.helpers.PostAddress
   khard.helpers.YamlPostAddresses
   khard.helpers.YAML


Functions
---------

.. autoapisummary::

   khard.helpers.list_to_string
   khard.helpers.pretty_print
   khard.helpers.get_random_uid
   khard.helpers.yaml_clean
   khard.helpers.yaml_dicts
   khard.helpers.yaml_addresses
   khard.helpers.yaml_anniversary
   khard.helpers.convert_to_yaml
   khard.helpers.indent_multiline_string
   khard.helpers.get_new_contact_template


Package Contents
----------------

.. py:function:: list_to_string(input: str | list, delimiter: str) -> str

   converts list to string recursively so that nested lists are supported

   :param input: a list of strings and lists of strings (and so on recursive)
   :param delimiter: the delimiter to use when joining the items
   :returns: the recursively joined list


.. py:data:: PostAddress

.. py:data:: YamlPostAddresses

.. py:data:: YAML

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


.. py:function:: get_random_uid() -> str

.. py:function:: yaml_clean(value: YAML) -> YAML | ruamel.yaml.scalarstring.LiteralScalarString

   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

   :param value: the value to be sanitized
   :returns: the sanitized value


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

   :param data: dict of contact data with keys as types and values as values.
   :param defaults: default dict to be used if data is empty.
   :returns: dict of types and values.


.. py:function:: yaml_addresses(addresses: dict[str, list[typing.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.

   :param addresses: dict of addresses with existing properties
   :param address_properties: list of properties that make up an address
   :param defaults: list of address types
   :returns: dict of address types with all properties


.. py:function:: yaml_anniversary(anniversary: str | datetime.datetime | None, version: str) -> str | None

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

   :param anniversary: a string or a datetime object, that is the anniversary
   :param version: the vCard version to format for
   :returns: the formatted date string


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

   :param name: name of object (example: phone)
   :param value: object contents
   :type value: str, list(str), list(list(str)), list(dict)
   :param indentation: indent all by number of spaces
   :param index_of_colon: use to position : at the name string (-1 for no
       space)
   :param show_multi_line_character: option to hide "|"
   :returns: yaml formatted string array of name, value pair


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

.. py:function:: get_new_contact_template(supported_private_objects: list[str] | None = None) -> str