dsw-templating 4.35.0__py3-none-any.whl

dsw/templating/__init__.py

@@ -0,0 +1,32 @@
+"""Rendering of DSW document templates, without any services behind it."""
+from .consts import VERSION
+from .context import ContextDefaults, enrich_context_config
+from .documents import DocumentFile, FileFormat, FileFormats
+from .exceptions import MissingExtraError, TemplateError, TemplateTriggeredError
+from .formats import Format
+from .locales import RenderContext, TemplateLocale
+from .plugins import create_manager, hookimpl, hookspec, register_plugin_steps
+from .settings import (
+    PandocSettings,
+    RenderSettings,
+    RequestsSettings,
+    SecuritySettings,
+    TemplateSettings,
+)
+from .steps import FormatStepError, Step
+from .steps.base import register_step
+from .template import Asset, AssetMetadata, ProjectFileResolver, Template
+
+
+__all__ = [
+    'VERSION',
+    'ContextDefaults', 'enrich_context_config',
+    'Asset', 'AssetMetadata', 'ProjectFileResolver', 'Template',
+    'DocumentFile', 'FileFormat', 'FileFormats',
+    'Format', 'FormatStepError', 'Step', 'register_step',
+    'MissingExtraError', 'TemplateError', 'TemplateTriggeredError',
+    'RenderContext', 'TemplateLocale',
+    'PandocSettings', 'RenderSettings', 'RequestsSettings', 'SecuritySettings',
+    'TemplateSettings',
+    'create_manager', 'hookimpl', 'hookspec', 'register_plugin_steps',
+]

dsw/templating/build_info.py

@@ -0,0 +1,17 @@
+# Generated file
+# - do not overwrite
+# - do not include in git
+from collections import namedtuple
+
+BuildInfo = namedtuple(
+    'BuildInfo',
+    ['version', 'built_at', 'sha', 'branch', 'tag'],
+)
+
+BUILD_INFO = BuildInfo(
+    version='v4.35.0~a55653b',
+    built_at='2026-10-06 09:23:39Z',
+    sha='a55653b2611764140b5c31f0aed558e618d3a4ab',
+    branch='HEAD',
+    tag='v4.35.0',
+)

dsw/templating/consts.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+DEFAULT_ENCODING = 'utf-8'
+EXIT_SUCCESS = 0
+PACKAGE_NAME = 'dsw-templating'
+PLUGINS_ENTRYPOINT = 'dsw_templating_plugins'
+
+JINJA_EXTENSIONS = ('jinja2.ext.do', 'jinja2.ext.loopcontrols')
+JINJA_FILE_EXTENSIONS = ('.j2', '.jinja', '.jinja2', '.jnj')
+
+# Rendering and POT extraction must agree on this: the msgid of a {% trans %}
+# block depends on it, and the POT file is per document template while a step
+# option would be per format.
+JINJA_I18N_TRIMMED = True
+
+DEFAULT_LANGUAGE = 'en'
+DEFAULT_LOCALE_DOMAIN = 'default'
+
+TEMPLATE_JSON_FILE_NAME = 'template.json'
+PROJECT_FILES_DIR = 'project-files'
+
+try:
+    __version__ = version(PACKAGE_NAME)
+except PackageNotFoundError:
+    __version__ = '0.0.0'
+VERSION = __version__
+
+
+class FormatField:
+    UUID = 'uuid'
+    NAME = 'name'
+    STEPS = 'steps'
+
+
+class StepField:
+    NAME = 'name'
+    OPTIONS = 'options'

dsw/templating/context.py

