Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/assignment-feedback.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ LE 1.93) and the RichText definition in `basic/conventions.html`:
| Preflight | `GET .../dropbox/folders/{folder}/submissions/user/{user}` (EntityDropbox, 1.88+) | Exactly one block for this user (`EntityType` User, integer `EntityId`); at least one submission; a `Feedback` key present (null or an object); `Status` 1 (Submitted) or 2 (Draft) as an integer or digit string, never 3 (Published), 0 or unknown; existing feedback must be a complete DropboxFeedbackOut with `IsGraded` exactly `false`, no `Score` or `GradedSymbol`, and empty rubric assessments, files and links; existing draft text, or an existing feedback object whose comment is null or empty (`{}`), only with `--replace-draft` |
| Re-check | Both reads again, after an interactive confirmation | A digest of the record's status and existing feedback must match the first preflight; otherwise nothing is sent |
| Save | `POST .../feedback/user/{user}`, one attempt, CSRF header fetched before the preflight | Body `{"Score": null, "Feedback": {"Text": ..., "Html": ...}, "RubricAssessments": [], "IsGraded": false, "GradedSymbol": null}`. The reference marks `Feedback` as RichText. Only HTTP 200, the documented success, counts; the response body is undocumented and ignored |
| Readback 1 | `GET .../feedback/user/{user}` (DropboxFeedbackOut) | The same draft-only checks as the preflight. Every comment part that is present, even an empty string, must match: `Text` equal to the comment (line endings normalized), `Html` equal to what was sent, or markup made only of `<p>` and `<br>` whose text is the comment (entities decoded, non-breaking spaces as spaces, outer line breaks ignored). Any other markup is a mismatch, and at least one part must be present |
| Readback 1 | `GET .../feedback/user/{user}` (DropboxFeedbackOut) | The same draft-only checks as the preflight. Every comment part that is present, even an empty string, must match: `Text` equal to the comment (line endings normalized), `Html` equal to what was sent, or the same structure: exactly one `<p>` with no attributes holding only text and attribute-free `<br>` line breaks, whose text is the comment. Only harmless reformatting is allowed: whitespace outside the paragraph, one line break next to a `<p>`, `<br>` or `</p>` tag, entity spelling (complete references to printable characters only), tag case and `<br>`/`<br/>`/`<br />` (non-breaking spaces count as spaces; line breaks, including leading and trailing ones, must match exactly). Any attribute or junk inside a tag, other element, comment, second paragraph, extra `<br>`, unknown or incomplete entity, or other raw line break is a mismatch and gives `unknown`. At least one part must be present |
| Readback 2 | `GET .../submissions/user/{user}` | Same user block, `Status` 2 (Draft), and its `Feedback` passes the same draft-only and comment checks as readback 1 |

