Upload 32 files

CHANGELOG.md

@@ -0,0 +1,139 @@
+# Change Log
+
+
+## v0.7.0 (dev)
+
+* Numbers in scientific notation with leading zeros in the exponent are now
+  permitted for siunitx notation within Markdown.  The zeros are stripped
+  during processing.
+
+
+
+## v0.6.0 (2022-08-31)
+
+* Leading plus signs `+` are now stripped for siunitx notation within
+  Markdown.
+
+* Added `amsmath`, `amssymb`, and `siunitx` to template for LaTeX solutions
+  export.
+
+* Fixed a bug with error handling when Pandoc fails to export solutions (#47).
+
+* For question groups, the value of `pick` is now allowed to equal the total
+  number of questions (#44).
+
+* Added support for Pandoc-style attributes on images:
+  `![alt_text](image_file){#id .class1 .class2 width=10em height=5em}` (#41).
+
+* Executable code blocks now use PATH to locate executables under Windows, and
+  thus now work with Python environments.  Previously PATH was ignored under
+  Windows due to the implementation details of Python's `subprocess.Popen()`
+  (#34, #42).
+
+* Added command-line options `--solutions` and `--only-solutions` to
+  command-line application.  These generate solutions in Pandoc Markdown,
+  PDF, and HTML formats.  Pandoc Markdown solutions are only suitable for
+  use with LaTeX and HTML (#35).
+
+* Added quiz-level options `feedback is solution`, `solutions sample groups`,
+  and `solutions randomize groups` for customizing solutions.  Added
+  group-level option `solutions pick` for customizing solutions.  Added
+  question-level syntax involving `!` for providing solutions.
+
+* In quiz parsing, simplified question type handling and error checking.
+
+* Fixed bug in calculation of total points possible per quiz.
+
+
+
+## v0.5.0 (2020-09-28)
+
+* Added `text2qti_tk` executable, which provides a basic graphical user
+  interface (GUI) via `tkinter`.  Added build scripts in `make_gui_exe/` for
+  creating a standalone GUI executable under Windows with PyInstaller (#27).
+* In executable code blocks, `.python` now invokes `python3` on systems where
+  `python` is equivalent to `python2` as well as on systems that lack a
+  `python` executable.  The README now suggests using `.python3` and
+  `.python2` to be more explicit (#22).
+* Added a new keyword argument `executable` for executable code blocks, which
+  allows a custom executable (including path) to be specified for running
+  code.  Added support for periods in code block language attributes, so that
+  things like `.python3.8` are now possible.
+* Fixed bug caused by swapped identifiers in QTI XML (#18, #19).  Now quiz
+  descriptions work with Canvas and question titles appear in Canvas in the
+  quiz editor (but not in the student view).   The following options now work
+  with Canvas:  `Shuffle answers`, `Show correct answers`,
+  `One question at a time`, and `Can't go back`.
+* Installation (`setup.py`) now requires `markdown` >= 3.2 to ensure
+  compatibility and avoid Markdown parsing bugs fixed in 3.2 (#31).
+* Fixed bug that produced incorrect QTI output paths when using quiz files
+  outside the current working directory (#28, #29).
+* README now covers more options for installing the development version (#20).
+
+
+
+## v0.4.0 (2020-07-17)
+
+* Improved preprocessing for siunitx notation, LaTeX math, and HTML comments.
+  Fixed catastrophic backtracking in LaTeX math regex (#11).  Added support
+  for newlines in HTML comments.  The preprocessor now skips backslash
+  escapes, inline code containing newlines, and fenced code blocks (as long as
+  they do not start on the same line as a list marker).  The preprocessor now
+  handles the escape `\$` itself, since Python-Markdown ignores it (#14).
+* Python-Markdown's Markdown-in-HTML extension is now enabled (#13).
+* Added quiz options `Shuffle answers`, `Show correct answers`,
+  `One question at a time`, and `Can't go back` (#10).  These options are
+  apparently ignored by Canvas, but may work with some other systems.
+* Revised README to clarify that some features are apparently not supported
+  by Canvas (#16).
+
+
+
+## v0.3.0 (2020-05-26)
+
+* Added support for multiple-answers questions.
+* Added support for short-answer (fill-in-the-blank) questions.
+* Added support for file-upload questions.
+* Added support for setting question titles and point values (#9).
+* Added support for text regions outside questions.
+* Added `--pandoc-mathml` command-line option.  This converts LaTeX to MathML
+  via Pandoc, rather than using a Canvas LaTeX rendering URL (#4).
+* Added support for comments at the top level of quiz files (outside Markdown
+  content like questions, choices, or feedback).  HTML comments within
+  Markdown are now stripped and no longer appear in the final QTI file (#2).
+* For numerical questions, exact answers with allowed margin are now treated
+  as exact answers, rather than being converted into ranges of values.  This
+  primarily affects how feedback for incorrect answers is worded (#7).
+* Essay questions now support general feedback.
+* Fixed a bug that prevented incorrect question feedback from working.
+* Relaxed indentation requirements for quiz titles spanning multiple lines.
+  Indentation for wrapped lines must now be at least 2 spaces or 1 tab, rather
+  than being equivalent to that of the first character in the title.
+* Fixed a bug that allowed trailing whitespace to cause incorrect indentation
+  calculations, resulting in indentation errors in valid quizzes.
+
+
+
+## v0.2.0 (2020-04-23)
+
+* Added support for images, using standard Markdown syntax.
+* Added support for multi-paragraph descriptions, questions, choices, and
+  feedback.
+* Added support for essay questions.
+* Added support for numerical questions.
+* Added support for question groups.  A subset of the questions in a group is
+  chosen at random when a quiz is taken.
+* Added support for executable code blocks.  These can be used to generate
+  questions automatically.  This feature requires the command-line flag
+  `--run-code-blocks` or setting `run_code_blocks = true` in the config
+  file.
+* Quiz titles are now processed as plain text, rather than as Markdown,
+  because QTI does not support HTML titles.
+* Fixed a bug that prevented source file names from appearing in error
+  messages.  Fixed misspelling of "imsmanifest.xml" in QTI output.
+
+
+
+## v0.1.0 (2020-04-01)
+
+* Initial release.

LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2020, Geoffrey M. Poore
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,2 @@
+include setup.cfg setup.py README.md LICENSE.txt CHANGELOG.md
+recursive-include text2qti *.py

README.md

@@ -1,21 +1,720 @@
----
-title: Text2qti
-emoji: 🚀
-colorFrom: red
-colorTo: red
-sdk: streamlit
-app_port: 8501
-tags:
-- streamlit
-pinned: false
-short_description: Quiz converter from Markdown to LMS qti.zip
-license: gpl-3.0
-sdk_version: 1.45.1
----
-
-# Welcome to Streamlit!
-
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
-
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+# text2qti – Create quizzes in QTI format from Markdown-based plain text
+
+text2qti converts
+[Markdown](https://daringfireball.net/projects/markdown/)-based plain text
+files into quizzes in QTI format (version 1.2), which can be imported by
+[Canvas](https://www.instructure.com/canvas/) and other educational software.
+It supports multiple-choice, true/false, multiple-answers, numerical,
+short-answer (fill-in-the-blank), essay, and file-upload questions.  It
+includes basic support for LaTeX math within Markdown, and allows a limited
+subset of [siunitx](https://ctan.org/pkg/siunitx) notation for units and for
+numbers in scientific notation.
+
+
+
+## Examples
+
+text2qti allows quick and efficient quiz creation.  Example
+**multiple-choice** plain-text quiz question that can be converted to QTI and
+then imported by Canvas:
+
+```
+1.  What is 2+3?
+a)  6
+b)  1
+*c) 5
+```
+
+A **question** is created by a line that starts with a number followed by a
+period and one or more spaces or tabs ("`1. `").  Possible **choices** are
+created by lines that start with a letter followed by a closing parenthesis
+and one or more spaces or tabs ("`a) `").  Numbers and letters do not have to
+be ordered or unique.  The **correct** choice is designated with an asterisk
+("`*c) `").  All question and choice text is processed as
+[Markdown](https://daringfireball.net/projects/markdown/).
+
+There is also support for a quiz title and description, as well as question
+titles, point values, and feedback.  Note that unlike most other text, titles
+like quiz and question titles are treated as plain text, not Markdown, due to
+the QTI format.  **Also note that Canvas correctly shows question titles
+within its quiz editor for instructors, but always replaces them with titles
+like "Question 1" in the student view.**  Question point values must be
+positive integers or half-integers.
+
+```
+Quiz title: Addition
+Quiz description: Checking addition.
+
+Title: An addition question
+Points: 2
+1.  What is 2+3?
+... General question feedback.
++   Feedback for correct answer.
+-   Feedback for incorrect answer.
+a)  6
+... Feedback for this particular answer.
+b)  1
+... Feedback for this particular answer.
+*c) 5
+... Feedback for this particular answer.
+```
+
+**Multiple-answers questions** use `[]` or `[ ]` for incorrect answers and
+`[*]` for correct answers.
+
+```
+1.  Which of the following are dinosaurs?
+[ ] Woolly mammoth
+[*] Tyrannosaurus rex
+[*] Triceratops
+[ ] Smilodon fatalis
+```
+
+**Numerical questions** use an equals sign followed by one or
+more spaces or tabs followed by the numerical answer.  Acceptable answers can
+be designated as a range of the form `[<min>, <max>]` or as a correct answer
+with a specified acceptable margin of error `<ans> +- <margin>`.  When the
+latter form is used, `<margin>` can be either a number or a percentage.
+`<margin>` can be omitted when the answer is an integer and an exact answer is
+required.  In this case, scientific notation is not permitted, but the
+underscore can be used as a digit separator; for example, `1000` and `1_000`
+are both valid, but `1e3` is not.  An exact answer can be required for
+floating-point numbers, but this requires an explicit `+- 0`, since a range is
+typically more appropriate for floating-point values.  Numerical questions
+have the limitation that the absolute value of the smallest acceptable answer
+must be greater than or equal to 0.0001 (1e-4).
+
+```
+1.  What is the square root of 2?
+=   1.4142 +- 0.0001
+
+2.  What is the cube root of 2?
+=   [1.2598, 1.2600]
+
+3.  What is 2+3?
+=   5
+```
+
+**Short-answer (fill-in-the-blank) questions** use an asterisk followed by one
+or more spaces or tabs followed by an answer.  Multiple acceptable answers can
+be given.  Answers are restricted to a single line each and are treated as
+plain text, not Markdown.
+```
+1.  Who lives at the North Pole?
+*   Santa
+*   Santa Claus
+*   Father Christmas
+*   Saint Nicholas
+*   Saint Nick
+```
+
+**Essay questions** are indicated by a sequence of three or more underscores.
+They only support general question feedback.
+
+```
+1.  Write an essay.
+... General question feedback.
+____
+```
+
+**File-upload questions** are indicated by a sequence of three or more
+circumflex accents.  They only support general question feedback.
+```
+1.  Upload a file.
+... General question feedback.
+^^^^
+```
+
+**Text regions** outside of questions are supported.  Note that unlike most
+other text, titles like text region titles are treated as plain text, not
+Markdown, due to the QTI format.  Also note that Canvas apparently ignores the
+text region title and only displays the text itself.  Text regions are not
+required to have both a title and text; either may be used alone, but the
+title must come first when both are present.
+```
+Text title:  Instructions about the next questions
+Text:  General comments about the next questions.
+```
+
+
+## Installation
+
+Install **Python 3.6+** if it is not already available on your machine.  See
+https://www.python.org/, or use the package manager or app store for your
+operating system.  Depending on your use case, you may want to consider a
+Python distribution like [Anaconda](https://www.anaconda.com/distribution/)
+instead.
+
+Install
+[setuptools](https://packaging.python.org/tutorials/installing-packages/)
+for Python if it is not already installed.  This can be accomplished by
+running
+```
+python -m pip install setuptools
+```
+on the command line.  Depending on your system, you may need to use `python3`
+instead of `python`.  This will often be the case for Linux and OS X.
+
+Install text2qti by running this on the command line:
+```
+python -m pip install text2qti
+```
+Depending on your system, you may need to use `python3` instead of `python`.
+This will often be the case for Linux and OS X.
+
+
+### Upgrading
+
+```
+python -m pip install text2qti --upgrade
+```
+Depending on your system, you may need to use `python3` instead of `python`.
+This will often be the case for Linux and OS X.
+
+
+### Installing the development version
+
+If you want to install the development version to use the latest features,
+download `text2qti` from [GitHub](https://github.com/gpoore/text2qti) and
+extract the files.  A few different ways to install the development version
+are listed below.  Depending on your system, you may need to use `python3`
+instead of `python` in the commands below.  This will often be the case for
+Linux and OS X.
+
+* You can install using the included `setup.py` by running
+  ```
+  python setup.py install
+  ```
+  Depending on your system configuration, especially if you do not have root
+  or administrator privileges, you may want to
+  [customize the installation location](https://docs.python.org/3.8/install/#alternate-installation-the-user-scheme).
+  For example, you can add `--user` to install under `%APPDATA%\Python` (Windows), `~/.local` (UNIX, and Mac OS X non-framework builds), or
+  `~/Library/Python/<VERSION>` (Mac framework builds):
+  ```
+  python setup.py install --user
+  ```
+* You can install using `pip`.  For example, in the directory with `setup.py`,
+  run this:
+  ```
+  python -m pip install .
+  ```
+
+
+
+
+## Usage
+
+text2qti has been designed to create QTI files for use with
+[Canvas](https://www.instructure.com/canvas/).  Some features may not be
+supported by other educational software.  You should **always preview**
+quizzes or assessments after converting them to QTI and importing them.
+
+Write your quiz or assessment in a plain text file.  You can use a basic
+editor like Notepad or gedit, or a code editor like
+[VS Code](https://code.visualstudio.com/).  You can even use Microsoft Word,
+as long as you save your file as plain text (*.txt).
+
+text2qti includes a graphical application and a command-line application.
+
+* To use the graphical application, open a command line and run `text2qti_tk`.
+
+* To use the command-line application, open a command line in the same folder
+  or directory as your quiz file.  Under Windows, you can hold the SHIFT
+  button down on the keyboard, then right click next to your file, and select
+  "Open PowerShell window here" or "Open command window here".  You can also
+  launch "Command Prompt" or "PowerShell" through the Start menu, and then
+  navigate to your file using `cd`.
+
+  Run the `text2qti` application using a command like this:
+  ```
+  text2qti quiz.txt
+  ```
+  Replace "quiz.txt" with the name of your file.  This will create a file like
+  `quiz.zip` (with "quiz" replaced by the name of your file) which is the
+  converted quiz in QTI format.
+
+Instructions for using the QTI file with Canvas:
+  * Go to the course in which you want to use the quiz.
+  * Go to Settings, click on "Import Course Content", select "QTI .zip file",
+    choose your file, and click "Import".  Typically you should not need to
+    select a question bank; that should be managed automatically.
+  * While the quiz upload will often be very fast, there is an additional
+    processing step that can take up to several minutes.  The status will
+    probably appear under "Current Jobs" after upload.
+  * Once the quiz import is marked as "Completed", the imported quiz should be
+    available under Quizzes.  If the imported quiz does not appear after
+    several minutes, there may be an error in your quiz file or a bug in
+    `text2qti`.  When Canvas encounters an invalid quiz file, it tends to fail
+    silently; instead of reporting an error in the quiz file, it just never
+    creates a quiz based on the invalid file.
+  * You should **always preview the quiz before use**.  text2qti can detect a
+    number of potential issues, but not everything.
+
+Typically, you should start your quizzes with a title, like this:
+```
+Quiz title: Title here
+```
+Otherwise, all quizzes will have the default title "Quiz", so it will be
+difficult to tell them apart.  Another option is to rename quizzes after
+importing them.  Note that unlike most other text, the title is treated as
+plain text, not Markdown, due to the QTI format.
+
+When you run `text2qti` for the first time, it will attempt to create a
+configuration file called `.text2qti.bespon` in your home or user directory.
+It will also ask for an institutional LaTeX rendering URL.  This is only
+needed if you plan to use LaTeX math; if not, simply press ENTER to continue.
+ * If you use Canvas, log into your account and look in the browser address
+   bar.  You will typically see an address that starts with something like
+   `institution.instructure.com/` or `canvas.institution.edu/`, with
+   `institution` replaced by the name of your school or an abbreviation for
+   it.  The LateX rendering URL that you want to use will then be something
+   like `https://institution.instructure.com/equation_images/` or
+   `https://canvas.institution.edu/equation_images/`, with `institution`
+   replaced by the appropriate value for your school.  If the URL is like the
+   second form, you may need to replace the `.edu` domain with the appropriate
+   value for your institution.
+ * If you use other educational software that handles LaTeX in a manner
+   compatible with Canvas, consult the documentation for your software.  Or
+   perhaps create a simple quiz within the software using its built-in tools,
+   then export the quiz to QTI and look through the resulting output to find
+   the URL.
+ * If you are using educational software that does not handle LaTeX in a
+   manner compatible with Canvas, try the `--pandoc-mathml` command-line
+   option when creating QTI files (note that this requires that
+   [Pandoc](https://pandoc.org/) be installed).  If that does not work, please
+   open an issue requesting support for that software, and include as much
+   information as possible about how that software processes LaTeX.
+
+
+
+## Additional features
+
+### Question groups
+
+A question group contains multiple questions, and only a specified number of
+these are randomly selected and used each time a quiz is taken.
+
+```
+GROUP
+pick: 1
+points per question: 1
+
+1.  A question.
+*a) true
+b)  false
+
+2.  Another question.
+*a) true
+b)  false
+
+END_GROUP
+```
+
+The number of questions from the group that are used is specified with
+"`pick:`".  If this is omitted, it defaults to `1`.  The points assigned per
+question is specified with "`points per question:`".  If this is omitted, it
+defaults to `1`.  All questions within a group must be worth the same number
+of points.
+
+
+### Executable code blocks
+
+text2qti can execute the code in Markdown-style fenced code blocks.  Code can
+be used to generate questions within a quiz.  Everything written to stdout by
+the executed code is included in the quiz file; the code block is replaced by
+stdout.
+
+``````
+```{.python .run}
+import textwrap
+for x in [2, 3]:
+    print(textwrap.dedent(rf"""
+        1.  What is ${x}\times 5$?
+        *a) ${x*5}$
+        b)  ${x+1}$
+        """))
+```
+``````
+
+
+For code to be executed, there are a few requirements:
+
+* The code block fences (` ``` `) must not be indented; the code block must be
+  at the top level of the document, not part of a question, choice, or
+  feedback.
+
+* As a security measure, code execution is disabled by default, so executable
+  code blocks will trigger an error.  Run `text2qti` with the option
+  `--run-code-blocks` to enable code execution, or set `run_code_blocks =
+  true` in the text2qti config file in your user or home directory.
+
+* The text immediately after the opening fence must have the form
+  `{.lang .run}` or `{.lang .run executable=<executable>}`.  This is inspired
+  by the code-block attributes in
+  [Pandoc Markdown](https://pandoc.org/MANUAL.html).
+
+  If the keyword argument `executable` is not provided, then `lang` must
+  designate an executable that can run the code once the code has been saved
+  to a file.  In the example above, `python` is extracted from the first line
+  (` ```{.python .run}`),  code is saved in a temporary file, and then the
+  file is executed via `python <file>`.
+
+  If `executable` is used to specify an executable, then `lang` is ignored by
+  `text2qti`, but it is still useful since some editors will use it to provide
+  syntax highlighting.
+
+  When `executable` is specified, the executable path must be quoted with
+  double quotes `"` if it contains anything other than the tilde, Unicode word
+  characters, numbers, forward slashes, periods, hyphens, and underscores.
+  When the executable path is quoted, backslashes and quotation marks are
+  still prohibited; forward slashes should be used under all operating systems
+  including Windows.  A leading `~` in the executable path is expanded to the
+  user's home directory under all operating systems including Windows.
+
+* **Special Python note**:  When `.python` is used with an executable code
+  block without specifying an `executable`, code will run with `python3` if
+  either of these conditions is met:
+
+    - `python3` exists on the system and `python` is equivalent to `python2`.
+
+    - `python` does not exist on the system, but `python3` does exist.
+
+  To avoid ambiguity, you may want to use `.python3` and `.python2` rather
+  than `.python` when working with operating systems other than Windows, or
+  when working with a Windows installation that includes a `python3`
+  executable or symlink.  It is also possible to be even more specific by
+  using something like `.python3.8`.
+
+Each code block is executed in its own process, so data and variables are not
+shared between code blocks.
+
+If an executable code block generates multiple questions that are identical,
+or multiple choices for a single question that are identical, this will be
+detected by `text2qti` and an error will be reported.  Questions or choices
+that may be equivalent, but are not represented by exactly the same text,
+cannot be detected (for example, things like `100` versus `1e2`, or `answer`
+versus `Answer`).
+
+
+### Additional quiz options
+
+There are additional quiz options that can be set immediately after the quiz
+title and quiz description.  These all take values `true` or `false`.  For
+example, `shuffle answers: true` could be on the line right after the quiz
+description.
+
+* `shuffle answers` — Shuffle answer order for questions.
+* `show correct answers` — Show correct answers after submission.
+* `one question at a time` — Only show one question at a time.
+* `can't go back` — Don't allow going back to the previous question when in
+  `one question at a time` mode.
+
+
+
+
+## Details for writing quiz text
+
+text2qti processes almost all text as
+[Markdown](https://daringfireball.net/projects/markdown/), using
+[Python-Markdown](https://python-markdown.github.io/).  (The only exceptions
+are the quiz title, question titles, and text region titles, which are
+processed as plain text due to the QTI format, plus the acceptable answers
+for short-answer questions.)  For example, `*emphasized*` produces *emphasized*
+text, which typically appears as italics.  Text can be styled using Markdown
+notation, or with HTML.  Remember to preview quizzes after conversion to QTI,
+especially when using any significant amount of HTML.
+
+Python-Markdown provides several
+[extensions to basic Markdown](https://python-markdown.github.io/extensions/).
+Currently, the following extensions are enabled:
+* `smarty`:  Automatic curly quotation marks and dashes.
+* `sane_lists`:  List behavior is closer to what might be expected.
+* `def_list`:  Definition lists of this form:
+  ```
+  term
+  :   definition
+* `fenced_code`:  Fenced code blocks (` ``` ` or `~~~`).
+* `footnotes`:  Footnotes using this form:
+  ```
+  Normal text [^1].
+
+  [^1]: Footnote text.
+* `tables`:  Tables of this form:
+  ```
+  Header | Header
+  ------ | ------
+  Cell   | Cell
+  Cell   | Cell
+  ```
+* `md_in_html`:  Text inside HTML tags is treated as Markdown.  This requires
+  setting the attribute `markdown="1"` in the opening tag for block-level
+  elements.  See the
+  [documentation](https://python-markdown.github.io/extensions/md_in_html/)
+  for more details about proper usage and potential issues.
+
+While indented Markdown code blocks are supported, fenced code blocks should
+be preferred.  Indented code can interfere with the preprocessor that strips
+HTML comments and handles LaTeX math and siunitx notation.
+
+
+### Titles
+
+Quiz, question, and text region titles are limited to a single paragraph.  If
+this paragraph is wrapped over multiple lines, all lines after the first must
+be indented by at least two spaces or one tab, and share the same indentation.
+All tabs are expanded to 4 spaces before indentation is compared, following
+the typical Markdown approach.
+
+All titles are treated as plain text, not Markdown, due to the QTI format.
+
+Titles are always optional, but when they are used for a given element, they
+are always required to be first, before any other attributes.
+
+
+### Descriptions, questions, choices, feedback, and text regions
+
+Descriptions, questions, choices, feedback, and text regions may span multiple
+paragraphs and include arbitrary Markdown content like code blocks or
+quotations.  Everything must be indented to at least the same level as the
+start of the first paragraph on the initial line.  All tabs are expanded to 4
+spaces before indentation is compared, following the typical Markdown
+approach.  For example,
+```
+1.  A question paragraph that is long enough to wrap onto a second line.
+    The second line must be indented to match up with the start of the
+    paragraph text on the first line.
+
+    Another paragraph.
+```
+Note that the acceptable answers for short-answer questions are treated as
+plain text and limited to a single line, and numerical answers are also
+processed specially and limited to a single line.
+
+
+### Images
+
+Images are included with the standard Markdown syntax:
+```
+![alt_text](image_file)
+```
+It will typically be easiest to put your image files in the same folder or
+directory as the quiz file, so you can use something like `![alt](image.jpg)`.
+However, file paths are supported, including `~` user expansion under all
+operating systems.  All image paths not starting with `http://` or `https://`
+are assumed to refer to local image files (files on your machine), and will
+result in errors if these files are not found.
+
+[Pandoc-style attributes](https://pandoc.org/MANUAL.html#images) can be used
+with images:
+```
+![alt_text](image_file){#id .class1 .class2 width=10em height=5em}
+```
+This allows image id, classes, and dimensions to be specified without
+resorting to HTML.
+
+
+### LaTeX
+
+By default, text2qti supports LaTeX using a Canvas LaTeX rendering URL.  This
+can be set during installation, or by editing the configuration file
+`.text2qti.bespon` in your home or user directory.  It is possible to convert
+LaTeX to MathML instead with the `--pandoc-mathml` command-line option.  This
+requires that [Pandoc](https://pandoc.org/) be installed for converting LaTeX
+to MathML.  For example, to create a quiz you might run a command like this:
+```
+text2qti --pandoc-mathml quiz.txt
+```
+When `--pandoc-mathml` is used, a cache file `_text2qti_cache.zip` will be
+created in the quiz file directory.  This is used to store Pandoc MathML
+output to increase performance for long quizzes with lots of math.
+
+text2qti supports inline LaTeX math within dollar signs `$`.  There must be a
+non-space character immediately after the opening `$` and immediately before
+the closing `$`.  For example, `$F = ma$`.  LaTeX math is limited to what is
+supported by Canvas or whatever other educational software you are using.  It
+is usually a good idea to preview imported quizzes before assigning them,
+because text2qti cannot detect LaTeX incompatibilities or limitations.  There
+is currently not support for block LaTeX math; only inline math is supported.
+
+When using Canvas with LaTeX math, be aware that in some cases Canvas's
+vertical alignment of math leaves much to be desired.  Sometimes this can be
+improved by including `\vphantom{fg}` or `\strut` at the beginning of an
+equation.  An alternative is simply to use LaTeX for all question or choice
+text (via `\text`, etc.).
+
+text2tqi supports a limited subset of LaTeX
+[siunitx](https://ctan.org/pkg/siunitx) notation.  You can use notation like
+`\num{1.23e5}` to enter numbers in scientific notation.  This would result in
+`1.23×10⁵`.  You can use notation like `\si{m/s}` or `\si{N.m}` to enter
+units.  These would result in `m/s` and `N·m`.  Unit macros currently are not
+supported, with these exceptions: `\degree`, `\celsius`, `\fahrenheit`,
+`\ohm`, `\micro`.  Finally, numbers and units can be combined with notation
+like `\SI{1.23e5}{m/s}`.  All of these can be used inside or outside LaTeX
+math.
+
+Technical note: LaTeX and siunitx support are currently implemented as
+preprocessors that are used separately from Python-Markdown.  In rare cases,
+this may lead to conflicts with Markdown syntax.  These features may be
+reimplemented as Python-Markdown extensions in the future.
+
+
+### Comments
+
+There are multiple ways to add comments within a quiz file.  In all cases,
+comments are completely removed during quiz creation and do not appear in the
+final quiz in any form.
+
+At the top level of a quiz document (outside of questions, choices, or
+feedback) there are two types of comments.  These comments cannot be indented.
+* Line comments:  Any line that starts with a percent sign `%` is discarded.
+* Multiline comments:  If a line starts with `COMMENT`, that line and all
+  subsequent lines are discarded through a line that starts with
+  `END_COMMENT`.  The `COMMENT` and `END_COMMENT` delimiters must be on lines
+  by themselves; otherwise, an error is raised.
+
+Within Markdown text, standard HTML comments of the form `<!--comment-->` may
+be used.  These are stripped out during processing and do not appear in the
+final QTI file.  HTML comments are not supported within LaTeX math.
+
+Technical note:  HTML comments are currently stripped in a preprocessing step
+separate from Python-Markdown.  In rare cases, this may conflict with raw HTML
+embedded in Markdown.  This feature may be reimplemented as a Python-Markdown
+extension in the future.
+
+
+
+## Export solutions to PDF and HTML
+
+There is basic support for exporting quiz solutions in Pandoc Markdown, PDF,
+and HTML formats.  This is currently only available in the command-line
+application.  Solutions exported as Pandoc Markdown are only suitable for use
+with LaTeX and HTML.  Exporting solutions as PDF requires
+[Pandoc](https://pandoc.org/) and a LaTeX installation (such as [TeX
+Live](https://www.tug.org/texlive/) or [MiKTeX](https://miktex.org/)).  There
+is currently no built-in support for customizing export, although you can edit
+the Pandoc Markdown output before processing it via Pandoc.
+
+To save solutions and also create a QTI file, use
+`--solutions <solutions_file>`.  To save solutions without creating a QTI
+file, use `--only-solutions <solutions_file>`.  `<solutions_file>` must have
+an `.md` or `.markdown` extension for Pandoc Markdown export, `.pdf` for PDF
+export, or `.html` for HTML export.  `--solutions` and `--only-solutions` can
+be used multiple times to generate solutions in multiple formats.
+
+When using `--only-solutions`, be aware that solutions and QTI may differ if
+executable code blocks generate problems using random numbers. Consider
+creating solutions and QTI at the same time (`--solutions`), or setting a seed
+for the random number generator so it is reproducible.
+
+
+### Customizing questions for solutions
+
+Each question can provide a solution or other important information that is
+*only* included in the solutions, *never* in the QTI.  This is particularly
+useful for essay and upload questions, since they are defined without
+specifying an answer and require manual grading.  For example,
+```
+1.  Write an essay about text2qti.
+
+!   This is important information about what the essay should cover.
+
+    This will only appear in the solutions, and can be as long or short as
+    you wish.
+
+____
+```
+The syntax for a question solution is the same as that for question feedback,
+except that an exclamation point `!` is used instead of `...` or `+` or `-`.
+
+
+### Quiz options
+
+At the beginning of a quiz, there are some quiz-level options that can be set
+to customize solutions.  These all take `true`/`false` values, and are `false`
+by default.  For example, add `solutions sample groups: true` at the beginning
+of a quiz.
+
+* `feedback is solution` — This disables the special question solution syntax
+  involving `!`, and treats general question feedback (`...`) as both feedback
+  and solution.  This is useful when you want to give students solution
+  information as part of the QTI feedback and also include this same
+  information in solutions.
+
+* `solutions sample groups` — By default, *all* questions in a question group
+  are included in solutions, with a notice about the number that are randomly
+  selected when the quiz is taken, unless the question group has `solutions
+  pick` set to use a different value.
+
+  This option causes only a sample of the questions in a group to be included
+  in the solutions.  This option displays the first N questions in a group
+  sequentially, where N is the group `solutions pick` value if it has been
+  set, and otherwise the `pick` value if it has been set, and otherwise 1.  It
+  is possible for solutions to include N random questions from a group instead
+  of the first N questions; see `solutions randomize groups`.
+
+* `solutions randomize groups` — For each question group, randomize the order
+  in which questions are displayed in solutions.  If only some questions from
+  a group are included in solutions (`solutions sample groups` is `true` or
+  `solutions pick` is set), also randomize which questions are displayed
+  instead of taking all displayed questions sequentially from the beginning of
+  the group.
+
+  Randomization is not used by default for two reasons that relate to quizzes
+  using `solutions pick` or `solutions sample groups`.  First, including group
+  questions sequentially allows specially chosen, representative questions to
+  be placed at the beginning of the group so that they will appear in
+  solutions.  If a group contains many questions that are generated by an
+  executable code block, a random selection might not provide a sample that is
+  representative.  Second, if a quiz is used several semesters or years in a
+  row with only minor modifications, and new randomized solutions are
+  distributed each time, this means that eventually all questions would be
+  distributed in solutions, rather than only a fixed subset.
+
+
+### Customizing groups for solutions
+
+When a quiz is taken, the number of questions randomly selected from a
+question group is the value of `pick` if `pick` is set for the group and
+otherwise 1.  However, by default solutions will include *all* questions from
+a group.  There are two ways to modify this.
+
+It is possible to modify the number of questions displayed in solutions for a
+specific group by setting `solutions pick` for the group.  This causes only
+the specified number of questions from the group to be displayed in solutions.
+The questions that are displayed are taken sequentially from the beginning of
+the group by default, with no randomization.  For randomization, see the
+quiz-level option `solutions randomize groups`.
+
+It is also possible to modify the number of questions displayed in solutions
+for *all* groups in a quiz by setting the quiz-level option `solutions sample
+groups` to `true`.  This option displays the first N questions in a group
+sequentially, where N is the group `solutions pick` value if it has been set,
+and otherwise the `pick` value if it has been set, and otherwise 1.  It is
+possible for solutions to include N random questions from a group instead of
+the first N questions; see `solutions randomize groups`.
+
+In the example below, the solutions would include 2 questions from the group,
+even though only 1 is displayed when the quiz is taken.  The first 2 questions
+would be included in solutions, unless `solutions randomize groups: true` is
+included at the beginning of the quiz.
+
+```
+GROUP
+pick: 1
+solutions pick: 2
+
+1.  A question.
+*a) true
+b)  false
+
+2.  Another question.
+*a) true
+b)  false
+
+3.  Yet another question.
+*a) true
+b)  false
+
+END_GROUP
+```
+

app.py

@@ -0,0 +1,77 @@
+import streamlit as st
+import text2qti
+import traceback
+import subprocess
+import os
+
+def convert_txt_to_qti(file_path):
+    # Use subprocess to run the text2qti command
+    output_file = file_path.replace('.txt', '.zip')
+    try:
+        subprocess.run(["text2qti", file_path], check=True, capture_output=True, text=True)
+        return output_file, None
+    except subprocess.CalledProcessError as e:
+        # Capture the stderr output
+        error_message = e.stderr.strip() if e.stderr else "An error occurred without any specific error message."
+        return None, error_message
+
+def main():
+    st.title("text2qti Converter")
+
+    st.markdown("""
+        For help or more information about how to generate/format .txt files for conversion and upload to Canvas, please visit the [following walk-through guide.](https://reutherlab.biosci.ucsd.edu/)
+    """)
+    
+    uploaded_file = st.file_uploader("Upload a .txt file", type=["txt"])
+
+    if uploaded_file:
+        # Extract the filename without the extension
+        file_name = os.path.splitext(uploaded_file.name)[0]
+
+        # Save the uploaded file to a location with the same name
+        temp_file_path = f"{file_name}.txt"
+        with open(temp_file_path, "wb") as f:
+            f.write(uploaded_file.getbuffer())
+
+        st.write("File uploaded successfully!")
+
+        # Button to initiate the conversion
+        if st.button('Convert to QTI'):
+            try:  
+                qti_zip_file, error = convert_txt_to_qti(temp_file_path)
+                if qti_zip_file and os.path.exists(qti_zip_file):
+                    with open(qti_zip_file, "rb") as f:
+                        zip_data = f.read()
+                    st.download_button(f'Download {file_name}.zip', zip_data, file_name=f'{file_name}.zip', mime='application/zip')
+                else:
+                    # If the conversion failed, display the error message
+                    error_message = (f"""Failed to convert the file. You will see a long, confusing error. **Focus on the part that provides a line number and text from the quiz itself. it will often be near the end of the error message.**  
+                                     ---  
+                                     **Here is an made-up example of what you should look for:**  
+                                     In test_quiz_error.txt on line 23: Syntax error; unexpected text, or incorrect indentation for a wrapped paragraph: #a) Polar heads face outward, nonpolar tails face inward  
+                                     This would indicate that there is an error on line 23 of the quiz. You need to change #a) to \*a) to fix the error.     
+                                     Please visit the walkthrough linked above for more information.  
+                                     ---  
+                    **Your error:**  
+                                     {error}") 
+                    """)
+                    st.markdown(error_message)
+            except Exception as e:
+                # Catch any other exception that might occur and display it using traceback
+                error_traceback = traceback.format_exc()
+                st.error(f"An unexpected error occurred: {error_traceback}") 
+
+
+    # Footer
+    st.markdown("---")
+    st.markdown("""
+        The text2qti python library is Copyright (c) 2020 by Geoffrey M. Poore. 
+        It can be found at [https://github.com/gpoore/text2qti](https://github.com/gpoore/text2qti) 
+        and is distributed under the BSD 3-Clause License.
+    """)
+    st.markdown("""
+        This app is managed by Keefe Reuther - [https://reutherlab.biosci.ucsd.edu/](https://reutherlab.biosci.ucsd.edu/)
+    """)
+
+if __name__ == "__main__":
+    main()

make_gui_exe/README.md

@@ -0,0 +1,35 @@
+# Create Standalone GUI Executable for Windows
+
+This directory contains scripts for creating a standalone GUI executable under
+Windows with PyInstaller.
+
+
+
+## Requirements
+
+* Windows
+* [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/)
+
+
+
+## Directions
+
+If you do not already have a local copy of the text2qti source, download
+`make_tk_exe.bat` and `text2qti_tk.pyw`, and place them in the same directory.
+Double-click on `make_tk_exe.bat` to run it.  Or open a command prompt,
+navigate to `make_gui_exe/` (or wherever the batch file is located), and run
+the batch file.  Under PowerShell, run something like
+`cmd /c make_gui_exe.bat`.
+
+The batch file performs these steps:
+* Create a new conda environment for building the executable.
+* Activate the conda environment.
+* Install needed Python packages in the environment:  bespon, markdown,
+  pyinstaller, and text2qti.  If the batch file detects that it is part of a
+  local copy of the text2qti source, then this local version of text2qti will
+  be used.  Otherwise, text2qti will be installed from PyPI via pip.
+* Build executable `text2qti_tk_VERSION.exe` using PyInstaller.
+* Deactivate the conda environment.
+* Remove the conda environment.
+* Move the executable to the working directory.
+* Remove all temp files and build files.

make_gui_exe/make_tk_exe.bat

@@ -0,0 +1,47 @@
+REM This is intended to be run with the .bat file directory as the working dir
+if not exist make_tk_exe.bat (
+    echo Missing make_tk_exe.bat in working directory
+    pause
+    exit
+)
+if not exist text2qti_tk.pyw (
+    echo Missing text2qti_tk.pyw in working directory
+    pause
+    exit
+)
+
+REM Create and activate a conda env for packaging the .exe
+call conda create -y --name make_text2qti_gui_exe python=3.9 --no-default-packages
+call conda activate make_text2qti_gui_exe
+REM List conda envs -- useful for debugging
+call conda info --envs
+REM Install dependencies
+pip install bespon
+pip install markdown
+pip install pyinstaller
+if exist ..\setup.py (
+    if exist ..\text2qti (
+        cd ..
+        pip install .
+        cd make_gui_exe
+    ) else (
+        pip install text2qti
+    )
+) else (
+    pip install text2qti
+)
+REM Build .exe
+FOR /F "tokens=* USEBACKQ" %%g IN (`python -c "import text2qti; print(text2qti.__version__)"`) do (SET "TEXT2QTI_VERSION=%%g")
+pyinstaller -F --name text2qti_tk_%TEXT2QTI_VERSION% text2qti_tk.pyw
+REM Deactivate and delete conda env
+call conda deactivate
+call conda remove -y --name make_text2qti_gui_exe --all
+REM List conda envs -- useful for debugging
+call conda info --envs
+REM Cleanup
+move dist\text2qti_tk_%TEXT2QTI_VERSION%.exe text2qti_tk_%TEXT2QTI_VERSION%.exe
+rd /s /q "__pycache__"
+rd /s /q "build"
+rd /s /q "dist"
+del *.spec
+pause

make_gui_exe/text2qti_tk.pyw

@@ -0,0 +1,2 @@
+import text2qti.gui.tk
+text2qti.gui.tk.main()

requirements.txt

@@ -1,3 +1 @@
-altair
-pandas
-streamlit
+text2qti

setup.cfg

@@ -0,0 +1,6 @@
+[metadata]
+license_file = LICENSE.txt
+
+
+[tool:pytest]
+norecursedirs = build

setup.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+import sys
+if sys.version_info < (3, 6):
+    sys.exit('text2qti requires Python 3.6+')
+import pathlib
+from setuptools import setup, find_packages
+
+
+
+
+# Extract the version from version.py, using functions in fmtversion.py
+fmtversion_path = pathlib.Path(__file__).parent / 'text2qti' / 'fmtversion.py'
+exec(compile(fmtversion_path.read_text(encoding='utf8'), 'text2qti/fmtversion.py', 'exec'))
+version_path = pathlib.Path(__file__).parent / 'text2qti' / 'version.py'
+version = get_version_from_version_py_str(version_path.read_text(encoding='utf8'))
+
+readme_path = pathlib.Path(__file__).parent / 'README.md'
+long_description = readme_path.read_text(encoding='utf8')
+
+
+setup(name='text2qti',
+      version=version,
+      py_modules=[],
+      packages=find_packages(),
+      package_data = {},
+      description='Create quizzes in QTI format from Markdown-based plain text',
+      long_description=long_description,
+      long_description_content_type='text/markdown',
+      author='Geoffrey M. Poore',
+      author_email='gpoore@gmail.com',
+      url='http://github.com/gpoore/text2qti',
+      license='BSD',
+      keywords=['QTI', 'IMS Question & Test Interoperability', 'quiz', 'test',
+          'exam', 'assessment', 'markdown', 'LaTeX', 'plain text'],
+      python_requires='>=3.6',
+      install_requires=[
+          'bespon>=0.4',
+          'markdown>=3.2',
+      ],
+      # https://pypi.python.org/pypi?:action=list_classifiers
+      classifiers=[
+          'Development Status :: 4 - Beta',
+          'Environment :: Console',
+          'Intended Audience :: Education',
+          'License :: OSI Approved :: BSD License',
+          'Operating System :: OS Independent',
+          'Programming Language :: Python :: 3.6',
+          'Programming Language :: Python :: 3.7',
+          'Programming Language :: Python :: 3.8',
+          'Topic :: Education :: Testing',
+      ],
+      entry_points = {
+          'console_scripts': ['text2qti = text2qti.cmdline:main'],
+          'gui_scripts': ['text2qti_tk = text2qti.gui.tk:main'],
+      },
+)

temp.txt

@@ -0,0 +1,59 @@
+Quiz title: Quiz 7 extra questions
+Quiz description: Delve deeper into the world of genetics by understanding the role of statistics in data interpretation and exploring the intricacies of Mendelian inheritance.
+
+Title: P-Values in Hypothesis Testing
+Points: 1
+2. A p-value of 0.05 in a scientific study typically means:
+... A p-value of 0.05 means that there is a 5% chance of observing the given results, or more extreme results, if the null hypothesis is true. It is a common threshold for statistical significance.
+a) There is definitely a difference between comparison groups.
+*b) There is a 5% chance of getting a test statistic at least as big as observed in your data if the null hypothesis is true
+c) There is a 95% chance that the alternative hypothesis is true
+d) The results are never statistically significant
+
+Title: Multiple Answer - False Positives and Negatives
+Points: 1
+4. In the context of diagnostic tests (e.g., a COVID-19 or breast cancer test), what consequences can false positives and false negatives have?
+... False positives can lead to unnecessary treatment or distress, while false negatives can result in a lack of treatment for a disease that is actually present.
+[*] False positives can lead to unnecessary treatment or emotional distress
+[ ] False negatives can lead to unnecessary treatment or emotional distress
+[ ] False positives are always better than false negatives.
+[*] False negatives can result in a lack of treatment for a disease that is present
+[ ] False positive can result in a lack of treatment for a disease that is present
+[ ] False negatives are always better than false positives.
+[ ] False positives and false negatives are not a concern in diagnostic tests since they are rare and we can never fully eliminate error.
+
+Title: Complete Dominance Basis
+Points: 1
+6. At the cellular level, what does complete dominance in Mendelian genetics typically reflect?
+... Complete dominance usually stems from the functionality of the gene product, where one allele produces a functional protein, while the other does not.
+*a) The presence of one functional allele compensates for a non-functional allele.
+b) Both alleles produce functional proteins in equal quantities.
+c) The dominant allele suppresses the expression of other genes.
+d) Both alleles are necessary for a complete phenotypic expression.
+
+Title: ABO Blood Type System
+Points: 1
+7. In the ABO blood group system, which phenomenon explains the simultaneous expression of both A and B antigens in individuals?
+... Codominance allows for both alleles to express their phenotypes fully when present.
+*a) Codominance
+b) Incomplete dominance
+c) Epistasis
+d) Pleiotropy
+
+Title: Impacts of Lethal Alleles
+Points: 1
+8. How do lethal alleles influence Mendelian ratios in genetic crosses?
+... Lethal alleles can cause death when homozygous, leading to deviations from the expected Mendelian phenotypic ratios.
+*a) They can cause death in homozygous individuals, leading to a lack of that genotype in the offspring.
+b) They prevent any form of genetic crossing.
+c) They introduce mutations into the genetic code.
+d) They always result in a dominant phenotype.
+
+Title: Epistasis and Phenotypic Outcomes
+Points: 1
+9. How does epistasis influence the phenotypic outcomes of genetic crosses?
+... Epistasis occurs when the alleles of one gene mask or modify the expression of another gene, thereby influencing the phenotypic outcomes of genetic crosses.
+*a) It can mask or modify the expression of another gene, altering expected phenotypic results.
+b) It increases the mutation rate in the offspring.
+c) It leads to incomplete dominance of one gene over another.
+d) It ensures that Mendelian ratios are always maintained.

temp.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:13fc67d7538c5aef01c94679e3077dfc707bd26cc703f536906a4acd5b7d1f3d
+size 6896

test_quiz.txt

@@ -0,0 +1,143 @@
+Quiz title: Introduction to Cell Biology – Quiz 2
+Quiz description: An examination of the key concepts in cell biology, including cell types, membrane structure, transport mechanisms, energy metabolism, and enzymatic reactions.
+
+Title: Learn with integrity
+Points: 1
+1. I agree to complete this quiz without the aid of others or AI. I agree not to discuss questions and answers of the quiz until the quiz key is posted. Anything otherwise is a breach of my Academic Integrity and subject to the policies of the University.
+*a) I agree
+b) I disagree
+
+Title: Comparing Prokaryotic and Eukaryotic Cells
+Points: 1
+2. Which of the following statements best distinguishes eukaryotic cells from prokaryotic cells?
+... Eukaryotic cells contain membrane-bound organelles, including a nucleus, while prokaryotic cells lack these structures.
+a) Only eukaryotic cells have a plasma membrane
+*b) Eukaryotic cells contain membrane-bound organelles, while prokaryotic cells do not
+c) Prokaryotic cells contain more DNA than eukaryotic cells
+d) Only prokaryotic cells contain ribosomes
+
+Title: Phospholipids in Cell Membranes
+Points: 1
+3. How do the polar and nonpolar ends of phospholipids interact in water to create the bilayer structure of cell membranes?
+... The polar (hydrophilic) heads face outward, interacting with water, while the nonpolar (hydrophobic) tails face inward, away from water, forming a bilayer.
+*a) Polar heads face outward, nonpolar tails face inward
+b) Polar heads face inward, nonpolar tails face outward
+c) Polar and nonpolar ends mix randomly
+d) Polar ends repel each other, forming a single layer
+
+Title: Diffusion and Entropy
+Points: 1
+4. Why does diffusion not require work and lead to passive transport?
+... Diffusion is the movement of molecules from an area of high concentration to low, driven by random motion, increasing entropy. It doesn't require energy input, aligning with the second law of thermodynamics.
+*a) Diffusion increases entropy and is driven by random motion
+b) Diffusion requires energy to move molecules against concentration gradients
+c) Diffusion decreases entropy by organizing molecules
+d) Diffusion is driven by active transport proteins
+
+Title: Tonicity and Animal Cells
+Points: 1
+5. What would happen to an animal cell if placed in a hypertonic solution?
+... In a hypertonic solution, the solute concentration is higher outside the cell, causing water to move out of the cell, leading to cell shrinkage or crenation.
+*a) The cell would shrink due to water loss
+b) The cell would swell due to water intake
+c) The cell would remain unchanged in size
+d) The cell would undergo lysis
+
+Title: Functions of Smooth ER and Rough ER
+Points: 1
+6. How do the functions of smooth endoplasmic reticulum (ER) and rough ER differ in a eukaryotic cell?
+... Smooth ER is involved in lipid synthesis and detoxification, while rough ER, studded with ribosomes, is involved in protein synthesis and processing.
+*a) Smooth ER synthesizes lipids; Rough ER synthesizes proteins
+b) Smooth ER synthesizes proteins; Rough ER synthesizes lipids
+c) Both Smooth and Rough ER are primarily involved in protein synthesis
+d) Both Smooth and Rough ER are primarily involved in lipid synthesis
+
+Title: Origins of Chloroplasts and Mitochondria
+Points: 1
+7. According to the endosymbiotic theory, how did chloroplasts and mitochondria originate?
+... The endosymbiotic theory proposes that chloroplasts and mitochondria originated from free-living bacteria that were engulfed by ancestral eukaryotic cells.
+*a) They originated from free-living bacteria joining with ancestral eukaryotic cells
+b) They originated from viral infections
+c) They were synthesized within the host cell
+d) They developed independently in eukaryotic cells just like the nucleus.
+
+Title: Osmosis and Water Concentration
+Points: 1
+8. How can you predict the movement of water based on solute concentration?
+... Water moves from areas of low solute concentration (high water concentration) to areas of high solute concentration (low water concentration) by osmosis.
+*a) Water moves from low solute to high solute concentration
+b) Water moves from high solute to low solute concentration
+c) Water moves randomly without regard to solute concentration
+d) Water movement is determined by temperature, not solute concentration
+
+Title: Facilitated Diffusion vs. Active Transport
+Points: 1
+9. What distinguishes facilitated diffusion from active transport in cell membrane transport?
+... Facilitated diffusion is passive and moves substances down their concentration gradient without energy input, while active transport requires energy to move substances against their gradient.
+*a) Facilitated diffusion is passive; Active transport requires energy
+b) Facilitated diffusion requires energy; Active transport is passive
+c) Both facilitated diffusion and active transport require energy
+d) Both facilitated diffusion and active transport are passive processes
+
+Title: Bound vs. Free Ribosomes
+Points: 1
+10. How do bound and free ribosomes differ in terms of the destination of the proteins they synthesize?
+... Bound ribosomes synthesize proteins that are incorporated into membranes or exported from the cell, while free ribosomes synthesize proteins that function within the cytosol.
+*a) Bound ribosomes synthesize membrane or exported proteins; Free ribosomes synthesize proteins destined for the cytoplasm
+b) Bound ribosomes synthesize proteins destined for the cytoplasm; Free ribosomes synthesize membrane proteins
+c) Both bound and free ribosomes synthesize exported proteins
+d) Both bound and free ribosomes synthesize proteins destined for the cytoplasm
+
+Title: Lysosomal Storage Disease
+Points: 1
+11. Lysosomal storage diseases are often the result of a specific enzyme not working, leading to an inability to break down and recycle a cellular waste product. Which of the following scenarios would likely be associated with a lysosomal storage disease?
+... Lysosomal storage diseases occur when there is a deficiency in an enzyme needed to break down a specific waste product, leading to its accumulation within lysosomes. This can result in cell damage and various symptoms.
+a) A deficiency in an enzyme required in the gut for sucrose digestion.
+b) An overproduction of a hormone regulating blood pressure
+*c) A deficiency in an enzyme required to break down a specific cellular waste product, leading to its accumulation.
+d) An overproduction of a gene responsible for cell growth
+
+Title: Regulation of Exergonic Reactions
+Points: 1
+12. Why don't exergonic reactions in our bodies happen quickly and spontaneously in a totally unregulated manner?
+... Exergonic reactions are thermodynamically favorable and release energy, but in biological systems, they are often controlled by enzymes and other regulatory mechanisms to ensure proper timing and coordination within metabolic pathways.
+*a) They are prevented by transition states and high activation energies, that can only be lowered with enzymes.
+b) They require energy input to proceed. Endergonic reactions are spontaneous.
+c) They don't ever increase entropy, so it would require lots of work to get them going.
+d) They are inhibited by high temperatures
+
+Title: Reaction Rates and Temperature or Substrate Concentration
+Points: 1
+13. What happens to reaction rates when you change the temperature or concentration of substrate/reactants?
+... Increasing the temperature generally accelerates reaction rates by providing more kinetic energy to the molecules. Increasing the concentration of substrate or reactants often enhances the reaction rate by increasing the frequency of collisions between molecules.
+*a) Increasing temperature and substrate/reactant concentration generally accelerates reaction rates
+b) Increasing temperature slows down reaction rates; increasing substrate/reactant concentration accelerates reaction rates
+c) Increasing temperature accelerates reaction rates; increasing substrate/reactant concentration slows down reaction rates
+d) Increasing temperature and substrate/reactant concentration generally slows down reaction rates
+
+Title: Fatty Acid Tails of Phospholipids and Water Interaction
+Points: 1
+14. Why do the fatty acid tails of phospholipids prefer not to interact with water?
+... The fatty acid tails of phospholipids are hydrophobic (nonpolar) and therefore tend to avoid interaction with water, which is a polar molecule. In a bilayer, they orient inward, away from the water, minimizing their contact with it.
+*a) They are hydrophobic and avoid interaction with polar water molecules
+b) They form hydrogen bonds with water
+c) They are hydrophilic and attract water molecules
+d) They dissolve in water, leading to membrane disintegration
+
+Title: Essay - ATP's Role in Metabolic Reactions
+Points: 2
+15. Explain how ATP functions in both anabolic and catabolic metabolic reactions.
+... ATP serves as the primary energy currency in cells, linking catabolic reactions that release energy with anabolic reactions that consume energy. Its hydrolysis provides the energy needed for various cellular functions, driving both the synthesis and breakdown of molecules.
+_________
+
+Title: Essay - Endomembrane System Pathway
+Points: 2
+16. Describe the pathway a single amino acid might take through the endomembrane system if it was destined to travel the blood stream throughout the body. Begin your story at the ribosome and end it at the plasma membrane.
+... The endomembrane system is a complex network within eukaryotic cells, involving the synthesis, modification, and transport of proteins. The pathway includes the smooth ER for lipid synthesis, rough ER for protein synthesis, the Golgi apparatus for modification, and lysosomes for degradation.
+_________
+
+Title: Personal Reflection on Learning
+Points: 2
+17. Share one thing you learned this week that wasn't directly mentioned in this quiz. Be specific in your explanation, and teach me about this concept or idea as if I were a fellow student.
+... Reflecting on what you've learned and teaching it to others can deepen your understanding and retention. Whether it's a novel concept, a fascinating fact, or a new perspective, I'm eager to learn from you!
+_________

