refactor: Simplify backcompat definitions for url_name, et al (openedx#37845)

XModuleMixin and CourseOverview both provided some backcompat names
for some XBlock key attributes. Due to refactors that have happened
in edx-platform and improvements to the XBlock API that have happened
over the years, we can now simplify these backcompat mappings. The
new mappings (old -> new) are:

* .course_id -> .context_key
* .location -> .usage_key
* .url_name -> .usage_key.block_id
* .category -> .usage_key.block_type

These are the ways we would like developers to access these
attributes going forward, so it's important that we set the
example in XModuleMixin and CourseOverview.

Note: It is technically correct to go through `.scope_ids` for
these fields, but it's harder to read. Under the hood, the XBlock
API indeed uses `.scope_ids`:
https://github.com/openedx/XBlock/blob/v5.3.0/xblock/core.py#L422-L446

Part of: openedx/xblocks-contrib#125

Author: kdmccormick

lms/djangoapps/grades/course_grade.py

@@ -242,7 +242,7 @@ def _get_chapter_grade_info(self, chapter, course_structure):
         chapter_subsection_grades = self._get_subsection_grades(course_structure, chapter.location)
         return {
             'display_name': block_metadata_utils.display_name_with_default(chapter),
-            'url_name': block_metadata_utils.url_name_for_block(chapter),
+            'url_name': chapter.usage_key.block_id,
             'sections': chapter_subsection_grades,
         }
 

lms/djangoapps/grades/subsection_grade.py

@@ -26,7 +26,7 @@ class SubsectionGradeBase(metaclass=ABCMeta):
     def __init__(self, subsection):
         self.location = subsection.location
         self.display_name = block_metadata_utils.display_name_with_default(subsection)
-        self.url_name = block_metadata_utils.url_name_for_block(subsection)
+        self.url_name = subsection.usage_key.block_id
 
         self.due = block_metadata_utils.get_datetime_field(subsection, 'due', None)
         self.end = getattr(subsection, 'end', None)

openedx/core/djangoapps/content/block_structure/block_structure.py

@@ -393,6 +393,10 @@ def __init__(self, usage_key):
         # Map of transformer name to its block-specific data.
         self.transformer_data = TransformerDataMap()
 
+    @property
+    def usage_key(self):
+        return self.location
+
 
 class BlockStructureBlockData(BlockStructure):
     """

openedx/core/djangoapps/content/course_overviews/models.py

@@ -478,9 +478,9 @@ def clean_id(self, padding_char='='):
         return course_metadata_utils.clean_course_key(self.location.course_key, padding_char)
 
     @property
-    def location(self):
+    def usage_key(self):
         """
-        Returns the UsageKey of this course.
+        Returns the UsageKey of the root block of this course.
 
         UsageKeyField has a strange behavior where it fails to parse the "run"
         of a course out of the serialized form of a Mongo Draft UsageKey. This
@@ -491,6 +491,13 @@ def location(self):
             self._location = self._location.map_into_course(self.id)
         return self._location
 
+    @property
+    def location(self):
+        """
+        The old name for `usage_key`. This method is analogous to `XModuleMixin.location`.
+        """
+        return self.usage_key
+
     @property
     def number(self):
         """
@@ -506,9 +513,9 @@ def number(self):
     @property
     def url_name(self):
         """
-        Returns this course's URL name.
+        The old name for `block_id`. This method is analogous to `XModuleMixin.url_name`.
         """
-        return block_metadata_utils.url_name_for_block(self)
+        return self.usage_key.block_id
 
     @property
     def display_name_with_default(self):

xmodule/block_metadata_utils.py

@@ -15,17 +15,6 @@
 logger = getLogger(__name__)  # pylint: disable=invalid-name
 
 
-def url_name_for_block(block):
-    """
-    Given a block, returns the block's URL name.
-
-    Arguments:
-        block (XModuleMixin|CourseOverview|BlockStructureBlockData):
-            Block that is being accessed
-    """
-    return block.location.block_id
-
-
 def display_name_with_default(block):
     """
     Calculates the display name for a block.
@@ -50,7 +39,7 @@ def display_name_with_default(block):
     """
     return (
         block.display_name if block.display_name is not None
-        else url_name_for_block(block).replace('_', ' ')
+        else block.usage_key.block_id.replace('_', ' ')
     )
 
 

xmodule/tests/test_course_metadata_utils.py

@@ -12,7 +12,6 @@
 from xmodule.block_metadata_utils import (
     display_name_with_default,
     display_name_with_default_escaped,
-    url_name_for_block
 )
 from xmodule.course_metadata_utils import (
     DEFAULT_START_DATE,
@@ -125,9 +124,6 @@ def noop_gettext(text):  # lint-amnesty, pylint: disable=unused-variable
                     "course_MNXXK4TTMUWXMMJ2KVXGS5TFOJZWS5DZLAVUGUZNGIYDGK2ZGIYDSNQ~"
                 ),
             ]),
-            FunctionTest(url_name_for_block, [
-                TestScenario((self.html_course,), self.html_course.location.block_id),
-            ]),
             FunctionTest(display_name_with_default_escaped, [
                 # Test course with a display name that contains characters that need escaping.
                 TestScenario((self.html_course,), "Intro to html"),

xmodule/x_module.py

@@ -311,18 +311,32 @@ def system(self):
 
     @property
     def course_id(self):
-        """Return the course key for this block."""
-        return self.location.course_key
+        """
+        Return the key of the block to which this Course belongs.
+
+        New code should always used `context_key`, which is the key of the Learning Context to which
+        this block belongs. "Learning Context" is a generalized notion of Courses which is inclusive
+        of Content Libraries, et al.
+        """
+        return self.context_key
 
     @property
     def category(self):
-        """Return the block type/category."""
+        """
+        Return the block type, formerly known as "category".
+
+        Preferred forms for new code: `self.usage_key.block_type` or `self.scope_ids.blocks_type`
+        """
         return self.scope_ids.block_type
 
     @property
     def location(self):
-        """Return the usage key identifying this block instance."""
-        return self.scope_ids.usage_id
+        """
+        Return the usage key identifying this block instance, formerly called the "location".
+
+        `self.usage_key` is always preferred in new code.
+        """
+        return self.usage_key
 
     @location.setter
     def location(self, value):
@@ -334,8 +348,12 @@ def location(self, value):
 
     @property
     def url_name(self):
-        """Return the URL-friendly name for this block."""
-        return block_metadata_utils.url_name_for_block(self)
+        """
+        Return the URL-friendly name for this block.
+
+        Preferred forms for new code: `self.usage_key.block_id`
+        """
+        return self.usage_key.block_id
 
     @property
     def display_name_with_default(self):