batstencil 1.0.0__py3-none-any.whl

batstencil/__init__.py

@@ -0,0 +1,5 @@
+__version__ = '1.0.0'
+
+__author__ = 'Thordur Matthiasson <doddi79@gmail.com>'
+__license__ = 'MIT License'
+__copyright__ = 'Copyright 2024 - CCP Games ehf, 2026 - Thordur Matthiasson'

batstencil/__main__.py

@@ -0,0 +1,4 @@
+from batstencil.cli.bat_stencil.main import main
+
+if __name__ == '__main__':
+    main()

batstencil/cli/bat_stencil/_runner.py

@@ -0,0 +1,88 @@
+__all__ = [
+    'StencilRunner',
+]
+import os
+import sys
+from batstencil.structs import *
+from batstencil.stencils import *
+import logging
+log = logging.getLogger(__name__)
+
+
+class StencilRunner:
+    """Runs the `bat-stencil` command line (also usable from code)"""
+    def __init__(self):
+        self.verbose: bool = False
+
+        self.template: Optional[str] = None
+        self.string_template: Optional[str] = None
+        self.directory_template: Optional[str] = None
+
+        self.input: Optional[str] = None
+        self.additional_arg_list: List[str] = []
+
+        self.output: Optional[str] = None
+        self.no_overwrite: bool = False
+        self.no_purge: bool = False
+
+    def _make_cwd_importable(self):
+        cwd = os.getcwd()
+        log.debug(f'os.getcwd()={cwd}')
+        if cwd not in sys.path:
+            sys.path.append(cwd)
+
+    def run(self):
+        self._make_cwd_importable()
+        rnd = self.get_renderer()
+        rnd.template = self.get_template()
+        rnd.context = self.get_context()
+        res = rnd.render()
+        if self.output:
+            if isinstance(res, list):
+                for f in res:
+                    print(f'Wrote file: {f}')
+            elif res is None:
+                print('Skipped rendering (skip_if)')
+            else:
+                print(f'Wrote file: {res}')
+
+    def get_template(self) -> ITemplate:
+        if self.directory_template:
+            return DirectoryTemplate(self.directory_template)
+        elif self.template:
+            return FileTemplate(self.template)
+        else:
+            return StringTemplate(self.string_template)
+
+    def _parse_arg(self, arg_str: str) -> Tuple[str, str]:
+        log.debug(f'_parse_arg({arg_str})')
+        if '=' not in arg_str:
+            raise ContextError(f'Invalid argument "{arg_str}", expected key=value (e.g. -a foo=bar)')
+        key, value = arg_str.split('=', maxsplit=1)
+        if not key.strip():
+            raise ContextError(f'Invalid argument "{arg_str}", the key is empty')
+        return key.strip(), value
+
+    def get_context(self) -> IContext:
+        if self.input:
+            ctx = AllConfContext(self.input)
+        else:
+            ctx = DictContext()
+
+        if self.additional_arg_list:
+            for arg in self.additional_arg_list:
+                ctx.nested_update(*self._parse_arg(arg))
+        return ctx
+
+    def get_renderer(self) -> IRenderer:
+        if self.directory_template:
+            if not self.output:
+                raise RenderError('Must specify output directory for directory rendering')
+            return DirectoryRenderer(output_path=self.output,
+                                     overwrite=not self.no_overwrite,
+                                     purge=not self.no_purge)
+        elif self.output:
+            return FileRenderer(self.output,
+                                overwrite=not self.no_overwrite)
+        else:
+            return StdOutRenderer()

batstencil/cli/bat_stencil/main.py

