feat: Create basket lazy (#101)

Instead of creating a basket always this PR changes the behavior to a
lazy creation. The basket will from now on only created on `article_add`
or if `basket_view` oder `get_current_session_cart_key` has been
explicit called with `create_if_missing=True`.

Author: sveneberth

src/viur/shop/modules/api.py

@@ -1,10 +1,10 @@
 import typing as t  # noqa
 
 from google.protobuf.message import DecodeError
-from viur.core import current, db, errors, exposed, force_post
-from viur.core.render.json.default import DefaultRender as JsonRenderer
 
 import viur.shop.types.exceptions as e
+from viur.core import current, db, errors, exposed, force_post
+from viur.core.render.json.default import DefaultRender as JsonRenderer
 from viur.shop.modules.abstract import ShopModuleAbstract
 from viur.shop.skeletons import ShippingSkel
 from viur.shop.types import *
@@ -48,12 +48,22 @@ def article_add(
         article_key: str | db.Key,
         quantity: int = 1,
         quantity_mode: QuantityMode = QuantityMode.REPLACE,
-        parent_cart_key: str | db.Key,
+        parent_cart_key: str | db.Key | t.Literal["BASKET"] = SENTINEL,
         **kwargs,
     ):
-        """Add an article to the cart"""
+        """Add an article to the cart
+
+        :param article_key: Key of the article to add.
+        :param quantity: Quantity of the article to add.
+        :param quantity_mode: Behavior of the quantity: absolute or relative valuation
+        :param parent_cart_key: Key of the (sub) cart (node) to which
+            this leaf will be added as a child.
+            Use "BASKET" as key to use the basket of the current session.
+        """
         article_key = self._normalize_external_key(
             article_key, "article_key")
+        if parent_cart_key == "BASKET":
+            parent_cart_key = self.shop.cart.get_current_session_cart_key(create_if_missing=True)
         parent_cart_key = self._normalize_external_key(
             parent_cart_key, "parent_cart_key")
         assert isinstance(quantity_mode, QuantityMode)
@@ -73,12 +83,23 @@ def article_update(
         article_key: str | db.Key,
         quantity: int,
         quantity_mode: QuantityMode = QuantityMode.REPLACE,
-        parent_cart_key: str | db.Key,
+        parent_cart_key: str | db.Key | t.Literal["BASKET"] = SENTINEL,
         **kwargs,
     ):
-        """Update an existing article in the cart"""
+        """Update an existing article in the cart
+
+        :param article_key: Key of the article to update.
+            Note: This is not the key of the leaf skel!
+        :param quantity: Quantity of the article to update.
+        :param quantity_mode: Behavior of the quantity: absolute or relative valuation
+        :param parent_cart_key: Optional. Key of the (sub) cart (node) to which
+            this leaf will be moved to as a child.
+            Use "BASKET" as key to use the basket of the current session.
+        """
         article_key = self._normalize_external_key(
             article_key, "article_key")
+        if parent_cart_key == "BASKET":
+            parent_cart_key = self.shop.cart.get_current_session_cart_key(create_if_missing=True)
         parent_cart_key = self._normalize_external_key(
             parent_cart_key, "parent_cart_key")
         assert isinstance(quantity_mode, QuantityMode)
@@ -260,19 +281,33 @@ def cart_clear(
     def basket_list(
         self,
     ):
-        """List the children of the basket (the cart stored in the session)"""
+        """List the children of the basket (the cart stored in the session)
+
+        :raises errors.PreconditionFailed: If no basket created yet for this session
+        """
+        if self.shop.cart.current_session_cart_key is None:
+            raise errors.PreconditionFailed("No basket created yet for this session")  # TODO(discuss): explicit?
+            return []  # TODO(discuss): implicit?
         return self.cart_list(cart_key=self.shop.cart.current_session_cart_key)
 
     @exposed
     def basket_view(
         self,
+        *,
+        create_if_missing: bool = False,
     ):
         """View the basket (the cart stored in the session) itself
 
+        :param create_if_missing: Create the basket if not already created for this session
+        :raises errors.PreconditionFailed: If no basket created yet for this session (and it should not be created)
+
         See also :meth:`basket_view` to view any cart.
         """
+        cart_key = self.shop.cart.get_current_session_cart_key(create_if_missing=create_if_missing)
+        if cart_key is None:
+            raise errors.PreconditionFailed("No basket created yet for this session")
         return JsonResponse(self.shop.cart.cart_get(
-            cart_key=self.shop.cart.current_session_cart_key, skel_type="node",
+            cart_key=cart_key, skel_type="node",
         ))
 
     @exposed
@@ -506,6 +541,8 @@ def _normalize_external_key(
             return None
         elif not external_key:
             raise InvalidKeyException(external_key, parameter_name)
+        if isinstance(external_key, db.Key):
+            return external_key
         try:
             return db.Key.from_legacy_urlsafe(external_key)
         except (ValueError, DecodeError):  # yes, the exception really comes from protobuf...

src/viur/shop/modules/cart.py

@@ -58,32 +58,35 @@ def canView(self, skelType: SkelType, skel: SkeletonInstance) -> bool:
     # --- Session -------------------------------------------------------------
 
     @property
-    def current_session_cart_key(self):
+    def current_session_cart_key(self) -> db.Key | None:
+        return self.get_current_session_cart_key(create_if_missing=False)
+
+    def get_current_session_cart_key(self, *, create_if_missing: bool = False) -> db.Key | None:
         if user := current.user.get():
             user_skel = conf.main_app.vi.user.viewSkel()
             user_skel.read(user["key"])
             if user_skel["basket"]:
                 self.session["session_cart_key"] = user_skel["basket"]["dest"]["key"]
                 current.session.get().markChanged()
-        self._ensure_current_session_cart()
+        if create_if_missing:
+            self._ensure_current_session_cart()
         return self.session.get("session_cart_key")
 
     @property
-    def current_session_cart(self):  # TODO: Caching
+    def current_session_cart(self) -> SkeletonInstance_T[CartNodeSkel]:  # TODO: Caching
         skel = self.viewSkel("node")
-        if not skel.read(self.current_session_cart_key):
+        if not skel.read(self.get_current_session_cart_key(create_if_missing=True)):
             logger.critical(f"Invalid session_cart_key {self.current_session_cart_key} ?! Not in DB!")
             self.detach_session_cart()
             return self.current_session_cart
             raise InvalidStateError(f"Invalid session_cart_key {self.current_session_cart_key} ?! Not in DB!")
-        return skel
+        return skel  # type: ignore
 
-    def _ensure_current_session_cart(self):
+    def _ensure_current_session_cart(self) -> db.Key:
         if not self.session.get("session_cart_key"):
             root_node = self.addSkel("node")
-            user = current.user.get() and current.user.get()["name"] or "__guest__"
             root_node["is_root_node"] = True
-            root_node["name"] = f"Session Cart of {user} created at {utils.utcNow()}"
+            root_node["name"] = root_node.name.getDefaultValue(root_node)
             root_node["cart_type"] = CartType.BASKET
             root_node.write()
             self.session["session_cart_key"] = root_node["key"]
@@ -110,7 +113,9 @@ def _set_basket_txn(user_key: db.Key, basket_key: db.Key | None) -> SkeletonInst
         return user_skel
 
     def get_available_root_nodes(self, *args, **kwargs) -> list[dict[t.Literal["name", "key"], str]]:
-        root_nodes = [self.current_session_cart]
+        root_nodes = []
+        if self.current_session_cart_key is not None:
+            root_nodes.append(self.current_session_cart)
 
         if user := current.user.get():
             for wishlist in user["wishlist"]:

src/viur/shop/modules/discount.py

@@ -79,6 +79,8 @@ def apply(
         if not bool(code) ^ bool(discount_key):
             raise ValueError(f"Need code xor discount_code")
         cart_key = self.shop.cart.current_session_cart_key  # TODO: parameter?
+        if cart_key is None:
+            raise errors.PreconditionFailed("No basket created yet for this session")
 
         skels = self.search(code, discount_key)
         # logger.debug(f"{skels = }")

src/viur/shop/skeletons/cart.py

@@ -2,7 +2,7 @@
 import typing as t  # noqa
 
 from viur import toolkit
-from viur.core import db
+from viur.core import current, db, utils
 from viur.core.bones import *
 from viur.core.prototypes.tree import TreeSkel
 from viur.core.skeleton import SkeletonInstance
@@ -195,6 +195,10 @@ class CartNodeSkel(TreeSkel):  # STATE: Complete (as in model)
     )
 
     name = StringBone(
+        defaultValue=lambda skel, bone: (
+            f"Session Cart of {current.user.get() and current.user.get()["name"] or "__guest__"}"
+            f" created at {utils.utcNow()}"
+        )
     )
 
     cart_type = SelectBone(