Skip to content
Draft
159 changes: 159 additions & 0 deletions cms/djangoapps/contentstore/rest_api/v1/advanced_settings_service.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
"""Reads and updates of a course's advanced settings."""

import logging
import re

from rest_framework.exceptions import NotFound, ValidationError
from rest_framework.settings import api_settings

from cms.djangoapps.contentstore.views.course import update_course_advanced_settings
from cms.djangoapps.contentstore.views.permissions import COURSE_NOT_FOUND_MESSAGE
from cms.djangoapps.models.settings.course_metadata import CourseMetadata
from xmodule.modulestore.django import modulestore

log = logging.getLogger(__name__)

# Reported under the name of a refused setting in place of any explanation
# that is not one of the course rules' own messages, such as the text of an
# exception raised while converting the value. That explanation is logged.
INVALID_SETTING_MESSAGE = "The value is not valid for this setting."

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This also replaces v0's hand-written messages, not just exception text, e.g. "The proctoring provider cannot be modified after a course has started. Contact …", "max_team_size cannot be greater than 500", duplicate team ids, missing escalation email. The authoring MFE shows message per setting (ModalErrorListItem.jsx), so once the page moves to v1 authors lose the reason. Could we keep the curated messages in errors[name] and only hide raw exception text? Same contract shape.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, and done in 4f180c5. CourseMetadata is frozen, so v1 can't be told at the source which messages are hand-written; instead it recognises the wording of the rules' own messages (the max_team_size limits, duplicate ids, the comma-joined team-set problems, the three proctoring rules including the unknown-provider sentence, and the missing escalation contact, under both settings it is reported on) and returns those as written. Anything else, such as the TypeError from converting a value, is still logged and replaced by the fixed message. Same shape: errors[name] is a list of strings, each listed once, in v0's order. Tests send the same PATCH to v0 and v1 for each rule and check the text is identical, plus a no-database test that the classifier accepts the real validators' output and refuses exception text. If a rule's wording ever changes, v1 falls back to the fixed message and those tests go red, so nothing can leak.

# Reported when the settings could not be saved for a reason tied to no setting.
SETTINGS_NOT_SAVED_MESSAGE = "The settings could not be saved. No setting was changed."


def _pattern(template):
"""Return a regular expression for ``template``, in which each ``{}`` stands for any text."""
return ".*".join(re.escape(part) for part in template.split("{}"))


def _any_of(patterns):
"""Return a regular expression, as one group, matching any one of ``patterns``."""
return "(?:{})".format("|".join(patterns))


def _in_order_separated_by_commas(slots):
"""Return a regular expression for one or more of ``slots``, in the given order, separated by commas."""
return _any_of(
first + "".join(f"(?:,{later})?" for later in slots[index + 1:])
for index, first in enumerate(slots)
)


# The problems the teams rules report about one team-set, joined with commas
# in this order. Each entry lists the problems that can take its place.
_TEAMSET_PROBLEMS = (
("type {} is invalid",),
("max_team_size must be greater than zero", "max_team_size cannot be greater than 500"),
("id attribute must not be empty",),
("name attribute must not be empty",),
("description attribute must not be empty",),
("extra keys: {}",),
)

_MISSING_ESCALATION_EMAIL = "Provider '{}' requires an exam escalation contact."

# The messages the course's rules in ``CourseMetadata`` write about a refused
# setting, by setting name. They are returned to the caller as written. A
# message missing here, including a rule's reworded or new message, is
# reported as ``INVALID_SETTING_MESSAGE``.
_RULE_MESSAGES = {
"teams_configuration": (
_pattern("max_team_size must be greater than zero"),
_pattern("max_team_size cannot be greater than 500"),
_pattern("duplicate ids: {}"),
_in_order_separated_by_commas([_any_of(map(_pattern, problems)) for problems in _TEAMSET_PROBLEMS]),
),
"proctoring_provider": (
_pattern("The proctoring provider cannot be modified after a course has started. Contact {} for assistance"),
_pattern("The proctoring provider configured for this course, '{}', is not valid."),
_pattern("The selected proctoring provider, {}, is not a valid provider. Please select from one of {}."),
_pattern(_MISSING_ESCALATION_EMAIL),
),
"proctoring_escalation_email": (
_pattern(_MISSING_ESCALATION_EMAIL),
),
}
_RULE_MESSAGE_PATTERNS = {name: re.compile(_any_of(patterns), re.DOTALL) for name, patterns in _RULE_MESSAGES.items()}