@@ -0,0 +1,80 @@
+import argparse
+
+from batstencil import __version__ as version
+from batstencil.structs import *
+from ._runner import StencilRunner
+
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(prog='bat-stencil',
+                                     description='Renders a template (or a directory of templates) using Jinja2'
+                                                 ' with an AllConf (YAML/JSON) input context',
+                                     epilog=f'bat-stencil version {version}')
+
+    parser.add_argument('--version', action='version', version=f'%(prog)s {version}')
+
+    parser.add_argument('-v', '--verbose', action="store_true", help='Spits out DEBUG level logs')
+
+    parser.add_argument('-i', '--input', nargs='?', help='AllConf file with input context (YAML or JSON)')
+
+    parser.add_argument('-a', '--arg', action='append',
+                        help='Add additional Context arguments from the command line, e.g. -a foo=bar'
+                             ' (nested keys with dots, e.g. -a app.name=bar)')
+
+    parser.add_argument('-o', '--output', help='Path or file to write the results to (otherwise its just printed to stdout).'
+                                               ' If this is a path (ends with /), the name of the rendered file will be the same as the input template.',
+                        default='', nargs='?')
+    parser.add_argument('--no-overwrite', action="store_true", help='Makes sure existing output files are not overwritten')
+    parser.add_argument('--no-purge', action="store_true", help='Skips purging the output path when rendering directories')
+
+    input_group = parser.add_mutually_exclusive_group(required=True)
+    input_group.add_argument('-t', '--template', default='',
+                             help='Template file to render')
+    input_group.add_argument('-s', '--string-template', default='',
+                             help='Supply a string directly from the command line to use as a template instead of a file')
+    input_group.add_argument('-d', '--directory-template', default='',
+                             help='Root directory of files and directories to render. This requires the output argument to be a directory')
+
+    args = parser.parse_args()
+
+    if args.verbose:
+        import logging
+        logging.basicConfig(level=logging.DEBUG)
+
+        log = logging.getLogger(__name__)
+        log.info('Verbose logging enabled')
+        log.info(f'Args: {args=}')
+
+    runner = StencilRunner()
+    runner.verbose = args.verbose or False
+    runner.input = args.input or None
+    runner.output = args.output or None
+    runner.no_overwrite = args.no_overwrite or False
+    runner.no_purge = args.no_purge or False
+    runner.template = args.template or None
+    runner.string_template = args.string_template or None
+    runner.directory_template = args.directory_template or None
+    if args.arg:
+        for arg in args.arg:
+            runner.additional_arg_list.append(arg)
+
+    try:
+        runner.run()
+    except StencilError as e:
+        print(f'An error occurred: {e}', file=sys.stderr)
+        if e.__cause__ is not None and args.verbose:
+            raise
+        sys.exit(3)
+    except jinja2.TemplateError as e:
+        where = f' in {e.filename}' if getattr(e, 'filename', None) else ''
+        line = f' (line {e.lineno})' if getattr(e, 'lineno', None) else ''
+        print(f'Template error{where}{line}: {e.__class__.__name__}: {e}', file=sys.stderr)
+        if args.verbose:
+            raise
+        sys.exit(3)
+
+
+if __name__ == '__main__':
+    main()

batstencil/context/__init__.py

@@ -0,0 +1,4 @@
+from batstencil.structs.interfaces import IContext
+from ._dict import *
+from ._kwarg import *
+from ._allconf import *

batstencil/context/_allconf.py

@@ -0,0 +1,40 @@
+__all__ = [
+    'AllConfContext',
+    'AlvissContext',
+]
+
+from batstencil.structs import *
+from allconf import quickloader
+from batutils.tpu import iters
+from pathlib import Path
+import logging
+log = logging.getLogger(__name__)
+
+
+class AllConfContext(IContext):
+    """A context loaded from an AllConf (JSON/YAML) file, with all of AllConf's
+    bells and whistles (includes, extensions, internal references,
+    `${__ENV__:...}`, `${__PY__:...}` etc.)."""
+    def __init__(self, file_name: Union[str, Path], **kwargs):
+        self._file_name = str(file_name)
+        self._data = quickloader.autoload(self._file_name)
+
+    @property
+    def file_name(self) -> str:
+        return self._file_name
+
+    def update(self, key: str, value: Any):
+        self.as_dict()[key] = value
+
+    def nested_update(self, key_tuple: Union[str, Sequence[str]], value: Any):
+        log.debug(f'nested_update({key_tuple=}, {value=})')
+        if isinstance(key_tuple, str):
+            key_tuple = key_tuple.split('.')
+        iters.nested_set(self.as_dict(), list(key_tuple), value)
+
+    def as_dict(self) -> Dict:
+        return self._data.as_dict(unmaksed=True)
+
+
+AlvissContext = AllConfContext
+"""Deprecated alias of `AllConfContext` (from back when AllConf was Alviss)"""

