Added logging root directory (#190)

Provides workaround for issue:
#137

BUG=b/382252531

Author: neshdev

README.md

@@ -263,14 +263,14 @@ Configure hatch to create virtual env in project folder.
 hatch config set dirs.env.virtual .env
 ```
 
-After, create all the python environments needed by running `hatch -e all run tests`.
+After, create all the python environments needed by running `hatch tests --all`.
 
 Finally, configure vscode to use one of the selected environments:
 `cmd + shift + p` -> `python: Select Interpreter` -> Pick one of the folders in `./.env`
 
 ## Support
 
-The kagglehub library has configured automatic logging which is stored in a log folder. The log destination is resolved via the [os.path.expanduser](https://docs.python.org/3/library/os.path.html#os.path.expanduser)
+The kagglehub library has configured automatic logging for console. For file based logging, setting the `KAGGLE_LOGGING_ENABLED=1` environment variable will output logs to a directory. The default log destination is resolved via the [os.path.expanduser](https://docs.python.org/3/library/os.path.html#os.path.expanduser)
 
 The table below contains possible locations:
 | os      | log path                                         |
@@ -279,4 +279,6 @@ The table below contains possible locations:
 | linux   | ~/.kaggle/logs/kagglehub.log                     |
 | windows | C:\Users\\%USERNAME%\\.kaggle\logs\kagglehub.log |
 
+If needed, the root log directory can be overriden using the following environment variable: `KAGGLE_LOGGING_ROOT_DIR`
+
 Please include the log to help troubleshoot issues.

src/kagglehub/logger.py

@@ -1,4 +1,5 @@
 import logging
+import os
 import sys
 from logging import LogRecord
 from logging.handlers import RotatingFileHandler
@@ -7,6 +8,9 @@
 
 from kagglehub.config import get_log_verbosity
 
+KAGGLE_LOGGING_ROOT_DIR_ENV_VAR_NAME = "KAGGLE_LOGGING_ROOT_DIR"
+KAGGLE_LOGGING_ENABLED_ENV_VAR_NAME = "KAGGLE_LOGGING_ENABLED"
+
 _FILE_BLOCK_KEY = "kaggle_file"
 EXTRA_FILE_BLOCK = {"block": _FILE_BLOCK_KEY}
 _CONSOLE_BLOCK_KEY = "console"
@@ -35,19 +39,21 @@ def _configure_logger(log_dir: Optional[Path] = None) -> None:
         handler = library_logger.handlers.pop()
         while handler.filters:
             handler.filters.pop()
-    log_dir = Path.home() / ".kaggle" / "logs" if log_dir is None else log_dir
-    log_dir.mkdir(exist_ok=True, parents=True)
-    file_handler = RotatingFileHandler(
-        str(log_dir / "kagglehub.log"), maxBytes=1024 * 1024 * 5, backupCount=5, delay=True
-    )
-    file_handler.addFilter(_block_logrecord_factory([_FILE_BLOCK_KEY]))
-    formatter = logging.Formatter(
-        "%(asctime)s - %(name)s - %(levelname)s - %(threadName)s - %(funcName)s - %(message)s"
-    )
-    file_handler.setFormatter(formatter)
-    file_handler.setLevel(logging.DEBUG)
-    library_logger.addHandler(file_handler)
-
+    logging_enabled = os.environ.get(KAGGLE_LOGGING_ENABLED_ENV_VAR_NAME, False)
+    if str(logging_enabled).lower() in ("true", 1):
+        log_root_dir = Path(os.environ.get(KAGGLE_LOGGING_ROOT_DIR_ENV_VAR_NAME, Path.home()))
+        log_dir = log_root_dir / ".kaggle" / "logs" if log_dir is None else log_dir
+        log_dir.mkdir(exist_ok=True, parents=True)
+        file_handler = RotatingFileHandler(
+            str(log_dir / "kagglehub.log"), maxBytes=1024 * 1024 * 5, backupCount=5, delay=True
+        )
+        file_handler.addFilter(_block_logrecord_factory([_FILE_BLOCK_KEY]))
+        formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(threadName)s - %(funcName)s - %(message)s"
+        )
+        file_handler.setFormatter(formatter)
+        file_handler.setLevel(logging.DEBUG)
+        library_logger.addHandler(file_handler)
     sh = logging.StreamHandler(sys.stdout)
     sh.addFilter(_block_logrecord_factory([_CONSOLE_BLOCK_KEY]))
     sh.setLevel(get_log_verbosity())

tests/test_logger.py

@@ -1,14 +1,18 @@
 import logging
+import os
 import unittest
 from contextlib import redirect_stdout
 from io import StringIO
 from pathlib import Path
 from tempfile import TemporaryDirectory
+from unittest import mock
 
 from kagglehub.logger import (
     _CONSOLE_BLOCK_KEY,
     EXTRA_CONSOLE_BLOCK,
     EXTRA_FILE_BLOCK,
+    KAGGLE_LOGGING_ENABLED_ENV_VAR_NAME,
+    KAGGLE_LOGGING_ROOT_DIR_ENV_VAR_NAME,
     _block_logrecord_factory,
     _configure_logger,
 )
@@ -64,14 +68,54 @@ def test_kagglehub_child_console_filter_discards_logrecord(self) -> None:
 
     def test_kagglehub_file_filter(self) -> None:
         with TemporaryDirectory() as f:
-            log_path = Path(f) / "testasdfasf-log"
-            _configure_logger(log_path)
-            logger = logging.getLogger("kagglehub")
-            logger.info("HIDE", extra={**EXTRA_FILE_BLOCK})
-            logger.info("SHOW")
-            text = (log_path / "kagglehub.log").read_text()
-            self.assertRegex(text, "^.*SHOW.*$")
-            self.assertRegex(text, "^(?!.*HIDE).*$")
+            with mock.patch.dict(os.environ, {KAGGLE_LOGGING_ENABLED_ENV_VAR_NAME: str(True)}):
+                log_path = Path(f) / "testasdfasf-log"
+                _configure_logger(log_path)
+                logger = logging.getLogger("kagglehub")
+                logger.info("HIDE", extra={**EXTRA_FILE_BLOCK})
+                logger.info("SHOW")
+                text = (log_path / "kagglehub.log").read_text()
+                self.assertRegex(text, "^.*SHOW.*$")
+                self.assertRegex(text, "^(?!.*HIDE).*$")
+
+    def test_log_env_variable_and_enabled(self) -> None:
+        with TemporaryDirectory() as d:
+            root_log_dir = Path(d) / "log"
+            with mock.patch.dict(
+                os.environ,
+                {
+                    KAGGLE_LOGGING_ROOT_DIR_ENV_VAR_NAME: str(root_log_dir),
+                    KAGGLE_LOGGING_ENABLED_ENV_VAR_NAME: str(True),
+                },
+            ):
+                _configure_logger()
+                logger = logging.getLogger("kagglehub")
+                logger.info("goose")
+                self.assertTrue((Path(root_log_dir) / ".kaggle/logs/kagglehub.log").exists(), "log file expected")
+
+    def test_log_disabled(self) -> None:
+        with TemporaryDirectory() as d:
+            log_dir = Path(d) / "log"
+            with mock.patch.dict(
+                os.environ,
+                {KAGGLE_LOGGING_ENABLED_ENV_VAR_NAME: str(False)},
+            ):
+                _configure_logger(log_dir)
+                logger = logging.getLogger("kagglehub")
+                logger.info("goose")
+                self.assertFalse((log_dir / "kagglehub.log").exists(), "no log file expected")
+
+    def test_log_enabled(self) -> None:
+        with TemporaryDirectory() as d:
+            log_dir = Path(d) / "log"
+            with mock.patch.dict(
+                os.environ,
+                {KAGGLE_LOGGING_ENABLED_ENV_VAR_NAME: str(True)},
+            ):
+                _configure_logger(log_dir)
+                logger = logging.getLogger("kagglehub")
+                logger.info("goose")
+                self.assertTrue((log_dir / "kagglehub.log").exists(), "log file expected")
 
 
 if __name__ == "__main__":