lms.djangoapps.course_api.blocks package

lms.djangoapps.course_api.blocks package#

Subpackages#

Submodules#

lms.djangoapps.course_api.blocks.api module#

API function for retrieving course blocks data

lms.djangoapps.course_api.blocks.api.get_block_metadata(block, includes=())#

Get metadata about the specified XBlock.

Parameters:

  • block (XBlock) – block object

  • includes (list|set) –

    list or set of metadata keys to include. Valid keys are: index_dictionary: a dictionary of data used to add this XBlock’s content

    to a search index.

lms.djangoapps.course_api.blocks.api.get_blocks(request, usage_key, user=None, depth=None, nav_depth=None, requested_fields=None, block_counts=None, student_view_data=None, return_type='dict', block_types_filter=None, hide_access_denials=False, allow_start_dates_in_future=False)#

Return a serialized representation of the course blocks.

Parameters:

  • request (HTTPRequest) – Used for calling django reverse.

  • usage_key (UsageKey) – Identifies the starting block of interest.

  • user (User) – Optional user object for whom the blocks are being retrieved. If None, blocks are returned regardless of access checks.

  • depth (integer or None) – Identifies the depth of the tree to return starting at the root block. If None, the entire tree starting at the root is returned.

  • nav_depth (integer) – Optional parameter that indicates how far deep to traverse into the block hierarchy before bundling all the descendants for navigation.

  • requested_fields (list) – Optional list of names of additional fields to return for each block. Supported fields are listed in transformers.SUPPORTED_FIELDS.

  • block_counts (list) – Optional list of names of block types for which to return an aggregate count of blocks.

  • student_view_data (list) – Optional list of names of block types for which blocks to return their student_view_data.

  • return_type (string) – Possible values are ‘dict’ or ‘list’. Indicates the format for returning the blocks.

  • block_types_filter (list) – Optional list of block type names used to filter the final result of returned blocks.

  • hide_access_denials (bool) – When True, filter out any blocks that were denied access to the user, even if they have access denial messages attached.

  • allow_start_dates_in_future (bool) – When True, will allow blocks to be returned that can bypass the StartDateTransformer’s filter to show blocks with start dates in the future.

lms.djangoapps.course_api.blocks.forms module#

Course API Forms

class lms.djangoapps.course_api.blocks.forms.BlockListGetForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None, bound_field_class=None)#

Bases: Form

A form to validate query parameters in the block list retrieval endpoint

base_fields = {'all_blocks': <openedx.core.djangoapps.util.forms.ExtendedNullBooleanField object>, 'block_counts': <openedx.core.djangoapps.util.forms.MultiValueField object>, 'block_types_filter': <openedx.core.djangoapps.util.forms.MultiValueField object>, 'depth': <django.forms.fields.CharField object>, 'nav_depth': <django.forms.fields.IntegerField object>, 'requested_fields': <openedx.core.djangoapps.util.forms.MultiValueField object>, 'return_type': <django.forms.fields.ChoiceField object>, 'student_view_data': <openedx.core.djangoapps.util.forms.MultiValueField object>, 'usage_key': <django.forms.fields.CharField object>, 'username': <django.forms.fields.CharField object>}#
clean()#

Return cleaned data, including additional requested fields.

clean_depth()#

Get the appropriate depth. No provided value will be treated as a depth of 0, while a value of “all” will be treated as unlimited depth.

clean_requested_fields()#

Return a set of requested_fields, merged with defaults of type and display_name

clean_return_type()#

Return valid ‘return_type’ or default value of ‘dict’

clean_usage_key()#

Ensure a valid usage_key was provided.

clean_username()#

Return cleaned username.

Overrides the default behaviour that maps an empty string to None. This allows us to differentiate between no username being provided (None) vs an empty username being provided (‘’).

declared_fields = {'all_blocks': <openedx.core.djangoapps.util.forms.ExtendedNullBooleanField object>, 'block_counts': <openedx.core.djangoapps.util.forms.MultiValueField object>, 'block_types_filter': <openedx.core.djangoapps.util.forms.MultiValueField object>, 'depth': <django.forms.fields.CharField object>, 'nav_depth': <django.forms.fields.IntegerField object>, 'requested_fields': <openedx.core.djangoapps.util.forms.MultiValueField object>, 'return_type': <django.forms.fields.ChoiceField object>, 'student_view_data': <openedx.core.djangoapps.util.forms.MultiValueField object>, 'usage_key': <django.forms.fields.CharField object>, 'username': <django.forms.fields.CharField object>}#
property media#

Return all media required to render the widgets on this form.

lms.djangoapps.course_api.blocks.permissions module#

Encapsulates permissions checks for Course Blocks API

lms.djangoapps.course_api.blocks.permissions.can_access_all_blocks(requesting_user, course_key)#

Returns whether the requesting_user can access all the blocks in the course.

lms.djangoapps.course_api.blocks.permissions.can_access_others_blocks(requesting_user, course_key)#

Returns whether the requesting_user can access the blocks for other users in the given course.

lms.djangoapps.course_api.blocks.permissions.can_access_self_blocks(requesting_user: User, course_key: CourseKey) → AccessResponse#

