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

• answer_data – value returned by answer_data(). May be None.

• 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.

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

• answer_data – value returned by answer_data(), or None, which means that no answer was supplied.

• grade_data – value updated by update_grade_data_from_grading_form_v2()

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

See django.forms.Form.

class django.http.request.HttpRequest

See django.http.HttpRequest.