📝 Add docstrings to MPT-16255/Seeding-for-catalog

Docstrings generation was requested by @albertsola.

* #152 (comment)

The following files were modified:

* `seed/accounts/api_tokens.py`
* `seed/accounts/buyer.py`
* `seed/accounts/licensee.py`
* `seed/accounts/module.py`
* `seed/accounts/seller.py`
* `seed/accounts/user_group.py`
* `seed/catalog/authorization.py`
* `seed/catalog/catalog.py`
* `seed/catalog/item.py`
* `seed/catalog/listing.py`
* `seed/catalog/price_list.py`
* `seed/catalog/product.py`
* `seed/context.py`
* `seed/helper.py`
* `seed/seed_api.py`
* `tests/seed/catalog/test_authorization.py`
* `tests/seed/catalog/test_listing.py`
* `tests/seed/catalog/test_price_list.py`
* `tests/seed/catalog/test_product.py`

Author: coderabbitai[bot]

seed/accounts/api_tokens.py

@@ -16,7 +16,14 @@ async def get_api_token(
     context: Context = Provide[Container.context],
     mpt_ops: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> ApiToken | None:
-    """Get API token from context or fetch from API."""
+    """
+    Retrieve the ApiToken from context if present; otherwise fetch it from the API and store it in context.
+    
+    If the token is fetched, it is saved in the context resources under "accounts.api_token" and "accounts.api_token.id" is updated.
+    
+    Returns:
+        `ApiToken` if found or fetched, `None` if no token id is present in context.
+    """
     api_token_id = context.get_string("accounts.api_token.id")
     if not api_token_id:
         return None
@@ -36,7 +43,19 @@ async def get_api_token(
 def build_api_token_data(
     context: Context = Provide[Container.context],
 ) -> dict[str, object]:
-    """Get API token data dictionary for creation."""
+    """
+    Builds the dictionary of fields required to create an API token used for end-to-end testing.
+    
+    The returned mapping includes:
+    - `account`: `{"id": <CLIENT_ACCOUNT_ID environment variable>}`
+    - `name`: token display name
+    - `description`: token description
+    - `icon`: token icon (empty string when not set)
+    - `modules`: list containing a module object with `id` read from the context key "accounts.module.id"
+    
+    Returns:
+        dict[str, object]: The payload suitable for API token creation.
+    """
     account_id = os.getenv("CLIENT_ACCOUNT_ID")
     module_id = context.get_string("accounts.module.id")
     return {
@@ -53,7 +72,14 @@ async def init_api_token(
     context: Context = Provide[Container.context],
     mpt_ops: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> ApiToken:
-    """Get or create API token."""
+    """
+    Ensure an API token exists for the account, creating and persisting one if necessary.
+    
+    If an API token is not already available, creates a new token and stores it in the context resource "accounts.api_token" and updates "accounts.api_token.id".
+    
+    Returns:
+        ApiToken: The existing or newly created API token instance.
+    """
     api_token = await get_api_token(context=context, mpt_ops=mpt_ops)
     if api_token is None:
         logger.debug("Creating API token ...")
@@ -72,4 +98,4 @@ async def seed_api_token() -> None:
     """Seed API token."""
     logger.debug("Seeding API token ...")
     await init_api_token()
-    logger.debug("Seeding API token completed.")
+    logger.debug("Seeding API token completed.")

seed/accounts/buyer.py

@@ -19,7 +19,14 @@ async def get_buyer(
     context: Context = Provide[Container.context],
     mpt_operations: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> Buyer | None:
-    """Get buyer from context or fetch from API."""
+    """
+    Retrieve the buyer identified by "accounts.buyer.id" from the context or fetch it from the API and cache it.
+    
+    If the context does not contain "accounts.buyer.id", returns `None`. If the id exists but no valid Buyer instance is cached, fetches the buyer from the API, stores it in the context under "accounts.buyer", updates "accounts.buyer.id" with the fetched buyer's id, and returns the Buyer.
+    
+    Returns:
+        Buyer or `None` if "accounts.buyer.id" is not set in the context.
+    """
     buyer_id = context.get_string("accounts.buyer.id")
     if not buyer_id:
         return None
@@ -37,7 +44,21 @@ async def get_buyer(
 
 @inject
 def build_buyer_data(context: Context = Provide[Container.context]) -> dict[str, object]:
-    """Build buyer data dictionary for creation."""
+    """
+    Builds the payload dictionary used to create a buyer in the MPT API.
+    
+    Reads CLIENT_ACCOUNT_ID from the environment and `accounts.seller.id` from the provided context to populate required account and seller references.
+    
+    Parameters:
+    	context (Context): Application context used to read `accounts.seller.id`.
+    
+    Returns:
+    	dict[str, object]: Buyer data payload including name, account, sellers, contact, and address.
+    
+    Raises:
+    	ValueError: If CLIENT_ACCOUNT_ID environment variable is missing.
+    	ValueError: If `accounts.seller.id` is not found in the context.
+    """
     buyer_account_id = os.getenv("CLIENT_ACCOUNT_ID")
     if not buyer_account_id:
         raise ValueError("CLIENT_ACCOUNT_ID environment variable is required")
@@ -68,7 +89,15 @@ async def init_buyer(
     context: Context = Provide[Container.context],
     mpt_operations: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> Buyer:
-    """Get or create buyer."""
+    """
+    Ensure a Buyer exists in the provided context, creating one via the API if none is present.
+    
+    Returns:
+        Buyer: The existing or newly created Buyer instance.
+    
+    Raises:
+        ValueError: If buyer creation via the API fails.
+    """
     buyer = await get_buyer(context=context, mpt_operations=mpt_operations)
     if buyer is None:
         buyer_data = build_buyer_data(context=context)
@@ -91,4 +120,4 @@ async def seed_buyer() -> None:
     """Seed buyer."""
     logger.debug("Seeding buyer ...")
     await init_buyer()
-    logger.debug("Seeding buyer completed.")
+    logger.debug("Seeding buyer completed.")

seed/accounts/licensee.py

@@ -19,7 +19,14 @@ async def get_licensee(
     context: Context = Provide[Container.context],
     mpt_client: AsyncMPTClient = Provide[Container.mpt_client],
 ) -> Licensee | None:
-    """Get licensee from context or fetch from API."""
+    """
+    Retrieve the current licensee from the context or fetch it from the MPT API and cache it in the context.
+    
+    If a licensee is not present in the context but a licensee id exists, the function fetches the licensee from the MPT API, stores the licensee as the context resource "accounts.licensee", and updates "accounts.licensee.id" in the context.
+    
+    Returns:
+        Licensee | None: `Licensee` instance if found, `None` if no licensee id is present.
+    """
     licensee_id = context.get_string("accounts.licensee.id")
     if not licensee_id:
         return None
@@ -39,7 +46,20 @@ async def get_licensee(
 def build_licensee_data(  # noqa: WPS238
     context: Context = Provide[Container.context],
 ) -> dict[str, object]:
-    """Get licensee data dictionary for creation."""
+    """
+    Constructs a licensee payload dictionary used to create a licensee.
+    
+    Parameters:
+        context (Context): Context used to read required values: `accounts.seller.id`, `accounts.buyer.id`, and the `accounts.user_group` resource.
+    
+    Returns:
+        dict[str, object]: A dictionary containing licensee fields required by the API (name, address, seller, buyer, account, eligibility, groups, type, status, and defaultLanguage).
+    
+    Raises:
+        ValueError: If the environment variable `CLIENT_ACCOUNT_ID` is not set.
+        ValueError: If `accounts.seller.id` or `accounts.buyer.id` is missing from the context.
+        ValueError: If the `accounts.user_group` resource is missing from the context.
+    """
     account_id = os.getenv("CLIENT_ACCOUNT_ID")
     if not account_id:
         raise ValueError("CLIENT_ACCOUNT_ID environment variable is required")
@@ -79,7 +99,17 @@ async def init_licensee(
     context: Context = Provide[Container.context],
     mpt_client: AsyncMPTClient = Provide[Container.mpt_client],
 ) -> Licensee:
-    """Get or create licensee."""
+    """
+    Ensure a licensee exists for the current context, creating one if none is present.
+    
+    If no licensee is found in the provided context, attempts to create one using the MPT client and the prepared licensee data, then stores the created licensee in the context.
+    
+    Returns:
+    	The Licensee instance associated with the context.
+    
+    Raises:
+    	ValueError: If licensee creation fails.
+    """
     licensee = await get_licensee(context=context, mpt_client=mpt_client)
     if licensee is None:
         licensee_data = build_licensee_data(context=context)
@@ -102,4 +132,4 @@ async def seed_licensee() -> None:
     """Seed licensee."""
     logger.debug("Seeding licensee ...")
     await init_licensee()
-    logger.info("Seeding licensee completed.")
+    logger.info("Seeding licensee completed.")

seed/accounts/module.py

@@ -16,7 +16,14 @@ async def get_module(
     context: Context = Provide[Container.context],
     mpt_operations: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> Module | None:
-    """Get module from context or fetch from API."""
+    """
+    Retrieve the Module stored in the context or fetch it from the API if not cached.
+    
+    If the context does not contain "accounts.module.id", returns None. When a cached resource is absent or not a Module, the function fetches the module from the API and stores it in the context.
+    
+    Returns:
+        Module if found or fetched, `None` if "accounts.module.id" is not set.
+    """
     module_id = context.get_string("accounts.module.id")
     if not module_id:
         return None
@@ -37,7 +44,14 @@ async def refresh_module(
     context: Context = Provide[Container.context],
     mpt_operations: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> Module | None:
-    """Refresh module in context (always fetch)."""
+    """
+    Ensure the context contains a current "Access Management" Module by fetching it if missing.
+    
+    If the context has no module, query the API for modules named "Access Management". Cache the first found Module in the context under "accounts.module" and store its id at "accounts.module.id". Logs a warning and returns None if no suitable Module is found.
+    
+    Returns:
+        Module if available, None otherwise.
+    """
     module = await get_module(context=context, mpt_operations=mpt_operations)
     if module is None:
         filtered_modules = mpt_operations.accounts.modules.filter(
@@ -69,4 +83,4 @@ async def seed_module() -> Module:
             raise ValueError("Could not seed module: no valid Module found.")
         return refreshed
     logger.debug("Seeding module completed.")
-    return existing_module
+    return existing_module

seed/accounts/seller.py

@@ -17,7 +17,14 @@ async def get_seller(
     context: Context = Provide[Container.context],
     mpt_operations: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> Seller | None:
-    """Get seller from context or fetch from API."""
+    """
+    Retrieve the Seller stored in the provided context or fetch it from the API and cache it in context.
+    
+    If the context does not contain a seller id ("accounts.seller.id"), returns `None`. If a seller id exists but the context has no matching Seller resource, fetches the Seller using the provided MPT client, stores the Seller in the context under "accounts.seller" and updates "accounts.seller.id" with the Seller's id before returning it.
+    
+    Returns:
+        Seller | None: The Seller retrieved from context or API, or `None` if no seller id is present.
+    """
     seller_id = context.get_string("accounts.seller.id")
     if not seller_id:
         return None
@@ -57,7 +64,14 @@ async def init_seller(
     context: Context = Provide[Container.context],
     mpt_operations: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> Seller | None:
-    """Get or create seller. Returns Seller if successful, None otherwise."""
+    """
+    Ensure a seller exists in the provided context by retrieving it or creating a new one.
+    
+    If no seller is found in context, a seller will be created via the MPT API. On successful creation the function sets the created Seller in the context under "accounts.seller" and its id under "accounts.seller.id".
+    
+    Returns:
+        `Seller` if the seller was retrieved or created, `None` otherwise.
+    """
     seller = await get_seller(context=context, mpt_operations=mpt_operations)
     if seller is None:
         logger.debug("Creating seller ...")
@@ -79,4 +93,4 @@ async def seed_seller() -> None:
     """Seed seller."""
     logger.debug("Seeding seller ...")
     await init_seller()
-    logger.debug("Seeding seller completed.")
+    logger.debug("Seeding seller completed.")

seed/accounts/user_group.py

@@ -17,7 +17,12 @@ async def get_user_group(
     context: Context = Provide[Container.context],
     mpt_operations: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> UserGroup | None:
-    """Get user group from context or fetch from API."""
+    """
+    Retrieve a UserGroup from the context or fetch it from the API when not present in the context.
+    
+    Returns:
+        The retrieved `UserGroup` if available (from context or fetched), `None` if no user group ID is set in the context.
+    """
     user_group_id = context.get_string("accounts.user_group.id")
     if not user_group_id:
         return None
@@ -37,7 +42,21 @@ async def get_user_group(
 def build_user_group_data(
     context: Context = Provide[Container.context],
 ) -> dict[str, object]:
-    """Get user group data dictionary for creation."""
+    """
+    Builds the payload dictionary used to create a UserGroup.
+    
+    Returns:
+        dict: Payload with keys:
+            - name: display name for the user group
+            - account: dict containing the account `id` from the CLIENT_ACCOUNT_ID environment variable
+            - buyers: currently `None`
+            - logo: string (empty by default)
+            - description: textual description
+            - modules: list containing a dict with the module `id` read from context ("accounts.module.id")
+    
+    Raises:
+        ValueError: If the CLIENT_ACCOUNT_ID environment variable is not set.
+    """
     account_id = os.getenv("CLIENT_ACCOUNT_ID")
     if not account_id:
         raise ValueError("CLIENT_ACCOUNT_ID environment variable is required")
@@ -57,7 +76,14 @@ async def init_user_group(
     context: Context = Provide[Container.context],
     mpt_operations: AsyncMPTClient = Provide[Container.mpt_operations],
 ) -> UserGroup | None:
-    """Get or create user group."""
+    """
+    Ensure a UserGroup exists for the current context, creating and storing one if it does not.
+    
+    If an existing UserGroup is present in the context it is returned unchanged. When creation succeeds the new UserGroup is saved in the context under "accounts.user_group" and "accounts.user_group.id".
+    
+    Returns:
+        UserGroup | None: The retrieved or newly created `UserGroup`, or `None` if creation failed or no group could be obtained.
+    """
     user_group = await get_user_group(context=context, mpt_operations=mpt_operations)
     if user_group is not None:
         logger.info("User group already exists: %s", user_group.id)
@@ -82,4 +108,4 @@ async def seed_user_group() -> UserGroup | None:
     logger.debug("Seeding user group ...")
     user_group = await init_user_group()
     logger.debug("Seeding user group completed.")
-    return user_group
+    return user_group

seed/catalog/authorization.py

@@ -10,15 +10,24 @@
 
 
 async def seed_authorization() -> None:
-    """Seed authorization."""
+    """
+    Ensure the catalog authorization resource is seeded.
+    
+    Creates the authorization resource if it does not exist and stores its identifier under the context key "catalog.authorization.id".
+    """
     await init_resource("catalog.authorization.id", create_authorization)
 
 
 async def create_authorization(
     operations: AsyncMPTClient = Provide[Container.mpt_operations],
     context: Context = Provide[Container.context],
 ) -> Authorization:
-    """Creates an authorization."""
+    """
+    Create an authorization in the catalog using required IDs from the provided context.
+    
+    Returns:
+        Authorization: The created Authorization object returned by the catalog service.
+    """
     product_id = require_context_id(context, "catalog.product.id", "Create authorization")
     seller_id = require_context_id(context, "accounts.seller.id", "Create authorization")
     account_id = require_context_id(context, "accounts.account.id", "Create authorization")
@@ -35,4 +44,4 @@ async def create_authorization(
         "name": "E2E Seeded",
         "vendor": {"id": account_id},
     }
-    return await operations.catalog.authorizations.create(authorization_data)
+    return await operations.catalog.authorizations.create(authorization_data)

seed/catalog/catalog.py

@@ -9,11 +9,15 @@
 
 
 async def seed_catalog() -> None:
-    """Seed catalog data including products, item groups, and parameters."""
+    """
+    Seed catalog data in a defined sequence.
+    
+    Seeds products first, then authorization data, then price lists, and finally listings to ensure dependent catalog data is created in order.
+    """
     logger.debug("Seeding catalog ...")
     await seed_product()
     await seed_authorization()
     await seed_price_list()
     await seed_listing()
 
-    logger.debug("Seeded catalog completed.")
+    logger.debug("Seeded catalog completed.")