content.py

# -*- coding: utf-8 -*-

__copyright__ = "Copyright (C) 2014 Andreas Kloeckner"

__license__ = """
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
"""

from typing import cast, Union, Text

from django.conf import settings
from django.utils.translation import gettext as _

import os
import re
import datetime
import sys

from django.utils.timezone import now
from django.core.exceptions import ObjectDoesNotExist, ImproperlyConfigured
from django.urls import NoReverseMatch

from markdown.extensions import Extension
from markdown.treeprocessors import Treeprocessor

import html.parser as html_parser

from jinja2 import (
        BaseLoader as BaseTemplateLoader, TemplateNotFound, FileSystemLoader)

from relate.utils import dict_to_struct, Struct, SubdirRepoWrapper
from course.constants import ATTRIBUTES_FILENAME

from yaml import safe_load as load_yaml

if sys.version_info >= (3,):
    CACHE_KEY_ROOT = "py3"
else:
    CACHE_KEY_ROOT = "py2"


# {{{ mypy

from typing import (  # noqa
    Any, List, Tuple, Optional, Callable, Text, Dict, FrozenSet, TYPE_CHECKING)
if TYPE_CHECKING:
    # for mypy
    from course.models import Course, Participation  # noqa
    import dulwich  # noqa
    from course.validation import ValidationContext, FileSystemFakeRepoTree  # noqa
    from course.page.base import PageBase  # noqa
    from relate.utils import Repo_ish  # noqa

Date_ish = Union[datetime.datetime, datetime.date]
Datespec = Union[datetime.datetime, datetime.date, Text]


class ChunkRulesDesc(Struct):
    if_has_role: List[Text]
    if_before: Datespec
    if_after: Datespec
    if_in_facility: Text
    if_has_participation_tags_any: List[Text]
    if_has_participation_tags_all: List[Text]
    roles: List[Text]
    start: Datespec
    end: Datespec
    shown: bool
    weight: float


class ChunkDesc(Struct):
    weight: float
    shown: bool
    title: Optional[Text]
    content: Text
    rules: List[ChunkRulesDesc]

    html_content: Text


class StaticPageDesc(Struct):
    chunks = None  # type: List[ChunkDesc]
    content = None  # type: Text


class CourseDesc(StaticPageDesc):
    pass

# }}}


# {{{ mypy: flow start rule

class FlowSessionStartRuleDesc(Struct):
    """Rules that govern when a new session may be started and whether
    existing sessions may be listed.

    Found in the ``start`` attribute of :class:`FlowRulesDesc`.

    .. rubric:: Conditions

    .. attribute:: if_after

        (Optional) A :ref:`datespec <datespec>` that determines a date/time
        after which this rule applies.

    .. attribute:: if_before

        (Optional) A :ref:`datespec <datespec>` that determines a date/time
        before which this rule applies.

    .. attribute:: if_has_role

        (Optional) A list of a subset of the roles defined in the course, by
        default ``unenrolled``, ``ta``, ``student``, ``instructor``.

    .. attribute:: if_has_participation_tags_any

        (Optional) A list of participation tags. Rule applies when the
        participation has at least one tag in this list.

    .. attribute:: if_has_participation_tags_all

        (Optional) A list of participation tags. Rule applies if only the
        participation's tags include all items in this list.

    .. attribute:: if_in_facility

        (Optional) Name of a facility known to the RELATE web page. This rule allows
        (for example) restricting flow starting based on whether a user is physically
        located in a computer-based testing center (which RELATE can
        recognize based on IP ranges).

    .. attribute:: if_has_in_progress_session

        (Optional) A Boolean (True/False) value, indicating that the rule only
        applies if the participant has an in-progress session.

    .. attribute:: if_has_session_tagged

        (Optional) An identifier (or ``null``) indicating that the rule only applies
        if the participant has a session with the corresponding tag.

    .. attribute:: if_has_fewer_sessions_than

        (Optional) An integer. The rule applies if the participant has fewer
        than this number of sessions.

    .. attribute:: if_has_fewer_tagged_sessions_than

        (Optional) An integer. The rule applies if the participant has fewer
        than this number of sessions with access rule tags.

    .. attribute:: if_signed_in_with_matching_exam_ticket

        (Optional) The rule applies if the participant signed in with an exam
        ticket matching this flow.

    .. rubric:: Rules specified

    .. attribute:: may_start_new_session

        (Mandatory) A Boolean (True/False) value indicating whether, if the
        rule applies, the participant may start a new session.

    .. attribute:: may_list_existing_sessions

        (Mandatory) A Boolean (True/False) value indicating whether, if the
        rule applies, the participant may view a list of existing sessions.

    .. attribute:: tag_session

        (Optional) An identifier that will be applied to a newly-created
        session as a "tag".  This can be used by
        :attr:`FlowSessionAccessRuleDesc.if_has_tag` and
        :attr:`FlowSessionGradingRuleDesc.if_has_tag`.

    .. attribute:: default_expiration_mode

        (Optional) One of :class:`~course.constants.flow_session_expiration_mode`.
        The expiration mode applied when a session is first created or rolled
        over.
    """