:py:mod:`khard.helpers`
=======================

.. py:module:: khard.helpers

.. autoapi-nested-parse::

   Some helper functions for khard



Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   interactive/index.rst
   typing/index.rst


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


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



Attributes
~~~~~~~~~~

.. autoapisummary::

   khard.helpers.PostAddress
   khard.helpers.YamlPostAddresses


.. py:function:: list_to_string(input: Union[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: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: Union[str, Sequence, Dict[str, Any], None]) -> Union[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

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


.. py:function:: yaml_dicts(data: Optional[Dict[str, Any]], defaults: Union[Dict[str, Any], List[str], None] = None) -> Optional[Dict[str, Any]]

   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: Optional[Dict[str, List[typing.PostAddress]]], address_properties: List[str], defaults: Optional[List[str]] = None) -> Optional[YamlPostAddresses]

   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: Union[str, datetime.datetime, None], version: str) -> Optional[str]

   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: Union[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: Union[str, List], indentation: int, show_multi_line_character: bool) -> str


.. py:function:: get_new_contact_template(supported_private_objects: Optional[List[str]] = None) -> str