# Battleships Server / Client for Education

I’ve been teaching a first year introductory module in Python programming for Engineering at Ulster University for a few years now. As part of the later labs I have let the students build a battleships game using Object Oriented Programming – with “Fleet” objects containing a list of “Ships” and so on where they could play on one computer against themselves. But I had often wanted to see if I could get as far as an on-line server application based on similar principles that the students could use. This would teach them client server fundamentals but also let them have fun playing against each other.

Last year I finally attained that goal. I built a very simple web-server using Python Django to manage players, games, and ships. I wanted to use Python partly because it’s become my language of choice for web applications, but also because I wanted the code to be as accessible and understandable to the students as possible. I have initially placed very little emphasis on the User Interface of the server – this is partly deliberate because I wanted the students to have a strong incentive to develop this in the clients. I did however build a very simple admin view to let me see the games in progress. Additionally Django provides a very easy way to build admin views to manipulate objects. I have enabled this to let admins (well me) tweak data if I need to.

## The Server

The server provides a very simple interface – an API – to let the students interact with the game. They can do this initially very directly using a web browser. They can simply type in specific web addresses to take certain actions. For instance

http://battleships.server.net/api/1.0/games/index/

will, for a battleships server installed on battleships.server.net (not a real server), list all the current active games. You’ll note the api/1.0/ part of the URL. I did this so that in future years I could change the API and add new version numbers. That’s partly the focus of a later section of this blog.

The output of all the API calls is actually encoded in JSON. This is still fairly human readable, and indeed some web browsers, like Firefox, will render this in a way that is easy to explore. Again, this makes it possible for the students to play the game with nothing more than a web browser and a certain amount of patience. This is good for exploration, but certainly not the easiest way to play. Here’s some sample output from my real games server with my students (poor Brian).

The code for the server and documentation about the API is all publicly available on my GitHub repository. You’ll also find some basic installation instructions in case you’d like to run your own game server.

I did want to build some very basic views into the server, I built a more human version of the games list, and I also built this view which was designed only for admins – obviously in the hands of normal players it would make the game a bit pointless.

This allowed me to see a little of what was actually going on in the games my students were playing, as well as showing the current state of ships and who owns what, it also showed a bit more info – here for another game than that above:

As you can see this shows some of the history of the game so far – this information is available to clients in the API, and likewise the list of surviving ships are shown. The API call for the ships still surviving only shows the ships for the player making the call, with a secret (password) that was generated when the player was created.

You may notice that the server automatically names ships with names taken from the Culture novels from Iain M. Banks.

## The Client(s)

In this way the students are using their web browsers as a highly unsophisticated client to access the server. Actually playing the game this way will be frustrating – requiring careful URLs to be typed every time and noting the output for further commands. This is quite deliberate. It would be easy to build the web server to allow the whole game to be played seamlessly from a web browser – but this isn’t the point – I want the students to experience building a client themselves and developing that.

For my module last year I gave the students a partially complete client, written in Python, using text only. Their aim for the lab was to complete the client. No client would be exactly the same, but they would all be written to work against the same server specification. In theory a better client will give a player an edge against others – a motivation for improvements. One student built the start of a graphical interface, some needed to be given more working pieces to complete their clients.

I’ve placed a more or less complete client on GitHub as well, but it could certainly do with a number of improvements. I may not make those since the idea of the project is to provide a focus for students to make these improvements.

## What Went Well

The server worked reasonably well, and once I got going the code for automatic ship generation and placement worked quite nicely. I built a good number of unit tests for this which flushed out some problems, and which again are intended as a useful teaching resource.

I spent a reasonable amount of time building a server API that couldn’t be too easily exploited. For instance, it’s not possible for any player to be more than one move ahead of another to prevent brute force attacks by a client.

The server makes it relatively easy for as many players as one wants in a given game.

## What Went Wrong

I made some missteps the first time around the block.

• the game grid’s default size is too large – I made this configurable, but too large a grid makes the chances of quick hits much more remote – which the students need for motivation. I only really noticed this when I built my admin view shown above.
• in the initial game, any hit on a ship destroys it, there is no concept of health, and bigger ships are more vulnerable. This is arguably not a mistake, but is a deviation from expected behaviour.

## What’s Next

This year I may add another version of the API that adds health to ships so that multiple hits are needed for large ships. By moving all of this to a new version number in the URL as above, e.g.

http://battleships.server.net/api/2.0/games/index/

I hope to allow for improved versions of the game while still supporting (within reason) older clients accessing the original version.

I might also add admin calls to tweak the number of ships per player and size of the ships. There are defaults in the code, but these can easily be overriden.

## Shall We Play A Game?

There’s absolutely no reason the clients need to be written in Python. There’s no reason not to write one in C++ or Java, or to build a client that runs on Android or iOS phones. There’s no reason that first year classes with a text mode Python client can’t play against final year students using an Android client.

If you are teaching in any of these languages and feel like writing new clients against the server please do. If you feel like making your clients open source to help more students (and lecturers) learn more, that would be super too.

If you have some improvements in mind for the server, do feel free to fork it, or put in pull requests.

If you or your class do have a go at this, I’d love to hear from you.

# Anatomy of a Puzzle

Recently I was asked to provide a Puzzle For Today for the BBC Radio 4 Today programme which was partially coming as an Outside Broadcast from Ulster University.

I’ve written a post about the puzzle itself, and some of the ramifications of it; this post is really more about the thought process that went into constructing it.

