feat: Implement cart_clear API method and the corresponding internal method (#170)

Author: sveneberth

src/viur/shop/data/translations.py

@@ -941,5 +941,12 @@
         "de": "Name",
         "en": "Name",
     },
+
+    # --- Errors --------------------------------------------------------------
+    "viur.shop.error.cart.is_frozen": {
+        # note: {{cart_key}} is a substitution variable for translations, not for an f-string!
+        "en": r"The cart {{cart_key}} can no longer be edited.",
+        "de": r"Der Warenkorb {{cart_key}} kann nicht mehr bearbeitet werden.",
+    }
 }
 """Initial translations used inside the viur-shop backend"""

src/viur/shop/modules/api.py

@@ -207,7 +207,7 @@ def cart_update(
         *,
         cart_key: str | db.Key,
         cart_type: CartType = SENTINEL,  # TODO: necessary?
-        name: str = None,
+        name: str = SENTINEL,
         customer_comment: str = SENTINEL,
         shipping_address_key: str | db.Key = SENTINEL,
         shipping_key: str | db.Key = SENTINEL,
@@ -267,15 +267,20 @@ def cart_remove(
     def cart_clear(
         self,
         *,
-        cart_key: str | db.Key,
-        remove_sub_carts: bool = False,
+        cart_key: str | db.Key | t.Literal["BASKET"] = SENTINEL,
+        keep_sub_carts: bool = False,
     ):
         """Remove direct or all children
 
-        :param remove_sub_carts: Remove child leafs, keep nodes
+        :param cart_key: Key of the (sub) cart (node) from which
+            the children should be removed.
+            Use "BASKET" as key to use the basket of the current session.
+        :param keep_sub_carts: Keep child nodes, remove only leafs
         """
+        if cart_key == "BASKET":
+            cart_key = self.shop.cart.get_current_session_cart_key(create_if_missing=False)
         cart_key = self._normalize_external_key(cart_key, "cart_key")
-        raise errors.NotImplemented  # TODO
+        return JsonResponse(self.shop.cart.cart_clear(cart_key, keep_sub_carts=keep_sub_carts))
 
     @exposed
     def basket_list(

src/viur/shop/modules/cart.py

@@ -2,7 +2,7 @@
 
 import viur.shop.types.exceptions as e
 from viur import toolkit
-from viur.core import conf, current, db, errors, exposed
+from viur.core import conf, current, db, errors, exposed, translate
 from viur.core.bones import BaseBone
 from viur.core.prototypes import Tree
 from viur.core.prototypes.tree import SkelType
@@ -544,6 +544,31 @@ def cart_remove(
                 # current.session.get().markChanged()
         EVENT_SERVICE.call(Event.CART_CHANGED, skel=skel, deleted=True)
 
+    def cart_clear(
+        self,
+        cart_key: db.Key,
+        *,
+        keep_sub_carts: bool = False,
+    ) -> None:
+        cart_skel = self.editSkel("node")
+        if not cart_skel.read(cart_key):
+            raise errors.NotFound
+        if cart_skel["is_frozen"]:
+            raise errors.Forbidden(
+                translate("viur.shop.error.cart.is_frozen",
+                          default_variables={"cart_key": cart_key})
+            )
+
+        for leaf_skel in toolkit.iter_skel(self.editSkel("leaf").all().filter("parententry =", cart_skel["key"])):
+            leaf_skel.delete()
+
+        if not keep_sub_carts:
+            for node_skel in toolkit.iter_skel(self.editSkel("node").all().filter("parententry =", cart_skel["key"])):
+                self.cart_clear(node_skel["key"], keep_sub_carts=keep_sub_carts)
+                node_skel.delete()
+
+        EVENT_SERVICE.call(Event.CART_CHANGED, skel=cart_skel, cleared=True)
+
     # --- Hooks ---------------------------------------------------------------
 
     def additional_add_or_update_article(