fix: improve docstring and add log messages (#1310)

* fix: add LOG_LEVEL envvar in .env file

* docs: add docstrings and debug log messages

* fix: add --overwrite option to generate-ocr-result CLI command

.env

@@ -90,3 +90,6 @@ ENABLE_MONGODB_ACCESS=0
 # gunicorn --auto-reload is not compatible with preload_app
 # so it has to be disabled when developing, to allow hot reload
 GUNICORN_PRELOAD_APP=0
+
+# The log level for the robotoff service
+LOG_LEVEL=DEBUG

robotoff/app/api.py

@@ -1019,7 +1019,14 @@ def on_get(self, req: falcon.Request, resp: falcon.Response):
         resp.media = {"logos": items, "count": query_count}
 
 
-def check_logo_annotation(type_: str, value: Optional[str] = None):
+def check_logo_annotation(type_: str, value: str | None = None) -> None:
+    """Check if the log annotation type and value are valid, and raise an
+    exception if not.
+
+    :param type_: the annotation type (brand, category, label, store)
+    :param value: the annotation value, if any
+    :raises falcon.HTTPBadRequest: if the annotation type or value is invalid
+    """
     if value is not None:
         if type_ == "label" and not is_prefixed_value(value):
             raise falcon.HTTPBadRequest(
@@ -1045,6 +1052,11 @@ def on_get(self, req: falcon.Request, resp: falcon.Response, logo_id: int):
     @jsonschema.validate(schema.UPDATE_LOGO_SCHEMA)
     def on_put(self, req: falcon.Request, resp: falcon.Response, logo_id: int):
         auth = parse_auth(req)
+        logger.info(
+            "Received logo annotation update request for logo %s (user: %s)",
+            logo_id,
+            auth.get_username() if auth else "unknown",
+        )
         media = req.get_media()
         if auth is None:
             raise falcon.HTTPForbidden(

robotoff/cli/main.py

@@ -828,6 +828,9 @@ def generate_ocr_result(
         dir_okay=True,
         help="Directory where the OCR JSON should be saved",
     ),
+    overwrite: bool = typer.Option(
+        False, help="Overwrite the output file if it already exists"
+    ),
 ) -> None:
     import os
 
@@ -846,6 +849,10 @@ def generate_ocr_result(
         str(source_image_path.parent).replace("/", "_")[1:]
         + f"_{source_image_path.stem}.json"
     )
+    if output_file.is_file() and not overwrite:
+        logger.info("Skipping %s, file already exists", output_file)
+        return
+
     logger.info("Downloading image %s", image_url)
     r = http_session.get(image_url)
     r.raise_for_status()

robotoff/logos.py

@@ -444,9 +444,17 @@ def generate_insights_from_annotated_logos_job(
 def generate_insights_from_annotated_logos(
     logos: list[LogoAnnotation], auth: OFFAuthentication, server_type: ServerType
 ) -> int:
-    """Generate and apply insights from annotated logos."""
+    """Generate and apply insights from annotated logos.
+
+    :param logos: a list of `LogoAnnotation` model instances, used to generate
+        insights
+    :param auth: the authentication credentials to use for the annotation
+    :param server_type: the server type (project) associated with the logos
+    :return: the number of insights annotated
+    """
     predictions = []
     for logo in logos:
+        logger.debug("Generating prediction for logo %s", logo.id)
         prediction = generate_prediction(
             logo_type=logo.annotation_type,
             logo_value=logo.taxonomy_value,
@@ -463,15 +471,19 @@ def generate_insights_from_annotated_logos(
         )
 
         if prediction is None:
+            logger.debug("No prediction generated for logo %s", logo.id)
             continue
 
         prediction.barcode = logo.barcode
         prediction.source_image = logo.source_image
+        logger.debug("Prediction generated for logo %s: %s", logo.id, prediction)
         predictions.append(prediction)
 
     import_result = import_insights(predictions, server_type)
     if import_result.created_predictions_count():
         logger.info(import_result)
+    else:
+        logger.debug("No insight created")
 
     annotated = 0
     for created_id in itertools.chain.from_iterable(