When I was first asked to do this I had a look at the #PuzzleForToday hashtag on Twitter and found that a lot of people found the puzzles pretty hard, so I thought I might try to construct a two part puzzle with one part being relatively easy and the other a bit harder. I also wanted something relatively easy to remember and work out in your head for those people driving, since commuters probably make up a lot of the Today programme audience.

A lot of my students will know I often do puzzles with them in class, but most are quite visual, or are really very classic puzzles, so I needed something else. Trying to find something topical I thought about setting a puzzle around a possible second referendum election, since this was much in the news at the time. My first go at this was coming up with a scenario about an election count, and different ballot counters with different speeds counting a lot of ballots.

I constructed an idea that a Returning Officer had a ballot with a team of people to count votes. One of the team could count all the votes in two hours, the next in four hours, and the next in eight hours. But how long would they take if they worked all together? The second part would be: if there were more counters available but each took twice as long again as the one before, what was the least possible time to complete the task.

I liked this idea because I thought there were a lot of formal and informal ways to get to the answer, and indeed the answers I saw on Twitter and Facebook confirmed this. Perhaps the easiest way to approach the puzzle is this: to consider how much work each can do in an hour. We see the first person gets half of it done, the next one quarter and the next one eighth. All together then:

We need to work out what number we would multiply by this to get one – i.e. the whole job being done. In this case it works out as

which works out (a bit imprecisely) with a bit of work, or a decent calculator, as one hour, eight minutes and thirty four seconds and a bit. So, not great, but the second part of the puzzle works out much more smoothly. If we keep on with out pattern, we get

Formally, this is called a Geometric Progression, there is a constant factor between each terms. Sometimes these infinite sums actually have a finite answer, which might be surprising. If you keep adding these fractions you might see that are adding ever closer to 1. Therefore this potentially infinite number of counters gets the work done in one hour, it can’t be less.

So, I was happy the second number worked out nicely, but the first is pretty tricky, and not easily worked out in one’s head. So I wondered what numbers I could use instead that would work out as an exact number of minutes. This really means that my three fractions from the first part of the problem, divide perfectly into 60. I used some Python to help me with this with a list comprehension:

# Establish a top size to work with n = 100
# Find all the triples where# a,b,c <= n and 1/a + 1/b + 1/c
# divides evenly into 60

triples = [(a,b,c) for a in range(1,n+1)
for b in range(1,a)
for c in range(1,b)
if (60/(1/a + 1/b + 1/c)).is_integer()]

It turns out that restricting ourselves to three numbers for the first quiz all of which are under 100 that there are 902 such sets of numbers. The very smallest numbers are 1, 2 and 6. The problem is that most of these triples don’t have the property of my original choices – which that there is a common number multiplied between the first and second, and the second and third etc.. That would make the second part of the puzzle more difficult.

So, I modified my list comprehension a bit to add the condition that there was a common ratio from a to b to c:

# Establish a top size to work with
n = 100

# Find all the triples where a,b,c <= n and 1/a + 1/b + 1/c
# divides evenly into 60 and where the factor between a and b,
# is the same as that between b and c

geometric_triples = [(a,b,c) for a in range(1,n+1)
for b in range(1,a)
for c in range(1,b)
if (60/(1/a + 1/b + 1/c)).is_integer()
and a/b == b/c]



This produced just three triples (with all numbers under 100):

>>> geometric_triples
[(28, 14, 7), (56, 28, 14), (84, 42, 21)]


and you can see these are all quite related. So I grabbed the first three numbers to try and keep the puzzle small.

As well as that, the programme team wanted a different focus than an election – they were a bit worried that because it was in the news so much it would be better to have another focus. I considered a computational task divided between processors, but eventually concluded this wouldn’t make a lot of sense to some listeners, so I went with this final configuration of the puzzle.

Part One

A Professor gives her team of three PhD students many calculations to perform. The first student is the most experienced and can complete the job on her own in 7 hours, the next would take 14 hours on his own, and the last would take 28 hours working single handed to complete the task. How long would the task take if they all worked together?

Part Two

If the Professor has more helpers, but which follow the same pattern of numbers to complete the task, what is the absolute minimum time the task can take?

You can probably answer this from the details of the construction above, but if not, you can always cheat here (the BBC programme page) or here.

# Establish a top size to work with n = 100
# Find all the triples where a,b,c <= n and 1/a + 1/b + 1/c
# divides evenly into 60 and where the factor between a and b,
# is the same as that between b and c
geometric_triples = [(a,b,c) for a in range(1,n+1) for b in range(1,a) for c in range(1,b) if (60/(1/a + 1/b + 1/c)).is_integer() and a/b == b/c]

# Implementing configurable work-flow patterns in Python Django

In my previous article, I discussed some of changes I’ve made to my WAM software to handle assessment and work-flow. I thought I’d have a look at this from the technical side for those interested in doing something similar, this is obviously extensible to general workflow management, where you might want to tweak the workflow later without diving into code.

My challenge was to consider how not to hard code a work-flow, but to have something that would be configurable, in my case in a SQL layer because I’m using Python and Django.

I had an idea about the work-flow I wanted, and it looked a bit like this (carefully sketched on my tablet). These nodes are particular states, so this isn’t really a flow chart, as decisions aren’t shown. What is shown is what states can progress to the next ones. But I wanted to be able to change the pattern of nodes in the future, or rather, I wanted users to be able to do this without altering the code. I also wanted to work out who could do what, and who should know about what.

## Understanding States

The first thing I did was to create a State model class, and I guess in my head I was thinking of Markov Models.

