add update_defaults task for inventory functions, fixing conn_open docs

nornir_salt/plugins/functions/InventoryFun.py

@@ -117,6 +117,7 @@
 .. autofunction:: nornir_salt.plugins.functions.InventoryFun._load
 .. autofunction:: nornir_salt.plugins.functions.InventoryFun._list_hosts
 .. autofunction:: nornir_salt.plugins.functions.InventoryFun._list_hosts_platforms
+.. autofunction:: nornir_salt.plugins.functions.InventoryFun._update_defaults
 """
 import logging
 
@@ -303,10 +304,7 @@ def _load(nr, data):
     of function to call, rest of the dictionary used as a ``**kwargs`` with
     specidfied call function.
     """
-    return [
-        fun_dispatcher[item.pop("call")](nr, **item)
-        for item in data
-    ]
+    return [fun_dispatcher[item.pop("call")](nr, **item) for item in data]
 
 
 def _list_hosts(nr, **kwargs):
@@ -395,6 +393,61 @@ def _read_host_data(nr, keys, default=None, **kwargs):
     return ret
 
 
+def _update_defaults(
+    nr,
+    connection_options: dict = None,
+    data: dict = None,
+    password: str = None,
+    platform: str = None,
+    port: int = None,
+    username: str = None,
+    **kwargs
+) -> bool:
+    """
+    Function to update defaults inventory.
+
+    :param nr: (obj) Nornir object
+    :param connection_options: (dict) dictionary with defaults's
+        connection options data to update. Should be keyed by
+        connection name with value being a dictionary of connection
+        attributes - hostname, port, username, password, platform
+        and extras dictionary
+    :param data: (dict) dictionary with defaults's data to update
+    :param kwargs: (dict) additional key-value pairs to add into
+        defaults data
+    :return: True on success
+
+    Replaces existing values for top keys similar to dictionary
+    ``update`` method, no recursive merge performed.
+    """
+    data = data or {}
+    data = {**data, **kwargs}
+
+    # update defaults data
+    if connection_options:
+        for name, opts in connection_options.items():
+            nr.inventory.defaults.connection_options[name] = ConnectionOptions(
+                hostname=opts.get("hostname"),
+                port=opts.get("port"),
+                username=opts.get("username"),
+                password=opts.get("password"),
+                platform=opts.get("platform"),
+                extras=opts.get("extras"),
+            )
+    if data:
+        nr.inventory.defaults.data.update(data)
+    if password is not None:
+        nr.inventory.defaults.password = password
+    if port is not None:
+        nr.inventory.defaults.port = port
+    if platform is not None:
+        nr.inventory.defaults.platform = platform
+    if username is not None:
+        nr.inventory.defaults.username = username
+
+    return True
+
+
 fun_dispatcher = {
     "create_host": _create_host,
     "update_host": _update_host,
@@ -409,6 +462,7 @@ def _read_host_data(nr, keys, default=None, **kwargs):
     "load": _load,
     "list_hosts": _list_hosts,
     "list_hosts_platforms": _list_hosts_platforms,
+    "update_defaults": _update_defaults,
 }
 
 
@@ -432,5 +486,6 @@ def InventoryFun(nr, call, **kwargs):
     - ``read_host_data`` - calls ``_read_host_data`` to return host's data under provided path keys
     - ``list_hosts`` - calls ``_list_hosts``, return a list of inventory's host names
     - ``list_hosts_platforms`` - calls ``_list_hosts_platforms``, return a dictionary of hosts' platforms
+    - ``update_defaults`` - calls ``_update_defaults``, non recursively update defaults attributes
     """
     return fun_dispatcher[call](nr, **kwargs)

nornir_salt/plugins/tasks/connections.py

@@ -185,37 +185,36 @@ def conn_open(
     logic retrying different connection parameters.
 
     :param conn_name: name of configured connection plugin to use
-        to open connection e.g. ``netmiko``, ``napalm``, ``scrapli``
+      to open connection e.g. ``netmiko``, ``napalm``, ``scrapli``
     :param hostname: hostname or ip address to connect to
     :param username: username to use to open the connection
     :param password: password to use to open the connection
     :param port: port to use to open the connection
     :param platform: platform name connection parameter
     :param extras: connection plugin extras parameters
     :param default_to_host_attributes: on True host's open connection  method
-        uses inventory data to suppliment not missing arguments like port or
-        platform
+      uses inventory data to suppliment not missing arguments like port or
+      platform
     :param close_open: if True, closes already open connection
-        and connects again
+      and connects again
     :param reconnect: list of parameters to use to try connecting
-        to device if primary set of parameters fails. If ``reconnect``
-        item is a dictionary, it is supplied as ``**kwargs`` to
-        host open connection call. Alternatively, ``reconnect`` item
-        can refer to a name of credentials set from inventory data
-        ``credentials`` section within host, groups or defaults inventory.
+      to device if primary set of parameters fails. If ``reconnect``
+      item is a dictionary, it is supplied as ``**kwargs`` to
+      host open connection call. Alternatively, ``reconnect`` item
+      can refer to a name of credentials set from inventory data
+      ``credentials`` section within host, groups or defaults inventory.
     :param raise_on_error: raises error if not able to establish
-        connection even after trying all ``reconnect`` parameters, used
-        to signal exception to parent function e.g. RetryRunner
+      connection even after trying all ``reconnect`` parameters, used
+      to signal exception to parent function e.g. RetryRunner
     :param host: Nornir Host object supplied by RetryRunner
     :param via: host's ``connection_options`` parameter name to use for
-        opening connection for ``conn_name``, if ``via`` parameter provided,
-        ``close_open`` always set to `True`` to re-establish host connection.
-        ``reconnect`` not suppported with ``via``. ``default_to_host_attributes``
-        set to ``True`` if ``via`` argument provided.
+      opening connection for ``conn_name``, if ``via`` parameter provided,
+      ``close_open`` always set to `True`` to re-establish host connection.
+      ``reconnect`` not suppported with ``via``. ``default_to_host_attributes``
+      set to ``True`` if ``via`` argument provided.
     :return: Nornir result object with connection establishment status
 
-    Device re-connects
-    ~~~~~~~~~~~~~~~~~~
+    **Device re-connects**
 
     Sample ``reconnect`` list content::
 
@@ -287,8 +286,7 @@ def conn_open(
     ``connection_options`` parameters are preferred and override
     higher level parameters.
 
-    Device via connections
-    ~~~~~~~~~~~~~~~~~~~~~~
+    **Device via connections**
 
     Specifying ``via`` parameter allows to open connection to device
     using certain connection options. This is useful when device has
@@ -314,8 +312,7 @@ def conn_open(
     setting ``via`` equal to ``out_of_band`` will result in connection
     being open using ``out_of_band`` parameters.
 
-    Device connection redispatch
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    **Device connection redispatch**
 
     Primary use case is to use ``via`` to open connection to console
     server and use Netmiko redispatch functionality to access device
@@ -422,11 +419,11 @@ def conn_open(
             raise TypeError("'{}' parameters not found or invalid".format(param_name))
 
         # extract connection_options and merge with params for non kwargs params
-        # do not deepcopy kwaergs params as they might contain Jumphost socket 
+        # do not deepcopy kwaergs params as they might contain Jumphost socket
         if index > 0:
             param = copy.deepcopy(param)
             param.update(param.pop("connection_options", {}).get(conn_name, {}))
-            
+
         try:
             if index == 0:
                 res_msg = f"'{conn_name}' connected with primary connection parameters"