@@ -0,0 +1,55 @@
+"""Values the document worker adds to the document context before rendering."""
+from __future__ import annotations
+
+import dataclasses
+
+
+@dataclasses.dataclass
+class ContextDefaults:
+    """Service information and fallbacks of the instance branding (``ctx.config``).
+
+    The defaults are those of the document worker's configuration.
+    """
+    service_name: str = 'Data Stewardship Wizard'
+    service_name_short: str = 'DSW'
+    service_url: str = 'https://ds-wizard.org'
+    service_domain_name: str = 'ds-wizard.org'
+    default_primary_color: str = '#0033aa'
+    default_illustrations_color: str = '#0033aa'
+    default_logo_url: str = '{{clientUrl}}/assets/logo.svg'
+    default_app_title: str = 'DS Wizard'
+    default_app_title_short: str = 'DS Wizard'
+
+
+def enrich_context_config(context: dict, defaults: ContextDefaults):
+    """Fill ``context['config']`` as the document worker does.
+
+    The service fields are always set from `defaults`; the branding of the
+    instance is kept when present and falls back to `defaults` otherwise.
+    """
+    old = context.get('config', {})
+
+    client_url = old.get('clientUrl', '').rstrip('/')
+    app_title = (old.get('appTitle', None) or
+                 defaults.default_app_title)
+    app_title_short = (old.get('appTitleShort', None) or
+                       defaults.default_app_title_short)
+    primary_color = (old.get('primaryColor', None) or
+                     defaults.default_primary_color)
+    illustrations_color = (old.get('illustrationsColor', None) or
+                           defaults.default_illustrations_color)
+    logo_url_template = (old.get('logoUrl', None) or
+                         defaults.default_logo_url)
+    logo_url = logo_url_template.replace('{{clientUrl}}', client_url)
+
+    context['config'].update({
+        'serviceName': defaults.service_name,
+        'serviceNameShort': defaults.service_name_short,
+        'serviceUrl': defaults.service_url,
+        'serviceDomainName': defaults.service_domain_name,
+        'appTitle': app_title,
+        'appTitleShort': app_title_short,
+        'primaryColor': primary_color,
+        'illustrationsColor': illustrations_color,
+        'logoUrl': logo_url,
+    })

