Other supporting code

Tools for demos and semi-automated testing

Scribbling on papers

Plom tools for scribbling fake answers on PDF files.

plom.create.scribble_utils.fill_in_fake_data_on_exams(paper_dir, classlist, outfile, *, which=None)[source]

Fill-in exams with fake data for demo or testing.

Parameters:

  • paper_dir (str/pathlib.Path) – Directory containing the blank exams.

  • classlist (list) – list of dicts with keys id and name. See also Issue #1646: maybe will use student_number someday.

  • outfile (str/pathlib.Path) – write results into this concatenated PDF file.

Keyword Arguments:

which (iterable) – By default we scribble on all exams or specify something like which=range(10, 16) here to scribble on a subset. (default: None)

Returns:

None

plom.create.scribble_utils.make_colliding_pages(paper_dir, outfile)[source]

Build two colliding pages - last pages of papers 2 and 3.

Parameters:

  • paper_dir (str/pathlib.Path) – Directory containing the blank exams.

  • outfile (pathlib.Path) – modify this pdf file, appending the colliding pages.

Intended for testing.

plom.create.scribble_utils.make_garbage_pages(pdf_file, number_of_garbage_pages=2)[source]

Randomly generates and inserts garbage pages into a PDF document.

Parameters:

pdf_file (pathlib.Path) – a pdf file we add pages to.

Keyword Arguments:

number_of_garbage_pages (int) – how many junk pages to add (default: 2)

Returns:

None

Intended for testing.

plom.create.scribble_utils.make_scribbles(basedir=PosixPath('.'), *, msgr)[source]

Fake exam writing by scribbling on the pages of the blank exams.

After Plom exam PDF files have been generated, this can be used to scribble on them to simulate random student work. Note this tool does not upload those files, it just makes some PDF files for you to play with or for testing purposes.

Parameters:

basedir (str/pathlib.Path) – the blank tests (for scribbling) will be taken from basedir/papersToPrint. The pdf files with scribbles will be created in basedir. Defaults to current directory.

Keyword Arguments:

msgr (plom.Messenger/tuple) – either a connected Messenger or a tuple appropriate for credientials.

Returns:

None

  1. Read in the existing papers.

  2. Create the fake data filled pdfs

  3. Do some things to make the data unpleasant:

    • delete the last page of the first test.

    • Randomly add some extra pages

plom.create.scribble_utils.scribble_name_and_id(pdf_doc, student_number, student_name, *, pagenum=0, seed=None)[source]

Write name/number on coverpage of fitz pdf_doc.

Parameters:

  • pdf_doc (fitz.Document) – an open pdf file, we’ll modify it implicitly but not close it.

  • student_number (str) – student number to write on page.

  • student_name (str) – student name to write on page.

Keyword Arguments:

  • pagenum (int) – which page is the coverpage, default 0 (1st page).

  • seed (None/int) – seed the random number generator with this value. Default of None means don’t. This can be used to ensure the same digit images are chosen each time, useful for testing.

Returns:

but modifies the open document as a side effect.

Return type:

None

plom.create.scribble_utils.scribble_pages(pdf_doc, exclude=(0, 1))[source]

Scribble on most pages of fitz pdf_doc.

Parameters:

pdf_doc (fitz.Document) – an open pdf file, we’ll modify it implicitly but not close it.

Keyword Arguments:

exclude – which pages to exclude. By default exclude pages 0 and 1 (the ID page and DNM page in our demo data).

Returns:

but modifies the open document as a side effect.

Return type:

None

plom.create.scribble_utils.splitFakeFile(outfile, *, parts=3)[source]

Split the scribble pdf into specified number of files (defaults to 3).

Random grading: plom.client.randoMarker

Command-line script

Perform marking tasks randomly, generally for testing.

usage: python -m plom.client.randoMarker [-h] [-w PASSWORD] [-u USER]
                                         [-s SERVER[:PORT]]
                                         [--partial PERCENTAGE] [-q N]
                                         [-v VERSION] [--download-rubrics]
Named Arguments
-w, --password