`IsGraded: false` is the documented draft state ("If true, the feedback is in
Expand Down Expand Up @@ -52,7 +52,8 @@ synthetic course, assignment and test learner that you own:
that learner is unchanged.
5. If the command reports `"outcome": "unknown"` after a save that worked,
record the readback shape (`Text`, `Html`, `Status`), because the check
needs adjusting. The likely causes are D2L rewriting `Text`, keeping
needs adjusting. The likely causes are D2L rewriting `Text`, storing `Html`
with attributes, extra elements or more than one paragraph, keeping
`Status` at 1, or answering the POST with a status other than 200.
6. Add a draft with a rubric assessment or an attachment in the UI and confirm
the command refuses it.
157 changes: 148 additions & 9 deletions lighthouse_cli/assignment_feedback.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,12 @@

import hashlib
import html
import html.entities
import json
import os
import re
import stat
from dataclasses import dataclass
from html.parser import HTMLParser
from typing import Any

import requests
Expand Down Expand Up @@ -89,21 +90,159 @@ def _html(text: str) -> str:
return "<p>" + html.escape(text, quote=True).replace("\n", "<br />") + "</p>"


_OPEN = re.compile(r"^\s*<p\b[^>]*>", re.IGNORECASE)
_CLOSE = re.compile(r"</p>\s*$", re.IGNORECASE)
_BREAK = re.compile(r"<br\s*/?>|</p>\s*<p\b[^>]*>", re.IGNORECASE)
# ASCII whitespace after line-ending normalization.
_HTML_SPACE = " \t\n\f"


class _RejectedMarkupError(Exception):
"""The readback Html is not the structure the command sent."""


def _bare_tag(raw: str, prefix: str, name: str, *, slash: bool = False) -> bool:
"""``raw`` is ``<name>``/``</name>`` with only whitespace (and, for ``<br/>``, one slash) before ``>``."""
head = prefix + name
if raw[:len(head)].lower() != head or not raw.endswith(">"):
return False
rest = raw[len(head):-1].strip(_HTML_SPACE)
return rest == "" or (slash and rest == "/")


class _CommentMarkup(HTMLParser):
"""Raw token spans of markup that may be one attribute-free ``<p>`` holding only ``<br>``.

The parser finds the tokens; the raw text of every tag is then checked
exactly, and the text between tags is sliced from the source, so a token
the parser drops or rewrites cannot slip through. Comments, declarations,
processing instructions and any other tag raise :class:`_RejectedMarkupError`.
"""

def __init__(self, markup: str) -> None:
super().__init__(convert_charrefs=False)
self.markup = markup
self._line_starts = [0] + [index + 1 for index, char in enumerate(markup) if char == "\n"]
self.tags: list[tuple[str, int, int]] = [] # (token, start, end)

def _add(self, token: str, raw: str) -> None:
line, offset = self.getpos()
start = self._line_starts[line - 1] + offset
end = start + len(raw)
if self.markup[start:end] != raw or (self.tags and start < self.tags[-1][2]):
raise _RejectedMarkupError
self.tags.append((token, start, end))

def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
raw = self.get_starttag_text() or ""
if attrs or tag not in ("p", "br") or not _bare_tag(raw, "<", tag, slash=tag == "br"):
raise _RejectedMarkupError
self._add(tag, raw)

def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
if tag != "br":
raise _RejectedMarkupError
self.handle_starttag(tag, attrs)

def handle_endtag(self, tag: str) -> None:
line, offset = self.getpos()
start = self._line_starts[line - 1] + offset
raw = self.markup[start:self.markup.find(">", start) + 1]
if tag != "p" or not _bare_tag(raw, "</", tag):
raise _RejectedMarkupError
self._add("/p", raw)

def handle_comment(self, data: str) -> None:
raise _RejectedMarkupError

def handle_decl(self, decl: str) -> None:
raise _RejectedMarkupError

def handle_pi(self, data: str) -> None:
raise _RejectedMarkupError

def unknown_decl(self, data: str) -> None:
raise _RejectedMarkupError


def _character(reference: str) -> str | None:
"""The character a complete ``&...;`` reference renders as, or ``None`` if it is not a plain, valid one."""
body = reference[1:-1]
if not body.startswith("#"):
return html.entities.html5.get(body + ";")
digits, base = (body[2:], 16) if body[1:2] in ("x", "X") else (body[1:], 10)
allowed = "0123456789abcdefABCDEF" if base == 16 else "0123456789"
if not 0 < len(digits) <= 8 or any(char not in allowed for char in digits):
return None
number = int(digits, base)
if number == 9 or 0x20 <= number < 0x7F or (
0xA0 <= number <= 0x10FFFF and not 0xD800 <= number <= 0xDFFF
and not 0xFDD0 <= number <= 0xFDEF and number & 0xFFFE != 0xFFFE
):
return chr(number)
return None


def _decode_text(raw: str) -> str | None:
"""Text content of raw paragraph text, or ``None`` for markup or an unclear reference.

A ``<`` that would open a tag, comment or declaration is refused; a ``<``
or ``&`` that browsers show as-is stays literal. A reference must be
complete (with ``;``) and name a valid, printable character.
"""
out: list[str] = []
index = 0
while index < len(raw):
char, following = raw[index], raw[index + 1:index + 2]
if char == "<" and (following == "" or (following.isascii() and (following.isalpha() or following in "/!?"))):
return None
if char != "&" or not (following == "#" or (following.isascii() and following.isalnum())):
out.append(char)
index += 1
continue
end = index + 1
while end < len(raw) and raw[end].isascii() and (raw[end].isalnum() or (raw[end] == "#" and end == index + 1)):
end += 1
if raw[end:end + 1] != ";":
return None
value = _character(raw[index:end + 1])
if value is None:
return None
out.append(value)
index = end + 1
return "".join(out)


def _comparable(text: str) -> str:
return text.replace("\xa0", " ").strip("\n")
return text.replace("\xa0", " ")


def _html_text(markup: str) -> str | None:
"""The text of paragraph/line-break-only markup, or ``None`` if it has any other markup."""
body = _BREAK.sub("\n", _CLOSE.sub("", _OPEN.sub("", _normalize(markup), count=1), count=1))
if "<" in body:
"""The text of markup shaped exactly like :func:`_html` output, or ``None`` for any other structure.

Allowed reformatting: whitespace outside the paragraph, one line break
directly after ``<p>``/``<br>`` or before ``<br>``/``</p>``, entity
spelling, tag case and ``<br>`` vs ``<br/>``. Any other raw line break is
rejected because it renders as a space, not a line break. Line breaks are
compared exactly, leading and trailing ones included.
"""
markup = _normalize(markup)
parser = _CommentMarkup(markup)
try:
parser.feed(markup)
parser.close()
except Exception: # any parser failure means "not the sent structure"
return None
tokens = [token for token, _, _ in parser.tags]
if len(tokens) < 2 or tokens[0] != "p" or tokens[-1] != "/p" or any(t != "br" for t in tokens[1:-1]):
return None
if markup[:parser.tags[0][1]].strip(_HTML_SPACE) or markup[parser.tags[-1][2]:].strip(_HTML_SPACE):
return None
return _comparable(html.unescape(body))
lines = []
for (_, _, start), (_, end, _) in zip(parser.tags, parser.tags[1:], strict=False):
segment = markup[start:end].removeprefix("\n").removesuffix("\n")
text = None if "\n" in segment else _decode_text(segment)
if text is None or "\n" in text or "\r" in text:
return None
lines.append(text)
return _comparable("\n".join(lines))


def feedback_payload(text: str) -> dict[str, Any]:
Expand Down
116 changes: 111 additions & 5 deletions tests/test_assignment_feedback.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@
FeedbackInputError,
FeedbackRefusedError,
_check_saved_comment,
_comparable,
_html,
_html_text,
_UnexpectedError,
check_feedback_target,
feedback_payload,
Expand Down Expand Up @@ -712,9 +715,9 @@ def test_readback_accepts_the_html_part_alone_when_it_matches_what_was_sent(feed

@pytest.mark.parametrize("markup", [
"<p>Synthetic draft note: revisit the second proof.<br>Line two.</p>",
"<p>Synthetic draft note: revisit the second proof.</p>\n<p>Line two.</p>",
'<p style="x">Synthetic draft note:&nbsp;revisit the second proof.<BR/>Line two.</p>',
], ids=["br", "paragraphs", "attributes-nbsp"])
"<P>Synthetic draft note:&nbsp;revisit the second proof.<BR/>Line two.</P>",
"\n <p>\nSynthetic draft note: revisit the second proof.<br />\nLine two.\n</p>\n",
], ids=["br", "case-nbsp", "pretty-printed"])
def test_readback_accepts_html_reformatted_with_the_same_text(feedback_file, markup):
fake = FakeLMS(happy_routes(get_feedback=[lambda: response(200, draft_feedback_out(Feedback={"Text": TEXT, "Html": markup}))]))
result = invoke(fake, "--file", str(feedback_file), "--yes", "--json")
Expand All @@ -737,14 +740,117 @@ def test_saved_comment_check_rejects_any_difference(rich, text):