class AssessmentState(models.Model):
"""Allows for configurable Assessment Resource Workflow

name            The name of the state
description     More details on the state
actors          The user types who can create this state, CSV field
notify          The user types to notify that the state has been created
initial_state   Can this be an initial state?
next_states     Permissible states to move to from this one
priority        To allow the states to be sorted for presentation to the user

actors and notify should be comma separated lists as in USER_TYPES below.
"""

ANYONE = 'anyone'
COORDINATOR = 'coordinator'
MODERATOR = 'moderator'
EXTERNAL = 'external'
TEAM_MEMBER = 'team_member'
ASSESSMENT_STAFF = 'assessment_staff'

USER_TYPES = (
(ANYONE, 'Any logged in user'),
(COORDINATOR, 'Module coordinator'),
(MODERATOR, 'Module moderator'),
(TEAM_MEMBER, 'Module teaching team member'),
(EXTERNAL, 'External Examiner'),
(ASSESSMENT_STAFF, 'Members of AssessmentStaff'),
('exams_office', 'Exams Office')
)

name = models.CharField(max_length=200)
description = models.TextField()
actors = models.TextField()
notify = models.TextField()
initial_state = models.BooleanField(default = False)
next_states = models.ManyToManyField('self', blank=True, symmetrical=False, related_name='children')
priority = models.IntegerField()

As you can see, I created variables that told me the name of the state, and an opportunity for a more detailed description. I then wanted to be able to specify who could do certain things, and be notified. So, rather than a long series of Booleans, I want for a text field – the work-flow won’t be edited very often, and when it is, it should be by someone who knows what they are doing. So it’s just a Comma Separated text field. For instance.

coordinator,moderator

will indicate that the Module Coordinator and Moderator should be involved (this is an HE example, but the principle is quite extensible).

So the actors field will specify which kinds of people can invoke this state, and the notify field those who should get to hear about it.

I want to draw your attention to this bit:

next_states = models.ManyToManyField('self', blank=True, symmetrical=False, related_name='children')

What on earth does this do? It allows a Django model to have a Many to Many relationship with itself. In other words, for me to associate a number of states with this one. Please also note that presence of

symmetrical=False

This is most easily explained by comparison to the Facebook and Twitter friendship model. Both of these essentially link a User model in a many to many relationship with itself.

Facebook friends are symmetrical, once the link is established, it is two way. Twitter followers are not symmetrical.

I wanted to establish which successor states could be invoked from any given one. And this should not be symmetrical by default. You can see in my example graph above, I want it to be possible to move from state A to either B or C, but this is not entirely symmetric, it is possible to move from B to A, but it should not be possible to go from C to A. Without symmetric=False, each link will create an implied link back (all arrows in my state diagram would be bi-directional) which would be problematic. By establishing the relationship as asymmetric we can allow a reciprocal link (as is possible in Twitter, and our A and B example), but we don’t enforce it, so that we prevent back tracking in work-flow where it should not be allowed (as in our A and C example).

## Invoking States

I then created another model to keep track of which states were invoked.

class AssessmentStateSignOff(models.Model):
"""Marks a particular sign off of an AssessmentState for a module

module              The module being signed off
assessment_state    The AssessmentState being used
signed_by           The user signing off (Could be Staff or Examiner)
created             The datestamp for signoff
notified            The datestamp for notificiations sent
"""

notified = models.DateTimeField(null=True, blank=True)
notes = models.TextField()

def __str__(self):
return str (self.assessment_state)

This model allows me to work out who (the signed_by field) invoked a particular AssessmentState, when, and with any particular notes.

I also added a field to record when a notification (notified) had been sent. On creation, I leave that field as null. One of the many glorious things about Django is that it’s infrastructure for custom management commands allows you to easily build command line tools for doing cron tasks while your web front end runs without interruption. I found this rather awkward, but not impossible, in PHP, but in Django the whole thing is very organic, and you get access to all your models. If you have pushed plenty of your logic into the Model layer and not the View layer, this can really help.

In my new custom commend I can easily work out which signoffs have not been notified yet:

# Get all sign offs with no notification time
signoffs = AssessmentStateSignOff.objects.all().filter(notified=None).order_by("created")

I can then act upon those, send notifications, and if that’s successful, set the notified field to the time at which I sent them.

In this article I have concentrated on the Model layer, with a few other observations, and in particular the relationship from a State model to itself.

All of the Forms and Views are available within my GitHub repository for the project. They aren’t a work of art, but if you have any questions feel free to look there, or get in touch.

I hope that might be helpful to someone facing the same challenge, and do feel free to suggest how I could have solved the problem more elegantly.

# Assessment handling and Assessment Workflow in WAM

As is often the way, the scope of the project broadened and I found myself writing in support for handling assessments and the QA processes around them. At some point this necessitates a new name for WAM to something more general (answers on a post card please) but for now, development continues.

Last year I added features to allow Exams, Coursework, and their Moderation and QA documents to be uploaded to WAM. This was generally reasonably successful, but a bit clunky. We gave several External Examiners access to the system and they were able to look in at the modules for which they were an examiner and the feedback was pretty good.

## What Worked

One of the things that worked best about last year’s experiment was that we put in information about the Programmes (Courses) each Module was on. It’s not at all unusual for many Programmes to have the same Module within them.

This can cause a headache for External Examination since an External Examiner is normally assigned to a Programme. In short, the same Module can end up being looked at by several Examiners. While this is OK, it can be wasteful of work, and creates potential problems when two Examiners have a different perspective on the Module.

