feat: Create LibraryContainerLocator for Library Containers [FC-0083]

CHANGELOG.rst

@@ -1,3 +1,8 @@
+# 2.12.0
+
+* Refactor: Rename LibraryCollectionKey to LibraryItemKey.
+* Added LibraryContainerLocator.
+
 # 2.11.0
 
 * Added LibraryCollectionKey and LibraryCollectionLocator

opaque_keys/__init__.py

@@ -14,7 +14,7 @@
 from stevedore.enabled import EnabledExtensionManager
 from typing_extensions import Self  # For python 3.11 plus, can just use "from typing import Self"
 
-__version__ = '2.11.0'
+__version__ = '2.12.0'
 
 
 class InvalidKeyError(Exception):

opaque_keys/edx/keys.py

@@ -93,19 +93,19 @@ def make_asset_key(self, asset_type: str, path: str) -> AssetKey:  # pragma: no
         raise NotImplementedError()
 
 
-class LibraryCollectionKey(OpaqueKey):
+class LibraryItemKey(OpaqueKey):
     """
-    An :class:`opaque_keys.OpaqueKey` identifying a particular Library Collection object.
+    An :class:`opaque_keys.OpaqueKey` identifying a particular item in a library.
     """
-    KEY_TYPE = 'collection_key'
+    KEY_TYPE = 'library_item_key'
     library_key: LibraryLocatorV2
-    collection_id: str
     __slots__ = ()
 
     @property
+    @abstractmethod
     def org(self) -> str | None:  # pragma: no cover
         """
-        The organization that this collection belongs to.
+        The organization that this object belongs to.
         """
         raise NotImplementedError()
 

opaque_keys/edx/locator.py

@@ -16,7 +16,7 @@
 
 from opaque_keys import OpaqueKey, InvalidKeyError
 from opaque_keys.edx.keys import AssetKey, CourseKey, DefinitionKey, \
-    LearningContextKey, UsageKey, UsageKeyV2, LibraryCollectionKey
+    LearningContextKey, UsageKey, UsageKeyV2, LibraryItemKey
 
 log = logging.getLogger(__name__)
 
@@ -1623,14 +1623,13 @@
         return str(self)
 
 
-class LibraryCollectionLocator(CheckFieldMixin, LibraryCollectionKey):
+class LibraryCollectionLocator(CheckFieldMixin, LibraryItemKey):
     """
     When serialized, these keys look like:
         lib-collection:org:lib:collection-id
     """
     CANONICAL_NAMESPACE = 'lib-collection'
     KEY_FIELDS = ('library_key', 'collection_id')
-    library_key: LibraryLocatorV2
     collection_id: str
 
     __slots__ = KEY_FIELDS
@@ -1655,7 +1654,7 @@
     @property
     def org(self) -> str | None:  # pragma: no cover
         """
-        The organization that this collection belongs to.
+        The organization that this Collection belongs to.
         """
         return self.library_key.org
 
@@ -1676,3 +1675,65 @@
             return cls(library_key, collection_id)
         except (ValueError, TypeError) as error:
             raise InvalidKeyError(cls, serialized) from error
+
+
+class LibraryContainerLocator(CheckFieldMixin, LibraryItemKey):
+    """
+    When serialized, these keys look like:
+        lct:org:lib:ct-type:ct-id
+    """
+    CANONICAL_NAMESPACE = 'lct'  # "Library Container"
+    KEY_FIELDS = ('library_key', 'container_type', 'container_id')
+    container_type: str
+    container_id: str
+
+    __slots__ = KEY_FIELDS
+    CHECKED_INIT = False
+
+    # Allow container IDs to contian unicode characters
+    CONTAINER_ID_REGEXP = re.compile(r'^[\w\-.]+$', flags=re.UNICODE)
+
+    def __init__(self, library_key: LibraryLocatorV2, container_type: str, container_id: str):
+        """
+        Construct a CollectionLocator
+        """
+        if not isinstance(library_key, LibraryLocatorV2):
+            raise TypeError("library_key must be a LibraryLocatorV2")
+
+        self._check_key_string_field("container_type", container_type)
+        self._check_key_string_field("container_id", container_id, regexp=self.CONTAINER_ID_REGEXP)
+        super().__init__(
+            library_key=library_key,
+            container_type=container_type,
+            container_id=container_id,
+        )
+
+    @property
+    def org(self) -> str | None:  # pragma: no cover
+        """
+        The organization that this Container belongs to.
+        """
+        return self.library_key.org
+
+    def _to_string(self) -> str:
+        """
+        Serialize this key as a string
+        """
+        return ":".join((
+            self.library_key.org,
+            self.library_key.slug,
+            self.container_type,
+            self.container_id
+        ))
+
+    @classmethod
+    def _from_string(cls, serialized: str) -> Self:
+        """
+        Instantiate this key from a serialized string
+        """
+        try:
+            (org, lib_slug, container_type, container_id) = serialized.split(':')
+            library_key = LibraryLocatorV2(org, lib_slug)
+            return cls(library_key, container_type, container_id)
+        except (ValueError, TypeError) as error:
+            raise InvalidKeyError(cls, serialized) from error

