support testing/linting module_utils code

This does not directly affect network because network has its own
solution for dealing with testing/linting module_utils code, but
it gets network to feature/code parity with the template and
other repos.

Defines a shell function in utils.sh - lsr_setup_module_utils -
that allows configuring a tox venv installed ansible to have
the repo module_utils code in the default pythonpath for the
venv, which allows testing and linting the module_utils code
without having to otherwise munge or mock the pythonpath.

Projects needing this functionality can set in `.travis/config.sh`
the variable `RUN_PYTEST_SETUP_MODULE_UTILS` to setup
module_utils/ for pytest, and `RUN_PYLINT_SETUP_MODULE_UTILS`
to setup module_utils/ for pylint.

.travis/config.sh

@@ -20,6 +20,7 @@
 #       - RUN_PYLINT_INCLUDE
 #       - RUN_PYLINT_EXCLUDE
 #       - RUN_PYLINT_DISABLED
+#       - RUN_PYLINT_SETUP_MODULE_UTILS
 #
 #   * .travis/runblack.sh:
 #
@@ -31,3 +32,6 @@
 #
 #       - RUN_FLAKE8_DISABLED
 #
+#   * .travis/runpytest.sh:
+#
+#       - RUN_PYTEST_SETUP_MODULE_UTILS

.travis/runpylint.sh

@@ -12,6 +12,13 @@
 
 # The given command line arguments are passed to custom_pylint.py.
 
+# Environment variables:
+#
+#   RUN_PYLINT_SETUP_MODULE_UTILS
+#     if set to an arbitrary non-empty value, the environment will be
+#     configured so that linting of the module_utils/ code will be run
+#     correctly
+
 set -e
 
 ME=$(basename $0)
@@ -19,5 +26,10 @@ SCRIPTDIR=$(readlink -f $(dirname $0))
 
 . ${SCRIPTDIR}/config.sh
 
+if [[ "${RUN_PYLINT_SETUP_MODULE_UTILS}" ]]; then
+  . ${SCRIPTDIR}/utils.sh
+  lsr_setup_module_utils
+fi
+
 set -x
 python ${SCRIPTDIR}/custom_pylint.py "$@"

.travis/runpytest.sh

@@ -10,18 +10,30 @@
 
 # The given command line arguments are passed to pytest.
 
+# Environment variables:
+#
+#   RUN_PYTEST_SETUP_MODULE_UTILS
+#     if set to an arbitrary non-empty value, the environment will be
+#     configured so that tests of the module_utils/ code will be run
+#     correctly
+
 set -e
 
 ME=$(basename $0)
 SCRIPTDIR=$(readlink -f $(dirname $0))
 
 . ${SCRIPTDIR}/utils.sh
+. ${SCRIPTDIR}/config.sh
 
 if [[ ! -d ${TOPDIR}/tests/unit ]]; then
   lsr_info "${ME}: No unit tests found. Skipping."
   exit 0
 fi
 
+if [[ "${RUN_PYTEST_SETUP_MODULE_UTILS}" ]]; then
+  lsr_setup_module_utils
+fi
+
 PYTEST_OPTS=()
 PYTEST_OPTS_NOCOV=()
 USE_COV=no

.travis/utils.sh

@@ -169,6 +169,25 @@ function lsr_venv_python_matches_system_python() {
   lsr_compare_pythons ${1:-python} -eq $syspython
 }
 
+##
+# lsr_setup_module_utils [$1] [$2]
+#
+#   $1 - path to the ansible/module_utils/ directory in the venv
+#        assumes ansible has been installed in the venv
+#        defaults to env var $SRC_MODULE_UTILS_DIR
+#   $2 - path to the local module_utils/ directory for the role
+#        defaults to env var $DEST_MODULE_UTILS_DIR
+#
+# Exit with 0 if virtual environment Python version matches the system Python
+# version.
+function lsr_setup_module_utils() {
+  local srcdir=${1:-$SRC_MODULE_UTILS_DIR}
+  local destdir=${2:-$DEST_MODULE_UTILS_DIR}
+  if [ -n "$srcdir" -a -d "$srcdir" -a -n "$destdir" -a -d "$destdir" ]; then
+    bash $TOPDIR/tests/setup_module_utils.sh "$srcdir" "$destdir"
+  fi
+}
+
 # set TOPDIR
 ME=${ME:-$(basename $0)}
 SCRIPTDIR=${SCRIPTDIR:-$(readlink -f $(dirname $0))}

tests/setup_module_utils.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# SPDX-License-Identifier: MIT
+
+set -euo pipefail
+
+if [ -n "${DEBUG:-}" ] ; then
+    set -x
+fi
+
+if [ ! -d "${1:-}" ] ; then
+    echo Either ansible is not installed, or there is no ansible/module_utils
+    echo in $1 - Skipping
+    exit 0
+fi
+
+if [ ! -d "${2:-}" ] ; then
+    echo Role has no module_utils - Skipping
+    exit 0
+fi
+
+# we need absolute path for $2
+absmoddir=$( readlink -f "$2" )
+
+# clean up old links to module_utils
+for item in "$1"/* ; do
+    if lnitem=$( readlink "$item" ) && test -n "$lnitem" ; then
+        case "$lnitem" in
+            *"${2}"*) rm -f "$item" ;;
+        esac
+    fi
+done
+
+# add new links to module_utils
+for item in "$absmoddir"/* ; do
+    case "$item" in
+        *__pycache__) continue;;
+        *.pyc) continue;;
+    esac
+    bnitem=$( basename "$item" )
+    ln -s "$item" "$1/$bnitem"
+done

tox.ini

@@ -22,6 +22,8 @@ passenv = *
 setenv =
     PYTHONPATH = {toxinidir}/library:{toxinidir}/module_utils
     LC_ALL = C
+    SRC_MODULE_UTILS_DIR = {envsitepackagesdir}/ansible/module_utils
+    DEST_MODULE_UTILS_DIR = {toxinidir}/module_utils
 changedir = {toxinidir}/tests
 covtargets = --cov={toxinidir}/library --cov={toxinidir}/module_utils
 pytesttarget = unit