So within WAM, I put in code an assumption of what we should be doing in paper based systems – that every Module should have a “Lead Programme”. The examiner for that Programme should be the one that has primacy, and furthermore, where they are presented other Modules on the Programme for which they aren’t the “lead” Examiner, they should know that this is for information, and they may not be required to delve into it in so much detail – unless they choose to.

This aspect worked well, and the External Examiners have a landing screen that shows which Modules they are examining, and which they are the lead Examiner.

## What Didn’t Work

I had written code that was intended to look at what assessment artefacts had been uploaded since a last user’s login, and email them the relevant stuff.

This turned out to be problematic, partly because one had to unpick who should get what, but mostly because I’m using remote authentication with Django (the Python framework in which WAM is written), and it seems that the last login time isn’t always updated properly when you aren’t using Django’s built in authentication.

But the biggest problem was a lack of any workflow. This was a bit deliberate since I didn’t want to hardcode my School or Faculty’s workflow.

You should never design your software product for HE around your own University too tightly. Because your own University will be a different University in two years’ time.

So, I wanted to ponder this a bit. It made visibility of what was going on a little difficult. It looked a bit like this (not exactly, as this is a screenshot from a newer version of an older module):

with items shown from oldest at the bottom to newest at the top. You can kind of infer the workflow state by the top item, and indeed, I used that in the module list.

But staff uploaded files they wanted to delete (and that was previously disallowed for audit reasons) and the workflow wasn’t too clear and that made notifications more difficult.

## What’s New

So, in a beta version of 2.0 of the software I have implemented a workflow model. I did this by:

• defining a model that represented the potential states a Module could be in, each state defines who can trigger it, and what can happen next, and who should be notified;
• defining a model that shows a “sign off” event.

Once it became possible to issue a “sign off” of where we were in the workflow, a lot of things became easier. This screenshot shows how it looks now.

Ok, it’s a bit of a dumb example, since I’m the only user triggering states here (and I can only do that in some cases since I’m a Superuser, otherwise some states can only be triggered by the correct stakeholder – the moderator of examiner).

However, you can see that now we can still have all the assessment resources, but with sign offs at various stages. The sign off could (and likely would) have much more detailed notes in a real implementation.

This in turn has made notification emails much easier to create. Here is the email triggered by the final sign off above.

The detailed notes aren’t shown in the email, in case other eyes are on it and there are sensitive comments.

All of this code is available at GitHub. It’s working now, but I’m probably do a few more bits before an official 2.0 release.

I will be demoing the system at the Royal Academy of Engineering in London next Monday, although that will focus entirely on WAM’s workload features.

# Migrating Django Migrations to Django 2.x

Django is a Python framework for making web applications, and its impressive in its completeness, flexibility and power for speedy prototyping.

It’s also an impressive project for forward planning, it has a kind of built in “lint” functionality that warns about deprecated code that will be disallowed in future versions.

As a result when Django 2.0 was released I didn’t have to make many changes to my app code base to get it to work successfully. However, today when I tried to update my oldest Django App (started in Django 1.8x) I hit an unexpected snag. The old migrations were sometimes invalid. Curiously I don’t think this problem emerged the last time I tried.

Django uses migrations to move the database schema from one version to the next. Most of the time it’s a wonderful system. In the rare case it goes wrong it can be … tricky. Today’s problem is quite specific, and easier to fix.

Django 2.0 enforces that ForeignKey fields explicitly specify a behaviour to follow on deletion of the object pointed to by the key. In general whether we Cascade the deletion, or set the field to Null, getting the behaviour write can be important, particular on fields where a Null value has a legitimate meaning.

But a bit of a sting in the tail is that an older Django project may have migrations created automatically by Django which don’t obey this. I discovered this today and found I couldn’t proceed with my project unless I went back and modified the old migrations to be 2.0 compliant.

So if this happens to you, here are some suggestions on fixing the problem.

You will know if you have a problem if when you try to run your test server, or indeed replace runserver by check

python3 manage.py runserver

you get an error and output like this

  File "/Users/colin/Development/WAM/WAM/loads/migrations/0024_auto_20160627_1049.py", line 7, in <module>
class Migration(migrations.Migration):
File "/Users/colin/Development/WAM/WAM/loads/migrations/0024_auto_20160627_1049.py", line 100, in Migration
TypeError: __init__() missing 1 required positional argument: 'on_delete'


I would suggest you try runserver whatever you did before as it will continue to try each time you save a file.

Open your code with your favourite editor, and open your models.py file (you may have several depending on your project), and the migration file that’s broken as above.

Looking in your migration file you’ll find the offending line. In this case it’s the last (non trivial) line below.

      migrations.AddField(
model_name='activity',
name='activity_set',
),

To ensure that your migrations will be applied consistently with your final model (well, as long as nobody tries to migrate to an intermediate state) look carefully in the correct model (Activity) in this case, and see what decision you make for deletion there. In my case I want deletion of the ActivitySet to kill all linked Activitiy(s). So replicate the “on_delete” choice from there.

      migrations.AddField(
model_name='activity',
name='activity_set',
),

Each time you save your new migration file the runserver terminal window will re-run the check, hopefully moving on to the next migration that needs to be fixed. Work your way through methodically until your code checks clean. Check into source control, and you’re done.

# Semi Open Book Exams

A few years ago, I switched one of my first year courses to use what I call a semi-open-book approach.

Open-book exams of course allow students to bring whatever materials they wish into them, but they have the disadvantage that students will often bring in materials that they have not studied in detail, or even at all. In such cases, sifting through materials to help them answer a question could be counter productive.