@pytest.mark.parametrize("rich,text", [
({"Text": "hello\n", "Html": "<p>hello</p>"}, "hello\n"),
({"Text": None, "Html": "<p>a &amp; b<br />c</p>"}, "a & b\nc"),
({"Text": "a\u00a0b", "Html": "<p>a&nbsp;b</p>"}, "a\u00a0b"),
], ids=["trailing-newline-dropped-in-html", "html-only-escaped", "nbsp"])
], ids=["html-only-escaped", "nbsp"])
def test_saved_comment_check_accepts_equivalent_parts(rich, text):
_check_saved_comment(draft_feedback_out(Feedback=rich), text)


_REJECTED_HTML = {
"p-hidden": ("<p hidden>hello</p>", "hello"),
"p-style": ('<p style="display:none">hello</p>', "hello"),
"p-class": ('<p class="sr-only">hello</p>', "hello"),
"p-id": ("<p id=x>hello</p>", "hello"),
"br-attribute": ('<p>a<br class="x">b</p>', "a\nb"),
"span": ("<p><span>hello</span></p>", "hello"),
"nested-p-in-div": ("<div><p>hello</p></div>", "hello"),
"extra-image": ('<p>hello</p><img src="x">', "hello"),
"script-inside": ("<p>hello<script>x()</script></p>", "hello"),
"script-after": ("<p>hello</p><script>x()</script>", "hello"),
"style-inside": ("<p>hello<style>p{}</style></p>", "hello"),
"comment-inside": ("<p>hello<!-- note --></p>", "hello"),
"comment-before": ("<!-- note --><p>hello</p>", "hello"),
"unfinished-comment": ("<p>hello</p><!--", "hello"),
"bogus-comment": ("<p>hello</ x></p>", "hello"),
"doctype": ("<!DOCTYPE html><p>hello</p>", "hello"),
"cdata": ("<p>hello<![CDATA[x]]></p>", "hello"),
"processing-instruction": ("<p>hello<?x?></p>", "hello"),
"second-paragraph": ("<p>hello</p><p>there</p>", "hello\nthere"),
"empty-second-paragraph": ("<p>hello</p><p></p>", "hello"),
"unclosed-second-paragraph": ("<p>hello</p><p>", "hello"),
"self-closing-p": ("<p/>hello</p>", "hello"),
"unclosed": ("<p>hello", "hello"),
"no-paragraph": ("hello", "hello"),
"stray-close-first": ("</p><p>hello</p>", "hello"),
"double-close": ("<p>hello</p></p>", "hello"),
"end-br": ("<p>a</br>b</p>", "a\nb"),
"unfinished-tag-after": ("<p>hello</p><b", "hello"),
"text-after": ("<p>hello</p>junk", "hello"),
"entity-after": ("<p>hello</p>&nbsp;", "hello"),
"raw-newline-inside": ("<p>x\ny</p>", "x\ny"),
"two-newlines-after-br": ("<p>x<br>\n\ny</p>", "x\ny"),
"trailing-break-dropped": ("<p>hello</p>", "hello\n"),
"extra-outer-breaks": ("<p><br>hello<br><br></p>", "hello"),
"extra-leading-break": ("<p><br>hello</p>", "hello"),
"invalid-charref": ("<p>he&#1;llo</p>", "hello"),
"c1-charref": ("<p>he&#x80;llo</p>", "he\x80llo"),
"zero-charref": ("<p>he&#0;llo</p>", "hello"),
"huge-charref": ("<p>he&#x110000;llo</p>", "hello"),
"surrogate-charref": ("<p>he&#xD800;llo</p>", "hello"),
"newline-charref": ("<p>a&#10;b</p>", "a\nb"),
"unterminated-charref": ("<p>&#38 x</p>", "& x"),
"unknown-entity": ("<p>a&bogus;b</p>", "ab"),
"unterminated-entity": ("<p>a&amp b</p>", "a& b"),
"end-tag-attribute": ("<p>hello</p hidden=x>", "hello"),
"end-tag-junk": ("<p>hello</p foo>", "hello"),
"end-tag-slash": ("<p>hello</p/>", "hello"),
"empty-end-tag": ("<p>he</>llo</p>", "hello"),
"empty-end-tag-after": ("<p>hello</p></>", "hello"),
"slash-attribute-p": ("<p/hidden>hello</p>", "hello"),
"slash-junk-br": ("<p>a<br/x>b</p>", "a\nb"),
"marked-section": ("<p>x<![ x</p>", "x"),
"vertical-tab-in-tag": ("<p\x0b>hello</p>", "hello"),
}


