Package `potluck`

Package for defining and evaluating Python programming tasks.

potluck/init.py

For a high-level interface, import potluck.compare. To define a task specification, import potluck.specifications. To define tests for a specification, import potluck.meta.

Compatibility

Overall potluck requires Python 3.6 or later, but the following modules are compatible with Python 2.7:

Dependencies:

Core (these should be installed automatically when installing via pip)

jinja2 for report rendering via HTML templates.
pygments for code highlighting in reports.
importlib_resources for resource loading.
markdown and beautifulsoup4 for creating instructions. If pymdown-extensions is available, its 'extra' collection will be used instead of standard markdown 'extra', which allows for things like code fences inside itemized lists.
python_dateutil for time zone management.

Optional (installing via [option] should fetch these when using pip)

[test] installs pytest for running the tests.
[expectations] installs optimism for capturing student tests using that module.
[turtle_capture] installs Pillow (>=6.0.0) for capturing turtle drawings, but you will need to manually install Ghostscript (which is not available directly from PyPI).
[server] installs flask and flask_cas for supporting the potluck_server module.
[security] installs flask_talisman and flask_seasurf for baseline server security.
[https_debug] installs pyopenssl for using HTTPS with a self-signed certificate when doing local debugging.

Getting Started

Unless you want to get into the guts of things, potluck.specifications is the place to get started, while potluck.rubrics and potluck.contexts deal with more advanced concepts without getting too far into the weeds. potluck.meta and potluck.snippets are also useful high-level interfaces for building tasks.

Flask App

For automatically collecting and evaluating submissions using potluck, a Flask WSGI app is available in the separate potluck_server module.

Expand source code

"""
Package for defining and evaluating Python programming tasks.

potluck/__init__.py

For a high-level interface, import `potluck.compare`. To define a task
specification, import `potluck.specifications`. To define tests for a
specification, import `potluck.meta`.


## Compatibility

Overall `potluck` requires Python 3.6 or later, but the following modules
are compatible with Python 2.7:

- `potluck.render`
- `potluck.html_tools`
- `potluck.phrasing`
- `potluck.file_utils`
- `potluck.time_utils`
- `potluck.logging`


## Dependencies:

Core (these should be installed automatically when installing via `pip`)

- `jinja2` for report rendering via HTML templates.
- `pygments` for code highlighting in reports.
- `importlib_resources` for resource loading.
- `markdown` and `beautifulsoup4` for creating instructions. If
    `pymdown-extensions` is available, its 'extra' collection will be
    used instead of standard markdown 'extra', which allows for things
    like code fences inside itemized lists.
- `python_dateutil` for time zone management.

Optional (installing via [option] should fetch these when using `pip`)

- `[test]` installs `pytest` for running the tests.
- `[expectations]` installs `optimism` for capturing student tests using
    that module.
- `[turtle_capture]` installs `Pillow` (>=6.0.0) for capturing turtle
    drawings, but you will need to manually install Ghostscript (which is
    not available directly from PyPI).
- `[server]` installs `flask` and `flask_cas` for supporting the
    `potluck_server` module.
- `[security]` installs `flask_talisman` and `flask_seasurf` for
    baseline server security.
- `[https_debug]` installs `pyopenssl` for using HTTPS with a
    self-signed certificate when doing local debugging.


## Getting Started

Unless you want to get into the guts of things, `potluck.specifications`
is the place to get started, while `potluck.rubrics` and
`potluck.contexts` deal with more advanced concepts without getting too
far into the weeds. `potluck.meta` and `potluck.snippets` are also useful
high-level interfaces for building tasks.


## Flask App

For automatically collecting and evaluating submissions using `potluck`,
a Flask WSGI app is available in the separate `potluck_server` module.
"""

# Import version variable
from ._version import __version__ # noqa F401

Sub-modules

potluck.compare: Functions for comparing Python values, and for rendering the results of those comparisons as HTML …
potluck.context_utils: Support functions for contexts that are also needed by modules which the potluck.contexts module depends on …
potluck.contexts: The Context class and related functions which form the backbone of the testing process …
potluck.control: High-level evaluation tools for launching core potluck tasks such as rubric creation, spec validation, and submission evaluation …
potluck.default_config
potluck.explain: Functions for explaining test results …
potluck.file_utils: File-management utilities …
potluck.harness: Tools for testing Python code and recording things like results, printed output, or even traces of calls to certain functions …
potluck.html_tools: Tools for building HTML strings …
potluck.load: Functions for loading submitted & solution code …
potluck.logging: Logging support …
potluck.mast: Mast: Matcher of ASTs for Python Copyright (c) 2017-2018, Benjamin P. Wood, Wellesley College …
potluck.mast_utils: Utils from codder which are necessary for the mast module …
potluck.meta: Routines for checking whether specifications are correctly implemented and working as intended …
potluck.patterns: Common code patterns for use with the potluck.mast AST matching module …
potluck.phrasing: Functions for phrasing feedback (e.g., pluralization) …
potluck.render: Tools for generating reports and managing jinja2 templates …
potluck.rubrics: Main classes for defining a rubric, including Rubric itself, as well as Goal and Context …
potluck.snippets: Code for defining examples that should be shown as part of instructions …
potluck.specifications: High-level code for defining task specifications …
potluck.tests: Runs tests via pytest. Invoke using python -m potluck.tests …
potluck.time_utils: Time and date management utilities …
potluck.timeout: Hacks in an attempt to permit running a function with an external time limit. Only the Unix-specific SIGALRM method seems to work? …