test_quiz.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2d5dbb85d30c59012c52c178ccc49928312b9a1e2c7c4fe6946a0da24c73a40f
+size 11546

test_quiz_error.txt

@@ -0,0 +1,143 @@
+Quiz title: Introduction to Cell Biology – Quiz 2
+Quiz description: An examination of the key concepts in cell biology, including cell types, membrane structure, transport mechanisms, energy metabolism, and enzymatic reactions.
+
+Title: Learn with integrity
+Points: 1
+1. I agree to complete this quiz without the aid of others or AI. I agree not to discuss questions and answers of the quiz until the quiz key is posted. Anything otherwise is a breach of my Academic Integrity and subject to the policies of the University.
+*a) I agree
+b) I disagree
+
+Title: Comparing Prokaryotic and Eukaryotic Cells
+Points: 1
+2. Which of the following statements best distinguishes eukaryotic cells from prokaryotic cells?
+... Eukaryotic cells contain membrane-bound organelles, including a nucleus, while prokaryotic cells lack these structures.
+a) Only eukaryotic cells have a plasma membrane
+*b) Eukaryotic cells contain membrane-bound organelles, while prokaryotic cells do not
+c) Prokaryotic cells contain more DNA than eukaryotic cells
+d) Only prokaryotic cells contain ribosomes
+
+Title: Phospholipids in Cell Membranes
+Points: 1
+3. How do the polar and nonpolar ends of phospholipids interact in water to create the bilayer structure of cell membranes?
+... The polar (hydrophilic) heads face outward, interacting with water, while the nonpolar (hydrophobic) tails face inward, away from water, forming a bilayer.
+#a) Polar heads face outward, nonpolar tails face inward
+b) Polar heads face inward, nonpolar tails face outward
+c) Polar and nonpolar ends mix randomly
+d) Polar ends repel each other, forming a single layer
+
+Title: Diffusion and Entropy
+Points: 1
+4. Why does diffusion not require work and lead to passive transport?
+... Diffusion is the movement of molecules from an area of high concentration to low, driven by random motion, increasing entropy. It doesn't require energy input, aligning with the second law of thermodynamics.
+*a) Diffusion increases entropy and is driven by random motion
+b) Diffusion requires energy to move molecules against concentration gradients
+c) Diffusion decreases entropy by organizing molecules
+d) Diffusion is driven by active transport proteins
+
+Title: Tonicity and Animal Cells
+Points: 1
+5. What would happen to an animal cell if placed in a hypertonic solution?
+... In a hypertonic solution, the solute concentration is higher outside the cell, causing water to move out of the cell, leading to cell shrinkage or crenation.
+*a) The cell would shrink due to water loss
+b) The cell would swell due to water intake
+c) The cell would remain unchanged in size
+d) The cell would undergo lysis
+
+Title: Functions of Smooth ER and Rough ER
+Points: 1
+6. How do the functions of smooth endoplasmic reticulum (ER) and rough ER differ in a eukaryotic cell?
+... Smooth ER is involved in lipid synthesis and detoxification, while rough ER, studded with ribosomes, is involved in protein synthesis and processing.
+*a) Smooth ER synthesizes lipids; Rough ER synthesizes proteins
+b) Smooth ER synthesizes proteins; Rough ER synthesizes lipids
+c) Both Smooth and Rough ER are primarily involved in protein synthesis
+d) Both Smooth and Rough ER are primarily involved in lipid synthesis
+
+Title: Origins of Chloroplasts and Mitochondria
+Points: 1
+7. According to the endosymbiotic theory, how did chloroplasts and mitochondria originate?
+... The endosymbiotic theory proposes that chloroplasts and mitochondria originated from free-living bacteria that were engulfed by ancestral eukaryotic cells.
+*a) They originated from free-living bacteria joining with ancestral eukaryotic cells
+b) They originated from viral infections
+c) They were synthesized within the host cell
+d) They developed independently in eukaryotic cells just like the nucleus.
+
+Title: Osmosis and Water Concentration
+Points: 1
+8. How can you predict the movement of water based on solute concentration?
+... Water moves from areas of low solute concentration (high water concentration) to areas of high solute concentration (low water concentration) by osmosis.
+*a) Water moves from low solute to high solute concentration
+b) Water moves from high solute to low solute concentration
+c) Water moves randomly without regard to solute concentration
+d) Water movement is determined by temperature, not solute concentration
+
+Title: Facilitated Diffusion vs. Active Transport
+Points: 1
+9. What distinguishes facilitated diffusion from active transport in cell membrane transport?
+... Facilitated diffusion is passive and moves substances down their concentration gradient without energy input, while active transport requires energy to move substances against their gradient.
+*a) Facilitated diffusion is passive; Active transport requires energy
+b) Facilitated diffusion requires energy; Active transport is passive
+c) Both facilitated diffusion and active transport require energy
+d) Both facilitated diffusion and active transport are passive processes
+
+Title: Bound vs. Free Ribosomes
+Points: 1
+10. How do bound and free ribosomes differ in terms of the destination of the proteins they synthesize?
+... Bound ribosomes synthesize proteins that are incorporated into membranes or exported from the cell, while free ribosomes synthesize proteins that function within the cytosol.
+*a) Bound ribosomes synthesize membrane or exported proteins; Free ribosomes synthesize proteins destined for the cytoplasm
+b) Bound ribosomes synthesize proteins destined for the cytoplasm; Free ribosomes synthesize membrane proteins
+c) Both bound and free ribosomes synthesize exported proteins
+d) Both bound and free ribosomes synthesize proteins destined for the cytoplasm
+
+Title: Lysosomal Storage Disease
+Points: 1
+11. Lysosomal storage diseases are often the result of a specific enzyme not working, leading to an inability to break down and recycle a cellular waste product. Which of the following scenarios would likely be associated with a lysosomal storage disease?
+... Lysosomal storage diseases occur when there is a deficiency in an enzyme needed to break down a specific waste product, leading to its accumulation within lysosomes. This can result in cell damage and various symptoms.
+a) A deficiency in an enzyme required in the gut for sucrose digestion.
+b) An overproduction of a hormone regulating blood pressure
+*c) A deficiency in an enzyme required to break down a specific cellular waste product, leading to its accumulation.
+d) An overproduction of a gene responsible for cell growth
+
+Title: Regulation of Exergonic Reactions
+Points: 1
+12. Why don't exergonic reactions in our bodies happen quickly and spontaneously in a totally unregulated manner?
+... Exergonic reactions are thermodynamically favorable and release energy, but in biological systems, they are often controlled by enzymes and other regulatory mechanisms to ensure proper timing and coordination within metabolic pathways.
+*a) They are prevented by transition states and high activation energies, that can only be lowered with enzymes.
+b) They require energy input to proceed. Endergonic reactions are spontaneous.
+c) They don't ever increase entropy, so it would require lots of work to get them going.
+d) They are inhibited by high temperatures
+
+Title: Reaction Rates and Temperature or Substrate Concentration
+Points: 1
+13. What happens to reaction rates when you change the temperature or concentration of substrate/reactants?
+... Increasing the temperature generally accelerates reaction rates by providing more kinetic energy to the molecules. Increasing the concentration of substrate or reactants often enhances the reaction rate by increasing the frequency of collisions between molecules.
+*a) Increasing temperature and substrate/reactant concentration generally accelerates reaction rates
+b) Increasing temperature slows down reaction rates; increasing substrate/reactant concentration accelerates reaction rates
+c) Increasing temperature accelerates reaction rates; increasing substrate/reactant concentration slows down reaction rates
+d) Increasing temperature and substrate/reactant concentration generally slows down reaction rates
+
+Title: Fatty Acid Tails of Phospholipids and Water Interaction
+Points: 1
+14. Why do the fatty acid tails of phospholipids prefer not to interact with water?
+... The fatty acid tails of phospholipids are hydrophobic (nonpolar) and therefore tend to avoid interaction with water, which is a polar molecule. In a bilayer, they orient inward, away from the water, minimizing their contact with it.
+*a) They are hydrophobic and avoid interaction with polar water molecules
+b) They form hydrogen bonds with water
+c) They are hydrophilic and attract water molecules
+d) They dissolve in water, leading to membrane disintegration
+
+Title: Essay - ATP's Role in Metabolic Reactions
+Points: 2
+15. Explain how ATP functions in both anabolic and catabolic metabolic reactions.
+... ATP serves as the primary energy currency in cells, linking catabolic reactions that release energy with anabolic reactions that consume energy. Its hydrolysis provides the energy needed for various cellular functions, driving both the synthesis and breakdown of molecules.
+_________
+
+Title: Essay - Endomembrane System Pathway
+Points: 2
+16. Describe the pathway a single amino acid might take through the endomembrane system if it was destined to travel the blood stream throughout the body. Begin your story at the ribosome and end it at the plasma membrane.
+... The endomembrane system is a complex network within eukaryotic cells, involving the synthesis, modification, and transport of proteins. The pathway includes the smooth ER for lipid synthesis, rough ER for protein synthesis, the Golgi apparatus for modification, and lysosomes for degradation.
+_________
+
+Title: Personal Reflection on Learning
+Points: 2
+17. Share one thing you learned this week that wasn't directly mentioned in this quiz. Be specific in your explanation, and teach me about this concept or idea as if I were a fellow student.
+... Reflecting on what you've learned and teaching it to others can deepen your understanding and retention. Whether it's a novel concept, a fascinating fact, or a new perspective, I'm eager to learn from you!
+_________

