openedx_authz.rest_api package

openedx_authz.rest_api package#

Subpackages#

Submodules#

openedx_authz.rest_api.data module#

Data classes and enums for the Open edX AuthZ REST API.

class openedx_authz.rest_api.data.BaseEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Base enum class.

classmethod values()

List the values of the enum.

class openedx_authz.rest_api.data.RoleOperationError(*values)

Bases: BaseEnum

Enum for errors that can occur during role assignment and removal operations.

ROLE_ASSIGNMENT_ERROR = 'role_assignment_error'
ROLE_REMOVAL_ERROR = 'role_removal_error'
USER_ALREADY_HAS_ROLE = 'user_already_has_role'
USER_DOES_NOT_HAVE_ROLE = 'user_does_not_have_role'
USER_NOT_FOUND = 'user_not_found'
class openedx_authz.rest_api.data.RoleOperationStatus(*values)

Bases: BaseEnum

Enum for the status of role assignment and removal operations.

ROLE_ADDED = 'role_added'
ROLE_REMOVED = 'role_removed'
class openedx_authz.rest_api.data.SearchField(*values)

Bases: BaseEnum

Enum for the fields allowed for text search filtering.

EMAIL = 'email'
FULL_NAME = 'full_name'
USERNAME = 'username'
class openedx_authz.rest_api.data.SortField(*values)

Bases: BaseEnum

Enum for the fields to sort by.

EMAIL = 'email'
FULL_NAME = 'full_name'
USERNAME = 'username'
class openedx_authz.rest_api.data.SortOrder(*values)

Bases: BaseEnum

Enum for the order to sort by.

ASC = 'asc'
DESC = 'desc'

openedx_authz.rest_api.decorators module#

Decorators for the Open edX AuthZ REST API.

openedx_authz.rest_api.decorators.authz_permissions(permissions: list[str])

Decorator to attach required permissions to view methods.

This decorator stores a list of permission identifiers that will be checked by MethodPermissionMixin during authorization.

Parameters:

permissions – List of permission identifiers e.g., [“content_libraries.view_library_team”, “content_libraries.manage_library_team”])

Examples

>>> class MyView(APIView):
...     @authz_permissions(["content_libraries.view_library_team"])
...     def get(self, request):
...         pass
...
...     @authz_permissions(["content_libraries.manage_library_team"])
...     def post(self, request):
...         pass
openedx_authz.rest_api.decorators.view_auth_classes(is_authenticated=True)

Function and class decorator that abstracts the authentication and permission checks for api views.

Parameters:

is_authenticated – Whether the view requires authentication.

Returns:

The decorated view or class.

Examples

>>> @view_auth_classes(is_authenticated=False)
... class MyView(APIView):
...     def get(self, request):
...         return Response("Hello, world!")

openedx_authz.rest_api.urls module#

Open edX AuthZ API URLs.

openedx_authz.rest_api.utils module#

Utility functions for the Open edX AuthZ REST API.

openedx_authz.rest_api.utils.filter_users(users: list[dict], search: str | None, roles: list[str] | None) → list[dict]

Filter users by a case-insensitive search string and/or by roles.

Parameters:

  • users (list[dict]) – The users to filter.

  • search (str | None) – Optional search term matched against fields in SearchField.

  • roles (list[str] | None) – Optional list of roles; include users that have any of these roles.

Returns:

The filtered users, preserving the original order.

Return type:

list[dict]

openedx_authz.rest_api.utils.get_generic_scope(scope: ScopeData) → ScopeData

Create a generic scope from a given scope by replacing its key with a wildcard.

This function preserves the namespace of the original scope but replaces the specific key with a wildcard, allowing for broader permission checks across all scopes within the same namespace.

Parameters:

scope (ScopeData) – The specific scope to generalize.

Returns:

A new scope with the same namespace but a wildcard key.

Return type:

ScopeData

Examples

>>> scope = ScopeData(namespaced_key="lib^lib:DemoX:CSPROB")
>>> get_generic_scope(scope)
ScopeData(namespaced_key="lib^*")
openedx_authz.rest_api.utils.get_user_by_username_or_email(username_or_email: str) → User

Retrieve a user by their username or email address.

Parameters:

username_or_email (str) – The username or email address to search for.

Returns:

The User object if found and not retired.

Return type:

User

Raises:

User.DoesNotExist – If no user matches the provided username or email, or if the user has an associated retirement request.

openedx_authz.rest_api.utils.get_user_map(usernames: list[str]) → dict[str, User]

Retrieve a dictionary mapping usernames to User objects for efficient batch lookups.

This function performs a single optimized database query to fetch multiple users, making it ideal for scenarios where we need to look up several users at once (e.g., when serializing multiple user role assignments).

Parameters:

usernames (list[str]) – List of usernames to retrieve. Duplicates are automatically handled by the database query.

Returns:

Dictionary mapping each username to its corresponding User object.

Only users that exist in the database are included in the returned dictionary.

Return type:

dict[str, User]

openedx_authz.rest_api.utils.sort_users(users: list[dict], sort_by: SortField = SortField.USERNAME, order: SortOrder = SortOrder.ASC) → list[dict]

Sort users by a given field and order.

Parameters:

  • users (list[dict]) – The users to sort.

  • sort_by (SortField, optional) – The field to sort by. Defaults to SortField.USERNAME.

  • order (SortOrder, optional) – The order to sort by. Defaults to SortOrder.ASC.

Raises:
Returns:

The sorted users.

Return type:

list[dict]

Module contents#

Contents