batstencil/context/_dict.py

@@ -0,0 +1,25 @@
+__all__ = [
+    'DictContext',
+]
+
+from batstencil.structs import *
+from batutils.tpu import iters
+import logging
+log = logging.getLogger(__name__)
+
+
+class DictContext(IContext):
+    def __init__(self, context_map: Optional[Dict[str, Any]] = None, **kwargs):
+        self._context_map = context_map if context_map is not None else {}
+
+    def update(self, key: str, value: Any):
+        self._context_map[key] = value
+
+    def nested_update(self, key_tuple: Union[str, Sequence[str]], value: Any):
+        log.debug(f'nested_update({key_tuple=}, {value=})')
+        if isinstance(key_tuple, str):
+            key_tuple = key_tuple.split('.')
+        iters.nested_set(self._context_map, list(key_tuple), value)
+
+    def as_dict(self) -> Dict:
+        return self._context_map

batstencil/context/_kwarg.py

@@ -0,0 +1,10 @@
+__all__ = [
+    'KeyWordArgumentContext',
+]
+
+from ._dict import *
+
+
+class KeyWordArgumentContext(DictContext):
+    def __init__(self, **kwargs):
+        super().__init__(context_map=kwargs)

batstencil/jinjaext/extensions/__init__.py

@@ -0,0 +1,4 @@
+from ._embed import *
+from ._skip_if import *
+from ._setfilename import *
+from ._repeat_for import *

batstencil/jinjaext/extensions/_embed.py

@@ -0,0 +1,54 @@
+__all__ = [
+    'EmbedExtension',
+]
+
+from jinja2 import nodes
+from jinja2.ext import Extension
+from batstencil.structs import *
+
+
+class EmbedExtension(Extension):
+    """Adds the `{% embed 'file' %}` tag that embeds a file "as-is" (not as a
+    template), with these optional arguments:
+
+    - `indent=N` to indent every line by N spaces (e.g. for YAML)
+    - `allconf=True` to render the file with AllConf first (`alviss=True` is a
+      deprecated alias), along with `env=True`, `fidelius=True` and `py=True`
+      to resolve `${__ENV__:...}`, `${__FID__:...}` and `${__PY__:...}`
+      expressions
+    """
+    tags = {'embed'}
+
+    def __init__(self, environment):
+        super().__init__(environment)
+        environment.extend(stencil_renderer=None)
+
+    @property
+    def renderer(self) -> IRenderer:
+        return self.environment.stencil_renderer  # noqa
+
+    def parse(self, parser):
+        lineno = next(parser.stream).lineno
+        args = [parser.parse_expression()]
+        source_file = parser.filename
+        kwargs = [nodes.Keyword('source_file', nodes.Const(source_file))]
+        while parser.stream.skip_if('comma'):
+            key = parser.stream.expect('name').value
+            parser.stream.expect('assign')
+            value = parser.parse_expression()
+            kwargs.append(nodes.Keyword(key, value))
+
+        return nodes.CallBlock(self.call_method('_render_embed', args, kwargs), [], [], []).set_lineno(lineno)
+
+    def _render_embed(self, file_path, source_file: Optional[str] = None, indent: int = 0,
+                      caller=None, **kwargs):
+
+        # Check if file_path is a variable in the context
+        if callable(file_path):
+            file_path = file_path()
+
+        content = self.renderer.get_embed(file_path, source_file=source_file, **kwargs)
+
+        indent_str = ' ' * int(indent or 0)
+
+        return f'{indent_str}{indent_str.join(content.splitlines(True))}\n'

batstencil/jinjaext/extensions/_repeat_for.py

