Little readme comment

README.md

@@ -21,7 +21,7 @@ camisatoshi-wordpress-reports check-health
 ### Make a report for the UM agreement between two dates
 
 ```shell
-camisatoshi-wordpress-reports generate-um-report --start-date "2023-08-01T00:00:00" --end-date "2023-09-01T00:00:00"c
+camisatoshi-wordpress-reports generate-um-report --start-date "2023-08-01T00:00:00" --end-date "2023-09-01T00:00:00"
 ```
 
 This will generate a file named `report.csv` in the current working directory.
@@ -37,4 +37,5 @@ This will generate a file named `report.csv` in the current working directory.
 
 
 ## Open issues
-- Pagination is not being managed. The moment we have more than 100 orders, we are gonna run into issues.
+- Pagination is not being managed. The moment we have more than 100 orders, we are gonna run into issues.
+- Some reports will break if the SKU has absolutely no orders. But well, if that happens, there is simply no report to build, so the only serious improvement would be dropping an informative error message.

camisatoshi_wordpress_reports/cli.py

@@ -5,7 +5,10 @@ import typer
 from typing_extensions import Annotated
 
 import camisatoshi_wordpress_reports.controllers as controllers
+import camisatoshi_wordpress_reports.logging as our_logging
 
+
+our_logging.set_config_level()
 app = typer.Typer()
 
 
@@ -18,10 +21,11 @@ def check_health():
 def generate_sku_report(
     start_date: Annotated[datetime.datetime, typer.Option(prompt=True)],
     end_date: Annotated[datetime.datetime, typer.Option(prompt=True)],
-    sku: Annotated[str, typer.Option(prompt=True)]
+    sku: Annotated[str, typer.Option(prompt=True)],
 ):
     controllers.generate_sku_report(start_date, end_date, sku)
 