On the other hand, the real world is now an increasingly “open-book” environment, which huge amounts of information available to those in the workplace which is now almost always Internet connected.

So I decided to look at another approach. Students are allowed to bring in a single, personalised, A4 sheet, on which they can write whatever they wish on both sides. There are a few rules:

• the sheet must be written on “by hand”, that is to say, it cannot be printed to from a computer, or typed;
• the sheet must be “original”, that is to say, it cannot be a photocopy of another sheet (though students may of course copy their original for reference);
• the sheet must be the student’s own work, and they must formally declare as much (with a tick box);
• the sheet must be handed in with the exam paper, although it is not marked.

The purpose of these restrictions are to ensure that each student takes a lead in producing an individual sheet, and to inhibit cottage industries of copied sheets.

In terms of what can go on the sheet? Well anything really. It can be sections from notes, important formulae, sample questions or solutions. The main purpose here is to prompt students to work out what they would individually distill down to an A4 page. So they go through all the module notes, tutorial problems and more, and work out the most valuable material that deserves to go on one A4 page. I believe that this process itself is the greatest value of the sheet, its production rather than its existence in the exam. I’m working on some research to test this.

So I email them each an A4 PDF, which they can print out at home, and on whatever colour paper they may desire. The sheet is individual and has their student number on it with a barcode, for automated processing and analysis afterwards for a project I’m working on, but this is anonymised. The student’s name in particular does not appear, since in Ulster University, it does not appear on the exam booklet.

The top of my sheet looks like this:

So, if you would like to do the same, I am enclosing the Python script, and LaTeX that I use to achieve this. You could of course use any other technology, or not individualise the sheet at all.

For convenience the most recent code will also be placed on a GitHub repository here, feel free to clone away.

My script has just been rewritten for Python 3.x, and I’ve added a lot of command line parameters to decouple it from me and Ulster University only use. It opens a CSV file from my University which contains student id numbers, student names, and emails in specific columns. These are the default for the script but can be changed. For each student it uses LaTeX to generate the page. It actually creates inserts for each student of the name and student number, you can then edit open-book.tex to allow the page to be as you wish it. You don’t need to know much LaTeX to achieve this, but ping me if you need help. I am also using a LaTeX package to create the barcodes automatically.

I’ve spent a bit of time adding command line parameters to this script, but you can try using

python3 open-book.py --help

for information. The script has been rewritten for Python 3. If you run it without parameters it will enter interactive mode and prompt you.

I’d strongly recommend running with the –test-only option at first to make sure all looks good, and opening open-book.pdf will show you the last generated page so you can see it’s what you want.

Anyway, feel free to do your own thing, or mutilate the code. Enjoy!

#!/usr/bin/env python

#
#
# Free and Open Source Software under GPL v3
#
import argparse

import csv
import re
import subprocess
import smtplib
from email.mime.application import MIMEApplication
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText

def process_student(args, row):
"""Takes a line from the CSV file, you will likely need to edit aspects of this."""
'kicks of the processing of a single student'
student_number = row[args.student_id_column]
student_name = row[args.student_name_column]
student_email = row[args.student_email_column]
print('  Processing:', student_name , ':', student_email)
create_latex_inserts(student_number, student_name)
create_pdf()
send_email(args, student_name, student_email)

def create_latex_inserts(student_number, student_name):
"""Write LaTeX inserts for the barcode and student name

For each student this will create two tiny LaTeX files:

* open-book-insert-barcode.tex which contains the LaTeX code for a barcode representing the student number
* open-book-insert-name.tex which will contain simply the student's name

These files can be included/inputted from open-book.tex as desired to personalise that document

student_number is the ID in the students record system for the student
student_name is the name of the student"""

# Open a tiny LaTeX file to put this in
file = open('open-book-insert-barcode.tex', 'w')

# All the file contains is LaTeX to code to create the bar code
string = '\psbarcode{' + student_number + '}{includetext height=0.25}{code39}'
file.write(string)
file.close()

# The same exercise for the second file to contain the student name
file = open('open-book-insert-name.tex', 'w')
string = student_name
file.write(string)
file.close()

def create_pdf():
"""Calls LaTeX and dvipdf to create the personalised PDF with inserts from create_latex_inserts()"""

# Suppress stdout, but we leave stderr enabled.
subprocess.call("latex open-book", stdout=subprocess.DEVNULL, shell=True)
subprocess.call("dvipdf open-book", stdout=subprocess.DEVNULL, shell=True)

def send_email(args, student_name, student_email):
"""Emails a single student with the generated PDF."""
#TODO: Might be useful to improve the to address
#TODO: Allow subject to be tailored.

subject = args.email_subject
# to_address = student_name + ' <' + student_email + '>'

msg = MIMEMultipart()
msg['Subject'] = subject

text = 'Dear Student\nPlease find enclosed your guide sheet template for the exam. Read the following email carefully.\n'
part1 = MIMEText(text, 'plain')
msg.attach(part1)

# Open the files in binary mode.  Let the MIMEImage class automatically
# guess the specific image type.
fp = open('open-book.pdf', 'rb')
fp.close()

msg.attach(img)

# Send the email via our own SMTP server, if we are not testing.
if not args.test_only:
s = smtplib.SMTP(args.smtp_server)
s.quit()

def override_arguments(args):
"""If necessary, prompt for arguments and override them

Takes, as input, args from an ArgumentParser and returns the same after processing or overrides.
"""

# If the user enabled batch mode, we disable interactive mode
if args.batch_mode:
args.interactive_mode = False

