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

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: PageContext, page_data: Any, answer_data: Any, grade_data: Any) → 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: 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, 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.