+
 @app.command()
 def generate_um_report(
     start_date: Annotated[datetime.datetime, typer.Option(prompt=True)],

camisatoshi_wordpress_reports/constants.py

@@ -6,23 +6,24 @@ DEFAULT_DOTENV_FILEPATH = ".camisatoshi-wordpress-reports/.env"
 
 ### Order keys
 
-order_keys = SimpleNamespace()
+ORDER_KEYS = SimpleNamespace()
-order_keys.meta_data = "meta_data"
+ORDER_KEYS.id = "id"
-order_keys.total = "total"
+ORDER_KEYS.meta_data = "meta_data"
-order_keys.line_items = "line_items"
+ORDER_KEYS.total = "total"
+ORDER_KEYS.line_items = "line_items"
 
-order_keys.line_item_keys = SimpleNamespace()
+ORDER_KEYS.line_item_keys = SimpleNamespace()
-order_keys.line_item_keys.sku = "sku"
+ORDER_KEYS.line_item_keys.sku = "sku"
-order_keys.line_item_keys.quantity = "quantity"
+ORDER_KEYS.line_item_keys.quantity = "quantity"
-order_keys.line_item_keys.total = "total"
+ORDER_KEYS.line_item_keys.total = "total"
 
-custom_meta_data_keys = SimpleNamespace()
+CUSTOM_META_DATA_KEYS = SimpleNamespace()
-custom_meta_data_keys.is_settled_um = "is_settled_um"
+CUSTOM_META_DATA_KEYS.is_settled_um = "is_settled_um"
-custom_meta_data_keys.sats_received = "sats_received"
+CUSTOM_META_DATA_KEYS.sats_received = "sats_received"
 
 
 ### Other
 
-um_first_agreement_percentage = 0.5
+UM_FIRST_AGREEMENT_PERCENTAGE = 0.5
-bbo_royalty_fee = 0.2
+BBO_ROYALTY_FEE_PERCENTAGE = 0.2
-
+BBO_SKUS = ["TEE-05-BBO-BLACK", "SUD-01-BBO-BLACK"]

camisatoshi_wordpress_reports/controllers.py

@@ -1,3 +1,4 @@
+from functools import partial
 from pathlib import Path
 import datetime
 import logging
@@ -8,9 +9,16 @@ from woocommerce import API
 
 from camisatoshi_wordpress_reports.order import Order, Orders
 from camisatoshi_wordpress_reports.constants import (
-    um_first_agreement_percentage,
+    ORDER_KEYS,
+    UM_FIRST_AGREEMENT_PERCENTAGE,
     DEFAULT_DOTENV_FILEPATH,
-    bbo_royalty_fee,
+    BBO_ROYALTY_FEE_PERCENTAGE,
+    BBO_SKUS,
+)
+from camisatoshi_wordpress_reports.report_building import (
+    OrderObtentionChainBuilder,
+    WoocomerceOrderScope,
+    keep_orders_containing_sku,
 )
 
 API_CONFIG = dotenv_values(
@@ -23,7 +31,6 @@ WC_API = API(
     version=API_CONFIG["VERSION"],
 )
 
-logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger()
 
 
@@ -67,10 +74,14 @@ def generate_um_report(
     )
     logger.info(f"Received {len(orders_in_date_range)} orders.")
 
-    relevant_sku = "TEE-05-BBO-BLACK"
+    relevant_skus = [
-    logger.info(f"Filtering by SKU: {relevant_sku}")
+        "TEE-05-BBO-BLACK",
-    relevant_orders = orders_in_date_range.filter_orders_by_sku(
+        "SUD-01-BBO-BLACK",
-        sku=relevant_sku
+        "TEE-09-SIMPLY-BITCOIN",
+    ]
+    logger.info(f"Filtering by SKUs: {relevant_skus}")
+    relevant_orders = orders_in_date_range.filter_orders_by_skus(
+        skus=relevant_skus
     )
     logger.info(f"Kept {len(relevant_orders)} orders.")
 
@@ -101,21 +112,35 @@ def generate_um_report(
         f"Relevant orders: {[order['id'] for order in unsettled_orders]}."
     )
     report = []
-    for order in unsettled_orders:
+    for relevant_sku in relevant_skus:
-        report.append(
+        logger.debug(f"Reporting SKU {relevant_sku}")
-            {
+        for order in unsettled_orders:
-                "order_id": order["id"],
+            if not order.contains_sku(relevant_sku):
-                "sku": relevant_sku,
+                continue
-                "units_sold": order.units_of_sku(relevant_sku),
+            logger.debug(f"Reporting for order {order[ORDER_KEYS.id]}")
-                "eur_income": order.sales_of_sku(relevant_sku),
+
-                "sats_income": order.sats_received_for_sku(relevant_sku),
+            # A few helper variables to make the last variable more understandable
-                "sats_owed_to_um": (
+            sats_received_for_sku = order.sats_received_for_sku(relevant_sku)
-                    order.sats_received_for_sku(relevant_sku)
+            bbo_fee_if_applicable = (BBO_ROYALTY_FEE_PERCENTAGE * (relevant_sku in BBO_SKUS))
-                    * (1 - bbo_royalty_fee)
+            discount_factor_for_bbo_skus = 1 - bbo_fee_if_applicable
-                )
+
-                * um_first_agreement_percentage,
+            # We owe UM his percentages of the sats received after discounting
-            }
+            # royalties paid to BBO for the BBO products.
-        )
+            sats_owed_to_um = (
+                (sats_received_for_sku * discount_factor_for_bbo_skus)
+                * UM_FIRST_AGREEMENT_PERCENTAGE
+            )
+
+            report.append(
+                {
+                    "order_id": order[ORDER_KEYS.id],
+                    "sku": relevant_sku,
+                    "units_sold": order.units_of_sku(relevant_sku),
+                    "eur_income": order.sales_of_sku(relevant_sku),
+                    "sats_income": sats_received_for_sku,
+                    "sats_owed_to_um": sats_owed_to_um,
+                }
+            )
     logger.info("Report generated.")
     logger.info(report)
 
@@ -130,41 +155,32 @@ def generate_um_report(
 def generate_sku_report(start_date, end_date, sku):
     logger.info(f"Fetching orders between {start_date} and {end_date}.")
 
-    orders_in_date_range = WC_API.get(
+    report_chain_builder = OrderObtentionChainBuilder()
-        endpoint="orders",
+
-        params={
+    report_chain_builder.add_order_fetching_step(
-            "after": start_date.isoformat(),
+        wc_order_scope=WoocomerceOrderScope(
-            "before": end_date.isoformat(),
+            after=start_date.isoformat(),
-            "per_page": 100,
+            before=end_date.isoformat(),
-            "status": "processing,completed",
+            status="processing,completed",
-        },
+        )
-    ).json()
-    orders_in_date_range = Orders(
-        [
-            Order.from_api_response(order_raw_data)
-            for order_raw_data in orders_in_date_range
-        ]
     )
-    logger.info(f"Received {len(orders_in_date_range)} orders.")
 
-    logger.info(f"Filtering by SKU: {sku}")
+    report_chain_builder.add_order_filtering_step(
-    relevant_orders = orders_in_date_range.filter_orders_by_sku(sku=sku)
+        partial(keep_orders_containing_sku, sku=sku)
-    logger.info(f"Kept {len(relevant_orders)} orders.")
-
-    logger.info("Order filtering finished.")
-
-    logger.info(
-        f"Relevant orders: {[order['id'] for order in relevant_orders]}."
     )
 
+    report_chain = report_chain_builder.get_report_chain()
+
+    relevant_orders = report_chain.run_chain(WC_API)
+
     report = []
     for order in relevant_orders:
         report.append(
             {
-                "order_id": order["id"],
+                "order_id": order[ORDER_KEYS.id],
                 "sku": sku,
-                "units_sold": order.units_of_sku(sku),
+                "units_sold": order.units_of_skus(sku),
-                "eur_income": order.sales_of_sku(sku),
+                "eur_income": order.sales_of_skus(sku),
             }
         )
     logger.info("Report generated.")

camisatoshi_wordpress_reports/logging.py

@@ -0,0 +1,5 @@
+import logging
+
+
+def set_config_level():
+    logging.basicConfig(level=logging.DEBUG)

camisatoshi_wordpress_reports/order.py

@@ -1,6 +1,10 @@
+import logging
 from typing import Dict, Collection
 
-from camisatoshi_wordpress_reports.constants import order_keys, custom_meta_data_keys
+from camisatoshi_wordpress_reports.constants import (
+    ORDER_KEYS,
+    CUSTOM_META_DATA_KEYS,
+)
 from camisatoshi_wordpress_reports.utils import safe_zero_division
 
 
@@ -15,30 +19,32 @@ class Order:
     def meta_data_entries(self):
         return {
             meta_data_entry["key"]: meta_data_entry["value"]
-            for meta_data_entry in self.raw_data[order_keys.meta_data]
+            for meta_data_entry in self.raw_data[ORDER_KEYS.meta_data]
         }
 
     def units_of_sku(self, sku: str) -> int:
         units = 0
-        for line in self[order_keys.line_items]:
+        for line in self[ORDER_KEYS.line_items]:
-            if line[order_keys.line_item_keys.sku] == sku:
+            if line[ORDER_KEYS.line_item_keys.sku] == sku:
-                units += line[order_keys.line_item_keys.quantity]
+                units += line[ORDER_KEYS.line_item_keys.quantity]
         return units
 
     def sales_of_sku(self, sku: str) -> float:
         sales = 0
-        for line in self[order_keys.line_items]:
+        for line in self[ORDER_KEYS.line_items]:
-            if line[order_keys.line_item_keys.sku] == sku:
+            if line[ORDER_KEYS.line_item_keys.sku] == sku:
-                sales += float(line[order_keys.line_item_keys.total])
+                sales += float(line[ORDER_KEYS.line_item_keys.total])
         return sales
 
     def sats_received_for_sku(self, sku: str) -> float:
-        total_order_eur = float(self[order_keys.total])
+        total_order_eur = float(self[ORDER_KEYS.total])
         eur_of_sku = self.sales_of_sku(sku)
 
-        monetary_weight_of_sku_in_order = safe_zero_division(eur_of_sku, total_order_eur)
+        monetary_weight_of_sku_in_order = safe_zero_division(
+            eur_of_sku, total_order_eur
+        )
         total_order_sats_received = float(
-            self.meta_data_entries[custom_meta_data_keys.sats_received]
+            self.meta_data_entries[CUSTOM_META_DATA_KEYS.sats_received]
         )
         sats_received_for_sku = (
             monetary_weight_of_sku_in_order * total_order_sats_received
@@ -47,8 +53,8 @@ class Order:
         return sats_received_for_sku
 
     def contains_sku(self, sku: str) -> bool:
-        for item in self[order_keys.line_items]:
+        for item in self[ORDER_KEYS.line_items]:
-            if item[order_keys.line_item_keys.sku] == sku:
+            if item[ORDER_KEYS.line_item_keys.sku] == sku:
                 return True
         return False
 
@@ -59,7 +65,7 @@ class Order:
 
     def is_settled_with_um(self):
         is_settled = self.meta_data_entries.get(
-            custom_meta_data_keys.is_settled_um, None
+            CUSTOM_META_DATA_KEYS.is_settled_um, None
         )
 
         return bool(is_settled)
@@ -87,6 +93,9 @@ class Orders:
             return next_order
         raise StopIteration
 
+    def __repr__(self):
+        return str([f"Order {order['id']}" for order in self])
+
     def filter_orders_by_sku(self, sku: str) -> "Orders":
         filtered_orders = []
 
@@ -96,11 +105,26 @@ class Orders:
 
         return Orders(filtered_orders)
 
+    def filter_orders_by_skus(self, skus: Collection[str]) -> "Orders":
+        filtered_orders = []
+
+        for order in self:
+            order_contains_at_least_one_of_the_skus = None # Guilty until proven innocent
+            for sku in skus:
+                if order.contains_sku(sku):
+                    order_contains_at_least_one_of_the_skus = True
+            if order_contains_at_least_one_of_the_skus:
+                filtered_orders.append(order)
+
+        return Orders(filtered_orders)
+
     def filter_orders_without_sats_received(self) -> "Orders":
         orders_without_sats_received = []
 
         for order in self:
-            if not order.contains_meta_data_entry(custom_meta_data_keys.sats_received):
+            if not order.contains_meta_data_entry(
+                CUSTOM_META_DATA_KEYS.sats_received
+            ):
                 orders_without_sats_received.append(order)
                 continue
 
@@ -114,3 +138,15 @@ class Orders:
                 unsettled_orders.append(order)
 
         return Orders(unsettled_orders)
+
+    def filter_orders_by_metadata_value(self, key, value):
+        orders_with_metadata_value = []
+
+        for order in self:
+            if (
+                order.contains_meta_data_entry(key)
+                and order.meta_data_entries[key] == value
+            ):
+                orders_with_metadata_value.append(order)
+
+        return Orders(orders_with_metadata_value)

camisatoshi_wordpress_reports/report_building.py

@@ -0,0 +1,163 @@
+import logging
+from functools import partial
+
+from woocommerce import API
+
+from camisatoshi_wordpress_reports.order import Orders, Order
+
+
+logger = logging.getLogger()
+
+
+class MetadataFilter:
+    def __init__(self, key, value, operator):
+        self.key = key
+        self.value = value
+        self.operator = operator
+
+    def order_satisfies_filter(self, order: Order) -> bool:
+        return self.operator(order.meta_data_entries[self.key], self.value)
+
+
+class WoocomerceOrderScope:
+
+    serializable_fields = ("after", "before", "status")
+
+    def __init__(self, after=None, before=None, status=None):
+        self.after = after
+        self.before = before
+        self.status = status
+
+    def serialize_for_api_request(self) -> dict:
+        params = {}
+
+        for field in self.serializable_fields:
+            if hasattr(self, field):
+                params[field] = self.__getattribute__(field)
+
+        params["per_page"] = 100
+
+        return params
+
+
+def fetch_orders_from_wc(
+    wc_api_client: API, wc_order_scope: WoocomerceOrderScope
+) -> Orders:
+
+    params = wc_order_scope.serialize_for_api_request()
+
+    orders_in_scope = wc_api_client.get(
+        endpoint="orders", params=params
+    ).json()
+    orders_in_scope = Orders(
+        [
+            Order.from_api_response(order_raw_data)
+            for order_raw_data in orders_in_scope
+        ]
+    )
+
+    return orders_in_scope
+
+
+def keep_orders_containing_sku(orders: Orders, sku: str) -> Orders:
+
+    return orders.filter_orders_by_sku(sku)
+
+
+def keep_orders_containing_metadata_value(
+    orders: Orders, metadata_key: str, metadata_value
+) -> Orders:
+
+    return orders.filter_orders_by_metadata_value(
+        key=metadata_key, value=metadata_value
+    )
+
+
+def validate_orders_satisfy_metadata_filter(
+    orders: Orders, metadata_filter: MetadataFilter
+) -> bool:
+
+    for order in orders:
+        if not metadata_filter.order_satisfies_filter(order):
+            return False
+
+    return True
+
+
+class OrderObtentionChain:
+    def __init__(self):
+        self.order_fetching_step = None
+        self.order_filtering_steps = []
+        self.order_validation_steps = []
+
+        self._orders = None
+
+    def run_chain(self, wc_api_client: API):
+        logger.info("Running report chain.")
+
+        self._run_order_fetching_step(wc_api_client)
+        self._run_order_filtering_steps()
+        self._run_order_validation_steps()
+
+        logger.info(f"Report chain ran. Returning {len(self._orders)} orders.")
+
+        return self._orders
+
+    def _run_order_fetching_step(self, wc_api_client: API) -> Orders:
+        logger.debug("Running order fetching step.")
+        self._orders = self.order_fetching_step(wc_api_client)
+        logger.debug(f"Received {len(self._orders)} orders.")
+
+    def _run_order_filtering_steps(self) -> Orders:
+        logger.debug(
+            f"Running {len(self.order_filtering_steps)} order filtering steps."
+        )
+        temp_orders = self._orders
+
+        for order_filtering_step in self.order_filtering_steps:
+            logger.debug(f"{len(temp_orders)} before filtering.")
+            temp_orders = order_filtering_step(temp_orders)
+            logger.debug(f"{len(temp_orders)} after filtering.")
+
+        self._orders = temp_orders
+
+    def _run_order_validation_steps(self):
+        for order_validation_step in self.order_validation_steps:
+            if not order_validation_step(self._orders):
+                raise ValueError("Error during order validation step.")
+
+
+class OrderObtentionChainBuilder:
+    def __init__(self):
+        self._wip_order_obtention_chain = OrderObtentionChain()
+
+    def add_order_fetching_step(
+        self, wc_order_scope: WoocomerceOrderScope
+    ) -> "OrderObtentionChainBuilder":
+        """
+        Define a scope of orders to get from Woocomerce.
+        """
+
+        self._order_scope = wc_order_scope
+
+        self._wip_order_obtention_chain.order_fetching_step = partial(
+            fetch_orders_from_wc, wc_order_scope=wc_order_scope
+        )
+
+        return self
+
+    def add_order_filtering_step(self, step) -> "OrderObtentionChainBuilder":
+
+        self._wip_order_obtention_chain.order_filtering_steps.append(step)
+
+        return self
+
+    def add_order_validation_step(self, step) -> "OrderObtentionChainBuilder":
+
+        self._wip_order_obtention_chain.order_validation_steps.append(step)
+
+        return self
+
+    def get_report_chain(self) -> OrderObtentionChain:
+
+        return self._wip_order_obtention_chain