by default, for the “scanner” user’, also checks the environment variable PLOM_SCAN_PASSWORD.

-u, --user

Override default of “scanner”

-s, --server

Which server to contact, port defaults to 41984. Also checks the environment variable PLOM_SERVER if omitted.

--partial

What percentage of questions to mark? Default is 100; mark all of them. Technically, this is a i.i.d. probability of grading each task that the server has.

Default: 100.0

-q, --question

Question number to mark. If omitted, mark all of them.

-v, --version

Which version to mark. If omitted, mark all of them.

--download-rubrics

Download rubrics from the server rather than creating own.

Default: False

Module docs

Randomly scribble marks and annotations on papers for testing purposes.

This is a very very cut-down version of Annotator, and a command-line tool used to automate some random marking of papers.

plom.client.randoMarker.build_random_rubrics(question_idx: int, *, username, messenger) → None[source]

Push random rubrics into a server: only for testing/demo purposes.

Caution

Do not use on a real production server.

Parameters:

question_idx – which question.

Keyword Arguments:

  • messenger – a messenger object already connected to the server.

  • username (str) – which username to create the rubrics.

Returns:

None

plom.client.randoMarker.do_rando_marking(server: str | None, user: str, password: str, *, partial: float = 100.0, question: None | int = None, version: None | int = None, download_rubrics: bool = False) → int[source]

Randomly annotate the papers assigning RANDOM grades: only for testing please.

Caution

Only for testing/demos. Do not use for real tests.

Also, for each paper, with probability 1/3, we tag with up to 3 randomly selected tags.

Parameters:

  • server – which server.

  • user – credientials.

  • password – credientials.

Keyword Arguments:

  • partial – what percentage of papers to grade?

  • question – what question to mark or if omitted, mark all of them.

  • version – what version to mark or if omitted, mark all of them.

  • download_rubrics – get and use rubrics from the server.

Returns:

0 on success, non-zero on error/unexpected.

Random identifying: plom.client.randoIDer

Command-line script

Perform identifier tasks randomly, generally for testing.

usage: python -m plom.client.randoIDer [-h] [-w PASSWORD] [-u USER]
                                       [-s SERVER[:PORT]] [--use-predictions]
Named Arguments
-w, --password

by default, for the “scanner” user’, also checks the environment variable PLOM_SCAN_PASSWORD.

-u, --user

Override default of “scanner”

-s, --server

Which server to contact, port defaults to 41984. Also checks the environment variable PLOM_SERVER if omitted.

--use-predictions

Download and use ID predictions from the server rather than being purely random.

Default: False

Module docs

Randomly ID papers for testing purposes.

plom.client.randoIDer.do_rando_identifying(server: str | None, user: str, password: str, *, use_predictions: bool = False) → int[source]

Randomly associate papers with students: only for testing please.

Parameters:

  • server – which server.

  • user – credientials.

  • password – credientials.

Keyword Arguments:

use_predictions – download and use predictions to try to id papers. Note that the rando-id-er uses prenamed IDs in all cases, regardless of this setting.

Returns:

0 on success, non-zero on error/unexpected.

TeX Tools

Tools for working with TeX.

plom.textools.buildLaTeX(src: str, out)[source]

Compile a string of latex.

Parameters:

  • src – a string of LaTeX code to compile.

  • out (file-like) – the binary pdf file will be written into this.

Returns:

tuple containing

  • (int): exit value from the subprocess call (zero good, non-zero bad)

  • (str): stdout/stderr from the subprocess call

TODO: this is more generally useful but how to generalize/handle the idBox?

plom.textools.texFragmentToPNG(fragment: str, *, dpi: int = 225) → Tuple[bool, bytes | str][source]

Process a fragment of latex and produce a png image.

Parameters:

fragment – a string of text to be rendered with LaTeX.

Keyword Arguments:

dpi – controls the resolution of the image by setting the dots-per-inch. Defaults: 225.

Returns:

(True, imgdata) or (False, error_msg) where imgdata is the raw contents of a PNG file, and error_msg is (currently) a string, but this could change in the future.

Return type:

tuple

Raises:

Not expected to raise any exceptions. –