dp_wizard_templates 0.1.0__tar.gz → 0.3.0__tar.gz

{dp_wizard_templates-0.1.0 → dp_wizard_templates-0.3.0}/.coveragerc

@@ -6,7 +6,7 @@ source = .
 # TODO: branch = True
 
 omit =
-  README_examples/*
+  examples/*
 
 
 [report]

{dp_wizard_templates-0.1.0 → dp_wizard_templates-0.3.0}/.flake8

@@ -9,6 +9,7 @@ extend-ignore = E203,E501,E701
 
 per-file-ignores =
     # Ignore undefined names in templates.
-    README_examples/*.py:F821,F401,E302
-    # Ignore mid-file imports: These are better for exaplanation.
-    README_test.py:E402
+    examples/*.py:F821,F401,E302
+    # Ignore mid-file imports: These make for a better exposition.
+    # Ignore lines that too long. Mostly URLs.
+    test_index_html.py:E402,B950

dp_wizard_templates-0.3.0/.nojekyll

@@ -0,0 +1 @@
+# Use index.html instead of Jekyll.

{dp_wizard_templates-0.1.0 → dp_wizard_templates-0.3.0}/.pre-commit-config.yaml

@@ -3,7 +3,8 @@ repos:
     rev: v2.3.0
     hooks:
     -   id: check-yaml
-    -   id: end-of-file-fixer
+    # This conflicts with generated notebooks:
+    # -   id: end-of-file-fixer
     -   id: trailing-whitespace
   # Using this mirror lets us use mypyc-compiled black, which is about 2x faster
   - repo: https://github.com/psf/black-pre-commit-mirror

dp_wizard_templates-0.3.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# CHANGELOG
+
+## 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.1.0 → dp_wizard_templates-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp_wizard_templates
-Version: 0.1.0
+Version: 0.3.0
 Summary: Code templating tools
 Author-email: The OpenDP Project <info@opendp.org>
 Description-Content-Type: text/markdown
@@ -10,7 +10,8 @@ Requires-Dist: ipykernel
 Requires-Dist: jupyter-client
 Requires-Dist: jupytext
 Requires-Dist: nbconvert
-Project-URL: Home, https://github.com/opendp/dp-wizard-templates
+Project-URL: GitHub, https://github.com/opendp/dp-wizard-templates
+Project-URL: Homepage, https://opendp.github.io/dp-wizard-templates
 
 # DP Wizard Templates
 
@@ -19,12 +20,7 @@ Project-URL: Home, https://github.com/opendp/dp-wizard-templates
 DP Wizard Templates lets you use syntactically valid Python code as a template.
 Templates can be filled and composed to generate entire notebooks.
 
-[`README_test.py`](https://github.com/opendp/dp-wizard-templates/blob/main/README_test.py) provides an example of use,
-and an example [output notebook](https://github.com/opendp/dp-wizard-templates/blob/main/README_examples/hello-world.ipynb)
-is also available.
-
-DP Wizard Templates was developed for [DP Wizard](https://github.com/opendp/dp-wizard),
-and that codebase remains a good place to look for further examples.
+See the [documentation](https://opendp.github.io/dp-wizard-templates) for more information.
 
 
 ## Development

{dp_wizard_templates-0.1.0 → dp_wizard_templates-0.3.0}/README.md

@@ -5,12 +5,7 @@
 DP Wizard Templates lets you use syntactically valid Python code as a template.
 Templates can be filled and composed to generate entire notebooks.
 
-[`README_test.py`](https://github.com/opendp/dp-wizard-templates/blob/main/README_test.py) provides an example of use,
-and an example [output notebook](https://github.com/opendp/dp-wizard-templates/blob/main/README_examples/hello-world.ipynb)
-is also available.
-
-DP Wizard Templates was developed for [DP Wizard](https://github.com/opendp/dp-wizard),
-and that codebase remains a good place to look for further examples.
+See the [documentation](https://opendp.github.io/dp-wizard-templates) for more information.
 
 
 ## Development

dp_wizard_templates-0.3.0/dp_wizard_templates/VERSION

@@ -0,0 +1 @@
+0.3.0

dp_wizard_templates-0.3.0/dp_wizard_templates/code_template.py

@@ -0,0 +1,179 @@
+from typing import Optional, Callable
+from pathlib import Path
+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: str | Callable,
+        root: Optional[Path] = 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) -> 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 Exception(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=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()
+        if unfilled_slots:
+            errors = [f"'{slot}' slot not filled" for slot in unfilled_slots]
+            raise Exception(self._make_message(errors))
+
+        if reformat:
+            self._template = black.format_str(self._template, mode=black.Mode())
+
+        return self._template

{dp_wizard_templates-0.1.0 → dp_wizard_templates-0.3.0}/dp_wizard_templates/converters.py

@@ -7,6 +7,7 @@ import json
 import nbformat
 import nbconvert
 import jupytext
+import black
 
 
 def _is_kernel_installed() -> bool:
@@ -27,7 +28,9 @@ class ConversionException(Exception):
         return f"Script to notebook conversion failed: {self.command}\n{self.stderr})"
 
 
-def convert_py_to_nb(python_str: str, title: str, execute: bool = False):
+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:
@@ -43,6 +46,9 @@ def convert_py_to_nb(python_str: str, title: str, execute: bool = False):
 
         temp_dir_path = Path(temp_dir)
         py_path = temp_dir_path / "input.py"
+        if reformat:
+            # Line length determined by PDF rendering.
+            python_str = black.format_str(python_str, mode=black.Mode(line_length=74))
         py_path.write_text(python_str)
 
         argv = [executable] + "-m jupytext --from .py --to .ipynb --output -".split(" ")
@@ -65,13 +71,13 @@ def convert_py_to_nb(python_str: str, title: str, execute: bool = False):
     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,
@@ -82,7 +88,9 @@ def _clean_nb(nb_json: str):
     for cell in nb["cells"]:
         if "pip install" in cell["source"][0]:
             cell["outputs"] = []
-        if "# Coda\n" in cell["source"]:
+        # "Coda" may, or may not be followed by "\n".
+        # Be flexible!
+        if any(line.startswith("# Coda") for line in cell["source"]):
             break
         # Make ID stable:
         cell["id"] = _stable_hash(cell["source"])
@@ -96,13 +104,9 @@ def _clean_nb(nb_json: str):
     return json.dumps(nb, indent=1)
 
 
-def convert_nb_to_html(python_nb: str):
-    return _convert_nb(python_nb, nbconvert.HTMLExporter)
-
-
-def _convert_nb(python_nb: str, exporter_constructor):
+def convert_nb_to_html(python_nb: str, numbered=True) -> str:
     notebook = nbformat.reads(python_nb, as_version=4)
-    exporter = exporter_constructor(
+    exporter = nbconvert.HTMLExporter(
         template_name="lab",
         # The "classic" template's CSS forces large code cells on to
         # the next page rather than breaking, so use "lab" instead.
@@ -116,4 +120,13 @@ def _convert_nb(python_nb: str, exporter_constructor):
         # ],
     )
     (body, _resources) = exporter.from_notebook_node(notebook)
+    if not numbered:
+        body = body.replace(
+            "</head>",
+            """
+<style>
+.jp-InputPrompt {display: none;}
+</style>
+</head>""",
+        )
     return body

{dp_wizard_templates-0.1.0/README_examples → dp_wizard_templates-0.3.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.1.0/README_examples → dp_wizard_templates-0.3.0/examples}/hello-world.html

@@ -7511,19 +7511,19 @@ a.anchor-link {
 <!-- End of mermaid configuration --></head>
 <body class="jp-Notebook" data-jp-theme-light="true" data-jp-theme-name="JupyterLab Light">
 <main>
-<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell" id="cell-id=3d14220e">
+<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell" id="cell-id=6fc59e52">
 <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">
 <h1 id="Hello-World!">Hello World!<a class="anchor-link" href="#Hello-World!">¶</a></h1><p>Comments will be rendered as <em>Markdown</em>.
-The + and - below ensure that only one cell is produced,
+The <code>+</code> and <code>-</code> below ensure that only one code cell is produced,
 even though the lines are not contiguous</p>
 </div>
 </div>
 </div>
-</div><div class="jp-Cell jp-CodeCell jp-Notebook-cell" id="cell-id=736e1e13">
+</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,8 +7535,11 @@ 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="s1">'It is freezing!'</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>
 
 
 <span class="n">freeze_warning</span><span class="p">(</span><span class="o">-</span><span class="mi">10</span><span class="p">)</span>

{dp_wizard_templates-0.1.0/README_examples → dp_wizard_templates-0.3.0/examples}/hello-world.ipynb

@@ -2,20 +2,22 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "id": "3d14220e",
-   "metadata": {},
+   "id": "6fc59e52",
+   "metadata": {
+    "lines_to_next_cell": 2
+   },
    "source": [
     "# Hello World!\n",
     "\n",
     "Comments will be rendered as *Markdown*.\n",
-    "The + and - below ensure that only one cell is produced,\n",
+    "The `+` and `-` below ensure that only one code cell is produced,\n",
     "even though the lines are not contiguous"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 1,
-   "id": "736e1e13",
+   "id": "d75dbbc1",
    "metadata": {},
    "outputs": [
     {
@@ -31,8 +33,11 @@
     "    \"\"\"\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",
+    "        print(\"It is freezing!\")\n",
     "\n",
     "\n",
     "freeze_warning(-10)"