def is_rule_message(name, message):
"""Return whether ``message`` is one the course's rules write about the setting ``name``."""
pattern = _RULE_MESSAGE_PATTERNS.get(name)
return pattern is not None and pattern.fullmatch(message) is not None


def _course_block(course_key):
"""Return the course block of ``course_key``, or raise ``NotFound`` when the modulestore has none."""
course_block = modulestore().get_course(course_key)
if course_block is None:
raise NotFound(COURSE_NOT_FOUND_MESSAGE)
return course_block


def settings_authors_do_not_edit(course_key):
"""Return the names of the course's settings that are not edited as advanced settings."""
return frozenset(CourseMetadata.get_exclude_list_of_fields(course_key))


def get_advanced_settings(course_key, full=False):
"""
Return the advanced settings of the course, keyed by setting name.

By default only the settings course authors edit in Studio are returned;
with ``full`` every setting of the course is.
"""
course_block = _course_block(course_key)
if full:
return CourseMetadata.fetch_all(course_block)
return CourseMetadata.fetch(course_block)


def update_advanced_settings(course_key, changes, user):
"""
Apply ``changes`` (``{name: {"value": value}}``) to the course as ``user``.

Every value is validated before any is stored; when one is refused,
nothing is stored and ``ValidationError`` maps each refused setting to its
messages (see ``_errors_by_setting``).
Returns the settings course authors edit in Studio, as stored.
"""
course_block = _course_block(course_key)
try:
return update_course_advanced_settings(course_block, changes, user)
except ValidationError as error:
raise _errors_by_setting(course_key, error) from error


def _errors_by_setting(course_key, error):
"""
Return a ``ValidationError`` mapping each refused setting to its messages.

The settings validator reports one entry per problem, carrying the
setting's name and an explanation. An explanation the course's rules write
themselves (a team size limit, a proctoring rule) is returned as written.
Any other explanation, such as the text of an exception raised while
converting the value, is logged with the course and setting and returned
as ``INVALID_SETTING_MESSAGE``. A failure not tied to a setting is logged
and reported with ``SETTINGS_NOT_SAVED_MESSAGE``.
"""
detail = error.detail if isinstance(error.detail, list) else [error.detail]
by_setting = {}
unattributed = []
for entry in detail:
name = entry.get("key") if isinstance(entry, dict) else None
if not name:
unattributed.append(entry)
continue
name, explanation = str(name), str(entry.get("message", ""))
if is_rule_message(name, explanation):
message = explanation
else:
log.warning("Advanced setting %s of course %s was refused: %s", name, course_key, explanation)
message = INVALID_SETTING_MESSAGE
messages = by_setting.setdefault(name, [])
if message not in messages:
messages.append(message)
if unattributed:
log.warning("Advanced settings of course %s were not saved: %s", course_key, unattributed)
by_setting.setdefault(api_settings.NON_FIELD_ERRORS_KEY, []).append(SETTINGS_NOT_SAVED_MESSAGE)
return ValidationError(by_setting)
6 changes: 6 additions & 0 deletions cms/djangoapps/contentstore/rest_api/v1/authoring_urls.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
YoutubeTranscriptChecksViewSet,
YoutubeTranscriptImportsViewSet,
)
from cms.djangoapps.contentstore.rest_api.v1.views.advanced_settings import CourseAdvancedSettingsViewSet

app_name = "authoring_v1"

Expand Down Expand Up @@ -39,4 +40,9 @@
),
name="xblock_detail",
),
path(
"courses/<course_key:course_key>/advanced_settings/",
CourseAdvancedSettingsViewSet.as_view({"get": "retrieve", "patch": "partial_update"}),
name="course_advanced_settings",
),
]
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
"""Serializers for a course's advanced settings."""

from collections.abc import Mapping

from drf_spectacular.extensions import OpenApiSerializerExtension
from drf_spectacular.plumbing import build_object_type, get_doc
from rest_framework import serializers
from rest_framework.exceptions import ValidationError
from rest_framework.settings import api_settings

