Merge pull request #3141 from tbielawa/fragment_banners

Fragment banners

7 files changed, 188 insertions, 2 deletions

diff --git a/roles/lib_openshift/library/oc_edit.py b/roles/lib_openshift/library/oc_edit.py
index 1a361ae20..2338d5e8e 100644
--- a/roles/lib_openshift/library/oc_edit.py
+++ b/roles/lib_openshift/library/oc_edit.py
@@ -24,6 +24,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+# -*- -*- -*- Begin included fragment: lib/import.py -*- -*- -*-
 '''
    OpenShiftCLI class that wraps the oc commands in a subprocess
 '''
@@ -40,6 +42,10 @@ import subprocess
 import ruamel.yaml as yaml
 from ansible.module_utils.basic import AnsibleModule
 
+# -*- -*- -*- End included fragment: lib/import.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: doc/edit -*- -*- -*-
+
 DOCUMENTATION = '''
 ---
 module: oc_edit
@@ -153,6 +159,10 @@ oc_edit:
     spec.template.spec.containers[0].resources.limits.memory: 512
     spec.template.spec.containers[0].resources.requests.memory: 256
 '''
+
+# -*- -*- -*- End included fragment: doc/edit -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: ../../lib_utils/src/class/yedit.py -*- -*- -*-
 # noqa: E301,E302
 
 
@@ -717,6 +727,10 @@ class Yedit(object):
                         'state': "present"}
 
         return {'failed': True, 'msg': 'Unkown state passed'}
+
+# -*- -*- -*- End included fragment: ../../lib_utils/src/class/yedit.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: lib/base.py -*- -*- -*-
 # pylint: disable=too-many-lines
 # noqa: E301,E302,E303,T001
 
@@ -1238,6 +1252,10 @@ class OpenShiftCLIConfig(object):
         return rval
 
 
+# -*- -*- -*- End included fragment: lib/base.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: class/oc_edit.py -*- -*- -*-
+
 class Edit(OpenShiftCLI):
     ''' Class to wrap the oc command line tools
     '''
@@ -1330,6 +1348,10 @@ class Edit(OpenShiftCLI):
 
         return {"changed": True, 'results': api_rval, 'state': 'present'}
 
+# -*- -*- -*- End included fragment: class/oc_edit.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: ansible/oc_edit.py -*- -*- -*-
+
 
 def main():
     '''
@@ -1375,3 +1397,5 @@ def main():
 
 if __name__ == '__main__':
     main()
+
+# -*- -*- -*- End included fragment: ansible/oc_edit.py -*- -*- -*-
diff --git a/roles/lib_openshift/library/oc_obj.py b/roles/lib_openshift/library/oc_obj.py
index 5b501484b..ac24c35ca 100644
--- a/roles/lib_openshift/library/oc_obj.py
+++ b/roles/lib_openshift/library/oc_obj.py
@@ -24,6 +24,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+# -*- -*- -*- Begin included fragment: lib/import.py -*- -*- -*-
 '''
    OpenShiftCLI class that wraps the oc commands in a subprocess
 '''
@@ -40,6 +42,10 @@ import subprocess
 import ruamel.yaml as yaml
 from ansible.module_utils.basic import AnsibleModule
 
+# -*- -*- -*- End included fragment: lib/import.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: doc/obj -*- -*- -*-
+
 DOCUMENTATION = '''
 ---
 module: oc_obj