@pytest.mark.parametrize("markup,text", list(_REJECTED_HTML.values()), ids=list(_REJECTED_HTML))
def test_saved_comment_check_rejects_html_with_a_different_structure(markup, text):
with pytest.raises(_UnexpectedError):
_check_saved_comment(draft_feedback_out(Feedback={"Text": text, "Html": markup}), text)


_ACCEPTED_HTML = {
"exact": ("<p>a &amp; b<br />c</p>", "a & b\nc"),
"br-spellings": ("<p>a<br>b<br/>c<br />d<BR>e<br/ >f</p>", "a\nb\nc\nd\ne\nf"),
"tag-case": ("<P>hello</P>", "hello"),
"space-inside-tags": ("<p >hello</p >", "hello"),
"outer-whitespace": ("\n\t <p>hello</p> \r\n", "hello"),
"line-breaks-next-to-tags": ("<p>\na<br />\nb\n<br>c\n</p>", "a\nb\nc"),
"crlf-next-to-tags": ("<p>\r\na<br />\r\nb\r\n</p>", "a\nb"),
"entity-spellings": ("<p>&#38;&#x26;&amp; &quot;\"&#34; &#39;&#x27;' &gt;&#62;> &lt;3</p>",
"&&& \"\"\" ''' >>> <3"),
"raw-lt-text": ("<p>x < y <3</p>", "x < y <3"),
"nbsp": ("<p>a&nbsp;b&#160;c</p>", "a b c"),
"bare-ampersand": ("<p>a & b &; x&</p>", "a & b &; x&"),
"outer-breaks-kept": ("<p><br>hello<br></p>", "\nhello\n"),
}


