Add logging.

Author: fkdosilovic

src/judge0/__init__.py

@@ -1,6 +1,9 @@
 import logging
+import logging.handlers
 import os
+import sys
 
+from pathlib import Path
 from typing import Union
 
 from .api import (
@@ -66,10 +69,79 @@
 JUDGE0_IMPLICIT_CE_CLIENT = None
 JUDGE0_IMPLICIT_EXTRA_CE_CLIENT = None
 
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except:  # noqa: E722
+    pass
+
+
+def setup_logging(
+    log_file: Path | None = None,
+    file_level: int | None = None,
+    console_level: int | None = None,
+) -> None:
+    """Set up logging for the package."""
+    if log_file is None:
+        try:
+            log_dir = Path.home() / ".judge0" / "logs"
+            log_dir.mkdir(parents=True, exist_ok=True)
+            log_file = log_dir / "judge0.log"
+        except (OSError, PermissionError):
+            # Fallback to user's current working directory
+            log_file = Path("judge0.log")
+
+    logger = logging.getLogger("judge0")
+    logger.setLevel(logging.DEBUG)
+
+    # Check if handlers are already added to avoid duplication.
+    if logger.hasHandlers():
+        return
+
+    # Determine log levels: parameter > env var > default
+    if file_level is None:
+        file_level = getattr(
+            logging, os.getenv("JUDGE0_FILE_LOG_LEVEL", "DEBUG").upper(), logging.DEBUG
+        )
+    if console_level is None:
+        console_level = getattr(
+            logging, os.getenv("JUDGE0_CONSOLE_LOG_LEVEL", "INFO").upper(), logging.INFO
+        )
+
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+
+    # File handler with weekly rotation.
+    file_handler = logging.handlers.TimedRotatingFileHandler(
+        filename=log_file,
+        when="W0",  # Rotate every Monday
+        interval=1,
+        backupCount=4,  # Keep 4 weeks of logs
+    )
+    file_handler.setLevel(file_level)
+    file_handler.setFormatter(formatter)
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(console_level)
+    console_handler.setFormatter(formatter)
+
+    # Add handlers
+    logger.addHandler(file_handler)
+    logger.addHandler(console_handler)
+
+
+# Call setup logging before intializing the logger below.
+setup_logging()
+
 logger = logging.getLogger(__name__)
 suppress_preview_warning = os.getenv("JUDGE0_SUPPRESS_PREVIEW_WARNING") is not None
 
 
+# TODO: I belive that the whole logic for importing implicit client can be moved
+# to a separate module.
 def _get_implicit_client(flavor: Flavor) -> Client:
     global JUDGE0_IMPLICIT_CE_CLIENT, JUDGE0_IMPLICIT_EXTRA_CE_CLIENT
 

src/judge0/api.py

@@ -1,3 +1,4 @@
+import logging
 from typing import Optional, Union
 
 from .base_types import Flavor, Iterable, TestCase, TestCases, TestCaseType
@@ -7,6 +8,8 @@
 from .retry import RegularPeriodRetry, RetryStrategy
 from .submission import Submission, Submissions
 
+logger = logging.getLogger(__name__)
+
 
 def get_client(flavor: Flavor = Flavor.CE) -> Client:
     """Resolve client from API keys from environment or default to preview client.
@@ -24,7 +27,9 @@ def get_client(flavor: Flavor = Flavor.CE) -> Client:
     from . import _get_implicit_client
 
     if isinstance(flavor, Flavor):
-        return _get_implicit_client(flavor=flavor)
+        client = _get_implicit_client(flavor=flavor)
+        logger.debug(f"Resolved implicit client for flavor {flavor}: {client}")
+        return client
     else:
         raise ValueError(
             "Expected argument flavor to be of of type enum Flavor, "
@@ -58,13 +63,15 @@ def _resolve_client(
     """
     # User explicitly passed a client.
     if isinstance(client, Client):
+        logger.debug(f"Using explicitly provided client: {client}")
         return client
 
     # NOTE: At the moment, we do not support the option to check if explicit
     # flavor of a client supports the submissions, i.e. submissions argument is
     # ignored if flavor argument is provided.
 
     if isinstance(client, Flavor):
+        logger.debug(f"Resolving client from flavor: {client}")
         return get_client(client)
 
     if client is None:
@@ -80,12 +87,14 @@ def _resolve_client(
 
     # Check which client supports all languages from the provided submissions.
     languages = [submission.language for submission in submissions]
+    logger.debug(f"Attempting to resolve client for languages: {languages}")
 
     for flavor in Flavor:
         client = get_client(flavor)
         if client is not None and all(
             (client.is_language_supported(lang) for lang in languages)
         ):
+            logger.debug(f"Resolved client {client} for languages {languages}")
             return client
 
     raise ClientResolutionError(
@@ -117,8 +126,10 @@ def create_submissions(
     client = _resolve_client(client=client, submissions=submissions)
 
     if isinstance(submissions, Submission):
+        logger.info("Creating a single submission.")
         return client.create_submission(submissions)
 
+    logger.info(f"Creating {len(submissions)} submissions.")
     result_submissions = []
     for submission_batch in batched(
         submissions, client.config.max_submission_batch_size
@@ -156,8 +167,10 @@ def get_submissions(
     client = _resolve_client(client=client, submissions=submissions)
 
     if isinstance(submissions, Submission):
+        logger.debug("Getting status for a single submission.")
         return client.get_submission(submissions, fields=fields)
 
+    logger.debug(f"Getting status for {len(submissions)} submissions.")
     result_submissions = []
     for submission_batch in batched(
         submissions, client.config.max_submission_batch_size
@@ -218,13 +231,16 @@ def wait(
         submission.token: submission for submission in submissions_list
     }
 
+    logger.info(f"Waiting for {len(submissions_to_check)} submissions to finish.")
     while len(submissions_to_check) > 0 and not retry_strategy.is_done():
+        logger.debug(f"Checking {len(submissions_to_check)} submissions...")
         get_submissions(client=client, submissions=list(submissions_to_check.values()))
         finished_submissions = [
             token
             for token, submission in submissions_to_check.items()
             if submission.is_done()
         ]
+        logger.debug(f"{len(finished_submissions)} submissions finished in this step.")
         for token in finished_submissions:
             submissions_to_check.pop(token)
 
@@ -314,7 +330,6 @@ def _execute(
     wait_for_result: bool = False,
     **kwargs,
 ) -> Union[Submission, Submissions]:
-
     if submissions is not None and source_code is not None:
         raise ValueError(
             "Both submissions and source_code arguments are provided. "
@@ -327,6 +342,7 @@ def _execute(
     if source_code is not None:
         submissions = Submission(source_code=source_code, **kwargs)
 
+    logger.info("Starting execution process.")
     client = _resolve_client(client=client, submissions=submissions)
     all_submissions = create_submissions_from_test_cases(submissions, test_cases)
     all_submissions = create_submissions(client=client, submissions=all_submissions)