lms.djangoapps.program_enrollments.api package

lms.djangoapps.program_enrollments.api package#

Submodules#

lms.djangoapps.program_enrollments.api.grades module#

Python API functions related to reading program-course grades.

Outside of this subpackage, import these functions from lms.djangoapps.program_enrollments.api.

class lms.djangoapps.program_enrollments.api.grades.BaseProgramCourseGrade(program_course_enrollment)#

Bases: object

Base for either a courserun grade or grade-loading failure.

Can be passed to ProgramCourseGradeResultSerializer.

is_error = None#
class lms.djangoapps.program_enrollments.api.grades.ProgramCourseGradeError(program_course_enrollment, exception=None)#

Bases: BaseProgramCourseGrade

Represents a failure to load a courserun grade for a user enrolled through a program.

is_error = True#
class lms.djangoapps.program_enrollments.api.grades.ProgramCourseGradeOk(program_course_enrollment, course_grade)#

Bases: BaseProgramCourseGrade

Represents a courserun grade for a user enrolled through a program.

is_error = False#
lms.djangoapps.program_enrollments.api.grades.iter_program_course_grades(program_uuid, course_key, paginate_queryset_fn=None)#

Load grades (or grading errors) for a given program-course.

Parameters:

  • program_uuid (str)

  • course_key (CourseKey)

  • paginate_queryset_fn (QuerySet -> QuerySet) – Optional function to paginate the results, generally passed in from self.request.paginate_queryset on a paginated DRF APIView. If None, all results will be loaded and returned.

Returns: generator[BaseProgramCourseGrade]

lms.djangoapps.program_enrollments.api.linking module#

Python API function to link program enrollments and external_user_keys to an LMS user.

Outside of this subpackage, import these functions from lms.djangoapps.program_enrollments.api.

Attempts to link the given program enrollment to the given user If the enrollment has any program course enrollments, enroll the user in those courses as well

Raises: CourseEnrollmentException if there is an error enrolling user in a waiting

program course enrollment IntegrityError if we try to create invalid records.

Utility function to link ProgramEnrollments to LMS Users

Parameters:

  • -program_uuid – the program for which we are linking program enrollments

  • -external_keys_to_usernames – dict mapping external_user_keys to LMS usernames.

Returns: dict[str: str]

Map from external keys to errors, for the external keys of users whose linking produced errors.

Raises: ValueError if None is included in external_keys_to_usernames

This function will look up program enrollments and users, and update the program enrollments with the matching user. If the program enrollment has course enrollments, we will enroll the user into their waiting program courses.

For each external_user_key:lms_username, if:

  • The user is not found

  • No enrollment is found for the given program and external_user_key

  • The enrollment already has a user and that user is the same as the given user

An error message will be logged, and added to a dictionary of error messages keyed by external_key. The input will be skipped. All other inputs will be processed and enrollments updated, and then the function will return the dictionary of error messages.

For each external_user_key:lms_username, if the enrollment already has a user, but that user is different than the requested user, we do the following. We unlink the existing user from the program enrollment and link the requested user to the program enrollment. This is accomplished by removing the existing user’s link to the program enrollment. If the program enrollment has course enrollments, then we unenroll the user. If there is an audit track in the course, we also move the enrollment into the audit track. We also remove the association between those course enrollments and the program course enrollments. The requested user is then linked to the program following the above logic.

If there is an error while enrolling a user in a waiting program course enrollment, the error will be logged, and added to the returned error dictionary, and we will roll back all transactions for that user so that their db state will be the same as it was before this function was called, to prevent program enrollments to be in a state where they have an LMS user but still have waiting course enrollments. All other inputs will be processed normally.

Unlinks CourseEnrollments from the ProgramEnrollment by doing the following for each ProgramCourseEnrollment associated with the Program Enrollment.

  1. unenrolling the corresponding user from the course

  2. moving the user into the audit track, if the track exists

  3. removing the link between the ProgramCourseEnrollment and the CourseEnrollment

Parameters:

program_enrollment – the ProgramEnrollment object

lms.djangoapps.program_enrollments.api.reading module#

Python API functions related to reading program enrollments.

Outside of this subpackage, import these functions from lms.djangoapps.program_enrollments.api.

