enterprise.api package

Contents

enterprise.api package#

Subpackages#

Submodules#

enterprise.api.filters module#

Filters for enterprise API.

class enterprise.api.filters.EnterpriseCourseEnrollmentFilterBackend#

Bases: BaseFilterBackend

Filter backend to return enrollments under the user’s enterprise(s) only.

  • Staff users will bypass this filter.

  • Non-staff users will receive enrollments under their linked enterprises, only if they have the enterprise.can_enroll_learners permission.

  • Non-staff users without the enterprise.can_enroll_learners permission will receive only their own enrollments.

filter_queryset(request, queryset, view)#

Filter out enrollments if learner is not linked

class enterprise.api.filters.EnterpriseCustomerInviteKeyFilterBackend#

Bases: BaseFilterBackend

Filter backend to return invite keys under the user’s enterprise(s) only. Supports filtering by enterprise_customer_uuid.

  • Staff users will bypass this filter.

filter_queryset(request, queryset, view)#

Return a filtered queryset.

class enterprise.api.filters.EnterpriseCustomerUserFilterBackend#

Bases: BaseFilterBackend

Allow filtering on the enterprise customer user api endpoint.

filter_queryset(request, queryset, view)#

Apply incoming filters only if user is staff. If not, only filter by user’s ID.

class enterprise.api.filters.EnterpriseLinkedUserFilterBackend#

Bases: BaseFilterBackend

Filter backend to return user’s linked enterprises only

  • Staff users will bypass this filter.

  • Non-staff users will receive only their linked enterprises.

filter_queryset(request, queryset, view)#

Filter out enterprise customer if learner is not linked

class enterprise.api.filters.UserFilterBackend#

Bases: BaseFilterBackend

Filter backend for any view that needs to filter against the requesting user’s ID.

  • Staff users will bypass this filter.

  • Non-staff users will receive only those objects that match their own user ID.

This requires that USER_ID_FILTER be set in the view as a class variable, to identify the object’s relationship to a user ID.

filter_queryset(request, queryset, view)#

Filter only for the user’s ID if non-staff.

enterprise.api.pagination module#

Pagination helpers for enterprise api.

class enterprise.api.pagination.PaginationWithFeatureFlags#

Bases: DefaultPagination

Adds a features dictionary to the default paginated response provided by edx_rest_framework_extensions. The features dict represents a collection of Waffle-based feature flags/samples/switches that may be used to control whether certain aspects of the system are enabled or disabled (e.g., feature flag turned on for all staff users but not turned on for real customers/learners).

get_paginated_response(data)#

Modifies the default paginated response to include enterprise_features dict.

Parameters:

  • self – PaginationWithFeatureFlags instance.

  • data (dict) – Results for current page.

Returns:

DRF response object containing enterprise_features dict.

Return type:

(Response)

enterprise.api.pagination.get_paginated_response(data, request)#

Update pagination links in course catalog data and return DRF Response.

Parameters:

  • data (dict) – Dictionary containing catalog courses.

  • request (HttpRequest) – Current request object.

Returns:

DRF response object containing pagination links.

Return type:

(Response)

enterprise.api.throttles module#

Throttle classes for enterprise API.

class enterprise.api.throttles.BaseThrottle#

Bases: UserRateThrottle

Base throttle class with common functionality.

allow_request(request, view)#

Modify throttling for service users.

Updates throttling rate if the request is coming from the service user, and defaults to UserRateThrottle’s configured setting otherwise.

Updated throttling rate comes from DEFAULT_THROTTLE_RATES key in REST_FRAMEWORK setting. specific user throttling is specified in DEFAULT_THROTTLE_RATES by it’s corresponding key.

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_RATES': {
        'service_user': '50/day',
        'high_service_user': '2000/minute',
    }
}
get_scope()#

Get the scope of the throttle.

Raises:

NotImplementedError – Must be implemented by subclasses

update_throttle_scope()#

Update throttle scope based on the specific subclass.

class enterprise.api.throttles.HighServiceUserThrottle#

Bases: BaseThrottle

A throttle for high service users.

get_scope()#

Get the scope of the throttle.

Returns:

The scope of the throttle.

Return type:

str

class enterprise.api.throttles.ServiceUserThrottle#

Bases: BaseThrottle

A throttle allowing the service user to override rate limiting.

get_scope()#

Get the scope of the throttle.

Returns:

The scope of the throttle.

Return type:

str

enterprise.api.urls module#

URL definitions for enterprise API endpoint.

enterprise.api.utils module#

Utility functions for the Enterprise API.

class enterprise.api.utils.CourseRunProgressStatuses#

Bases: object

Class to group statuses that a course run can be in with respect to user progress.

COMPLETED = 'completed'#
IN_PROGRESS = 'in_progress'#
SAVED_FOR_LATER = 'saved_for_later'#
UNENROLLED = 'unenrolled'#
UPCOMING = 'upcoming'#
enterprise.api.utils.assign_feature_roles(user)#

Add the ENTERPRISE_DASHBOARD_ADMIN_ROLE, ENTERPRISE_REPORTING_CONFIG_ADMIN_ROLE, ENTERPRISE_CATALOG_ADMIN_ROLE feature roles if the user does not already have them

enterprise.api.utils.create_message_body(email, enterprise_name, number_of_codes=None, notes=None)#

Return the message body with extra information added by user.

enterprise.api.utils.create_pending_invites(enterprise_customer: EnterpriseCustomer, emails_to_invite: List[str]) → List[PendingEnterpriseCustomerAdminUser]#

Create pending admin invitations and trigger email notifications.

