dp_wizard_templates 0.1.0__py2.py3-none-any.whl

dp_wizard_templates/VERSION

@@ -0,0 +1 @@
+0.1.0

dp_wizard_templates/__init__.py

@@ -0,0 +1,6 @@
+"""Code templating tools"""
+
+from pathlib import Path
+
+
+__version__ = (Path(__file__).parent / "VERSION").read_text().strip()

dp_wizard_templates/code_template.py

@@ -0,0 +1,127 @@
+import re
+
+
+def _get_body(func):
+    import inspect
+    import re
+
+    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) -> 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}"
+            )
+        return self._template

dp_wizard_templates/converters.py

@@ -0,0 +1,119 @@
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from dataclasses import dataclass
+from sys import executable
+import subprocess
+import json
+import nbformat
+import nbconvert
+import jupytext
+
+
+def _is_kernel_installed() -> bool:
+    try:
+        # This method isn't well documented, so it may be fragile.
+        jupytext.kernels.kernelspec_from_language("python")  # type: ignore
+        return True
+    except ValueError:  # pragma: no cover
+        return False
+
+
+@dataclass(frozen=True)
+class ConversionException(Exception):
+    command: str
+    stderr: str
+
+    def __str__(self):
+        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):
+    """
+    Given Python code as a string, returns a notebook as a string.
+    Calls jupytext as a subprocess:
+    Not ideal, but only the CLI is documented well.
+    """
+    with TemporaryDirectory() as temp_dir:
+        if not _is_kernel_installed():
+            subprocess.run(  # pragma: no cover
+                [executable]
+                + "-m ipykernel install --name kernel_name --user".split(" "),
+                check=True,
+            )
+
+        temp_dir_path = Path(temp_dir)
+        py_path = temp_dir_path / "input.py"
+        py_path.write_text(python_str)
+
+        argv = [executable] + "-m jupytext --from .py --to .ipynb --output -".split(" ")
+        if execute:
+            argv.append("--execute")
+        argv.append(str(py_path.absolute()))  # type: ignore
+        result = subprocess.run(argv, text=True, capture_output=True)
+    if result.returncode != 0:
+        # If there is an error, we want a copy of the file that will stay around,
+        # outside the "with TemporaryDirectory()" block.
+        # The command we show in the error message isn't exactly what was run,
+        # but it should reproduce the error.
+        debug_path = Path("/tmp/script.py")
+        debug_path.write_text(python_str)
+        argv.pop()
+        argv.append(str(debug_path))  # type: ignore
+        raise ConversionException(command=" ".join(argv), stderr=result.stderr)
+    nb_dict = json.loads(result.stdout.strip())
+    nb_dict["metadata"]["title"] = title
+    return _clean_nb(json.dumps(nb_dict))
+
+
+def _stable_hash(lines: list[str]):
+    import hashlib
+
+    return hashlib.sha1("\n".join(lines).encode()).hexdigest()[:8]
+
+
+def _clean_nb(nb_json: str):
+    """
+    Given a notebook as a string of JSON, remove the coda and pip output.
+    (The code may produce reports that we do need,
+    but the code isn't actually interesting to end users.)
+    """
+    nb = json.loads(nb_json)
+    new_cells = []
+    for cell in nb["cells"]:
+        if "pip install" in cell["source"][0]:
+            cell["outputs"] = []
+        if "# Coda\n" in cell["source"]:
+            break
+        # Make ID stable:
+        cell["id"] = _stable_hash(cell["source"])
+        # Delete execution metadata:
+        try:
+            del cell["metadata"]["execution"]
+        except KeyError:
+            pass
+        new_cells.append(cell)
+    nb["cells"] = new_cells
+    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):
+    notebook = nbformat.reads(python_nb, as_version=4)
+    exporter = exporter_constructor(
+        template_name="lab",
+        # The "classic" template's CSS forces large code cells on to
+        # the next page rather than breaking, so use "lab" instead.
+        #
+        # If you want to tweak the CSS, enable this block and make changes
+        # in nbconvert_templates/custom:
+        #
+        # template_name="custom",
+        # extra_template_basedirs=[
+        #     str((Path(__file__).parent / "nbconvert_templates").absolute())
+        # ],
+    )
+    (body, _resources) = exporter.from_notebook_node(notebook)
+    return body

dp_wizard_templates-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: dp_wizard_templates
+Version: 0.1.0
+Summary: Code templating tools
+Author-email: The OpenDP Project <info@opendp.org>
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: black
+Requires-Dist: ipykernel
+Requires-Dist: jupyter-client
+Requires-Dist: jupytext
+Requires-Dist: nbconvert
+Project-URL: Home, https://github.com/opendp/dp-wizard-templates
+
+# DP Wizard Templates
+
+[![pypi](https://img.shields.io/pypi/v/dp_wizard_templates)](https://pypi.org/project/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.
+
+
+## Development
+
+### Getting Started
+
+On MacOS:
+```shell
+$ git clone https://github.com/opendp/dp-wizard-templates.git
+$ cd dp-wizard-templates
+$ brew install python@3.10
+$ python3.10 -m venv .venv
+$ source .venv/bin/activate
+```
+
+You can now install dependencies:
+```shell
+$ pip install -r requirements-dev.txt
+$ pre-commit install
+$ flit install
+```
+
+Tests should pass, and code coverage should be complete (except blocks we explicitly ignore):
+```shell
+$ scripts/ci.sh
+```
+
+### Release
+
+- Make sure you're up to date, and have the git-ignored credentials file `.pypirc`.
+- Make one last feature branch with the new version number in the name:
+  - Run `scripts/changelog.py` to update the `CHANGELOG.md`.
+  - Review the updates and pull a couple highlights to the top.
+  - Bump `dp_wizard/VERSION`, and add the new number at the top of the `CHANGELOG.md`.
+  - Commit your changes, make a PR, and merge this branch to main.
+- Update `main` with the latest changes: `git checkout main; git pull`
+- Publish: `flit publish --pypirc .pypirc`
+

dp_wizard_templates-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+dp_wizard_templates/VERSION,sha256=atlhOkVXmNbZLl9fOQq0uqcFlryGntaxf1zdKyhjXwY,5
+dp_wizard_templates/__init__.py,sha256=E2xrnvZGY24pU3PCryH4TmvhNYsLmxXCtfvIcYNbTYw,126
+dp_wizard_templates/code_template.py,sha256=GW4wcAguGRFEE_eKLPedjmsklZR9dtx4wn8CYq-avh8,4389
+dp_wizard_templates/converters.py,sha256=l-MYAiTAH_isjggH03DKlgV-j-uxc0CyW1hiCLD39yQ,3957
+dp_wizard_templates-0.1.0.dist-info/licenses/LICENSE,sha256=FDrIMeZPiT4g_4w0i1Ec4Bc8h9wfNytroheQN4508yU,1063
+dp_wizard_templates-0.1.0.dist-info/WHEEL,sha256=Dyt6SBfaasWElUrURkknVFAZDHSTwxg3PaTza7RSbkY,100
+dp_wizard_templates-0.1.0.dist-info/METADATA,sha256=ZMvavNpdRK7GvyB-j4ht2JWSzPjhIC52n7VHVCyX70c,2139
+dp_wizard_templates-0.1.0.dist-info/RECORD,,

dp_wizard_templates-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

dp_wizard_templates-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenDP
+
+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.