lms.djangoapps.program_enrollments.api.reading.fetch_program_course_enrollments(program_uuid, course_key, curriculum_uuids=None, users=None, external_user_keys=None, program_enrollment_statuses=None, program_enrollments=None, active_only=False, inactive_only=False, realized_only=False, waiting_only=False)#

Fetch program-course enrollments for a specific program and course run.

Required argument:

  • program_uuid (UUID|str)

  • course_key (CourseKey|str)

Optional arguments:

  • curriculum_uuids (iterable[UUID|str])

  • users (iterable[User])

  • external_user_keys (iterable[str])

  • program_enrollment_statuses (iterable[str])

  • program_enrollments (iterable[ProgramEnrollment])

  • active_only (bool)

  • inactive_only (bool)

  • realized_only (bool)

  • waiting_only (bool)

Optional arguments are used as filtersets if they are not None. At most one of (realized_only, waiting_only) may be provided. At most one of (active_only, inactive_only) may be provided.

Returns: queryset[ProgramCourseEnrollment]

lms.djangoapps.program_enrollments.api.reading.fetch_program_course_enrollments_by_students(users=None, external_user_keys=None, program_uuids=None, curriculum_uuids=None, course_keys=None, program_enrollment_statuses=None, active_only=False, inactive_only=False, realized_only=False, waiting_only=False)#

Fetch program-course enrollments for a specific list of students.

Required arguments (at least one must be provided):

  • users (iterable[User])

  • external_user_keys (iterable[str])

Optional arguments:

  • provided_uuids (iterable[UUID|str])

  • curriculum_uuids (iterable[UUID|str])

  • course_keys (iterable[CourseKey|str])

  • program_enrollment_statuses (iterable[str])

  • realized_only (bool)

  • waiting_only (bool)

Optional arguments are used as filtersets if they are not None. At most one of (realized_only, waiting_only) may be provided. At most one of (active_only, inactive_only) may be provided.

Returns: queryset[ProgramCourseEnrollment]

lms.djangoapps.program_enrollments.api.reading.fetch_program_enrollments(program_uuid, curriculum_uuids=None, users=None, external_user_keys=None, program_enrollment_statuses=None, realized_only=False, waiting_only=False)#

Fetch program enrollments for a specific program.

Required argument:

  • program_uuid (UUID|str)

Optional arguments:

  • curriculum_uuids (iterable[UUID|str])

  • users (iterable[User])

  • external_user_keys (iterable[str])

  • program_enrollment_statuses (iterable[str])

  • realized_only (bool)

  • waiting_only (bool)

Optional arguments are used as filtersets if they are not None. At most one of (realized_only, waiting_only) may be provided.

Returns: queryset[ProgramEnrollment]

lms.djangoapps.program_enrollments.api.reading.fetch_program_enrollments_by_student(user=None, external_user_key=None, program_uuids=None, curriculum_uuids=None, program_enrollment_statuses=None, realized_only=False, waiting_only=False)#

Fetch program enrollments for a specific student.

Required arguments (at least one must be provided):

  • user (User)

  • external_user_key (str)

Optional arguments:

  • provided_uuids (iterable[UUID|str])

  • curriculum_uuids (iterable[UUID|str])

  • program_enrollment_statuses (iterable[str])

  • realized_only (bool)

  • waiting_only (bool)

Optional arguments are used as filtersets if they are not None. At most one of (realized_only, waiting_only) may be provided.

Returns: queryset[ProgramEnrollment]

lms.djangoapps.program_enrollments.api.reading.fetch_program_enrollments_by_students(users=None, external_user_keys=None, program_enrollment_statuses=None, realized_only=False, waiting_only=False)#

Fetch program enrollments for a specific list of students.

Required arguments (at least one must be provided):

  • users (iterable[User])

  • external_user_keys (iterable[str])

Optional arguments:

  • program_enrollment_statuses (iterable[str])

  • realized_only (bool)

  • waiting_only (bool)

Optional arguments are used as filtersets if they are not None.

Returns: queryset[ProgramEnrollment]

lms.djangoapps.program_enrollments.api.reading.get_external_key_by_user_and_course(user, course_key)#

Returns the external_user_key of the edX account/user enrolled into the course

