potluck.snippets

   1"""
   2Code for defining examples that should be shown as part of instructions.
   3
   4snippets.py
   5
   6This module can be used in specifications files to define named examples,
   7which can then be compiled to HTML files using the --snippets option.
   8These examples will be evaluated within the context of the solution code,
   9and their output + return values will be formatted for display to the
  10students. By using snippets this way, as long as your solution file is
  11up-to-date, your example output will never be out-of-sync with what the
  12problem set is actually asking for.
  13
  14Example usage:
  15
  16```py
  17from potluck import snippets as sn
  18
  19EXAMPLE = [
  20    {
  21        "key": "value",
  22        "key2": "value2",
  23    },
  24    {
  25        "key": "valueB",
  26        "key2": "value2B"
  27    }
  28]
  29
  30sn.Variables(
  31    "vars", # snippet ID
  32    "<code>EXAMPLE</code> variable", # snippet displayed title
  33    (
  34        "A simple example of what the input data might look like, and"
  35        " the slightly more complex <code>DATA</code> variable provided"
  36        " in the starter code."
  37    ), # displayed snippet caption
  38    [ "EXAMPLE", "DATA" ] # list of variable names to display definitions of
  39).provide({ "EXAMPLE": EXAMPLE })
  40# provide overrides (or provides missing) solution module values
  41
  42sn.FunctionCalls(
  43    "examples", # snippet ID
  44    "Example results", # title
  45    (
  46        "Some examples of what <code>processData</code> should return"
  47        " for various inputs, using the <code>EXAMPLE</code> and"
  48        " <code>DATA</code> variables shown above."
  49    ),
  50    # caption (note we're assuming the 'vars' snippet will be included
  51    # first, otherwise this caption doesn't make sense).
  52    [
  53        ("processData", (EXAMPLE, 1)),
  54        ("processData", (EXAMPLE, 2)),
  55        ("processData", (EXAMPLE, 3))",
  56        ("processData", (cu.SolnValue("DATA"), 3)),
  57    ], # list of function name, arguments tuples to evaluate
  58)
  59
  60sn.RunModule(
  61    "run", # ID
  62    "Full output example", # title
  63    (
  64        "An example of what the output should look like when your code"
  65        " is run. Note that the blue text shows what inputs were"
  66        " provided in this example."
  67    ), # caption
  68).provide_inputs(["A", "B"]) # we're providing some inputs during the run
  69```
  70
  71The various snippet classes like `Variable`, `Expressions`, and
  72`RunModule` each inherit from `potluck.specifications.TestGroup`
  73meaning that you can use the various modification methods from that
  74module (such as `provide_inputs` as shown above) to control exactly how
  75the code is run.
  76"""
  77
  78import textwrap
  79import re
  80import os
  81
  82import pygments
  83
  84from . import logging
  85from . import specifications
  86from . import file_utils
  87from . import html_tools
  88from . import harness
  89from . import render
  90from . import rubrics
  91from . import contexts
  92from . import context_utils
  93
  94
  95#---------#
  96# Helpers #
  97#---------#
  98
  99FMT_WIDTH = 80
 100"""
 101Line width we'll attempt to hit for formatting output nicely.
 102"""
 103
 104
 105def wrap_str(string, width):
 106    """
 107    Returns a list of strings, which when combined form the given
 108    string, where none is longer than the given width. Lines are broken
 109    at spaces whenever possible, but may be broken in the middle of
 110    words when a single word is longer than the target width. This
 111    function uses a greedy algorithm that doesn't optimize the evenness
 112    of the right margin. \\n and \\r are represented by those character
 113    pairs, but other characters are as-is.
 114    """
 115    escaped = string.replace('\n', '\\n')
 116    escaped = escaped.replace('\r', '\\r')
 117    words = escaped.split(' ')
 118    result = []
 119    while len(words) > 0: # until we've used up the words
 120        # Figure out how many words would fit on the next line
 121        i = 0
 122        # + i accounts for spaces we'll need
 123        while len(words[:i + 1]) + (i + 1) < width:
 124            i += 1
 125
 126        # Back off to the number that fits
 127        i -= 1
 128
 129        # first word doesn't fit!
 130        if i == -1:
 131            first = words[0]
 132            # Chop up the first word and put the pieces into the result
 133            pieces = len(first) // width
 134            for j in range(pieces):
 135                result.append(first[width * j:width * (j + 1)])
 136
 137            # Handle leftovers
 138            rest = first[width * pieces:]
 139            # Note that even empty leftovers serve as a placeholder to
 140            # ensure that a space gets added.
 141            words[0] = rest # put rest back into words, replacing old
 142        else:
 143            # at least one word fits
 144            line = ' '.join(words[:i + 1]) + ' '
 145            result.append(line)
 146            words = words[i + 1:]
 147
 148    # Remove the extra space introduced after the end of the last word
 149    # Works even for an empty string input
 150    result[-1] = result[-1][:-1]
 151
 152    return result
 153
 154
 155def wrapped_repr(obj, width=FMT_WIDTH, indentation=1, prefix='', memo=None):
 156    """
 157    Returns a string representing the given object, whose lines are not
 158    longer than the given width, and which uses the given number of
 159    spaces to indent sub-objects when necessary. Replacement for
 160    pprint.pformat, which does NOT reorder dictionary keys. May violate
 161    the width restriction when given a complex object that it doesn't
 162    know how to wrap whose repr alone is wider than the specified width.
 163
 164    A prefix may be supplied, which will be added to the first line of
 165    the given representation as-is. The prefix itself will not be subject
 166    to wrapping, but the first line of the result will in some cases wrap
 167    earlier to compensate for the prefix. The prefix should not include
 168    any newlines or carriage returns.
 169
 170    The memo helps avoid problems with recursion, and doesn't need to be
 171    provided explicitly.
 172    """
 173    # Create a memo if we need to
 174    if memo is None:
 175        memo = set()
 176
 177    # Check the memo
 178    if id(obj) in memo:
 179        return '...'
 180
 181    # Add ourselves to the memo
 182    memo.add(id(obj))
 183
 184    simple = prefix + repr(obj)
 185
 186    if len(simple) <= width: # no need to do anything fancy
 187        return simple
 188
 189    indent = ' ' * indentation
 190    between = '\n' + indent
 191
 192    broken = repr(obj)
 193    if len(broken) < width - indentation:
 194        return prefix + '\\' + between + broken
 195
 196    elif type(obj) == str: # need to wrap this string
 197        lines = wrap_str(obj, width - (indentation + 2))
 198        return (
 199            prefix + '(' + between
 200          + between.join('"' + line + '"' for line in lines)
 201          + '\n)'
 202        )
 203
 204    elif type(obj) == bytes: # need to wrap these bytes
 205        lines = wrap_str(obj, width - (indentation + 3))
 206        return (
 207            prefix + '(' + between
 208          + between.join('b"' + line + '"' for line in lines)
 209          + '\n)'
 210        )
 211
 212    elif type(obj) in (list, tuple, set): # need to wrap each item
 213        if type(obj) in (list, tuple):
 214            ldelim, rdelim = str(type(obj)())
 215        elif len(obj) == 0:
 216            return prefix + 'set()' # too bad if width is < 5
 217        else:
 218            ldelim = '{'
 219            rdelim = '}'
 220
 221        result = prefix + ldelim + between
 222        for item in obj:
 223            result += textwrap.indent(
 224                wrapped_repr(item, width - indentation, indentation),
 225                indent
 226            ) + ',' + between
 227
 228        return result[:-len(between)] + '\n' + rdelim
 229
 230    elif type(obj) == dict: # need to wrap keys and values
 231        indent = ' ' * indentation
 232        between = '\n' + indent
 233
 234        result = prefix + '{' + between
 235        for key in obj:
 236            key_repr = wrapped_repr(
 237                key,
 238                width - (indentation + 1),
 239                indentation
 240            )
 241            val = obj[key]
 242            val_repr = wrapped_repr(
 243                val,
 244                width - indentation * 2,
 245                indentation
 246            )
 247
 248            # Can we fit on one line?
 249            if len(indent) + len(key_repr) + len(val_repr) + 3 <= width:
 250                result += key_repr + ': ' + val_repr + ',' + between
 251            elif val_repr[1] == '\n': # ldelim/newline start
 252                result += (
 253                    key_repr + ':' + val_repr[0] + '\n'
 254                  + textwrap.indent(val_repr[2:], indent)
 255                  + ',' + between
 256                )
 257            else:
 258                result += key_repr + ':\n' + textwrap.indent(
 259                    val_repr,
 260                    indent * 2
 261                ) + ',' + between
 262
 263        # Chop off final between and add closing brace after a newline
 264        result = result[:-len(between)] + '\n}'
 265
 266        return result
 267
 268    else: # Not sure how to wrap this, so we give up...
 269        return prefix + repr(obj)
 270
 271
 272def wrapped_with_prefix(obj, prefix, indentation_level=0):
 273    """
 274    Returns a string representing the given object, as `wrapped_repr`
 275    would, except that:
 276
 277    1. The first line includes the given prefix (as a string without
 278       repr applied to it; after indentation) and the wrapping of object
 279       values takes this into account.
 280    2. The entire representation is indented by the given indentation
 281       level (one space per level).
 282    """
 283    rep = wrapped_repr(
 284        obj,
 285        width=FMT_WIDTH - indentation_level,
 286        indentation=1,
 287        prefix=prefix
 288    )
 289
 290    # remove extra indentation from tuple
 291    rep = textwrap.dedent(rep)
 292
 293    # restore indent and add prefix
 294    return textwrap.indent(rep, ' ' * indentation_level)
 295
 296
 297def extract(context, key):
 298    """
 299    Gets value from a context but raises a ValueError showing the
 300    context's error log if it can't.
 301    """
 302    if key in context:
 303        return context[key]
 304    else:
 305        # Note: we use a ValueError here instead of a KeyError because
 306        # KeyError uses repr on its message...
 307        if "ref_error_log" in context:
 308            raise ValueError(
 309                (
 310                    "Error: context is missing the '{}' key. Error log"
 311                    " is:\n{}"
 312                ).format(key, context["ref_error_log"]),
 313            )
 314        else:
 315            raise ValueError(
 316                "Error: context is missing the '{}' key. No error log"
 317                " available."
 318            )
 319
 320
 321#--------------#
 322# Registration #
 323#--------------#
 324
 325SNIPPET_REGISTRY = {}
 326"""
 327All registered snippets, by defining module and then snippet ID.
 328"""
 329
 330
 331#-----------------------#
 332# Snippet setup/cleanup #
 333#-----------------------#
 334
 335REMEMBER = {}
 336"""
 337Things to remember so we can undo setup changes.
 338"""
 339
 340
 341def snippet_setup(context):
 342    """
 343    If the wavesynth module is available, disables the playTrack and
 344    saveTrack functions from that module. If the optimism module is
 345    available, disables colors for that module.
 346    """
 347    try:
 348        import wavesynth
 349        REMEMBER["playTrack"] = wavesynth.playTrack
 350        wavesynth.playTrack = lambda _=None: None
 351        REMEMBER["saveTrack"] = wavesynth.saveTrack
 352        wavesynth.saveTrack = lambda _: None
 353    except ModuleNotFoundError:
 354        pass
 355
 356    try:
 357        import optimism
 358        REMEMBER["opt_colors"] = optimism.COLORS
 359        optimism.colors(False)
 360    except ModuleNotFoundError:
 361        pass
 362
 363    return context
 364
 365
 366def snippet_cleanup(context):
 367    """
 368    Puts things back how they were before `snippet_setup`.
 369    """
 370    try:
 371        import wavesynth
 372        wavesynth.playTrack = REMEMBER["playTrack"]
 373        wavesynth.saveTrack = REMEMBER["saveTrack"]
 374    except ModuleNotFoundError:
 375        pass
 376
 377    try:
 378        import optimism
 379        optimism.colors(REMEMBER["opt_colors"])
 380    except ModuleNotFoundError:
 381        pass
 382
 383    return context
 384
 385
 386#----------------------------#
 387# Snippet class & subclasses #
 388#----------------------------#
 389
 390class Snippet(specifications.TestGroup):
 391    """
 392    Common functionality for snippets. Don't instantiate this class;
 393    instead use one of the subclasses `Variables`, `Expressions`, or
 394    `RunModule`.
 395
 396    Note that a `Snippet` is a `potluck.specifications.TestGroup`, from
 397    which it inherits a powerful interface for customizing behavior. Some
 398    default modifications are applied to every snippet:
 399
 400    1. Output, including stderr and error tracebacks, is captured.
 401    2. A setup function is run which disables turtle tracing, wavesynth
 402        track playing/saving, and optimism colors (only when the relevant
 403        module(s) are available). A cleanup function that reverses all of
 404        these changes except the turtle speed is also run afterwards.
 405    """
 406    @staticmethod
 407    def base_context(task_info):
 408        """
 409        Creates a base context object for a snippet, given a task info
 410        object.
 411        """
 412        return {
 413            "task_info": task_info,
 414            "username": "__soln__",
 415            "submission_root": task_info["specification"].soln_path,
 416            "default_file": task_info["target"],
 417            "actual_file": task_info["target"]
 418        }
 419
 420    def __init__(
 421        self,
 422        sid,
 423        title,
 424        caption,
 425        tests,
 426        postscript='',
 427        glamers=None,
 428        ignore_errors=False
 429    ):
 430        """
 431        All `Snippet`s have a snippet ID, a title, a caption, and one or
 432        more tests. `tests` must be an iterable of unregistered
 433        `potluck.specifications.TestCase` objects.
 434
 435        An optional postscript is markdown source to be placed after the
 436        code block.
 437
 438        An optional list of glamer functions may be provided. These will
 439        be given individual pieces of HTML code and the associated
 440        context those were rendered from and their result value will
 441        replace the HTML code to be used; they are applied in-order.
 442
 443        Unless ignore_errors is set to False (default is True), errors
 444        generated by the base payload and captured along with output will
 445        be logged under the assumption that in most cases an exception in
 446        a snippet is a bug with the snippet code rather than intentional.
 447        """
 448        # Set ourselves up as a TestGroup...
 449        super().__init__(sid, '_')
 450
 451        # We store our arguments
 452        self.title = title
 453        self.caption = caption
 454        self.postscript = postscript
 455        self.glamers = glamers or []
 456        self.ignore_errors = ignore_errors
 457
 458        # Final edit function to manipulate the context to be rendered
 459        self.editor = None
 460
 461        # What's the name of our spec file?
 462        self.spec_file = file_utils.get_spec_file_name()
 463
 464        # Add our tests to ourself
 465        for t in tests:
 466            self.add(t)
 467
 468        # Fetch the defining-module-specific registry
 469        reg = SNIPPET_REGISTRY.setdefault(
 470            file_utils.get_spec_module_name(),
 471            {}
 472        )
 473
 474        # Prevent ID collision
 475        if sid in reg:
 476            raise ValueError(
 477                "Multiple snippets cannot be registered with the same"
 478                " ID ('{sid}')."
 479            )
 480
 481        # Register ourself
 482        reg[sid] = self
 483
 484        # A place to cache our compiled result
 485        self.cached_for = None
 486        self.cached_value = None
 487
 488        # Set up default augmentations
 489        self.capture_output(capture_errors=True, capture_stderr=True)
 490        self.do_setup(snippet_setup)
 491        self.do_cleanup(snippet_cleanup)
 492
 493    def provide(self, vars_map):
 494        """
 495        A convenience function for providing the snippet with values not
 496        defined in the solution module. Under the hood, this uses
 497        `specifications.HasPayload.use_decorations`, so using that
 498        alongside this will not work (one will overwrite the other). This
 499        also means that you cannot call `provide` multiple times on the
 500        same instance to accumulate provided values: each call discards
 501        previous provided values.
 502        """
 503        self.use_decorations(
 504            {
 505                k: (lambda _: v)
 506                for (k, v) in vars_map.items()
 507            },
 508            ignore_missing=True
 509        )
 510
 511    # TODO: define replacements so that formatting of calls can use
 512    # varnames?
 513
 514    def compile(self, base_context):
 515        """
 516        Runs the snippet, collects its results, and formats them as HTML.
 517        Returns a string containing HTML code for displaying the snippet
 518        (which assumes that the potluck.css stylesheet will be loaded).
 519
 520        This method will always re-run the compilation process,
 521        regardless of whether a cached result is available, and will
 522        update the cached result. Use `Snippet.get_html` to recompile
 523        only as needed.
 524
 525        Requires a base context object (see `potluck.contexts.Context`
 526        for the required structure).
 527
 528        The returned HTML's outermost tag is a &lt;section&gt; tag with
 529        an id that starts with 'snippet:' and then ends with the
 530        snippet's ID value.
 531        """
 532        # Set up traceback-rewriting for the specifications module we
 533        # were defined in
 534        html_tools.set_tb_rewrite(
 535            base_context["task_info"]["specification"].__file__,
 536            "<task specification>"
 537        )
 538        html_tools.set_tb_rewrite(
 539            base_context["submission_root"],
 540            "<solution>"
 541        )
 542
 543        # Tell the run_for_base_and_ref_values augmentation to run only
 544        # for ref values.
 545        self.augmentations.setdefault(
 546            "run_for_base_and_ref_values",
 547            {}
 548        )["ref_only"] = True
 549
 550        for case in self.tests:
 551            case.augmentations.setdefault(
 552                "run_for_base_and_ref_values",
 553                {}
 554            )["ref_only"] = True
 555
 556        # Create our Goal object
 557        goal = self.provide_goal()
 558
 559        # Reset and evaluate our goal:
 560        goal.reset_network()
 561        goal.evaluate(base_context)
 562
 563        # Grab the contexts that were used for each test
 564        if goal.test_in and len(goal.test_in["contexts"]) > 0:
 565            contexts = goal.test_in["contexts"]
 566        else:
 567            # This shouldn't be possible unless an empty list of
 568            # variables or functions was provided...
 569            raise ValueError(
 570                "A Snippet must have at least one context to compile."
 571                " (Did you pass an empty list to Variables or"
 572                " FunctionCalls?)"
 573            )
 574
 575        # Translate from markdown
 576        title = render.render_markdown(self.title)
 577        caption = render.render_markdown(self.caption)
 578        post = render.render_markdown(self.postscript)
 579
 580        context_dicts = []
 581        for ctx in contexts:
 582            try:
 583                cdict = ctx.create(base_context)
 584            except context_utils.ContextCreationError:
 585                cdict = {
 586                    # for RunModule snippets (note no ref_)
 587                    "filename": "UNKNOWN",
 588                    # In case it's a Variables snippet
 589                    "ref_variable": "UNKNOWN",
 590                    # for FunctionCalls snippets
 591                    "ref_function": "UNKNOWN",
 592                    "ref_args": (),
 593                    "ref_kwargs": {},
 594                    # for Blocks snippets
 595                    "ref_block": "UNKNOWN",
 596                    # For all kinds of snippets
 597                    "ref_value": "There was an error compiling this snippet.",
 598                    "ref_output": "There was an error compiling this snippet.",
 599                    "ref_error_log": html_tools.string_traceback()
 600                }
 601            context_dicts.append(cdict)
 602
 603        # Strip out solution file paths from output, and perform final
 604        # edits if we have an editor function
 605        soln_path = os.path.abspath(
 606            base_context["task_info"]["specification"].soln_path
 607        )
 608        for context in context_dicts:
 609            if (
 610                "ref_output" in context
 611            and soln_path in context["ref_output"]
 612            ):
 613                context["ref_output"] = context["ref_output"].replace(
 614                    soln_path,
 615                    '&lt;soln&gt;'
 616                )
 617
 618            if (
 619                "ref_error_log" in context
 620            and soln_path in context["ref_error_log"]
 621            ):
 622                context["ref_error_log"] = context["ref_error_log"].replace(
 623                    soln_path,
 624                    '&lt;soln&gt;'
 625                )
 626
 627            if self.editor:
 628                self.editor(context)
 629
 630        # Include title & caption, and render each context to produce our
 631        # result
 632        result = (
 633            '<section class="snippet" id="snippet:{sid}">'
 634            '<div class="snippet_title">{title}</div>\n'
 635            '{caption}\n<pre>{snippet}</pre>\n{post}'
 636            '</section>'
 637        ).format(
 638            sid=self.base_name,
 639            title=title,
 640            caption=caption,
 641            post=post,
 642            snippet=''.join(
 643                self.compile_context(cd)
 644                for cd in context_dicts
 645            )
 646        )
 647
 648        self.cached_for = base_context["task_info"]["id"]
 649        self.cached_value = result
 650
 651        return result
 652
 653    def compile_context(self, context):
 654        """
 655        Turns a context dictionary resulting from an individual snippet
 656        case into HTML code for displaying that result, using
 657        `render_context` but also potentially adding additional HTML for
 658        extra context slots (see e.g., `show_image` and `play_audio`).
 659        """
 660        if not self.ignore_errors and "ref_error" in context:
 661            logging.log(
 662                "Error captured by context creation:\n"
 663              + context["ref_error"]
 664              + "\nFull log is:\n"
 665              + context.get("ref_error_log", '<missing>')
 666            )
 667        result = self.render_context(context)
 668        for glamer in self.glamers:
 669            result = glamer(result, context)
 670
 671        return result
 672
 673    def render_context(self, context):
 674        """
 675        Override this to define how a specific Snippet sub-class should
 676        render a context dictionary into HTML code.
 677        """
 678        raise NotImplementedError(
 679            "Snippet is abstract and context rendering is only available"
 680            " via overrides in sub-classes."
 681        )
 682
 683    def get_html(self, task_info):
 684        """
 685        Returns the snippet value, either cached or newly-compiled
 686        depending on the presence of an appropriate cached value.
 687        """
 688        if self.cached_for == task_info["id"]:
 689            return self.cached_value
 690        else:
 691            return self.compile(Snippet.base_context(task_info))
 692
 693    def final_edit(self, editor):
 694        """
 695        Sets up a function to be run on each created context just before
 696        that context gets rendered. The editor may mutate the context it
 697        is given in order to change what gets rendered. Multiple calls to
 698        this function each simply replace the previous editor function.
 699
 700        Note that the ref_* values from the context are used to create
 701        the snippet.
 702        """
 703        self.editor = editor
 704
 705    def show_image(self):
 706        """
 707        Adds a glamer that augments output by appending a "Image "
 708        prompt followed by an image element which shows the contents of
 709        the "ref_image" context slot. To establish a "ref_image" slot,
 710        call a method like
 711        `potluck.specifications.HasPayload.capture_turtle_image`.
 712
 713        Returns self for chaining.
 714        """
 715        self.glamers.append(append_image_result)
 716        return self
 717
 718    def play_audio(self):
 719        """
 720        Adds a glamer that augments output by appending an "Audio "
 721        prompt followed by an audio element which plays the contents of
 722        the "ref_audio" context slot. To make an "ref_audio" slot, call a
 723        method like
 724        `potluck.specifications.HasPayload.capture_wavesynth`.
 725
 726        Returns self for chaining.
 727        """
 728        self.glamers.append(append_audio_result)
 729        return self
 730
 731    def show_memory_report(self):
 732        """
 733        Adds a glamer that augments output by appending a "Memory Report"
 734        prompt followed by a memory report showing the structure of the
 735        "ref_value" context slot.
 736
 737        Returns self for chaining.
 738        """
 739        self.glamers.append(append_memory_report)
 740        return self
 741
 742    def show_file_contents(self):
 743        """
 744        Adds a glamer that augments output by appending a "File"
 745        prompt followed by a text box showing the filename and the
 746        contents of that file. Requires 'ref_output_filename' and
 747        'ref_output_file_contents' slots, which could be established
 748        using a method like
 749        `potluck.specifications.HasPayload.capture_file_contents`
 750
 751        Returns self for chaining.
 752        """
 753        self.glamers.append(append_file_contents)
 754        return self
 755
 756
 757def highlight_code(code):
 758    """
 759    Runs pygments highlighting but converts from a div/pre/code setup
 760    back to just a code tag with the 'highlight' class.
 761    """
 762    markup = pygments.highlight(
 763        code,
 764        pygments.lexers.PythonLexer(),
 765        pygments.formatters.HtmlFormatter()
 766    )
 767    # Note: markup will start a div and a pre we want to get rid of
 768    start = '<div class="highlight"><pre>'
 769    end = '</pre></div>\n'
 770    if markup.startswith(start):
 771        markup = markup[len(start):]
 772    if markup.endswith(end):
 773        markup = markup[:-len(end)]
 774
 775    return '<code class="highlight">{}</code>'.format(markup)
 776
 777
 778class Variables(Snippet):
 779    """
 780    A snippet which shows the definition of one or more variables. Use
 781    this to display examples of input data, especially when you want to
 782    use shorter expressions in examples of running code. If you want to
 783    use variables that aren't defined in the solution module, use the
 784    `Snippet.provide` method (but note that that method is incompatible
 785    with using `specifications.HasPayload.use_decorations`).
 786    """
 787    def __init__(self, sid, title, caption, varnames, postscript=''):
 788        """
 789        A snippet ID, a title, and a caption are required, as is a list
 790        of strings indicating the names of variables to show definitions
 791        of. Use `Snippet.provide` to supply values for variables not in
 792        the solution module.
 793
 794        A postscript is optional (see `Snippet`).
 795        """
 796        cases = [
 797            specifications.TestValue(
 798                varname,
 799                register=False
 800            )
 801            for varname in varnames
 802        ]
 803        super().__init__(sid, title, caption, cases, postscript)
 804
 805    def render_context(self, context):
 806        """
 807        Renders a context created for goal evaluation as HTML markup for
 808        the definition of a variable, including Jupyter-notebook-style
 809        prompts.
 810        """
 811        varname = extract(context, "ref_variable")
 812        value = extract(context, "ref_value")
 813
 814        # format value's repr using wrapped_repr, but leaving room for
 815        # varname = at beginning of first line
 816        rep = wrapped_with_prefix(value, varname + ' = ')
 817
 818        # Use pygments to generate HTML markup for our assignment
 819        markup = highlight_code(rep)
 820        return (
 821            '<span class="prompt input">In []:</span>'
 822            '<div class="snippet-input">{}</div>\n'
 823        ).format(markup)
 824
 825
 826class RunModule(Snippet):
 827    """
 828    A snippet which shows the output produced by running a module.
 829    Functions like `potluck.specifications.HasPayload.provide_inputs`
 830    can be used to control exactly what happens.
 831
 832    The module to import is specified by the currently active file
 833    context (see `potluck.contexts.FileContext`).
 834    """
 835    def __init__(self, sid, title, caption, postscript=''):
 836        """
 837        A snippet ID, title, and caption are required.
 838
 839        A postscript is optional (see `Snippet`).
 840        """
 841        cases = [ specifications.TestImport(register=False) ]
 842        super().__init__(sid, title, caption, cases, postscript)
 843
 844    def render_context(self, context):
 845        """
 846        Renders a context created for goal evaluation as HTML markup for
 847        running a module. Includes a Jupyter-style prompt with %run magic
 848        syntax to show which file was run.
 849        """
 850        filename = extract(context, "filename") # Note: no ref_ here
 851        captured = context.get("ref_output", '')
 852        captured_errs = context.get("ref_error_log", '')
 853
 854        # Wrap faked inputs with spans so we can color them blue
 855        captured = re.sub(
 856            harness.FAKE_INPUT_PATTERN,
 857            r'<span class="input">\1</span>',
 858            captured
 859        )
 860
 861        result = (
 862            '<span class="prompt input">In []:</span>'
 863            '<div class="snippet-input">'
 864            '<code class="magic">%run {filename}</code>'
 865            '</div>\n'
 866        ).format(filename=filename)
 867        if captured:
 868            result += (
 869                '<span class="prompt printed">Prints</span>'
 870                '<div class="snippet-printed">{captured}</div>\n'
 871            ).format(captured=captured)
 872        if captured_errs:
 873            result += (
 874                '<span class="prompt stderr">Logs</span>'
 875                '<div class="snippet-stderr">{log}</div>\n'
 876            ).format(log=captured_errs)
 877
 878        return result
 879
 880
 881class FunctionCalls(Snippet):
 882    """
 883    A snippet which shows the results (printed output and return values)
 884    of calling one or more functions. To control what happens in detail,
 885    use specialization methods from `potluck.specifications.HasPayload`
 886    and `potluck.specifications.HasContext`.
 887    """
 888    def __init__(self, sid, title, caption, calls, postscript=''):
 889        """
 890        A snippet ID, title, and caption are required, along with a list
 891        of function calls. Each entry in the list must be a tuple
 892        containing a function name followed by a tuple of arguments,
 893        and optionally, a dictionary of keyword arguments.
 894
 895        A postscript is optional (see `Snippet`).
 896        """
 897        cases = [
 898            specifications.TestCase(
 899                fname,
 900                args,
 901                kwargs or {},
 902                register=False
 903            )
 904            for fname, args, kwargs in (
 905                map(lambda case: (case + (None,))[:3], calls)
 906            )
 907        ]
 908        super().__init__(sid, title, caption, cases, postscript)
 909
 910    def render_context(self, context):
 911        """
 912        Renders a context created for goal evaluation as HTML markup for
 913        calling a function. Includes a Jupyter-style prompt for input as
 914        well as the return value.
 915        """
 916        if "ref_error" in context:
 917            print(
 918                "Error during context creation:"
 919              + context["ref_error"]
 920              + "\nFull log is:\n"
 921              + context.get("ref_error_log", '<missing>')
 922            )
 923        fname = extract(context, "ref_function")
 924        value = extract(context, "ref_value")
 925        args = extract(context, "ref_args")
 926        kwargs = extract(context, "ref_kwargs")
 927        captured = context.get("ref_output", '')
 928        captured_errs = context.get("ref_error_log", '')
 929
 930        # Figure out representations of each argument
 931        argreps = []
 932        for arg in args:
 933            argreps.append(wrapped_with_prefix(arg, '', 1))
 934
 935        for kw in kwargs:
 936            argreps.append(wrapped_with_prefix(kwargs[kw], kw + "=", 1))
 937
 938        # Figure out full function call representation
 939        oneline = "{}({})".format(
 940            fname,
 941            ', '.join(rep.strip() for rep in argreps)
 942        )
 943        if '\n' not in oneline and len(oneline) <= FMT_WIDTH:
 944            callrep = oneline
 945        else:
 946            callrep = "{}(\n{}\n)".format(fname, ',\n'.join(argreps))
 947
 948        # Wrap faked inputs with spans so we can color them blue
 949        captured = re.sub(
 950            harness.FAKE_INPUT_PATTERN,
 951            r'<span class="input">\1</span>',
 952            captured
 953        )
 954
 955        # Highlight the function call
 956        callrep = highlight_code(callrep)
 957
 958        result = (
 959            '<span class="prompt input">In []:</span>'
 960            '<div class="snippet-input">{}</div>'
 961        ).format(callrep)
 962
 963        if captured:
 964            result += (
 965                '<span class="prompt printed">Prints</span>'
 966                '<div class="snippet-printed">{}</div>\n'
 967            ).format(captured)
 968
 969        if captured_errs:
 970            result += (
 971                '<span class="prompt stderr">Logs</span>'
 972                '<div class="snippet-stderr">{log}</div>\n'
 973            ).format(log=captured_errs)
 974
 975        # Highlight the return value
 976        if value is not None:
 977            value = highlight_code(wrapped_with_prefix(value, ""))
 978
 979            result += (
 980                '<span class="prompt output">Out[]:</span>'
 981                '<div class="snippet-output">{}</div>\n'
 982            ).format(value)
 983
 984        return result
 985
 986
 987class Blocks(Snippet):
 988    """
 989    A snippet which shows the results (printed output and result value of
 990    final line) of one or more blocks of statements, just like Jupyter
 991    Notebook cells. To control what happens in detail, use specialization
 992    methods from `potluck.specifications.HasPayload` and
 993    `potluck.specifications.HasContext`.
 994
 995    Note: Any direct side-effects of the blocks (like changing the value
 996    of a variable or defining a function) won't persist in the module
 997    used for evaluation. However, indirect effects (like appending to a
 998    list) will persist, and thus should be avoided because they could
 999    have unpredictable effects on other components of the system such as
1000    evaluation.
1001
1002    Along the same lines, each block of code to demonstrate is executed
1003    independently of the others. You cannot define a variable in one
1004    block and then use it in another (although you could fake this using
1005    the ability to define separate presentation and actual code).
1006    """
1007    def __init__(self, sid, title, caption, blocks, postscript=''):
1008        """
1009        A snippet ID, title, and caption are required, along with a list
1010        of code blocks. Each entry in the list should be either a
1011        multi-line string, or a tuple of two such strings. In the first
1012        case, the string is treated as the code to run, in the second,
1013        the first item in the tuple is the code to display, while the
1014        second is the code to actually run.
1015
1016        A postscript is optional (see `Snippet`).
1017        """
1018        cases = []
1019        for item in blocks:
1020            if isinstance(item, str):
1021                cases.append(
1022                    specifications.TestBlock(
1023                        sid,
1024                        item,
1025                        register=False
1026                    )
1027                )
1028            else:
1029                display, actual = item
1030                cases.append(
1031                    specifications.TestBlock(
1032                        sid,
1033                        display,
1034                        actual,
1035                        register=False
1036                    )
1037                )
1038
1039        super().__init__(sid, title, caption, cases, postscript)
1040
1041    def render_context(self, context):
1042        """
1043        Renders a context created for goal evaluation as HTML markup for
1044        executing a block of code. Includes a Jupyter-style prompt for
1045        input as well as the result value of the last line of the block
1046        as long as that's not None.
1047        """
1048        src = extract(context, "ref_block")
1049        value = extract(context, "ref_value")
1050        captured = context.get("ref_output", '')
1051        captured_errs = context.get("ref_error_log", '')
1052
1053        # Wrap faked inputs with spans so we can color them blue
1054        captured = re.sub(
1055            harness.FAKE_INPUT_PATTERN,
1056            r'<span class="input">\1</span>',
1057            captured
1058        )
1059
1060        # Highlight the code block
1061        blockrep = highlight_code(src)
1062
1063        result = (
1064            '<span class="prompt input">In []:</span>'
1065            '<div class="snippet-input">{}</div>\n'
1066        ).format(blockrep)
1067
1068        if captured:
1069            result += (
1070                '<span class="prompt printed">Prints</span>'
1071                '<div class="snippet-printed">{}</div>\n'
1072            ).format(captured)
1073
1074        if captured_errs:
1075            result += (
1076                '<span class="prompt stderr">Logs</span>'
1077                '<div class="snippet-stderr">{log}</div>\n'
1078            ).format(log=captured_errs)
1079
1080        # Highlight the return value
1081        if value is not None:
1082            value = highlight_code(wrapped_with_prefix(value, ""))
1083
1084            result += (
1085                '<span class="prompt output">Out[]:</span>'
1086                '<div class="snippet-output">{}</div>\n'
1087            ).format(value)
1088
1089        return result
1090
1091
1092class Fakes(Snippet):
1093    """
1094    One or more fake snippets, which format code, printed output, stderr
1095    output, and a result value (and possibly glamer additions) but each
1096    of these things is simply specified ahead of time. Note that you want
1097    to avoid using this if at all possible, because it re-creates the
1098    problems that this module was trying to solve (namely, examples
1099    becoming out-of-sync with the solution code). The specialization
1100    methods of this kind of snippet are ignored and have no effect,
1101    because no code is actually run.
1102    """
1103    def __init__(self, sid, title, caption, fake_contexts, postscript=''):
1104        """
1105        A snippet ID, title, and caption are required, along with a list
1106        of fake context dictionary objects to be rendered as if they came
1107        from a real test. Each dictionary must contain a "code" slot, and
1108        may contain "ref_value", "ref_output", and/or "ref_error_log"
1109        keys. If using glamers, relevant keys should be added directly to
1110        these fake contexts.
1111
1112        If "ref_value" or "ref_output" slots are missing, defaults of
1113        None and '' will be added, since these slots are ultimately
1114        required.
1115
1116        A postscript is optional (see `Snippet`).
1117        """
1118        self.fake_contexts = fake_contexts
1119        for ctx in self.fake_contexts:
1120            if 'code' not in ctx:
1121                raise ValueError(
1122                    "Fake context dictionaries must contain a 'code'"
1123                    " slot."
1124                )
1125            if 'ref_value' not in ctx:
1126                ctx['ref_value'] = None
1127            if 'ref_output' not in ctx:
1128                ctx['ref_output'] = ''
1129        super().__init__(sid, title, caption, [], postscript)
1130
1131    def create_goal(self):
1132        """
1133        We override TestGroup.create_goal to just create a dummy goal
1134        which depends on dummy contexts.
1135        """
1136        ctx_list = []
1137        for fake in self.fake_contexts:
1138            def make_builder():
1139                """
1140                We need to capture 'fake' on each iteration of the loop,
1141                which is why this extra layer of indirection is added.
1142                """
1143                nonlocal fake
1144                return lambda _: fake
1145            ctx_list.append(contexts.Context(builder=make_builder()))
1146
1147        return rubrics.NoteGoal(
1148            self.taskid,
1149            "fakeSnippetGoal:" + self.base_name,
1150            (
1151                "NoteGoal for fake snippet '{}'.".format(self.base_name),
1152                "A fake NoteGoal."
1153            ),
1154            test_in={ "contexts": ctx_list }
1155        )
1156
1157    def render_context(self, context):
1158        """
1159        Renders a context created for goal evaluation as HTML markup for
1160        executing a block of code. Includes a Jupyter-style prompt for
1161        input as well as the result value of the last line of the block
1162        as long as that's not None.
1163        """
1164        src = extract(context, "code")
1165        value = extract(context, "ref_value")
1166        captured = context.get("ref_output", '')
1167        captured_errs = context.get("ref_error_log", '')
1168
1169        # Wrap faked inputs with spans so we can color them blue
1170        captured = re.sub(
1171            harness.FAKE_INPUT_PATTERN,
1172            r'<span class="input">\1</span>',
1173            captured
1174        )
1175
1176        # Highlight the code block
1177        blockrep = highlight_code(src)
1178
1179        result = (
1180            '<span class="prompt input">In []:</span>'
1181            '<div class="snippet-input">{}</div>\n'
1182        ).format(blockrep)
1183
1184        if captured:
1185            result += (
1186                '<span class="prompt printed">Prints</span>'
1187                '<div class="snippet-printed">{}</div>\n'
1188            ).format(captured)
1189
1190        if captured_errs:
1191            result += (
1192                '<span class="prompt stderr">Logs</span>'
1193                '<div class="snippet-stderr">{log}</div>\n'
1194            ).format(log=captured_errs)
1195
1196        # Highlight the return value
1197        if value is not None:
1198            value = highlight_code(wrapped_with_prefix(value, ""))
1199
1200            result += (
1201                '<span class="prompt output">Out[]:</span>'
1202                '<div class="snippet-output">{}</div>\n'
1203            ).format(value)
1204
1205        return result
1206
1207
1208class Files(Snippet):
1209    """
1210    A snippet which shows the contents of one or more files, without
1211    running any code, in the same Jupyter-like format that file contents
1212    are shown when `Snippet.show_file_contents` is used. Most
1213    specialization methods don't work properly on this kind of snippet.
1214
1215    By default, file paths are interpreted as relative to the solutions
1216    directory, but specifying a different base directory via the
1217    constructor can change that.
1218    """
1219    def __init__(
1220        self,
1221        sid,
1222        title,
1223        caption,
1224        filepaths,
1225        base='__soln__',
1226        postscript=''
1227    ):
1228        """
1229        A snippet ID, title, and caption are required, along with a list
1230        of file paths. Each entry in the list should be a string path to
1231        a starter file relative to the starter directory. The versions of
1232        files in the solution directory will be used. But only files
1233        present in both starter and solution directories will be
1234        available.
1235
1236        If `base` is specified, it should be either '__soln__' (the
1237        default), '__starter__', or a path string. If it's __soln__ paths
1238        will be interpreted relative to the solution directory; if it's
1239        __starter__ they'll be interpreted relative to the starter
1240        directory, and for any other path, paths are interpreted relative
1241        to that directory. In any case, absolute paths will not be
1242        modified.
1243
1244        A postscript is optional (see `Snippet`).
1245        """
1246        if base == "__soln__":
1247            base = file_utils.current_solution_path()
1248        elif base == "__starter__":
1249            base = file_utils.current_starter_path()
1250        # else leave base as-is
1251
1252        self.filepaths = {
1253            path: os.path.join(base, path)
1254            for path in filepaths
1255        }
1256
1257        super().__init__(sid, title, caption, [], postscript)
1258
1259    def create_goal(self):
1260        """
1261        We override TestGroup.create_goal to just create a dummy goal
1262        which depends on dummy contexts.
1263        """
1264        ctx_list = []
1265        for showpath in self.filepaths:
1266            filepath = self.filepaths[showpath]
1267            with open(filepath, 'r', encoding="utf-8") as fileInput:
1268                contents = fileInput.read()
1269
1270            def make_builder():
1271                """
1272                We need to capture 'filepath' on each iteration of the
1273                loop, which is why this extra layer of indirection is
1274                added.
1275                """
1276                nonlocal showpath, filepath, contents
1277                sp = showpath
1278                fp = filepath
1279                ct = contents
1280                return lambda _: {
1281                    "path": sp,
1282                    "real_path": fp,
1283                    "contents": ct
1284                }
1285
1286            ctx_list.append(contexts.Context(builder=make_builder()))
1287
1288        return rubrics.NoteGoal(
1289            self.taskid,
1290            "fileSnippetGoal:" + self.base_name,
1291            (
1292                "NoteGoal for file snippet '{}'.".format(self.base_name),
1293                "A file-displaying NoteGoal."
1294            ),
1295            test_in={ "contexts": ctx_list }
1296        )
1297
1298    def render_context(self, context):
1299        """
1300        Renders a context with just file information as HTML markup for
1301        displaying a file with %more magic. Includes a Jupyter-style
1302        prompt for input as well as the contents of the file.
1303        """
1304        path = extract(context, "path")
1305        contents = extract(context, "contents")
1306
1307        result = (
1308            '<span class="prompt input">In []:</span>'
1309            '<div class="snippet-input">'
1310            '<code class="magic">%more {filename}</code>'
1311            '</div>\n'
1312            '<span class="prompt special">File</span>'
1313            '<div class="snippet-filename">{filename}</div>\n'
1314            '<div class="snippet-file-contents">{contents}</div>\n'
1315        ).format(filename=path, contents=contents)
1316
1317        return result
1318
1319
1320#---------#
1321# Glamers #
1322#---------#
1323
1324def append_image_result(markup, context):
1325    """
1326    Given some HTML markup and a context dictionary, turns the
1327    "ref_image" context slot into an HTML img tag and returns the given
1328    markup with that appended, prefixed by an "Image " prompt. If the
1329    context has no "image" value, the original markup is returned
1330    unmodified.
1331
1332    The "ref_image_alt" slot of the context is used as alt text for the
1333    image, with the "ref_output" slot being used as backup (under a
1334    hopeful assumption about turtleBeads being imported for printed
1335    descriptions). If neither is present, "no alt text available" will be
1336    used.
1337    """
1338    # Short-circuit unless we've got an image
1339    if "ref_image" not in context:
1340        return markup
1341
1342    image = extract(context, "ref_image")
1343    alt = context.get(
1344        "ref_image_alt",
1345        context.get("ref_output", "no alt text available")
1346    )
1347
1348    img_tag = html_tools.html_image(image, alt, ["example"])
1349    return (
1350        markup
1351      + '<span class="prompt special">Image </span>'
1352      + img_tag
1353    )
1354
1355
1356def append_audio_result(markup, context):
1357    """
1358    Given some HTML markup and a context dictionary, turns the
1359    "ref_audio" context slot into an HTML audio tag and returns the given
1360    markup with that appended, prefixed by an "Audio " prompt.
1361
1362    Note that this can result in a pretty large string if the WAV format
1363    is used, since the string needs to be base64-encoded and WAV is
1364    uncompressed (and we double the size by including the data URL twice)
1365    :(
1366
1367    TODO: Maybe use Ogg/Vorbis?
1368
1369    If there is no "ref_audio" context slot, the given markup is returned
1370    unmodified.
1371
1372    The "ref_audio" context value must be a dictionary with at least
1373    "mimetype" and "data" slots containing the MIME type for the data and
1374    the data itself (as a bytes object). It may also include a "label"
1375    slot which will be used invisibly as an aria-label property of the
1376    audio element; if absent no aria-label will be attached.
1377    """
1378    # Short-circuit unless we've got audio
1379    if "ref_audio" not in context:
1380        return markup
1381
1382    audio = extract(context, "ref_audio")
1383    mime = audio["mimetype"]
1384    data = audio["data"]
1385    label = audio.get("label")
1386
1387    audio_tag = html_tools.html_audio(data, mime, label)
1388    return (
1389        markup
1390      + '\n<span class="prompt special">Audio </span>'
1391      + audio_tag
1392    )
1393
1394
1395def append_memory_report(markup, context):
1396    """
1397    Given some HTML markup and a context dictionary, creates a memory
1398    report showing the structure of the object in the "ref_value" context
1399    slot, and appends that to the markup, using a 'Memory Report' tag.
1400    """
1401    # Do nothing if no ref_value is available
1402    if "ref_value" not in context:
1403        return markup
1404
1405    obj = extract(context, "ref_value")
1406
1407    report = html_tools.escape(specifications.memory_report(obj))
1408    formatted = "<pre>{report}</pre>".format(report=report)
1409    return (
1410        markup
1411      + '\n<span class="prompt special">Memory\nReport</span>'
1412      + formatted
1413    )
1414
1415
1416def append_file_contents(markup, context):
1417    """
1418    Given some HTML markup and a context dictionary, turns the
1419    "ref_output_filename" and "ref_output_file_contents" context slots
1420    into HTML markup displaying the contents of that file, which gets
1421    appended to the given markup and returned.
1422
1423    Note that this is intended to display the contents of text files.
1424
1425    If either of the "ref_output_filename" or "ref_output_file_contents"
1426    context slots are missing, the given markup is returned unmodified.
1427    """
1428    # Short-circuit unless we've got output file contents
1429    if (
1430        "ref_output_filename" not in context
1431     or "ref_output_file_contents" not in context
1432    ):
1433        return markup
1434
1435    filename = extract(context, "ref_output_filename")
1436    contents = extract(context, "ref_output_file_contents")
1437
1438    return (
1439        markup
1440      + (
1441            '\n<span class="prompt special">File</span>'
1442        )
1443      + '<div class="snippet-filename">{}</div>\n'.format(filename)
1444      + '<div class="snippet-file-contents">{}</div>\n'.format(contents)
1445    )
1446
1447
1448#--------#
1449# Lookup #
1450#--------#
1451
1452def list_snippets(task_info):
1453    """
1454    Returns a list containing all snippet IDs (strings) for the given
1455    task (as a task info dictionary).
1456    """
1457    reg = SNIPPET_REGISTRY.get(task_info["specification"].__name__, {})
1458    return list(reg.keys())
1459
1460
1461def get_html(task_info, sid):
1462    """
1463    Retrieves the HTML code (a string) for the snippet with the given ID
1464    in the given task (as a task info dictionary). Returns None if there
1465    is no such snippet.
1466    """
1467    reg = SNIPPET_REGISTRY.get(task_info["specification"].__name__, {})
1468    if sid not in reg:
1469        return None
1470    return reg[sid].get_html(task_info)
1471
1472
1473def get_all_snippets(task_info):
1474    """
1475    Returns a list of HTML strings containing each registered snippet for
1476    the given (as a task_info dictionary) task.
1477    """
1478    return [
1479        get_html(task_info, sid)
1480        for sid in list_snippets(task_info)
1481    ]