openedx.core.djangoapps.user_api.preferences package

openedx.core.djangoapps.user_api.preferences package#

Submodules#

openedx.core.djangoapps.user_api.preferences.api module#

API for managing user preferences.

openedx.core.djangoapps.user_api.preferences.api.create_user_preference_serializer(user, preference_key, preference_value)#

Creates a serializer for the specified user preference.

Parameters:

  • user (User) – The user whose preference is being serialized.

  • preference_key (str) – The key for the user preference.

  • preference_value (str) – The value to be stored. Non-string values will be converted to strings.

Returns:

A serializer that can be used to save the user preference.

openedx.core.djangoapps.user_api.preferences.api.delete_user_preference(requesting_user, preference_key, username=None)#

Deletes a user preference on behalf of a requesting user.

Note

It is up to the caller of this method to enforce the contract that this method is only called with the user who made the request.

Parameters:

  • requesting_user (User) – The user requesting to delete the preference. Only the user with username ‘username’ has permissions to delete their own preference.

  • preference_key (str) – The key for the user preference.

  • username (str) – Optional username specifying which account should be updated. If not specified, requesting_user.username is assumed.

Returns:

True if the preference was deleted, False if the user did not have a preference with the supplied key.

Raises:

  • UserNotFound – no user with username username exists (or requesting_user.username if username is not specified)

  • UserNotAuthorized – the requesting_user does not have access to change the account associated with username

  • PreferenceUpdateError – the operation failed when performing the update.

  • UserAPIInternalError – the operation failed due to an unexpected error.

openedx.core.djangoapps.user_api.preferences.api.get_country_time_zones(country_code=None)#

Returns a sorted list of time zones commonly used in the specified country. If country_code is None (or unrecognized), or if the country has no defined time zones, return a list of all time zones.

Parameters:

country_code (str) – ISO 3166-1 Alpha-2 country code

openedx.core.djangoapps.user_api.preferences.api.get_user_preference(requesting_user, preference_key, username=None)#

Returns the value of the user preference with the specified key.

Parameters:

  • requesting_user (User) – The user requesting the user preferences. Only the user with username username or users with “is_staff” privileges can access the preferences.

  • preference_key (str) – The key for the user preference.

  • username (str) – Optional username for which to look up the preferences. If not specified, requesting_user.username is assumed.

Returns:

The value for the user preference which is always a string, or None if a preference has not been specified.

Raises:

  • UserNotFound – no user with username username exists (or requesting_user.username if username is not specified)

  • UserNotAuthorized – the requesting_user does not have access to the user preference.

  • UserAPIInternalError – the operation failed due to an unexpected error.

openedx.core.djangoapps.user_api.preferences.api.get_user_preferences(requesting_user, username=None)#

Returns all user preferences as a JSON response.

Parameters:

  • requesting_user (User) – The user requesting the user preferences. Only the user with username username or users with “is_staff” privileges can access the preferences.

  • username (str) – Optional username for which to look up the preferences. If not specified, requesting_user.username is assumed.

Returns:

A dict containing account fields.

Raises:

  • UserNotFound – no user with username username exists (or requesting_user.username if username is not specified)

  • UserNotAuthorized – the requesting_user does not have access to the user preference.

  • UserAPIInternalError – the operation failed due to an unexpected error.

openedx.core.djangoapps.user_api.preferences.api.has_user_preference(requesting_user, preference_key, username=None)#

Returns True if the user has preference with the specified key.

Parameters:

  • requesting_user (User) – The user requesting the user preference check. Only the user with username username or users with “is_staff” privileges can access the preferences.

  • preference_key (str) – The key for the user preference.

  • username (str) – Optional username for which to look up the preferences. If not specified, requesting_user.username is assumed.

Returns:

Returns True if the user has preference with the specified key and False otherwise.

Return type:

(bool)

Raises:

  • UserNotFound – no user with username username exists (or requesting_user.username if username is not specified)

  • UserNotAuthorized – the requesting_user does not have access to the user preference.

  • UserAPIInternalError – the operation failed due to an unexpected error.

openedx.core.djangoapps.user_api.preferences.api.set_user_preference(requesting_user, preference_key, preference_value, username=None)#

Update a user preference for the given username.

Note

It is up to the caller of this method to enforce the contract that this method is only called with the user who made the request.

Parameters:

  • requesting_user (User) – The user requesting to modify account information. Only the user with username ‘username’ has permissions to modify account information.

  • preference_key (str) – The key for the user preference.

  • preference_value (str) – The value to be stored. Non-string values are converted to strings.

  • username (str) – Optional username specifying which account should be updated. If not specified, requesting_user.username is assumed.

Raises:
openedx.core.djangoapps.user_api.preferences.api.update_email_opt_in(user, org, opt_in)#

Updates a user’s preference for receiving org-wide emails.

Sets a User Org Tag defining the choice to opt in or opt out of organization-wide emails.

Parameters:

  • user (User) – The user to set a preference for.

  • org (str) – The org is used to determine the organization this setting is related to.

  • opt_in (bool) – True if the user is choosing to receive emails for this organization. If the user requires parental consent then email-optin is set to False regardless.

Returns:

None

Raises:

UserNotFound – no user profile exists for the specified user.

openedx.core.djangoapps.user_api.preferences.api.update_user_preferences(requesting_user, update, user=None)#

Update the user preferences for the given user.

Note

It is up to the caller of this method to enforce the contract that this method is only called with the user who made the request.