text2qti/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+from .version import __version__, __version_info__
+from .config import Config
+from .quiz import Quiz
+from .qti import QTI

text2qti/cmdline.py

@@ -0,0 +1,173 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020-2021, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+import argparse
+import os
+import pathlib
+import platform
+from re import sub
+import shutil
+import subprocess
+import textwrap
+from .version import __version__ as version
+from .err import Text2qtiError
+from .config import Config
+from .quiz import Quiz
+from .qti import QTI
+from .export import quiz_to_pandoc
+
+
+
+
+def main():
+    '''
+    text2qti executable main function.
+    '''
+    parser = argparse.ArgumentParser(prog='text2qti')
+    parser.set_defaults(func=lambda x: parser.print_help())
+    parser.add_argument('--version', action='version', version=f'text2qti {version}')
+    parser.add_argument('--latex-render-url',
+                        help='URL for rendering LaTeX equations')
+    parser.add_argument('--run-code-blocks', action='store_const', const=True,
+                        help='Allow special code blocks to be executed and insert their output (off by default for security)')
+    parser.add_argument('--pandoc-mathml', action='store_const', const=True,
+                        help='Convert LaTeX math to MathML using Pandoc (this will create a cache file "_text2qti_cache.zip" in the quiz file directory)')
+    soln_group = parser.add_mutually_exclusive_group()
+    soln_group.add_argument('--solutions', action='append', metavar='SOLUTIONS_FILE',
+                            help='Save solutions in Pandoc Markdown (.md), PDF (.pdf), or HTML (.html) format, and also create a QTI file. '
+                                 'Can be used multiple times to export multiple formats. '
+                                 'Pandoc Markdown output is only suitable for use with LaTeX or HTML; PDF output requires Pandoc plus LaTeX.')
+    soln_group.add_argument('--only-solutions', action='append', metavar='SOLUTIONS_FILE',
+                            help='Save solutions in Pandoc Markdown (.md), PDF (.pdf), or HTML (.html) format, but do not create a QTI file. '
+                                 'Can be used multiple times to export multiple formats. '
+                                 'Pandoc Markdown output is only suitable for use with LaTeX or HTML; PDF output requires Pandoc plus LaTeX. '
+                                 'With this option, solutions and QTI may differ if executable code blocks generate problems using random numbers. '
+                                 'Consider creating solutions and QTI together, or setting a seed for the random number generator so it is reproducible.')
+    parser.add_argument('file',
+                        help='File to convert from text to QTI')
+    args = parser.parse_args()
+
+    config = Config()
+    config.load()
+    if not config.loaded_config_file:
+        latex_render_url = input(textwrap.dedent('''\
+            It looks like text2qti has not been installed on this machine
+            before.  Would you like to set a default LaTeX rendering URL?  If
+            no, press ENTER.  If yes, provide the URL and press ENTER.
+
+            If you use Canvas, the URL will be something like
+                https://<institution>.instructure.com/equation_images/
+            or
+                https://canvas.<institution>.edu/equation_images/
+            with "<institution>" replaced by the name or abbreviation for
+            your institution.  You can determine "<institution>" by logging
+            into Canvas and then looking in the browser address bar for
+            something like "<institution>.instructure.com/" or
+            "canvas.<institution>.edu/".  If the address is similar to the
+            second form, you may need to change the domain from ".edu" to
+            the appropriate value for your institution.
+
+            If you do not use Canvas or software with a compatible LaTeX
+            rendering URL, you should not set a rendering URL.  You may still
+            be able to use LaTeX via the command-line option
+            "--pandoc-mathml".
+
+            LaTeX rendering URL:  '''))
+        latex_render_url = latex_render_url.strip()
+        if latex_render_url:
+            config['latex_render_url'] = latex_render_url
+            config.save()
+    if args.latex_render_url is not None:
+        config['latex_render_url'] = args.latex_render_url
+    if args.run_code_blocks is not None:
+        config['run_code_blocks'] = args.run_code_blocks
+    if args.pandoc_mathml is not None:
+        config['pandoc_mathml'] = args.pandoc_mathml
+
+    file_path = pathlib.Path(args.file).expanduser()
+    file_path_abs = file_path.absolute()
+    try:
+        text = file_path.read_text(encoding='utf-8-sig')  # Handle BOM for Windows
+    except FileNotFoundError:
+        raise Text2qtiError(f'File "{file_path}" does not exist')
+    except PermissionError as e:
+        raise Text2qtiError(f'File "{file_path}" cannot be read due to permission error:\n{e}')
+    except UnicodeDecodeError as e:
+        raise Text2qtiError(f'File "{file_path}" is not encoded in valid UTF-8:\n{e}')
+
+    cwd = pathlib.Path.cwd()
+    if args.solutions:
+        qti_path = pathlib.Path(f'{file_path.stem}.zip')
+        solutions_paths = [pathlib.Path(x).expanduser().absolute() for x in args.solutions]
+    elif args.only_solutions:
+        qti_path = None
+        solutions_paths = [pathlib.Path(x).expanduser().absolute() for x in args.only_solutions]
+    else:
+        qti_path = pathlib.Path(f'{file_path.stem}.zip')
+        solutions_paths = None
+    if solutions_paths is not None:
+        if file_path_abs in solutions_paths:
+            raise Text2qtiError(f'Solutions cannot overwrite quiz file "{file_path}"')
+        if not all(x.suffix.lower() in ('.md', '.markdown', '.pdf', '.html') for x in solutions_paths):
+            invalid_extensions = ', '.join(x.suffix for x in solutions_paths if x.suffix not in ('.md', '.markdown', '.pdf', '.html'))
+            raise Text2qtiError(f'Unsupported export format(s) {invalid_extensions} for solutions; use .md, .markdown, .pdf, or .html')
+    os.chdir(file_path.parent)
+    try:
+        # Quiz and any solutions should only be generated once each so that
+        # any randomization is only invoked once.
+        quiz = Quiz(text, config=config, source_name=file_path.as_posix())
+        if solutions_paths is not None:
+            solutions_text = quiz_to_pandoc(quiz, solutions=True)
+            for solutions_path in solutions_paths:
+                if solutions_path.suffix.lower() == '.pdf':
+                    if not shutil.which('pandoc'):
+                        raise Text2qtiError('Exporting solutions in PDF format requires Pandoc (https://pandoc.org/)')
+                    if not shutil.which('pdflatex'):
+                        raise Text2qtiError('Exporting solutions in PDF format requires LaTeX (https://www.tug.org/texlive/ or https://miktex.org/)')
+                    if platform.system() == 'Windows':
+                        cmd = [shutil.which('pandoc'), '-f', 'markdown', '-o', str(solutions_path)]
+                    else:
+                        cmd = ['pandoc', '-f', 'markdown', '-o', str(solutions_path)]
+                    try:
+                        proc = subprocess.run(
+                            cmd,
+                            input=solutions_text,
+                            capture_output=True,
+                            check=True,
+                            encoding='utf8'
+                        )
+                    except subprocess.CalledProcessError as e:
+                        raise Text2qtiError(f'Pandoc failed:\n{"-"*78}\n{e}\n{"-"*78}')
+                elif solutions_path.suffix.lower() == '.html':
+                    if not shutil.which('pandoc'):
+                        raise Text2qtiError('Exporting solutions in HTML format requires Pandoc (https://pandoc.org/)')
+                    if platform.system() == 'Windows':
+                        cmd = [shutil.which('pandoc'), '-f', 'markdown', '-o', str(solutions_path), '--mathjax', '-s']
+                    else:
+                        cmd = ['pandoc', '-f', 'markdown', '-o', str(solutions_path), '--mathjax', '-s']
+                    try:
+                        proc = subprocess.run(
+                            cmd,
+                            input=solutions_text,
+                            capture_output=True,
+                            check=True,
+                            encoding='utf8'
+                        )
+                    except subprocess.CalledProcessError as e:
+                        raise Text2qtiError(f'Pandoc failed:\n{"-"*78}\n{e}\n{"-"*78}')
+                elif solutions_path.suffix.lower() in ('.md', '.markdown'):
+                    solutions_path.write_text(solutions_text, encoding='utf8')
+                else:
+                    raise ValueError
+        if qti_path is not None:
+            qti = QTI(quiz)
+            qti.save(qti_path)
+    finally:
+        os.chdir(cwd)

text2qti/config.py

@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+import bespon
+import pathlib
+import textwrap
+import warnings
+from .err import Text2qtiError
+
+
+
+
+class Config(dict):
+    '''
+    Dict-like configuration that raises an error when invalid keys are set.
+    If `.load()` is invoked, a config file in BespON format is loaded if it
+    exists, and otherwise is created if possible.
+    '''
+    def __init__(self, *args, **kwargs):
+        self.loaded_config_file = False
+        self.update(self._defaults)
+        self.update(dict(*args, **kwargs))
+
+    _defaults = {
+        'pandoc_mathml': False,
+        'run_code_blocks': False,
+    }
+    _key_check = {
+        'latex_render_url': lambda x: isinstance(x, str),
+        'pandoc_mathml': lambda x: isinstance(x, bool),
+        'run_code_blocks': lambda x: isinstance(x, bool),
+    }
+    _config_path = pathlib.Path('~/.text2qti.bespon').expanduser()
+
+    def __setitem__(self, key, value):
+        if key not in self._key_check:
+            raise Text2qtiError(f'Invalid configuration option "{key}"')
+        if not self._key_check[key](value):
+            raise Text2qtiError(f'Configuration option "{key}" has invalid value "{value}"')
+        super().__setitem__(key, value)
+
+
+    def update(self, other: dict):
+        '''
+        Send all keys through __setitem__ so that they are checked for
+        validity.
+        '''
+        for k, v in other.items():
+            self[k] = v
+
+
+    def __missing__(self, key):
+        if self.loaded_config_file:
+            raise Text2qtiError(textwrap.dedent(f'''\
+                Configuration option "{key}" has not been set.
+                Open "{self._config_path}" to edit config manually.
+                '''))
+        raise Text2qtiError(f'Configuration option "{key}" has not been set.')
+
+
+    _default_config_template = textwrap.dedent('''\
+        # To set a default LaTeX rendering URL for Canvas, uncomment the
+        # appropriate config line below and replace <institution> with the name or
+        # abbreviation for your institution.  You can find this by looking at
+        # your browser address bar when logged into Canvas.  In some cases, more
+        # modifications may be necessary than simply replacing <institution>.
+
+        # For Canvas through Instructure:
+        # latex_render_url = "https://<institution>.instructure.com/equation_images/"
+
+        # For Canvas through your institution (may need to change ".edu" domain):
+        # latex_render_url = "https://canvas.<institution>.edu/equation_images/"
+        ''')
+
+    def load(self):
+        '''
+        Load config file.
+        '''
+        config_path = self._config_path
+        config_text = None
+        try:
+            config_text = config_path.read_text('utf8')
+            self.loaded_config_file = True
+        except FileNotFoundError:
+            try:
+                config_path.write_text(self._default_config_template, encoding='utf8')
+            except FileNotFoundError:
+                warnings.warn(f'Could not create default text2qti config file "{config_path}" due to FileNotFoundError (directory does not exist).')
+            except PermissionError:
+                warnings.warn(f'Could not create default text2qti config file "{config_path}" due to PermissionError.')
+        except PermissionError:
+            raise Text2qtiError(f'Could not open text2qti config file "{config_path}" due to PermissionError.')
+        except UnicodeDecodeError:
+            raise Text2qtiError(f'Could not open text2qti config file "{config_path}" due to UnicodeDecodeError. File may be corrupt.')
+
+        if config_text is not None:
+            try:
+                config_dict = bespon.loads(config_text, empty_default=dict)
+            except Exception as e:
+                raise Text2qtiError(f'Failed to load config file "{config_path}":\n{e}')
+            try:
+                self.update(config_dict)
+            except Text2qtiError as e:
+                raise Text2qtiError(f'Failed to load config file "{config_path}":\n{e}')
+
+    def save(self):
+        '''
+        Save config file.
+        '''
+        config_path = self._config_path
+        try:
+            bespon_text = bespon.dumps(dict(self))
+        except Exception as e:
+            raise Text2qtiError(f'Failed to convert config data to config file format (invalid data?):\n{e}')
+        try:
+            config_path.write_text(bespon_text, 'utf8')
+        except FileNotFoundError:
+            raise Text2qtiError(f'Could not create text2qti config file "{config_path}" due to FileNotFoundError (directory does not exist).')
+        except PermissionError:
+            raise Text2qtiError(f'Could not create text2qti config file "{config_path}" due to PermissionError.')

text2qti/err.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+class Text2qtiError(Exception):
+    pass

text2qti/export.py

