feat: XBlock.usage_key, XBlock.context_key convenience props (#690)

Add two new properties to `XBlock` objects: `.usage_key` and
`.context_key`. These simply expose the values of
`.scope_ids.usage_id`` and `.scope_ids.usage_id.context_key`,
providing a convenient replacement to the deprecated,
edx-platform-specific block properties `.location` and `.course_id`,
respectively.

Note: this adds opaque-keys as a dependency for some new unit tests.
Normally it wouldn't make sense to add a dependency just for a couple
of tests, but we anticipate to make the repo depend on opaque-keys:
soon anyway, for:

* #707, and
* #708

Bumps version from 1.9.1 to 1.10.0

CHANGELOG.rst

@@ -7,6 +7,14 @@ These are notable changes in XBlock.
 Unreleased
 ----------
 
+1.10.0 - 2024-01-12
+-------------------
+
+* Add two new properties to ``XBlock`` objects: ``.usage_key`` and ``.context_key``.
+  These simply expose the values of ``.scope_ids.usage_id`` and ``.scope_ids.usage_id.context_key``,
+  providing a convenient replacement to the deprecated, edx-platform-specific block properties ``.location``
+  and ``.course_id``, respectively.
+
 1.9.1 - 2023-12-22
 ------------------
 

requirements/base.in

@@ -1,6 +1,7 @@
 # Core requirements for using this package
 -c constraints.txt
 
+edx-opaque-keys
 fs
 lxml
 mako

requirements/base.txt

@@ -6,16 +6,22 @@
 #
 appdirs==1.4.4
     # via fs
+edx-opaque-keys==2.5.1
+    # via -r requirements/base.in
 fs==2.4.16
     # via -r requirements/base.in
 lxml==5.1.0
     # via -r requirements/base.in
-mako==1.3.0
+mako==1.3.1
     # via -r requirements/base.in
 markupsafe==2.1.4
     # via
     #   -r requirements/base.in
     #   mako
+pbr==6.0.0
+    # via stevedore
+pymongo==3.13.0
+    # via edx-opaque-keys
 python-dateutil==2.8.2
     # via -r requirements/base.in
 pytz==2023.3.post1
@@ -28,6 +34,10 @@ six==1.16.0
     # via
     #   fs
     #   python-dateutil
+stevedore==5.1.0
+    # via edx-opaque-keys
+typing-extensions==4.9.0
+    # via edx-opaque-keys
 web-fragments==2.1.0
     # via -r requirements/base.in
 webob==1.8.7

requirements/dev.txt

@@ -21,11 +21,11 @@ attrs==23.2.0
     # via
     #   -r requirements/test.txt
     #   hypothesis
-boto3==1.34.23
+boto3==1.34.26
     # via
     #   -r requirements/test.txt
     #   fs-s3fs
-botocore==1.34.23
+botocore==1.34.26
     # via
     #   -r requirements/test.txt
     #   boto3
@@ -93,6 +93,8 @@ django==2.2.28
     #   openedx-django-pyfs
 edx-lint==5.3.6
     # via -r requirements/test.txt
+edx-opaque-keys==2.5.1
+    # via -r requirements/test.txt
 exceptiongroup==1.2.0
     # via
     #   -r requirements/test.txt
@@ -113,7 +115,7 @@ fs-s3fs==1.1.1
     # via
     #   -r requirements/test.txt
     #   openedx-django-pyfs
-hypothesis==6.96.1
+hypothesis==6.96.4
     # via -r requirements/test.txt
 importlib-metadata==7.0.1
     # via
@@ -150,7 +152,7 @@ lazy==1.6
     # via -r requirements/test.txt
 lxml==5.1.0
     # via -r requirements/test.txt
-mako==1.3.0
+mako==1.3.1
     # via -r requirements/test.txt
 markupsafe==2.1.4
     # via
@@ -230,6 +232,10 @@ pylint-plugin-utils==0.8.2
     #   -r requirements/test.txt
     #   pylint-celery
     #   pylint-django
+pymongo==3.13.0
+    # via
+    #   -r requirements/test.txt
+    #   edx-opaque-keys
 pyproject-api==1.6.1
     # via
     #   -r requirements/ci.txt
@@ -289,6 +295,7 @@ stevedore==5.1.0
     # via
     #   -r requirements/test.txt
     #   code-annotations
+    #   edx-opaque-keys
 text-unidecode==1.3
     # via
     #   -r requirements/test.txt
@@ -319,6 +326,7 @@ typing-extensions==4.9.0
     #   -r requirements/test.txt
     #   annotated-types
     #   astroid
+    #   edx-opaque-keys
     #   inflect
     #   pydantic
     #   pydantic-core

requirements/django.txt

@@ -8,9 +8,9 @@ appdirs==1.4.4
     # via
     #   -r requirements/base.txt
     #   fs
-boto3==1.34.23
+boto3==1.34.26
     # via fs-s3fs
-botocore==1.34.23
+botocore==1.34.26
     # via
     #   boto3
     #   s3transfer
@@ -19,6 +19,8 @@ django==2.2.28
     #   -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt
     #   -r requirements/django.in
     #   openedx-django-pyfs
+edx-opaque-keys==2.5.1
+    # via -r requirements/base.txt
 fs==2.4.16
     # via
     #   -r requirements/base.txt
@@ -34,14 +36,22 @@ lazy==1.6
     # via -r requirements/django.in
 lxml==5.1.0
     # via -r requirements/base.txt
-mako==1.3.0
+mako==1.3.1
     # via -r requirements/base.txt
 markupsafe==2.1.4
     # via
     #   -r requirements/base.txt
     #   mako
 openedx-django-pyfs==3.4.1
     # via -r requirements/django.in
+pbr==6.0.0
+    # via
+    #   -r requirements/base.txt
+    #   stevedore
+pymongo==3.13.0
+    # via
+    #   -r requirements/base.txt
+    #   edx-opaque-keys
 python-dateutil==2.8.2
     # via
     #   -r requirements/base.txt
@@ -64,6 +74,14 @@ six==1.16.0
     #   python-dateutil
 sqlparse==0.4.4
     # via django
+stevedore==5.1.0
+    # via
+    #   -r requirements/base.txt
+    #   edx-opaque-keys
+typing-extensions==4.9.0
+    # via
+    #   -r requirements/base.txt
+    #   edx-opaque-keys
 urllib3==1.26.18
     # via botocore
 web-fragments==2.1.0

requirements/doc.txt

@@ -18,11 +18,11 @@ babel==2.14.0
     #   sphinx
 beautifulsoup4==4.12.3
     # via pydata-sphinx-theme
-boto3==1.34.23
+boto3==1.34.26
     # via
     #   -r requirements/django.txt
     #   fs-s3fs
-botocore==1.34.23
+botocore==1.34.26
     # via
     #   -r requirements/django.txt
     #   boto3
@@ -40,6 +40,8 @@ docutils==0.19
     # via
     #   pydata-sphinx-theme
     #   sphinx
+edx-opaque-keys==2.5.1
+    # via -r requirements/django.txt
 fs==2.4.16
     # via
     #   -r requirements/django.txt
@@ -66,7 +68,7 @@ lazy==1.6
     # via -r requirements/django.txt
 lxml==5.1.0
     # via -r requirements/django.txt
-mako==1.3.0
+mako==1.3.1
     # via -r requirements/django.txt
 markupsafe==2.1.4
     # via
@@ -81,13 +83,21 @@ packaging==23.2
     # via
     #   pydata-sphinx-theme
     #   sphinx
+pbr==6.0.0
+    # via
+    #   -r requirements/django.txt
+    #   stevedore
 pydata-sphinx-theme==0.14.4
     # via sphinx-book-theme
 pygments==2.17.2
     # via
     #   accessible-pygments
     #   pydata-sphinx-theme
     #   sphinx
+pymongo==3.13.0
+    # via
+    #   -r requirements/django.txt
+    #   edx-opaque-keys
 python-dateutil==2.8.2
     # via
     #   -r requirements/django.txt
@@ -140,8 +150,15 @@ sqlparse==0.4.4
     # via
     #   -r requirements/django.txt
     #   django
+stevedore==5.1.0
+    # via
+    #   -r requirements/django.txt
+    #   edx-opaque-keys
 typing-extensions==4.9.0
-    # via pydata-sphinx-theme
+    # via
+    #   -r requirements/django.txt
+    #   edx-opaque-keys
+    #   pydata-sphinx-theme
 urllib3==1.26.18
     # via
     #   -r requirements/django.txt

requirements/test.txt

@@ -17,11 +17,11 @@ astroid==3.0.2
     #   pylint-celery
 attrs==23.2.0
     # via hypothesis
-boto3==1.34.23
+boto3==1.34.26
     # via
     #   -r requirements/django.txt
     #   fs-s3fs
-botocore==1.34.23
+botocore==1.34.26
     # via
     #   -r requirements/django.txt
     #   boto3
@@ -61,6 +61,8 @@ distlib==0.3.8
     #   openedx-django-pyfs
 edx-lint==5.3.6
     # via -r requirements/test.in
+edx-opaque-keys==2.5.1
+    # via -r requirements/django.txt
 exceptiongroup==1.2.0
     # via
     #   hypothesis
@@ -78,7 +80,7 @@ fs-s3fs==1.1.1
     # via
     #   -r requirements/django.txt
     #   openedx-django-pyfs
-hypothesis==6.96.1
+hypothesis==6.96.4
     # via -r requirements/test.in
 inflect==7.0.0
     # via jinja2-pluralize
@@ -102,7 +104,7 @@ lazy==1.6
     # via -r requirements/django.txt
 lxml==5.1.0
     # via -r requirements/django.txt
-mako==1.3.0
+mako==1.3.1
     # via -r requirements/django.txt
 markupsafe==2.1.4
     # via
@@ -123,7 +125,9 @@ packaging==23.2
 path==16.9.0
     # via -r requirements/test.in
 pbr==6.0.0
-    # via stevedore
+    # via
+    #   -r requirements/django.txt
+    #   stevedore
 platformdirs==4.1.0
     # via
     #   pylint
@@ -157,6 +161,10 @@ pylint-plugin-utils==0.8.2
     # via
     #   pylint-celery
     #   pylint-django
+pymongo==3.13.0
+    # via
+    #   -r requirements/django.txt
+    #   edx-opaque-keys
 pyproject-api==1.6.1
     # via tox
 pytest==7.4.4
@@ -202,7 +210,10 @@ sqlparse==0.4.4
     #   -r requirements/django.txt
     #   django
 stevedore==5.1.0
-    # via code-annotations
+    # via
+    #   -r requirements/django.txt
+    #   code-annotations
+    #   edx-opaque-keys
 text-unidecode==1.3
     # via python-slugify
 tomli==2.0.1
@@ -218,8 +229,10 @@ tox==4.12.1
     # via -r requirements/test.in
 typing-extensions==4.9.0
     # via
+    #   -r requirements/django.txt
     #   annotated-types
     #   astroid
+    #   edx-opaque-keys
     #   inflect
     #   pydantic
     #   pydantic-core

xblock/__init__.py

@@ -27,4 +27,4 @@ def __init__(self, *args, **kwargs):
 # without causing a circular import
 xblock.fields.XBlockMixin = XBlockMixin
 
-__version__ = '1.9.1'
+__version__ = '1.10.0'

xblock/core.py

@@ -205,6 +205,32 @@ def __init__(self, runtime, field_data=None, scope_ids=UNSET, *args, **kwargs):
         # Provide backwards compatibility for external access through _field_data
         super().__init__(runtime=runtime, scope_ids=scope_ids, field_data=field_data, *args, **kwargs)
 
+    @property
+    def usage_key(self):
+        """
+        A key identifying this particular usage of the XBlock, unique across all learning contexts in the system.
+
+        Equivalent to to `.scope_ids.usage_id`.
+        """
+        return self.scope_ids.usage_id
+
+    @property
+    def context_key(self):
+        """
+        A key identifying the learning context (course, library, etc.) that contains this XBlock usage.
+
+        Equivalent to `.scope_ids.usage_id.context_key`.
+
+        Returns:
+        * `LearningContextKey`, if `.scope_ids.usage_id` is a `UsageKey` instance.
+        * `None`, otherwise.
+
+        After https://github.com/openedx/XBlock/issues/708 is complete, we can assume that
+        `.scope_ids.usage_id` is always a `UsageKey`, and that this method will
+        always return a `LearningContextKey`.
+        """
+        return getattr(self.scope_ids.usage_id, "context_key", None)
+
     def render(self, view, context=None):
         """Render `view` with this block's runtime and the supplied `context`"""
         return self.runtime.render(self, view, context)