Creates PendingEnterpriseCustomerAdminUser records for new admin invites and enqueues Braze email tasks to be sent after transaction commits.

Parameters:

  • enterprise_customer – The enterprise customer instance.

  • emails_to_invite – List of normalized email addresses to invite.

Returns:

List of created PendingEnterpriseCustomerAdminUser instances.

Raises:

  • DatabaseError – If database operation fails.

  • ValueError – If emails_to_invite is empty.

  • RuntimeError – If called outside a transaction.atomic block.

Note

  • Caller must wrap in transaction.atomic() to ensure atomicity

  • Uses get_or_create per email to avoid duplicate invite emails in race conditions

  • Emails are queued via transaction.on_commit() to send after transaction commits

  • Emails are routed to different Braze campaigns based on EnterpriseCustomerUser existence determined at invite creation time (before transaction commits)

  • This ensures emails only send if database changes succeed

Example

>>> with transaction.atomic():
...     invites = create_pending_invites(customer, ['new@example.com'])
>>> len(invites) > 0
True
enterprise.api.utils.delta_format(current, prior)#

Formate delta of the given numbers.

If the delta is positive, number is ‘+10’. If negative, change nothing, it will come through as ‘-10’ by default.

enterprise.api.utils.generate_prompt_for_learner_engagement_summary(engagement_data)#

Generate an OpenAI prompt to get the summary of learner engagement from engagement data.

Parameters:

engagement_data (dict) – A dictionary containing learner engagement numbers for some enterprise customer.

Returns:

OpenAI prompt for getting engagement summary.

Return type:

(str)

enterprise.api.utils.generate_prompt_for_learner_progress_summary(progress_data)#

Generate an OpenAI prompt to get the summary of learner progress from progress data.

Parameters:

progress_data (dict) – A dictionary containing learner progress numbers for some enterprise customer.

Returns:

OpenAI prompt for getting learner progress summary.

Return type:

(str)

enterprise.api.utils.get_ent_cust_from_enterprise_customer_key(enterprise_customer_key)#

Get the enterprise customer id given an enterprise customer key.

enterprise.api.utils.get_ent_cust_from_report_config_uuid(uuid)#

Get the enterprise customer id given an enterprise report configuration UUID.

enterprise.api.utils.get_enterprise_customer_from_catalog_id(catalog_id)#

Get the enterprise customer id given an enterprise customer catalog id.

enterprise.api.utils.get_enterprise_customer_from_enterprise_group_id(group_id)#

Get the enterprise customer id given an enterprise customer group id.

enterprise.api.utils.get_enterprise_customer_from_user_id(user_id)#

Get the enterprise customer id given an user id

enterprise.api.utils.get_existing_admin_emails(enterprise_customer: EnterpriseCustomer) → Set[str]#

Retrieve normalized email addresses of existing ACTIVE enterprise admins.

Only includes admins who have: 1. An EnterpriseCustomerAdmin record 2. An active EnterpriseCustomerUser (active=True)

Parameters:

enterprise_customer – The enterprise customer instance.

Returns:

Set of lowercased email addresses of active admins.

Raises:

DatabaseError – If database query fails.

Example

>>> emails = get_existing_admin_emails(customer)
>>> 'admin@example.com' in emails
True
enterprise.api.utils.get_existing_pending_emails(enterprise_customer: EnterpriseCustomer, normalized_emails: List[str]) → Set[str]#

Retrieve normalized email addresses of pending admin invitations.

Parameters:

  • enterprise_customer – The enterprise customer instance.

  • normalized_emails – List of normalized email addresses to check.

Returns:

Set of lowercased email addresses that have pending invitations.

Raises:

DatabaseError – If database query fails.

Example

>>> pending = get_existing_pending_emails(customer, ['user@example.com'])
>>> 'user@example.com' in pending
True
enterprise.api.utils.get_invite_status(email: str, existing_admin_emails: Set[str], existing_pending_emails: Set[str]) → str#

Determine the invitation status for a given email address.

Parameters:

  • email (str) – The email address to check.

  • existing_admin_emails (Set[str]) – Set of existing active admin email addresses.

  • existing_pending_emails (Set[str]) – Set of pending invitation email addresses.

Returns:

Status constant indicating email state:

  • AdminInviteStatus.EXISTING_ADMIN if user is already an active admin

  • AdminInviteStatus.PENDING_INVITE if invitation already sent

  • AdminInviteStatus.NEW_INVITE if this is a new invitation

Return type:

str

Example

>>> status = get_invite_status('new@example.com', set(), set())
>>> status == 'invite sent'
True
enterprise.api.utils.get_service_usernames()#

Return the set of service usernames that are given extended permissions in the API.

enterprise.api.utils.has_api_credentials_enabled(enterprise_uuid)#

Check whether the enterprise customer can access to api credentials or not

enterprise.api.utils.percentage_format(number)#

Turn float representation of percentage into a cleaner format (0.89 -> 89%)

Parameters:

number (float) – Floating point number to format.

Returns:

String representation of the float in percentage form.

Return type:

(str)

enterprise.api.utils.set_application_name_from_user_id(user_id)#

Get the enterprise customer user’s name given a user id.

Module contents#

Python API for various enterprise functionality.

enterprise.api.activate_admin_permissions(enterprise_customer_user)#

Activates admin permissions for an existing PendingEnterpriseCustomerAdminUser.

Specifically, the “enterprise_admin” system-wide role is assigned to the user and the PendingEnterpriseCustomerAdminUser record is removed.

Requires an EnterpriseCustomerUser record to exist which ensures the user already has the “enterprise_learner” role as a prerequisite.

Parameters:

enterprise_customer_user – an EnterpriseCustomerUser instance

Contents