codesnipper 0.0.2

A lightweight framework for censoring student solutions files and extracting code + output

Snipper

A lightweight framework for removing code from student solutions.

Installation

pip install codesnipper

What it does

This project address the following three challenges for administering a python-based course

• You need to maintain a (working) version for debugging as well as a version handed out to students (with code missing)
• You ideally want to make references in source code to course material "(see equation 2.1 in exercise 5)" but these tend to go out of date
• You want to include code snippets and code output in lectures notes/exercises/beamer slides
• You want to automatically create student solutions

This framework address these problems and allow you to maintain a single, working project repository.

The project is currently used in 02465 at DTU. An example of student code can be found at:

• https://gitlab.gbar.dtu.dk/02465material/02465students/blob/master/irlc/ex02/dp.py

A set of lectures notes where all code examples/output are automatically generated from the working repository can be found a

• https://lab.compute.dtu.dk/tuhe/books (see Sequential decision making)

How it works

The basic functionality is quite simple. You start with your working script in your private repository and add special tags to the script. In this case I have added the tags #!b (cut a block) and #!f (cut function scope).

def myfun(): #!f The error I am going to raise
    """ The function docstring will not be removed"""
    print("This is a function")
    return 42
    
def a_long_function():
    a = 234
    print("a line")
    print("a line") #!b
    print("a line")
    print("a line") #!b Insert three missing print statements. 
    print("a line")
    return a
    
if __name__ == "__main__":
    myfun()

This will produce the following file:

def myfun():
    """ The function docstring will not be removed"""
    # TODO: 2 lines missing.
    raise NotImplementedError("The error I am going to raise")
    
def a_long_function():
    a = 234
    print("a line")
    # TODO: 3 lines missing.
    raise NotImplementedError("Insert three missing print statements.")
    print("a line")
    return a
    
if __name__ == "__main__":
    myfun()

You can also use the framework to capture code snippets, outputs and interactive python output. To do this, save the following in foo.py

def myfun(): #!s This snippet will be saved to foo.py in the output directory. 
    print("Hello") #!s 

print("Do not capture me") 
for i in range(4): #!o
    print("Output", i)
print("Goodbuy world") #!o
print("don't capture me")

# Interactive pythong example
print("Hello World") #!i #!i # this is a single-line cutout.

These block-tags will create a file foo.py (in the output directory) containing

def myfun():
    print("Hello") 

A file foo.txt containing the captured output

Output 0
Output 1
Output 2
Output 3
Goodbuy world

and a typeset version of an interactive python session in foo.pyi (use pycon in minted; this gitlab server appears not to support pycon)

>>> print("hello world")
Hello World"

All these files can be directly imported into LaTeX using e.g. minted: You never need to mix LaTeX code and python again!

References:

Bibliography references can be loaded from references.bib-files and in-document references from the .aux file. For this example, we will insert references shown in the examples/latex/index.tex-document. To do so, we can use these tags:

def myfun(): #!s
    """
    To solve this exercise, look at \ref{eq1} in \ref{sec1}.
    You can also look at \cite{bertsekasII} and \cite{herlau}
    More specifically, look at \cite[Equation 117]{bertsekasII} and \cite[\ref{fig1}]{herlau}

    We can also write a special tag to reduce repetition: \nref{fig1} and \nref{sec1}.
    """
    return 42 #!s

We can manually compile this example by first loading the aux-files and the bibliographies as follows:

# load_references.py
    from snipper.citations import get_bibtex, get_aux 
    bibfile = "latex/library.bib"
    auxfile = 'latex/index.aux'
    bibtex = get_bibtex(bibfile)
    aux = get_aux(auxfile) 

Next, we load the python file containing the reference code and fix all references based on the aux and bibliography data.

# load_references.py
    file = "citations.py" 
    with open(file, 'r') as f:
        lines = f.read().splitlines()
    lines = fix_aux(lines, aux=aux)
    lines = fix_aux_special(lines, aux=aux, command='\\nref', bibref='herlau')
    lines = fix_bibtex(lines, bibtex=bibtex)
    with open('output/citations.py', 'w') as f:
        f.write("\n".join(lines)) 

The middle command is a convenience feature: It allows us to specify a special citation command \nref{..} which always compiles to \cite[\ref{...}]{herlau}. This is useful if e.g. herlau is the bibtex key for your lecture notes. The result is as follows:

"""
References:
  [Ber07] Dimitri P. Bertsekas. Dynamic Programming and Optimal Control, Vol. II. Athena Scientific, 3rd edition, 2007. ISBN 1886529302.
  [Her21] Tue Herlau. Sequential decision making. (See 02465_Notes.pdf), 2021.
"""
def myfun(): #!s
    """
    To solve this exercise, look at eq. (1) in Section 1.
    You can also look at (Ber07) and (Her21)
    More specifically, look at (Ber07, Equation 117) and (Her21, Figure 1)

    We can also write a special tag to reduce repetition: (Her21, Figure 1) and (Her21, Section 1).
    """
    return 42 #!s

Note this example uses the low-level api. Normally you would just pass the bibtex and aux-file to the main censor-file command.

Additional features:

• You can name tags using #!s=bar to get a foo_bar.py snippet. This is useful when you need to cut multiple sessions. This also works for the other tags.