Repository navigation
feat: serve course advanced settings from authoring v1 #39303
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
taimoor-ahmed-1
wants to merge
10
commits into
openedx:master
Choose a base branch
from
edly-io:feat/standardize-advanced-settings-api
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+2,453
−6
Draft
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
15a9886
feat: add course existence and advanced settings permission classes
4cf3dec
feat: serve course advanced settings from authoring v1
ac6fe16
docs: mark the v0 advanced settings deprecated in favour of authoring v1
2376c38
test: import the authoring URLconf inside the test that needs it
0131b82
test: align the advanced settings tests with the platform's behaviour
9b4d60e
test: share the authoring v1 test helpers
25c5768
docs: describe what an inactive session and a superuser are allowed
de829c6
docs: remove the deprecation notes from the v0 advanced settings docs…
4f180c5
fix: return the course rules' own messages for refused advanced settings
a3be9b7
test: give the long-explanation check text that is not a rule message
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
159 changes: 159 additions & 0 deletions
159
cms/djangoapps/contentstore/rest_api/v1/advanced_settings_service.py
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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." | ||
| # 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) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
144 changes: 144 additions & 0 deletions
144
cms/djangoapps/contentstore/rest_api/v1/serializers/advanced_settings.py
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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, | ||
| ) |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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
messageper setting (ModalErrorListItem.jsx), so once the page moves to v1 authors lose the reason. Could we keep the curated messages inerrors[name]and only hide raw exception text? Same contract shape.There was a problem hiding this comment.
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.
CourseMetadatais 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 (themax_team_sizelimits, 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 theTypeErrorfrom 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.