Returns whether the requesting_user can access own blocks.

lms.djangoapps.course_api.blocks.permissions.is_course_public(course_key: CourseKey) → AccessResponse#

This checks if a course is publicly accessible or not.

lms.djangoapps.course_api.blocks.serializers module#

Serializers for Course Blocks related return objects.

class lms.djangoapps.course_api.blocks.serializers.BlockDictSerializer(*args, **kwargs)#

Bases: Serializer

Serializer that formats a BlockStructure object to a dictionary, rather than a list, of blocks

get_blocks(structure)#

Serialize to a dictionary of blocks keyed by the block’s usage_key.

class lms.djangoapps.course_api.blocks.serializers.BlockSerializer(*args, **kwargs)#

Bases: Serializer

Serializer for single course block

to_representation(block_key)#

Return a serializable representation of the requested block

class lms.djangoapps.course_api.blocks.serializers.SupportedFieldType(block_field_name, transformer=None, requested_field_name=None, serializer_field_name=None, default_value=None)#

Bases: object

Metadata about fields supported by different transformers

lms.djangoapps.course_api.blocks.toggles module#

Toggles for Course API.

lms.djangoapps.course_api.blocks.urls module#

Course Block API URLs

lms.djangoapps.course_api.blocks.utils module#

Utils for Blocks

lms.djangoapps.course_api.blocks.utils.filter_discussion_xblocks_from_response(response, course_key)#

Removes discussion xblocks if discussion provider is openedx.

lms.djangoapps.course_api.blocks.views module#

CourseBlocks API views

class lms.djangoapps.course_api.blocks.views.BlockMetadataView(**kwargs)#

Bases: DeveloperErrorViewMixin, ListAPIView

Use Case

Returns the block metadata. Data like index_dictionary related to a block should be fetched using this API, because they are too large for the cache used by the course blocks/transformers API.

Example requests:

GET /api/courses/v1/block_metadata/<usage_id>/?

&include=index_dictionary

Parameters:

  • “include”: a comma-separated list of keys to include. Valid keys are “index_dictionary”.

Response Values

A dictionary containing: * id (string): Block usage_key_str. * type (string) Block type. * index_dictionary: (dict) The index_dictionary JSON data

(usually this is the text content of the block, for search indexing or other purposes) for this block. Returned only if the “index_dictionary” is included in the “include” parameter.

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'>)#
dispatch(request, *args, **kwargs)#

.dispatch() is pretty much the same as Django’s regular dispatch, but with extra hooks for startup, finalize, and exception handling.

list(request, usage_key_string)#

Retrieves the usage_key for the requested block, and then returns the block metadata

Parameters:

object (request - Django request)

permission_classes = ()#
class lms.djangoapps.course_api.blocks.views.BlocksInCourseView(**kwargs)#

Bases: BlocksView

Use Case

Returns the blocks in the course according to the requesting user’s access level.

Example requests:

GET /api/courses/v1/blocks/?course_id=<course_id> GET /api/courses/v1/blocks/?course_id=<course_id>

&username=anjali &depth=all &requested_fields=graded,format,student_view_multi_device,lti_url &block_counts=video &student_view_data=video &block_types_filter=problem,html

Parameters:

This view redirects to /api/courses/v1/blocks/<root_usage_key>/ for the root usage key of the course specified by course_id. The view accepts all parameters accepted by BlocksView, plus the following required parameter

  • course_id: (string, required) The ID of the course whose block data we want to return

Response Values

Responses are identical to those returned by BlocksView when passed the root_usage_key of the requested course.

If the course_id is not supplied, a 400: Bad Request is returned, with a message indicating that course_id is required.

If an invalid course_id is supplied, a 400: Bad Request is returned, with a message indicating that the course_id is not valid.

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'>)#
list(request, hide_access_denials=False)#

Retrieves the usage_key for the requested course, and then returns the same information that would be returned by BlocksView.list, called with that usage key

Parameters:

object (request - Django request)

permission_classes = ()#
class lms.djangoapps.course_api.blocks.views.BlocksView(**kwargs)#

Bases: DeveloperErrorViewMixin, ListAPIView

Use Case

Returns the blocks within the requested block tree according to the requesting user’s access level.

Example requests:

GET /api/courses/v1/blocks/<root_block_usage_id>/?depth=all GET /api/courses/v1/blocks/<usage_id>/?

username=anjali &depth=all &requested_fields=graded,format,student_view_multi_device,lti_url,due &block_counts=video &student_view_data=video &block_types_filter=problem,html