MINIMAL_VIEW = "minimal"
FULL_VIEW = "full"


class AdvancedSettingSerializer(serializers.Serializer): # pylint: disable=abstract-method
"""One advanced setting of a course, as Studio presents it for editing."""

value = serializers.JSONField(
allow_null=True,
help_text="Current value of the setting. Its type depends on the setting.",
)
display_name = serializers.CharField(help_text="Name of the setting as Studio shows it.")
help = serializers.CharField(
allow_null=True,
help_text="Text explaining what the setting does, or null when the setting has none.",
)
deprecated = serializers.BooleanField(help_text="Whether the setting is deprecated.")
hide_on_enabled_publisher = serializers.BooleanField(
help_text="Whether Studio hides the setting when the course is managed by a publishing service.",
)

class Meta:
ref_name = "AdvancedSetting.v1"


class AdvancedSettingUpdateSerializer(serializers.Serializer): # pylint: disable=abstract-method
"""The new value of one advanced setting."""

value = serializers.JSONField(
allow_null=True,
help_text="New value of the setting. Its type depends on the setting.",
)

class Meta:
ref_name = "AdvancedSettingUpdate.v1"


class _SettingsByNameSerializer(serializers.Serializer): # pylint: disable=abstract-method
"""
An object whose members are settings keyed by setting name.

The set of names depends on the course, so the members cannot be declared
as fields; each one is handled by ``setting_serializer_class``. Names given
in the ``ignored_settings`` context entry are dropped before any member is
validated.
"""

setting_serializer_class = None

def to_representation(self, instance):
return {
name: self.setting_serializer_class(setting).data
for name, setting in instance.items()
}

def to_internal_value(self, data):
if not isinstance(data, Mapping):
message = self.error_messages["invalid"].format(datatype=type(data).__name__)
raise ValidationError({api_settings.NON_FIELD_ERRORS_KEY: [message]}, code="invalid")
ignored = self.context.get("ignored_settings", frozenset())
validated, errors = {}, {}
for name, item in data.items():
if name in ignored:
continue
setting = self.setting_serializer_class(data=item)
if setting.is_valid():
validated[name] = dict(setting.validated_data)
else:
errors[name] = [str(message) for messages in setting.errors.values() for message in messages]
if errors:
raise ValidationError(errors)
return validated


class CourseAdvancedSettingsSerializer(_SettingsByNameSerializer): # pylint: disable=abstract-method
"""A course's advanced settings, keyed by setting name in the order the course declares them."""

setting_serializer_class = AdvancedSettingSerializer

class Meta:
ref_name = "CourseAdvancedSettings.v1"


class CourseAdvancedSettingsUpdateSerializer(_SettingsByNameSerializer): # pylint: disable=abstract-method
"""
New values for some of a course's advanced settings, keyed by setting name.

Settings that authors do not edit are ignored, whatever their entry holds;
settings the course does not have are ignored once their entry is valid.
"""

setting_serializer_class = AdvancedSettingUpdateSerializer

class Meta:
ref_name = "CourseAdvancedSettingsUpdate.v1"


class AdvancedSettingsQuerySerializer(serializers.Serializer): # pylint: disable=abstract-method
"""Query parameters of a read of a course's advanced settings."""

view = serializers.ChoiceField(
choices=[MINIMAL_VIEW, FULL_VIEW],
default=MINIMAL_VIEW,
help_text=(
"Which settings to return. 'minimal' returns the settings course authors edit in Studio; "
"'full' returns every setting of the course, including those Studio manages on other pages "
"and those of features that are turned off."
),
)
fields = serializers.CharField(
required=False,
allow_blank=True,
help_text=(
"Comma-separated names of the settings to return, out of those the view returns. "
"Names the view does not return are ignored."
),
)

class Meta:
ref_name = "AdvancedSettingsQuery.v1"


class SettingsByNameSerializerExtension(OpenApiSerializerExtension):
"""Publish a settings-by-name serializer as an object whose members are its setting component."""

target_class = _SettingsByNameSerializer
match_subclasses = True

def map_serializer(self, auto_schema, direction):
setting = auto_schema.resolve_serializer(self.target.setting_serializer_class, direction)
return build_object_type(
description=get_doc(self.target.__class__),
additionalProperties=setting.ref,
)
Loading
Loading