if args.interactive_mode:
override = input("CSV filename? default=[{}] :".format(args.input_file))
if len(override):
args.input_file = override

override = input("Student ID Column? default=[{}] :".format(args.student_id_column))
if len(override):
args.student_id_column = int(override)

override = input("Student Name Column? default=[{}] :".format(args.student_name_column))
if len(override):
args.student_name_column = int(override)

override = input("Student Email Column? default=[{}] :".format(args.student_email_column))
if len(override):
args.student_email_column = int(override)

override = input("Student ID Regular Expression? default=[{}] :".format(args.student_id_regexp))
if len(override):
args.student_id_regexp = override

override = input("SMTP Server? default=[{}] :".format(args.smtp_server))
if len(override):
args.smtp_server = override

override = input("Email subject? default=[{}] :".format(args.email_subject))
if len(override):
args.email_subject = override

override = input("Email sender address? default=[{}] :".format(args.email_sender))
if len(override):
args.email_sender = override

return(args)

def parse_arguments():
"""Get all the command line arguments for the file and return the args from an ArgumentParser"""

parser = argparse.ArgumentParser(
description="A script to email students study pages for a semi-open book exam",
epilog="Note that column count arguments start from zero."

)

action='store_true',
dest='batch_mode',
default=False,
help='run automatically with values given')

action='store_true',
dest='interactive_mode',
default=True,
help='prompt the user for details (default)')

dest='input_file',
default='students.csv',
help='the name of the input CSV file with one row per student')

dest='student_id_column',
default=1,
help='the column containing the student id (default 1)')

dest='student_name_column',
default=2,
help='the column containing the student name (default 2)')

dest='student_email_column',
default=9,
help='the column containing the student email (default 9)')

dest='student_id_regexp',
default='B[0-9]+',
help='a regular expression for valid student IDs (default B[0-9]+)')

dest='smtp_server',
default='localhost',
help='the address of an smtp server')

dest='email_subject',
help='the subject of emails that are sent')

dest='email_sender',
help='the sender address from which to send emails')

action='store_true',
dest='test_only',
default=False,
help='do not send any emails')

args = parser.parse_args()

# Allow for any overrides from program logic or interaction with the user
args = override_arguments(args)
return(args)

def main():
"""the main function that kicks everything else off"""

print("Hello")
args = parse_arguments()

print("Starting open-book...")
print(args)

student_count = 0
# Go through each row
student_number = row[args.student_id_column]
# Check if the second cell looks like a student number
if re.match(args.student_id_regexp, row[args.student_id_column]):
student_count = student_count + 1
process_student(args, row)
else:
print('  Skipping: non matching row')

print('Stopping open-book...')

if __name__ == '__main__':
main()


I use a LaTeX template for the base information, this can be easily edited for taste.

\documentclass[12pt,a4paper]{minimal}
\usepackage[latin1]{inputenc}
\usepackage{pst-barcode}
\usepackage[margin=2cm]{geometry}

%
% Does it all have to be Arial now? <sigh>
%
\renewcommand{\familydefault}{\sfdefault}

\author{Professor Colin Turner}
\begin{document}
\begin{centering}
\textbf{EEE122 Examination Guide Sheet}

This sheet, and its contents that you have added, can be brought into
the examination for EEE122. The contents \textbf{must} be compiled
by yourself, be handwritten, and be original (i.e. \textbf{NOT}
photocopied or similar). You may use the
reverse side. You may retain a copy you have made before the examination
but the original must be handed in with your examination scripts at the

%\input{open-book-insert-name.tex}
% D'Oh! Not supposed to put a name on anything going in the exam.
\input{open-book-insert-barcode.tex}
\hfill
\begin{pspicture}(7,1in)
%\psbarcode{
%\input{./open_book_insert.tex}
%B00526636
%}{includetext height=0.25}{code39}
\input{open-book-insert-barcode.tex}
\end{pspicture}
\end{centering}

\vfill
\begin{centering}
Please read the following declaration and tick the box to indicate you agree:

I declare this sheet to have been compiled by myself and not by another, and that the student number above is mine.

%\rule[-1 cm]{10 cm}{1 pt}
\framebox[0.3 cm]{ }

\end{centering}

\end{document}


# Workload Allocation Modelling Update – Scalability

I have been doing some more work on my software to handle Academic Workload Modelling, developing a roadmap for two future versions, one being modifications needed to run real allocations for next year without scrapping existing data, and another being code to handle the moderation of exams and coursework (which isn’t really anything to do with workload modelling, there’s some more mission creep going on).

Speaking of mission creep I noted in the last article I’d added some code to capture tasks that staff members would be reminded off and could self-certify as complete. I improved this a lot with more rich detail about when tasks were overdue and UI improvements.

I wanted to automate some batch code to send emails from the system periodically. I discovered that using a Django management command provided an elegant way to the batch mode code into the project that could be called with cron through the usual Django manage.py script that it creates to handle its own internal related tasks for the project from the command line.

#
# Regular cron jobs for the wam package
#
#  m h  dom mon dow user command
# Every week
#
# Each Monday at 7 am, send all reminders
0 7 * * 1 root /usr/bin/python3 /usr/local/share/wam/manage.py email_reminders
# Each Wednesday and Friday at 7 am, send reminders for overdue and less than 7 days to deadline tasks
0 7 * * 3,5 root /usr/bin/python3 /usr/local/share/wam/manage.py email_reminders --urgent-only


It was easy to use this framework to add command switches and configuration of verbosity (you might note I haven’t disabled all output at the moment so I can monitor execution at this stage). I have set this up to email folks on a Monday morning with all the tasks, but also on Wednesday and Friday if there are urgent tasks still outstanding (less than a week to deadline).

