lms.backend.canvas.common

  1import datetime
  2import http
  3import re
  4import typing
  5
  6import html2text
  7
  8import edq.net.request
  9import edq.util.json
 10import edq.util.time
 11import requests
 12
 13DEFAULT_PAGE_SIZE: int = 95
 14HEADER_LINK: str = 'Link'
 15
 16def fetch_next_canvas_link(response: requests.Response) -> typing.Union[str, None]:
 17    """
 18    Fetch the Canvas-style next link within the headers.
 19    If there is no next link, return None.
 20    """
 21
 22    headers = response.headers
 23
 24    if (HEADER_LINK not in headers):
 25        return None
 26
 27    links = headers[HEADER_LINK].split(',')
 28    for link in links:
 29        parts = link.split(';')
 30        if (len(parts) != 2):
 31            continue
 32
 33        if (parts[1].strip() != 'rel="next"'):
 34            continue
 35
 36        return str(parts[0].strip().strip('<>'))
 37
 38    return None
 39
 40def make_request(
 41        method: str,
 42        url: str,
 43        raise_on_404: bool = False,
 44        json: bool = True,
 45        **kwargs: typing.Any) -> typing.Union[typing.Any, None]:
 46    """ Make a single Canvas request and return the decoded JSON body. """
 47
 48    try:
 49        _, body_text = edq.net.request.make_request(method, url, **kwargs)
 50    except requests.HTTPError as ex:
 51        if (raise_on_404 or (ex.response is None) or (ex.response.status_code != http.HTTPStatus.NOT_FOUND)):
 52            raise ex
 53
 54        return None
 55
 56    if (not json):
 57        return body_text
 58
 59    return edq.util.json.loads(body_text, strict = True)
 60
 61def make_get_request(url: str, **kwargs: typing.Any) -> typing.Union[typing.Any, None]:
 62    """ Make a single Canvas GET request. """
 63
 64    return make_request('GET', url, **kwargs)
 65
 66def make_post_request(url: str, **kwargs: typing.Any) -> typing.Union[typing.Any, None]:
 67    """ Make a single Canvas POST request. """
 68
 69    return make_request('POST', url, **kwargs)
 70
 71def make_put_request(url: str, **kwargs: typing.Any) -> typing.Union[typing.Any, None]:
 72    """ Make a single Canvas PUT request. """
 73
 74    return make_request('PUT', url, **kwargs)
 75
 76def make_delete_request(url: str, **kwargs: typing.Any) -> typing.Union[typing.Any, None]:
 77    """ Make a single Canvas DELETE request. """
 78
 79    return make_request('DELETE', url, **kwargs)
 80
 81def make_get_request_list(
 82        url: str,
 83        headers: typing.Dict[str, typing.Any],
 84        data: typing.Union[typing.Dict[str, typing.Any], None] = None,
 85        raise_on_404: bool = False,
 86        ) -> typing.Union[typing.List[typing.Dict[str, typing.Any]], None]:
 87    """ Repeatedly call make_get_request() (using a JSON body and next link) until there are no more results. """
 88
 89    output: typing.List[typing.Dict[str, typing.Any]] = []
 90
 91    next_url: typing.Union[str, None] = url
 92
 93    while (next_url is not None):
 94        try:
 95            response, body_text = edq.net.request.make_get(next_url, headers = headers, data = data)
 96        except requests.HTTPError as ex:
 97            if (raise_on_404 or (ex.response is None) or (ex.response.status_code != http.HTTPStatus.NOT_FOUND)):
 98                raise ex
 99
100            return None
101
102        next_url = fetch_next_canvas_link(response)
103
104        new_results = edq.util.json.loads(body_text, strict = True)
105        for new_result in new_results:
106            output.append(new_result)
107
108    return output
109
110def parse_timestamp(value: typing.Union[str, None]) -> typing.Union[edq.util.time.Timestamp, None]:
111    """ Parse a Canvas-style timestamp into a common form. """
112
113    if (value is None):
114        return None
115
116    # Parse out some cases that Python <= 3.10 cannot deal with.
117    value = re.sub(r'Z$', '+00:00', value)
118    value = re.sub(r'(\d\d:\d\d)(\.\d+)', r'\1', value)
119
120    pytime = datetime.datetime.fromisoformat(value)
121    return edq.util.time.Timestamp.from_pytime(pytime)
122
123def html_to_markdown(html: typing.Union[str, None]) -> str:
124    """
125    Parse the text from a Canvas quiz question into markdown.
126    We intend for the resulting markdown to have a little HTML as possible.
127    This is an impossible task, but we want to do our best.
128    """
129
130    if (html is None):
131        return ''
132
133    converter = html2text.HTML2Text()
134
135    converter.body_width = 0
136    converter.mark_code = True
137
138    text = converter.handle(html)
139    text = text.strip()
140
141    # Replace code tags with fences.
142    text = re.sub(r'\[/?code\]', '```', text)
143
144    # Replace placeholders (e.g., for fill in the blank questions).
145    text = re.sub(r'\[(\w+?)\]', r'<placeholder>\1</placeholder>', text)
146
147    return text