docs: mark all containers APIs as unstable

Author: bradenmacdonald

openedx_learning/apps/authoring/containers/api.py

@@ -22,6 +22,8 @@
 from ..publishing import api as publishing_api
 
 
+# 🛑 UNSTABLE: All APIs related to containers are unstable until we've figured
+#              out our approach to dynamic content (randomized, A/B tests, etc.)
 __all__ = [
     "create_container",
     "create_container_version",
@@ -42,6 +44,7 @@ def create_container(
     created_by: int | None,
 ) -> ContainerEntity:
     """
+    [ 🛑 UNSTABLE ]
     Create a new container.
 
     Args:
@@ -65,6 +68,7 @@ def create_container(
 
 def create_entity_list() -> EntityList:
     """
+    [ 🛑 UNSTABLE ]
     Create a new entity list. This is an structure that holds a list of entities
     that will be referenced by the container.
 
@@ -81,6 +85,7 @@ def create_next_defined_list(
     entity_version_pks: list[int | None],
 ) -> EntityListRow:
     """
+    [ 🛑 UNSTABLE ]
     Create new entity list rows for an entity list.
 
     Args:
@@ -129,6 +134,7 @@ def create_defined_list_with_rows(
     entity_version_pks: list[int | None],
 ) -> EntityList:
     """
+    [ 🛑 UNSTABLE ]
     Create new entity list rows for an entity list.
 
     Args:
@@ -164,6 +170,7 @@ def get_entity_list_with_pinned_versions(
     rows: QuerySet[EntityListRow],
 ) -> EntityList:
     """
+    [ 🛑 UNSTABLE ]
     Copy rows from an existing entity list to a new entity list.
 
     Args:
@@ -194,6 +201,7 @@ def check_unpinned_versions_in_defined_list(
     defined_list: EntityList,
 ) -> bool:
     """
+    [ 🛑 UNSTABLE ]
     Check if there are any unpinned versions in the defined list.
 
     Args:
@@ -214,6 +222,7 @@ def check_new_changes_in_defined_list(
     publishable_entities_pk: list[int],
 ) -> bool:
     """
+    [ 🛑 UNSTABLE ]
     Check if there are any new changes in the defined list.
 
     Args:
@@ -239,6 +248,7 @@ def create_container_version(
     created_by: int | None,
 ) -> ContainerEntityVersion:
     """
+    [ 🛑 UNSTABLE ]
     Create a new container version.
 
     Args:
@@ -288,6 +298,7 @@ def create_next_container_version(
     created_by: int | None,
 ) -> ContainerEntityVersion:
     """
+    [ 🛑 UNSTABLE ]
     Create the next version of a container. A new version of the container is created
     only when its metadata changes:
 
@@ -378,6 +389,7 @@ def create_container_and_version(
     entity_version_pks: list[int | None],
 ) -> ContainerEntityVersion:
     """
+    [ 🛑 UNSTABLE ]
     Create a new container and its first version.
 
     Args:
@@ -409,6 +421,7 @@ def create_container_and_version(
 
 def get_container(pk: int) -> ContainerEntity:
     """
+    [ 🛑 UNSTABLE ]
     Get a container by its primary key.
 
     Args:
@@ -424,6 +437,7 @@ def get_container(pk: int) -> ContainerEntity:
 @dataclass(frozen=True)
 class ContainerEntityListEntry:
     """
+    [ 🛑 UNSTABLE ]
     Data about a single entity in a container, e.g. a component in a unit.
     """
     entity_version: PublishableEntityVersion
@@ -438,6 +452,7 @@ def get_entities_in_draft_container(
     container: ContainerEntity | ContainerEntityMixin,
 ) -> list[ContainerEntityListEntry]:
     """
+    [ 🛑 UNSTABLE ]
     Get the list of entities and their versions in the draft version of the
     given container.
     """
@@ -458,6 +473,7 @@ def get_entities_in_published_container(
     container: ContainerEntity | ContainerEntityMixin,
 ) -> list[ContainerEntityListEntry] | None:
     """
+    [ 🛑 UNSTABLE ]
     Get the list of entities and their versions in the draft version of the
     given container.
     """
@@ -486,6 +502,7 @@ def contains_unpublished_changes(
     container: ContainerEntity | ContainerEntityMixin,
 ) -> bool:
     """
+    [ 🛑 UNSTABLE ]
     Check recursively if a container has any unpublished changes.
 
     Note: container.versioning.has_unpublished_changes only checks if the container

openedx_learning/apps/authoring/units/api.py

@@ -16,6 +16,8 @@
 
 from datetime import datetime
 
+# 🛑 UNSTABLE: All APIs related to containers are unstable until we've figured
+#              out our approach to dynamic content (randomized, A/B tests, etc.)
 __all__ = [
     "create_unit",
     "create_unit_version",
@@ -33,7 +35,8 @@
 def create_unit(
     learning_package_id: int, key: str, created: datetime, created_by: int | None
 ) -> Unit:
-    """Create a new unit.
+    """
+    [ 🛑 UNSTABLE ] Create a new unit.
 
     Args:
         learning_package_id: The learning package ID.
@@ -61,7 +64,8 @@ def create_unit_version(
     created: datetime,
     created_by: int | None = None,
 ) -> Unit:
-    """Create a new unit version.
+    """
+    [ 🛑 UNSTABLE ] Create a new unit version.
 
     Args:
         unit_pk: The unit ID.
@@ -98,7 +102,8 @@ def create_next_unit_version(
     created: datetime,
     created_by: int | None = None,
 ) -> Unit:
-    """Create the next unit version.
+    """
+    [ 🛑 UNSTABLE ] Create the next unit version.
 
     Args:
         unit_pk: The unit ID.
@@ -145,7 +150,8 @@ def create_unit_and_version(
     created: datetime,
     created_by: int | None = None,
 ) -> tuple[Unit, UnitVersion]:
-    """Create a new unit and its version.
+    """
+    [ 🛑 UNSTABLE ] Create a new unit and its version.
 
     Args:
         learning_package_id: The learning package ID.
@@ -168,7 +174,8 @@ def create_unit_and_version(
 
 
 def get_unit(unit_pk: int) -> Unit:
-    """Get a unit.
+    """
+    [ 🛑 UNSTABLE ] Get a unit.
 
     Args:
         unit_pk: The unit ID.
@@ -177,7 +184,8 @@ def get_unit(unit_pk: int) -> Unit:
 
 
 def get_unit_version(unit_version_pk: int) -> UnitVersion:
-    """Get a unit version.
+    """
+    [ 🛑 UNSTABLE ] Get a unit version.
 
     Args:
         unit_version_pk: The unit version ID.
@@ -186,7 +194,8 @@ def get_unit_version(unit_version_pk: int) -> UnitVersion:
 
 
 def get_latest_unit_version(unit_pk: int) -> UnitVersion:
-    """Get the latest unit version.
+    """
+    [ 🛑 UNSTABLE ] Get the latest unit version.
 
     Args:
         unit_pk: The unit ID.
@@ -197,6 +206,7 @@ def get_latest_unit_version(unit_pk: int) -> UnitVersion:
 @dataclass(frozen=True)
 class UnitListEntry:
     """
+    [ 🛑 UNSTABLE ]
     Data about a single entity in a container, e.g. a component in a unit.
     """
     component_version: ComponentVersion
@@ -211,6 +221,7 @@ def get_components_in_draft_unit(
     unit: Unit,
 ) -> list[UnitListEntry]:
     """
+    [ 🛑 UNSTABLE ]
     Get the list of entities and their versions in the draft version of the
     given container.
     """
@@ -228,6 +239,7 @@ def get_components_in_published_unit(
     unit: Unit | UnitVersion,
 ) -> list[UnitListEntry]:
     """
+    [ 🛑 UNSTABLE ]
     Get the list of entities and their versions in the draft version of the
     given container.
     """

tests/openedx_learning/apps/authoring/units/test_api.py

@@ -305,18 +305,19 @@ def test_query_count_of_contains_unpublished_changes(self):
         with self.assertNumQueries(2):
             assert authoring_api.contains_unpublished_changes(unit) == True
 
+    # Test that soft-deleting a component doesn't show the unit as changed but does show it contains changes ?
     # Test that only components can be added to units
     # Test that components must be in the same learning package
     # Test that _version_pks=[] arguments must be related to publishable_entities_pks
-    # Test that publishing a unit publishes its child components (either automatically or throws an exception if you
-    #     don't request the children be published together with the containeer)
+    # Test that publishing a unit publishes its child components automatically
     # Test that publishing a component does NOT publish changes to its parent unit
     # Test that I can get a history of a given unit and all its children, including children that aren't currently in
     #     the unit and excluding children that are only in other units.
     # Test that I can get a history of a given unit and its children, that includes changes made to the child components
     #     while they were part of the unit but excludes changes made to those children while they were not part of
     #     the unit. 🫣
-    # Test viewing old snapshots of units and components by passing in a timestamp to some get_historic_unit() API?
+    # Test viewing old snapshots of units and components by passing in a timestamp (or PublishLog PK) to a
+    #     get_historic_unit() API?
 
 
     def test_next_version_with_different_different_title(self):