@@ -0,0 +1,412 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2021, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+import random
+import re
+import textwrap
+
+from .quiz import Quiz, Question, GroupStart, GroupEnd, TextRegion
+from .markdown import Markdown
+
+
+markdown = Markdown()
+
+
+# https://daringfireball.net/projects/markdown/syntax
+_md_escape_chars_re = re.compile(r'[\\`*_{}\[\]()#+\-.!]')
+
+def _md_escape_chars_repl_func(match: re.Match) -> str:
+    return '\\' + match.group()
+
+def md_escape(raw_text: str) -> str:
+    '''
+    Escape raw text so that it is suitable for inclusion in Markdown.
+    '''
+    return _md_escape_chars_re.sub(_md_escape_chars_repl_func, raw_text)
+
+
+def indent(text: str, n_spaces: int, first_line: bool=True):
+    '''
+    Indent a string by a specified number of spaces, optionally leaving the
+    first line unchanged.
+    '''
+    if n_spaces < 0:
+        raise ValueError
+    if n_spaces == 0 or not text:
+        return text
+    indent_spaces = ' '*n_spaces
+    indented_text = text.replace('\n', '\n' + indent_spaces)
+    indented_text = indented_text.replace('\n' + indent_spaces + '\n', '\n\n')
+    if text[-1] == '\n':
+        indented_text = indented_text.rstrip(' ')
+    if first_line and text[0] != '\n':
+        indented_text = indent_spaces + indented_text
+    return indented_text
+
+
+_latex_templates = {
+    'header': textwrap.dedent(
+        r'''
+        %%%% Begin text2qti custom preamble
+        % Page layout
+        \usepackage[margin=1in]{geometry}
+        % Graphics
+        \usepackage{graphicx}
+        % Math/science
+        \usepackage{amsmath, amssymb}
+        \usepackage{siunitx}
+        % Symbols for solutions
+        \usepackage{fontawesome}
+        % Answers and solutions use itemize with custom item symbols
+        \def\texttoqtimctfchoicesymb{%
+            \resizebox{2ex}{!}{\faCircleO}}
+        \def\texttoqtimctfcorrectchoicesymb{%
+            \resizebox{2ex}{!}{\faDotCircleO}}
+        \def\texttoqtimultanschoicesymb{%
+            \resizebox{2ex}{!}{\faSquareO}}
+        \def\texttoqtimultanscorrectchoicesymb{%
+            \resizebox{2ex}{!}{\faCheckSquare}}
+        \def\texttoqtigeneralcorrectanssymb{%
+            \resizebox{2ex}{!}{\faArrowRight}}
+        \def\texttoqtisolutionsymb{%
+            \resizebox{2ex}{!}{\faFileTextO}}
+        \def\texttoqtishortansbox{%
+            \framebox[0.25\linewidth]{\strut}}
+        \def\texttoqtiessayansbox{%
+            \framebox{\begin{minipage}\vspace{4\baselineskip}\end{minipage}}}
+        %%%% End text2qti custom preamble
+        '''[1:]
+    ),
+    'mctf_choice_start': r'\item[\texttoqtimctfchoicesymb]',
+    'mctf_choice_end': r'',
+    'mctf_correct_choice_start': r'\item[\texttoqtimctfcorrectchoicesymb]',
+    'mctf_correct_choice_end': r'',
+    'multans_choice_start': r'\item[\texttoqtimultanschoicesymb]',
+    'multans_choice_end': r'',
+    'multans_correct_choice_start': r'\item[\texttoqtimultanscorrectchoicesymb]',
+    'multans_correct_choice_end': r'',
+    'generic_correct_choice_start': r'\item[\texttoqtigeneralcorrectanssymb]',
+    'generic_correct_choice_end': r'',
+    'choices_start': r'\begin{itemize}',
+    'choices_end': r'\end{itemize}',
+    'solution_start': r'\begin{itemize}' +'\n' + r'\item[\texttoqtisolutionsymb]',
+    'solution_end': r'\end{itemize}',
+    'shortans_placeholder': r'\texttoqtishortansbox',
+    'essay_placeholder': r'\texttoqtiessayansbox',
+    'file_upload_placeholder': r'\framebox{\texttt{<file upload>}}',
+    'random_questions_start': r'\begingroup\renewcommand{\labelitemi}{[?]}',
+    'random_questions_end': r'\endgroup',
+}
+
+_html_templates = {
+    'header': textwrap.dedent(
+        '''
+        <style type="text/css">
+        html {
+            line-height: 1.2;
+        }
+        div.text2qti-randomized > ul {
+            list-style-position: outside;
+            margin-left: -0.5em;
+        }
+        div.text2qti-randomized > ul > li {
+            list-style-type: "[?]";
+            padding-left: 0.5em;
+        }
+        ul.text2qti {
+            list-style-position: outside;
+            /* margin-left: -0.5em; */
+        }
+        ul > li.text2qti-mctf-choice::marker, ul > li.text2qti-mctf-correct-choice::marker {
+            font-size: 1.5em;
+        }
+        ul > li.text2qti-mctf-choice, ul > li.text2qti-mctf-correct-choice {
+            margin-top: -0.5em;
+        }
+        li.text2qti-mctf-choice {
+            list-style-type: "○";
+            padding-left: 0.5em;
+        }
+        li.text2qti-mctf-correct-choice {
+            list-style-type: "●";
+            padding-left: 0.5em;
+        }
+        li.text2qti-multans-choice {
+            list-style-type: "☐";
+            padding-left: 0.5em;
+        }
+        li.text2qti-multans-correct-choice {
+            list-style-type: "☑";
+            padding-left: 0.5em;
+        }
+        li.text2qti-generic-correct {
+            list-style-type: "🡆";
+            padding-left: 0.5em;
+        }
+        ul > li.text2qti-solution::marker {
+            font-size: 1.75em;
+        }
+        ul > li.text2qti-solution {
+            margin-top: -0.25em;
+        }
+        li.text2qti-solution {
+            list-style-type: "🗈";
+            padding-left: 0.5em;
+        }
+        </style>
+        '''[1:]
+    ),
+    'mctf_choice_start': '<li class="text2qti-mctf-choice">',
+    'mctf_choice_end': '</li>',
+    'mctf_correct_choice_start': '<li class="text2qti-mctf-correct-choice">',
+    'mctf_correct_choice_end': '</li>',
+    'multans_choice_start': '<li class="text2qti-multans-choice">',
+    'multans_choice_end': '</li>',
+    'multans_correct_choice_start': '<li class="text2qti-multans-correct-choice">',
+    'multans_correct_choice_end': '</li>',
+    'generic_correct_choice_start': '<li class="text2qti-generic-correct">',
+    'generic_correct_choice_end': '</li>',
+    'choices_start': '<ul class="text2qti">',
+    'choices_end': '</ul>',
+    'solution_start': '<ul class="text2qti"><li class="text2qti-solution">',
+    'solution_end': '</ul></li>',
+    'shortans_placeholder': '<div style="width:20em; height:1.5em; border:1px solid black;"></div>',
+    'essay_placeholder': '<div style="width:100%; height:6em; border:1px solid black;"></div>',
+    'file_upload_placeholder': '<pre style="border:1px solid black;"><file upload></pre>',
+    'random_questions_start': '<div class="text2qti-randomized">',
+    'random_questions_end': '</div>',
+}
+
+_templates = {}
+template = textwrap.dedent(
+    r'''
+    ```{=latex}
+    !{latex}
+    ```
+
+    ```{=html}
+    !{html}
+    ```
+
+    '''[1:]
+)
+for key in _latex_templates:
+    _templates[key] = template.replace('!{latex}', _latex_templates[key]).replace('!{html}', _html_templates[key])
+del template
+_templates['divider'] = '{0}\n\n'.format('-'*78)
+
+
+def question_to_markdown(question: Question, *,
+                         solutions: bool, unordered: bool,
+                         show_points: bool=False) -> str:
+    '''
+    Convert a question to Markdown
+    '''
+    if not solutions:
+        raise NotImplementedError
+
+    quiz_md = []
+
+    # List marker and point value
+    if solutions and unordered:
+        quiz_md.append('*   ')
+    else:
+        quiz_md.append('@.  ')
+    if show_points:
+        quiz_md.append('**[{0}]** '.format(question.points_possible))
+    quiz_md.append(indent(markdown.md_to_pandoc(question.question_raw), 4, first_line=False))
+    quiz_md.append('\n\n')
+
+    if question.type in ('true_false_question', 'multiple_choice_question'):
+        quiz_md.append(indent(_templates['choices_start'], 4))
+        for choice in question.choices:
+            if solutions and choice.correct:
+                quiz_md.append(indent(_templates['mctf_correct_choice_start'], 4))
+            else:
+                quiz_md.append(indent(_templates['mctf_choice_start'], 4))
+            quiz_md.append(indent(markdown.md_to_pandoc(choice.choice_raw), 4))
+            quiz_md.append('\n\n')
+            if solutions and choice.correct:
+                quiz_md.append(indent(_templates['mctf_correct_choice_end'], 4))
+            else:
+                quiz_md.append(indent(_templates['mctf_choice_end'], 4))
+        quiz_md.append(indent(_templates['choices_end'], 4))
+    elif question.type == 'multiple_answers_question':
+        quiz_md.append(indent(_templates['choices_start'], 4))
+        for choice in question.choices:
+            if solutions and choice.correct:
+                quiz_md.append(indent(_templates['multans_correct_choice_start'], 4))
+            else:
+                quiz_md.append(indent(_templates['multans_choice_start'], 4))
+            quiz_md.append(indent(markdown.md_to_pandoc(choice.choice_raw), 4))
+            quiz_md.append('\n\n')
+            if solutions and choice.correct:
+                quiz_md.append(indent(_templates['multans_correct_choice_end'], 4))
+            else:
+                quiz_md.append(indent(_templates['multans_choice_end'], 4))
+        quiz_md.append(indent(_templates['choices_end'], 4))
+    elif question.type == 'short_answer_question':
+        if solutions:
+            quiz_md.append(indent(_templates['choices_start'], 4))
+            quiz_md.append(indent(_templates['generic_correct_choice_start'], 4))
+            quiz_md.append(indent(' | '.join(markdown.md_to_pandoc(choice.choice_raw) for choice in question.choices), 4))
+            quiz_md.append('\n\n')
+            quiz_md.append(indent(_templates['generic_correct_choice_end'], 4))
+            quiz_md.append(indent(_templates['choices_end'], 4))
+        else:
+            quiz_md.append(indent(_templates['shortans_placeholder'], 4))
+    elif question.type == 'numerical_question':
+        if solutions:
+            quiz_md.append(indent(_templates['choices_start'], 4))
+            quiz_md.append(indent(_templates['generic_correct_choice_start'], 4))
+            ans = question.numerical_raw
+            if '+-' in ans:
+                while '+- ' in ans:
+                    ans = ans.replace('+- ', '+-')
+                if ans.endswith('+-0'):
+                    ans = ans[:-3]
+                else:
+                    ans = ans.replace('+-', r'\pm ')
+                ans = ans.replace('%', r'\%')
+            quiz_md.append(indent('$', 4))
+            quiz_md.append(ans)
+            if question.numerical_min is not None and question.numerical_max is not None:
+                if '+-' in question.numerical_raw:
+                    if isinstance(question.numerical_min, int) and isinstance(question.numerical_max, int):
+                        quiz_md.append(rf' \quad \Rightarrow \quad [{question.numerical_min}, {question.numerical_max}]')
+                    else:
+                        quiz_md.append(rf' \quad \Rightarrow \quad [{question.numerical_min:.4f}, {question.numerical_max:.4f}]')
+            quiz_md.append('$')
+            quiz_md.append('\n\n')
+            quiz_md.append(indent(_templates['generic_correct_choice_end'], 4))
+            quiz_md.append(indent(_templates['choices_end'], 4))
+    elif question.type == 'essay_question':
+        if not solutions:
+            quiz_md.append(indent(_templates['essay_placeholder'], 4))
+    elif question.type == 'file_upload_question':
+        if not solutions:
+            quiz_md.append(indent(_templates['file_upload_placeholder'], 4))
+    else:
+        raise ValueError
+
+    if solutions and question.solution is not None:
+        quiz_md.append(indent(_templates['solution_start'], 4))
+        quiz_md.append(indent(markdown.md_to_pandoc(question.solution), 4))
+        quiz_md.append('\n\n')
+        quiz_md.append(indent(_templates['solution_end'], 4))
+
+    return ''.join(quiz_md)
+
+
+def quiz_to_pandoc(quiz: Quiz, *, solutions=False) -> str:
+    '''
+    Generate a Pandoc Markdown version of assessment that optionally includes
+    solutions.
+    '''
+    if not solutions:
+        raise NotImplementedError
+
+    quiz_md = []
+
+    title = md_escape(quiz.title_raw or 'Quiz')
+    title += r'`\\ \textsc{solutions}`{=latex}'
+    title += r'`<br><span style="font-variant: small-caps;">solutions</span>`{=html}'
+    title = title.replace('\\', '\\\\').replace(r'"', r'\"')
+    meta = textwrap.dedent(
+        r'''
+        ---
+        title: "{title}"
+        header-includes: |
+            {header}
+        ...
+
+        '''[1:]
+    )
+    meta = meta.format(title=title, header=indent(_templates['header'], 4, first_line=False))
+    quiz_md.append(meta)
+
+    if quiz.description_raw:
+        quiz_md.append(markdown.md_to_pandoc(quiz.description_raw))
+        quiz_md.append('\n\n')
+        quiz_md.append(_templates['divider'])
+
+    len_quiz_md_before_questions = len(quiz_md)
+    in_group = False
+    group_needs_divider = False
+    for question_or_delim in quiz.questions_and_delims:
+        if isinstance(question_or_delim, TextRegion):
+            if question_or_delim.title_raw:
+                if len(quiz_md) > len_quiz_md_before_questions and quiz_md[-1] != _templates['divider']:
+                    quiz_md.append(_templates['divider'])
+                quiz_md.append('## {0}\n\n'.format(md_escape(question_or_delim.title_raw.replace('\n', ' '))))
+            if question_or_delim.text_raw:
+                quiz_md.append(markdown.md_to_pandoc(question_or_delim.text_raw))
+                quiz_md.append('\n\n')
+            quiz_md.append(_templates['divider'])
+            continue
+        if isinstance(question_or_delim, GroupStart):
+            in_group = True
+            group = question_or_delim.group
+            if solutions:
+                if group.solutions_pick is not None:
+                    num_questions_displayed = group.solutions_pick
+                elif quiz.solutions_sample_groups:
+                    num_questions_displayed = group.pick
+                else:
+                    num_questions_displayed = len(group.questions)
+                if num_questions_displayed > 1:
+                    if len(quiz_md) > len_quiz_md_before_questions and quiz_md[-1] != _templates['divider']:
+                        quiz_md.append(_templates['divider'])
+                    group_needs_divider = True
+                if group.pick == 1:
+                    if num_questions_displayed == 1:
+                        quiz_md.append(f'### Randomized question: representative example is shown\n\n')
+                    elif num_questions_displayed < len(group.questions):
+                        quiz_md.append(f'### Randomized question: randomly select {group.pick} from representative examples shown\n\n')
+                    else:
+                        quiz_md.append(f'### Randomized question: randomly select {group.pick}\n\n')
+                else:
+                    if num_questions_displayed == group.pick:
+                        quiz_md.append(f'### Randomized questions: representative examples are shown\n\n')
+                    elif num_questions_displayed < len(group.questions):
+                        quiz_md.append(f'### Randomized questions: randomly select {group.pick} from representative examples shown\n\n')
+                    else:
+                        quiz_md.append(f'### Randomized questions: randomly select {group.pick}\n\n')
+                if num_questions_displayed != group.pick:
+                    for _ in range(group.pick):
+                        quiz_md.append('@.  `<randomly selected>`\n\n')
+                unordered = num_questions_displayed != group.pick
+                if unordered:
+                    quiz_md.append(_templates['random_questions_start'])
+                if quiz.solutions_randomize_groups:
+                    for question in random.choices(question_or_delim.group.questions, num_questions_displayed):
+                        quiz_md.append(question_to_markdown(question, solutions=solutions, unordered=unordered))
+                else:
+                    for question in question_or_delim.group.questions[:num_questions_displayed]:
+                        quiz_md.append(question_to_markdown(question, solutions=solutions, unordered=unordered))
+                if unordered:
+                    quiz_md.append(_templates['random_questions_end'])
+                if group_needs_divider:
+                    quiz_md.append(_templates['divider'])
+                    group_needs_divider = False
+            continue
+        if isinstance(question_or_delim, GroupEnd):
+            in_group = False
+            continue
+        if isinstance(question_or_delim, Question):
+            if in_group:
+                continue
+            quiz_md.append(question_to_markdown(question_or_delim, solutions=solutions, unordered=in_group))
+            continue
+        raise TypeError
+
+    if quiz_md and quiz_md[-1] is _templates['divider']:
+        quiz_md.pop()
+    return ''.join(quiz_md)

text2qti/fmtversion.py

@@ -0,0 +1,217 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2015-2018, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+'''
+=============================================================
+``fmtversion``:  Simple version variables for Python packages
+=============================================================
+
+:Author: Geoffrey M. Poore
+:License: `BSD 3-Clause <http://opensource.org/licenses/BSD-3-Clause>`_
+
+Converts version information into a string ``__version__`` and a namedtuple
+``__version_info__`` suitable for Python packages.  The approach is inspired
+by PEP 440 and ``sys.version_info``:
+
+* https://www.python.org/dev/peps/pep-0440
+* https://docs.python.org/3/library/sys.html
+
+Versions of the form "major.minor.micro" are supported, with an optional,
+numbered dev/alpha/beta/candidate/final/post status.  The module does not
+support more complicated version numbers like "1.0b2.post345.dev456", since
+this does not fit into a namedtuple of the form used by ``sys.version_info``.
+The code is written as a single module, so that it may be bundled into
+packages, rather than needing to be installed as a separate dependency.
+
+Typical usage in a package's ``version.py`` with a bundled ``fmtversion.py``::
+
+    from .fmtversion import get_version_plus_info
+    __version__, __version_info__ = get_version_plus_info(1, 1, 0, 'final', 0)
+
+Following ``sys.version_info``, ``get_version_plus_info()`` takes arguments
+for a five-component version number:  major, minor, micro, releaselevel, and
+serial.  The releaselevel may be any of dev, alpha, beta, candidate, final, or
+post, or common variations/abbreviations thereof.  All arguments but
+releaselevel must be convertable to integers.
+
+If only ``__version__`` or ``__version_info__`` is desired, then the functions
+``get_version()`` or ``get_version_info()`` may be used instead.  If a micro
+version is not needed (``<major>.<minor>.<micro>``), then set the optional
+keyword argument ``usemicro=False``.  This will omit a micro version from the
+string ``__version__``, while the namedtuple ``__version_info__`` will still
+have a field ``micro`` that is set to zero to simplify comparisons.  If each
+releaselevel will only have one release, then set ``useserial=False``.  This
+will omit a serial number from the string ``__version__``, while the
+namedtuple ``__version_info__`` will still have a field ``serial`` that is set
+to zero.
+
+A function ``get_version_from_version_py_str()`` is included for extracting
+the version from a ``version.py`` file that has been read into a string.  This
+is intended for use in ``setup.py`` files.
+'''
+
+
+
+
+from __future__ import (division, print_function, absolute_import,
+                        unicode_literals)
+import sys
+if sys.version_info.major == 2:
+    str = basestring
+import collections
+
+
+# Version of this module, which will later be converted into a `__version__`
+# and `__version_info__` once the necessary functions are created
+__version_tuple__ = (1, 1, 0, 'final', 0)
+
+__docformat__ = 'restructuredtext en'
+
+
+
+
+VersionInfo = collections.namedtuple('VersionInfo', ['major', 'minor', 'micro',
+                                                     'releaselevel', 'serial'])
+
+
+def get_version_info(major, minor, micro, releaselevel, serial,
+                     usemicro=True, useserial=True):
+    '''
+    Create a VersionInfo instance suitable for use as `__version_info__`.
+
+    Perform all type and value checking that is needed for arguments; assume
+    that no previous checks have been performed.  This allows all checks to be
+    centralized in this single function.
+    '''
+    if not all(isinstance(x, int) or isinstance(x, str)
+            for x in (major, minor, micro, serial)):
+        raise TypeError('major, minor, micro, and serial must be integers or strings')
+    if not isinstance(releaselevel, str):
+        raise TypeError('releaselevel must be a string')
+    if not all(isinstance(x, bool) for x in (usemicro, useserial)):
+        raise TypeError('usemicro and useserial must be bools')
+
+    try:
+        major = int(major)
+        minor = int(minor)
+        micro = int(micro)
+        serial = int(serial)
+    except ValueError:
+        raise ValueError('major, minor, micro, and serial must be convertable to integers')
+    if any(x < 0 for x in (major, minor, micro, serial)):
+        raise ValueError('major, minor, micro, and serial must correspond to non-negative integers')
+    if not usemicro and micro != 0:
+        raise ValueError('usemicro=False, but a micro value "{0}" has been set'.format(micro))
+    if not useserial and serial != 0:
+        raise ValueError('useserial=False, but a serial value "{0}" has been set'.format(serial))
+
+    releaselevel_dict = {'dev': 'dev',
+                         'a': 'a', 'alpha': 'a',
+                         'b': 'b', 'beta': 'b',
+                         'c': 'c', 'rc': 'c',
+                         'candidate': 'c', 'releasecandidate': 'c',
+                         'pre': 'c', 'preview': 'c',
+                         'final': 'final',
+                         'post': 'post', 'r': 'post', 'rev': 'post'}
+    try:
+        releaselevel = releaselevel_dict[releaselevel.lower()]
+    except KeyError:
+        raise ValueError('Invalid releaselevel "{0}"'.format(releaselevel))
+    if releaselevel == 'final' and serial != 0:
+        raise ValueError('final release must not have non-zero serial')
+
+    return VersionInfo(major, minor, micro, releaselevel, serial)
+
+
+def get_version(*args, **kwargs):
+    '''
+    Create a version string suitable for use as `__version__`.
+
+    Make sure arguments are appropriate, but leave all actual processing and
+    value and type checking to `get_version_info()`.
+    '''
+    usemicro = kwargs.pop('usemicro', True)
+    useserial = kwargs.pop('useserial', True)
+    if kwargs:
+        raise TypeError('Unexpected keyword(s): {0}'.format(', '.join('{0}'.format(k) for k in kwargs)))
+
+    if len(args) == 1:
+        version_info = args[0]
+        if not isinstance(version_info, VersionInfo):
+            raise TypeError('Positional argument must have 5 components, or be a VersionInfo instance')
+    elif len(args) == 5:
+        version_info = get_version_info(*args, usemicro=usemicro, useserial=useserial)
+    else:
+        raise TypeError('Positional argument must have 5 components, or be a VersionInfo instance')
+
+    version = '{0}.{1}'.format(version_info.major, version_info.minor)
+    if usemicro:
+        version += '.{0}'.format(version_info.micro)
+    if version_info.releaselevel != 'final':
+        if version_info.releaselevel in ('dev', 'post'):
+                version += '.{0}'.format(version_info.releaselevel)
+        else:
+            version += '{0}'.format(version_info.releaselevel)
+        if useserial:
+            version += '{0}'.format(version_info.serial)
+
+    return version
+
+
+def get_version_plus_info(*args, **kwargs):
+    '''
+    Create a tuple consisting of a version string and a VersionInfo instance.
+    '''
+    usemicro = kwargs.pop('usemicro', True)
+    useserial = kwargs.pop('useserial', True)
+    if kwargs:
+        raise TypeError('Unexpected keyword(s): {0}'.format(', '.join('{0}'.format(k) for k in kwargs)))
+
+    version_info = get_version_info(*args, usemicro=usemicro, useserial=useserial)
+    version = get_version(version_info, usemicro=usemicro, useserial=useserial)
+    return (version, version_info)
+
+
+
+
+# Now that the required functions exist, process `__version_tuple__` into
+# `__version__` and `__version_info__` for the module
+__version__, __version_info__ = get_version_plus_info(*__version_tuple__)
+
+
+
+
+
+def get_version_from_version_py_str(string):
+    '''
+    Extract version from version.py that has been read into a string.
+
+    This assumes a simple, straightforward version.py.  It is meant for use
+    in setup.py files.
+    '''
+    if not isinstance(string, str):
+        raise TypeError('Argument must be a string')
+    if string.count('__version__') != 1:
+        raise RuntimeError('Failed to extract version from string')
+    exec_locals = {}
+    for line in string.splitlines():
+        if line.startswith('__version__'):
+            if not any(x in line for x in ['get_version(', 'get_version_plus_info(']):
+                raise RuntimeError('Failed to extract version from string')
+            if 'fmtversion.get_version' in line:
+                line = line.replace('fmtversion.get_version', 'get_version')
+            try:
+                exec(compile(line, 'version.py', 'exec'), globals(), exec_locals)
+            except Exception:
+                raise RuntimeError('Failed to extract version from string')
+            break
+    if '__version__' not in exec_locals:
+        raise RuntimeError('Failed to extract version from string')
+    return exec_locals['__version__']

text2qti/gui/tk.py

@@ -0,0 +1,320 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+import os
+import pathlib
+import shutil
+import time
+import tkinter as tk
+import tkinter.filedialog
+import webbrowser
+from ..config import Config
+from ..err import Text2qtiError
+from ..qti import QTI
+from ..quiz import Quiz
+from .. import version
+
+
+
+def main():
+    config = Config()
+    config.load()
+    file_name = ''
+
+    window = tk.Tk()
+    window.title('text2qti')
+    # Bring window to front and put in focus
+    window.iconify()
+    window.update()
+    window.deiconify()
+
+    # Window grid setup
+    current_row = 0
+    column_count = 4
+
+
+    header_label = tk.Label(
+        window,
+        text='text2qti – Create quizzes in QTI format from Markdown-based plain text',
+        font=(None, 16),
+    )
+    header_label.grid(
+        row=current_row, column=0, columnspan=column_count, padx=(30, 30),
+        sticky='nsew',
+    )
+    current_row += 1
+    header_link_label = tk.Label(
+        window,
+        text='github.com/gpoore/text2qti',
+        font=(None, 14), fg='blue', cursor='hand2',
+    )
+    header_link_label.bind('<Button-1>', lambda x: webbrowser.open_new('https://github.com/gpoore/text2qti'))
+    header_link_label.grid(
+        row=current_row, column=0, columnspan=column_count, padx=(30, 30),
+        sticky='nsew',
+    )
+    current_row += 1
+    version_label = tk.Label(
+        window,
+        text=f'Version {version.__version__}',
+    )
+    version_label.grid(
+        row=current_row, column=0, columnspan=column_count, padx=(30, 30), pady=(0, 30),
+        sticky='nsew',
+    )
+    current_row += 1
+
+
+    file_browser_label = tk.Label(
+        window,
+        text='Quiz file:\n(plain text file)',
+        justify='right',
+    )
+    file_browser_label.grid(
+        row=current_row, column=0, padx=(30, 5), pady=(5, 25),
+        sticky='nse',
+    )
+    last_dir = None
+    def browse_files():
+        nonlocal file_name
+        nonlocal last_dir
+        if last_dir is None:
+            initialdir = pathlib.Path('~').expanduser()
+        else:
+            initialdir = last_dir
+        file_name = tkinter.filedialog.askopenfilename(
+            initialdir=initialdir,
+            title='Select a quiz file',
+            filetypes=[('Quiz files', '*.md;*.txt')],
+        )
+        if file_name:
+            if last_dir is None:
+                last_dir = pathlib.Path(file_name).parent
+            file_browser_button.config(text=f'"{file_name}"', fg='green')
+        else:
+            file_browser_button.config(text=f'<none selected>', fg='red')
+
+    file_browser_button = tk.Button(
+        window,
+        text='<none selected>',
+        fg='red',
+        command=browse_files,
+    )
+    file_browser_button.grid(
+        row=current_row, column=1, columnspan=column_count-1, padx=(0, 30), pady=(5, 25),
+        sticky='nsew',
+    )
+    current_row += 1
+
+
+    advanced_options_label = tk.Label(
+        window,
+        text='Advanced options – LaTeX math & executable code',
+        justify='right',
+    )
+    advanced_options_label.grid(
+        row=current_row, column=1, columnspan=2, padx=(0, 0), pady=(5, 5),
+        sticky='nsw',
+    )
+    current_row += 1
+
+
+    latex_url_label = tk.Label(
+        window,
+        text='LaTeX math rendering URL:\n(for Canvas and similar systems)',
+        justify='right',
+    )
+    latex_url_label.grid(
+        row=current_row, column=0, padx=(30, 5), pady=(5, 5),
+        sticky='nse',
+    )
+    latex_url_entry = tk.Entry(window, width=100)
+    latex_url_entry.grid(
+        row=current_row, column=1, columnspan=column_count-1, padx=(0, 30), pady=(5, 5),
+        sticky='nsew',
+    )
+    if 'latex_render_url' in config:
+        latex_url_entry.insert(1, f"{config['latex_render_url']}")
+    current_row += 1
+
+
+    pandoc_exists = bool(shutil.which('pandoc'))
+    pandoc_mathml_label = tk.Label(
+        window,
+        text='Convert LaTeX math to MathML:\n(requires Pandoc; ignores rendering URL)',
+        justify='right',
+    )
+    if not pandoc_exists:
+        pandoc_mathml_label['fg'] = 'gray'
+    pandoc_mathml_label.grid(
+        row=current_row, column=0, padx=(30, 5), pady=(5, 5),
+        sticky='nse',
+    )
+    pandoc_mathml_bool = tk.BooleanVar()
+    def pandoc_mathml_command():
+        if pandoc_mathml_bool.get():
+            latex_url_label['fg'] = 'gray'
+            latex_url_entry['fg'] = 'gray'
+        else:
+            latex_url_label['fg'] = 'black'
+            latex_url_entry['fg'] = 'black'
+    if pandoc_exists:
+        pandoc_mathml_button = tk.Checkbutton(
+            window,
+            variable=pandoc_mathml_bool,
+            command=pandoc_mathml_command,
+        )
+        pandoc_mathml_bool.set(config['pandoc_mathml'])
+    else:
+        pandoc_mathml_button = tk.Checkbutton(
+            window,
+            state=tk.DISABLED,
+        )
+    pandoc_mathml_button.grid(
+        row=current_row, column=1, sticky='w',
+    )
+    current_row += 1
+
+
+    run_code_blocks_label = tk.Label(
+        window,
+        text='Allow executable code blocks:\n(only use for trusted code)',
+        justify='right',
+    )
+    run_code_blocks_label.grid(
+        row=current_row, column=0, padx=(30, 5), pady=(5, 5),
+        sticky='nse',
+    )
+    run_code_blocks_bool = tk.BooleanVar()
+    run_code_blocks_bool.set(config['run_code_blocks'])
+    def run_code_blocks_command():
+        if run_code_blocks_bool.get():
+            run_code_blocks_label['fg'] = 'red'
+        else:
+            run_code_blocks_label['fg'] = 'black'
+    run_code_blocks_button = tk.Checkbutton(
+        window,
+        variable=run_code_blocks_bool,
+        command=run_code_blocks_command,
+    )
+    run_code_blocks_button.grid(
+        row=current_row, column=1, sticky='w',
+    )
+    current_row += 1
+
+
+    def run():
+        run_message_text.delete(1.0, tk.END)
+        run_message_text['fg'] = 'gray'
+        run_message_text.insert(tk.INSERT, 'Starting...')
+        run_message_text.update()
+        error_message = None
+        if not file_name:
+            error_message = 'Must select a quiz file'
+            run_message_text.delete(1.0, tk.END)
+            run_message_text.insert(tk.INSERT, error_message)
+            run_message_text['fg'] = 'red'
+            return
+        if latex_url_entry.get():
+            config['latex_render_url'] = latex_url_entry.get()
+        config['run_code_blocks'] = run_code_blocks_bool.get()
+        config['pandoc_mathml'] = pandoc_mathml_bool.get()
+
+        file_path = pathlib.Path(file_name)
+        try:
+            text = file_path.read_text(encoding='utf-8-sig')  # Handle BOM for Windows
+        except FileNotFoundError:
+            error_message = f'File "{file_path}" does not exist.'
+        except PermissionError as e:
+            error_message = f'File "{file_path}" cannot be read due to permission error. Technical details:\n\n{e}'
+        except UnicodeDecodeError as e:
+            error_message = f'File "{file_path}" is not encoded in valid UTF-8. Technical details:\n\n{e}'
+        except Exception as e:
+            error_message = f'An error occurred in reading the quiz file. Technical details:\n\n{e}'
+        if error_message:
+            run_message_text.delete(1.0, tk.END)
+            run_message_text.insert(tk.INSERT, error_message)
+            run_message_text['fg'] = 'red'
+            return
+        cwd = pathlib.Path.cwd()
+        os.chdir(file_path.parent)
+        try:
+            quiz = Quiz(text, config=config, source_name=file_path.as_posix())
+            qti = QTI(quiz)
+            qti.save(f'{file_path.stem}.zip')
+        except Text2qtiError as e:
+            error_message = f'Quiz creation failed:\n\n{e}'
+        except Exception as e:
+            error_message = f'Quiz creation failed unexpectedly. Technical details:\n\n{e}'
+        finally:
+            os.chdir(cwd)
+        if error_message:
+            run_message_text.delete(1.0, tk.END)
+            run_message_text.insert(tk.INSERT, error_message)
+            run_message_text['fg'] = 'red'
+        else:
+            run_message_text.delete(1.0, tk.END)
+            run_message_text.insert(tk.INSERT, f'Created quiz "{file_path.parent.as_posix()}/{file_path.stem}.zip"')
+            run_message_text['fg'] = 'green'
+    run_button = tk.Button(
+        window,
+        text='RUN',
+        font=(None, 14),
+        command=run,
+    )
+    run_button.grid(
+        row=current_row, column=1, columnspan=2, padx=(0, 0), pady=(30, 30),
+        sticky='nsew',
+    )
+    current_row += 1
+
+
+    run_message_label = tk.Label(
+        window,
+        text='\nRun Summary:\n',
+        relief='ridge',
+        width=120,
+    )
+    run_message_label.grid(
+        row=current_row, column=0, columnspan=column_count, padx=(30, 30), pady=(0, 0),
+        sticky='nsew',
+    )
+    current_row += 1
+
+
+    run_message_frame = tk.Frame(
+        window,
+        width=120, height=40,
+        borderwidth=1, relief='sunken', bg='white',
+    )
+    run_message_frame.grid(
+        row=current_row, column=0, columnspan=column_count, padx=(30, 30), pady=(0, 30),
+        sticky='nsew',
+    )
+    run_message_scrollbar = tk.Scrollbar(run_message_frame)
+    run_message_scrollbar.pack(
+        side='right', fill='y',
+    )
+    run_message_text = tk.Text(
+        run_message_frame,
+        width=10, height=10, borderwidth=0, highlightthickness=0,
+        wrap='word',
+        yscrollcommand=run_message_scrollbar.set,
+    )
+    run_message_text.insert(tk.INSERT, 'Waiting...')
+    run_message_text['fg'] = 'gray'
+    run_message_scrollbar.config(command=run_message_text.yview)
+    run_message_text.pack(
+        side='left', fill='both', expand=True,
+        padx=(5, 5), pady=(5, 5),
+    )
+
+
+    window.mainloop()