Parameters:

  • user (User) – The edX account representing the user in auth_user table

  • course_key (CourseKey|str) – The course key of the course user is enrolled in

Returns: external_user_key (str|None)

The external user key provided by Masters degree provider Or None if cannot find edX user to Masters learner mapping

lms.djangoapps.program_enrollments.api.reading.get_org_key_for_program(program_uuid)#

Return the key of the first Organization administering the given program.

Parameters:

program_uuid (UUID|str)

Returns: org_key (str)

Raises:
lms.djangoapps.program_enrollments.api.reading.get_program_course_enrollment(program_uuid, course_key, user=None, external_user_key=None, curriculum_uuid=None)#

Get a single program-course enrollment.

Required arguments:

  • program_uuid (UUID|str)

  • course_key (CourseKey|str)

  • At least one of:

    • user (User)

    • external_user_key (str)

Optional arguments:

  • curriculum_uuid (UUID|str) [optional]

Returns: ProgramCourseEnrollment

Raises:

  • * ProgramCourseEnrollment.DoesNotExist –

  • * ProgramCourseEnrollment.MultipleObjectsReturned –

lms.djangoapps.program_enrollments.api.reading.get_program_enrollment(program_uuid, user=None, external_user_key=None, curriculum_uuid=None)#

Get a single program enrollment.

Required arguments:

  • program_uuid (UUID|str)

  • At least one of:

    • user (User)

    • external_user_key (str)

Optional arguments:

  • curriculum_uuid (UUID|str) [optional]

Returns: ProgramEnrollment

Raises: ProgramEnrollment.DoesNotExist, ProgramEnrollment.MultipleObjectsReturned

lms.djangoapps.program_enrollments.api.reading.get_provider_slug(provider_config)#

Returns slug identifying a SAML provider.

Parameters:

provider_config – SAMLProvider

Returns: str

lms.djangoapps.program_enrollments.api.reading.get_saml_providers_by_org_key(org_key)#

Returns a list of SAML providers associated with the provided org_key. In most cases an organization will only have one configured provider. However, multiple may be returned during a migration between two active providers.

Parameters:

org_key (str)

Returns: list[SAMLProvider]

Raises:

BadOrganizationShortNameException –

lms.djangoapps.program_enrollments.api.reading.get_saml_providers_for_organization(organization)#

Return currently configured SAML provider(s) for the given Organization. In most cases an organization will only have one configured provider. However, multiple may be returned during a migration between two active providers.

Parameters:

organization – Organization

Returns: list[SAMLProvider]

Raises:

ProviderDoesNotExistsException –

lms.djangoapps.program_enrollments.api.reading.get_users_by_external_keys(program_uuid, external_user_keys)#

Given a program and a set of external keys, return a dict from external user keys to Users.

Parameters:

  • program_uuid (UUID|str) – uuid for program these users is/will be enrolled in

  • external_user_keys (sequence[str]) – external user keys used by the program creator’s IdP.

Returns: dict[str: User|None]

A dict mapping external user keys to Users. If an external user key is not registered, then None is returned instead

of a User for that key.

Raises:
lms.djangoapps.program_enrollments.api.reading.get_users_by_external_keys_and_org_key(external_user_keys, org_key)#

Given an organization_key and a set of external keys, return a dict from external user keys to Users.

Parameters:

  • external_user_keys (sequence[str]) – external user keys used by the program creator’s IdP.

  • org_key (str) – The organization short name of which the external_user_key belongs to

Returns: dict[str: User|None]

A dict mapping external user keys to Users. If an external user key is not registered, then None is returned instead

of a User for that key.

Raises:
lms.djangoapps.program_enrollments.api.reading.is_course_staff_enrollment(program_course_enrollment)#

Returns whether the provided program_course_enrollment have the course staff role on the course.

Parameters:

program_course_enrollment – ProgramCourseEnrollment

returns: bool

lms.djangoapps.program_enrollments.api.reading.remove_prefix(text, prefix)#

lms.djangoapps.program_enrollments.api.writing module#

Python API functions related to writing program enrollments.

Outside of this subpackage, import these functions from lms.djangoapps.program_enrollments.api.

lms.djangoapps.program_enrollments.api.writing.change_program_course_enrollment_status(program_course_enrollment, new_status)#