@@ -0,0 +1,44 @@
+__all__ = [
+    'RepeatForExtension',
+]
+from jinja2 import nodes
+from jinja2.ext import Extension
+from batstencil.structs import *
+
+
+class RepeatForExtension(Extension):
+    """Adds the `{% repeat_for item in items %}` tag (also
+    `{% repeat_for key, value in some_dict.items() %}`) that makes the
+    `DirectoryRenderer` render the template, or the directory when used in a
+    `__stencil_meta__` file, once per item, with the loop variable(s) added to
+    the context (and loop info in `__stencil__.loop`).
+
+    Use `{% setfilename %}` along with it to give each copy a unique name.
+    """
+    tags = {'repeat_for'}
+
+    def __init__(self, environment):
+        super().__init__(environment)
+        environment.extend(stencil_renderer=None)
+
+    def parse(self, parser):
+        lineno = next(parser.stream).lineno
+        target = parser.parse_assign_target(extra_end_rules=('name:in',))
+        if isinstance(target, nodes.Name):
+            names = [target.name]
+        elif isinstance(target, nodes.Tuple) and all(isinstance(n, nodes.Name) for n in target.items):
+            names = [n.name for n in target.items]
+        else:
+            parser.fail('repeat_for expects a variable name (or names) like: repeat_for item in items', lineno)
+        parser.stream.expect('name:in')
+        iterable = parser.parse_expression()
+        return nodes.CallBlock(self.call_method('_repeat_for', [nodes.Const(names), iterable]),  # noqa
+                               [], [], []).set_lineno(lineno)
+
+    def _repeat_for(self, names: List[str], iterable, caller):
+        renderer = self.environment.stencil_renderer  # noqa
+        if getattr(renderer, 'repeat_mode', None) == 'ignore':
+            return ''  # The loop item has already been set
+        if isinstance(iterable, jinja2.Undefined) or iterable is None:
+            iterable = []
+        raise RepeatRendering(names, iterable)

batstencil/jinjaext/extensions/_setfilename.py

@@ -0,0 +1,38 @@
+__all__ = [
+    'SetFilenameExtension',
+]
+
+from jinja2 import nodes
+from jinja2.ext import Extension
+from batstencil.structs import *
+import logging
+log = logging.getLogger(__name__)
+
+
+class SetFilenameExtension(Extension):
+    """Adds the `{% setfilename %}...{% endsetfilename %}` tag that sets the
+    name of the rendered file (or directory, in `__stencil_meta__` files) to
+    whatever its body renders as (stripped)."""
+    tags = {'setfilename'}
+
+    def __init__(self, environment):
+        super().__init__(environment)
+        environment.extend(stencil_renderer=None)
+
+    @property
+    def renderer(self) -> IRenderer:
+        return self.environment.stencil_renderer  # noqa
+
+    def parse(self, parser):
+        lineno = next(parser.stream).lineno
+        body = parser.parse_statements(('name:endsetfilename',), drop_needle=True)
+        return nodes.CallBlock(self.call_method('_set_filename', [nodes.Const(parser.filename)]),
+                               [], [], body).set_lineno(lineno)
+
+    def _set_filename(self, source_file: Optional[str], caller):
+        name = caller().strip()
+        if not name:
+            log.warning(f'The setfilename tag in {source_file or "a template"} rendered an empty file name'
+                        f' (check the template code and context), so it is ignored and the default name is used')
+        self.renderer.output_file_name = name
+        return ''

batstencil/jinjaext/extensions/_skip_if.py

@@ -0,0 +1,24 @@
+__all__ = [
+    'SkipIfExtension',
+]
+from jinja2 import nodes
+from jinja2.ext import Extension
+from batstencil.structs import *
+
+
+class SkipIfExtension(Extension):
+    """Adds the `{% skip_if <condition> %}` tag that skips rendering the
+    template (or directory, in `__stencil_meta__` files) if the condition is
+    true."""
+    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 a skip_if condition being true')
+        return ''

batstencil/jinjaext/filters/__init__.py

@@ -0,0 +1 @@
+from ._base64 import *

batstencil/jinjaext/filters/_base64.py

@@ -0,0 +1,13 @@
+__all__ = [
+    'base64',
+]
+
+import base64 as _base64
+from typing import *
+
+
+def base64(value: Union[str, bytes]) -> str:
+    """Base64 encodes a value (e.g. for Kubernetes Secrets) as a single line"""
+    if not isinstance(value, bytes):
+        value = str(value).encode('utf-8')
+    return _base64.b64encode(value).decode('ascii')

batstencil/renderer/__init__.py

@@ -0,0 +1,6 @@
+from batstencil.structs.interfaces import IRenderer
+from ._base import *
+from ._string import *
+from ._stdout import *
+from ._file import *
+from ._dir import *