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: django.http.HttpRequest | None = None)[source]¶

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.

final class course.page.base.PageBehavior(show_correctness: bool, show_answer: bool, may_change_answer: bool)[source]¶

show_correctness¶

show_answer¶

may_change_answer¶

final class course.page.base.AnswerFeedback(correctness: float | None, feedback: str | None = None, bulk_feedback: str | None = None)[source]¶

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[source]¶

Base Classes For Pages¶

class course.page.base.PageBase(vctx: ValidationContext | None, location: str, page_desc: Any)[source]¶

The abstract interface of a flow page.

location¶: A string ‘location’ for reporting errors.

id¶: The page identifier.

required_attrs() → Sequence[tuple[str, type | tuple[type, ...] | Literal['markup']]][source]¶: Required attributes, as accepted by course.validation.validate_struct(). Subclasses should only add to, not remove entries from this.

allowed_attrs() → Sequence[tuple[str, type | tuple[type, ...] | Literal['markup']]][source]¶: 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][source]¶

initialize_page_data(page_context: PageContext) → dict[str, Any][source]¶: 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.

abstractmethod title(page_context: PageContext, page_data: dict[str, Any]) → str[source]¶: Return the (non-HTML) title of this page.

abstractmethod body(page_context: PageContext, page_data: dict[str, Any]) → str[source]¶: Return the (HTML) body of the page.

abstractmethod expects_answer() → bool[source]¶

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

is_answer_gradable() → bool[source]¶

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

True by default.

abstractmethod max_points(page_data: Any) → float[source]¶

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

Student Input

abstractmethod answer_data(page_context: PageContext, page_data: Any, form: Form, files_data: Any) → Any[source]¶: Return a JSON-persistable object reflecting the user’s answer on the form. This will be passed to methods below as answer_data.

abstractmethod make_form(page_context: PageContext, page_data: Any, answer_data: Any, page_behavior: Any) → StyledFormBase[source]¶

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.

abstractmethod process_form_post(page_context: PageContext, page_data: Any, post_data: Any, files_data: Any, page_behavior: PageBehavior) → StyledFormBase[source]¶

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: HttpRequest, page_context: PageContext, form: StyledFormBase, answer_data: Any)[source]¶: Returns an HTML rendering of form.

Grader Input

abstractmethod make_grading_form(page_context: PageContext, page_data: Any, grade_data: Any) → StyledFormBase | None[source]¶

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.

abstractmethod post_grading_form(page_context: PageContext, page_data: Any, grade_data: Any, post_data: Any, files_data: Any) → StyledFormBase[source]¶

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: HttpRequest, page_context: PageContext, page_data: Any, grade_data: Any, grading_form: Any, files_data: Any)[source]¶: 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: HttpRequest, page_context: PageContext, grading_form: Any, grade_data: Any) → str[source]¶: Returns an HTML rendering of grading_form.

Grading/Feedback

abstractmethod grade(page_context: PageContext, page_data: dict[str, Any], answer_data: dict[str, Any] | None, grade_data: dict[str, Any] | None) → AnswerFeedback | None[source]¶

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.

abstractmethod correct_answer(page_context: PageContext, page_data: dict[str, Any], answer_data: dict[str, Any] | None, grade_data: dict[str, Any] | None) → str | None[source]¶: The correct answer to this page’s interaction, formatted as HTML, or None.

analytic_view_body(page_context: PageContext, page_data: dict[str, Any]) → str[source]¶: Return the (HTML) body of the page, which is shown in page analytic view.

abstractmethod normalized_answer(page_context: PageContext, page_data: dict[str, Any], answer_data: dict[str, Any]) → str | None[source]¶: An HTML-formatted answer to be used for summarization and display in analytics. By default, this is escaped when included in the output page, however it may use utilities such as mark_safe() to mark the output as safe and avoid escaping.

abstractmethod normalized_bytes_answer(page_context: PageContext, page_data: dict[str, Any], answer_data: dict[str, Any]) → tuple[str, bytes] | None[source]¶

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 (including 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: ValidationContext | None, location: str, page_desc: Any)[source]¶

class course.page.base.PageBaseWithHumanTextFeedback(vctx: ValidationContext | None, location: str, page_desc: Any)[source]¶

human_feedback_point_value(page_context: PageContext, page_data: Any) → float | None[source]¶: 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: ValidationContext | None, location: str, page_desc: Any)[source]¶

Automatic Feedback¶

course.page.base.get_auto_feedback(correctness: float | None) → str[source]¶

Validation¶

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

repo¶

commit_sha¶

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

course.validation.validate_struct(vctx: ValidationContext, location: str, obj: Any, required_attrs: Sequence[tuple[str, type | tuple[type, ...] | Literal['markup']]], allowed_attrs: Sequence[tuple[str, type | tuple[type, ...] | Literal['markup']]]) → None[source]¶

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[source]¶

class course.models.FlowSession[source]¶

class relate.utils.SubdirRepoWrapper[source]¶

class course.utils.FlowPageContext[source]¶

class relate.utils.StyledFormBase[source]¶

Canonicalization of Django Names¶

class django.forms.forms.Form[source]¶: See django.forms.Form.

class django.http.request.HttpRequest[source]¶: See django.http.HttpRequest.