Internals

Flow Page Interface

This describes the programming interface between Relate and a page in a flow.

Stub Docs of Internals

class course.page.base.Repo_ish

See relate.utils.Repo_ish.

class course.page.base.Course

See course.models.Course.

class course.page.base.FlowSession

See course.models.FlowSession.

Page Interface

class course.page.base.PageContext(course: Course, repo: Repo_ish, commit_sha: bytes, flow_session: FlowSession, in_sandbox: bool = False, page_uri: str | None = None, request: Optional[django.http.HttpRequest] = None)
course
repo
commit_sha
flow_session

May be None.

page_uri
request

Note that this is different from course.utils.FlowPageContext, which is used internally by the flow views.

class course.page.base.PageBehavior(show_correctness: bool, show_answer: bool, may_change_answer: bool)
show_correctness
show_answer
may_change_answer
class course.page.base.AnswerFeedback(correctness: float | None, feedback: Optional[str] = None, bulk_feedback: Optional[str] = None)
correctness

A float between 0 and 1 (inclusive), indicating the degree of correctness of the answer. May be None.

feedback

Text (at least as a full sentence, or even multi-paragraph HTML) providing feedback to the student about the provided answer. Should not reveal the correct answer.

May be None, in which case generic feedback is generated from correctness.

bulk_feedback
exception course.page.base.InvalidPageData

Base Classes For Pages

class course.page.base.PageBase(vctx, location, page_desc)

The abstract interface of a flow page.

location

A string ‘location’ for reporting errors.

id

The page identifier.

required_attrs()

Required attributes, as accepted by course.validation.validate_struct(). Subclasses should only add to, not remove entries from this.

allowed_attrs()

Allowed attributes, as accepted by course.validation.validate_struct(). Subclasses should only add to, not remove entries from this.

get_modified_permissions_for_page(permissions: frozenset[str]) frozenset[str]
initialize_page_data(page_context: course.page.base.PageContext) dict

Return (possibly randomly generated) data that is used to generate the content on this page. This is passed to methods below as the page_data argument. One possible use for this argument would be a random permutation of choices that is generated once (at flow setup) and then used whenever this page is shown.

title(page_context: course.page.base.PageContext, page_data: dict) str

Return the (non-HTML) title of this page.

body(page_context: course.page.base.PageContext, page_data: dict) str

Return the (HTML) body of the page.

expects_answer() bool
Returns

a bool indicating whether this page lets the user provide an answer of some type.

is_answer_gradable() bool
Returns

a bool indicating whether answers on this can have grade() called on them.

True by default.

max_points(page_data: Any) float
Returns

a int or float indicating how many points are achievable on this page.

Student Input

answer_data(page_context: course.page.base.PageContext, page_data: Any, form: django.forms.forms.Form, files_data: Any) Any

Return a JSON-persistable object reflecting the user’s answer on the form. This will be passed to methods below as answer_data.

make_form(page_context: course.page.base.PageContext, page_data: Any, answer_data: Any, page_behavior: Any)
Parameters
Returns

a django.forms.Form instance with answer_data prepopulated. If page_behavior.may_change_answer is False, the form should be read-only.

process_form_post(page_context: course.page.base.PageContext, page_data: Any, post_data: Any, files_data: Any, page_behavior: course.page.base.PageBehavior) django.forms.forms.Form

Return a form with the POST response from post_data and files_data filled in.

Parameters

page_behavior – an instance of PageBehavior

Returns

a django.forms.Form instance with answer_data prepopulated. If page_behavior.may_change_answer is False, the form should be read-only.

form_to_html(request: django.http.request.HttpRequest, page_context: course.page.base.PageContext, form: relate.utils.StyledForm, answer_data: Any)

Returns an HTML rendering of form.

Grader Input

make_grading_form(page_context: course.page.base.PageContext, page_data: Any, grade_data: Any) django.forms.forms.Form
Parameters

grade_data – value returned by update_grade_data_from_grading_form_v2(). May be None.

Returns

a django.forms.Form instance with grade_data prepopulated.

post_grading_form(page_context: course.page.base.PageContext, page_data: Any, grade_data: Any, post_data: Any, files_data: Any) django.forms.forms.Form

Return a form with the POST response from post_data and files_data filled in.

Returns

a django.forms.Form instance with grade_data prepopulated.

update_grade_data_from_grading_form_v2(request: django.http.request.HttpRequest, page_context: course.page.base.PageContext, page_data: Any, grade_data: Any, grading_form: Any, files_data: Any)

Return an updated version of grade_data, which is a JSON-persistable object reflecting data on grading of this response. This will be passed to other methods as grade_data.

grading_form_to_html(request: django.http.request.HttpRequest, page_context: course.page.base.PageContext, grading_form: Any, grade_data: Any) str

Returns an HTML rendering of grading_form.

Grading/Feedback

grade(page_context: course.page.base.PageContext, page_data: Any, answer_data: Any, grade_data: Any) course.page.base.AnswerFeedback | None

Grade the answer contained in answer_data.

Parameters
Returns

a AnswerFeedback instanstance, or None if the grade is not yet available.

correct_answer(page_context: course.page.base.PageContext, page_data: Any, answer_data: Any, grade_data: Any) str | None

The correct answer to this page’s interaction, formatted as HTML, or None.

analytic_view_body(page_context: course.page.base.PageContext, page_data: dict) str

Return the (HTML) body of the page, which is shown in page analytic view.

normalized_answer(page_context: course.page.base.PageContext, page_data: Any, answer_data: Any) str | None

An HTML-formatted answer to be used for summarization and display in analytics.

normalized_bytes_answer(page_context: course.page.base.PageContext, page_data: Any, answer_data: Any) tuple[str, bytes] | None

An answer to be used for batch download, given as a batch of bytes to be stuffed in a zip file.

Returns

a tuple of (file_ext, data) where file_ext is a suggested file extension (inlcuding the leading period, if applicable). May also return None.

One use case of this function is to work as input for a plagiarism checker.

class course.page.base.PageBaseWithTitle(vctx, location, page_desc)
class course.page.base.PageBaseWithHumanTextFeedback(vctx, location, page_desc)
human_feedback_point_value(page_context, page_data)

Subclasses can override this to make the point value of the human feedback known, which will enable grade entry in points.

Supports automatic computation of point values from textual feedback. See Automatic point computation from textual feedback.

class course.page.base.PageBaseWithCorrectAnswer(vctx, location, page_desc)

Automatic Feedback

course.page.base.get_auto_feedback(correctness: float | None) str

Validation

class course.validation.ValidationContext(repo: Repo_ish, commit_sha: bytes, course: Course | None = None)
repo
commit_sha
course

A course.models.Course instance, or None, if no database is currently available.

course.validation.validate_struct(vctx: course.validation.ValidationContext, location: str, obj: Any, required_attrs: list[tuple[str, Any]], allowed_attrs: list[tuple[str, Any]]) None
Parameters
  • required_attrs – an attribute validation list (see below)

  • allowed_attrs – an attribute validation list (see below)

An attribute validation list is a list of elements, where each element is either a string (the name of the attribute), in which case the type of each attribute is not checked, or a tuple (name, type), where type is valid as a second argument to isinstance().

Stub Docs

class course.validation.Course
class course.validation.Repo_ish

Stub Docs

class course.models.Course
class course.models.FlowSession
class relate.utils.SubdirRepoWrapper
class course.utils.FlowPageContext
class relate.utils.StyledForm

Canonicalization of Django Names

class django.forms.forms.Form[source]

See django.forms.Form.

class django.http.request.HttpRequest[source]

See django.http.HttpRequest.