fix: Correct and extend several docstring and some smaller implementation fixes (viur-framework#130)

Author: sveneberth

src/viur/shop/modules/address.py

@@ -5,8 +5,9 @@
 from viur.core.prototypes.skelmodule import DEFAULT_ORDER_TYPE
 from viur.core.skeleton import SkeletonInstance
 from .abstract import ShopModuleAbstract
-from .. import AddressSkel, SkeletonInstance_T
 from ..globals import SHOP_LOGGER
+from ..skeletons import AddressSkel
+from ..types import SkeletonInstance_T
 
 logger = SHOP_LOGGER.getChild(__name__)
 

src/viur/shop/modules/order.py

@@ -439,7 +439,7 @@ def can_order(
         return errors
 
     def set_checkout_in_progress(self, order_skel: "SkeletonInstance") -> "SkeletonInstance":
-        """Set an order to the state _is_checkout_in_progress_"""
+        """Set an order to the state *is_checkout_in_progress*"""
         order_skel = toolkit.set_status(
             key=order_skel["key"],
             skel=order_skel,
@@ -450,7 +450,7 @@ def set_checkout_in_progress(self, order_skel: "SkeletonInstance") -> "SkeletonI
         return order_skel
 
     def set_ordered(self, order_skel: "SkeletonInstance", payment: t.Any) -> "SkeletonInstance":
-        """Set an order to the state _ordered_"""
+        """Set an order to the state *ordered*"""
         order_skel = toolkit.set_status(
             key=order_skel["key"],
             skel=order_skel,
@@ -461,7 +461,7 @@ def set_ordered(self, order_skel: "SkeletonInstance", payment: t.Any) -> "Skelet
         return order_skel
 
     def set_paid(self, order_skel: "SkeletonInstance") -> "SkeletonInstance":
-        """Set an order to the state _paid_"""
+        """Set an order to the state *paid*"""
         order_skel = toolkit.set_status(
             key=order_skel["key"],
             skel=order_skel,
@@ -472,7 +472,7 @@ def set_paid(self, order_skel: "SkeletonInstance") -> "SkeletonInstance":
         return order_skel
 
     def set_rts(self, order_skel: "SkeletonInstance") -> "SkeletonInstance":
-        """Set an order to the state _Ready to ship_"""
+        """Set an order to the state *Ready to ship*"""
         order_skel = toolkit.set_status(
             key=order_skel["key"],
             skel=order_skel,

src/viur/shop/payment_providers/__init__.py

@@ -7,7 +7,7 @@
 try:
     import unzer
 except ImportError:
-    # The unzer extras was not enabled, we don't import the related providers
+    # The unzer extra was not enabled, we don't import the related providers
     ...
 else:
     del unzer

src/viur/shop/payment_providers/abstract.py

@@ -18,7 +18,17 @@
 
 
 class PaymentProviderAbstract(InstancedModule, Module, abc.ABC):
+    """
+    Abstract base class for all payment providers in the ViUR Shop.
+
+    Provides a standardized interface for implementing different payment methods,
+    including methods for checkout, charging, and handling payment states.
+
+    Subclasses must implement the required methods to integrate specific payment providers.
+    """
+
     shop: "Shop" = None
+    """Reference to the main :class:`Shop` instance."""
 
     def __init__(
         self,

src/viur/shop/payment_providers/amazon_pay.py

@@ -10,6 +10,12 @@
 
 
 class AmazonPay(PaymentProviderAbstract):
+    """
+    Amazon Pay integration for the ViUR Shop.
+
+    Handles the checkout process using Amazon Pay, including authorization and payment capture.
+    Requires Amazon MWS credentials and configuration parameters.
+    """
     name: t.Final[str] = "amazonpay"
 
     def __init__(
@@ -26,6 +32,18 @@ def __init__(
         language: str = "en",
         **kwargs: t.Any,
     ) -> None:
+        """
+
+        :param mws_access_key: Amazon MWS access key.
+        :param mws_secret_key: Amazon MWS secret key.
+        :param merchant_id: Amazon merchant ID.
+        :param client_id: Amazon client ID.
+        :param client_secret: Amazon client secret.
+        :param region: Region code (default: 'de').
+        :param currency_code: Currency code (default: 'EUR').
+        :param sandbox: Use sandbox environment (default: False).
+        :param language: Language code (default: 'en').
+        """
         super().__init__(**kwargs)
         self.mws_access_key = mws_access_key
         self.mws_secret_key = mws_secret_key

src/viur/shop/payment_providers/invoice.py

@@ -12,10 +12,14 @@
 
 class Invoice(PaymentProviderAbstract):
     """
-    Order is directly RTS, but not paid.
+    Invoice payment method for the ViUR Shop.
 
-    The customer pays this order in the next x days, independent of shipping.
-    But this will not be handled or checked here.
+    Allows customers to place orders with the agreement to pay later via invoice.
+    The order can be marked as ready to ship (RTS) immediately but is not considered paid.
+
+    Note:
+        Payment processing (the customer pays this order in the next x days)
+        and verification are handled externally and not within this module.
     """
 
     name: t.Final[str] = "invoice"

src/viur/shop/payment_providers/paypal_plus.py

@@ -10,6 +10,13 @@
 
 
 class PayPalPlus(PaymentProviderAbstract):
+    """
+    PayPal Plus integration for the ViUR Shop.
+
+    Supports multiple payment methods through PayPal Plus, including PayPal, credit card, and more.
+    Handles the checkout process, payment state checks, and webhook handling for payment updates.
+    """
+
     name: t.Final[str] = "paypal_plus"
 
     def checkout(

src/viur/shop/payment_providers/prepayment.py

@@ -15,11 +15,18 @@
 
 class Prepayment(PaymentProviderAbstract):
     """
-    Order is RTS as soon as the customer has paid.
+    Prepayment method for the ViUR Shop.
+
+    Allows customers to place orders with the agreement to pay in advance.
+    The order is marked as ready to ship (RTS) once payment is received.
 
     The customer pays this order in the next x days, shipping will wait.
-    But this will not be handled or checked here.
+
+    Note:
+       Payment receipt verification (The customer pays this order in the next x days,
+       shipping will wait) is handled externally and not within this module.
     """
+
     name: t.Final[str] = "prepayment"
 
     def checkout(

src/viur/shop/payment_providers/unzer_abstract.py

@@ -26,7 +26,7 @@ class UnzerClientViURShop(unzer.UnzerClient):
     def _request(self, url, method, headers, payload, auth):
         # Extend with ViUR Logic:
         # Before the request is performed, we update the accept-language with
-        # the language of the current request, except it's explicit set.
+        # the language of the current request, unless it has been explicitly set.
         if self.language is None:
             # language for translation of customerMessage in errors
             headers["accept-language"] = current.language.get()
@@ -35,6 +35,12 @@ def _request(self, url, method, headers, payload, auth):
 
 
 class UnzerAbstract(PaymentProviderAbstract):
+    """
+    Abstract base class for Unzer payment methods in the ViUR Shop.
+
+    Provides common functionality for Unzer-based payment providers,
+    including API communication and payment type handling.
+    """
 
     def __init__(
         self,
@@ -155,14 +161,18 @@ def can_order(
     def charge(self):
         raise errors.NotImplemented()
 
-    def get_order_by_pay_id(self, payment_id, public_key, *args, **kwargs):
+    def get_order_by_pay_id(
+        self,
+        payment_id: str,
+        public_key: str,
+        *args, **kwargs
+    ) -> SkeletonInstance_T[OrderSkel] | None:
         """Helper method to get the order skel for a payment-id.
 
         :param payment_id: The payment id. (ex: s-pay-1).
         :param public_key: Public key of the key pair.
 
-        :return: The order-skel if the key seems to be valid. None otherwise.
-        :rtype: OrderSkel | None
+        :return: The order-skel if the key seems valid. None otherwise.
         """
         logger.debug(f"get_order_by_pay_id({payment_id=} | {public_key=})")
 
@@ -235,7 +245,7 @@ def webhook(self, *args, **kwargs):
             raise errors.BadRequest("Invalid payload")
         logger.info(f"Received request via webhook. {args=}, {kwargs=}")
         logger.info(f"{payload=}")
-        logger.info(f"headers={current.request.get().request.headers!r}")
+        logger.info(f"headers={dict(current.request.get().request.headers)!r}")
 
         ip = current.request.get().request.remote_addr
         logger.info(f"{ip=}")

src/viur/shop/payment_providers/unzer_bancontact.py

@@ -11,6 +11,12 @@
 
 
 class UnzerBancontact(UnzerAbstract):
+    """
+    Unzer Bancontact payment method integration for the ViUR Shop.
+
+    Enables customers to pay using Bancontact through the Unzer payment gateway.
+    """
+
     name: t.Final[str] = "unzer-bancontact"
 
     def get_payment_type(