text2qti/markdown.py

@@ -0,0 +1,560 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+import atexit
+import hashlib
+import json
+import pathlib
+import platform
+import re
+import subprocess
+import time
+import typing
+from typing import Dict, Optional, Set
+import urllib.parse
+import zipfile
+
+import markdown
+# Markdown extensions are imported and initialized explicitly to ensure that
+# pyinstaller identifies them.
+import markdown.extensions
+import markdown.extensions.smarty
+import markdown.extensions.sane_lists
+import markdown.extensions.def_list
+import markdown.extensions.fenced_code
+import markdown.extensions.footnotes
+import markdown.extensions.tables
+import markdown.extensions.md_in_html
+from markdown.inlinepatterns import ImageInlineProcessor, IMAGE_LINK_RE
+
+from .config import Config
+from .err import Text2qtiError
+from .version import __version__ as version
+from . import pymd_pandoc_attr
+
+
+md_extensions = [
+    markdown.extensions.smarty.makeExtension(),
+    markdown.extensions.sane_lists.makeExtension(),
+    markdown.extensions.def_list.makeExtension(),
+    markdown.extensions.fenced_code.makeExtension(),
+    markdown.extensions.footnotes.makeExtension(),
+    markdown.extensions.tables.makeExtension(),
+    markdown.extensions.md_in_html.makeExtension(),
+    pymd_pandoc_attr.makeExtension(),
+]
+
+
+
+
+class Image(object):
+    '''
+    Raw image data for quiz insertion.
+    '''
+    def __init__(self, name: str, data: bytes):
+        self.name = name
+        self.data = data
+        h = hashlib.blake2b()
+        h.update(data)
+        self.id = h.hexdigest()[:64]
+
+    @property
+    def src_path(self):
+        return f'%24IMS-CC-FILEBASE%24/images/{urllib.parse.quote(self.name)}'
+
+    @property
+    def qti_zip_path(self):
+        return f'images/{self.name}'
+
+    @property
+    def qti_xml_path(self):
+        return f'images/{urllib.parse.quote(self.name)}'
+
+
+
+
+class Text2qtiImagePattern(ImageInlineProcessor):
+    '''
+    Custom image processor for Python-Markdown that modifies local image
+    paths to their final QTI form and also accumulates all image data for QTI
+    inclusion.
+    '''
+    def __init__(self, pattern_re, markdown_md, text2qti_md):
+        super().__init__(pattern_re, markdown_md)
+        self.text2qti_md = text2qti_md
+
+    def handleMatch(self, match, data):
+        node, start, end = super().handleMatch(match, data)
+        src = node.attrib.get('src')
+        if src and not any(src.startswith(x) for x in ('http://', 'https://')):
+            src_path = pathlib.Path(src).expanduser()
+            try:
+                data = src_path.read_bytes()
+            except FileNotFoundError:
+                raise Text2qtiError(f'File "{src_path}" does not exist')
+            except PermissionError as e:
+                raise Text2qtiError(f'File "{src_path}" cannot be read due to permission error:\n{e}')
+            image = Image(src_path.name, data)
+            if image.id in self.text2qti_md.images:
+                image = self.text2qti_md.images[image.id]
+            else:
+                if image.name in self.text2qti_md.image_name_set:
+                    n = 8
+                    while image.name in self.text2qti_md.image_name_set:
+                        image.name = f'{src_path.stem}_{image.id[:n]}{src_path.suffix}'
+                        n *= 2
+                        if n >= len(image.id)*2:
+                            raise Text2qtiError('Hash collision occurred during image deduplication')
+                self.text2qti_md.image_name_set.add(image.name)
+                self.text2qti_md.images[image.id] = image
+            node.attrib['src'] = image.src_path
+        return node, start, end
+
+
+
+
+class Markdown(object):
+    r'''
+    Convert text from Markdown to HTML.  Then escape the HTML for insertion
+    into XML templates.
+
+    During the Markdown to HTML conversion, LaTeX math is converted to Canvas
+    img tags.  A subset of siunitx (https://ctan.org/pkg/siunitx) LaTeX macros
+    are also supported, with limited features:  `\SI`, `\si`, and `\num`.
+    siunitx macros are extracted via regex and then converted into plain
+    LaTeX, since Canvas LaTeX support does not cover siunitx.
+    '''
+    def __init__(self, config: Optional[Config]=None):
+        self.config = config
+
+        markdown_processor = markdown.Markdown(extensions=md_extensions)
+        markdown_image_processor = Text2qtiImagePattern(IMAGE_LINK_RE, markdown_processor, self)
+        markdown_processor.inlinePatterns.register(markdown_image_processor, 'image_link', 150)
+        self.markdown_processor = markdown_processor
+
+        self.images: Dict[str, Image] = {}
+        self.image_name_set: Set[str] = set()
+
+        if config is None:
+            self.latex_to_qti = self._latex_to_qti_unconfigured
+        elif config['pandoc_mathml']:
+            self.latex_to_qti = self.latex_to_pandoc_mathml
+            self._prep_cache()
+        else:
+            self.latex_to_qti = self.latex_to_canvas_img
+
+
+    def finalize(self):
+        if self.config is not None and self.config['pandoc_mathml']:
+            self._save_cache()
+            self._cache_lock_path.unlink()
+
+
+    def _latex_to_qti_unconfigured(self, latex: str):
+        raise Text2qtiError('Cannot convert LaTeX to QTI unless Markdown configuration is provided')
+
+
+    def _prep_cache(self):
+        self._cache_path = pathlib.Path('_text2qti_cache.zip')
+        self._cache_lock_path = pathlib.Path('_text2qti_cache.lock')
+
+        max_lock_wait = 2
+        lock_check_interval = 0.1
+        lock_time = 0
+        while True:
+            try:
+                self._cache_lock_path.touch(exist_ok=False)
+            except FileExistsError:
+                if lock_time > max_lock_wait:
+                    raise Text2qtiError('The text2qti cache is locked; this usually means that another instance of '
+                                        'text2qti is already running and you should try again later')
+                time.sleep(lock_check_interval)
+                lock_time += lock_check_interval
+            else:
+                break
+        def final_cache_cleanup():
+            try:
+                self._cache_lock_path.unlink()
+            except FileNotFoundError:
+                pass
+        atexit.register(final_cache_cleanup)
+
+        default_cache = {
+            'version': version,
+            'pandoc_mathml': {}
+        }
+        try:
+            with zipfile.ZipFile(str(self._cache_path)) as zf:
+                with zf.open('cache.json') as f:
+                    cache = json.load(f)
+        except (FileNotFoundError, KeyError, json.JSONDecodeError):
+            cache = default_cache
+        else:
+            if not isinstance(cache, dict) or cache.get('version') != version:
+                cache = default_cache
+        for v in cache['pandoc_mathml'].values():
+            v['unused_count'] += 1
+        self._cache = cache
+
+
+    def _save_cache(self):
+        self._cache['pandoc_mathml'] = {k: v for k, v in self._cache['pandoc_mathml'].items()
+                                       if v['unused_count'] <= 10}
+        with zipfile.ZipFile(str(self._cache_path), 'w', compression=zipfile.ZIP_DEFLATED) as zf:
+            zf.writestr('cache.json', json.dumps(self._cache))
+
+
+    XML_ESCAPES = (('&', '&amp;'),
+                ('<', '&lt;'),
+                ('>', '&gt;'),
+                ('"', '&quot;'),
+                ("'", '&apos;'))
+    XML_ESCAPES_LESS_QUOTES = tuple(x for x in XML_ESCAPES if x[0] not in ("'", '"'))
+    XML_ESCAPES_LESS_SQUOTE = tuple(x for x in XML_ESCAPES if x[0] != "'")
+    XML_ESCAPES_LESS_DQUOTE = tuple(x for x in XML_ESCAPES if x[0] != '"')
+
+    def xml_escape(self, string: str, *, squotes: bool=True, dquotes: bool=True) -> str:
+        '''
+        Escape a string for XML insertion, with options not to escape quotes.
+        '''
+        if squotes and dquotes:
+            escapes = self.XML_ESCAPES
+        elif squotes:
+            escapes = self.XML_ESCAPES_LESS_DQUOTE
+        elif dquotes:
+            escapes = self.XML_ESCAPES_LESS_SQUOTE
+        else:
+            escapes = self.XML_ESCAPES_LESS_QUOTES
+        for char, esc in escapes:
+            string = string.replace(char, esc)
+        return string
+
+
+    CANVAS_EQUATION_TEMPLATE = '<img class="equation_image" title="{latex_xml_escaped}" src="{latex_render_url}/{latex_url_escaped}" alt="LaTeX: {latex_xml_escaped}" data-equation-content="{latex_xml_escaped}">'
+
+    def latex_to_canvas_img(self, latex: str) -> str:
+        '''
+        Convert a LaTeX equation into an img tag suitable for Canvas.
+
+        Requires an institutional LaTeX equation rendering URL.  The URL is stored
+        in the text2qti config file or can be passed with flag --latex-render-url.
+        It will typically be of the form
+
+            https://<institution>.instructure.com/equation_images/
+
+        or
+
+            https://canvas.<institution>.edu/equation_images/
+        '''
+        latex_render_url = self.config['latex_render_url'].rstrip('/')
+        latex_xml_escaped = self.xml_escape(latex)
+        # Double url escaping is required
+        latex_url_escaped = urllib.parse.quote(urllib.parse.quote(latex))
+        return self.CANVAS_EQUATION_TEMPLATE.format(latex_render_url=latex_render_url,
+                                                    latex_xml_escaped=latex_xml_escaped,
+                                                    latex_url_escaped=latex_url_escaped)
+
+
+    def latex_to_pandoc_mathml(self, latex: str) -> str:
+        '''
+        Convert a LaTeX equation into MathML using Pandoc.
+        '''
+        data = self._cache['pandoc_mathml'].get(latex)
+        if data is not None:
+            mathml = data['mathml']
+            data['unused_count'] = 0
+        else:
+            if platform.system() == 'Windows':
+                # Prevent console from appearing for an instant
+                startupinfo = subprocess.STARTUPINFO()
+                startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+            else:
+                startupinfo = None
+            try:
+                proc = subprocess.run(['pandoc', '-f', 'markdown', '-t', 'html', '--mathml'],
+                                      input='${0}$'.format(latex), encoding='utf8',
+                                      stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                                      startupinfo=startupinfo,
+                                      check=True)
+            except FileNotFoundError as e:
+                raise Text2qtiError(f'Could not find Pandoc:\n{e}')
+            except subprocess.CalledProcessError as e:
+                raise Text2qtiError(f'Running Pandoc failed:\n{e}')
+            mathml = proc.stdout.strip()
+            if mathml.startswith('<p>'):
+                mathml = mathml[len('<p>'):]
+            if mathml.endswith('</p>'):
+                mathml = mathml[:-len('</p>')]
+            self._cache['pandoc_mathml'][latex] = {
+                'mathml': mathml,
+                'unused_count': 0,
+            }
+        return mathml
+
+
+    siunitx_num_number_re = re.compile(r'[+-]?(?:0|(?:[1-9][0-9]*(?:\.[0-9]+)?|0?\.[0-9]+)(?:[eE][+-]?(?:[1-9][0-9]*|0+[1-9][0-9]*))?)$')
+
+    def siunitx_num_to_plain_latex(self, number: str, in_math: bool=False) -> str:
+        r'''
+        Convert a basic subset of siunitx \num{<number>} syntax into plain LaTeX.
+        If `in_math` is true, covert the plain LaTeX to a Canvas img tag.
+        '''
+        number = number.strip()
+        if number.startswith('.'):
+            number = f'0{number}'
+        if not self.siunitx_num_number_re.match(number):
+            raise Text2qtiError(f'Invalid or unsupported LaTeX number "{number}"')
+        number = number.lower()
+        if 'e' in number:
+            significand, magnitude = number.split('e', 1)
+            magnitude = magnitude.lstrip('+').lstrip('0')
+            if magnitude.startswith('-0'):
+                magnitude = magnitude[0] + magnitude[1:].lstrip('0')
+            latex_number = f'{significand}\\times 10^{{{magnitude}}}'
+        else:
+            latex_number = number
+        if in_math:
+            return latex_number
+        return self.latex_to_qti(latex_number)
+
+
+    def siunitx_si_to_plain_latex(self, unit: str, in_math: bool=False) -> str:
+        r'''
+        Convert a basic subset of siunitx \si{<unit>} syntax into plain LaTeX.
+        If `in_math` is true, covert the plain LaTeX to a Canvas img tag.
+        '''
+        unit = unit.strip()
+        unit_list = []
+        unit_iter = iter(unit)
+        char = next(unit_iter, '')
+        while True:
+            if char == '' or char == ' ':
+                pass
+            elif char == '.':
+                unit_list.append(r'\!\cdot\!')  # Alternative:  r'\,'
+            elif char == '^':
+                char = next(unit_iter, '')
+                if char.isdigit():
+                    unit_list.append(f'^{{{char}}}')
+                elif char == '\\':
+                    unit_list.append('^')
+                    continue
+                else:
+                    raise Text2qtiError(f'Invalid or unsupported LaTeX unit "{unit}"')
+            elif char == '/':
+                unit_list.append(r'/')  # Alternative: r'\big/'
+            elif char == '\\':
+                macro = char
+                char = next(unit_iter, '')
+                while char.isalpha():
+                    macro += char
+                    char = next(unit_iter, '')
+                if macro == r'\degree':
+                    unit_list.append(r'^\circ')
+                elif macro == r'\celsius':
+                    unit_list.append(r'^\circ\textrm{C}')
+                elif macro == r'\fahrenheit':
+                    unit_list.append(r'^\circ\textrm{F}')
+                elif macro == r'\ohm':
+                    unit_list.append(r'\Omega')
+                elif macro == r'\micro':
+                    # Ideally, this would be an upright rather than slanted mu
+                    unit_list.append(r'\mu')
+                else:
+                    unit_list.append(macro)
+                continue
+            elif char.isalpha():
+                unit_list.append(r'\text{')
+                unit_list.append(char)
+                char = next(unit_iter, '')
+                while char.isalpha():
+                    unit_list.append(char)
+                    char = next(unit_iter, '')
+                unit_list.append('}')
+                continue
+            else:
+                raise Text2qtiError(f'Invalid or unsupported LaTeX unit "{unit}"')
+            try:
+                char = next(unit_iter)
+            except StopIteration:
+                break
+        latex_unit = '{' + ''.join(unit_list) + '}'  # wrapping {} may prevent line breaks
+        if in_math:
+            return latex_unit
+        return self.latex_to_qti(latex_unit)
+
+
+    def siunitx_SI_to_plain_latex(self, number: str, unit: str, in_math: bool=False) -> str:
+        r'''
+        Convert a basic subset of siunitx \SI{<number>}{<unit>} syntax into plain
+        LaTeX.  If `in_math` is true, covert the plain LaTeX to a Canvas img tag.
+        '''
+        latex_number = self.siunitx_num_to_plain_latex(number, in_math=True)
+        latex_unit = self.siunitx_si_to_plain_latex(unit, in_math=True)
+        if latex_unit.startswith(r'^\circ'):
+            unit_sep = ''
+        else:
+            unit_sep = r'\,'  # Alternative: `\>`
+        latex = f'{latex_number}{unit_sep}{latex_unit}'
+        if in_math:
+            return latex
+        return self.latex_to_qti(latex)
+
+
+    siunitx_num_macro_pattern = r'\\num\{(?P<num_number>[^{}]+)\}'
+    siunitx_si_macro_pattern = r'\\si\{(?P<si_unit>[^{}]+)\}'
+    siunitx_SI_macro_pattern = r'\\SI\{(?P<SI_number>[^{}]+)\}\{(?P<SI_unit>[^{}]+)\}'
+    siunitx_latex_macros_pattern = '|'.join([siunitx_num_macro_pattern, siunitx_si_macro_pattern, siunitx_SI_macro_pattern])
+    siunitx_latex_macros_re = re.compile(siunitx_latex_macros_pattern)
+
+    def _siunitx_dispatch(self, match: typing.Match[str], in_math: bool) -> str:
+        '''
+        Convert an siunitx regex match to plain LaTeX.  If `in_math` is true,
+        covert the plain LaTeX to a Canvas img tag.
+        '''
+        lastgroup = match.lastgroup
+        if lastgroup == 'SI_unit':
+            return self.siunitx_SI_to_plain_latex(match.group('SI_number'), match.group('SI_unit'), in_math)
+        if lastgroup == 'num_number':
+            return self.siunitx_num_to_plain_latex(match.group('num_number'), in_math)
+        if lastgroup == 'si_unit':
+            return self.siunitx_si_to_plain_latex(match.group('si_unit'), in_math)
+        raise ValueError
+
+    def sub_siunitx_to_plain_latex(self, string: str, in_math: bool=False) -> str:
+        '''
+        Convert all siunitx macros in a string to plain LaTeX.  If `in_math` is
+        true, covert the plain LaTeX to a Canvas img tag.
+        '''
+        return self.siunitx_latex_macros_re.sub(lambda match: self._siunitx_dispatch(match, in_math), string)
+
+
+    escape = r'(?P<escape>\\\$)'
+    skip = r'(?P<skip>\\.|\\\n|\$\$+(?!\$))'
+    html_comment_pattern = r'(?P<html_comment><!--(?:.|\n)*?-->)'
+    block_code_pattern = (
+        r'^(?P<block_code>'
+        r'(?P<indent>[ \t]*)(?P<block_code_delim>```+(?!`)|~~~+(?!~)).*?\n'
+        r'(?:[ \t]*\n|(?P=indent).*\n)*?'
+        r'(?P=indent)(?P=block_code_delim)[ \t]*(?:\n|$)'
+        r')'
+    )
+    inline_code_pattern = (
+        r'(?P<inline_code>'
+        r'(?P<inline_code_delim>`+(?!`))'
+        r'(?:.|\n[ \t]*(?![ \t\n]))+?'
+        r'(?<!`)(?P=inline_code_delim)(?!`)'
+        r')'
+    )
+    inline_math_pattern = (
+        r'\$(?=[^ \t\n])'
+        r'(?P<math>(?:[^$\n\\]|\\.|\\?\n[ \t]*(?:[^ \t\n$]))+)'
+        r'(?<![ \t\n])\$(?!\$)'
+    )
+    patterns = '|'.join([
+        block_code_pattern,
+        siunitx_latex_macros_pattern,
+        escape,
+        skip,
+        html_comment_pattern,
+        inline_code_pattern,
+        inline_math_pattern,
+    ])
+    skip_or_html_comment_or_code_math_siunitx_re = re.compile(patterns, re.MULTILINE)
+
+    def _html_comment_or_inline_code_math_siunitx_dispatch(self, match: typing.Match[str]) -> str:
+        '''
+        Process LaTeX math and siunitx regex matches into Canvas image tags,
+        while stripping HTML comments and leaving things like backslash
+        escapes and code unchanged.
+        '''
+        lastgroup = match.lastgroup
+        if lastgroup == 'html_comment':
+            return ''
+        if lastgroup == 'escape':
+            return match.group('escape')[1:]
+        if lastgroup == 'skip':
+            return match.group('skip')
+        if lastgroup == 'block_code':
+            return match.group('block_code')
+        if lastgroup == 'inline_code':
+            return match.group('inline_code')
+        if lastgroup == 'math':
+            math = match.group('math')
+            math = math.replace('\n ', ' ').replace('\n', ' ')
+            math = self.sub_siunitx_to_plain_latex(math, in_math=True)
+            return self.latex_to_qti(math)
+        if lastgroup == 'SI_unit':
+            return self.siunitx_SI_to_plain_latex(match.group('SI_number'), match.group('SI_unit'), in_math=False)
+        if lastgroup == 'num_number':
+            return self.siunitx_num_to_plain_latex(match.group('num_number'), in_math=False)
+        if lastgroup == 'si_unit':
+            return self.siunitx_si_to_plain_latex(match.group('si_unit'), in_math=False)
+        raise ValueError
+
+    def sub_math_siunitx_to_canvas_img(self, string: str) -> str:
+        '''
+        Convert all siunitx macros in a string into plain LaTeX.  Then convert
+        this LaTeX and all $-delimited LaTeX into Canvas img tags.
+        '''
+        return self.skip_or_html_comment_or_code_math_siunitx_re.sub(self._html_comment_or_inline_code_math_siunitx_dispatch, string)
+
+    def md_to_html_xml(self, markdown_string: str, strip_p_tags: bool=False) -> str:
+        '''
+        Convert the Markdown in a string to HTML, then escape the HTML for
+        embedding in XML.
+        '''
+        markdown_string_processed_latex = self.sub_math_siunitx_to_canvas_img(markdown_string)
+        try:
+            html = self.markdown_processor.reset().convert(markdown_string_processed_latex)
+        except Exception as e:
+            raise Text2qtiError(f'Conversion from Markdown to HTML failed:\n{e}')
+        if strip_p_tags:
+            if html.startswith('<p>'):
+                html = html[3:]
+            if html.endswith('</p>'):
+                html = html[:-4]
+        xml = self.xml_escape(html, squotes=False, dquotes=False)
+        return xml
+
+    def _md_to_pandoc_dispatch(self, match: typing.Match[str],
+                                     _passthrough=set(['escape', 'skip', 'block_code', 'inline_code'])) -> str:
+        '''
+        Process LaTeX math and siunitx regex matches into Pandoc Markdown,
+        while stripping HTML comments and leaving things like backslash
+        escapes and code unchanged.
+        '''
+        lastgroup = match.lastgroup
+        if lastgroup == 'html_comment':
+            return ''
+        if lastgroup in _passthrough:
+            return match.group(lastgroup)
+        if lastgroup == 'math':
+            math = match.group('math')
+            math = math.replace('\n ', ' ').replace('\n', ' ')
+            math = self.sub_siunitx_to_plain_latex(math, in_math=True)
+            return '${0}$'.format(math)
+        if lastgroup == 'SI_unit':
+            return '${0}$'.format(self.siunitx_SI_to_plain_latex(match.group('SI_number'), match.group('SI_unit'), in_math=True))
+        if lastgroup == 'num_number':
+            return '${0}$'.format(self.siunitx_num_to_plain_latex(match.group('num_number'), in_math=True))
+        if lastgroup == 'si_unit':
+            return '${0}$'.format(self.siunitx_si_to_plain_latex(match.group('si_unit'), in_math=True))
+        raise ValueError
+
+    def md_to_pandoc(self, string: str) -> str:
+        '''
+        Convert Markdown from a quiz into a form suitable for Pandoc Markdown.
+
+        Convert all siunitx macros in a string into plain LaTeX guaranteed to
+        be wrapped in `$`.  This can be processed into multiple formats by
+        Pandoc.
+        '''
+        return self.skip_or_html_comment_or_code_math_siunitx_re.sub(self._md_to_pandoc_dispatch, string)

text2qti/pymd_pandoc_attr.py

@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2021, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+'''
+Pandoc-style attribute syntax for Python-Markdown.
+Attribute support is currently limited to images.
+See https://pandoc.org/MANUAL.html#images.
+
+Inspired by https://github.com/Python-Markdown/markdown/blob/master/markdown/extensions/attr_list.py.
+'''
+
+
+from markdown.extensions import Extension
+from markdown.treeprocessors import Treeprocessor
+from typing import List, Tuple
+import re
+
+
+IDENTIFIER_PATTERN = r'[A-Za-z][0-9A-Za-z_\-]+'
+ID_PATTERN = rf'#{IDENTIFIER_PATTERN}'
+CLASS_PATTERN = rf'\.{IDENTIFIER_PATTERN}'
+KV_PATTERN = rf'{IDENTIFIER_PATTERN}=[0-9A-Za-z_\-%]+'
+ATTR_PATTERN = (
+    r'\{[ ]*(?!\})('
+    rf'(?:{ID_PATTERN}(?=[ \}}]))?'
+    rf'(?:{CLASS_PATTERN}(?=[ \}}])|{KV_PATTERN}(?=[ \}}])|[ ]+(?=[^ \}}]))*'
+    r')[ ]*\}'
+)
+
+def _handle_id(scanner: re.Scanner, token: str) -> Tuple[str, str]:
+    return '#', token[1:]
+
+def _handle_class(scanner: re.Scanner, token: str) -> Tuple[str, str]:
+    return '.', token[1:]
+
+def _handle_key_value(scanner: re.Scanner, token: str) -> Tuple[str, str]:
+    return token.split('=', 1)
+
+_scanner = re.Scanner([
+    (ID_PATTERN, _handle_id),
+    (CLASS_PATTERN, _handle_class),
+    (KV_PATTERN, _handle_key_value),
+    (r'[ ]+', None),
+])
+
+def get_attrs(string: str) -> List[Tuple[str, str]]:
+    '''
+    Parse a string of attributes `<attrs>` that has already been extracted
+    from a string of the form `{<attrs>}`.  Return a list of attribute tuples
+    of the form `(<key>, <value>)`.
+    '''
+    results, remainder = _scanner.scan(string)
+    return results
+
+
+class PandocAttrTreeprocessor(Treeprocessor):
+    ATTR_RE = re.compile(ATTR_PATTERN)
+    def run(self, doc):
+        for elem in doc.iter():
+            if self.md.is_block_level(elem.tag):
+                pass
+            else:
+                # inline, only for images currently
+                if elem.tag == 'img' and elem.tail and elem.tail.startswith('{'):
+                    match = self.ATTR_RE.match(elem.tail)
+                    if match:
+                        self.assign_attrs(elem, match.group(1))
+                        elem.tail = elem.tail[match.end():]
+
+    def assign_attrs(self, elem, attrs):
+        '''
+        Assign attrs to element.
+        '''
+        for k, v in get_attrs(attrs):
+            if k == '#':
+                elem.set('id', v)
+            elif k == '.':
+                elem_class = elem.get('class')
+                if elem_class:
+                    elem.set('class', f'{elem_class} {v}')
+                else:
+                    elem.set('class', v)
+            else:
+                elem_style = elem.get('style')
+                if elem_style:
+                    elem.set('style', f'{elem_style} {k}:{v};')
+                else:
+                    elem.set('style', f'{k}:{v};')
+
+
+class PandocAttrExtension(Extension):
+    def extendMarkdown(self, md):
+        md.treeprocessors.register(PandocAttrTreeprocessor(md), 'pandoc_attr', 8)
+        md.registerExtension(self)
+
+
+def makeExtension(**kwargs):
+    return PandocAttrExtension(**kwargs)