@pytest.mark.parametrize("markup,text", list(_ACCEPTED_HTML.values()), ids=list(_ACCEPTED_HTML))
def test_saved_comment_check_accepts_known_reformatting(markup, text):
_check_saved_comment(draft_feedback_out(Feedback={"Text": None, "Html": markup}), text)


@pytest.mark.parametrize("text", [
"hello", "\nleading break", "trailing break\n", "\n\nboth\n\n", "a\n\nb", "<b>\"x\" & 'y'</b>",
"tab\there", " outer spaces ", "nbsp here", "</p><p hidden>x", "<!-- c -->", "&amp; literal",
"x<y and y>z", "unicode é中\U0001f600",
])
def test_html_matcher_accepts_exactly_what_was_sent(text):
assert _html_text(_html(text)) == _comparable(text)


def test_attribute_paragraph_with_matching_text_reports_unknown(feedback_file):
hidden = feedback_payload(TEXT)["Feedback"]["Html"].replace("<p>", "<p hidden>", 1)
fake = FakeLMS(happy_routes(get_feedback=[
lambda: response(200, draft_feedback_out(Feedback={"Text": TEXT, "Html": hidden}))]))
result = invoke(fake, "--file", str(feedback_file), "--yes", "--json")
assert result.exit_code == 1
assert json.loads(result.stdout)["outcome"] == "unknown"
assert "saved-draft" not in result.stdout


def test_csrf_bootstrap_failure_means_nothing_was_sent(feedback_file):
fake = FakeLMS(happy_routes())

Expand Down
Loading