@@ -132,6 +138,10 @@ oc_obj:
   namespace: default
 register: router_output
 '''
+
+# -*- -*- -*- End included fragment: doc/obj -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: ../../lib_utils/src/class/yedit.py -*- -*- -*-
 # noqa: E301,E302
 
 
@@ -696,6 +706,10 @@ class Yedit(object):
                         'state': "present"}
 
         return {'failed': True, 'msg': 'Unkown state passed'}
+
+# -*- -*- -*- End included fragment: ../../lib_utils/src/class/yedit.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: lib/base.py -*- -*- -*-
 # pylint: disable=too-many-lines
 # noqa: E301,E302,E303,T001
 
@@ -1217,6 +1231,10 @@ class OpenShiftCLIConfig(object):
         return rval
 
 
+# -*- -*- -*- End included fragment: lib/base.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: class/oc_obj.py -*- -*- -*-
+
 # pylint: disable=too-many-instance-attributes
 class OCObject(OpenShiftCLI):
     ''' Class to wrap the oc command line tools '''
@@ -1408,6 +1426,10 @@ class OCObject(OpenShiftCLI):
 
             return {'changed': True, 'results': api_rval, 'state': "present"}
 
+# -*- -*- -*- End included fragment: class/oc_obj.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: ansible/oc_obj.py -*- -*- -*-
+
 # pylint: disable=too-many-branches
 def main():
     '''
@@ -1442,3 +1464,5 @@ def main():
 
 if __name__ == '__main__':
     main()
+
+# -*- -*- -*- End included fragment: ansible/oc_obj.py -*- -*- -*-
diff --git a/roles/lib_openshift/library/oc_route.py b/roles/lib_openshift/library/oc_route.py
index 19c7462ea..f5d6c3dfe 100644
--- a/roles/lib_openshift/library/oc_route.py
+++ b/roles/lib_openshift/library/oc_route.py
@@ -24,6 +24,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+# -*- -*- -*- Begin included fragment: lib/import.py -*- -*- -*-
 '''
    OpenShiftCLI class that wraps the oc commands in a subprocess
 '''
@@ -40,6 +42,10 @@ import subprocess
 import ruamel.yaml as yaml
 from ansible.module_utils.basic import AnsibleModule
 
+# -*- -*- -*- End included fragment: lib/import.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: doc/route -*- -*- -*-
+
 DOCUMENTATION = '''
 ---
 module: oc_route
@@ -157,6 +163,10 @@ EXAMPLES = '''
     tls_termination: reencrypt
   run_once: true
 '''
+
+# -*- -*- -*- End included fragment: doc/route -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: ../../lib_utils/src/class/yedit.py -*- -*- -*-
 # noqa: E301,E302
 
 
@@ -721,6 +731,10 @@ class Yedit(object):
                         'state': "present"}
 
         return {'failed': True, 'msg': 'Unkown state passed'}
+
+# -*- -*- -*- End included fragment: ../../lib_utils/src/class/yedit.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: lib/base.py -*- -*- -*-
 # pylint: disable=too-many-lines
 # noqa: E301,E302,E303,T001
 
@@ -1241,6 +1255,10 @@ class OpenShiftCLIConfig(object):
 
         return rval
 
+
+# -*- -*- -*- End included fragment: lib/base.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: lib/route.py -*- -*- -*-
 # noqa: E302,E301
 
 
@@ -1363,6 +1381,10 @@ class Route(Yedit):
         ''' return wildcardPolicy '''
         return self.get(Route.wildcard_policy)
 
+# -*- -*- -*- End included fragment: lib/route.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: class/oc_route.py -*- -*- -*-
+
 
 # pylint: disable=too-many-instance-attributes
 class OCRoute(OpenShiftCLI):
@@ -1531,6 +1553,10 @@ class OCRoute(OpenShiftCLI):
         # catch all
         return {'failed': True, 'msg': "Unknown State passed"}
 
+# -*- -*- -*- End included fragment: class/oc_route.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: ansible/oc_route.py -*- -*- -*-
+
 
 def get_cert_data(path, content):
     '''get the data for a particular value'''
@@ -1612,3 +1638,5 @@ def main():
 
 if __name__ == '__main__':
     main()
+
+# -*- -*- -*- End included fragment: ansible/oc_route.py -*- -*- -*-
diff --git a/roles/lib_openshift/library/oc_version.py b/roles/lib_openshift/library/oc_version.py
index 197a0a947..5ee3e9c9b 100644
--- a/roles/lib_openshift/library/oc_version.py
+++ b/roles/lib_openshift/library/oc_version.py
@@ -24,6 +24,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+# -*- -*- -*- Begin included fragment: lib/import.py -*- -*- -*-
 '''
    OpenShiftCLI class that wraps the oc commands in a subprocess
 '''
@@ -40,6 +42,10 @@ import subprocess
 import ruamel.yaml as yaml
 from ansible.module_utils.basic import AnsibleModule
 
+# -*- -*- -*- End included fragment: lib/import.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: doc/version -*- -*- -*-
+
 DOCUMENTATION = '''
 ---
 module: oc_version
