Skip to content

feat: read and partially update course grading through authoring v3 - #39227

Open
taimoor-ahmed-1 wants to merge 4 commits into
openedx:masterfrom
edly-io:feat/standardize-course-grading-api
Open

taimoor-ahmed-1 wants to merge 4 commits into
openedx:masterfrom
edly-io:feat/standardize-course-grading-api

Conversation

@taimoor-ahmed-1

@taimoor-ahmed-1 taimoor-ahmed-1 commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR standardizes the Course Grading functional area (#39065, umbrella #38137) on the existing authoring v3 grading resource, /api/authoring/v3/courses/{course_key}/grading/, following the API standardization ADRs docs/decisions/0025 to 0038 and OEP-69.

Why extend v3 instead of adding a version. Grading is versioned per resource, and v3 is already its conforming version (#39078 mounted it at the address above). But v3 could only write, so every caller still read through v1. This PR:

  • adds a GET to v3. Every GET to v3 returned 405, and the schema change only adds.
  • validates every PATCH body against the published shape. The v3 PATCH came in with feat: apply ADR standardization to AuthorGrading apis #38726 (f3e5da0) and is on no named release (absent from release/verawood and release/ulmo), so there is no released contract to keep; one strict request serializer replaces master's unvalidated pass-through. The guarantee is that whatever a read returns, sending it back is accepted and changes nothing.
  • makes PATCH a real partial update. Partial bodies all returned 500 before.
  • deprecates v1 GET/POST and v0 POST in favour of v3.

Change table

Endpoint Before After
GET /api/authoring/v3/courses/{course_key}/grading/, and the already-deprecated /api/contentstore/v3/authoring_grading/{course_key}/ 405 Default: the four-field policy, the same shape PATCH returns. ?view=full also returns v1's course_assignment_lists, default_grade_designations, is_credit_course, show_credit_eligibility and mfe_proctored_exam_settings_url, under their v1 names.
PATCH, both v3 addresses The body went to the model unvalidated. Any body without all four keys returned 500, and some malformed bodies wrote corrupt data first. Whole body (all four keys): validated against the published shape. Cutoff values and the credit minimum must be finite JSON numbers, grader types and labels strings, graders a list. Of the 227 whole-body shapes master stored, 56 are now 400 with nothing written (15 grader type, 14 cutoff values, 13 grader label, 7 credit minimum, 4 graders ""/{}, 3 cutoffs null/{}); the other 171 are stored as before, with the same response, events and credit task. Partial body: changes only the fields sent; graders are never re-sent, so stored weights cannot drift. Every body that returned 500: 400 validation envelope, nothing written.
v1 GET/POST /api/contentstore/v1/course_grading/{course_id}, v0 POST /api/contentstore/v0/grading/{course_id} v1 not deprecated; v0 listed on #39128 but not marked in the schema Behaviour unchanged. deprecated: true in the schema, plus a docstring naming the successor.

ADRs applied

  • 0025 serializers - separate request and response serializers, help_text on every field, *.v3 ref names, nullability and required fields matching real responses
  • 0026 permissions - per-action permission classes (CanViewGradingSettings, CanEditGradingSettings) replace the inline check; 404-before-403 kept; where policy-based permissions are off, a read falls back to Studio read access and a change to Studio write access
  • 0027 schema / docs - every action documented; the viewset parses JSON only, so the PATCH body is published as application/json alone; GET 200 is one read component whose view=full fields are optional; errors reference ErrorResponse; GET carries the openedx-platform-sdk tag
  • 0028 viewsets - retrieve on the existing ViewSet; logic in grading_service.py; query counts pinned against v1
  • 0029 errors - envelope on every 400/401/403/404 this view raises. Open, unchanged from master and pinned by tests to flip when fixed: (1) DRF's malformed-JSON 400, 405, 406 and 415 come back typed internal because edx-drf-extensions does not catalogue them; (2) a malformed course key gets the routing-level HTML 404 on the conforming address, and on the legacy address for keys with no separator. No catch-all exists for authoring v3 yet.
  • 0030 GET idempotence - GET, ?view=full and HEAD write no domain data and fire no signal (SQL and Mongo captured, credit and non-credit, flag off and on, course auditor on a fresh database). The only write is the openedx-authz policy-version cache row on a fresh database's first permission check, which v1 makes too.
  • 0031 merged endpoints - n/a: no action family; the three writes are versions of one operation, which 0037 governs
  • 0032 pagination - n/a: singleton resource, no list
  • 0033 filtering - n/a: no list; the one view parameter is serializer-validated and documented
  • 0034 authentication - no authentication_classes on the viewset: it uses the platform default (JWT and session). A session whose account is not activated is now refused with 401 on both v3 addresses, where master's v3 PATCH admitted it; v1 and v0 still admit it. Bearer is refused, as before on v3.
  • 0035 MFE config - n/a: no Course Grading endpoint serves front-end configuration
  • 0036 nested JSON - thin default, ?view=full opt-in; both views are published in one read component, with the five view=full fields optional and described as present only with view=full
  • 0037 versioning - in-place categories 1, 2 and 4 with evidence below; v1 and v0 deprecated in schema and docstrings; DEPR entry on [DEPR]: Contentstore and enrollment API versions superseded by FC-0118 #39128 (comment) with the window per [DEPR]: Contentstore and enrollment API versions superseded by FC-0118 #39128
  • 0038 URL structure - route map change only (GET added); both v3 addresses serve the same view and actions; no address or URL name changed
  • OEP-66 queryset scoping - n/a: not a list endpoint
  • OEP-69 conventions - no governance identifiers or history narration in code or schema text; no local copies of library primitives

Compliance matrix

Decision Status How Evidence
0025 met serializers/grading.py: response CourseGradingRead.v3 (GET, view=full fields optional), CourseGrading.v3 (PATCH), Grader.v3, GracePeriod.v3; request CourseGradingUpdate.v3, GraderUpdate.v3, GracePeriodUpdate.v3. CourseGradingUpdateSerializer validates every PATCH body, whole or partial. GradingReadTest.test_reads_match_the_published_shapes; test_a_read_sent_back_is_accepted_and_changes_nothing (six stored shapes, both mounts, default and ?view=full); test_equivalent_spellings_store_the_same_policy; cms/lib/tests/test_spectacular.py schema pins
0026 met v3/permissions.py, chosen per action in get_permissions(); legacy fallback READ for the read, WRITE for the change GradingAccessLegacyPermissionsTest, GradingAccessAuthzTest: every cell also asserts v1 makes the same decision; test_each_operation_falls_back_to_its_own_studio_access withholds each Studio access level in turn
0027 met @extend_schema on every action; parser_classes = (JSONParser,), so the request body is JSON-only; GET 200 = one read component, view=full fields optional test_spectacular.py (test_the_read_is_one_shape_whose_full_view_fields_are_optional, test_the_update_body_is_json_only, nullable/required pins); schema gate
0028 met ViewSet retrieve; thin views; service module GradingQueryCountTest, GradingQueryCountAuthzTest, test_default_read_costs_no_more_than_the_v1_read, test_full_read_costs_the_same_as_the_v1_read
0029 partial Envelope via StandardizedErrorMixin; validation before any write test_bodies_outside_the_published_shape_are_refused_before_anything_is_written, test_numbers_too_large_to_store_are_refused_before_anything_is_written; open items pinned by test_malformed_json_is_refused_with_400, test_unsupported_body_type_is_refused_with_415, test_a_form_encoded_body_is_refused_with_415, test_unsupported_accept_is_refused_with_406, test_other_methods_are_not_allowed, test_unparsable_or_slash_form_key_is_404_on_conforming_route, test_key_without_separators_is_404_on_legacy_route
0030 met No writes on read GradingReadSideEffectsLegacyPermissionsTest, GradingReadSideEffectsAuthzTest, test_the_first_v1_read_writes_the_same_row
0034 met Platform default authentication; no authentication_classes on the viewset test_inactive_user_with_a_session_is_refused_with_401 (the same session is admitted once the account is active), test_jwt_caller_may_read, test_bearer_token_is_refused, test_anonymous_caller_is_refused_with_401
0036 met Thin default, ?view=full test_full_view_equals_the_v1_read_flattened, test_full_view_credit_context_equals_v1, test_full_view_proctoring_link_equals_v1, test_full_view_without_a_grace_period_equals_v1, test_grace_period_seconds_are_shown_where_v1_drops_them, test_unknown_view_is_refused_with_400, test_empty_view_is_the_default_view
0037 met Categories 1, 2, 4 (below), plus two tightenings in place, both on a PATCH that is on no release branch (#38726; absent from verawood and ulmo), so category 2's released-contract rule does not apply: the whole-body contract is narrowed (56 shapes refused), and sessions of inactive accounts are refused (platform default authentication); DEPR entry on #39128 versions gate; test_a_read_sent_back_is_accepted_and_changes_nothing; test_inactive_user_with_a_session_is_refused_with_401; DEPR entry
0038 met Route map only GradingRoutingTest (test_conforming_and_legacy_routes_share_view_and_actions, test_legacy_format_suffix_reads_and_updates_like_the_plain_address); urls gate
0031, 0032, 0033, 0035, OEP-66 n/a Reasons in the checkbox list none

In-place edits

File Category (ADR 0037) What and why
v3/views/authoring_grading.py 2 opt-in addition (GET, view, partial bodies that returned 500); 1 like-for-like (inline check to permission classes, v0 to v3 serializers) Whole-body PATCH is validated against the published shape (a tightening on an unreleased endpoint, see 0037); reads round-trip into PATCH unchanged
v3/authoring_urls.py 2 {"patch": "partial_update"} becomes {"get": "retrieve", "patch": "partial_update"} and nothing else
v3/views/tests/test_authoring_grading.py current-version tests Mocks replaced by real courses and roles; traceability below
v3/grading_service.py, v3/permissions.py, v3/serializers/__init__.py, v3/serializers/grading.py added inside v3 Service, permission classes and v3-owned serializers. The v0 serializers lack help_text and are frozen; reusing their names with new classes would collide in the schema.
v1/views/grading.py, v0/views/authoring_grading.py 4 docstring-only deprecation markers AST with docstrings stripped is identical to master; v1 and v0 tests untouched
cms/lib/spectacular.py, cms/lib/tests/test_spectacular.py schema hook (not a version directory) SUPERSEDED_PATHS gains v1 and v0, so the existing post-processing hook marks them deprecated: true. No new hook, no other hook change, no settings change.

Test traceability (master test_authoring_grading.py to this PR)

Master test Now covered by
test_unauthenticated_patch_returns_401 (x2), test_unauthenticated_patch_returns_standardized_401, test_unauthenticated_401_type_uri test_anonymous_caller_is_refused_with_401 (both permission classes, both mounts, GET and PATCH, envelope slug)
test_authenticated_without_grading_permission_returns_403, test_non_author_patch_returns_standardized_403, test_non_author_403_type_uri test_user_without_a_role_is_refused_with_403, test_limited_staff_is_refused, test_staff_of_another_course_is_refused, test_data_researcher_is_refused, test_legacy_course_staff_without_a_policy_role_is_refused
test_nonexistent_course_returns_standardized_404, test_not_found_type_uri test_unknown_course_is_404_before_permission_is_checked
test_patch_with_minimum_grade_credit_fires_credit_task, test_patch_without_minimum_grade_credit_skips_credit_task test_partial_bodies_change_only_the_fields_sent (task queued if and only if the key is sent); test_a_read_sent_back_is_accepted_and_changes_nothing (the task is queued for every whole body, since a read always carries the key)
test_patch_on_conforming_route_updates_grading test_partial_bodies_change_only_the_fields_sent, test_a_read_sent_back_is_accepted_and_changes_nothing (real course instead of a mocked update)
test_post_not_allowed test_other_methods_are_not_allowed (POST, PUT, DELETE; envelope)
test_error_body_has_no_developer_message, test_instance_field_is_request_path assert_error_envelope on every refusal
test_detail_url_resolves, test_conforming_url_reverses_to_expected_path, test_conforming_and_legacy_routes_share_view_and_actions, test_version_only_course_key_is_404_on_conforming_route, test_v0_endpoint_unaffected_by_v3_envelope kept under the same names in GradingRoutingTest
test_invalid_course_key_is_404_on_conforming_route test_unparsable_or_slash_form_key_is_404_on_conforming_route (now also pins the HTML content type)

Backward compatibility

  • Versions gate: PASS. v1 and v0 differ from master only in docstrings. Protected: the grading model, the legacy Studio handler, utils.py, cms/urls.py, the authz app, view_utils.py, views/permissions.py.

  • URLs gate: PASS. No address or URL name changed. The gate does not see HTTP methods, so the added GET was probed by request: the legacy .json suffix address now answers GET and PATCH like the plain address, where master answered 405 and 500.

  • v1, v0 and course-settings tests untouched and green.

  • PATCH replay against master. 520 distinct bodies were each sent to master and to this branch, on both v3 addresses and both sides of MATERIAL_RECOMPUTE_ONLY:

    • of the 215 bodies master accepted, 159 give identical response bytes, stored policy, signals, events and credit task; 56 are now refused with 400 and nothing written (the shapes listed in the change table), which is the one deliberate contract change;
    • 294 bodies that made master return 500 now return a 400 validation envelope with nothing written;
    • 11 partial bodies that made master return 500 now succeed and change only the fields sent;
    • nothing else.

    The replay was a one-off measurement. The committed guarantee is the round trip: for six stored shapes (never configured; custom graders with empty and null labels; no assignment types; null credit minimum; cutoffs and credit outside 0–1; a course saved with the authoring app's body), the read is sent back on both mounts, default and ?view=full, on both sides of MATERIAL_RECOMPUTE_ONLY, and must be accepted, change nothing, queue the credit task, and fire the signal only with the flag off.

  • Schema gate: FAIL, 4 BREAKING, each a correction. The PATCH 200 schema on both addresses now marks grade_cutoffs and graders[].type nullable. Master already returns null in exactly those places: the replay records 8 master 200 responses carrying grade_cutoffs: null, a null cutoff value and a null grader type. The wire is unchanged; master's schema was wrong, and a client generated from it fails on those courses. Otherwise: 0 other breaking, 5 INFO (2 GETs added, 3 operations newly deprecated), 2 WARN (the viewset's authenticator declaration at the time; it declares none now, so what remains is the platform-default authenticator warning every default-auth view emits; the gate was not re-run after the review round).

  • Request schema changes (PATCH, both addresses):

    • form and multipart media types removed: the viewset parses JSON only, so a form or multipart body is refused with 415, as any other non-JSON body already was;
    • graders no longer nullable (null was a 500);
    • each grader requires only type (the model defaults the rest);
    • grade_cutoffs gains minProperties: 1 for partial bodies;
    • grace_period gets its own request component;
    • description text added.

Error-format decision

Versioned path: the new GET and the validated PATCH use v3's existing error envelope; v1 and v0 keep their legacy bodies.

Deprecations

v1 GET/POST /api/contentstore/v1/course_grading/{course_id} and v0 POST /api/contentstore/v0/grading/{course_id} are deprecated: true in the CMS schema, and their docstrings name the v3 successor. No runtime header (frozen routes). The DEPR record is an entry on #39128, whose body says further areas are appended there; the entry is this comment. Window, per #39128: the marking ships in the next named release after Verawood, and v1 and v0 stay mounted until one named release after that.

Authorization

Legacy check v3
IsAuthenticated (v1, v0 view_auth_classes; v3 PATCH) IsAuthenticated, first
verify_course_exists (v1, v0); resolve_course_key (v3) resolve_course_key inside the action's permission class, before the role check: 404 before 403
authz_permission_required(COURSES_VIEW_GRADING_SETTINGS, READ) (v1 GET) CanViewGradingSettings
authz_permission_required(COURSES_EDIT_GRADING_SETTINGS, READ) (v1 POST, v0 POST); inline check (v3 PATCH) CanEditGradingSettings
Legacy fallback has_studio_read_access for both read and edit has_studio_read_access for the read, has_studio_write_access for the change. On a course in Studio the two grant the same callers (read-only Studio access exists only for libraries), so no course caller gains or loses access; the matrix still agrees with v1 cell for cell.

Nobody gains read access. Bearer-token callers (v1 only) and slash-form course keys on the conforming address are refused, as on v3 before this PR. Sessions of accounts that are not activated are refused with 401 on both v3 addresses (master's v3 PATCH admitted them; v1 and v0 still do), so an author with an unactivated account who moves from v1 to v3 must activate first.

Gate report

run_gates.sh --base origin/master --service cms --prefix /api/authoring/v3/, run in a container with the branch's pinned requirements (Python 3.12, edx-drf-extensions 10.9.0). No gate was skipped.

versions   PASS  v1/v0 docstring-only; protected legacy files untouched
hygiene    PASS  0 FAIL, 0 WARN
schema     FAIL  4 BREAKING = "response field became nullable" on PATCH 200 grade_cutoffs and
                 graders[].type, both addresses: corrections, see Backward compatibility.
                 2 WARN = the authenticator declaration at the time, since removed (gate not
                 re-run after the review round). 5 INFO.
urls       PASS  0 FAIL, 0 WARN
old-tests  PASS  107 passed (v1, v0 grading; course settings), unmodified
tests      PASS  319 passed on 8ef03ef9ea (v3 grading, v1 and v0 grading, CMS schema hooks), run in a platform container

The schema gate cannot tell a schema fix from a contract change: it reports any response field gaining nullable as breaking. The four lines are fixes; the replay above shows master already sends null there.

The replay tests (about 4.3 minutes together) are removed; the update tests now build about 120 courses instead of about 1,680.

Query counts (warm request, flag off; SQL / Mongo reads / Mongo writes): v1 GET 14 / 4 / 0; v3 GET 12 / 4 / 0; v3 GET ?view=full 14 / 4 / 0; PATCH 33 / 42 / 6 on both addresses, the same as master.

Mutation checks. Each guard was broken on purpose and the suite went red, with the files restored byte-for-byte afterwards:

  • implementation, 22 mutations;
  • validation, 18;
  • schema, 15;
  • tests and hook, 13, before the hook was removed; after the review round, the edit fallback reverted to READ turns four cells of test_each_operation_falls_back_to_its_own_studio_access red.

SDK

The GET is tagged openedx-platform-sdk. Regenerating the SDK after merge brings:

  • the conforming GET and partial PATCH;
  • a GET on the deprecated /api/contentstore/v3/authoring_grading/... address, deprecated from the start;
  • model renames authoring_grading_*_v0 to *_v3;
  • a grader request model that requires only type (it required five fields, more than the server ever did);
  • grade_cutoffs and grader type typed nullable in responses;
  • one read model whose five view=full fields are optional.

Follow-ups

  • frontend-app-authoring: read v3 ?view=full instead of v1 GET, and write to the conforming v3 address.
  • Grader weights are truncated on output in v0, v1 and v3: 0.29 is shown as 28, so an MFE save stores 0.28.
  • v0 and v1: an integer wider than 8 bytes in a grading body returns 500 and leaves the course unreadable until the process restarts. v3 now refuses these with 400.
  • edx-drf-extensions:
    • catalogue ParseError, MethodNotAllowed, NotAcceptable and UnsupportedMediaType;
    • flatten_detail puts a Python repr into detail for every field-keyed 400.
  • openedx-authz: the first permission check on a fresh database writes the policy-version row, including during reads.
  • Authoring v3: a JSON catch-all for unmatched keys (the HTML 404 above).
  • Corrupt legacy data: a course that a v0/v1 write or an import left with null cutoffs, a null cutoff value or a non-string grader type reads back a body the v3 PATCH refuses (400, nothing written); the author fixes the value first. Counts, weights and grace periods stay lenient (numeric strings, booleans, any timedelta unit) because the model converts them.
  • Credit task on null: minimum_grade_credit: null still queues the credit recalculation, as on master.

🤖 Generated with Claude Code

@openedx-webhooks openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Oct 13, 2026
@openedx-webhooks

openedx-webhooks commented Oct 13, 2026 •

Copy link
Copy Markdown

Thanks for the pull request, @taimoor-ahmed-1!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform-oncall.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

  • If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
    • This process (including the steps you'll need to take) is documented here.
  • If it doesn't, simply proceed with the next step.
🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

  • Dependencies

    This PR must be merged before / after / at the same time as ...

  • Blockers

    This PR is waiting for OEP-1234 to be accepted.

  • Timeline information

    This PR must be merged by XX date because ...

  • Partner information

    This is for a course on edx.org.

  • Supporting documentation
  • Relevant Open edX discussion forum threads
🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details
Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

  • The size and impact of the changes that it introduces
  • The need for product review
  • Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

@Faraz32123 Faraz32123 left a comment

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.

Went through this locally. The read, the partial update and the permission order all look right to me. A few things below, mainly the first one.

Also, the description and the test module are quite big now (about 1,000 more test lines, and two tests take around 4 minutes together). If the first point goes the simpler way, a lot of that goes away too.

list_serializer_class = _GraderListSerializer


class _WholeGradingPolicyUpdateSerializer(CourseGradingUpdateSerializer): # pylint: disable=abstract-method

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.

Do we need this second serializer? v3 grading PATCH came in with #38726 in June and isn't on release/verawood, so no named release has shipped it. Keeping master's quirks (null cutoffs, any JSON type for grader type, "" as credit minimum) and the 227-body parity test against v0 looks like ADR 0037's released-contract rules applied to an unreleased endpoint.

I think the guarantee we really need is: whatever GET returns, PATCH accepts back. One strict request serializer that keeps that round trip would drop this class, _AnyGradeCutoffsField, _CreditMinimumField and the slow parity tests. What do you think?

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, done in 917203f. I checked the claim: the v3 PATCH came in with #38726 (f3e5da0) and is on neither release/verawood nor release/ulmo. One strict request serializer now validates every body; the lenient class, _AnyGradeCutoffsField, _CreditMinimumField and the 227-body replay are gone. The guarantee is tested the way you put it: for six stored shapes (default, custom graders with empty/null labels, no assignment types, null credit minimum, cutoffs and credit outside 0–1, and a course saved with the authoring app's body), the read is sent back on both mounts, default and ?view=full, and must be accepted and change nothing. Of the 227 bodies master accepted, 56 are now refused (cutoff values, grader type or label not a string, graders ""/{}, credit minimum ""/string/bool). The description lists them.

"a grace period cannot be removed here."
),
)
minimum_grade_credit = _NumberField(

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 only checks that float() works, and the view then passes request.data to the model as sent. So {"minimum_grade_credit": "0.7"} or true passes and gets stored as sent, while the schema says number. Cutoffs use _ScoreField, which requires a real JSON number, so the two are inconsistent. Could this use the same check? The 0 to 1 range from the help text isn't checked either, for this or for cutoffs (master didn't check it), which might be worth adding while we're here.

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.

Fixed in the same commit: minimum_grade_credit uses the same _ScoreField as the cutoffs, so "0.7", true and "" are refused with the fixed message. No 0–1 range check, on purpose: the model stores cutoffs and the credit minimum as sent, and course import and the live v0/v1 POSTs can store any number, so a read can return values outside 0–1 and the round-trip guarantee has to accept them. One of the round-trip shapes pins that.

The credit requirements of the course are refreshed whenever ``minimum_grade_credit``
is present, whether or not its value changes.
"""
if "minimum_grade_credit" in changes:

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.

Minor: this queues the credit task even for "minimum_grade_credit": null, which changes nothing. Master does the same, so fine to leave as is, just noting it.

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.

Left as on master, noted in the description's follow-ups. The round-trip test asserts the task is queued, since a read always carries the key.

Comment thread cms/lib/spectacular.py Outdated
"""
Post-processing hook: mark the legacy addresses of
migrated APIs ``deprecated: true`` and BFF surfaces ``x-internal``.
migrated APIs ``deprecated: true`` and BFF surfaces ``x-internal``,

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.

Heads up: #39310 removes INTERNAL_BFF_PATH_PREFIXES and the x-internal marking, so this docstring will conflict. Whichever merges second just drops "and BFF surfaces x-internal" and keeps the new _publish_overlapping_shapes_as_any_of call.

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.

Noted. #39310 is still open; whichever lands second drops "and BFF surfaces x-internal" and keeps the _publish_overlapping_shapes_as_any_of call.

Comment thread cms/lib/tests/test_spectacular.py Outdated
assert cms_mark_migrated_paths({"paths": {}}, None, None, True) == {"paths": {}}


class SpectacularSettingsTest(TestCase):

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.

Needs a rebase, this conflicts with master in this file now that #39300 has landed. Because of the conflict CI never ran on 917203f, so the re-worked update tests have only run locally. They pass for me on this head, 289 passed, but we want CI on them before this merges.

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.

Rebased onto master in 8ef03ef; the conflict in test_spectacular.py was master's import re / SimpleTestCase change against this branch's additions, both kept. CI runs on the rebased head now.

ref_name = "authoring_grading.CourseGradingUpdate.v3"

def to_internal_value(self, data):
if html.is_html_input(data):

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.

Set parser_classes = (JSONParser,) on the viewset instead of checking for a form body here, then a form body gets the same 415 as any other non-JSON body and the request={"application/json": ...} map in extend_schema can go back to the plain serializer. I tried it and the schema still comes out JSON-only; the only test that changes is test_a_form_encoded_body_is_refused, which now gets a 415.

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.

Done in 8ef03ef: parser_classes = (JSONParser,) on the viewset, the form-body check and its imports are gone from the serializer, and the extend_schema request is the plain serializer again. test_a_form_encoded_body_is_refused became test_a_form_encoded_body_is_refused_with_415 and asserts the 415 internal envelope with nothing written.

Update a course's grading.

Deprecated: use ``PATCH /api/authoring/v3/courses/{course_key}/grading/``,
which accepts this body unchanged. See https://github.com/openedx/openedx-platform/issues/39128.

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.

Since 917203f this is only true for bodies with the published types: a cutoff or credit minimum sent as a string, a "" credit minimum, or a grader whose type is not a string is stored by this endpoint and refused by v3. Say what v3 refuses here, since that is what a caller moving over hits. The migration notes on #39128 make the same claim and need the same note.

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.

Reworded in 8ef03ef. The note now says v3 takes the same body but answers 400 to a null grade_cutoffs or a cutoff that is not a JSON number, a minimum_grade_credit that is neither a number nor null ("" and numeric strings included), and a grader whose type is not a string or whose short_label is neither a string nor null, each of which this endpoint stores. The migration notes in the #39128 entry say the same now.

Update a course's grading.

Deprecated: use ``PATCH /api/authoring/v3/courses/{course_key}/grading/``,
which accepts this body unchanged. See https://github.com/openedx/openedx-platform/issues/39128.

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.

Same here, v3 refuses some of the bodies this endpoint stores.

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.

Same wording as the v1 note, in 8ef03ef.

Comment on lines +82 to +84
# Studio authors whose account is not yet activated use this endpoint from
# the authoring app; the default session class would reject them.
authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser)

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.

Drop the SessionAuthenticationAllowInactiveUser override and the comment above it so this viewset uses the platform default session class, the same as the outline endpoint in #39229. We've had mixed opinions over the years on whether an account that hasn't been activated yet should be able to do things in Studio, so I'd like to standardize on requiring an active account for the authoring APIs. The ADR 0034 line in the description should say the same.

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.

Dropped in 8ef03ef: no authentication_classes on the viewset, so it uses the platform default like the outline endpoint. test_inactive_user_with_a_session_may_read_and_change became test_inactive_user_with_a_session_is_refused_with_401: an unactivated account's session gets 401 on GET and PATCH with nothing written, and the same session is admitted once the account is active. The description's 0034 line and matrix row say the default is used, and the 0037 row records this as a second tightening on the unreleased PATCH, since master's v3 PATCH admitted those sessions.

Comment thread cms/lib/spectacular.py Outdated
# instead of drf-spectacular's oneOf. The default grading shape allows extra
# keys, so a full read matches both shapes and a strict oneOf validator would
# reject it.
ANY_OF_COMPONENTS = {

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.

Do we need this hook? If the read response is one serializer with the five view=full fields marked required=False, the schema says the same thing without any post-processing, and a generated client gets one model with optional fields instead of an anyOf wrapper. I think that is the simpler contract to maintain, but if you went this way on purpose I would like to hear why.

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.

No reason beyond keeping the default read free of absent keys in the schema, which one serializer with optional fields describes just as well. Gone in 8ef03ef: the read is a single authoring_grading.CourseGradingRead.v3 whose five view=full fields are required=False and say they are present only with view=full; ANY_OF_COMPONENTS, its post-processing and OverlappingShapesTest are removed, so cms/lib/spectacular.py differs from master only in SUPERSEDED_PATHS. test_reads_match_the_published_shapes checks the default read has exactly the four policy keys and the full read all nine against that one component.

authz_permission = COURSES_VIEW_GRADING_SETTINGS.identifier


class CanEditGradingSettings(_GradingSettingsPermission):

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.

nit: Use LegacyAuthoringPermission.WRITE as the fallback for the edit permission. Studio has no read-only course access today so this doesn't change who gets in, but the fallback should say what the permission means.

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.

Done in 8ef03ef: each permission class names its fallback, READ for the view and LegacyAuthoringPermission.WRITE for the edit. test_each_operation_falls_back_to_its_own_studio_access withholds each Studio access level in turn and expects the matching 403, since course roles grant both together.

Taimoor Ahmed and others added 4 commits November 10, 2026 18:41
Authoring v3 could only write the grading policy, so every caller still
read it through v1. v3 now answers GET with the four-field policy, and
with ?view=full adds v1's five derived fields under their v1 names.

PATCH validates its body and applies partial updates. A body with all
four keys takes exactly the previous path. Other bodies change only the
fields sent and never re-send graders, so stored weights cannot drift.
Bodies that used to fail with 500, some after writing corrupt data, now
get 400 with nothing written. Permissions move into per-action classes
with the same checks, fallback and 404-before-403 order. v1 and v0
grading are marked deprecated in the CMS schema.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Docstring-only markers naming the v3 successor and DEPR openedx#39128. No
statement, decorator or import changes; with docstrings stripped the
modules match the base.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The v3 partial update kept a second, lenient serializer so that every
body master's PATCH accepted stayed accepted: null cutoffs, any JSON
type for a grader's type or label, and an empty string as the credit
minimum. That endpoint has shipped in no named release, so there is no
released contract to keep. One strict request serializer now validates
every body: cutoff values and the credit minimum must be finite JSON
numbers, grader types and labels strings, and graders a list. The
guarantee is that whatever a read returns, sending it back is accepted
and changes nothing, tested on six stored shapes on both mounts. The
227-body replay against v0 and the lenient fields are removed.
… grading

The viewset no longer overrides the authentication classes, so a session
from an account that is not yet activated is refused like everywhere
else in the authoring APIs. Only JSON bodies are parsed, so a form body
gets the same 415 as any other unsupported type instead of a 400 from
the serializer.

The read is one serializer whose view=full fields are optional, in place
of two shapes published through a oneOf rewritten to anyOf by a schema
hook; the hook and its tests go. The edit permission falls back to
Studio write access, which says what it means even though Studio grants
course read and write together.

The v1 and v0 deprecation notes now say which bodies v3 refuses that
those endpoints still store.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

open-source-contribution PR author is not from Axim or 2U

Projects

Status: In Eng Review

Development

Successfully merging this pull request may close these issues.

4 participants