Configure logger

Why these changes are being introduced:

As a library that is installed and imported, it is important that
logging is setup in a way that aligns with the calling application.

How this addresses that need:
* Function configure_logger returns a logger instance that is
configured properly and uses an optional env var TDA_LOG_LEVEL
to set the level for only this logger.

Side effects of this change:
* None

Relevant ticket(s):
* https://mitlibraries.atlassian.net/browse/TIMX-415

Author: ghukill

README.md

@@ -26,6 +26,15 @@ timdex_dataset_api = {git = "https://github.com/MITLibraries/timdex-dataset-api.
 ... other dependencies...
 ```
 
+## Environment Variables
+
+### Required
+
+### Optional
+```shell
+TDA_LOG_LEVEL=# log level for timdex-dataset-api, accepts [DEBUG, INFO, WARNING, ERROR], default INFO
+```
+
 ## Usage
 
 _TODO..._

pyproject.toml

@@ -94,6 +94,7 @@ ignore = [
     "S320",
     "S321",
     "S608",
+    "TRY003"
 ]
 
 fixable = ["E", "F", "I", "Q"]

tests/conftest.py

@@ -0,0 +1,6 @@
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _test_env(monkeypatch):
+    monkeypatch.setenv("TDA_LOG_LEVEL", "INFO")

tests/test_config.py

@@ -0,0 +1,28 @@
+from timdex_dataset_api.config import configure_logger
+
+
+def test_configure_logger_default_info_level(monkeypatch, caplog):
+    caplog.set_level("DEBUG")
+    logger = configure_logger(__name__)
+
+    info_msg = "hello INFO world"
+    logger.info(info_msg)
+    assert info_msg in caplog.text
+
+    debug_msg = "hello DEBUG world"
+    logger.debug(debug_msg)
+    assert debug_msg not in caplog.text  # NOT captured
+
+
+def test_configure_logger_env_var_sets_debug_level(monkeypatch, caplog):
+    caplog.set_level("DEBUG")
+    monkeypatch.setenv("TDA_LOG_LEVEL", "DEBUG")
+    logger = configure_logger(__name__)
+
+    info_msg = "hello INFO world"
+    logger.info(info_msg)
+    assert info_msg in caplog.text
+
+    debug_msg = "hello DEBUG world"
+    logger.debug(debug_msg)
+    assert debug_msg in caplog.text  # IS captured

timdex_dataset_api/config.py

@@ -0,0 +1,31 @@
+import logging
+import os
+
+
+def configure_logger(name: str) -> logging.Logger:
+    """Prepares and returns a logger instance for a given module name.
+
+    This approach is suitable for an installed and imported library such as this, where
+    any calling application logging levels and handlers should be utilized.
+
+    Args:
+        name (str): The name of the logger, typically __name__ is passed by caller
+    """
+    logger = logging.getLogger(name)
+    logger.addHandler(logging.NullHandler())
+
+    log_level = os.getenv("TDA_LOG_LEVEL", "INFO").strip().upper()
+    if log_level not in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]:
+        raise ValueError(f"Invalid log level: '{log_level}'")
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(
+        logging.Formatter(
+            "%(asctime)s %(levelname)s %(name)s.%(funcName)s() "
+            "line %(lineno)d: %(message)s"
+        )
+    )
+    logger.addHandler(handler)
+    logger.setLevel(getattr(logging, log_level))
+
+    return logger