[Resolve #1318] Implement dump template and write output files

docs/_source/docs/resolvers.rst

@@ -476,7 +476,7 @@ have not yet been deployed. During normal deployment operations (using the ``lau
 ensure that order is followed, so everything works as expected.
 
 But there are other commands that will not actually deploy dependencies of a stack config before
-operating on that Stack Config. These commands include ``generate``, ``validate``, and ``diff``.
+operating on that Stack Config. These commands include ``dump template``, ``validate``, and ``diff``.
 If you have used resolvers to reverence other stacks, it is possible that a resolver might not be able
 to be resolved when performing that command's operations and will trigger an error. This is not likely
 to happen when you have only used resolvers in a stack's ``parameters``, but it is much more likely
@@ -491,7 +491,7 @@ A few examples...
   and you run the ``diff`` command before other_stack.yaml has been deployed, the diff output will
   show the value of that parameter to be ``"{ !StackOutput(other_stack.yaml::OutputName) }"``.
 * If you have a ``sceptre_user_data`` value used in a Jinja template referencing
-  ``!stack_output other_stack.yaml::OutputName`` and you run the ``generate`` command, the generated
+  ``!stack_output other_stack.yaml::OutputName`` and you run the ``dump template`` command, the generated
   template will replace that value with ``"StackOutputotherstackyamlOutputName"``. This isn't as
   "pretty" as the sort of placeholder used for stack parameters, but the use of sceptre_user_data is
   broader, so it placeholder values can only be alphanumeric to reduce chances of it breaking the

sceptre/cli/dump.py

@@ -2,8 +2,10 @@
 import click
 
 from sceptre.context import SceptreContext
-from sceptre.cli.helpers import catch_exceptions, write
+from sceptre.cli.helpers import catch_exceptions, dump_to_file
 from sceptre.plan.plan import SceptrePlan
+from sceptre.helpers import null_context
+from sceptre.resolvers.placeholders import use_resolver_placeholders_on_error
 
 logger = logging.getLogger(__name__)
 
@@ -41,15 +43,77 @@ def dump_config(ctx, path):
 
     output = []
     for stack, config in responses.items():
-        if config is None:
-            logger.warning(f"{stack.external_name} does not exist")
-        else:
-            output.append({stack.external_name: config})
+        output.append({stack.external_name: config})
 
     output_format = "json" if context.output_format == "json" else "yaml"
 
-    if len(output) == 1:
-        write(output[0][stack.external_name], output_format)
-    else:
-        for config in output:
-            write(config, output_format)
+    for config in output:
+        dump_to_file(config, output_format, type="config")
+
+
+@dump_group.command(name="template")
+@click.argument("path")
+@click.option(
+    "-n",
+    "--no-placeholders",
+    is_flag=True,
+    help="If True, no placeholder values will be supplied for resolvers that cannot be resolved.",
+)
+@click.pass_context
+@catch_exceptions
+def dump_template(ctx, no_placeholders, path):
+    """
+    Prints the template used for stack in PATH.
+    \f
+
+    :param path: Path to execute the command on.
+    :type path: str
+    """
+    context = SceptreContext(
+        command_path=path,
+        command_params=ctx.params,
+        project_path=ctx.obj.get("project_path"),
+        user_variables=ctx.obj.get("user_variables"),
+        options=ctx.obj.get("options"),
+        output_format=ctx.obj.get("output_format"),
+        ignore_dependencies=ctx.obj.get("ignore_dependencies"),
+    )
+
+    plan = SceptrePlan(context)
+
+    execution_context = (
+        null_context() if no_placeholders else use_resolver_placeholders_on_error()
+    )
+    with execution_context:
+        responses = plan.dump_template()
+
+    output = []
+    for stack, template in responses.items():
+        output.append({stack.external_name: template})
+
+    output_format = "json" if context.output_format == "json" else "yaml"
+
+    for template in output:
+        dump_to_file(template, output_format)
+
+
+@dump_group.command(name="all")
+@click.argument("path")
+@click.option(
+    "-n",
+    "--no-placeholders",
+    is_flag=True,
+    help="If True, no placeholder values will be supplied for resolvers that cannot be resolved.",
+)
+@click.pass_context
+@catch_exceptions
+def dump_all(ctx, no_placeholders, path):
+    """
+    Dumps both the rendered (post-Jinja) Stack Configs and the template used for stack in PATH.
+    \f
+
+    :param path: Path to execute the command on.
+    :type path: str
+    """
+    ctx.invoke(dump_config, path=path)
+    ctx.invoke(dump_template, no_placeholders=no_placeholders, path=path)

sceptre/cli/helpers.py

@@ -1,8 +1,12 @@
 import logging
 import sys
+
 from itertools import cycle
 from functools import partial, wraps
 
+from typing import Any, Optional
+from pathlib import Path
+
 import json
 import click
 import six
@@ -16,6 +20,8 @@
 from sceptre.stack_status import StackStatus
 from sceptre.stack_status_colourer import StackStatusColourer
 
+logger = logging.getLogger(__name__)
+
 
 def catch_exceptions(func):
     """
@@ -66,18 +72,21 @@ def confirmation(command, ignore, command_path, change_set=None):
         click.confirm(msg, abort=True)
 
 
-def write(var, output_format="json", no_colour=True):
+def write(
+    var: Any,
+    output_format: str = "json",
+    no_colour: bool = True,
+    file_path: Optional[Path] = None,
+) -> None:
     """
     Writes ``var`` to stdout. If output_format is set to "json" or "yaml",
     write ``var`` as a JSON or YAML string.
 
     :param var: The object to print
-    :type var: object
     :param output_format: The format to print the output as. Allowed values: \
     "text", "json", "yaml"
-    :type output_format: str
     :param no_colour: Whether to colour stack statuses
-    :type no_colour: bool
+    :param file_path: Optional path to a file to save the output
     """
     output = var
 
@@ -93,6 +102,13 @@ def write(var, output_format="json", no_colour=True):
 
     click.echo(output)
 
+    if file_path:
+        dir_path = file_path.parent
+        dir_path.mkdir(parents=True, exist_ok=True)
+
+        with open(file_path, "w") as f:
+            f.write(output)
+
 
 def _generate_json(stream):
     encoder = CustomJsonEncoder(indent=4)
@@ -173,6 +189,23 @@ def _generate_text(stream):
     return stream
 
 
+def dump_to_file(
+    template: dict, output_format: str, template_type: str = "template"
+) -> None:
+    """
+    Helper to write templates and configs used in dump commands.
+
+    :param template: the template.
+    :param output_format: The format to print the output as. Allowed values: \
+    :param template_type: either template or config used only in the file name.
+    """
+    stack_name = list(template.keys())[0]
+    file_path = Path(".dump") / stack_name / f"{template_type}.{output_format}"
+    logger.info(f"{stack_name} dumping {template_type} to {file_path}")
+    write(template[stack_name], output_format, no_colour=True, file_path=file_path)
+    logger.info(f"{stack_name} dump to {file_path} complete.")
+
+
 def setup_vars(var_file, var, merge_vars, debug, no_colour):
     """
     Handle --var-file and --var arguments before

sceptre/cli/template.py

@@ -1,8 +1,10 @@
 import logging
 import webbrowser
-
 import click
 
+from deprecation import deprecated
+
+from sceptre import __version__
 from sceptre.cli.helpers import catch_exceptions, write
 from sceptre.context import SceptreContext
 from sceptre.helpers import null_context
@@ -65,6 +67,7 @@ def validate_command(ctx, no_placeholders, path):
 @click.argument("path")
 @click.pass_context
 @catch_exceptions
+@deprecated("4.2.0", "5.0.0", __version__, "Use dump template instead.")
 def generate_command(ctx, no_placeholders, path):
     """
     Prints the template used for stack in PATH.

sceptre/plan/actions.py

@@ -12,15 +12,17 @@
 import time
 import typing
 import urllib
-from datetime import datetime, timedelta
-from os import path
-from typing import Dict, Optional, Tuple, Union
-
 import botocore
+
+from datetime import datetime, timedelta
 from dateutil.tz import tzutc
+from os import path
+from deprecation import deprecated
 
+from sceptre import __version__
 from sceptre.config.reader import ConfigReader
 from sceptre.connection_manager import ConnectionManager
+
 from sceptre.exceptions import (
     CannotUpdateFailedStackError,
     ProtectedStackError,
@@ -33,6 +35,8 @@
 from sceptre.stack import Stack
 from sceptre.stack_status import StackChangeSetStatus, StackStatus
 
+from typing import Dict, Optional, Tuple, Union
+
 if typing.TYPE_CHECKING:
     from sceptre.diffing.stack_differ import StackDiff, StackDiffer
 
@@ -624,12 +628,12 @@ def _convert_to_url(self, summaries):
 
         return new_summaries
 
-    @add_stack_hooks
+    @deprecated("4.2.0", "5.0.0", __version__, "Use dump template instead.")
     def generate(self):
         """
         Returns the Template for the Stack
         """
-        return self.stack.template.body
+        return self.dump_template()
 
     @add_stack_hooks
     def validate(self):
@@ -1152,3 +1156,10 @@ def dump_config(self, config_reader: ConfigReader):
         """
         stack_path = normalise_path(self.stack.name + ".yaml")
         return config_reader.read(stack_path)
+
+    @add_stack_hooks
+    def dump_template(self):
+        """
+        Returns the Template for the Stack
+        """
+        return self.stack.template.body

sceptre/plan/plan.py

@@ -8,8 +8,10 @@
 """
 import functools
 import itertools
+
 from os import path, walk
 from typing import Dict, List, Set, Callable, Iterable, Optional
+from deprecation import deprecated
 
 from sceptre.config.graph import StackGraph
 from sceptre.config.reader import ConfigReader
@@ -19,6 +21,7 @@
 from sceptre.helpers import sceptreise_path
 from sceptre.plan.executor import SceptrePlanExecutor
 from sceptre.stack import Stack
+from sceptre import __version__
 
 
 def require_resolved(func) -> Callable:
@@ -440,3 +443,14 @@ def dump_config(self, *args):
         """
         self.resolve(command=self.dump_config.__name__)
         return self._execute(self.config_reader, *args)
+
+    @deprecated("4.2.0", "5.0.0", __version__, "Use dump template instead.")
+    def dump_template(self, *args):
+        """
+        Returns a generated Template for a given Stack
+
+        :returns: A dictionary of Stacks and their template body.
+        :rtype: dict
+        """
+        self.resolve(command=self.dump_template.__name__)
+        return self._execute(*args)

sceptre/stack.py

@@ -8,9 +8,9 @@
 """
 
 import logging
-from typing import List, Any, Optional
 
-import deprecation
+from typing import List, Any, Optional
+from deprecation import deprecated
 
 from sceptre import __version__
 from sceptre.connection_manager import ConnectionManager
@@ -383,7 +383,7 @@ def template(self):
         return self._template
 
     @property
-    @deprecation.deprecated(
+    @deprecated(
         "4.0.0", "5.0.0", __version__, "Use the template Stack Config key instead."
     )
     def template_path(self) -> str:
@@ -393,7 +393,7 @@ def template_path(self) -> str:
         return self.template_handler_config["path"]
 
     @template_path.setter
-    @deprecation.deprecated(
+    @deprecated(
         "4.0.0", "5.0.0", __version__, "Use the template Stack Config key instead."
     )
     def template_path(self, value: str):

tests/test_connection_manager.py

@@ -1,11 +1,12 @@
 # -*- coding: utf-8 -*-
 import warnings
+import pytest
+
 from collections import defaultdict
 from typing import Union
 from unittest.mock import Mock, patch, sentinel, create_autospec
+from deprecation import fail_if_not_removed
 
-import deprecation
-import pytest
 from boto3.session import Session
 from botocore.exceptions import ClientError
 from moto import mock_s3
@@ -805,11 +806,11 @@ def test_create_session_environment_variables__include_system_envs_false__does_n
         }
         assert expected == result
 
-    @deprecation.fail_if_not_removed
+    @fail_if_not_removed
     def test_iam_role__is_removed_on_removal_version(self):
         self.connection_manager.iam_role
 
-    @deprecation.fail_if_not_removed
+    @fail_if_not_removed
     def test_iam_role_session_duration__is_removed_on_removal_version(self):
         self.connection_manager.iam_role_session_duration
 

tests/test_plan.py

@@ -1,6 +1,8 @@
 import pytest
 from unittest.mock import MagicMock, patch, sentinel
 
+from deprecation import fail_if_not_removed
+
 from sceptre.context import SceptreContext
 from sceptre.stack import Stack
 from sceptre.config.reader import ConfigReader
@@ -61,3 +63,9 @@ def test_command_not_found_error_raised(self):
             plan = MagicMock(spec=SceptrePlan)
             plan.context = self.mock_context
             plan.invalid_command()
+
+    @fail_if_not_removed
+    def test_generate_removed(self):
+        plan = MagicMock(spec=SceptrePlan)
+        plan.context = self.mock_context
+        plan.generate("test-attribute")