opaque_keys/edx/tests/test_container_locators.py

@@ -0,0 +1,75 @@
+"""
+Tests of LibraryContainerLocator
+"""
+import ddt
+from opaque_keys import InvalidKeyError
+from opaque_keys.edx.tests import LocatorBaseTest
+from opaque_keys.edx.locator import LibraryContainerLocator, LibraryLocatorV2
+
+
+@ddt.ddt
+class TestLibraryContainerLocator(LocatorBaseTest):
+    """
+    Tests of :class:`.LibraryContainerLocator`
+    """
+    @ddt.data(
+        "org/lib/id/foo",
+        "org/lib/id",
+        "org+lib+id",
+        "org+lib+",
+        "org+lib++id@library",
+        "org+ne@t",
+        "per%ent+sign",
+    )
+    def test_coll_key_from_invalid_string(self, coll_id_str):
+        with self.assertRaises(InvalidKeyError):
+            LibraryContainerLocator.from_string(coll_id_str)
+
+    def test_key_constructor(self):
+        org = 'TestX'
+        lib = 'LibraryX'
+        container_type = 'unit'
+        container_id = 'test-container'
+        library_key = LibraryLocatorV2(org=org, slug=lib)
+        container_key = LibraryContainerLocator(
+            library_key=library_key,
+            container_type=container_type,
+            container_id=container_id,
+        )
+        library_key = container_key.library_key
+        self.assertEqual(str(container_key), "lct:TestX:LibraryX:unit:test-container")
+        self.assertEqual(container_key.org, org)
+        self.assertEqual(container_key.container_type, container_type)
+        self.assertEqual(container_key.container_id, container_id)
+        self.assertEqual(library_key.org, org)
+        self.assertEqual(library_key.slug, lib)
+
+    def test_key_constructor_bad_ids(self):
+        library_key = LibraryLocatorV2(org="TestX", slug="lib1")
+
+        with self.assertRaises(TypeError):
+            LibraryContainerLocator(library_key=None, container_type='unit', container_id='usage')
+
+        with self.assertRaises(ValueError):
+            LibraryContainerLocator(library_key=library_key, container_type='unit', container_id='usage-!@#{$%^&*}')
+
+    def test_key_constructor_bad_type(self):
+        library_key = LibraryLocatorV2(org="TestX", slug="lib1")
+
+        with self.assertRaises(ValueError):
+            LibraryContainerLocator(library_key=library_key, container_type='unit-!@#{$%^&*}', container_id='usage')
+
+    def test_key_from_string(self):
+        org = 'TestX'
+        lib = 'LibraryX'
+        container_type = 'unit'
+        container_id = 'test-container'
+        str_key = f"lct:{org}:{lib}:{container_type}:{container_id}"
+        container_key = LibraryContainerLocator.from_string(str_key)
+        library_key = container_key.library_key
+        self.assertEqual(str(container_key), str_key)
+        self.assertEqual(container_key.org, org)
+        self.assertEqual(container_key.container_type, container_type)
+        self.assertEqual(container_key.container_id, container_id)
+        self.assertEqual(library_key.org, org)
+        self.assertEqual(library_key.slug, lib)

setup.py

@@ -183,8 +183,9 @@ def get_version(*file_paths):
         'block_type': [
             'block-type-v1 = opaque_keys.edx.block_types:BlockTypeKeyV1',
         ],
-        'collection_key': [
+        'library_item_key': [
             'lib-collection = opaque_keys.edx.locator:LibraryCollectionLocator',
+            'lct = opaque_keys.edx.locator:LibraryContainerLocator',
         ],
     }
 )