text2qti/qti.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+import io
+import pathlib
+from typing import Union, BinaryIO
+import zipfile
+from .quiz import Quiz
+from .xml_imsmanifest import imsmanifest
+from .xml_assessment_meta import assessment_meta
+from .xml_assessment import assessment
+
+
+class QTI(object):
+    '''
+    Create QTI from a Quiz object.
+    '''
+    def __init__(self, quiz: Quiz):
+        self.quiz = quiz
+        id_base = 'text2qti'
+        self.manifest_identifier = f'{id_base}_manifest_{quiz.id}'
+        self.assessment_identifier = f'{id_base}_assessment_{quiz.id}'
+        self.dependency_identifier = f'{id_base}_dependency_{quiz.id}'
+        self.assignment_identifier = f'{id_base}_assignment_{quiz.id}'
+        self.assignment_group_identifier = f'{id_base}_assignment-group_{quiz.id}'
+
+        self.imsmanifest_xml = imsmanifest(manifest_identifier=self.manifest_identifier,
+                                           assessment_identifier=self.assessment_identifier,
+                                           dependency_identifier=self.dependency_identifier,
+                                           images=self.quiz.images)
+        self.assessment_meta = assessment_meta(assessment_identifier=self.assessment_identifier,
+                                               assignment_identifier=self.assignment_identifier,
+                                               assignment_group_identifier=self.assignment_group_identifier,
+                                               title_xml=quiz.title_xml,
+                                               description_html_xml=quiz.description_html_xml,
+                                               points_possible=quiz.points_possible,
+                                               shuffle_answers=quiz.shuffle_answers_xml,
+                                               show_correct_answers=quiz.show_correct_answers_xml,
+                                               one_question_at_a_time=quiz.one_question_at_a_time_xml,
+                                               cant_go_back=quiz.cant_go_back_xml)
+        self.assessment = assessment(quiz=quiz,
+                                     assessment_identifier=self.assessment_identifier,
+                                     title_xml=quiz.title_xml)
+
+
+    def write(self, bytes_stream: BinaryIO):
+        with zipfile.ZipFile(bytes_stream, 'w', compression=zipfile.ZIP_DEFLATED) as zf:
+            zf.writestr('imsmanifest.xml', self.imsmanifest_xml)
+            zf.writestr(zipfile.ZipInfo('non_cc_assessments/'), b'')
+            zf.writestr(f'{self.assessment_identifier}/assessment_meta.xml', self.assessment_meta)
+            zf.writestr(f'{self.assessment_identifier}/{self.assessment_identifier}.xml', self.assessment)
+            for image in self.quiz.images.values():
+                zf.writestr(image.qti_zip_path, image.data)
+
+
+    def zip_bytes(self) -> bytes:
+        stream = io.BytesIO()
+        self.write(stream)
+        return stream.getvalue()
+
+
+    def save(self, qti_path: Union[str, pathlib.Path]):
+        if isinstance(qti_path, str):
+            qti_path = pathlib.Path(qti_path)
+        elif not isinstance(qti_path, pathlib.Path):
+            raise TypeError
+        qti_path.write_bytes(self.zip_bytes())

text2qti/quiz.py

