dp_wizard_templates 0.2.0__tar.gz → 0.4.0__tar.gz

{dp_wizard_templates-0.2.0 → dp_wizard_templates-0.4.0}/.coveragerc

@@ -13,5 +13,5 @@ omit =
 show_missing = True
 skip_covered = True
 fail_under = 100
-exclude_also =
-  template
+# Negative look-ahead: We *do* want to cover test functions.
+exclude_also = def (?!test)\w*template

dp_wizard_templates-0.4.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# CHANGELOG
+
+## 0.4.0
+
+- Safer template filling, and option to ignore slots [#20](https://github.com/opendp/dp-wizard-templates/pull/20)
+- Check for `root` kwarg, and fix test coverage [#19](https://github.com/opendp/dp-wizard-templates/pull/19)
+
+## 0.3.0
+
+- Show all errors, and support comment blocks [#12](https://github.com/opendp/dp-wizard-templates/pull/12)
+
+## 0.2.0
+
+- Link to ghpages [#7](https://github.com/opendp/dp-wizard-templates/pull/7)
+- Add black, and a generated index.html [#6](https://github.com/opendp/dp-wizard-templates/pull/6)
+
+## 0.1.0
+
+Initial release

{dp_wizard_templates-0.2.0 → dp_wizard_templates-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp_wizard_templates
-Version: 0.2.0
+Version: 0.4.0
 Summary: Code templating tools
 Author-email: The OpenDP Project <info@opendp.org>
 Description-Content-Type: text/markdown

dp_wizard_templates-0.4.0/dp_wizard_templates/VERSION

@@ -0,0 +1 @@
+0.4.0

dp_wizard_templates-0.4.0/dp_wizard_templates/code_template.py

@@ -0,0 +1,209 @@
+from typing import Optional, Callable, Iterable
+from pathlib import Path
+import inspect
+import re
+import black
+import json
+
+
+class TemplateException(Exception):
+    pass
+
+
+def _get_body(func):
+
+    source_lines = inspect.getsource(func).splitlines()
+    first_line = source_lines[0]
+    if not re.match(r"def \w+\((\w+(, \w+)*)?\):", first_line.strip()):
+        # Parsing to AST and unparsing is a more robust option,
+        # but more complicated.
+        raise TemplateException(
+            f"def and parameters should fit on one line: {first_line}"
+        )
+
+    # The "def" should not be in the output,
+    # and cleandoc handles the first line differently.
+    source_lines[0] = ""
+    body = inspect.cleandoc("\n".join(source_lines))
+    comments_to_strip = [
+        r"\s+#\s+type:\s+ignore\s*",
+        r"\s+#\s+noqa:.+\s*",
+        r"\s+#\s+pragma:\s+no cover\s*",
+    ]
+    for comment_re in comments_to_strip:
+        body = re.sub(
+            comment_re,
+            "\n",
+            body,
+        )
+
+    return body
+
+
+def _check_repr(value):
+    """
+    Confirms that the string returned by repr()
+    can be evaluated to recreate the original value.
+    Takes a conservative approach by checking
+    if the value can be serialized to JSON.
+    """
+    try:
+        json.dumps(value)
+    except TypeError as e:
+        raise TemplateException(e)
+    return repr(value)
+
+
+class Template:
+    def __init__(
+        self,
+        template: str | Callable,
+        root: Optional[Path] = None,
+        ignore: Iterable[str] = ("TODO",),
+    ):
+        if root is None:
+            if callable(template):
+                self._source = "function template"
+                self._template = _get_body(template)
+            else:
+                self._source = "string template"
+                self._template = template
+        else:
+            if callable(template):
+                raise TemplateException(
+                    "If template is function, root kwarg not allowed"
+                )
+            else:
+                template_name = f"_{template}.py"
+                template_path = root / template_name
+                self._source = f"'{template_name}'"
+                self._template = template_path.read_text()
+        # We want a list of the initial slots, because substitutions
+        # can produce sequences of upper case letters that could be mistaken for slots.
+        self._initial_slots = self._find_slots()
+        self._ignore = ignore
+
+    def _find_slots(self) -> set[str]:
+        # Slots:
+        # - are all caps or underscores
+        # - have word boundary on either side
+        # - are at least three characters
+        slot_re = r"\b[A-Z][A-Z_]{2,}\b"
+        return set(re.findall(slot_re, self._template))
+
+    def _make_message(self, errors: list[str]) -> str:
+        return (
+            f"In {self._source}, " + ", ".join(sorted(errors)) + f":\n{self._template}"
+        )
+
+    def _loop_kwargs(
+        self,
+        function: Callable[[str, str, list[str]], None],
+        **kwargs,
+    ) -> None:
+        errors = []
+        for k, v in kwargs.items():
+            function(k, v, errors)
+        if errors:
+            raise TemplateException(self._make_message(errors))
+
+    def _fill_inline_slots(
+        self,
+        stringifier: Callable[[str], str],
+        **kwargs,
+    ) -> None:
+        def function(k, v, errors):
+            k_re = re.escape(k)
+            self._template, count = re.subn(
+                rf"\b{k_re}\b", stringifier(v), self._template
+            )
+            if count == 0:
+                errors.append(f"no '{k}' slot to fill with '{v}'")
+
+        self._loop_kwargs(function, **kwargs)
+
+    def _fill_block_slots(
+        self,
+        prefix_re: str,
+        splitter: Callable[[str], list[str]],
+        **kwargs,
+    ) -> None:
+        def function(k, v, errors):
+            if not isinstance(v, str):
+                errors.append(f"for '{k}' slot, expected string, not '{v}'")
+                return
+
+            def match_indent(match):
+                # This does what we want, but binding is confusing.
+                return "\n".join(
+                    match.group(1) + line for line in splitter(v)  # noqa: B023
+                )
+
+            k_re = re.escape(k)
+            self._template, count = re.subn(
+                rf"^([ \t]*{prefix_re}){k_re}$",
+                match_indent,
+                self._template,
+                flags=re.MULTILINE,
+            )
+            if count == 0:
+                base_message = f"no '{k}' slot to fill with '{v}'"
+                if k in self._template:
+                    note = (
+                        "comment slots must be prefixed with '#'"
+                        if prefix_re
+                        else "block slots must be alone on line"
+                    )
+                    errors.append(f"{base_message} ({note})")
+                else:
+                    errors.append(base_message)
+
+        self._loop_kwargs(function, **kwargs)
+
+    def fill_expressions(self, **kwargs) -> "Template":
+        """
+        Fill in variable names, or dicts or lists represented as strings.
+        """
+        self._fill_inline_slots(stringifier=str, **kwargs)
+        return self
+
+    def fill_values(self, **kwargs) -> "Template":
+        """
+        Fill in string or numeric values. `repr` is called before filling.
+        """
+        self._fill_inline_slots(stringifier=_check_repr, **kwargs)
+        return self
+
+    def fill_code_blocks(self, **kwargs) -> "Template":
+        """
+        Fill in code blocks. Slot must be alone on line.
+        """
+
+        def splitter(s):
+            return s.split("\n")
+
+        self._fill_block_slots(prefix_re=r"", splitter=splitter, **kwargs)
+        return self
+
+    def fill_comment_blocks(self, **kwargs) -> "Template":
+        """
+        Fill in comment blocks. Slot must be commented.
+        """
+
+        def splitter(s):
+            stripped = [line.strip() for line in s.split("\n")]
+            return [line for line in stripped if line]
+
+        self._fill_block_slots(prefix_re=r"#\s+", splitter=splitter, **kwargs)
+        return self
+
+    def finish(self, reformat: bool = False) -> str:
+        unfilled_slots = (self._initial_slots & self._find_slots()) - set(self._ignore)
+        if unfilled_slots:
+            errors = [f"'{slot}' slot not filled" for slot in unfilled_slots]
+            raise TemplateException(self._make_message(errors))
+
+        if reformat:
+            self._template = black.format_str(self._template, mode=black.Mode())
+
+        return self._template

{dp_wizard_templates-0.2.0 → dp_wizard_templates-0.4.0}/dp_wizard_templates/converters.py

@@ -30,7 +30,7 @@ class ConversionException(Exception):
 
 def convert_py_to_nb(
     python_str: str, title: str, execute: bool = False, reformat: bool = True
-):
+) -> str:
     """
     Given Python code as a string, returns a notebook as a string.
     Calls jupytext as a subprocess:
@@ -71,13 +71,13 @@ def convert_py_to_nb(
     return _clean_nb(json.dumps(nb_dict))
 
 
-def _stable_hash(lines: list[str]):
+def _stable_hash(lines: list[str]) -> str:
     import hashlib
 
     return hashlib.sha1("\n".join(lines).encode()).hexdigest()[:8]
 
 
-def _clean_nb(nb_json: str):
+def _clean_nb(nb_json: str) -> str:
     """
     Given a notebook as a string of JSON, remove the coda and pip output.
     (The code may produce reports that we do need,
@@ -104,7 +104,7 @@ def _clean_nb(nb_json: str):
     return json.dumps(nb, indent=1)
 
 
-def convert_nb_to_html(python_nb: str, numbered=True):
+def convert_nb_to_html(python_nb: str, numbered=True) -> str:
     notebook = nbformat.reads(python_nb, as_version=4)
     exporter = nbconvert.HTMLExporter(
         template_name="lab",

{dp_wizard_templates-0.2.0 → dp_wizard_templates-0.4.0}/examples/_block_demo.py

@@ -2,4 +2,5 @@ def FUNCTION_NAME(PARAMS):
     """
     This demonstrates how larger blocks of code can be built compositionally.
     """
+    # COMMENT
     INNER_BLOCK

{dp_wizard_templates-0.2.0 → dp_wizard_templates-0.4.0}/examples/hello-world.html

@@ -7523,7 +7523,7 @@ even though the lines are not contiguous</p>
 </div>
 </div>
 </div>
-</div><div class="jp-Cell jp-CodeCell jp-Notebook-cell" id="cell-id=bbe7eb3d">
+</div><div class="jp-Cell jp-CodeCell jp-Notebook-cell" id="cell-id=d75dbbc1">
 <div class="jp-Cell-inputWrapper" tabindex="0">
 <div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
 </div>
@@ -7535,6 +7535,9 @@ even though the lines are not contiguous</p>
 <span class="w">    </span><span class="sd">"""</span>
 <span class="sd">    This demonstrates how larger blocks of code can be built compositionally.</span>
 <span class="sd">    """</span>
+    <span class="c1"># Water freezes at:</span>
+    <span class="c1"># 32 Fahrenheit</span>
+    <span class="c1"># 0 Celsius</span>
     <span class="k">if</span> <span class="n">temp_c</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">:</span>
         <span class="nb">print</span><span class="p">(</span><span class="s2">"It is freezing!"</span><span class="p">)</span>
 

{dp_wizard_templates-0.2.0 → dp_wizard_templates-0.4.0}/examples/hello-world.ipynb

@@ -17,7 +17,7 @@
   {
    "cell_type": "code",
    "execution_count": 1,
-   "id": "bbe7eb3d",
+   "id": "d75dbbc1",
    "metadata": {},
    "outputs": [
     {
@@ -33,6 +33,9 @@
     "    \"\"\"\n",
     "    This demonstrates how larger blocks of code can be built compositionally.\n",
     "    \"\"\"\n",
+    "    # Water freezes at:\n",
+    "    # 32 Fahrenheit\n",
+    "    # 0 Celsius\n",
     "    if temp_c < 0:\n",
     "        print(\"It is freezing!\")\n",
     "\n",

{dp_wizard_templates-0.2.0 → dp_wizard_templates-0.4.0}/index.html

@@ -7574,13 +7574,18 @@ itself can be parsed as Python code, so syntax highlighting and linting still wo
 </div>
 </div>
 </div>
-<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell" id="cell-id=debe102a">
+<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell" id="cell-id=39e34438">
 <div class="jp-Cell-inputWrapper" tabindex="0">
 <div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
 </div>
 <div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
 </div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput" data-mime-type="text/markdown">
-<p>Note the different methods used:</p>
+<p>Note that <code>conditional_print_template</code> is not called: Instead,
+the <code>inspect</code> package is used to load its source, and the slots
+in all-caps are filled. Including a parameter list is optional,
+but providing args which match the names of your slots can prevent
+warnings from your IDE.</p>
+<p>Different methods are available on the <code>Template</code> object:</p>
 <ul>
 <li><code>fill_expressions()</code> fills the slot with verbatim text.
 It can be used for an expression like this, or for variable names.</li>
@@ -7590,14 +7595,15 @@ data structure, as long as it has a usable repr.</li>
 <li><code>finish()</code> converts the template to a string, and will error
 if not all slots have been filled.</li>
 </ul>
-<p>Templates can also be in standalone files. If a <code>root</code> parameter is provided,
+<p>(The next section will introduce <code>fill_code_block()</code> and <code>fill_comment_block()</code>.)</p>
+<p>Templates can also be standalone files. If a <code>root</code> parameter is provided,
 the system will prepend <code>_</code> and append <code>.py</code> and look for a corresponding file.
 (The convention of prepending <code>_</code> reminds us that although these files
 can be parsed, they should not be imported or executed as-is.)</p>
 </div>
 </div>
 </div>
-</div><div class="jp-Cell jp-CodeCell jp-Notebook-cell jp-mod-noOutputs" id="cell-id=4fd80ead">
+</div><div class="jp-Cell jp-CodeCell jp-Notebook-cell jp-mod-noOutputs" id="cell-id=c3374f03">
 <div class="jp-Cell-inputWrapper" tabindex="0">
 <div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
 </div>
@@ -7612,7 +7618,14 @@ can be parsed, they should not be imported or executed as-is.)</p>
 <span class="n">block_demo</span> <span class="o">=</span> <span class="p">(</span>
     <span class="n">Template</span><span class="p">(</span><span class="s2">"block_demo"</span><span class="p">,</span> <span class="n">root</span><span class="o">=</span><span class="n">root</span> <span class="o">/</span> <span class="s2">"examples"</span><span class="p">)</span>
     <span class="o">.</span><span class="n">fill_expressions</span><span class="p">(</span><span class="n">FUNCTION_NAME</span><span class="o">=</span><span class="s2">"freeze_warning"</span><span class="p">,</span> <span class="n">PARAMS</span><span class="o">=</span><span class="s2">"temp_c"</span><span class="p">)</span>
-    <span class="o">.</span><span class="n">fill_blocks</span><span class="p">(</span><span class="n">INNER_BLOCK</span><span class="o">=</span><span class="n">conditional_print</span><span class="p">)</span>
+    <span class="o">.</span><span class="n">fill_code_blocks</span><span class="p">(</span><span class="n">INNER_BLOCK</span><span class="o">=</span><span class="n">conditional_print</span><span class="p">)</span>
+    <span class="o">.</span><span class="n">fill_comment_blocks</span><span class="p">(</span>
+        <span class="n">COMMENT</span><span class="o">=</span><span class="s2">"""</span>
+<span class="s2">        Water freezes at:</span>
+<span class="s2">        32 Fahrenheit</span>
+<span class="s2">        0 Celsius</span>
+<span class="s2">        """</span>
+    <span class="p">)</span>
     <span class="o">.</span><span class="n">finish</span><span class="p">()</span>
 <span class="p">)</span>
 
@@ -7622,6 +7635,9 @@ can be parsed, they should not be imported or executed as-is.)</p>
 <span class="s1">    """</span>
 <span class="s1">    This demonstrates how larger blocks of code can be built compositionally.</span>
 <span class="s1">    """</span>
+<span class="s1">    # Water freezes at:</span>
+<span class="s1">    # 32 Fahrenheit</span>
+<span class="s1">    # 0 Celsius</span>
 <span class="s1">    if temp_c &lt; 0:</span>
 <span class="s1">        print('It is freezing!')</span>
 <span class="s1">'''</span>
@@ -7683,7 +7699,7 @@ to produce other artifacts without adding clutter.</p>
 </div>
 </div>
 </div>
-</div><div class="jp-Cell jp-CodeCell jp-Notebook-cell jp-mod-noOutputs" id="cell-id=b5dc8879">
+</div><div class="jp-Cell jp-CodeCell jp-Notebook-cell jp-mod-noOutputs" id="cell-id=ccf10f98">
 <div class="jp-Cell-inputWrapper" tabindex="0">
 <div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
 </div>
@@ -7720,7 +7736,7 @@ to produce other artifacts without adding clutter.</p>
 <span class="n">title</span> <span class="o">=</span> <span class="s2">"Hello World!"</span>
 <span class="n">notebook_py</span> <span class="o">=</span> <span class="p">(</span>
     <span class="n">Template</span><span class="p">(</span><span class="n">notebook_template</span><span class="p">)</span>
-    <span class="o">.</span><span class="n">fill_blocks</span><span class="p">(</span><span class="n">BLOCK</span><span class="o">=</span><span class="n">block_demo</span><span class="p">)</span>
+    <span class="o">.</span><span class="n">fill_code_blocks</span><span class="p">(</span><span class="n">BLOCK</span><span class="o">=</span><span class="n">block_demo</span><span class="p">)</span>
     <span class="o">.</span><span class="n">fill_expressions</span><span class="p">(</span><span class="n">FUNCTION_NAME</span><span class="o">=</span><span class="s2">"freeze_warning"</span><span class="p">,</span> <span class="n">TITLE</span><span class="o">=</span><span class="n">title</span><span class="p">)</span>
     <span class="o">.</span><span class="n">finish</span><span class="p">()</span>
 <span class="p">)</span>
@@ -7736,7 +7752,7 @@ to produce other artifacts without adding clutter.</p>
 </div>
 </div>
 </div>
-<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell" id="cell-id=746eea6a">
+<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell" id="cell-id=50f5c776">
 <div class="jp-Cell-inputWrapper" tabindex="0">
 <div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
 </div>
@@ -7756,7 +7772,7 @@ and configure pytest (<code>--ignore-glob '**/templates/</code>) and pyright
 (<code>ignore = ["**/templates/"]</code>) to ignore them.</li>
 <li>For template functions, you might have a consistent naming
 convention, and configure coverage (<code>exclude_also = def template_</code>)
-to exclude them as well.</li>
+to exclude them as well, or else use <code># pragma: no cover</code>.</li>
 </ul>
 </div>
 </div>

dp_wizard_templates-0.4.0/tests/test_code_template.py

@@ -0,0 +1,260 @@
+from pathlib import Path
+
+import pytest
+from dp_wizard_templates.code_template import Template, TemplateException
+
+
+def test_non_repr_value():
+    def template(VALUE):
+        print(VALUE)
+
+    with pytest.raises(
+        TemplateException,
+        match=r"Object of type set is not JSON serializable",
+    ):
+        Template(template).fill_values(VALUE={1, 2, 3})
+
+
+def test_ignore_todo_by_default():
+    def template():
+        print("TODO")
+
+    assert Template(template).finish() == 'print("TODO")'
+
+
+def test_ignore_kwarg():
+    def template():
+        print("IGNORE_ME")
+
+    with pytest.raises(
+        TemplateException,
+        match=r"'IGNORE_ME' slot not filled",
+    ):
+        Template(template).finish()
+
+    assert Template(template, ignore={"IGNORE_ME"}).finish() == 'print("IGNORE_ME")'
+
+
+def test_strip_pragma():
+    def template():
+        pass  # pragma: no cover
+
+    assert Template(template).finish() == "pass\n"
+
+
+def test_strip_noqa():
+    def template():
+        pass  # noqa: B950 (explanation here!)
+
+    assert Template(template).finish() == "pass\n"
+
+
+def test_strip_type_ignore():
+    def template():
+        pass  # type: ignore
+
+    assert Template(template).finish() == "pass\n"
+
+
+def test_def_too_long():
+    def template(
+        BEGIN,
+        END,
+    ):
+        print(BEGIN, END)
+
+    with pytest.raises(
+        TemplateException, match=r"def and parameters should fit on one line"
+    ):
+        Template(template)
+
+
+def test_def_template():
+    def template(BEGIN, END):
+        print(BEGIN, END)
+
+    assert (
+        Template(template).fill_values(BEGIN="abc", END="xyz").finish()
+        == "print('abc', 'xyz')"
+    )
+
+
+def test_fill_expressions():
+    template = Template("No one VERB the ADJ NOUN!")
+    filled = template.fill_expressions(
+        VERB="expects",
+        ADJ="Spanish",
+        NOUN="Inquisition",
+    ).finish()
+    assert filled == "No one expects the Spanish Inquisition!"
+
+
+def test_fill_expressions_missing_slots_in_template():
+    template = Template("No one ... the ... ...!")
+    with pytest.raises(
+        TemplateException,
+        match=r"no 'ADJ' slot to fill with 'Spanish', "
+        r"no 'NOUN' slot to fill with 'Inquisition', "
+        r"no 'VERB' slot to fill with 'expects':",
+    ):
+        template.fill_expressions(
+            VERB="expects",
+            ADJ="Spanish",
+            NOUN="Inquisition",
+        ).finish()
+
+
+def test_fill_expressions_extra_slots_in_template():
+    template = Template("No one VERB ARTICLE ADJ NOUN!")
+    with pytest.raises(
+        TemplateException, match=r"'ARTICLE' slot not filled, 'VERB' slot not filled"
+    ):
+        template.fill_expressions(
+            ADJ="Spanish",
+            NOUN="Inquisition",
+        ).finish()
+
+
+def test_fill_values():
+    template = Template("assert [STRING] * NUM == LIST")
+    filled = template.fill_values(
+        STRING="🙂",
+        NUM=3,
+        LIST=["🙂", "🙂", "🙂"],
+    ).finish()
+    assert filled == "assert ['🙂'] * 3 == ['🙂', '🙂', '🙂']"
+
+
+def test_fill_values_missing_slot_in_template():
+    template = Template("assert [STRING] * ... == LIST")
+    with pytest.raises(TemplateException, match=r"no 'NUM' slot to fill with '3'"):
+        template.fill_values(
+            STRING="🙂",
+            NUM=3,
+            LIST=["🙂", "🙂", "🙂"],
+        ).finish()
+
+
+def test_fill_values_extra_slot_in_template():
+    template = Template("CMD [STRING] * NUM == LIST")
+    with pytest.raises(TemplateException, match=r"'CMD' slot not filled"):
+        template.fill_values(
+            STRING="🙂",
+            NUM=3,
+            LIST=["🙂", "🙂", "🙂"],
+        ).finish()
+
+
+def test_fill_blocks():
+    # "OK" is less than three characters, so it is not a slot.
+    template = Template(
+        """# MixedCase is OK
+
+FIRST
+
+with fake:
+    my_tuple = (
+        # SECOND
+        VALUE,
+    )
+    if True:
+        THIRD
+""",
+    )
+    filled = (
+        template.fill_code_blocks(
+            FIRST="\n".join(f"import {i}" for i in "abc"),
+            THIRD="\n".join(f"{i}()" for i in "xyz"),
+        )
+        .fill_comment_blocks(
+            SECOND="This is a\nmulti-line comment",
+        )
+        .fill_values(VALUE=42)
+        .finish()
+    )
+    assert (
+        filled
+        == """# MixedCase is OK
+
+import a
+import b
+import c
+
+with fake:
+    my_tuple = (
+        # This is a
+        # multi-line comment
+        42,
+    )
+    if True:
+        x()
+        y()
+        z()
+"""
+    )
+
+
+def test_fill_comment_block():
+    template = Template("# SLOT")
+    filled = template.fill_comment_blocks(SLOT="placeholder").finish()
+    assert filled == "# placeholder"
+
+
+def test_finish_reformat():
+    template = Template("print( 'messy','code!' )#comment")
+    filled = template.finish(reformat=True)
+    assert filled == 'print("messy", "code!")  # comment\n'
+
+
+def test_fill_comment_block_without_comment():
+    template = Template("SLOT")
+    with pytest.raises(
+        TemplateException,
+        match=r"In string template, no 'SLOT' slot to fill with 'placeholder' "
+        r"\(comment slots must be prefixed with '#'\)",
+    ):
+        template.fill_comment_blocks(SLOT="placeholder").finish()
+
+
+def test_fill_blocks_missing_slot_in_template_alone():
+    template = Template("No block slot")
+    with pytest.raises(
+        TemplateException, match=r"no 'SLOT' slot to fill with 'placeholder':"
+    ):
+        template.fill_code_blocks(SLOT="placeholder").finish()
+
+
+def test_fill_blocks_missing_slot_in_template_not_alone():
+    template = Template("No block SLOT")
+    with pytest.raises(
+        TemplateException,
+        match=r"no 'SLOT' slot to fill with 'placeholder' "
+        r"\(block slots must be alone on line\)",
+    ):
+        template.fill_code_blocks(SLOT="placeholder").finish()
+
+
+def test_fill_blocks_extra_slot_in_template():
+    template = Template("EXTRA\nSLOT")
+    with pytest.raises(TemplateException, match=r"'EXTRA' slot not filled"):
+        template.fill_code_blocks(SLOT="placeholder").finish()
+
+
+def test_fill_blocks_not_string():
+    template = Template("SOMETHING")
+    with pytest.raises(
+        TemplateException,
+        match=r"for 'SOMETHING' slot, expected string, not '123'",
+    ):
+        template.fill_code_blocks(SOMETHING=123).finish()
+
+
+def test_no_root_kwarg_with_function_template():
+    def template():
+        pass
+
+    with pytest.raises(
+        TemplateException,
+        match=r"If template is function, root kwarg not allowed",
+    ):
+        Template(template, root=Path("not-allowed"))

{dp_wizard_templates-0.2.0 → dp_wizard_templates-0.4.0}/tests/test_index_html.py

@@ -54,7 +54,13 @@ assert conditional_print == "if temp_c < 0:\n    print('It is freezing!')"
 
 # -
 
-# Note the different methods used:
+# Note that `conditional_print_template` is not called: Instead,
+# the `inspect` package is used to load its source, and the slots
+# in all-caps are filled. Including a parameter list is optional,
+# but providing args which match the names of your slots can prevent
+# warnings from your IDE.
+#
+# Different methods are available on the `Template` object:
 # - `fill_expressions()` fills the slot with verbatim text.
 #   It can be used for an expression like this, or for variable names.
 # - `fill_values()` fills the slot with the repr of the provided value.
@@ -63,7 +69,9 @@ assert conditional_print == "if temp_c < 0:\n    print('It is freezing!')"
 # - `finish()` converts the template to a string, and will error
 #   if not all slots have been filled.
 #
-# Templates can also be in standalone files. If a `root` parameter is provided,
+# (The next section will introduce `fill_code_block()` and `fill_comment_block()`.)
+#
+# Templates can also be standalone files. If a `root` parameter is provided,
 # the system will prepend `_` and append `.py` and look for a corresponding file.
 # (The convention of prepending `_` reminds us that although these files
 # can be parsed, they should not be imported or executed as-is.)
@@ -77,7 +85,14 @@ root = Path(__file__).parent.parent
 block_demo = (
     Template("block_demo", root=root / "examples")
     .fill_expressions(FUNCTION_NAME="freeze_warning", PARAMS="temp_c")
-    .fill_blocks(INNER_BLOCK=conditional_print)
+    .fill_code_blocks(INNER_BLOCK=conditional_print)
+    .fill_comment_blocks(
+        COMMENT="""
+        Water freezes at:
+        32 Fahrenheit
+        0 Celsius
+        """
+    )
     .finish()
 )
 
@@ -87,6 +102,9 @@ assert (
     """
     This demonstrates how larger blocks of code can be built compositionally.
     """
+    # Water freezes at:
+    # 32 Fahrenheit
+    # 0 Celsius
     if temp_c < 0:
         print('It is freezing!')
 '''
@@ -152,7 +170,7 @@ def notebook_template(TITLE, BLOCK, FUNCTION_NAME):
 title = "Hello World!"
 notebook_py = (
     Template(notebook_template)
-    .fill_blocks(BLOCK=block_demo)
+    .fill_code_blocks(BLOCK=block_demo)
     .fill_expressions(FUNCTION_NAME="freeze_warning", TITLE=title)
     .finish()
 )
@@ -182,7 +200,7 @@ notebook_html = convert_nb_to_html(notebook_ipynb)
 #   (`ignore = ["**/templates/"]`) to ignore them.
 # - For template functions, you might have a consistent naming
 #   convention, and configure coverage (`exclude_also = def template_`)
-#   to exclude them as well.
+#   to exclude them as well, or else use `# pragma: no cover`.
 
 # # Coda
 

dp_wizard_templates-0.2.0/CHANGELOG.md

@@ -1,10 +0,0 @@
-# CHANGELOG
-
-## 0.2.0
-
-- Link to ghpages [#7](https://github.com/opendp/dp-wizard-templates/pull/7)
-- Add black, and a generated index.html [#6](https://github.com/opendp/dp-wizard-templates/pull/6)
-
-## 0.1.0
-
-Initial release

dp_wizard_templates-0.2.0/dp_wizard_templates/VERSION

@@ -1 +0,0 @@
-0.2.0

dp_wizard_templates-0.2.0/dp_wizard_templates/code_template.py

@@ -1,131 +0,0 @@
-import inspect
-import re
-import black
-
-
-def _get_body(func):
-
-    source_lines = inspect.getsource(func).splitlines()
-    first_line = source_lines[0]
-    if not re.match(r"def \w+\((\w+(, \w+)*)?\):", first_line.strip()):
-        # Parsing to AST and unparsing is a more robust option,
-        # but more complicated.
-        raise Exception(f"def and parameters should fit on one line: {first_line}")
-
-    # The "def" should not be in the output,
-    # and cleandoc handles the first line differently.
-    source_lines[0] = ""
-    body = inspect.cleandoc("\n".join(source_lines))
-    body = re.sub(
-        r"\s*#\s+type:\s+ignore\s*",
-        "\n",
-        body,
-    )
-    body = re.sub(
-        r"\s*#\s+noqa:.+",
-        "",
-        body,
-    )
-    return body
-
-
-class Template:
-    def __init__(self, template, root=None):
-        if root is not None:
-            template_name = f"_{template}.py"
-            template_path = root / template_name
-            self._source = f"'{template_name}'"
-            self._template = template_path.read_text()
-        else:
-            if callable(template):
-                self._source = "function template"
-                self._template = _get_body(template)
-            else:
-                self._source = "string template"
-                self._template = template
-        # We want a list of the initial slots, because substitutions
-        # can produce sequences of upper case letters that could be mistaken for slots.
-        self._initial_slots = self._find_slots()
-
-    def _find_slots(self):
-        # Slots:
-        # - are all caps or underscores
-        # - have word boundary on either side
-        # - are at least three characters
-        slot_re = r"\b[A-Z][A-Z_]{2,}\b"
-        return set(re.findall(slot_re, self._template))
-
-    def fill_expressions(self, **kwargs):
-        """
-        Fill in variable names, or dicts or lists represented as strings.
-        """
-        for k, v in kwargs.items():
-            k_re = re.escape(k)
-            self._template, count = re.subn(rf"\b{k_re}\b", str(v), self._template)
-            if count == 0:
-                raise Exception(
-                    f"No '{k}' slot to fill with '{v}' in "
-                    f"{self._source}:\n\n{self._template}"
-                )
-        return self
-
-    def fill_values(self, **kwargs):
-        """
-        Fill in string or numeric values. `repr` is called before filling.
-        """
-        for k, v in kwargs.items():
-            k_re = re.escape(k)
-            self._template, count = re.subn(rf"\b{k_re}\b", repr(v), self._template)
-            if count == 0:
-                raise Exception(
-                    f"No '{k}' slot to fill with '{v}' in "
-                    f"{self._source}:\n\n{self._template}"
-                )
-        return self
-
-    def fill_blocks(self, **kwargs):
-        """
-        Fill in code blocks. Slot must be alone on line.
-        """
-        for k, v in kwargs.items():
-            if not isinstance(v, str):
-                raise Exception(f"For {k} in {self._source}, expected string, not {v}")
-
-            def match_indent(match):
-                # This does what we want, but binding is confusing.
-                return "\n".join(
-                    match.group(1) + line for line in v.split("\n")  # noqa: B023
-                )
-
-            k_re = re.escape(k)
-            self._template, count = re.subn(
-                rf"^([ \t]*){k_re}$",
-                match_indent,
-                self._template,
-                flags=re.MULTILINE,
-            )
-            if count == 0:
-                base_message = (
-                    f"No '{k}' slot to fill with '{v}' in "
-                    f"{self._source}:\n\n{self._template}"
-                )
-                if k in self._template:
-                    raise Exception(
-                        f"Block slots must be alone on line; {base_message}"
-                    )
-                raise Exception(base_message)
-        return self
-
-    def finish(self, reformat=False) -> str:
-        unfilled_slots = self._initial_slots & self._find_slots()
-        if unfilled_slots:
-            slots_str = ", ".join(sorted(f"'{slot}'" for slot in unfilled_slots))
-            raise Exception(
-                f"{slots_str} slot not filled "
-                f"in {self._source}:\n\n{self._template}"
-            )
-
-        if reformat:
-            self._template = black.format_str(self._template, mode=black.Mode())
-
-        return self._template

dp_wizard_templates-0.2.0/tests/test_code_template.py

@@ -1,150 +0,0 @@
-import pytest
-from dp_wizard_templates.code_template import Template
-
-
-def test_def_too_long():
-    def template(
-        BEGIN,
-        END,
-    ):
-        print(BEGIN, END)
-
-    with pytest.raises(Exception, match=r"def and parameters should fit on one line"):
-        Template(template)
-
-
-def test_def_template():
-    def template(BEGIN, END):
-        print(BEGIN, END)
-
-    assert (
-        Template(template).fill_values(BEGIN="abc", END="xyz").finish()
-        == "print('abc', 'xyz')"
-    )
-
-
-def test_fill_expressions():
-    template = Template("No one VERB the ADJ NOUN!")
-    filled = template.fill_expressions(
-        VERB="expects",
-        ADJ="Spanish",
-        NOUN="Inquisition",
-    ).finish()
-    assert filled == "No one expects the Spanish Inquisition!"
-
-
-def test_fill_expressions_missing_slot_in_template():
-    template = Template("No one ... the ADJ NOUN!")
-    with pytest.raises(Exception, match=r"No 'VERB' slot to fill with 'expects'"):
-        template.fill_expressions(
-            VERB="expects",
-            ADJ="Spanish",
-            NOUN="Inquisition",
-        ).finish()
-
-
-def test_fill_expressions_extra_slot_in_template():
-    template = Template("No one VERB ARTICLE ADJ NOUN!")
-    with pytest.raises(Exception, match=r"'ARTICLE' slot not filled"):
-        template.fill_expressions(
-            VERB="expects",
-            ADJ="Spanish",
-            NOUN="Inquisition",
-        ).finish()
-
-
-def test_fill_values():
-    template = Template("assert [STRING] * NUM == LIST")
-    filled = template.fill_values(
-        STRING="🙂",
-        NUM=3,
-        LIST=["🙂", "🙂", "🙂"],
-    ).finish()
-    assert filled == "assert ['🙂'] * 3 == ['🙂', '🙂', '🙂']"
-
-
-def test_fill_values_missing_slot_in_template():
-    template = Template("assert [STRING] * ... == LIST")
-    with pytest.raises(Exception, match=r"No 'NUM' slot to fill with '3'"):
-        template.fill_values(
-            STRING="🙂",
-            NUM=3,
-            LIST=["🙂", "🙂", "🙂"],
-        ).finish()
-
-
-def test_fill_values_extra_slot_in_template():
-    template = Template("CMD [STRING] * NUM == LIST")
-    with pytest.raises(Exception, match=r"'CMD' slot not filled"):
-        template.fill_values(
-            STRING="🙂",
-            NUM=3,
-            LIST=["🙂", "🙂", "🙂"],
-        ).finish()
-
-
-def test_fill_blocks():
-    # "OK" is less than three characters, so it is not a slot.
-    template = Template(
-        """# MixedCase is OK
-
-FIRST
-
-with fake:
-    SECOND
-    if True:
-        THIRD
-""",
-    )
-    template.fill_blocks(
-        FIRST="\n".join(f"import {i}" for i in "abc"),
-        SECOND="\n".join(f"f({i})" for i in "123"),
-        THIRD="\n".join(f"{i}()" for i in "xyz"),
-    )
-    assert (
-        template.finish()
-        == """# MixedCase is OK
-
-import a
-import b
-import c
-
-with fake:
-    f(1)
-    f(2)
-    f(3)
-    if True:
-        x()
-        y()
-        z()
-"""
-    )
-
-
-def test_fill_blocks_missing_slot_in_template_alone():
-    template = Template("No block slot")
-    with pytest.raises(Exception, match=r"No 'SLOT' slot"):
-        template.fill_blocks(SLOT="placeholder").finish()
-
-
-def test_fill_blocks_missing_slot_in_template_not_alone():
-    template = Template("No block SLOT")
-    with pytest.raises(
-        Exception, match=r"Block slots must be alone on line; No 'SLOT' slot"
-    ):
-        template.fill_blocks(SLOT="placeholder").finish()
-
-
-def test_fill_blocks_extra_slot_in_template():
-    template = Template("EXTRA\nSLOT")
-    with pytest.raises(Exception, match=r"'EXTRA' slot not filled"):
-        template.fill_blocks(SLOT="placeholder").finish()
-
-
-def test_fill_blocks_not_string():
-    template = Template("SOMETHING")
-    with pytest.raises(
-        Exception,
-        match=r"For SOMETHING in string template, expected string, not 123",
-    ):
-        template.fill_blocks(SOMETHING=123).finish()