Package: randassign
Author:Geoffrey M. PooreLicense:BSD 3-ClauseCreate randomized assignments with solutions/keys using Python and LaTeX.ContentsInstallationStandard usageError handlingCustomizationInstallationPython 2.7 and 3.2+ are officially supported.For the latest version, download the source fromGitHub, then run:python setup.py installThe package is also available onPyPI(the Python Package Index).  Install
via:pip install randassignOr use:easy_install randassignRequires thePythonTeXpackage for LaTeX.  PythonTeX is part of the fullTeX Liveinstallation; it may also be installed via the TeX Live package
manager, or using the Python installation script that is bundled with PythonTeX
(this supports MiKTeX).Standard usageThe steps to create a typical randomized assignment are listed below.  Or
consult the availablecomplete examples.Create a LaTeX document, with\usepackage{pythontex}.  Have this file\inputa filename.texthat contains a placeholder name for the
person who will take the assignment.  Also\inputa fileattempt.texthat contains a placeholder integer for the number of attempts the person
taking the assignment has made (optional; depends on keyword argumentmultipleattempts, described below).Write the assignment within the LaTeX document, using PythonTeX as desired
to generate random values for parameters.At the beginning of each PythonTeX session:from randassign import RandAssign
ra = RandAssign()Within the session, add solutions viara.addsoln().  This takes
an arbitrary number of arguments, corresponding to the solutions for a
single problem; if multiple arguments are received, they are treated as
the solutions to a multi-part problem.  The optional, keyword argumentinfois used to pass information about the problem into the
solutions.  The keyword argumentnumbermay be used to set the
problem number manually when the problems created in a session are not
directly sequential.  When solutions are created withaddsoln(),
solutions are formatted automatically; only the actual answers and any
accompanying info need be provided.Alternately, solutions may be created by appending text to the listra.soln.  Solutions created in this way will not be automatically
numbered and formatted; the user has complete, direct control over the form
of the solution text.  Any desired linebreaks must be included explicitly as\nin the text that is appended tora.soln.  This method of creating
solutions may not be mixed withra.addsoln().Create a text filestudents.txtthat contains the names of all
individuals for whom assignments are to be generated, with one name per line.
Commas should only appear in names in “Last, First” format.  Put this file
in the same directory as the LaTeX file.Run the command-line utilityrandassign:randassign <tex_file>By default, this will create a directoryrandassignin the LaTeX file’s
directory.  Within this will be anassignmentsdirectory that contains
an assignment for each student, and asolutionsdirectory that contains
complete solutions for all students within a single PDF document, as well
as a data file in JSON format.Run therandassignutility again as desired to create additional
assignments to allow for additional attempts.  Solutions will be updated
automatically.  Use the--student<student>command-line flag to
generate an additional assignment for only a single student.Error handlingTherandassignutility (andmake()function) is carefully designed so
that if an error occurs during a run, all assignments generated during that run
will automatically be discarded.  If an error occurs, it should typically be
adequate to resolve the error and then runrandassignagain, without
performing any manual cleanup from the failed run.In the event that automatic cleanup somehow fails,randassignalso creates
backups of the data file in which raw assignment data and metadata are stored.
These are saved in the same directory as the data file, which is by default
in the directory with the solutions.CustomizationTherandassignutility accepts a limited number of command-line arguments
to customize settings.  Runrandassign--helpfor a list of available
options.Further customization is available by creating a Python script and passing
arguments torandassign’smake()function:from randassign import make
make(texfile='<tex_file>', <kwargs>)Themake()function accepts the following keyword arguments.  Note that
all paths (including all*dirkeywords) are interpreted relative to the
LaTeX file’s directory, rather than relative to the current working directory.
This ensures that LaTeX functions smoothly and does not attempt to write to
directories outside the document directory and its subdirectories.  Absolute
paths may be used when this behavior is not desired.Unix-style paths with forward slashes, and with leading~expanding to the
user’s home directory, will work under all systems, including Windows.argv(bool) default:TrueWhether to supplement supplied arguments fromsys.argv, using the parser
from therandassigncommand-line utility.verbose(bool) default:FalseVerbose output.silent(bool) default:FalseSuppress all output.texfile(str)LaTeX file from which to generate assignments.texcmd(strorlistofstr) default:pdflatex-interaction=nonstopmodeCommand for compiling LaTeX file (does not include file name).pythontexcmd(strorlistofstr) default:pythontex--rerunalwaysCommand for running PythonTeX (does not include file name).randassigndir(str) default:randassignRoot directory for saving created assignments and solutions.subdirs(bool) default:TrueWhether to create subdirectories underrandassigndirfor assignments and
solutions.assigndir(str) default:assignmentsSubdirectory for assignments.solndir(str) default:solutionsSubdirectory for solutions.namefile(str) default:name.texLaTeX file containing the name of the current student.attemptfile(str) default:attempt.texLaTeX file containing the number of the current attempt.student(str) default:NoneAn individual student for whom to generate assignments.studentfile(str) default:students.txtFile containing the names of all students.txtfiles with names in
“Last, First” or “First Last” form are accepted, as well as CSV files with
the first column containing last names and the second column containing first
names (with no header row).parsestudentfile(function)Function for parsing the student file and returning a list of student names
in the form needed for assignments.  See_parsestudentfileinmake.pyfor an example.parsestudentname(function)Function for parsing individual lines/rows of the student file into student
names in the desired format.onlysolutions(bool) default:FalseOnly generate solutions; do not generate any assignments.  Useful for
regenerating solutions in a different format or with a different template.solnfile(str)  default:solutions.texSolution file.solnfmt(str)  default:texSolution file format.texandmd/markdownare accepted.solncmd(strorlistofstr, orNone)  default:pdflatex-interaction=nonstopmodeCommand for post-processing solution file (does not include file name).
Should beNone/evaluate toFalseif no post-processing is desired.writesoln(function)Function for writing the solutions, given the solution data, templates, and
other parameters.  See_writesoln()inmake.pyfor an example.msgfilepattern(str) default:_randassign.*.jsonPattern for identifying “message” files, files containing solutions, that are
saved by PythonTeX and used to pass data to RandAssign.onlylastsoln(bool) default:FalseSolutions include all solutions for all attempts for each students, or only
the solutions from the most recent attempt (all solutions are still saved in
the data file).multipleattempts(bool) default:TrueWhether multiple attempts will be given for an assignment; this determines
whether attempts are listed/numbered in solutions.randassigndatafile(str)  default:<solndir>/<tex_filename>.<randassigndatafilefmt>File for saving raw solution data and associated metadata.randassigndatafilefmt(str) default:json.zipFormat for data file.  Accepted options arejson,json.zip, andpickle/pkl.solntemplatedoc(str)Template for overall solution document; see examples inmake.py.solntemplatestudent(str)Template for overall solutions for each student.solntemplatesolnsattempt(str)Template for attempt heading.solntemplatesolnswrapper(str)Template for wrapping a set of solutions, if the set of solutions needs to be
preceded and followed by markup.solntemplatesolnsingle(str)Template for a one-part solution.solntemplatesolnsingleinfo(str)Template for a one-part solution that includes additional info from the
problem.solntemplatesolnmultiwrapper(str)Template for wrapping a multi-part solution.solntemplatesolnmultiwrapperinfo(str)Template for wrapping a multi-part solution that includes additional info
from the problem.solntemplatesolnmulti(str)Template for each piece of a multi-part solution.