@@ -0,0 +1,1186 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020-2021, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+'''
+Parse text into a Quiz object that contains a list of Question objects, each
+of which contains a list of Choice objects.
+'''
+
+
+import hashlib
+import io
+import itertools
+import locale
+import pathlib
+import platform
+import re
+import shutil
+import subprocess
+import tempfile
+from typing import Dict, List, Optional, Set, Union
+from .config import Config
+from .err import Text2qtiError
+from .markdown import Image, Markdown
+
+
+
+
+# regex patterns for parsing quiz content
+start_patterns = {
+    'question': r'\d+\.',
+    'mctf_correct_choice': r'\*[a-zA-Z]\)',
+    'mctf_incorrect_choice': r'[a-zA-Z]\)',
+    'multans_correct_choice': r'\[\*\]',
+    'multans_incorrect_choice': r'\[ ?\]',
+    'shortans_correct_choice': r'\*',
+    'feedback': r'\.\.\.',
+    'correct_feedback': r'\+',
+    'incorrect_feedback': r'\-',
+    'solution': r'!',
+    'essay': r'___+',
+    'upload': r'\^\^\^+',
+    'numerical': r'=',
+    'question_title': r'[Tt]itle:',
+    'question_points': r'[Pp]oints:',
+    'text_title': r'[Tt]ext [Tt]itle:',
+    'text': r'[Tt]ext:',
+    'quiz_title': r'[Qq]uiz [Tt]itle:',
+    'quiz_description': r'[Qq]uiz description:',
+    'start_group': r'GROUP',
+    'end_group': r'END_GROUP',
+    'group_pick': r'[Pp]ick:',
+    'group_solutions_pick': r'[Ss]olutions pick:',
+    'group_points_per_question': r'[Pp]oints per question:',
+    'start_code': r'```+\s*\S.*',
+    'end_code': r'```+',
+    'quiz_shuffle_answers': r'[Ss]huffle answers:',
+    'quiz_show_correct_answers': r'[Ss]how correct answers:',
+    'quiz_one_question_at_a_time': r'[Oo]ne question at a time:',
+    'quiz_cant_go_back': r'''[Cc]an't go back:''',
+    'quiz_feedback_is_solution': r'[Ff]eedback is solution:',
+    'quiz_solutions_sample_groups': r'[Ss]olutions sample groups:',
+    'quiz_solutions_randomize_groups': r'[Ss]olutions randomize groups:',
+}
+# comments are currently handled separately from content
+comment_patterns = {
+    'start_multiline_comment': r'COMMENT',
+    'end_multiline_comment': r'END_COMMENT',
+    'line_comment': r'%',
+}
+# whether regex needs to check after pattern for content on the same line
+no_content = set(['essay', 'upload', 'start_group', 'end_group', 'start_code', 'end_code'])
+# whether parser needs to check for multi-line content
+single_line = set(['question_points', 'group_pick', 'group_solutions_pick', 'group_points_per_question',
+                   'numerical', 'shortans_correct_choice',
+                   'quiz_shuffle_answers', 'quiz_show_correct_answers',
+                   'quiz_one_question_at_a_time', 'quiz_cant_go_back',
+                   'quiz_feedback_is_solution', 'quiz_solutions_sample_groups', 'quiz_solutions_randomize_groups'])
+multi_line = set([x for x in start_patterns
+                  if x not in no_content and x not in single_line])
+# whether parser needs to check for multi-paragraph content
+multi_para = set([x for x in multi_line if 'title' not in x])
+start_re = re.compile('|'.join(r'(?P<{0}>{1}[ \t]+(?=\S))'.format(name, pattern)
+                               if name not in no_content else
+                               r'(?P<{0}>{1}\s*)$'.format(name, pattern)
+                               for name, pattern in start_patterns.items()))
+start_missing_content_re = re.compile('|'.join(r'(?P<{0}>{1}[ \t]*$)'.format(name, pattern)
+                                               for name, pattern in start_patterns.items()
+                                               if name not in no_content))
+start_missing_whitespace_re = re.compile('|'.join(r'(?P<{0}>{1}(?=\S))'.format(name, pattern)
+                                                  for name, pattern in start_patterns.items()
+                                                  if name not in no_content))
+start_code_supported_info_re = re.compile(r'\{\s*'
+                                          r'\.(?P<lang>[a-zA-Z](?:[a-zA-Z0-9]+|[\._\-]+[a-zA-Z0-9]+)*)'
+                                          r'\s+'
+                                          r'\.run'
+                                          r'(?:\s+executable=(?P<executable>[~\w/\.\-]+|"[^\\\"\']+"))?'
+                                          r'\s*\}$')
+int_re = re.compile('(?:0|[+-]?[1-9](?:[0-9]+|_[0-9]+)*)$')
+
+
+
+
+class TextRegion(object):
+    '''
+    A text region between questions.
+    '''
+    def __init__(self, *, index: int, md: Markdown):
+        self.title_raw: Optional[str] = None
+        self.title_xml = ''
+        self.text_raw: Optional[str] = None
+        self.text_html_xml = ''
+        self.md = md
+        self._index = index
+
+    def _set_id(self):
+        h = hashlib.blake2b()
+        h.update(f'{self._index}'.encode('utf8'))
+        h.update(h.digest())
+        h.update(self.title_xml.encode('utf8'))
+        h.update(h.digest())
+        h.update(self.text_html_xml.encode('utf8'))
+        self.id = h.hexdigest()[:64]
+
+    def set_title(self, text: str):
+        if self.title_raw is not None:
+            raise Text2qtiError('Text title has already been set')
+        if self.text_raw is not None:
+            raise Text2qtiError('Must set text title before text itself')
+        self.title_raw = text
+        self.title_xml = self.md.xml_escape(text)
+        self._set_id()
+
+    def set_text(self, text: str):
+        if self.text_raw is not None:
+            raise Text2qtiError('Text has already been set')
+        self.text_raw = text
+        self.text_html_xml = self.md.md_to_html_xml(text)
+        self._set_id()
+
+
+
+
+class Choice(object):
+    '''
+    A choice for a question plus optional feedback.
+
+    The id is based on a hash of both the question and the choice itself.
+    The presence of feedback does not affect the id.
+    '''
+    def __init__(self, text: str, *,
+                 correct: bool, shortans: bool=False,
+                 question_hash_digest: bytes, md: Markdown):
+        self.choice_raw = text
+        if shortans:
+            self.choice_xml = md.xml_escape(text)
+        else:
+            self.choice_html_xml = md.md_to_html_xml(text)
+        self.correct = correct
+        self.shortans = shortans
+        self.feedback_raw: Optional[str] = None
+        self.feedback_html_xml: Optional[str] = None
+        # ID is based on hash of choice XML as well as question XML.  This
+        # gives different IDs for identical choices in different questions.
+        if shortans:
+            self.id = hashlib.blake2b(self.choice_xml.encode('utf8'), key=question_hash_digest).hexdigest()[:64]
+        else:
+            self.id = hashlib.blake2b(self.choice_html_xml.encode('utf8'), key=question_hash_digest).hexdigest()[:64]
+        self.md = md
+
+    def append_feedback(self, text: str):
+        if self.shortans:
+            raise Text2qtiError('Feedback cannot be specified for individual short answer responses, only for the question')
+        if self.feedback_raw is not None:
+            raise Text2qtiError('Feedback can only be specified once')
+        self.feedback_raw = text
+        self.feedback_html_xml = self.md.md_to_html_xml(text)
+
+
+class Question(object):
+    '''
+    A question, along with a list of possible choices and optional feedback of
+    various types.
+    '''
+    def __init__(self, text: str, *, quiz: 'Quiz', title: Optional[str], points: Optional[str], md: Markdown):
+        # Question type is set once it is known.  For true/false or multiple
+        # choice, this is done during .finalize(), once all choices are
+        # available.  For essay, this is done as soon as essay response is
+        # specified.
+        self.type: Optional[str] = None
+        self.quiz: 'Quiz' = quiz
+        if title is None:
+            self.title_raw: Optional[str] = None
+            self.title_xml = 'Question'
+        else:
+            self.title_raw: Optional[str] = title
+            self.title_xml = md.xml_escape(title)
+        self.question_raw = text
+        self.question_html_xml = md.md_to_html_xml(text)
+        self.choices: List[Choice] = []
+        # The set for detecting duplicate choices uses the XML version of the
+        # choices, to avoid the issue of multiple Markdown representations of
+        # the same XML.
+        self._choice_set: Set[str] = set()
+        self.numerical_raw: Optional[str] = None
+        self.numerical_min: Optional[Union[int, float]] = None
+        self.numerical_min_html_xml: Optional[str] = None
+        self.numerical_exact: Optional[Union[int, float]] = None
+        self.numerical_exact_html_xml: Optional[str] = None
+        self.numerical_max: Optional[Union[int, float]] = None
+        self.numerical_max_html_xml: Optional[str] = None
+        self.correct_choices = 0
+        if points is None:
+            self.points_possible_raw: Optional[str] = None
+            self.points_possible: Union[int, float] = 1
+        else:
+            self.points_possible_raw: Optional[str] = points
+            try:
+                points_num = float(points)
+            except ValueError:
+                raise Text2qtiError(f'Invalid points value "{points}"; need positive integer or half-integer')
+            if points_num <= 0:
+                raise Text2qtiError(f'Invalid points value "{points}"; need positive integer or half-integer')
+            if points_num.is_integer():
+                points_num = int(points)
+            elif abs(points_num-round(points_num)) != 0.5:
+                raise Text2qtiError(f'Invalid points value "{points}"; need positive integer or half-integer')
+            self.points_possible: Union[int, float] = points_num
+        self.feedback_raw: Optional[str] = None
+        self.feedback_html_xml: Optional[str] = None
+        self.correct_feedback_raw: Optional[str] = None
+        self.correct_feedback_html_xml: Optional[str] = None
+        self.incorrect_feedback_raw: Optional[str] = None
+        self.incorrect_feedback_html_xml: Optional[str] = None
+        self.solution: Optional[str] = None
+        h = hashlib.blake2b(self.question_html_xml.encode('utf8'))
+        self.hash_digest = h.digest()
+        self.id = h.hexdigest()[:64]
+        self.md = md
+
+
+    def append_feedback(self, text: str):
+        if self.type is not None and not self.choices:
+            raise Text2qtiError('Question feedback must immediately follow the question')
+        if not self.choices:
+            if self.feedback_raw is not None:
+                raise Text2qtiError('Feedback can only be specified once')
+            self.feedback_raw = text
+            self.feedback_html_xml = self.md.md_to_html_xml(text)
+            if self.quiz.feedback_is_solution:
+                self.solution = text
+        else:
+            self.choices[-1].append_feedback(text)
+
+    def append_correct_feedback(self, text: str):
+        if self.type is not None:
+            raise Text2qtiError('Correct feedback can only be specified for questions')
+        if self.correct_feedback_raw is not None:
+            raise Text2qtiError('Feedback can only be specified once')
+        self.correct_feedback_raw = text
+        self.correct_feedback_html_xml = self.md.md_to_html_xml(text)
+
+    def append_incorrect_feedback(self, text: str):
+        if self.type is not None:
+            raise Text2qtiError('Incorrect feedback can only be specified for questions')
+        if self.incorrect_feedback_raw is not None:
+            raise Text2qtiError('Feedback can only be specified once')
+        self.incorrect_feedback_raw = text
+        self.incorrect_feedback_html_xml = self.md.md_to_html_xml(text)
+
+    def append_solution(self, text: str):
+        if self.type is not None:
+            raise Text2qtiError('Solutions can only be specified for questions')
+        if self.solution is not None:
+            raise Text2qtiError('Solutions can only be specified once')
+        if self.quiz.feedback_is_solution:
+            raise Text2qtiError('Solutions syntax with "!" is disabled for quizzes with setting "feedback is solution: true"')
+        self.solution = text
+
+    def append_mctf_correct_choice(self, text: str):
+        if self.type is None:
+            self.type = 'multiple_choice_question'
+        elif self.type != 'multiple_choice_question':
+            raise Text2qtiError(f'Question type "{self.type}" does not support multiple choice')
+        choice = Choice(text, correct=True, question_hash_digest=self.hash_digest, md=self.md)
+        if choice.choice_html_xml in self._choice_set:
+            raise Text2qtiError('Duplicate choice for question')
+        self._choice_set.add(choice.choice_html_xml)
+        self.choices.append(choice)
+        self.correct_choices += 1
+
+    def append_mctf_incorrect_choice(self, text: str):
+        if self.type is None:
+            self.type = 'multiple_choice_question'
+        elif self.type != 'multiple_choice_question':
+            raise Text2qtiError(f'Question type "{self.type}" does not support multiple choice')
+        choice = Choice(text, correct=False, question_hash_digest=self.hash_digest, md=self.md)
+        if choice.choice_html_xml in self._choice_set:
+            raise Text2qtiError('Duplicate choice for question')
+        self._choice_set.add(choice.choice_html_xml)
+        self.choices.append(choice)
+
+    def append_shortans_correct_choice(self, text: str):
+        if self.type is None:
+            self.type = 'short_answer_question'
+        elif self.type != 'short_answer_question':
+            raise Text2qtiError(f'Question type "{self.type}" does not support short answer')
+        choice = Choice(text, correct=True, shortans=True, question_hash_digest=self.hash_digest, md=self.md)
+        if choice.choice_xml in self._choice_set:
+            raise Text2qtiError('Duplicate choice for question')
+        self._choice_set.add(choice.choice_xml)
+        self.choices.append(choice)
+        self.correct_choices += 1
+
+    def append_multans_correct_choice(self, text: str):
+        if self.type is None:
+            self.type = 'multiple_answers_question'
+        elif self.type != 'multiple_answers_question':
+            raise Text2qtiError(f'Question type "{self.type}" does not support multiple answers')
+        choice = Choice(text, correct=True, question_hash_digest=self.hash_digest, md=self.md)
+        if choice.choice_html_xml in self._choice_set:
+            raise Text2qtiError('Duplicate choice for question')
+        self._choice_set.add(choice.choice_html_xml)
+        self.choices.append(choice)
+        self.correct_choices += 1
+
+    def append_multans_incorrect_choice(self, text: str):
+        if self.type is None:
+            self.type = 'multiple_answers_question'
+        elif self.type != 'multiple_answers_question':
+            raise Text2qtiError(f'Question type "{self.type}" does not support multiple answers')
+        choice = Choice(text, correct=False, question_hash_digest=self.hash_digest, md=self.md)
+        if choice.choice_html_xml in self._choice_set:
+            raise Text2qtiError('Duplicate choice for question')
+        self._choice_set.add(choice.choice_html_xml)
+        self.choices.append(choice)
+
+    def append_essay(self, text: str):
+        if text:
+            # The essay response syntax provides no text to process; the
+            # `text` argument just gives all append functions the same form.
+            raise ValueError
+        if self.type is not None:
+            if self.type == 'essay_question':
+                raise Text2qtiError(f'Cannot specify essay response multiple times')
+            raise Text2qtiError(f'Question type "{self.type}" does not support essay response')
+        self.type = 'essay_question'
+        if any(x is not None for x in (self.correct_feedback_raw, self.incorrect_feedback_raw)):
+            raise Text2qtiError(f'Question type "{self.type}" does not support correct/incorrect feedback')
+
+    def append_upload(self, text: str):
+        if text:
+            # The upload response syntax provides no text to process; the
+            # `text` argument just gives all append functions the same form.
+            raise ValueError
+        if self.type is not None:
+            if self.type == 'file_upload_question':
+                raise Text2qtiError(f'Cannot specify upload response multiple times')
+            raise Text2qtiError(f'Question type "{self.type}" does not support upload response')
+        self.type = 'file_upload_question'
+        if any(x is not None for x in (self.correct_feedback_raw, self.incorrect_feedback_raw)):
+            raise Text2qtiError(f'Question type "{self.type}" does not support correct/incorrect feedback')
+
+    def append_numerical(self, text: str):
+        if self.type is not None:
+            if self.type == 'numerical_question':
+                raise Text2qtiError(f'Cannot specify numerical response multiple times')
+            raise Text2qtiError(f'Question type "{self.type}" does not support numerical response')
+        self.type = 'numerical_question'
+        self.numerical_raw = text
+        if text.startswith('['):
+            if not text.endswith(']') or ',' not in text:
+                raise Text2qtiError('Invalid numerical response; need "[<min>, <max>]" or "<number> +- <margin>" or "<integer>"')
+            min, max = text[1:-1].split(',', 1)
+            try:
+                min = float(min)
+                max = float(max)
+            except Exception:
+                raise Text2qtiError('Invalid numerical response; need "[<min>, <max>]" or "<number> +- <margin>" or "<integer>"')
+            if min > max:
+                raise Text2qtiError('Invalid numerical response; need "[<min>, <max>]" with min < max')
+            self.numerical_min = min
+            self.numerical_max = max
+            if min.is_integer() and max.is_integer():
+                self.numerical_min_html_xml = f'{min}'
+                self.numerical_max_html_xml = f'{max}'
+            else:
+                self.numerical_min_html_xml = f'{min:.4f}'
+                self.numerical_max_html_xml = f'{max:.4f}'
+        elif '+-' in text:
+            num, margin = text.split('+-', 1)
+            if margin.endswith('%'):
+                margin_is_percentage = True
+                margin = margin[:-1]
+            else:
+                margin_is_percentage = False
+            try:
+                num = float(num)
+                margin = float(margin)
+            except Exception:
+                raise Text2qtiError('Invalid numerical response; need "[<min>, <max>]" or "<number> +- <margin>" or "<integer>"')
+            if margin < 0:
+                raise Text2qtiError('Invalid numerical response; need "<number> +- <margin>" with margin > 0')
+            if margin_is_percentage:
+                min = num - abs(num)*(margin/100)
+                max = num + abs(num)*(margin/100)
+            else:
+                min = num - margin
+                max = num + margin
+            self.numerical_min = min
+            self.numerical_exact = num
+            self.numerical_max = max
+            if min.is_integer() and num.is_integer() and max.is_integer():
+                self.numerical_min_html_xml = f'{min}'
+                self.numerical_exact_html_xml = f'{num}'
+                self.numerical_max_html_xml = f'{max}'
+            else:
+                self.numerical_min_html_xml = f'{min:.4f}'
+                self.numerical_exact_html_xml = f'{num:.4f}'
+                self.numerical_max_html_xml = f'{max:.4f}'
+        elif int_re.match(text):
+            num = int(text)
+            min = max = num
+            self.numerical_min = min
+            self.numerical_exact = num
+            self.numerical_max = max
+            self.numerical_min_html_xml = f'{min}'
+            self.numerical_exact_html_xml = f'{num}'
+            self.numerical_max_html_xml = f'{max}'
+        else:
+            raise Text2qtiError('Invalid numerical response; need "[<min>, <max>]" or "<number> +- <margin>" or "<integer>"')
+        if abs(min) < 1e-4 or abs(max) < 1e-4:
+            raise Text2qtiError('Invalid numerical response; all acceptable values must have a magnitude >= 0.0001')
+
+
+    def finalize(self):
+        if self.type is None:
+            raise Text2qtiError('Question must specify a response type')
+        elif self.type == 'multiple_choice_question':
+            if len(self.choices) == 2 and all(c.choice_raw in ('true', 'True', 'false', 'False') for c in self.choices):
+                self.type = 'true_false_question'
+            if not self.choices:
+                raise Text2qtiError('Question must provide choices')
+            if len(self.choices) < 2:
+                raise Text2qtiError('Question must provide more than one choice')
+            if self.correct_choices < 1:
+                raise Text2qtiError('Question must specify a correct choice')
+            if self.correct_choices > 1:
+                raise Text2qtiError('Question must specify only one correct choice')
+        elif self.type == 'short_answer_question':
+            if not self.choices:
+                raise Text2qtiError('Question must provide at least one answer')
+        elif self.type == 'multiple_answers_question':
+            if len(self.choices) < 2:
+                raise Text2qtiError('Question must provide more than one choice')
+            if self.correct_choices < 1:
+                raise Text2qtiError('Question must specify a correct choice')
+
+
+
+
+class Group(object):
+    '''
+    A group of questions.  A random subset of the questions in a group is
+    actually displayed.
+    '''
+    def __init__(self):
+        self.pick = 1
+        self._pick_is_set = False
+        self.solutions_pick: Optional[int] = None
+        self.points_per_question = 1
+        self._points_per_question_is_set = False
+        self.questions: List[Question] = []
+        self._question_points_possible: Optional[Union[int, float]] = None
+        self.title_raw: Optional[str] = None
+        self.title_xml = 'Group'
+
+    def append_group_pick(self, text: str):
+        if self.questions:
+            raise Text2qtiError('Question group options must be set at the very start of the group')
+        if self._pick_is_set:
+            Text2qtiError('"Pick" has already been set for this question group')
+        try:
+            self.pick = int(text)
+        except Exception as e:
+            raise Text2qtiError(f'"pick" value is invalid (must be positive number):\n{e}')
+        if self.pick <= 0:
+            raise Text2qtiError('"pick" value is invalid (must be positive number)')
+        if self.solutions_pick is not None and self.pick > self.solutions_pick:
+            raise Text2qtiError('"pick" value must be less than or equal to "solutions pick" value')
+        self._pick_is_set = True
+
+    def append_group_solutions_pick(self, text: str):
+        if self.questions:
+            raise Text2qtiError('Question group options must be set at the very start of the group')
+        if self.solutions_pick is not None:
+            Text2qtiError('"solutions pick" has already been set for this question group')
+        try:
+            self.solutions_pick = int(text)
+        except Exception as e:
+            raise Text2qtiError(f'"solutions pick" value is invalid (must be positive number):\n{e}')
+        if self.solutions_pick <= 0:
+            raise Text2qtiError('"solutions pick" value is invalid (must be positive number)')
+        if self.solutions_pick < self.pick:
+            raise Text2qtiError('"solutions pick" value must be greater than or equal to "pick" value')
+
+    def append_group_points_per_question(self, text: str):
+        if self.questions:
+            raise Text2qtiError('Question group options must be set at the very start of the group')
+        if self._points_per_question_is_set:
+            Text2qtiError('"Points per question" has already been set for this question group')
+        try:
+            self.points_per_question = int(text)
+        except Exception as e:
+            raise Text2qtiError(f'"Points per question" value is invalid (must be positive number):\n{e}')
+        if self.points_per_question <= 0:
+            raise Text2qtiError(f'"Points per question" value is invalid (must be positive number):')
+        self._points_per_question_is_set = True
+
+    def append_question(self, question: Question):
+        if self._question_points_possible is None:
+            self._question_points_possible = question.points_possible
+        elif question.points_possible != self._question_points_possible:
+            raise Text2qtiError('Question groups must only contain questions with the same point value')
+        self.questions.append(question)
+
+    def finalize(self):
+        if len(self.questions) < self.pick:
+            raise Text2qtiError(f'Question group only contains {len(self.questions)} questions, needs at least {self.pick+1}')
+        if self.solutions_pick is not None and len(self.questions) < self.solutions_pick:
+            raise Text2qtiError(f'Question group only contains {len(self.questions)} questions, needs at least {self.solutions_pick}')
+        h = hashlib.blake2b()
+        for digest in sorted(q.hash_digest for q in self.questions):
+            h.update(digest)
+        self.hash_digest = h.digest()
+        self.id = h.hexdigest()[:64]
+
+class GroupStart(object):
+    '''
+    Start delim for a group of questions.
+    '''
+    def __init__(self, group: Group):
+        self.group = group
+
+class GroupEnd(object):
+    '''
+    End delim for a group of questions.
+    '''
+    def __init__(self, group: Group):
+        self.group = group
+
+
+
+
+class Quiz(object):
+    '''
+    A quiz or assessment.  Contains a list of questions along with possible
+    choices and feedback.
+    '''
+    def __init__(self, string: str, *, config: Config,
+                 source_name: Optional[str]=None,
+                 resource_path: Optional[Union[str, pathlib.Path]]=None):
+        self.string = string
+        self.config = config
+        self.source_name = '<string>' if source_name is None else f'"{source_name}"'
+        if resource_path is not None:
+            if isinstance(resource_path, str):
+                resource_path = pathlib.Path(resource_path)
+            else:
+                raise TypeError
+            if not resource_path.is_dir():
+                raise Text2qtiError(f'Resource path "{resource_path.as_posix()}" does not exist')
+        self.resource_path = resource_path
+        self.title_raw = None
+        self.title_xml = 'Quiz'
+        self.description_raw = None
+        self.description_html_xml = ''
+        self.shuffle_answers_raw = None
+        self.shuffle_answers_xml = 'false'
+        self.show_correct_answers_raw = None
+        self.show_correct_answers_xml = 'true'
+        self.one_question_at_a_time_raw = None
+        self.one_question_at_a_time_xml = 'false'
+        self.cant_go_back_raw = None
+        self.cant_go_back_xml = 'false'
+        self.feedback_is_solution: Optional[bool] = None
+        self.solutions_sample_groups: Optional[bool] = None
+        self.solutions_randomize_groups: Optional[bool] = None
+        self.questions_and_delims: List[Union[Question, GroupStart, GroupEnd, TextRegion]] = []
+        self._current_group: Optional[Group] = None
+        # The set for detecting duplicate questions uses the XML version of
+        # the question, to avoid the issue of multiple Markdown
+        # representations of the same XML.
+        self.question_set: Set[str] = set()
+        self.md = Markdown(config)
+        self.images: Dict[str, Image] = self.md.images
+        self._next_question_attr = {}
+
+        # Determine how to interpret `.python` for executable code blocks.
+        # If `python3` exists, use it instead of `python` if `python` does not
+        # exist or if `python` is equivalent to `python2`.
+        if not shutil.which('python2') or not shutil.which('python3'):
+            python_executable = 'python'
+        elif not shutil.which('python'):
+            python_executable = 'python3'
+        elif pathlib.Path(shutil.which('python')).resolve() == pathlib.Path(shutil.which('python2')).resolve():
+            python_executable = 'python3'
+        else:
+            python_executable = 'python'
+
+        try:
+            parse_actions = {}
+            for k in start_patterns:
+                parse_actions[k] = getattr(self, f'append_{k}')
+            parse_actions[None] = self.append_unknown
+            start_multiline_comment_pattern = comment_patterns['start_multiline_comment']
+            end_multiline_comment_pattern = comment_patterns['end_multiline_comment']
+            line_comment_pattern = comment_patterns['line_comment']
+            n_line_iter = iter(x for x in enumerate(string.splitlines()))
+            n, line = next(n_line_iter, (0, None))
+            lookahead = False
+            n_code_start = 0
+            while line is not None:
+                match = start_re.match(line)
+                if match:
+                    action = match.lastgroup
+                    text = line[match.end():].strip()
+                    if action == 'start_code':
+                        info = line.lstrip('`').strip()
+                        info_match = start_code_supported_info_re.match(info)
+                        if info_match is None:
+                            pass
+                        else:
+                            executable = info_match.group('executable')
+                            if executable is not None:
+                                if executable.startswith('"'):
+                                    executable = executable[1:-1]
+                                executable = pathlib.Path(executable).expanduser().as_posix()
+                            else:
+                                executable = info_match.group('lang')
+                                if executable == 'python':
+                                    executable = python_executable
+                            delim = '`'*(len(line) - len(line.lstrip('`')))
+                            n_code_start = n
+                            code_lines = []
+                            n, line = next(n_line_iter, (0, None))
+                            # No lookahead here; all lines are consumed
+                            while line is not None and not (line.startswith(delim) and line[len(delim):] == line.lstrip('`')):
+                                code_lines.append(line)
+                                n, line = next(n_line_iter, (0, None))
+                            if line is None:
+                                raise Text2qtiError(f'In {self.source_name} on line {n}:\nCode closing fence is missing')
+                            if line.lstrip('`').strip():
+                                raise Text2qtiError(f'In {self.source_name} on line {n+1}:\nCode closing fence is missing')
+                            code_lines.append('\n')
+                            code = '\n'.join(code_lines)
+                            try:
+                                stdout = self._run_code(executable, code)
+                            except Exception as e:
+                                raise Text2qtiError(f'In {self.source_name} on line {n_code_start+1}:\n{e}')
+                            code_n_line_iter = ((n_code_start, stdout_line) for stdout_line in stdout.splitlines())
+                            n_line_iter = itertools.chain(code_n_line_iter, n_line_iter)
+                            n, line = next(n_line_iter, (0, None))
+                            continue
+                    elif action in multi_line:
+                        if start_patterns[action].endswith(':'):
+                            indent_expandtabs = None
+                        else:
+                            indent_expandtabs = ' '*len(line[:match.end()].expandtabs(4))
+                        text_lines = [text]
+                        n, line = next(n_line_iter, (0, None))
+                        line_expandtabs = line.expandtabs(4) if line is not None else None
+                        lookahead = True
+                        while (line is not None and
+                                (not line or line.isspace() or
+                                    indent_expandtabs is None or line_expandtabs.startswith(indent_expandtabs))):
+                            if not line or line.isspace():
+                                if action in multi_para:
+                                    text_lines.append('')
+                                else:
+                                    break
+                            else:
+                                if indent_expandtabs is None:
+                                    if not line.startswith(' '):
+                                        break
+                                    indent_expandtabs = ' '*(len(line_expandtabs)-len(line_expandtabs.lstrip(' ')))
+                                    if len(indent_expandtabs) < 2:
+                                        raise Text2qtiError(f'In {self.source_name} on line {n+1}:\nIndentation must be at least 2 spaces or 1 tab here')
+                                # The `rstrip()` prevents trailing double
+                                # spaces from becoming `<br />`.
+                                text_lines.append(line_expandtabs[len(indent_expandtabs):].rstrip())
+                            n, line = next(n_line_iter, (0, None))
+                            line_expandtabs = line.expandtabs(4) if line is not None else None
+                        if text_lines and not text_lines[-1]:
+                            while text_lines and not text_lines[-1]:
+                                text_lines.pop()
+                        text = '\n'.join(text_lines)
+                elif line.startswith(line_comment_pattern):
+                    n, line = next(n_line_iter, (0, None))
+                    continue
+                elif line.startswith(start_multiline_comment_pattern):
+                    if line.strip() != start_multiline_comment_pattern:
+                        raise Text2qtiError(f'In {self.source_name} on line {n+1}:\nUnexpected content after "{start_multiline_comment_pattern}"')
+                    n, line = next(n_line_iter, (0, None))
+                    while line is not None and not line.startswith(end_multiline_comment_pattern):
+                        n, line = next(n_line_iter, (0, None))
+                    if line is None:
+                        raise Text2qtiError(f'In {self.source_name} on line {n+1}:\nf"{start_multiline_comment_pattern}" without following "{end_multiline_comment_pattern}"')
+                    if line.strip() != end_multiline_comment_pattern:
+                        raise Text2qtiError(f'In {self.source_name} on line {n+1}:\nUnexpected content after "{end_multiline_comment_pattern}"')
+                    n, line = next(n_line_iter, (0, None))
+                    continue
+                elif line.startswith(end_multiline_comment_pattern):
+                    raise Text2qtiError(f'In {self.source_name} on line {n+1}:\n"{end_multiline_comment_pattern}" without preceding "{start_multiline_comment_pattern}"')
+                else:
+                    action = None
+                    text = line
+                try:
+                    parse_actions[action](text)
+                except Text2qtiError as e:
+                    if lookahead and n != n_code_start:
+                        raise Text2qtiError(f'In {self.source_name} on line {n}:\n{e}')
+                    raise Text2qtiError(f'In {self.source_name} on line {n+1}:\n{e}')
+                if not lookahead:
+                    n, line = next(n_line_iter, (0, None))
+                lookahead = False
+            if not self.questions_and_delims:
+                raise Text2qtiError('No questions were found')
+            if self._current_group is not None:
+                raise Text2qtiError(f'In {self.source_name} on line {len(string.splitlines())}:\nQuestion group never ended')
+            last_question_or_delim = self.questions_and_delims[-1]
+            if isinstance(last_question_or_delim, Question):
+                try:
+                    last_question_or_delim.finalize()
+                except Text2qtiError as e:
+                    raise Text2qtiError(f'In {self.source_name} on line {len(string.splitlines())}:\n{e}')
+
+            points_possible = 0
+            digests = []
+            for x in self.questions_and_delims:
+                if isinstance(x, Question):
+                    points_possible += x.points_possible
+                    digests.append(x.hash_digest)
+                elif isinstance(x, GroupStart):
+                    points_possible += x.group.points_per_question*x.group.pick
+                    digests.append(x.group.hash_digest)
+                elif isinstance(x, GroupEnd):
+                    pass
+                elif isinstance(x, TextRegion):
+                    pass
+                else:
+                    raise TypeError
+            self.points_possible = points_possible
+            h = hashlib.blake2b()
+            for digest in sorted(digests):
+                h.update(digest)
+            self.hash_digest = h.digest()
+            self.id = h.hexdigest()[:64]
+        finally:
+            self.md.finalize()
+
+    def _run_code(self, executable: str, code: str) -> str:
+        if not self.config['run_code_blocks']:
+            raise Text2qtiError('Code execution for code blocks is not enabled; use --run-code-blocks, or set run_code_blocks = true in config')
+        h = hashlib.blake2b()
+        h.update(code.encode('utf8'))
+        if platform.system() == 'Windows':
+            # Prevent console from appearing for an instant
+            startupinfo = subprocess.STARTUPINFO()
+            startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+        else:
+            startupinfo = None
+        with tempfile.TemporaryDirectory() as tempdir:
+            tempdir_path = pathlib.Path(tempdir)
+            code_path = tempdir_path / f'{h.hexdigest()[:16]}.code'
+            code_path.write_text(code, encoding='utf8')
+            if platform.system() == 'Windows':
+                # Modify executable since subprocess.Popen() ignores PATH
+                # * https://bugs.python.org/issue15451
+                # * https://bugs.python.org/issue8557
+                which_executable = shutil.which(executable)
+                if which_executable is None:
+                    raise Text2qtiError(f'Failed to execute code (missing executable "{executable}")')
+                cmd = [which_executable, code_path.as_posix()]
+            else:
+                cmd = [executable, code_path.as_posix()]
+            try:
+                # stdin is needed for GUI because standard file handles can't
+                # be inherited
+                proc = subprocess.run(cmd,
+                                      stdout=subprocess.PIPE, stderr=subprocess.PIPE, stdin=subprocess.PIPE,
+                                      startupinfo=startupinfo)
+            except FileNotFoundError as e:
+                raise Text2qtiError(f'Failed to execute code (missing executable "{executable}"?):\n{e}')
+            except Exception as e:
+                raise Text2qtiError(f'Failed to execute code with command "{cmd}":\n{e}')
+        # Use io to handle output as if read from a file in terms of newline
+        # treatment
+        if proc.returncode != 0:
+            stderr_str = io.TextIOWrapper(io.BytesIO(proc.stderr),
+                                          encoding=locale.getpreferredencoding(False),
+                                          errors='backslashreplace').read()
+            raise Text2qtiError(f'Code execution resulted in errors:\n{"-"*50}\n{stderr_str}\n{"-"*50}')
+        try:
+            stdout_str = io.TextIOWrapper(io.BytesIO(proc.stdout),
+                                          encoding=locale.getpreferredencoding(False)).read()
+        except Exception as e:
+            raise Text2qtiError(f'Failed to decode output of executed code:\n{e}')
+        return stdout_str
+
+    def append_quiz_title(self, text: str):
+        if any(x is not None for x in (self.shuffle_answers_raw, self.show_correct_answers_raw,
+                                       self.one_question_at_a_time_raw, self.cant_go_back_raw)):
+            raise Text2qtiError('Must give quiz title before quiz options')
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.title_raw is not None:
+            raise Text2qtiError('Quiz title has already been given')
+        if self.questions_and_delims:
+            raise Text2qtiError('Must give quiz title before questions')
+        if self.description_raw is not None:
+            raise Text2qtiError('Must give quiz title before quiz description')
+        self.title_raw = text
+        self.title_xml = self.md.xml_escape(text)
+
+    def append_quiz_description(self, text: str):
+        if any(x is not None for x in (self.shuffle_answers_raw, self.show_correct_answers_raw,
+                                       self.one_question_at_a_time_raw, self.cant_go_back_raw)):
+            raise Text2qtiError('Must give quiz description before quiz options')
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.description_raw is not None:
+            raise Text2qtiError('Quiz description has already been given')
+        if self.questions_and_delims:
+            raise Text2qtiError('Must give quiz description before questions')
+        self.description_raw = text
+        self.description_html_xml = self.md.md_to_html_xml(text)
+
+    def append_quiz_shuffle_answers(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.questions_and_delims:
+            raise Text2qtiError('Must give quiz options before questions')
+        if self.shuffle_answers_raw is not None:
+            raise Text2qtiError('Quiz option "Shuffle answers" has already been set')
+        if text not in ('true', 'True', 'false', 'False'):
+            raise Text2qtiError('Expected option value "true" or "false"')
+        self.shuffle_answers_raw = text
+        self.shuffle_answers_xml = text.lower()
+
+    def append_quiz_show_correct_answers(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.questions_and_delims:
+            raise Text2qtiError('Must give quiz options before questions')
+        if self.show_correct_answers_raw is not None:
+            raise Text2qtiError('Quiz option "Show correct answers" has already been set')
+        if text not in ('true', 'True', 'false', 'False'):
+            raise Text2qtiError('Expected option value "true" or "false"')
+        self.show_correct_answers_raw = text
+        self.show_correct_answers_xml = text.lower()
+
+    def append_quiz_one_question_at_a_time(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.questions_and_delims:
+            raise Text2qtiError('Must give quiz options before questions')
+        if self.one_question_at_a_time_raw is not None:
+            raise Text2qtiError('Quiz option "One question at a time" has already been set')
+        if text not in ('true', 'True', 'false', 'False'):
+            raise Text2qtiError('Expected option value "true" or "false"')
+        self.one_question_at_a_time_raw = text
+        self.one_question_at_a_time_xml = text.lower()
+
+    def append_quiz_cant_go_back(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.questions_and_delims:
+            raise Text2qtiError('Must give quiz options before questions')
+        if self.cant_go_back_raw is not None:
+            raise Text2qtiError('''Quiz option "Can't go back" has already been set''')
+        if text not in ('true', 'True', 'false', 'False'):
+            raise Text2qtiError('Expected option value "true" or "false"')
+        if self.one_question_at_a_time_xml != 'true':
+            raise Text2qtiError('''Must set "One question at a time" to "true" before setting "Can't go back"''')
+        self.cant_go_back_raw = text
+        self.cant_go_back_xml = text.lower()
+
+    def append_quiz_feedback_is_solution(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.questions_and_delims:
+            raise Text2qtiError('Must give quiz options before questions')
+        if self.feedback_is_solution is not None:
+            raise Text2qtiError('Quiz option "feedback is solution" has already been set')
+        if text in ('true', 'True'):
+            self.feedback_is_solution = True
+        elif text in ('false', 'False'):
+            self.feedback_is_solution = False
+        else:
+            raise Text2qtiError('Expected option value "true" or "false"')
+
+    def append_quiz_solutions_sample_groups(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.questions_and_delims:
+            raise Text2qtiError('Must give quiz options before questions')
+        if self.solutions_sample_groups is not None:
+            raise Text2qtiError('Quiz option "solutions sample groups" has already been set')
+        if text in ('true', 'True'):
+            self.solutions_sample_groups = True
+        elif text in ('false', 'False'):
+            self.solutions_sample_groups = False
+        else:
+            raise Text2qtiError('Expected option value "true" or "false"')
+
+    def append_quiz_solutions_randomize_groups(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.questions_and_delims:
+            raise Text2qtiError('Must give quiz options before questions')
+        if self.solutions_randomize_groups is not None:
+            raise Text2qtiError('Quiz option "solutions randomize groups" has already been set')
+        if text in ('true', 'True'):
+            self.solutions_randomize_groups = True
+        elif text in ('false', 'False'):
+            self.solutions_randomize_groups = False
+        else:
+            raise Text2qtiError('Expected option value "true" or "false"')
+
+    def append_text_title(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.questions_and_delims:
+            last_question_or_delim = self.questions_and_delims[-1]
+            if isinstance(last_question_or_delim, Question):
+                last_question_or_delim.finalize()
+        text_region = TextRegion(index=len(self.questions_and_delims), md=self.md)
+        text_region.set_title(text)
+        self.questions_and_delims.append(text_region)
+
+    def append_text(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self.questions_and_delims:
+            last_question_or_delim = self.questions_and_delims[-1]
+            if isinstance(last_question_or_delim, Question):
+                last_question_or_delim.finalize()
+            if isinstance(last_question_or_delim, TextRegion) and last_question_or_delim.text_raw is None:
+                last_question_or_delim.set_text(text)
+            else:
+                text_region = TextRegion(index=len(self.questions_and_delims), md=self.md)
+                text_region.set_text(text)
+                self.questions_and_delims.append(text_region)
+        else:
+            text_region = TextRegion(index=len(self.questions_and_delims), md=self.md)
+            text_region.set_text(text)
+            self.questions_and_delims.append(text_region)
+
+    def append_question(self, text: str):
+        if self.questions_and_delims:
+            last_question_or_delim = self.questions_and_delims[-1]
+            if isinstance(last_question_or_delim, Question):
+                last_question_or_delim.finalize()
+        question = Question(text,
+                            quiz=self,
+                            title=self._next_question_attr.get('title'),
+                            points=self._next_question_attr.get('points'),
+                            md=self.md)
+        self._next_question_attr = {}
+        if question.question_html_xml in self.question_set:
+            raise Text2qtiError('Duplicate question')
+        self.question_set.add(question.question_html_xml)
+        self.questions_and_delims.append(question)
+        if self._current_group is not None:
+            self._current_group.append_question(question)
+
+    def append_question_title(self, text: str):
+        if 'title' in self._next_question_attr:
+            raise Text2qtiError('Title for next question has already been set')
+        if 'points' in self._next_question_attr:
+            raise Text2qtiError('Title for next question must be set before point value')
+        self._next_question_attr['title'] = text
+
+    def append_question_points(self, text: str):
+        if 'points' in self._next_question_attr:
+            raise Text2qtiError('Points for next question has already been set')
+        self._next_question_attr['points'] = text
+
+    def append_feedback(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have feedback without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have feedback without a question')
+        last_question_or_delim.append_feedback(text)
+
+    def append_correct_feedback(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have feedback without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have feedback without a question')
+        last_question_or_delim.append_correct_feedback(text)
+
+    def append_incorrect_feedback(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have feedback without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have feedback without a question')
+        last_question_or_delim.append_incorrect_feedback(text)
+
+    def append_solution(self, text: str):
+        if self.feedback_is_solution:
+            raise Text2qtiError('Quiz option "feedback is solution" is "true"; '
+                                '"!" solution syntax is disabled and solutions must be provided as feedback ("...") rather than separately')
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have a solution without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have a solution without a question')
+        last_question_or_delim.append_solution(text)
+
+    def append_mctf_correct_choice(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have a choice without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have a choice without a question')
+        last_question_or_delim.append_mctf_correct_choice(text)
+
+    def append_mctf_incorrect_choice(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have a choice without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have a choice without a question')
+        last_question_or_delim.append_mctf_incorrect_choice(text)
+
+    def append_shortans_correct_choice(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have an answer without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have an answer without a question')
+        last_question_or_delim.append_shortans_correct_choice(text)
+
+    def append_multans_correct_choice(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have a choice without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have a choice without a question')
+        last_question_or_delim.append_multans_correct_choice(text)
+
+    def append_multans_incorrect_choice(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have a choice without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have a choice without a question')
+        last_question_or_delim.append_multans_incorrect_choice(text)
+
+    def append_essay(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have an essay response without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have an essay response without a question')
+        last_question_or_delim.append_essay(text)
+
+    def append_upload(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have an upload response without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have an upload response without a question')
+        last_question_or_delim.append_upload(text)
+
+    def append_numerical(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if not self.questions_and_delims:
+            raise Text2qtiError('Cannot have a numerical response without a question')
+        last_question_or_delim = self.questions_and_delims[-1]
+        if not isinstance(last_question_or_delim, Question):
+            raise Text2qtiError('Cannot have a numerical response without a question')
+        last_question_or_delim.append_numerical(text)
+
+    def append_start_group(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if text:
+            raise ValueError
+        if self._current_group is not None:
+            raise Text2qtiError('Question groups cannot be nested')
+        if self.questions_and_delims:
+            last_question_or_delim = self.questions_and_delims[-1]
+            if isinstance(last_question_or_delim, Question):
+                last_question_or_delim.finalize()
+        group = Group()
+        self._current_group = group
+        self.questions_and_delims.append(GroupStart(group))
+
+    def append_end_group(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if text:
+            raise ValueError
+        if self._current_group is None:
+            raise Text2qtiError('No question group to end')
+        if self.questions_and_delims:
+            last_question_or_delim = self.questions_and_delims[-1]
+            if isinstance(last_question_or_delim, Question):
+                last_question_or_delim.finalize()
+        self._current_group.finalize()
+        self.questions_and_delims.append(GroupEnd(self._current_group))
+        self._current_group = None
+
+    def append_group_pick(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self._current_group is None:
+            raise Text2qtiError('No question group for setting properties')
+        self._current_group.append_group_pick(text)
+
+    def append_group_solutions_pick(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self._current_group is None:
+            raise Text2qtiError('No question group for setting properties')
+        self._current_group.append_group_solutions_pick(text)
+
+    def append_group_points_per_question(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if self._current_group is None:
+            raise Text2qtiError('No question group for setting properties')
+        self._current_group.append_group_points_per_question(text)
+
+    def append_start_code(self, text: str):
+        raise Text2qtiError('Invalid code block start')
+
+    def append_end_code(self, text: str):
+        raise Text2qtiError('Code block end missing code block start')
+
+    def append_unknown(self, text: str):
+        if self._next_question_attr:
+            raise Text2qtiError('Expected question; question title and/or points were set but not used')
+        if text and not text.isspace():
+            match = start_missing_whitespace_re.match(text)
+            if match:
+                raise Text2qtiError(f'Missing whitespace after "{match.group().strip()}"')
+            match = start_missing_content_re.match(text)
+            if match:
+                raise Text2qtiError(f'Missing content after "{match.group().strip()}"')
+            raise Text2qtiError(f'Syntax error; unexpected text, or incorrect indentation for a wrapped paragraph:\n"{text}"')

text2qti/version.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+from .fmtversion import get_version_plus_info
+__version__, __version_info__ = get_version_plus_info(0, 7, 0, 'dev', 1)

text2qti/xml_assessment.py

@@ -0,0 +1,621 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+from .quiz import Quiz, Question, GroupStart, GroupEnd, TextRegion
+
+
+BEFORE_ITEMS = '''\
+<?xml version="1.0" encoding="UTF-8"?>
+<questestinterop xmlns="http://www.imsglobal.org/xsd/ims_qtiasiv1p2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.imsglobal.org/xsd/ims_qtiasiv1p2 http://www.imsglobal.org/xsd/ims_qtiasiv1p2p1.xsd">
+  <assessment ident="{assessment_identifier}" title="{title}">
+    <qtimetadata>
+      <qtimetadatafield>
+        <fieldlabel>cc_maxattempts</fieldlabel>
+        <fieldentry>1</fieldentry>
+      </qtimetadatafield>
+    </qtimetadata>
+    <section ident="root_section">
+'''
+
+AFTER_ITEMS = '''\
+    </section>
+  </assessment>
+</questestinterop>
+'''
+
+GROUP_START = '''\
+    <section ident="{ident}" title="{group_title}">
+      <selection_ordering>
+        <selection>
+          <selection_number>{pick}</selection_number>
+          <selection_extension>
+            <points_per_item>{points_per_item}</points_per_item>
+          </selection_extension>
+        </selection>
+      </selection_ordering>
+'''
+
+GROUP_END = '''\
+    </section>
+'''
+
+TEXT = '''\
+      <item ident="{ident}" title="{text_title_xml}">
+        <itemmetadata>
+          <qtimetadata>
+            <qtimetadatafield>
+              <fieldlabel>question_type</fieldlabel>
+              <fieldentry>text_only_question</fieldentry>
+            </qtimetadatafield>
+            <qtimetadatafield>
+              <fieldlabel>points_possible</fieldlabel>
+              <fieldentry>0</fieldentry>
+            </qtimetadatafield>
+            <qtimetadatafield>
+              <fieldlabel>original_answer_ids</fieldlabel>
+              <fieldentry></fieldentry>
+            </qtimetadatafield>
+            <qtimetadatafield>
+              <fieldlabel>assessment_question_identifierref</fieldlabel>
+              <fieldentry>{assessment_question_identifierref}</fieldentry>
+            </qtimetadatafield>
+          </qtimetadata>
+        </itemmetadata>
+        <presentation>
+          <material>
+            <mattext texttype="text/html">{text_html_xml}</mattext>
+          </material>
+        </presentation>
+      </item>
+'''
+
+START_ITEM = '''\
+      <item ident="{question_identifier}" title="{question_title}">
+'''
+
+END_ITEM = '''\
+      </item>
+'''
+
+
+ITEM_METADATA_MCTF_SHORTANS_MULTANS_NUM = '''\
+        <itemmetadata>
+          <qtimetadata>
+            <qtimetadatafield>
+              <fieldlabel>question_type</fieldlabel>
+              <fieldentry>{question_type}</fieldentry>
+            </qtimetadatafield>
+            <qtimetadatafield>
+              <fieldlabel>points_possible</fieldlabel>
+              <fieldentry>{points_possible}</fieldentry>
+            </qtimetadatafield>
+            <qtimetadatafield>
+              <fieldlabel>original_answer_ids</fieldlabel>
+              <fieldentry>{original_answer_ids}</fieldentry>
+            </qtimetadatafield>
+            <qtimetadatafield>
+              <fieldlabel>assessment_question_identifierref</fieldlabel>
+              <fieldentry>{assessment_question_identifierref}</fieldentry>
+            </qtimetadatafield>
+          </qtimetadata>
+        </itemmetadata>
+'''
+
+ITEM_METADATA_ESSAY = ITEM_METADATA_MCTF_SHORTANS_MULTANS_NUM.replace('{original_answer_ids}', '')
+
+ITEM_METADATA_UPLOAD = ITEM_METADATA_ESSAY
+
+ITEM_PRESENTATION_MCTF = '''\
+        <presentation>
+          <material>
+            <mattext texttype="text/html">{question_html_xml}</mattext>
+          </material>
+          <response_lid ident="response1" rcardinality="Single">
+            <render_choice>
+{choices}
+            </render_choice>
+          </response_lid>
+        </presentation>
+'''
+
+ITEM_PRESENTATION_MCTF_CHOICE = '''\
+              <response_label ident="{ident}">
+                <material>
+                  <mattext texttype="text/html">{choice_html_xml}</mattext>
+                </material>
+              </response_label>'''
+
+ITEM_PRESENTATION_MULTANS = ITEM_PRESENTATION_MCTF.replace('Single', 'Multiple')
+
+ITEM_PRESENTATION_MULTANS_CHOICE = ITEM_PRESENTATION_MCTF_CHOICE
+
+ITEM_PRESENTATION_SHORTANS = '''\
+        <presentation>
+          <material>
+            <mattext texttype="text/html">{question_html_xml}</mattext>
+          </material>
+          <response_str ident="response1" rcardinality="Single">
+            <render_fib>
+              <response_label ident="answer1" rshuffle="No"/>
+            </render_fib>
+          </response_str>
+        </presentation>
+'''
+
+ITEM_PRESENTATION_ESSAY = '''\
+        <presentation>
+          <material>
+            <mattext texttype="text/html">{question_html_xml}</mattext>
+          </material>
+          <response_str ident="response1" rcardinality="Single">
+            <render_fib>
+              <response_label ident="answer1" rshuffle="No"/>
+            </render_fib>
+          </response_str>
+        </presentation>
+'''
+
+ITEM_PRESENTATION_UPLOAD = '''\
+        <presentation>
+          <material>
+            <mattext texttype="text/html">{question_html_xml}</mattext>
+          </material>
+        </presentation>
+'''
+
+ITEM_PRESENTATION_NUM = '''\
+        <presentation>
+          <material>
+            <mattext texttype="text/html">{question_html_xml}</mattext>
+          </material>
+          <response_str ident="response1" rcardinality="Single">
+            <render_fib fibtype="Decimal">
+              <response_label ident="answer1"/>
+            </render_fib>
+          </response_str>
+        </presentation>
+'''
+
+
+ITEM_RESPROCESSING_START = '''\
+        <resprocessing>
+          <outcomes>
+            <decvar maxvalue="100" minvalue="0" varname="SCORE" vartype="Decimal"/>
+          </outcomes>
+'''
+
+ITEM_RESPROCESSING_MCTF_GENERAL_FEEDBACK = '''\
+          <respcondition continue="Yes">
+            <conditionvar>
+              <other/>
+            </conditionvar>
+            <displayfeedback feedbacktype="Response" linkrefid="general_fb"/>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_MCTF_CHOICE_FEEDBACK = '''\
+          <respcondition continue="Yes">
+            <conditionvar>
+              <varequal respident="response1">{ident}</varequal>
+            </conditionvar>
+            <displayfeedback feedbacktype="Response" linkrefid="{ident}_fb"/>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_MCTF_SET_CORRECT_WITH_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+              <varequal respident="response1">{ident}</varequal>
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+            <displayfeedback feedbacktype="Response" linkrefid="correct_fb"/>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_MCTF_SET_CORRECT_NO_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+              <varequal respident="response1">{ident}</varequal>
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_MCTF_INCORRECT_FEEDBACK = '''\
+          <respcondition continue="Yes">
+            <conditionvar>
+              <other/>
+            </conditionvar>
+            <displayfeedback feedbacktype="Response" linkrefid="general_incorrect_fb"/>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_SHORTANS_GENERAL_FEEDBACK = ITEM_RESPROCESSING_MCTF_GENERAL_FEEDBACK
+
+ITEM_RESPROCESSING_SHORTANS_CHOICE_FEEDBACK = '''\
+          <respcondition continue="Yes">
+            <conditionvar>
+              <varequal respident="response1">{answer_xml}</varequal>
+            </conditionvar>
+            <displayfeedback feedbacktype="Response" linkrefid="{ident}_fb"/>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_SHORTANS_SET_CORRECT_WITH_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+{varequal}
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+            <displayfeedback feedbacktype="Response" linkrefid="correct_fb"/>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_SHORTANS_SET_CORRECT_NO_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+{varequal}
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_SHORTANS_SET_CORRECT_VAREQUAL = '''\
+              <varequal respident="response1">{answer_xml}</varequal>'''
+
+ITEM_RESPROCESSING_SHORTANS_INCORRECT_FEEDBACK = ITEM_RESPROCESSING_MCTF_INCORRECT_FEEDBACK
+
+ITEM_RESPROCESSING_MULTANS_GENERAL_FEEDBACK = ITEM_RESPROCESSING_MCTF_GENERAL_FEEDBACK
+
+ITEM_RESPROCESSING_MULTANS_CHOICE_FEEDBACK = ITEM_RESPROCESSING_MCTF_CHOICE_FEEDBACK
+
+ITEM_RESPROCESSING_MULTANS_SET_CORRECT_WITH_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+              <and>
+{varequal}
+              </and>
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+            <displayfeedback feedbacktype="Response" linkrefid="correct_fb"/>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_MULTANS_SET_CORRECT_NO_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+              <and>
+{varequal}
+              </and>
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_MULTANS_SET_CORRECT_VAREQUAL_CORRECT = '''\
+                <varequal respident="response1">{ident}</varequal>'''
+
+ITEM_RESPROCESSING_MULTANS_SET_CORRECT_VAREQUAL_INCORRECT = '''\
+                <not>
+                  <varequal respident="response1">{ident}</varequal>
+                </not>'''
+
+ITEM_RESPROCESSING_MULTANS_INCORRECT_FEEDBACK = ITEM_RESPROCESSING_MCTF_INCORRECT_FEEDBACK
+
+ITEM_RESPROCESSING_ESSAY_GENERAL_FEEDBACK = ITEM_RESPROCESSING_MCTF_GENERAL_FEEDBACK
+
+ITEM_RESPROCESSING_UPLOAD_GENERAL_FEEDBACK = ITEM_RESPROCESSING_MCTF_GENERAL_FEEDBACK
+
+ITEM_RESPROCESSING_NUM_GENERAL_FEEDBACK = ITEM_RESPROCESSING_MCTF_GENERAL_FEEDBACK
+
+ITEM_RESPROCESSING_NUM_RANGE_SET_CORRECT_WITH_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+              <vargte respident="response1">{num_min}</vargte>
+              <varlte respident="response1">{num_max}</varlte>
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+            <displayfeedback feedbacktype="Response" linkrefid="correct_fb"/>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_NUM_RANGE_SET_CORRECT_NO_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+              <vargte respident="response1">{num_min}</vargte>
+              <varlte respident="response1">{num_max}</varlte>
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_NUM_EXACT_SET_CORRECT_WITH_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+              <or>
+                <varequal respident="response1">{num_exact}</varequal>
+                <and>
+                  <vargte respident="response1">{num_min}</vargte>
+                  <varlte respident="response1">{num_max}</varlte>
+                </and>
+              </or>
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+            <displayfeedback feedbacktype="Response" linkrefid="correct_fb"/>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_NUM_EXACT_SET_CORRECT_NO_FEEDBACK = '''\
+          <respcondition continue="No">
+            <conditionvar>
+              <or>
+                <varequal respident="response1">{num_exact}</varequal>
+                <and>
+                  <vargte respident="response1">{num_min}</vargte>
+                  <varlte respident="response1">{num_max}</varlte>
+                </and>
+              </or>
+            </conditionvar>
+            <setvar action="Set" varname="SCORE">100</setvar>
+          </respcondition>
+'''
+
+ITEM_RESPROCESSING_NUM_INCORRECT_FEEDBACK = ITEM_RESPROCESSING_MCTF_INCORRECT_FEEDBACK
+
+ITEM_RESPROCESSING_ESSAY = '''\
+          <respcondition continue="No">
+            <conditionvar>
+              <other/>
+            </conditionvar>
+          </respcondition>
+'''
+
+
+
+ITEM_RESPROCESSING_END = '''\
+        </resprocessing>
+'''
+
+
+ITEM_FEEDBACK_MCTF_SHORTANS_MULTANS_NUM_GENERAL = '''\
+        <itemfeedback ident="general_fb">
+          <flow_mat>
+            <material>
+              <mattext texttype="text/html">{feedback}</mattext>
+            </material>
+          </flow_mat>
+        </itemfeedback>
+'''
+
+ITEM_FEEDBACK_MCTF_SHORTANS_MULTANS_NUM_CORRECT = '''\
+        <itemfeedback ident="correct_fb">
+          <flow_mat>
+            <material>
+              <mattext texttype="text/html">{feedback}</mattext>
+            </material>
+          </flow_mat>
+        </itemfeedback>
+'''
+
+ITEM_FEEDBACK_MCTF_SHORTANS_MULTANS_NUM_INCORRECT = '''\
+        <itemfeedback ident="general_incorrect_fb">
+          <flow_mat>
+            <material>
+              <mattext texttype="text/html">{feedback}</mattext>
+            </material>
+          </flow_mat>
+        </itemfeedback>
+'''
+
+ITEM_FEEDBACK_MCTF_SHORTANS_MULTANS_NUM_INDIVIDUAL = '''\
+        <itemfeedback ident="{ident}_fb">
+          <flow_mat>
+            <material>
+              <mattext texttype="text/html">{feedback}</mattext>
+            </material>
+          </flow_mat>
+        </itemfeedback>
+'''
+
+
+
+
+def assessment(*, quiz: Quiz, assessment_identifier: str, title_xml: str) -> str:
+    '''
+    Generate assessment XML from Quiz.
+    '''
+    xml = []
+    xml.append(BEFORE_ITEMS.format(assessment_identifier=assessment_identifier,
+                                   title=title_xml))
+    for question_or_delim in quiz.questions_and_delims:
+        if isinstance(question_or_delim, TextRegion):
+            xml.append(TEXT.format(ident=f'text2qti_text_{question_or_delim.id}',
+                                   text_title_xml=question_or_delim.title_xml,
+                                   assessment_question_identifierref=f'text2qti_question_ref_{question_or_delim.id}',
+                                   text_html_xml=question_or_delim.text_html_xml))
+            continue
+        if isinstance(question_or_delim, GroupStart):
+            xml.append(GROUP_START.format(ident=f'text2qti_group_{question_or_delim.group.id}',
+                                          group_title=question_or_delim.group.title_xml,
+                                          pick=question_or_delim.group.pick,
+                                          points_per_item=question_or_delim.group.points_per_question))
+            continue
+        if isinstance(question_or_delim, GroupEnd):
+            xml.append(GROUP_END)
+            continue
+        if not isinstance(question_or_delim, Question):
+            raise TypeError
+        question = question_or_delim
+
+        xml.append(START_ITEM.format(question_identifier=f'text2qti_question_{question.id}',
+                                     question_title=question.title_xml))
+
+        if question.type in ('true_false_question', 'multiple_choice_question',
+                             'short_answer_question', 'multiple_answers_question'):
+            item_metadata = ITEM_METADATA_MCTF_SHORTANS_MULTANS_NUM
+            original_answer_ids = ','.join(f'text2qti_choice_{c.id}' for c in question.choices)
+        elif question.type == 'numerical_question':
+            item_metadata = ITEM_METADATA_MCTF_SHORTANS_MULTANS_NUM
+            original_answer_ids = f'text2qti_numerical_{question.id}'
+        elif question.type == 'essay_question':
+            item_metadata = ITEM_METADATA_ESSAY
+            original_answer_ids = f'text2qti_essay_{question.id}'
+        elif question.type == 'file_upload_question':
+            item_metadata = ITEM_METADATA_UPLOAD
+            original_answer_ids = f'text2qti_upload_{question.id}'
+        else:
+            raise ValueError
+        xml.append(item_metadata.format(question_type=question.type,
+                                        points_possible=question.points_possible,
+                                        original_answer_ids=original_answer_ids,
+                                        assessment_question_identifierref=f'text2qti_question_ref_{question.id}'))
+
+        if question.type in ('true_false_question', 'multiple_choice_question', 'multiple_answers_question'):
+            if question.type in ('true_false_question', 'multiple_choice_question'):
+                item_presentation_choice = ITEM_PRESENTATION_MCTF_CHOICE
+                item_presentation = ITEM_PRESENTATION_MCTF
+            elif question.type == 'multiple_answers_question':
+                item_presentation_choice = ITEM_PRESENTATION_MULTANS_CHOICE
+                item_presentation = ITEM_PRESENTATION_MULTANS
+            else:
+                raise ValueError
+            choices = '\n'.join(item_presentation_choice.format(ident=f'text2qti_choice_{c.id}', choice_html_xml=c.choice_html_xml)
+                                                                for c in question.choices)
+            xml.append(item_presentation.format(question_html_xml=question.question_html_xml, choices=choices))
+        elif question.type == 'short_answer_question':
+            xml.append(ITEM_PRESENTATION_SHORTANS.format(question_html_xml=question.question_html_xml))
+        elif question.type == 'numerical_question':
+            xml.append(ITEM_PRESENTATION_NUM.format(question_html_xml=question.question_html_xml))
+        elif question.type == 'essay_question':
+            xml.append(ITEM_PRESENTATION_ESSAY.format(question_html_xml=question.question_html_xml))
+        elif question.type == 'file_upload_question':
+            xml.append(ITEM_PRESENTATION_UPLOAD.format(question_html_xml=question.question_html_xml))
+        else:
+            raise ValueError
+
+        if question.type in ('true_false_question', 'multiple_choice_question'):
+            correct_choice = None
+            for choice in question.choices:
+                if choice.correct:
+                  correct_choice = choice
+                  break
+            if correct_choice is None:
+                raise TypeError
+            resprocessing = []
+            resprocessing.append(ITEM_RESPROCESSING_START)
+            if question.feedback_raw is not None:
+                resprocessing.append(ITEM_RESPROCESSING_MCTF_GENERAL_FEEDBACK)
+            for choice in question.choices:
+                if choice.feedback_raw is not None:
+                    resprocessing.append(ITEM_RESPROCESSING_MCTF_CHOICE_FEEDBACK.format(ident=f'text2qti_choice_{choice.id}'))
+            if question.correct_feedback_raw is not None:
+                resprocessing.append(ITEM_RESPROCESSING_MCTF_SET_CORRECT_WITH_FEEDBACK.format(ident=f'text2qti_choice_{correct_choice.id}'))
+            else:
+                resprocessing.append(ITEM_RESPROCESSING_MCTF_SET_CORRECT_NO_FEEDBACK.format(ident=f'text2qti_choice_{correct_choice.id}'))
+            if question.incorrect_feedback_raw is not None:
+                resprocessing.append(ITEM_RESPROCESSING_MCTF_INCORRECT_FEEDBACK)
+            resprocessing.append(ITEM_RESPROCESSING_END)
+            xml.extend(resprocessing)
+        elif question.type == 'short_answer_question':
+            resprocessing = []
+            resprocessing.append(ITEM_RESPROCESSING_START)
+            if question.feedback_raw is not None:
+                resprocessing.append(ITEM_RESPROCESSING_SHORTANS_GENERAL_FEEDBACK)
+            for choice in question.choices:
+                if choice.feedback_raw is not None:
+                    resprocessing.append(ITEM_RESPROCESSING_SHORTANS_CHOICE_FEEDBACK.format(ident=f'text2qti_choice_{choice.id}', answer_xml=choice.choice_xml))
+            varequal = []
+            for choice in question.choices:
+                varequal.append(ITEM_RESPROCESSING_SHORTANS_SET_CORRECT_VAREQUAL.format(answer_xml=choice.choice_xml))
+            if question.correct_feedback_raw is not None:
+                resprocessing.append(ITEM_RESPROCESSING_SHORTANS_SET_CORRECT_WITH_FEEDBACK.format(varequal='\n'.join(varequal)))
+            else:
+                resprocessing.append(ITEM_RESPROCESSING_SHORTANS_SET_CORRECT_NO_FEEDBACK.format(varequal='\n'.join(varequal)))
+            if question.incorrect_feedback_raw is not None:
+                resprocessing.append(ITEM_RESPROCESSING_SHORTANS_INCORRECT_FEEDBACK)
+            resprocessing.append(ITEM_RESPROCESSING_END)
+            xml.extend(resprocessing)
+        elif question.type == 'multiple_answers_question':
+            resprocessing = []
+            resprocessing.append(ITEM_RESPROCESSING_START)
+            if question.feedback_raw is not None:
+                resprocessing.append(ITEM_RESPROCESSING_MULTANS_GENERAL_FEEDBACK)
+            for choice in question.choices:
+                if choice.feedback_raw is not None:
+                    resprocessing.append(ITEM_RESPROCESSING_MULTANS_CHOICE_FEEDBACK.format(ident=f'text2qti_choice_{choice.id}'))
+            varequal = []
+            for choice in question.choices:
+                if choice.correct:
+                    varequal.append(ITEM_RESPROCESSING_MULTANS_SET_CORRECT_VAREQUAL_CORRECT.format(ident=f'text2qti_choice_{choice.id}'))
+                else:
+                    varequal.append(ITEM_RESPROCESSING_MULTANS_SET_CORRECT_VAREQUAL_INCORRECT.format(ident=f'text2qti_choice_{choice.id}'))
+            if question.correct_feedback_raw is not None:
+                resprocessing.append(ITEM_RESPROCESSING_MULTANS_SET_CORRECT_WITH_FEEDBACK.format(varequal='\n'.join(varequal)))
+            else:
+                resprocessing.append(ITEM_RESPROCESSING_MULTANS_SET_CORRECT_NO_FEEDBACK.format(varequal='\n'.join(varequal)))
+            if question.incorrect_feedback_raw is not None:
+                resprocessing.append(ITEM_RESPROCESSING_MULTANS_INCORRECT_FEEDBACK)
+            resprocessing.append(ITEM_RESPROCESSING_END)
+            xml.extend(resprocessing)
+        elif question.type == 'numerical_question':
+            xml.append(ITEM_RESPROCESSING_START)
+            if question.feedback_raw is not None:
+              xml.append(ITEM_RESPROCESSING_NUM_GENERAL_FEEDBACK)
+            if question.correct_feedback_raw is None:
+                if question.numerical_exact is None:
+                    item_resprocessing_num_set_correct = ITEM_RESPROCESSING_NUM_RANGE_SET_CORRECT_NO_FEEDBACK
+                else:
+                    item_resprocessing_num_set_correct = ITEM_RESPROCESSING_NUM_EXACT_SET_CORRECT_NO_FEEDBACK
+            else:
+                if question.numerical_exact is None:
+                    item_resprocessing_num_set_correct = ITEM_RESPROCESSING_NUM_RANGE_SET_CORRECT_WITH_FEEDBACK
+                else:
+                    item_resprocessing_num_set_correct = ITEM_RESPROCESSING_NUM_EXACT_SET_CORRECT_WITH_FEEDBACK
+            xml.append(item_resprocessing_num_set_correct.format(num_min=question.numerical_min_html_xml,
+                                                                 num_exact=question.numerical_exact_html_xml,
+                                                                 num_max=question.numerical_max_html_xml))
+            if question.incorrect_feedback_raw is not None:
+                xml.append(ITEM_RESPROCESSING_NUM_INCORRECT_FEEDBACK)
+            xml.append(ITEM_RESPROCESSING_END)
+        elif question.type == 'essay_question':
+            xml.append(ITEM_RESPROCESSING_START)
+            xml.append(ITEM_RESPROCESSING_ESSAY)
+            if question.feedback_raw is not None:
+                xml.append(ITEM_RESPROCESSING_ESSAY_GENERAL_FEEDBACK)
+            xml.append(ITEM_RESPROCESSING_END)
+        elif question.type == 'file_upload_question':
+            xml.append(ITEM_RESPROCESSING_START)
+            if question.feedback_raw is not None:
+                xml.append(ITEM_RESPROCESSING_UPLOAD_GENERAL_FEEDBACK)
+            xml.append(ITEM_RESPROCESSING_END)
+        else:
+            raise ValueError
+
+        if question.type in ('true_false_question', 'multiple_choice_question',
+                             'short_answer_question', 'multiple_answers_question',
+                             'numerical_question', 'essay_question', 'file_upload_question'):
+            if question.feedback_raw is not None:
+                xml.append(ITEM_FEEDBACK_MCTF_SHORTANS_MULTANS_NUM_GENERAL.format(feedback=question.feedback_html_xml))
+            if question.correct_feedback_raw is not None:
+                xml.append(ITEM_FEEDBACK_MCTF_SHORTANS_MULTANS_NUM_CORRECT.format(feedback=question.correct_feedback_html_xml))
+            if question.incorrect_feedback_raw is not None:
+                xml.append(ITEM_FEEDBACK_MCTF_SHORTANS_MULTANS_NUM_INCORRECT.format(feedback=question.incorrect_feedback_html_xml))
+        if question.type in ('true_false_question', 'multiple_choice_question',
+                             'short_answer_question', 'multiple_answers_question'):
+            for choice in question.choices:
+                if choice.feedback_raw is not None:
+                    xml.append(ITEM_FEEDBACK_MCTF_SHORTANS_MULTANS_NUM_INDIVIDUAL.format(ident=f'text2qti_choice_{choice.id}',
+                                                                                         feedback=choice.feedback_html_xml))
+
+        xml.append(END_ITEM)
+
+    xml.append(AFTER_ITEMS)
+
+    return ''.join(xml)

text2qti/xml_assessment_meta.py

@@ -0,0 +1,110 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+from typing import Union
+
+
+TEMPLATE = '''\
+<?xml version="1.0" encoding="UTF-8"?>
+<quiz identifier="{assessment_identifier}" xmlns="http://canvas.instructure.com/xsd/cccv1p0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://canvas.instructure.com/xsd/cccv1p0 https://canvas.instructure.com/xsd/cccv1p0.xsd">
+  <title>{title}</title>
+  <description>{description}</description>
+  <shuffle_answers>{shuffle_answers}</shuffle_answers>
+  <scoring_policy>keep_highest</scoring_policy>
+  <hide_results>{hide_results}</hide_results>
+  <quiz_type>assignment</quiz_type>
+  <points_possible>{points_possible:.1f}</points_possible>
+  <require_lockdown_browser>false</require_lockdown_browser>
+  <require_lockdown_browser_for_results>false</require_lockdown_browser_for_results>
+  <require_lockdown_browser_monitor>false</require_lockdown_browser_monitor>
+  <lockdown_browser_monitor_data/>
+  <show_correct_answers>{show_correct_answers}</show_correct_answers>
+  <anonymous_submissions>false</anonymous_submissions>
+  <could_be_locked>false</could_be_locked>
+  <allowed_attempts>1</allowed_attempts>
+  <one_question_at_a_time>{one_question_at_a_time}</one_question_at_a_time>
+  <cant_go_back>{cant_go_back}</cant_go_back>
+  <available>false</available>
+  <one_time_results>false</one_time_results>
+  <show_correct_answers_last_attempt>false</show_correct_answers_last_attempt>
+  <only_visible_to_overrides>false</only_visible_to_overrides>
+  <module_locked>false</module_locked>
+  <assignment identifier="{assignment_identifier}">
+    <title>{title}</title>
+    <due_at/>
+    <lock_at/>
+    <unlock_at/>
+    <module_locked>false</module_locked>
+    <workflow_state>unpublished</workflow_state>
+    <assignment_overrides>
+    </assignment_overrides>
+    <quiz_identifierref>{assessment_identifier}</quiz_identifierref>
+    <allowed_extensions></allowed_extensions>
+    <has_group_category>false</has_group_category>
+    <points_possible>{points_possible:.1f}</points_possible>
+    <grading_type>points</grading_type>
+    <all_day>false</all_day>
+    <submission_types>online_quiz</submission_types>
+    <position>1</position>
+    <turnitin_enabled>false</turnitin_enabled>
+    <vericite_enabled>false</vericite_enabled>
+    <peer_review_count>0</peer_review_count>
+    <peer_reviews>false</peer_reviews>
+    <automatic_peer_reviews>false</automatic_peer_reviews>
+    <anonymous_peer_reviews>false</anonymous_peer_reviews>
+    <grade_group_students_individually>false</grade_group_students_individually>
+    <freeze_on_copy>false</freeze_on_copy>
+    <omit_from_final_grade>false</omit_from_final_grade>
+    <intra_group_peer_reviews>false</intra_group_peer_reviews>
+    <only_visible_to_overrides>false</only_visible_to_overrides>
+    <post_to_sis>false</post_to_sis>
+    <moderated_grading>false</moderated_grading>
+    <grader_count>0</grader_count>
+    <grader_comments_visible_to_graders>true</grader_comments_visible_to_graders>
+    <anonymous_grading>false</anonymous_grading>
+    <graders_anonymous_to_graders>false</graders_anonymous_to_graders>
+    <grader_names_visible_to_final_grader>true</grader_names_visible_to_final_grader>
+    <anonymous_instructor_annotations>false</anonymous_instructor_annotations>
+    <post_policy>
+      <post_manually>false</post_manually>
+    </post_policy>
+  </assignment>
+  <assignment_group_identifierref>{assignment_group_identifier}</assignment_group_identifierref>
+  <assignment_overrides>
+  </assignment_overrides>
+</quiz>
+'''
+
+
+def assessment_meta(*,
+                    assessment_identifier: str,
+                    assignment_group_identifier: str,
+                    assignment_identifier: str,
+                    title_xml: str,
+                    description_html_xml: str,
+                    points_possible: Union[int, float],
+                    shuffle_answers: str,
+                    show_correct_answers: str,
+                    one_question_at_a_time: str,
+                    cant_go_back: str) -> str:
+    '''
+    Generate `assessment_meta.xml`.
+    '''
+    return TEMPLATE.format(assessment_identifier=assessment_identifier,
+                           assignment_identifier=assignment_identifier,
+                           assignment_group_identifier=assignment_group_identifier,
+                           title=title_xml,
+                           description=description_html_xml,
+                           points_possible=points_possible,
+                           shuffle_answers=shuffle_answers,
+                           show_correct_answers=show_correct_answers,
+                           hide_results='always' if show_correct_answers == 'false' else '',
+                           one_question_at_a_time=one_question_at_a_time,
+                           cant_go_back=cant_go_back)

text2qti/xml_imsmanifest.py

@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Geoffrey M. Poore
+# All rights reserved.
+#
+# Licensed under the BSD 3-Clause License:
+# http://opensource.org/licenses/BSD-3-Clause
+#
+
+
+import datetime
+from typing import Dict, Optional
+from .quiz import Image
+
+
+MANIFEST_START = '''\
+<?xml version="1.0" encoding="UTF-8"?>
+<manifest identifier="{manifest_identifier}" xmlns="http://www.imsglobal.org/xsd/imsccv1p1/imscp_v1p1" xmlns:lom="http://ltsc.ieee.org/xsd/imsccv1p1/LOM/resource" xmlns:imsmd="http://www.imsglobal.org/xsd/imsmd_v1p2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.imsglobal.org/xsd/imsccv1p1/imscp_v1p1 http://www.imsglobal.org/xsd/imscp_v1p1.xsd http://ltsc.ieee.org/xsd/imsccv1p1/LOM/resource http://www.imsglobal.org/profile/cc/ccv1p1/LOM/ccv1p1_lomresource_v1p0.xsd http://www.imsglobal.org/xsd/imsmd_v1p2 http://www.imsglobal.org/xsd/imsmd_v1p2p2.xsd">
+  <metadata>
+    <schema>IMS Content</schema>
+    <schemaversion>1.1.3</schemaversion>
+    <imsmd:lom>
+      <imsmd:general>
+        <imsmd:title>
+          <imsmd:string>QTI assessment generated by text2qti</imsmd:string>
+        </imsmd:title>
+      </imsmd:general>
+      <imsmd:lifeCycle>
+        <imsmd:contribute>
+          <imsmd:date>
+            <imsmd:dateTime>{date}</imsmd:dateTime>
+          </imsmd:date>
+        </imsmd:contribute>
+      </imsmd:lifeCycle>
+      <imsmd:rights>
+        <imsmd:copyrightAndOtherRestrictions>
+          <imsmd:value>yes</imsmd:value>
+        </imsmd:copyrightAndOtherRestrictions>
+        <imsmd:description>
+          <imsmd:string>Private (Copyrighted) - http://en.wikipedia.org/wiki/Copyright</imsmd:string>
+        </imsmd:description>
+      </imsmd:rights>
+    </imsmd:lom>
+  </metadata>
+  <organizations/>
+  <resources>
+    <resource identifier="{assessment_identifier}" type="imsqti_xmlv1p2">
+      <file href="{assessment_identifier}/{assessment_identifier}.xml"/>
+      <dependency identifierref="{dependency_identifier}"/>
+    </resource>
+    <resource identifier="{dependency_identifier}" type="associatedcontent/imscc_xmlv1p1/learning-application-resource" href="{assessment_identifier}/assessment_meta.xml">
+      <file href="{assessment_identifier}/assessment_meta.xml"/>
+    </resource>
+'''
+
+IMAGE = '''\
+    <resource identifier="text2qti_image_{ident}" type="webcontent" href="{path}">
+      <file href="{path}"/>
+    </resource>
+'''
+
+MANIFEST_END = '''\
+  </resources>
+</manifest>
+'''
+
+
+def imsmanifest(*,
+                manifest_identifier: str,
+                assessment_identifier: str,
+                dependency_identifier: str,
+                images: Dict[str, Image],
+                date: Optional[str]=None) -> str:
+    '''
+    Generate `imsmanifest.xml`.
+    '''
+    if date is None:
+        date = str(datetime.date.today())
+    xml = []
+    xml.append(MANIFEST_START.format(manifest_identifier=manifest_identifier,
+                                     assessment_identifier=assessment_identifier,
+                                     dependency_identifier=dependency_identifier,
+                                     date=date))
+    for image in images.values():
+        xml.append(IMAGE.format(ident=image.id, path=image.qti_xml_path))
+    xml.append(MANIFEST_END)
+    return ''.join(xml)