dp_wizard_templates 0.7.0__py2.py3-none-any.whl

dp_wizard_templates/VERSION

@@ -0,0 +1 @@
+0.7.0

dp_wizard_templates/__init__.py

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

dp_wizard_templates/code_template.py

@@ -0,0 +1,305 @@
+import inspect
+import json
+import re
+from pathlib import Path
+from typing import Callable, Iterable, Optional
+
+import black
+
+
+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)
+
+
+_slot_re = r"\b[A-Z][A-Z_]{2,}\b"
+
+
+def _check_kwargs(func):
+    def wrapper(*args, **kwargs):
+        WHEN = "when"
+        errors = []
+        for k in kwargs.keys():
+            if k in args[0]._ignore:
+                errors.append(f'kwarg "{k}" is an ignored slot name')
+            if not (re.fullmatch(_slot_re, k) or k == WHEN):
+                errors.append(f'kwarg "{k}" is not a valid slot name')
+        if errors:
+            raise TemplateException(
+                "; ".join(errors)
+                + f'. Slots should match "{_slot_re}". '
+                + "Some slots are ignored, and should not be filled: "
+                + ",".join(f'"{v}"' for v in args[0]._ignore)
+            )
+        if not kwargs.get(WHEN, True):
+            # return self:
+            return args[0]
+        kwargs.pop(WHEN, None)
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+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
+        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_attribute_slots(self, **kwargs) -> None:
+        def function(k, v, errors):
+            k_re = re.escape(k)
+            attr_re = rf"\.\b{k_re}\b"
+            self._template, count = re.subn(
+                attr_re, f".{v}" if v else "", self._template
+            )
+            if count == 0:
+                errors.append(
+                    f"no '.{k}' slot to fill with '{v}'"
+                    if v
+                    else f"no '.{k}' slot to delete (because replacement is false-y)"
+                )
+
+        self._loop_kwargs(function, **kwargs)
+
+    def _fill_argument_slots(
+        self,
+        stringifier: Callable[[str], str],
+        **kwargs,
+    ) -> None:
+        def function(k, v, errors):
+            k_re = re.escape(k)
+            arg_re = rf"\s*\b{k_re}\b,\s*"
+            self._template, count = re.subn(
+                arg_re, f"{stringifier(v)}," if v else "", self._template
+            )
+            if count == 0:
+                errors.append(
+                    f"no '{k},' slot to fill with '{v}'"
+                    if v
+                    else f"no '{k},' slot to delete (because replacement is false-y)"
+                )
+
+        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)
+
+    @_check_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
+
+    @_check_kwargs
+    def fill_attributes(self, **kwargs) -> "Template":
+        """
+        Fill in attributes with expressions, or remove leading "." if false-y.
+        """
+        self._fill_attribute_slots(**kwargs)
+        return self
+
+    @_check_kwargs
+    def fill_argument_expressions(self, **kwargs) -> "Template":
+        """
+        Fill in argument expressions, or removing trailing "," if false-y.
+        """
+        self._fill_argument_slots(stringifier=str, **kwargs)
+        return self
+
+    @_check_kwargs
+    def fill_argument_values(self, **kwargs) -> "Template":
+        """
+        Fill in argument values, or removing trailing "," if false-y.
+        """
+        self._fill_argument_slots(stringifier=_check_repr, **kwargs)
+        return self
+
+    @_check_kwargs
+    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
+
+    @_check_kwargs
+    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
+
+    @_check_kwargs
+    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:
+        # The reformat default is False here,
+        # because it is true downstream for notebook generation,
+        # and we don't need to be redundant.
+        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/converters.py

@@ -0,0 +1,140 @@
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from sys import executable
+from tempfile import TemporaryDirectory
+
+import black
+import jupytext
+import nbconvert
+
+
+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, reformat: bool = True
+) -> str:
+    """
+    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"
+        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(" ")
+        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]) -> str:
+    import hashlib
+
+    return hashlib.sha1("\n".join(lines).encode()).hexdigest()[:8]
+
+
+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,
+    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"] = []
+        # "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"])
+        # 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, numbered=True) -> str:
+    import warnings
+
+    import nbformat.warnings
+
+    with warnings.catch_warnings():
+        warnings.simplefilter(
+            action="ignore", category=nbformat.warnings.DuplicateCellId
+        )
+        notebook = nbformat.reads(python_nb, as_version=4)
+    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.
+        #
+        # 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)
+    if not numbered:
+        body = body.replace(
+            "</head>",
+            """
+<style>
+.jp-InputPrompt {display: none;}
+</style>
+</head>""",
+        )
+    return body

dp_wizard_templates-0.7.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: dp_wizard_templates
+Version: 0.7.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: GitHub, https://github.com/opendp/dp-wizard-templates
+Project-URL: Homepage, https://opendp.github.io/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.
+
+See the [documentation](https://opendp.github.io/dp-wizard-templates) for more information.
+
+
+## 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.7.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+dp_wizard_templates/VERSION,sha256=sMsnbN5Rd3nKQ6X4_pStzWsco7Tn2l6X8szZw7Q4Hfg,5
+dp_wizard_templates/__init__.py,sha256=DF2xPO1uVitkB9NRBpqd_HayLHk4hnckLo8jaccoEbI,125
+dp_wizard_templates/code_template.py,sha256=GmKOSfU7eOX9QN9PJ0zq1nXUHSTePyn2wM5Wmhjda-g,9687
+dp_wizard_templates/converters.py,sha256=Xzb0suMDCMpqLytgFUtlW80GKlVWRbzfTtfsD6cL8Uo,4548
+dp_wizard_templates/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dp_wizard_templates-0.7.0.dist-info/licenses/LICENSE,sha256=FDrIMeZPiT4g_4w0i1Ec4Bc8h9wfNytroheQN4508yU,1063
+dp_wizard_templates-0.7.0.dist-info/WHEEL,sha256=Dyt6SBfaasWElUrURkknVFAZDHSTwxg3PaTza7RSbkY,100
+dp_wizard_templates-0.7.0.dist-info/METADATA,sha256=y0A2fFxjkUuzYX-CQDyUWnipDjRTMA6k-wry0PJyS5w,1881
+dp_wizard_templates-0.7.0.dist-info/RECORD,,

dp_wizard_templates-0.7.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.7.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.