@@ -77,6 +83,10 @@ oc_version:
   oc_version:
   register: oc_version
 '''
+
+# -*- -*- -*- End included fragment: doc/version -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: ../../lib_utils/src/class/yedit.py -*- -*- -*-
 # noqa: E301,E302
 
 
@@ -641,6 +651,10 @@ class Yedit(object):
                         'state': "present"}
 
         return {'failed': True, 'msg': 'Unkown state passed'}
+
+# -*- -*- -*- End included fragment: ../../lib_utils/src/class/yedit.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: lib/base.py -*- -*- -*-
 # pylint: disable=too-many-lines
 # noqa: E301,E302,E303,T001
 
@@ -1162,6 +1176,10 @@ class OpenShiftCLIConfig(object):
         return rval
 
 
+# -*- -*- -*- End included fragment: lib/base.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: class/oc_version.py -*- -*- -*-
+
 
 # pylint: disable=too-many-instance-attributes
 class OCVersion(OpenShiftCLI):
@@ -1207,6 +1225,10 @@ class OCVersion(OpenShiftCLI):
                     'results': result,
                     'changed': False}
 
+# -*- -*- -*- End included fragment: class/oc_version.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: ansible/oc_version.py -*- -*- -*-
+
 def main():
     ''' ansible oc module for version '''
 
@@ -1230,3 +1252,5 @@ def main():
 
 if __name__ == '__main__':
     main()
+
+# -*- -*- -*- End included fragment: ansible/oc_version.py -*- -*- -*-
diff --git a/roles/lib_openshift/src/generate.py b/roles/lib_openshift/src/generate.py
index 6daade108..3f23455b5 100755
--- a/roles/lib_openshift/src/generate.py
+++ b/roles/lib_openshift/src/generate.py
@@ -27,19 +27,54 @@ def parse_args():
     return parser.parse_args()
 
 
+def fragment_banner(fragment_path, side, data):
+    """Generate a banner to wrap around file fragments
+
+:param string fragment_path: A path to a module fragment
+:param string side: ONE OF: "header", "footer"
+:param StringIO data: A StringIO object to write the banner to
+"""
+    side_msg = {
+        "header": "Begin included fragment: {}",
+        "footer": "End included fragment: {}"
+    }
+    annotation = side_msg[side].format(fragment_path)
+
+    banner = """
+# -*- -*- -*- {} -*- -*- -*-
+""".format(annotation)
+
+    # Why skip?
+    #
+    # * 'generated' - This is the head of the script, we don't want to
+    #   put comments before the #!shebang
+    #
+    # * 'license' - Wrapping this just seemed like gratuitous extra
+    if ("generated" not in fragment_path) and ("license" not in fragment_path):
+        data.write(banner)
+
+    # Make it self-contained testable
+    return banner
+
+
 def generate(parts):
-    '''generate the source code for the ansible modules'''
+    '''generate the source code for the ansible modules
+
+:param Array parts: An array of paths (strings) to module fragments
+    '''
 
     data = six.StringIO()
     for fpart in parts:
         # first line is pylint disable so skip it
         with open(os.path.join(OPENSHIFT_ANSIBLE_PATH, fpart)) as pfd:
+            fragment_banner(fpart, "header", data)
             for idx, line in enumerate(pfd):
                 if idx in [0, 1] and 'flake8: noqa' in line or 'pylint: skip-file' in line:  # noqa: E501
                     continue
 
                 data.write(line)
 
+            fragment_banner(fpart, "footer", data)
     return data
 
 
diff --git a/roles/lib_utils/library/yedit.py b/roles/lib_utils/library/yedit.py
index 6a5b40dcc..8a2bd92f9 100644
--- a/roles/lib_utils/library/yedit.py
+++ b/roles/lib_utils/library/yedit.py
@@ -24,6 +24,8 @@
 # limitations under the License.
 #
 
+# -*- -*- -*- Begin included fragment: class/import.py -*- -*- -*-
+
 # pylint: disable=wrong-import-order
 import json
 import os
@@ -33,6 +35,10 @@ import ruamel.yaml as yaml
 import shutil
 from ansible.module_utils.basic import AnsibleModule
 
+# -*- -*- -*- End included fragment: class/import.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: doc/yedit -*- -*- -*-
+
 DOCUMENTATION = '''
 ---
 module: yedit