Update a program course enrollment with a new status.

If program_course_enrollment is realized with a CourseEnrollment, then also update that.

Parameters:
Returns: str

String from ProgramOperationCourseStatuses.

lms.djangoapps.program_enrollments.api.writing.change_program_enrollment_status(program_enrollment, new_status)#

Update a program enrollment with a new status.

Parameters:

  • program_enrollment (ProgramEnrollment)

  • status (str) – from ProgramCourseEnrollmentStatuses

Returns: str

String from ProgramOperationStatuses.

lms.djangoapps.program_enrollments.api.writing.create_program_course_enrollment(program_enrollment, course_key, status, save=True)#

Create a program course enrollment.

If program_enrollment is realized (i.e., has a non-null User), then also create a course enrollment.

Parameters:

  • program_enrollment (ProgramEnrollment)

  • course_key (CourseKey|str)

  • status (str) – from ProgramCourseEnrollmentStatuses

  • save (bool) – Whether to save the created ProgamCourseEnrollment. Defaults to True. One may set this to False in order to bulk-create the enrollments. Note that if a CourseEnrollment is created, it will be saved regardless of this value.

Returns: ProgramCourseEnrollment

Raises: NonExistentCourseError

lms.djangoapps.program_enrollments.api.writing.create_program_enrollment(program_uuid, curriculum_uuid, user, external_user_key, status, save=True)#

Create a program enrollment.

Parameters:

  • program_uuid (UUID|str)

  • curriculum_uuid (str)

  • user (User)

  • external_user_key (str)

  • status (str) – from ProgramEnrollmentStatuses

  • save (bool) – Whether to save the created ProgamEnrollment. Defaults to True. One may set this to False in order to bulk-create the enrollments.

Returns: ProgramEnrollment

lms.djangoapps.program_enrollments.api.writing.enroll_in_masters_track(user, course_key, status)#

Ensure that the user is enrolled in the Master’s track of course. Either creates or updates a course enrollment.

Parameters:

  • user (User)

  • course_key (CourseKey|str)

  • status (str) – from ProgramCourseEnrollmentStatuses

Returns: CourseEnrollment

Raises: NonExistentCourseError

lms.djangoapps.program_enrollments.api.writing.write_program_course_enrollments(program_uuid, course_key, enrollment_requests, create, update)#

Bulk create/update a set of program-course enrollments.

Parameters:

  • program_uuid (UUID|str)

  • enrollment_requests (list[dict]) – dicts in the form: * ‘external_user_key’: str * ‘status’: str from ProgramCourseEnrollmentStatuses * ‘course_staff’: Boolean if the user should have the CourseStaff role

  • create (bool) – non-existent enrollments will be created iff create, otherwise they will be skipped as ‘duplicate’.

  • update (bool) – existing enrollments will be updated iff update, otherwise they will be skipped as ‘not-in-program’

At least one of create or update must be True.

Returns: dict[str: str]

Mapping of external user keys to strings from ProgramCourseOperationStatuses.

lms.djangoapps.program_enrollments.api.writing.write_program_enrollments(program_uuid, enrollment_requests, create, update)#

Bulk create/update a set of program enrollments.

Parameters:

  • program_uuid (UUID|str)

  • enrollment_requests (list[dict]) – dicts in the form: * ‘external_user_key’: str * ‘status’: str from ProgramEnrollmentStatuses * ‘curriculum_uuid’: str, omittable if create==False.

  • create (bool) – non-existent enrollments will be created iff create, otherwise they will be skipped as ‘duplicate’.

  • update (bool) – existing enrollments will be updated iff update, otherwise they will be skipped as ‘not-in-program’

At least one of create or update must be True.

Returns: dict[str: str]

Mapping of external user keys to strings from ProgramOperationStatuses.

Module contents#

Python API exposed by the program_enrollments app to other in-process apps.

The functions are split into separate files for code organization, but they are imported into here so they can be imported directly from lms.djangoapps.program_enrollments.api.

When adding new functions to this API, add them to the appropriate module within the /api/ folder, and then “expose” them here by importing them.

We use explicit imports here because (1) it hides internal variables in the sub-modules and (2) it provides a nice catalog of functions for someone using this API.