I’ve been using this functionality live and it has worked very well. I used Django templates to help provide the email bodies, both in HTML and plain text.

## Issues of Scale

My early prototype handled data for one academic year, albeit with fields in the schema to try and solve this at a later stage. It also suffered from a problem in that if other Schools wanted to use the system, how would I disaggregate the data both for security and convenience?

In the end I hit upon a solution for both issues, a WorkPackage model that allows a range of dates (usually one academic year) and a collection of Django User Groups to be specified. This allows all manually allocated activities, and module data to be specified with a package and therefore both invisible to other packages (users in other Schools, or in other Academic Years). I was also able to put the constants I’m using to model workload into the Django model, making it easier to tweak year on year.

class WorkPackage(models.Model):
'''Groups workload by user groups and time

A WorkPackage can represent all the users and the time period
for which activities are relevant. A most usual application
would be to group activities by School and Academic Year.

name        the name of the package, probably the academic unit
details     any further details of the package
startdate   the first date of activities related to the package
enddate     the end date of the activities related to the package
draft       indicates the package is still being constructed
archive     indicates the package is maintained for record only
groups      a collection of all django groups affected
created     when the package was created
nominal_hours
the considered normal number of load hours in a year
credit_contact_scaling
multiplier from credit points to contact hours
multiplier from contact hours to admin hours
contact_assessment_scaling
multiplier from contact hours to assessment hours

'''

name = models.CharField(max_length = 100)
details = models.TextField()
startdate = models.DateField()
enddate = models.DateField()
draft = models.BooleanField(default=True)
archive = models.BooleanField(default=False)
groups = models.ManyToManyField(Group, blank=True)
nominal_hours = models.PositiveIntegerField(default=1600)
credit_contact_scaling = models.FloatField(default=8/20)
contact_assessment_scaling = models.FloatField(default=1)
modified = models.DateTimeField(auto_now = True)

def __str__(self):
return self.name + ' (' + str(self.startdate) + ' - ' + str(self.enddate) + ')'

class Meta:
ordering = ['name', '-startdate']



I’m pretty much ready to use the system for a real allocation now without having to purge the test data I used this this year. I can simply create a new WorkPackage.

I need to write some functionality to allow one package’s allocations to be automatically rolled over to the next as a starting point, but I reckon that’s maybe two or three more hours.

## Future Plans for the Application

The next part of planned functionality is an ability to handle coursework and examination and the moderation process. It will be quite a big chunk of new functionality and moving the system again to something quite a bit bigger than just a workload allocation system.

This of course means I need a better Application name, (WAM isn’t so awesome anyway). Suggestions on a post card.

## Django Issues

I think I’m getting more to grips with Django all the time – although I often have the nagging feeling I’m writing several lines of code that would be simpler if I had a better feel for its syntax for dealing with QuerySets.

The big problem I hit, again, was issues in migrations. I created and executed migrations on my (SQLite) development system, but when I moved these over to production (MySQL) it barfed spectacularly.

Once again the lack of idempotent execution means you have to work out what part of the migration worked and then tag the migration as “faked” in order to move onto the next. This was sufficient this time, and I didn’t have to write custom migrations like last time, but it’s really not very reassuring.

## Further Details

As before, the code is on GitHub, and the development website on foss.ulster.ac.uk, if you want more details.

# Manually completing a botched django migration

I wrote a lot of code for my Workload Allocation system on Friday, and had been developing it on the machine with django’s built in lightweight web server, and a (default) sqlite database backend. In production I decided to use a MySQL backend in case sqlite was, well, too lite.

One of the things that is really neat about django, but which also profoundly scares me, is that it handles changes to the database schema automatically. I am used to doing all of this by hand. It has been a pleasant change, but I wondered what would happen if it went wrong.

Which it did on Friday. The migrations had worked perfectly well on the development server and after some testing I decided to roll the code into production, whereupon the migration failed. I’m still not sure why, but something in the django deep magic failed. To make things worse the process is, I have discovered, not idempotent, and trying to run the migration again caused it to fail in new places because some of the database schema changes had been successful; so it was now bailing out with “already exists” kind of errors.

Removing some tables and trying again didn’t quite do the trick. I thought about trying to fix the schema manually, since with the mysql command line tool I could see what fields needed to be added, but upon inspection the restraints added by django were complex and I was unsure how important they were.

So this is my clumsy workaround, that will no doubt come back to haunt me.

I used the following commands from the top of the django app directory to find the name of the migration that was failing, and than used –fake to force django to forget about having to apply it.

python manage.py migrate --list
python manage.py migrate --fake [failed migration]

I then created a “manual” django migration that added the new fields.

# -*- coding: utf-8 -*-
from __future__ import unicode_literals

from django.db import migrations, models

class Migration(migrations.Migration):

dependencies = [
]

operations = [
model_name='modulestaff',
name='module',
),
model_name='modulestaff',
name='staff',
),

]


It turns out that getting the dependency right at the top is very important, it needs to be previous migration.

The name of this script is important, follow the naming convention of your most recent failed migration, changing auto to custom and the timestamp appropriately. I discovered that django, would not run this migration. It detected a conflict with the previous migration that should have created the fields and wanted me to try and merge them. That would be pointless since the previous migration failed. I also discovered to my surprise there was no –force command line switch to override this logic, though Google perhaps suggests that previous versions of django allowed this.

