Shared lib of small but usefull functions and other
This commit adds 'sharedlib' loader that allows to organize
functions into tree structure. Salt doesn't allow this as it
only imports top-level modules
https://github.com/saltstack/salt/issues/37273
See README for more details.
Change-Id: I7827c42f8f0d4caef56eff6352a49fe1a95a50cc
diff --git a/README.rst b/README.rst
index 5cfa7ae..b89cb51 100644
--- a/README.rst
+++ b/README.rst
@@ -896,6 +896,86 @@
.. literalinclude:: tests/pillar/control_virt_custom.sls
:language: yaml
+Salt shared library
+-------------------
+
+This formula includes 'sharedlib' execution module which is a kind
+of 'library' of function and / or classes to be used in Jinja templates
+or directly as execution module.
+
+'sharedlib' implements a loader that is able to scan nested directories
+and import Python classes / functions from nested modules. Salt doesn't
+allow this as it only imports top-level modules:
+
+https://github.com/saltstack/salt/issues/37273
+
+'sharedlib' implements 4 main functions:
+
+* 'sharedlib.list' - search and print functions / classes found in nested directories
+* 'sharedlib.info' - print docstring of a function (if it exists)
+* 'sharedlib.get' - get function / class object, but not execute it immediately
+* 'sharedlib.call' - get function / class and execute / initialize it with
+ arguments given.
+
+Each of the commands above also have it's own docstring so it's possible to
+use them on a system:
+
+.. code-block:: text
+
+ # salt-call sys.doc sharedlib.list
+ local:
+ ----------
+ sharedlib.list:
+
+ List available functions.
+
+ .. code-block::
+
+ salt-call sharedlib.list
+
+Usage examples:
+
+.. code-block:: text
+
+ # salt-call sharedlib.list
+ local:
+ ----------
+ sharedlib.list:
+ ----------
+ classes:
+ - misc.Test
+ - misc2.Test
+ functions:
+ - misc.cast_dict_keys_to_int
+
+.. code-block:: text
+
+ # salt-call sharedlib.info misc.cast_dict_keys_to_int
+ local:
+ ----------
+ sharedlib.info:
+ ----------
+ misc.cast_dict_keys_to_int:
+
+ Return a dictionary with keys casted to int.
+ This usually is required when you want sort the dict later.
+
+ Jinja example:
+
+ .. code-block: jinja
+
+ {%- set ruleset = salt['sharedlib.call']('misc.cast_dict_keys_to_int', c.get('ruleset', {})) %}
+
+ .. code-block:: jinja
+
+ {%- set func = salt['sharedlib.get']('misc.cast_dict_keys_to_int') %}
+ {%- for c_name, c in t.chains.items() %}
+ {%- set ruleset = func(c.get('ruleset', {})) %}
+ {%- for rule_id, r in ruleset | dictsort %}
+ ...
+ {%- endfor %}
+
+
Usage
=====