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)
course
repo
commit_sha
flow_session

May be None.

page_uri

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: str | None = None, bulk_feedback: str | None = 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: PageContext, page_data: Any, answer_data: Any, grade_data: Any) 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: 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: 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: 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.

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, typing.Any]], allowed_attrs: list[tuple[str, typing.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.