Parameters:

  • requesting_user (User) – The user requesting to modify account information. Only the user with username ‘username’ has permissions to modify account information.

  • update (dict) –

    The updated account field values. Some notes:

    Values are expected to be strings. Non-string values will be converted to strings. Null values for a preference will be treated as a request to delete the key in question.

  • user (str/User) – Optional, either username string or user object specifying which account should be updated. If not specified, requesting_user.username is assumed.

Raises:
openedx.core.djangoapps.user_api.preferences.api.validate_user_preference_serializer(serializer, preference_key, preference_value)#

Validates a user preference serializer.

Parameters:

  • serializer (UserPreferenceSerializer) – The serializer to be validated.

  • preference_key (str) – The key for the user preference.

  • preference_value (str) – The value to be stored. Non-string values will be converted to strings.

Raises:

PreferenceValidationError – the supplied key and/or value for a user preference are invalid.

openedx.core.djangoapps.user_api.preferences.views module#

An API for retrieving user preference information.

For additional information and historical context, see: https://openedx.atlassian.net/wiki/display/TNL/User+API

class openedx.core.djangoapps.user_api.preferences.views.PreferencesDetailView(**kwargs)#

Bases: APIView

Use Cases

Get, create, update, or delete a specific user preference.

Example Requests

GET /api/user/v1/preferences/{username}/{preference_key}

PUT /api/user/v1/preferences/{username}/{preference_key}

DELETE /api/user/v1/preferences/{username}/{preference_key}

Response Values for GET

If the specified username or preference does not exist, an HTTP 404 “Not Found” response is returned.

If a user without “is_staff” access requests preferences for a different user, a 404 error is returned.

If the user makes the request for her own account, or makes a request for another account and has “is_staff” access, an HTTP 200 “OK” response is returned that contains a JSON string.

Response Values for PUT

Users can only modify their own preferences. If the requesting user does not have the specified username and has staff access, the request returns an HTTP 403 “Forbidden” response. If the requesting user does not have staff access, the request returns an HTTP 404 “Not Found” response to avoid revealing the existence of the account.

If the specified preference does not exist, an HTTP 404 “Not Found” response is returned.

If the request is successful, a 204 “No Content” status is returned with no additional content.

Response Values for DELETE

Users can only delete their own preferences. If the requesting user does not have the specified username and has staff access, the request returns an HTTP 403 “Forbidden” response. If the requesting user does not have staff access, the request returns an HTTP 404 “Not Found” response to avoid revealing the existence of the account.

If the specified preference does not exist, an HTTP 404 “Not Found” response is returned.

If the update is successful, an HTTP 204 “No Content” response is returned with no additional content.

authentication_classes = (<class 'openedx.core.lib.api.authentication.BearerAuthenticationAllowInactiveUser'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>)#
delete(request, username, preference_key)#

DELETE /api/user/v1/preferences/{username}/{preference_key}

get(request, username, preference_key)#

GET /api/user/v1/preferences/{username}/{preference_key}

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx.core.lib.api.permissions.IsUserInUrlOrStaff'>)#
put(request, username, preference_key)#

PUT /api/user/v1/preferences/{username}/{preference_key}

class openedx.core.djangoapps.user_api.preferences.views.PreferencesView(**kwargs)#

Bases: APIView

Use Cases

Get or update the user’s preference information. Updates are only supported through merge patch. Preference values of null in a patch request are treated as requests to remove the preference.

Example Requests

GET /api/user/v1/preferences/{username}/

PATCH /api/user/v1/preferences/{username}/ with content_type “application/merge-patch+json”

Response Values for GET

If no user exists with the specified username, an HTTP 404 “Not Found” response is returned.

If a user without “is_staff” access requests preferences for a different user, an HTTP 404 “Not Found” message is returned.

If the user makes the request for her own account, or makes a request for another account and has “is_staff” access, an HTTP 200 “OK” response is returned. The response contains a JSON dictionary with a key/value pair (of type String) for each preference.

The list of preferences depends on your implementation. By default, the list includes the following preferences.

  • account_privacy: The user’s setting for sharing her personal profile. Possible values are “all_users” or “private”.

  • pref-lan: The user’s preferred language, as set in account settings.

Response Values for PATCH

Users can only modify their own preferences. If the requesting user does not have the specified username and has staff access, the request returns an HTTP 403 “Forbidden” response. If the requesting user does not have staff access, the request returns an HTTP 404 “Not Found” response to avoid revealing the existence of the account.

If no user exists with the specified username, an HTTP 404 “Not Found” response is returned.

If “application/merge-patch+json” is not the specified content type, a 415 “Unsupported Media Type” response is returned.

If validation errors prevent the update, this method returns a 400 “Bad Request” response that includes a “field_errors” field that lists all error messages.

If a failure at the time of the update prevents the update, a 400 “Bad Request” error is returned. The JSON collection contains specific errors.

If the update is successful, an HTTP 204 “No Content” response is returned with no additional content.

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'openedx.core.lib.api.authentication.BearerAuthenticationAllowInactiveUser'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>)#
get(request, username)#

GET /api/user/v1/preferences/{username}/

parser_classes = (<class 'openedx.core.lib.api.parsers.MergePatchParser'>,)#
patch(request, username)#

PATCH /api/user/v1/preferences/{username}/

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx.core.lib.api.permissions.IsUserInUrlOrStaff'>)#

Module contents#