Parameters:

  • all_blocks: (boolean) Provide a value of “true” to return all blocks. Returns all blocks only if the requesting user has course staff permissions. Blocks that are visible only to specific learners (for example, based on group membership or randomized content) are all included. If all_blocks is not specified, you must specify the username for the user whose course blocks are requested.

  • username: (string) Required, unless all_blocks is specified. Specify the username for the user whose course blocks are requested. A blank/empty username can be used to request the blocks accessible to anonymous users (for public courses). Only users with course staff permissions can specify other users’ usernames. If a username is specified, results include blocks that are visible to that user, including those based on group or cohort membership or randomized content assigned to that user.

    Example: username=anjali

    username=’’ username

  • student_view_data: (list) Indicates for which block types to return student_view_data.

    Example: student_view_data=video

  • block_counts: (list) Indicates for which block types to return the aggregate count of the blocks.

    Example: block_counts=video,problem

  • requested_fields: (list) Indicates which additional fields to return for each block. For a list of available fields see under Response Values -> blocks, below.

    The following fields are always returned: id, type, display_name

    Example: requested_fields=graded,format,student_view_multi_device

  • depth: (integer or all) Indicates how deep to traverse into the blocks hierarchy. A value of all means the entire hierarchy.

    Default is 0

    Example: depth=all

  • nav_depth: (integer)

    WARNING: nav_depth is not supported, and may be removed at any time.

    Indicates how far deep to traverse into the course hierarchy before bundling all the descendants.

    Default is 3 since typical navigational views of the course show a maximum of chapter->sequential->vertical.

    Example: nav_depth=3

  • return_type (string) Indicates in what data type to return the blocks.

    Default is dict. Supported values are: dict, list

    Example: return_type=dict

  • block_types_filter: (list) Requested types of blocks used to filter the final result of returned blocks. Possible values include sequential, vertical, html, problem, video, and discussion.

    Example: block_types_filter=vertical,html

Response Values

The following fields are returned with a successful response.

  • root: The ID of the root node of the requested course block structure.

  • blocks: A dictionary or list, based on the value of the “return_type” parameter. Maps block usage IDs to a collection of information about each block. Each block contains the following fields.

    • id: (string) The usage ID of the block.

    • type: (string) The type of block. Possible values the names of any XBlock type in the system, including custom blocks. Examples are course, chapter, sequential, vertical, html, problem, video, and discussion.

    • display_name: (string) The display name of the block.

    • children: (list) If the block has child blocks, a list of IDs of the child blocks. Returned only if “children” is included in the “requested_fields” parameter.

    • completion: (float or None) The level of completion of the block. Its value can vary between 0.0 and 1.0 or be equal to None if block is not completable. Returned only if “completion” is included in the “requested_fields” parameter.

    • block_counts: (dict) For each block type specified in the block_counts parameter to the endpoint, the aggregate number of blocks of that type for this block and all of its descendants.

    • graded (boolean) Whether or not the block or any of its descendants is graded. Returned only if “graded” is included in the “requested_fields” parameter.

    • format: (string) The assignment type of the block. Possible values can be “Homework”, “Lab”, “Midterm Exam”, and “Final Exam”. Returned only if “format” is included in the “requested_fields” parameter.

    • student_view_data: (dict) The JSON data for this block. Returned only if the “student_view_data” input parameter contains this block’s type.

    • student_view_url: (string) The URL to retrieve the HTML rendering of this block’s student view. The HTML could include CSS and Javascript code. This field can be used in combination with the student_view_multi_device field to decide whether to display this content to the user.

      This URL can be used as a fallback if the student_view_data for this block type is not supported by the client or the block.

    • student_view_multi_device: (boolean) Whether or not the HTML of the student view that is rendered at “student_view_url” supports responsive web layouts, touch-based inputs, and interactive state management for a variety of device sizes and types, including mobile and touch devices. Returned only if “student_view_multi_device” is included in the “requested_fields” parameter.

    • lms_web_url: (string) The URL to the navigational container of the xBlock on the web. This URL can be used as a further fallback if the student_view_url and the student_view_data fields are not supported. Will direct to either the “New” (micro-frontend) or “Legacy” (Django-template-rendered) frontend experience depending on which experience is active.

    • legacy_web_url: (string) Like lms_web_url, but always directs to the “Legacy” frontend experience. Should only be used for transitional purposes; will be removed as part of DEPR-109.

    • lti_url: The block URL for an LTI consumer. Returned only if the “ENABLE_LTI_PROVIDER” Django settign is set to “True”.

    • due: The due date of the block. Returned only if “due” is included in the “requested_fields” parameter.

    • show_correctness: Whether to show scores/correctness to learners for the current sequence or problem. Returned only if “show_correctness” is included in the “requested_fields” parameter.

    • Additional XBlock fields can be included in the response if they are configured via the COURSE_BLOCKS_API_EXTRA_FIELDS Django setting and requested via the “requested_fields” parameter.

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'>)#
dispatch(request, *args, **kwargs)#

.dispatch() is pretty much the same as Django’s regular dispatch, but with extra hooks for startup, finalize, and exception handling.

list(request, usage_key_string, hide_access_denials=False)#

REST API endpoint for listing all the blocks information in the course, while regarding user access and roles.

Parameters:

  • object (request - Django request)

  • block. (usage_key_string - The usage key for a)

permission_classes = ()#
lms.djangoapps.course_api.blocks.views.recurse_mark_complete(block_id, blocks)#

Helper function to walk course tree dict, marking completion as 1 or 0

If all blocks are complete, mark parent block complete

Parameters:

  • blocks – dict of all blocks

  • block_id – root or child block id

Returns:

block: course_outline_root_block block object or child block

Module contents#

Course API Blocks