@@ -168,6 +174,10 @@ EXAMPLES = '''
 #   b:
 #     c: d
 '''
+
+# -*- -*- -*- End included fragment: doc/yedit -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: class/yedit.py -*- -*- -*-
 # noqa: E301,E302
 
 
@@ -733,6 +743,10 @@ class Yedit(object):
 
         return {'failed': True, 'msg': 'Unkown state passed'}
 
+# -*- -*- -*- End included fragment: class/yedit.py -*- -*- -*-
+
+# -*- -*- -*- Begin included fragment: ansible/yedit.py -*- -*- -*-
+
 
 # pylint: disable=too-many-branches
 def main():
@@ -772,3 +786,5 @@ def main():
 
 if __name__ == '__main__':
     main()
+
+# -*- -*- -*- End included fragment: ansible/yedit.py -*- -*- -*-
diff --git a/roles/lib_utils/src/generate.py b/roles/lib_utils/src/generate.py
index 6daade108..3f23455b5 100755
--- a/roles/lib_utils/src/generate.py
+++ b/roles/lib_utils/src/generate.py
@@ -27,19 +27,54 @@ def parse_args():
     return parser.parse_args()
 
 
+def fragment_banner(fragment_path, side, data):
+    """Generate a banner to wrap around file fragments
+
+:param string fragment_path: A path to a module fragment
+:param string side: ONE OF: "header", "footer"
+:param StringIO data: A StringIO object to write the banner to
+"""
+    side_msg = {
+        "header": "Begin included fragment: {}",
+        "footer": "End included fragment: {}"
+    }
+    annotation = side_msg[side].format(fragment_path)
+
+    banner = """
+# -*- -*- -*- {} -*- -*- -*-
+""".format(annotation)
+
+    # Why skip?
+    #
+    # * 'generated' - This is the head of the script, we don't want to
+    #   put comments before the #!shebang
+    #
+    # * 'license' - Wrapping this just seemed like gratuitous extra
+    if ("generated" not in fragment_path) and ("license" not in fragment_path):
+        data.write(banner)
+
+    # Make it self-contained testable
+    return banner
+
+
 def generate(parts):
-    '''generate the source code for the ansible modules'''
+    '''generate the source code for the ansible modules
+
+:param Array parts: An array of paths (strings) to module fragments
+    '''
 
     data = six.StringIO()
     for fpart in parts:
         # first line is pylint disable so skip it
         with open(os.path.join(OPENSHIFT_ANSIBLE_PATH, fpart)) as pfd:
+            fragment_banner(fpart, "header", data)
             for idx, line in enumerate(pfd):
                 if idx in [0, 1] and 'flake8: noqa' in line or 'pylint: skip-file' in line:  # noqa: E501
                     continue
 
                 data.write(line)
 
+            fragment_banner(fpart, "footer", data)
     return data