Feature/meta tag to cancel rendering

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2024-05-30
+
+### Added
+
+- New Extension that adds a `{% skip_if %}` tag where you can insert any 
+ condition (e.g. checking the Context) and if it evals as True, a 
+ `CancelRendering` exception is raised and caught by the Renderers causing 
+ them to silently just skip rendering that template.
+ - The `StringRenderer` returns `None`
+ - The `StoutRenderer` prints out nothing
+ - The `FileRenderer` doesn't create an output file
+- Added unittests for the `{% skip_if %}` tag
+
+
 ## [0.3.0] - 2024-05-28
 
 ### Fixed

ccpstencil/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '0.3.0'
+__version__ = '0.4.0'
 
 __author__ = 'Thordur Matthiasson <[email protected]>'
 __license__ = 'MIT License'

ccpstencil/jinjaext/extensions/__init__.py

@@ -1 +1,2 @@
 from ._embed import *
+from ._skip_if import *

ccpstencil/jinjaext/extensions/_skip_if.py

@@ -0,0 +1,21 @@
+__all__ = [
+ 'SkipIfExtension',
+]
+from jinja2 import nodes
+from jinja2.ext import Extension
+from ccpstencil.structs import *
+
+
+class SkipIfExtension(Extension):
+ tags = {'skip_if'}
+
+ def parse(self, parser):
+ lineno = next(parser.stream).lineno
+ # Parse the condition expression
+ condition = parser.parse_expression()
+ return nodes.CallBlock(self.call_method('_check_condition', [condition]), [], [], []).set_lineno(lineno)
+
+ def _check_condition(self, condition, caller):
+ if condition:
+ raise CancelRendering("Rendering cancelled due to meta_only_render_if condition being False")
+ return ''

ccpstencil/renderer/_base.py

@@ -125,13 +125,22 @@ def template(self, value: ITemplate):
  value.set_renderer(self)
  self._template = value
 
- @abc.abstractmethod
  def render(self):
- """This should just be called by subclasses via super().render() in
- order to run preflight and common stuff, but the empty return value
- should be ignored.
- """
  self._pre_flight()
+ try:
+ rendered_string = self._render_as_string()
+ return self._output_rendered_results(rendered_string)
+ except CancelRendering:
+ log.info(f'Rendering cancelled by skip_if tag')
+ return None
+
+ @abc.abstractmethod
+ def _output_rendered_results(self, rendered_string: str):
+ pass
+
+ @abc.abstractmethod
+ def _render_as_string(self) -> str:
+ pass
 
  @property
  def jinja_environment(self) -> jinja2.Environment:

ccpstencil/renderer/_file.py

@@ -19,9 +19,19 @@ def __init__(self, output_file: Union[str, Path],
  super().__init__(context, template, **kwargs)
 
  def render(self) -> str:
+ return super().render()
+
+ def _output_rendered_results(self, rendered_string: str) -> str:
+ results = super().render()
+ if results is None:
+ return f'Skipped: {self._output_file.absolute()}'
+
  if self._output_file.exists() and not self._overwrite:
- raise OutputFileExistsError(f'The target output file already exists and overwriting is disabled: {self._output_file.absolute()}')
+ raise OutputFileExistsError(f'The target output file already exists and overwriting is'
+ f' disabled: {self._output_file.absolute()}')
  self._output_file.parent.mkdir(parents=True, exist_ok=True)
+
  with open(self._output_file, 'w') as fout:
- fout.write(super().render())
+ fout.write(results)
  return str(self._output_file.absolute())
+

ccpstencil/renderer/_stdout.py

@@ -2,10 +2,12 @@
  'StdOutRenderer',
 ]
 
-
+from ccpstencil.structs import *
 from ._string import *
 
 
 class StdOutRenderer(StringRenderer):
- def render(self):
- print(super().render())
+ def render(self) -> NoReturn:
+ results = super().render()
+ if results is not None:
+ print(results)

ccpstencil/renderer/_string.py

@@ -10,8 +10,11 @@ class StringRenderer(_BaseRenderer):
  def __init__(self, context: Optional[IContext] = None, template: Optional[ITemplate] = None, **kwargs):
  super().__init__(context, template, **kwargs)
 
- def render(self) -> str:
- super().render()
- return self.template.get_jinja_template().render(**self.context.as_dict())
+ def render(self) -> Optional[str]:
+ return super().render()
 
+ def _render_as_string(self) -> str:
+ return self.template.get_jinja_template().render(**self.context.as_dict())
 
+ def _output_rendered_results(self, rendered_string: str) -> str:
+ return rendered_string

ccpstencil/structs/_errors.py

@@ -12,6 +12,8 @@
  'InvalidTemplateTypeForRendererError',
  'OutputFileExistsError',
  'EmbedFileNotFound',
+
+ 'CancelRendering',
 ]
 
 
@@ -53,3 +55,7 @@ class OutputFileExistsError(RenderError, FileExistsError):
 
 class EmbedFileNotFound(RenderError, FileNotFoundError):
  pass
+
+
+class CancelRendering(Exception):
+ pass

tests/res/skipif/context.yaml

@@ -0,0 +1,10 @@
+mode:
+ normal:
+ adjective: Now
+ positive:
+ enabled: true
+ adjective: Shiny
+ negative:
+ enabled: false
+ adjective: Shitty
+number: 7

tests/res/skipif/template_negative.txt

@@ -0,0 +1,2 @@
+{% skip_if not mode.negative.enabled %}
+The day is {{mode.negative.adjective}}

tests/res/skipif/template_normal.txt

@@ -0,0 +1 @@
+The day is {{mode.normal.adjective}}

tests/res/skipif/template_positive.txt

@@ -0,0 +1,2 @@
+{% skip_if not mode.positive.enabled %}
+The day is {{mode.positive.adjective}}

tests/res/skipif/template_seven.txt

@@ -0,0 +1,2 @@
+{% skip_if number == 7 %}
+Seven!

tests/res/skipif/template_six.txt

@@ -0,0 +1,2 @@
+{% skip_if number == 6 %}
+Six!

tests/test_skip_if.py

@@ -0,0 +1,45 @@
+import unittest
+
+from ccpstencil.stencils import *
+
+import os
+import pathlib
+
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+
+_HERE = pathlib.Path(__file__).parent.resolve()
+
+
+def fp(file_name: str) -> str:
+ return str((_HERE / 'res/skipif/' / file_name).absolute())
+
+
+class TestSkipIf(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ os.environ['STENCIL_TEMPLATE_PATH'] = str(_HERE / 'res/skipif/')
+
+ def test_normal(self):
+ res = render_stencil('template_normal.txt', fp('context.yaml'))
+ self.assertEqual('The day is Now', res)
+
+ def test_skipped(self):
+ res = render_stencil('template_negative.txt', fp('context.yaml'))
+ self.assertIsNone(res)
+
+ def test_not_skipped(self):
+ res = render_stencil('template_positive.txt', fp('context.yaml'))
+ self.assertEqual('The day is Shiny', res)
+
+ def test_numbers(self):
+ # res = render_stencil('template_six.txt', fp('context.yaml'))
+ # self.assertEqual('Six!', res)
+ res = render_stencil('template_seven.txt', fp('context.yaml'))
+ self.assertIsNone(res)
+
+ @classmethod
+ def tearDownClass(cls):
+ if 'STENCIL_TEMPLATE_PATH' in os.environ:
+ del os.environ['STENCIL_TEMPLATE_PATH']