question: Add the Question.multimedia attribute

Many questions have figures associated with the prompt text or the
answer choices.  This attribute provides a means to link to these
multimedia assets from the question.  Here's an example from the force
concept inventory, which I'm currently transcribing:

    {
      "class": "ChoiceQuestion",
      "id": "sling shot",
      "prompt": "A heavy ball is attached to a string...",
      "multimedia": [
        {
          "content-type": "image/png",
          "path": "force-concept-inventory/04.png"
        }
      ],
      "display_choices": true,
      "answer": [
        "(A) in the figure",
        "(B) in the figure",
        "(C) in the figure",
        "(D) in the figure",
        "(E) in the figure"
      ]
    }

The 'multimedia' attribute is an array because a question might
conceivably reference several assets (e.g. an image and an audio clip,
or multiple images).

To display the assets alongside the question, I've refactored the WSGI
handler to pull out QuestionApp._format_prompt(), which in turn
delegates to the new QuestionApp._format_multimedia().  This embeds a
link to the asset, using a MIME-appropriate container (currently just
<img> for image/* types).  The assets themselves are served as
media/<HASH>, where I hash the whole multimedia-defining dictionary to
avoid information leakage which might otherwise help in solving the
problem.  Using hash-based URLs also avoids problems with special
characters in the multimedia data.

In the CLI handler, we can't inline multimedia.  I use the user's
mailcap configuration (RFC 1524) to spawn their preferred
MIME-appropriate viewer when the prompt for a new question is being
generated.  If the user hasn't configured a viewer for the MIME type
in question, we just print a message referring to the asset by its
full path and let the user take it from there.

The mailcap viewer is adapted from an example I initially posted on my
blog in 2011 [1].  The path-quoting follows the Mutt docs [2]:

> The interpretion of shell meta-characters embedded in MIME
> parameters can lead to security problems in general. Mutt tries to
> quote parameters in expansion of `%s` syntaxes properly, and avoids
> risky characters by substituting them, see the `mailcap_sanitize`
> variable.

[1]: http://blog.tremily.us/posts/mailcap/mailcap-test.py
[2]: http://www.mutt.org/doc/manual/manual-5.html

ui.wsgi: Factor URL handling out into WSGI_UrlObject

QuestionApp is complicated enough without this generic URL delegation
code being jumbled in.  This commit makes helps isolate the
quizzer-specific code from boilerplate WSGI utilities.

Run update-copyright.py

util: Support Python 3.2 by ignoring timeouts passed to invoke()

If you're not asking ScriptQuestions, you don't care about this
feature, and it's good to be able to relax the Python 3.3 requirement.

README: Describe the types of supported questions

ui.cli: Remove explicit return from QuestionCommandLine._extra_ps1_lines()

Mixing return statements and `yield`-based generators is bad practice.

Bump to version 0.4

Changes since 0.3:
* Added a WSGI-based HTML interface.
* Added user keys to answer database and stack (for multi-user support
  in the WSGI interface).
* Added Question.accept_all for open-ended questions.
* Extended ChoiceQuestion to support multiple choice questions
  (display_choices) which default to "select one of ...", but can be
  configured to "select all that apply" (multiple_answer).
* Added a new software-carpentry-pre-assessment quiz.
* Assorted minor fixups.

I bumped any existing quizzes that use new features to v0.4, but left
the others alone.

quizzes/software-carpentry-pre-assessment: Allow multiple platforms

For mixed-OS environments (e.g. local OS X machine with department
Linux boxes).

question: Add the ChoiceQuestion.multiple_answer attribute

This adds support for multiple choice questions where you are allowed
to select one or more of the possible choices.  In web forms, this is
usually done via checkboxes.

ui.cli: Don't record EOF or blank entries as answers

If the user closes stdin, don't check and see if 'EOF' is an allowed
answer, just exit the QuestionCommandLine loop.  Don't try to process
blank entries either, just re-ask the question.

quizzes/software-carpentry-pre-assessment: Automate the pre-assessment

From swcarpentry/assets [1], as of 4a6d554 (Importing a whole bunch of
old material relevant to Software Carpentry, 2012-12-20).

[1]: https://github.com/swcarpentry/assets/blob/master/assessment/5.1/wilson-pre-assessment-2012-11.html

question: Move ChoiceQuestion.open_ended to Question.accept_all

Accepting all answers is a more general case of an open ended multiple
choice question.  It also allows us to ask questions that are
difficult or impossible to grade automatically.  We just record the
student's answer for the grader to look at later.

quizzer: Add ChoiceQuestion.open_ended

This allows us to ask open-ended multiple-choice questions, like:

  Pick one:
  1) Answer-1
  2) Answer-2
  or fill in something else
  quizzer? Answer-3

quizzer: Add ChoiceQuestion.display_choices

This gives us more traditional multiple-choice questions.

ui.wsgi: Close the text-input tag

quizzer: Add user keys to the answer database and stack

Instead of:

  answerdb[question.id] = [list, of, answers]
  ui.stack = [list, of, questions]

Now we have:

  answerdb[user.name][question.id] = [list, of, answers]
  ui.stack[user.name] = [list, of, questions]

This will allow us to use a single answer database and stack for a
multi-user interface (e.g. WSGI).  I've added the appropriate upgrade
rules to update existing answer databases once we bump to v0.4.

To reduce redundancy and ease future maintenance, I also factored out
AnswerDatabase._get_questions() from .get_unanswered() and friends.

There's a bit of hackery to deal with the default None user in the
answer database.  Because JSON objects (the equivalent of Python's
dicts) are keyed by strings, you get things like:

  >>> import json
  >>> json.dumps({None: 'value'})
  '{"null": "value"}'

We avoid this and preserve the None key through a save/load cycle by
replacing it with the empty string.  This means that you shouldn't use
the empty string as a user name when interacting with the database
from Python, and we'll raise a ValueError if you try to do that
through AnswerDatabase-specific methods.

ui.wsgi: Add a preliminary WSGI/HTML user interface

The basic WSGI handling (e.g. HandlerErrorApp and WSGI_DataObject) is
largely based on code I'd written for Bugs Everywhere.

question: Question.check() now returns (correct, details)

When the answer is correct, details will be None.  When the answer is
incorrect, details may be None or an explanatory message that provides
details about why the answer is incorrect.  This is mostly useful for
`ScriptQuestion`s, where the difference between the answered and
expected output streams may help diagnose errors.

The details are returned as a string (instead of, for example, logging
them in invocation_difference) so they will be easy to display in user
interfaces that aren't built around the command line.

cli: Teach quizzer.cli.main() the --ui option

This uses the new quizzer.ui.INTERFACES and quizzer.ui.get_ui() to
select from among the available interfaces (currently just the command
line interface).

quizzes/monty-python: Fix JSON error (missing comma in copyright)

This fixes a typo introduced in 5909e7f (quiz: Add copyright metadata,
2013-02-15).

ui.cli: Import UserInterface with an underscore

For a cleaner namespace.

ui: Remove UserInterface.display_results()

Having quizzer.cli.main() calling ui.display_results() does not
translate well to an HTML-based UI.

CommandLineInterface now displays results as part of its .run()
implementation.

quizzes: Bump quizzes to v0.3 because they have copyright data

Copyright data was added after v0.2.  By bumping the quiz versions,
the quizzes will no longer work with quizzer clients too old to
understand this metadata.

Bump to version 0.3

Changes since 0.2:
* Add quiz copyright metadata and the `copyright` cli command.
* Cleaned up the data-upgrade framework, so we're ready for any future
  data format refactoring ;).

quizzer: Get upgrade-from-v0.2-to-v0.3 methods in place

quizzer: Add methods to upgrade data from v0.1 to v0.2

These are both no-ops that only bump the version number, since the
stored format didn't change between the two versions.

quizzes/DiRAC-drivers-license: Add copyright and licensing info

On Thu, Mar 07, 2013 at 06:35:09PM +0000, Mike Jackson wrote:
> Copyright is Software Carpentry and The University of Edinburgh and
> University College London and the licence is just CC-BY 3.0 as for
> Software Carpentry material. Hope that helps,

Merge branch 'license'

* license:
  quiz: Add copyright metadata

quiz: Add copyright metadata

Because quizzer may be used to administer quizzes that are not under
the GPLv3+, make it easy to store and access per-quiz copyrights.

Also add a `copyright` command to ui.cli.QuestionCommandLine and add
copyright blurbs to the individual quizzes.

Bump to version 0.2

Changes since 0.1:
* Added optional pygments colorization.
* New `skip` and `shell` commands for ui.cli.
* New Quiz.introduction.
* New DiRAC driver's license sample quiz.
* Assorted cleanups.

quizzes/DiRAC-drivers-license: First pass at automating the exam

See:
  http://software-carpentry.org/blog/2012/08/alpha-test-of-drivers-license-exam.html
  http://software-carpentry.org/blog/2013/02/dirac-dry-run-two.html

I was unable to convert the code review question to the quizzer
format, because it's hard to evaluate refactorings automatically.

This quiz is probably not under the GPLv3.  The licensing for the
original quiz is unclear, but most Software Carpentry stuff is under
the Creative Commons Attribution 3.0 Unported (CC BY 3.0).

ui.cli: Add do_shell() and associated framework

For more open ended questions, users may need an interactive shell to
develop the answer, and we won't be able to bundle their answer with
setup and teardown instructions in a single script.  This commit
breaks setup and teardown into separate scripts, and moves the
TemporaryDirectory stuff over to quizzer.util.  If it's enabled via
allow_interactive, users can now drop into an interactive command
using !$COMMAND (e.g. !bash) from the cli user interface.

If you want to tweak environment variables for the answer script and
interactive commands, use the new environment dictionary.

For situations where you *do* need setup/teardown stuff in the answer
script (e.g. to check the current working directory or variables that
should have been altered by the user's answer action), you can use
the new pre_answer and post_answer.

Previous versions of ScriptQuestion compared the output of the single
setup/answer/teardown script to check for matches.  With this commit
we only compare the output of the teardown script, unless
compare_answers is set, in which case we compare both the answer
output and teardown output.  When we're not comparing the answer
output, we still plot nonempty user-answer standard errors, because
without seeing stderr, it can be difficult to determine where your
attempted command went wrong.

Existing quizzes were updated accordingly, with a few additional
tweaks and cleanups that I discovered while debugging.

ui.cli: Isolate ui.get_question() in QuestionCommandLine.get_question()

Ensure uniform handling across class methods by avoiding duplication.

quizzes/git: Fix JSON indentation for GIT_AUTHOR_EMAIL

ui.cli: Avoid divide-by-zero errors if no questions were answered

quiz: Add Quiz.introduction for an optional intro message

ui.cli: `skip` shifts the current question to the back of the stack

Rather than dropping skipped questions, just save them for later.
This gives you another stab at them without having to restart the
quiz.  If you still can't answer the questions once you reach them
again, you can always `quit` ;).

ui.cli: Add a `skip` command to the quizzer shell

This lets you bypass a difficult question on the stack and continue
with the rest of the quiz.

ui.cli: Unwrap multiline answers in display_result

No need to surprise the user with the internal list representation.

ui.cli: Use pygments to colorize command line output

quizzes/git: Don't timeout during the 'gitignore' question

In case the user decides to spawn an editor to tweak .gitignore.

quizzes/git: Add remote-related questions

New questions:
* git remote add
* git remote -v
* git fetch REPOSITORY
* git push REPOSITORY BRANCH

quizzer/git: Add 'git merge' question

quizzes/git: Add 'git checkout *' questions

New questions:
* git checkout
* git checkout -b
* git checkout -b NEW_BRANCH START_POINT

quizzes/git: Add 'git branch *' questions

New questions:
* git branch
* git branch -a
* git branch -r
* git branch -d

quizzes/git: Fix 'in repository' -> 'in your repository'

For the 'git rm / commit' question.

quizzes/git: Add 'git rm / commit' question

quizzes/git: Add 'git log *' questions

New questions:
* git log
* git log -p
* git log --stat
* git log --all
* git log --oneline
* git log --oneline --graph
* git log --oneline --decorate

quizzes/git: Add 'git diff *' questions

New questions:
* git diff
* git diff HEAD --
* git diff HEAD -- README
* git diff --cached

quizzes/git: Avoid escaped double-quotes when single-quotes will do

quizzes/git: Add 'git commit -a' question

ui.cli: Don't start the QuestionCommandLine with an empty stack

There's not much point in a question-answering shell if there are no
questions to be answered.

quizzes/git: Add 'git status' question

quizzes/git: Add 'gitignore' question

ui.cli: Quit after the last question

Oops, should have tested that when I transitioned to Cmd ;).

ui.cli: Fix ._set_ps1 when .question is None

Otherwise QuestionCommandLine will crash if its launched with an empty
stack (not that this should happen, but we should still avoid the
crash).

quizzes/git: Add 'git help config' question

ui.cli: Fix single-line answer extraction

`var.get(key, default)` only works for dicts.  I don't think there is
an equivalent that works for lists.

cli: Add --select to filter the stack by index

For example, you can show the questions in a quiz with either the
`config` tag or the `checkout` tag:

  $ ./pq.py --all --tag config --tag checkout --questions quizzes/git.json
  Question 0:
  Configure your user-wide name to be `A U Thor`.

  Question 1:
  Configure your user-wide email to be `author@example.com`.

  Question 2:
  You've messed up your README file.
  Restore it to the last committed version.

Say questions 0 and 2 look interesting, and you'd like to try question
2 first.  Run:

  $ ./pq.py --all --tag config --tag checkout -s 2 -s 0 quizzes/git.json

ui.cli: Add an `answer` command to QuestionCommandLine

This allows you to bypass quizzer-shell command handling when your
answer line starts with a quizzer-shell command.

ui.cli: Repeat the basic help when the user calls `help`

ui.cli: Transition to a CLI based on cmd.Cmd

This makes command handling more robust, and makes adding additional
non-answer commands more organized.

quizzes: Convert multi-line help to lists

question: Add support for list-of-lines help

We use lists of lines for other question attributes (e.g. setup,
teardown, answer, prompt).  Be consistent with multi-line help.

quizzes/git: Convert multi-line prompts to lists

question: Add support for list-of-lines prompts

We use lists of lines for other question attributes (e.g. setup,
teardown, answer).  Be consistent with multi-line prompts.

The handling is in Question.format_prompt() for easy access by any
consumer.  The `newline` option will make it easy to support
non-terminal output formats (e.g. `newline='<br/>'` for HTML).

quizzes: Use complete sentences with punctation for prompts

This makes multi-sentence prompts less awkward.

cli: Add the --questions option to list questions on the stack

This lets you see what a quiz will ask without actually taking the
quiz.  In the future, it may be useful for jumping to a specific
question.

cli: Add the --tags option to list tags on the stack

quizzes/git: Tag existing questions

Add --tag option and Question.tags sets for filtering large quizzes

cli: Add --all for easy review of previously-answered questions

answerdb: Timestamp answers

This may provide insight into the learning process (e.g. after I
reviewed the Git index, everyone started doing better).

quizzes/git: Add 'git commit --amend' question

README.rst: Add a symlink for GitHub's README renderer

quizzes/git: Add 'git config --global user.{name,email}' questions

quizzes/git: Add 'git checkout HEAD -- FILE' question

question: Add a trailing newline to ScriptQuestion scripts

question: Pass stdin through to the ScriptQuestion-invoked script

Use a temporary script to hold the answer script, to leave stdin open.
This allows users to use commands that need stdin (e.g. `git commit`,
which spawns an `$EDITOR`).

quizzes/git: Add 'git add / commit' question

Remove the default timeout, to give users who spawn `$EDITOR` via `git
commit` time to write and save their message.

Run update-copyright.py

.update-copyright.conf: Configure update-copyright.py

http://blog.tremily.us/posts/update-copyright/
http://pypi.python.org/pypi/update-copyright/

Add `# Copyright` tags to Python files

.gitignore: Ignore MANIFEST and dist/ packaging side effects

MANIFEST.in: Distribute COPYING and quizzes/*.json

setup.py: Package with distutils

README: Flesh out description and add example typescript

README: Mention Python 3.3 dependency

COPYING: Distribute quizzer under the GPLv3+

quizzes/git: Add preliminary Git quiz (repository creation)

Add Question.multiline and associated handling

Some questions can't be answered in a single line without reqiring
more shell knowledge than we need (e.g. `&&`).

ui.cli: Import `readline` for more comfortable input() editing

quizzes/posix-shell: Add a preliminary POSIX shell language quiz

quizzes/posix-utilities: Rename from posix-shell.json and flesh out

Added few more questions:
* print the current directory to stdout
* change to your home directory
* change to the parent of your current working directory
* print the contents of README file to the terminal

The renaming is because the tests are testing knowledge of POSIX
utilities, not knowledge of the shell syntax itself.

question: Normalize tempdir paths in stdout/stderr

Otherwise it's hard to test `pwd`, since tempdir will change between
the expected and user-supplied answer runs.

question: Add ChoiceQuestion for one-of-several correct answers

quizzes: Move quizzes into a subdirectory

Add script invocation to ScriptQuestion

We need Python >= 3.3 for the `timeout` argument to
Popen.communicate().

Remove debugging print(self.stack) from UserInterface.get_question()

Initial ScriptQuestion framework