Deprecate 'options' argument to 'expand_template' (#1085)

The only known use of the 'options' argument is to force EmPy to treat
bangpaths as comments. This change promotes that option to an explicit
keyword argument of 'expand_template', which decouples the API from the
EmPy API.

Any current uses of 'options' will continue to work, and the new
'ignore_bangpath' option will take precedence in a collision.

ros_buildfarm/scripts/ci/generate_ci_script.py

@@ -17,7 +17,6 @@
 import re
 import sys
 
-from em import BANGPATH_OPT
 from em import Hook
 from ros_buildfarm.argument import add_argument_arch
 from ros_buildfarm.argument import add_argument_build_name
@@ -163,7 +162,7 @@ def beforeInclude(self, *_, **kwargs):
             'scripts': hook.scripts,
             'build_tool': args.build_tool or build_file.build_tool,
             'parameters': hook.parameters},
-        options={BANGPATH_OPT: False})
+        ignore_bangpath=True)
     value = re.sub(r'(^| )python3 ', r'\1' + sys.executable + ' ', value, flags=re.M)
     print(value)
 

ros_buildfarm/scripts/devel/generate_devel_script.py

@@ -16,7 +16,6 @@
 import re
 import sys
 
-from em import BANGPATH_OPT
 from em import Hook
 from ros_buildfarm.argument import add_argument_arch
 from ros_buildfarm.argument import add_argument_build_name
@@ -140,7 +139,7 @@ def beforeInclude(self, *_, **kwargs):
             'scms': hook.scms,
             'scripts': hook.scripts,
             'build_tool': args.build_tool or build_file.build_tool},
-        options={BANGPATH_OPT: False})
+        ignore_bangpath=True)
     value = re.sub(r'(^| )python3 ', r'\1' + sys.executable + ' ', value, flags=re.M)
     print(value)
 

ros_buildfarm/scripts/doc/generate_doc_script.py

@@ -16,7 +16,6 @@
 import re
 import sys
 
-from em import BANGPATH_OPT
 from em import Hook
 from ros_buildfarm.argument import add_argument_arch
 from ros_buildfarm.argument import add_argument_build_name
@@ -127,7 +126,7 @@ def beforeInclude(self, *args, **kwargs):
             'scms': hook.scms,
             'scripts': scripts,
             'doc_path': doc_path},
-        options={BANGPATH_OPT: False})
+        ignore_bangpath=True)
     value = re.sub(r'(^| )python3 ', r'\1' + sys.executable + ' ', value, flags=re.M)
     print(value)
 

ros_buildfarm/scripts/prerelease/generate_prerelease_overlay_script.py

@@ -19,7 +19,6 @@
 import sys
 
 from catkin_pkg.packages import find_packages
-from em import BANGPATH_OPT
 from ros_buildfarm.argument import add_argument_arch
 from ros_buildfarm.argument import add_argument_config_url
 from ros_buildfarm.argument import add_argument_os_code_name
@@ -111,7 +110,7 @@ def main(argv=sys.argv[1:]):
         value = expand_template(
             'prerelease/prerelease_overlay_script.sh.em', {
                 'scms': scms},
-            options={BANGPATH_OPT: False})
+            ignore_bangpath=True)
         print(value)
 
 

ros_buildfarm/scripts/prerelease/generate_prerelease_script.py

@@ -20,7 +20,6 @@
 import stat
 import sys
 
-from em import BANGPATH_OPT
 from em import Hook
 from ros_buildfarm.argument import add_argument_arch
 from ros_buildfarm.argument import add_argument_build_name
@@ -294,7 +293,7 @@ def beforeInclude(self, *_, **kwargs):
             'prerelease_clone_underlay']:
         content = expand_template(
             'prerelease/%s_script.sh.em' % script_name, data,
-            options={BANGPATH_OPT: False})
+            ignore_bangpath=True)
         script_file = os.path.join(args.output_dir, script_name + '.sh')
         with open(script_file, 'w') as h:
             h.write(content)

ros_buildfarm/scripts/release/generate_release_script.py

@@ -16,7 +16,6 @@
 import re
 import sys
 
-from em import BANGPATH_OPT
 from em import Hook
 from ros_buildfarm.argument import add_argument_arch
 from ros_buildfarm.argument import add_argument_build_name
@@ -151,7 +150,7 @@ def beforeInclude(self, *args, **kwargs):
             'source_scripts': source_scripts,
             'binary_scripts': binary_scripts,
             'package_format': package_format},
-        options={BANGPATH_OPT: False})
+        ignore_bangpath=True)
     value = re.sub(r'(^| )python3 ', r'\1' + sys.executable + ' ', value, flags=re.M)
     print(value)
 

ros_buildfarm/templates/__init__.py

@@ -21,8 +21,10 @@
 import os
 import sys
 import time
+import warnings
 from xml.sax.saxutils import escape
 
+from em import BANGPATH_OPT
 from em import Interpreter
 
 template_prefix_path = [os.path.abspath(os.path.dirname(__file__))]
@@ -67,10 +69,24 @@ def parse(self, scanner, locals=None):
             token.run(self, locals)
 
 
-def expand_template(template_name, data, options=None):
+def expand_template(
+    template_name, data, options=None, *, ignore_bangpath=None,
+):
     global interpreter
     global template_hooks
 
+    if options is not None:
+        warnings.warn(
+            "The 'options' argument is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2)
+
+    if ignore_bangpath:
+        options = {
+            **(options or {}),
+            BANGPATH_OPT: False,
+        }
+
     output = StringIO()
     try:
         interpreter = CachingInterpreter(output=output, options=options)