dsw/templating/conversions.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import logging
+import shlex
+import subprocess
+import typing
+
+from . import consts
+from .documents import FileFormat, FileFormats
+from .exceptions import require
+
+
+if typing.TYPE_CHECKING:
+    from .settings import PandocSettings
+
+
+LOG = logging.getLogger(__name__)
+
+
+def run_conversion(*, args: list, workdir: str, input_data: bytes, name: str,
+                   source_format: FileFormat, target_format: FileFormat, timeout=None) -> bytes:
+    command = ' '.join(args)
+    LOG.info('Calling "%s" to convert from %s to %s',
+             command, source_format, target_format)
+    try:
+        proc = subprocess.Popen(args, cwd=workdir, stdin=subprocess.PIPE,
+                                stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    except FileNotFoundError as e:
+        raise FormatConversionError(
+            name, source_format, target_format,
+            f'Executable "{args[0]}" not found, is it installed?',
+        ) from e
+    with proc:
+        stdout, stderr = proc.communicate(input=input_data, timeout=timeout)
+        exit_code = proc.returncode
+    if exit_code != consts.EXIT_SUCCESS:
+        raise FormatConversionError(
+            name, source_format, target_format,
+            f'Failed to execute (exit code: {exit_code}): '
+            f'{stderr.decode(consts.DEFAULT_ENCODING)}',
+        )
+    return stdout
+
+
+class FormatConversionError(Exception):
+
+    def __init__(self, convertor, source_format, target_format, message):
+        self.convertor = convertor
+        self.source_format = source_format
+        self.target_format = target_format
+        self.message = message
+
+    def __str__(self):
+        return f'{self.convertor} failed to convert {self.source_format}' \
+               f' to {self.target_format} - {self.message}'
+
+
+class Pandoc:
+
+    def __init__(self, settings: PandocSettings, filter_names: list[str],
+                 template_name: str | None):
+        self.settings = settings
+        self.filter_names = filter_names
+        self.template_name = template_name
+        self._check_filters()
+        self._check_template()
+
+    def _check_filters(self):
+        for name in self.filter_names:
+            if self.settings.filter_path(name) is None:
+                raise RuntimeError(f'Pandoc filter "{name}" not found')
+
+    def _check_template(self):
+        if self.template_name and self.settings.template_path(self.template_name) is None:
+            raise RuntimeError(f'Pandoc template "{self.template_name}" not found')
+
+    def _extra_args(self) -> list[str]:
+        # paths are passed as they are (not re-split), they may contain spaces
+        args: list[str] = []
+        if self.template_name:
+            args.extend(['--template', str(self.settings.template_path(self.template_name))])
+        for filter_name in self.filter_names:
+            option = '--lua-filter' if filter_name.endswith('.lua') else '--filter'
+            args.extend([option, str(self.settings.filter_path(filter_name))])
+        return args
+
+    def __call__(self, *, source_format: FileFormat, target_format: FileFormat,
+                 data: bytes, metadata: dict, workdir: str) -> bytes:
+        args = ['-f', source_format.name, '-t', target_format.name, '-o', '-']
+        template_args = self.extract_template_args(metadata)
+        extra_args = self._extra_args()
+        command = self.settings.command + template_args + extra_args + args
+        return run_conversion(
+            args=command,
+            workdir=workdir,
+            input_data=data,
+            name=type(self).__name__,
+            source_format=source_format,
+            target_format=target_format,
+            timeout=self.settings.timeout,
+        )
+
+    @staticmethod
+    def extract_template_args(metadata: dict):
+        return shlex.split(metadata.get('args', ''))
+
+
+class RdfLibConvert:
+
+    FORMATS = {
+        FileFormats.RDF_XML: 'xml',
+        FileFormats.N3: 'n3',
+        FileFormats.NTRIPLES: 'ntriples',
+        FileFormats.TURTLE: 'turtle',
+        FileFormats.TRIG: 'trig',
+        FileFormats.JSONLD: 'json-ld',
+    }
+
+    def __init__(self):
+        self.rdflib = require('rdflib', 'rdf')
+
+    def __call__(self, *, source_format: FileFormat, target_format: FileFormat,
+                 data: bytes, metadata: dict) -> bytes:
+        g = self.rdflib.Dataset()
+        g.parse(
+            data=data.decode(consts.DEFAULT_ENCODING),
+            format=self.FORMATS.get(source_format) or 'turtle',
+        )
+        return g.serialize(
+            format=self.FORMATS.get(target_format) or 'turtle',
+            encoding=consts.DEFAULT_ENCODING,
+        )

dsw/templating/documents.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import pathlib
+
+from . import consts
+
+
+class FileFormat:
+
+    def __init__(self, name: str, content_type: str, file_extension: str):
+        self.name = name
+        self.content_type = content_type
+        self.file_extension = file_extension
+
+    def __eq__(self, other):
+        return isinstance(other, FileFormat) and other.name == self.name
+
+    def __hash__(self):
+        return hash(self.name)
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return f'Format[{self.name}]'
+
+
+class FileFormats:
+    JSON = FileFormat('json', 'application/json', 'json')
+    HTML = FileFormat('html', 'text/html', 'html')
+    PDF = FileFormat('pdf', 'application/pdf', 'pdf')
+    DOCX = FileFormat(
+        'docx',
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        'docx',
+    )
+    Markdown = FileFormat('markdown', 'text/markdown', 'md')
+    ODT = FileFormat('odt', 'application/vnd.oasis.opendocument.text', 'odt')
+    RST = FileFormat('rst', 'text/x-rst', 'rst')
+    LaTeX = FileFormat('latex', 'application/x-tex', 'tex')
+    EPUB = FileFormat('epub', 'application/epub+zip', 'epub')
+    DocBook4 = FileFormat('docbook4', 'application/docbook+xml', 'dbk')
+    DocBook5 = FileFormat('docbook5', 'application/docbook+xml', 'dbk')
+    PPTX = FileFormat(
+        'pptx',
+        'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        'pptx',
+    )
+    RTF = FileFormat('rtf', 'application/rtf', 'rtf')
+    ADoc = FileFormat('asciidoc', 'text/asciidoc', 'adoc')
+    RDF_XML = FileFormat('rdf', 'application/rdf+xml', 'rdf')
+    N3 = FileFormat('n3', 'text/n3', 'n3')
+    NTRIPLES = FileFormat('nt', 'application/n-triples', 'nt')
+    TURTLE = FileFormat('ttl', 'text/turtle', 'ttl')
+    TRIG = FileFormat('trig', 'application/trig', 'trig')
+    JSONLD = FileFormat('jsonld', 'application/ld+json', 'jsonld')
+    ZIP = FileFormat('zip', 'application/zip', 'zip')
+    TAR = FileFormat('tar', 'application/x-tar', 'tar')
+    TAR_GZIP = FileFormat('gzip', 'application/gzip', 'tar.gz')
+    TAR_BZIP2 = FileFormat('bzip2', 'application/x-bzip2', 'tar.bz2')
+    TAR_LZMA = FileFormat('lzma', 'application/x-lzma', 'tar.xz')
+    XLSX = FileFormat(
+        'xlsx',
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        'xlsx',
+    )
+    XLSM = FileFormat(
+        'xlsm',
+        'application/vnd.ms-excel.sheet.macroEnabled.12',
+        'xlsm',
+    )
+
+    @staticmethod
+    def get(name: str):
+        known_formats = {
+            'html': FileFormats.HTML,
+            'pdf': FileFormats.PDF,
+            'docx': FileFormats.DOCX,
+            'markdown': FileFormats.Markdown,
+            'odt': FileFormats.ODT,
+            'rst': FileFormats.RST,
+            'latex': FileFormats.LaTeX,
+            'json': FileFormats.JSON,
+            'epub': FileFormats.EPUB,
+            'docbook4': FileFormats.DocBook4,
+            'docbook5': FileFormats.DocBook5,
+            'pptx': FileFormats.PPTX,
+            'rtf': FileFormats.RTF,
+            'asciidoc': FileFormats.ADoc,
+            'rdf': FileFormats.RDF_XML,
+            'rdf/xml': FileFormats.RDF_XML,
+            'turtle': FileFormats.TURTLE,
+            'ttl': FileFormats.TURTLE,
+            'n3': FileFormats.N3,
+            'ntriples': FileFormats.NTRIPLES,
+            'n-triples': FileFormats.NTRIPLES,
+            'trig': FileFormats.TRIG,
+            'json-ld': FileFormats.JSONLD,
+            'jsonld': FileFormats.JSONLD,
+            'zip': FileFormats.ZIP,
+            'tar': FileFormats.TAR,
+            'gzip': FileFormats.TAR_GZIP,
+            'bzip2': FileFormats.TAR_BZIP2,
+            'lzma': FileFormats.TAR_LZMA,
+            'xlsx': FileFormats.XLSX,
+            'xlsm': FileFormats.XLSM,
+        }
+        return known_formats.get(name)
+
+
+class DocumentFile:
+
+    def __init__(self, file_format: FileFormat, content: bytes,
+                 encoding: str | None = None):
+        self.file_format = file_format
+        self._content = content
+        self.byte_size = len(content)
+        self.encoding = encoding
+
+    @property
+    def content_type(self) -> str:
+        return self.file_format.content_type
+
+    @property
+    def safe_encoding(self) -> str:
+        return self.encoding or consts.DEFAULT_ENCODING
+
+    @property
+    def content(self) -> bytes:
+        return self._content
+
+    @content.setter
+    def content(self, content: bytes):
+        self._content = content
+        self.byte_size = len(content)
+
+    def filename(self, name: str) -> str:
+        return f'{name}.{self.file_format.file_extension}'
+
+    def store(self, name: str):
+        pathlib.Path(self.filename(name)).write_bytes(self.content)
+
+    @property
+    def object_content_type(self) -> str:
+        if self.encoding is not None:
+            return f'{self.content_type}; charset={self.encoding}'
+        return self.content_type

dsw/templating/docx_pagebreak.py

@@ -0,0 +1,91 @@
+"""Pandoc filter `pandoc-docx-pagebreakpy`: page breaks and TOC as OpenXML raw blocks (DOCX only).
+
+`\\newpage` becomes a page break and `\\toc` (`\\toc1` to `\\toc6` for the depth) a table of
+contents. Installed as the `pandoc-docx-pagebreakpy` command with the `docx` extra, for
+`--filter=pandoc-docx-pagebreakpy` in the `args` of the `pandoc` step. Deprecated in favour of the
+`docx-pagebreak.lua` and `docx-toc.lua` filters.
+
+Based on https://github.com/pandocker/pandoc-docx-pagebreak-py (formerly the
+`pandoc-docx-pagebreak` addon of the document worker):
+"""
+# MIT License
+#
+# Copyright (c) 2018 pandocker
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+from __future__ import annotations
+
+import sys
+
+from .exceptions import MissingExtraError, require
+
+
+TOC_DEPTHS = {r'\toc1': 1, r'\toc2': 2, r'\toc4': 4, r'\toc5': 5, r'\toc6': 6}
+DEFAULT_TOC_DEPTH = 3
+
+
+class DocxPagebreak:
+
+    def __init__(self):
+        self.pf = require('panflute', 'docx')
+
+    def _make_pagebreak(self):
+        return self.pf.RawBlock('<w:p><w:r><w:br w:type="page" /></w:r></w:p>', format='openxml')
+
+    def _make_toc(self, instr: str):
+        depth = TOC_DEPTHS.get(instr, DEFAULT_TOC_DEPTH)
+        toc_lines = [
+            r'<w:sdt>',
+            r'<w:sdtContent xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">',
+            r'<w:p><w:r>',
+            r'<w:fldChar w:fldCharType="begin" w:dirty="true" />',
+            rf'<w:instrText xml:space="preserve">TOC \o "1-{depth}" \h \z \u</w:instrText>',
+            r'<w:fldChar w:fldCharType="separate" />',
+            r'<w:fldChar w:fldCharType="end" />',
+            r'</w:r></w:p>',
+            r'</w:sdtContent>',
+            r'</w:sdt>',
+        ]
+        return self.pf.RawBlock('\n'.join(toc_lines), format='openxml')
+
+    def action(self, elem, doc):
+        pf = self.pf
+        if doc.format != 'docx':
+            return elem
+        if isinstance(elem, (pf.Para, pf.Plain)):
+            for child in elem.content:
+                if isinstance(child, pf.Str) and child.text == r'\newpage':
+                    elem = self._make_pagebreak()
+                elif isinstance(child, pf.Str) and child.text.startswith(r'\toc'):
+                    elem = self._make_toc(child.text)
+        if isinstance(elem, pf.RawBlock):
+            if elem.text == r'\newpage':
+                elem = self._make_pagebreak()
+            elif elem.text.startswith(r'\toc'):
+                elem = self._make_toc(elem.text)
+        return elem
+
+
+def main(doc=None):
+    try:
+        dp = DocxPagebreak()
+    except MissingExtraError as e:
+        # run by pandoc: a message on stderr rather than a traceback
+        sys.exit(f'pandoc-docx-pagebreakpy: {e}')
+    return dp.pf.run_filter(dp.action, doc=doc)

dsw/templating/exceptions.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import importlib
+import typing
+
+
+if typing.TYPE_CHECKING:
+    import types
+
+
+class TemplateError(Exception):
+
+    def __init__(self, template_uuid: str, message: str):
+        self.template_uuid = template_uuid
+        self.message = message
+
+    def __str__(self):
+        return f'Error in template "{self.template_uuid}"\n' \
+               f'- {self.message}'
+
+
+class TemplateTriggeredError(Exception):
+    """Error invoked from a template to report a problem to a user (not system)."""
+
+    def __init__(self, title, message):
+        self.title = title
+        self.message = message
+        self.msg = f'{title}\n\n{message}'
+        super().__init__(self.msg)
+
+    def __str__(self):
+        return self.msg
+
+
+class MissingExtraError(ImportError):
+    """An optional dependency of a step is not installed."""
+
+    def __init__(self, module: str, extra: str):
+        self.module = module
+        self.extra = extra
+        super().__init__(
+            f'Module "{module}" is not installed, '
+            f'install dsw-templating[{extra}] to use it',
+            name=module,
+        )
+
+
+def require(module: str, extra: str) -> types.ModuleType:
+    """Import an optional dependency, failing with the extra to install."""
+    try:
+        return importlib.import_module(module)
+    except ImportError as e:
+        raise MissingExtraError(module, extra) from e
+
+
+class MissingModule:
+    """Stands in for an optional module; fails as soon as it is used."""
+
+    def __init__(self, module: str, extra: str):
+        self._module = module
+        self._extra = extra
+
+    def __getattr__(self, name: str):
+        raise MissingExtraError(self._module, self._extra)
+
+
+def optional(module: str, extra: str) -> types.ModuleType | MissingModule:
+    try:
+        return importlib.import_module(module)
+    except ImportError:
+        return MissingModule(module, extra)