So, I used the sqlmigration django command to output the correct SQL that it would produce if this migration did run. Once I got it showing in the shell, I forwarded this to a file.

python manage.py sqlmigration [migrationname] > fixme.sql

Finally I used the mysql command line tool

mysql -u root -p [appname]

to get access to the database, and then used the following command to import and run the SQL produced above.

source fixme.sql

And so far so good. I had been getting Server Errors on pages relating to the botched model before and at the moment they seem to be behaving correctly. Hopefully this may help you and not come back to haunt me.

# Workload Allocation Monitoring (WAM) Prototype

I decided to start writing a workload allocation monitoring system for Higher Education. I found one written as part of a JISC project at Cambridge, but despite my experience with PHP I found it difficult to set-up, a bit crude (sorry) and hard to maintain. It was clearly very flexible, and I wanted something flexible, simple and clean.

So I decided I’d try writing something quickly using the Python django framework. This is my first web-app written in Python and so I dare say I would do some things differently with more experience, but I have now reached the point where I have a workable prototype that I can start to use myself. I’ve got to say, I found django to be pretty neat.

At its heart is a list of the loads against Academic Staff in a department or school. The idea is to try and increase transparency. There are problems with this approach: some known irregularities of loading can be for confidential reasons; small numbers of staff with key skills can cause issues as well, but it is intended to provide a basis.

While classically the word semester implies that there are two of them, most Universities operate a three semester system with the third covering the Summer. Unevenness in loading over the Summer is another cause of potential trouble, so the system tries to show loading as spread across semesters. A scaled column accounts for staff who do not have a 100% FTE contribution but their hours are up-scaled for comparison.

Naturally staff will want to see some granularity of these loads and they are broken into individual activities that are allocated to given members of staff.

An individual activity can be specified as occupying a number of hours, or alternatively a percentage of a staff member’s time. It can occupy one or more semesters (in which case it is spread evenly across them). Types can be allocated for activities to help track contributions of different types. It might be that an activity is related to a module or study, or not.

Speaking of modules basic information is stored for these, and another issue I think will help, tracking the submission of exams and coursework through various QA processes.

While activities are considered to be events with long engagements, another issue for staff are tasks that are allocated to them, usually of comparatively short duration. It can be hard to staff to remember all of these tasks, and hard for manager to follow up their completion, especially without annoying staff who have completed them already.

The web-app will allow tasks to be defined against one person, many people, categories of people and so on.

It is possible to easily see which tasks are still open and whether their deadline has come and gone.

A look at a given task will show who has completed it and who still needs to.

It is often the case that admin and clerical staff check off colleagues who have responded to a given call, so the system allows for staff with given permissions to indicate someone has having completed the task. Alternatively the member of staff can do this for themselves.

So while it is still a bit rough and ready I’ve reached the point where the system is stable enough for use. Of course the challenge comes when we consider the assumptions to come up with the hours and percentage loading in the first place. So I hope to pick the brains of some colleagues about this and start testing the system.

I’ve yet to make a formal release, but the code is Affero GPL (you can use the code free of restrictions (and charge) but cannot deprive others of the same freedom on derivative works) so feel free to have a look at it.

My roadmap for an initial release can be found on foss.ulster.ac.uk, where I will eventually host the code as well, but at the moment it can be found at GitHub. My previous post detailed how to get the app to work with a central authentication system your University likely has, or something similar.

Yeah… design and CSS is not my strongest skill, more work to be done on that.

Share and enjoy.

# Django, CAS authentication and Apache

I am certainly no stranger to Web Development, but I decide to really look at the Python web framework django in some detail last week to write a small web application for Workload Modelling for Academic Staff.

Yes, this is a geeky, programming post.

In doing so I ran into some trouble trying to get CAS authentication to work with the app. I tried using a django-cas client I found, having found no direct CAS support in django. This took a reasonable number of code modifications, in several source files (really only a pain because I would have to maintain both development code and production code on different authentication). However the critical problem was that while I could get authentication into the “userland” parts of the app, I was getting redirect issues with the django generated administration interface.

So, I found a totally different approach. Django does have generic remote user support built-in which I hadn’t initially found. There are some details here. As you can see there are only two lines of code needed to enable this support.

I found this worked without any drama when I used Apache to force the CAS authentication. So the code required (in version 1.8 of django) is simply as follows, in the settings.py file.

MIDDLEWARE_CLASSES = (
'...',
'django.contrib.auth.middleware.AuthenticationMiddleware',
# This is where the new line needs to be added
'django.contrib.auth.middleware.RemoteUserMiddleware',
'...',
)

AUTHENTICATION_BACKENDS = (
'django.contrib.auth.backends.RemoteUserBackend',
)

The Apache Configuration looks something like this.

WSGIPythonPath /usr/local/share/WAM/

<IfModule mod_auth_cas.c>
CASValidateServer Off
CASVersion 2
CASDebug On
CASValidateURL https://your.cas.server/serviceValidate
CASTimeout 43200
CASIdleTimeout 3600
</IfModule>

<Location /wam>
AuthType CAS
Require valid-user
</Location>

Require all granted
</Directory>

WSGIScriptAlias /wam /usr/local/share/WAM/WAM/wsgi.py

<Directory /usr/local/share/WAM/WAM>
<Files wsgi.py>
Require all granted
</Files>
</Directory>


You will need to ensure you have Apache’s CAS and wsgi modules installed and enabled too.

I wasted a couple of hours going around the houses on this one, so hopefully it may save you. I will be hosting the project for my modeller on foss.ulster.ac.uk along with the code once I move it from GitHub.