rats-apps 0.11.1.dev20250527164358__py3-none-any.whl → 0.11.1.dev20250527164753__py3-none-any.whl

rats/cli/_container.py

@@ -55,11 +55,11 @@ class Container(Protocol):
 
         commands = get_class_commands(type(self))
         tates = commands.annotations
+        logger.debug(f"[{type(self)}] commands: {tates}")
 
         for tate in tates:
             method = getattr(self, tate.name)
             params = list(reversed(getattr(method, "__click_params__", [])))
-            logger.debug(tate.namespace)
             for command in tate.groups:
                 if tate.namespace == "commands":
                     group.add_command(

rats/logs/__init__.py

@@ -7,16 +7,62 @@ handle configuring the python logging libraries, with a few configuration option
 !!! warning
     We expose the logging functionality through a [rats.apps.AppContainer][] in order to leverage
     the built in plugin system to give users the ability to adjust the default settings, but this
-    entire application should be lightweight and should not contain very complex logic, avoiding
-    logic that is very time consuming or has a chance of failing with confusing errors.
+    application should be lightweight and should not contain very complex logic, avoiding logic
+    that is very time consuming or has a chance of failing with confusing errors.
+
+## Verbosity Env Variables
+
+To help develop modules, logging output can be configured with the `DEBUG_LOGS_*`, `QUIET_LOGS_*`,
+and `LEVEL_LOGS_*` environment variables. The suffix of the environment variables match the module
+name wanting to be configured.
+
+### Module Loggers
+
+Environment variables named `DEBUG_LOGS_*` cause logs from the given module to be shown; the
+`QUIET_LOGS_*` environment variables silence logs emitted by the module; and `LEVEL_LOGS_*` allows
+a specific [logging-level](https://docs.python.org/3/library/logging.html#logging-levels) to be
+used.
+
+```
+$ rats-ci fix
+All checks passed!
+63 files left unchanged
+ran 2 fix commands
+```
+
+```bash
+# Enable DEBUG level logs for the `rats.*` modules
+export DEBUG_LOGS_RATS="1"
+# Enable WARNING level logs for the `rats.projects.*` modules
+export LEVEL_LOGS_RATS_PROJECTS="WARNING"
+# Disable logs for `rats.cli.*` modules
+export QUIET_LOGS_RATS_CLI="1"
+```
+```
+$ rats-ci fix
+2025-05-27 00:49:45 DEBUG    [rats.logs._app:96]: done configuring logging
+All checks passed!
+63 files left unchanged
+ran 2 fix commands
+```
+
+### Root Logger
+
+The root logger can be configured with the `DEBUG_LOGS`, `QUIET_LOGS`, and `LEVEL_LOGS` environment
+variables.
+
+```bash
+# Enable WARNING level logs for all logs
+export LEVEL_LOGS="WARNING"
+```
 
-    If the logging options made available through this module are far from what is desired, instead
-    of adding flags and options to this module, we recommend configuring logging in your own code.
 """
 
 from ._app import AppConfigs, ConfigureApplication
+from ._showwarning import showwarning
 
 __all__ = [
     "AppConfigs",
     "ConfigureApplication",
+    "showwarning",
 ]

rats/logs/_app.py

@@ -1,10 +1,13 @@
 import logging.config
+import os
 import warnings
 from collections.abc import Iterator
 from typing import Any
 
 from rats import apps
 
+from ._showwarning import showwarning
+
 logger = logging.getLogger(__name__)
 LoggerConfigEntry = tuple[str, dict[str, Any]]
 
@@ -61,12 +64,12 @@ class ConfigureApplication(apps.AppContainer, apps.PluginMixin):
                     "colored": {
                         "()": "colorlog.ColoredFormatter",
                         "format": (
-                            "%(log_color)s%(asctime)s %(levelname)-8s [%(name)s][%(lineno)d]: "
+                            "%(log_color)s%(asctime)s %(levelname)-8s [%(name)s:%(lineno)d]: "
                             "%(message)s%(reset)s"
                         ),
                         "datefmt": "%Y-%m-%d %H:%M:%S",
                         "log_colors": {
-                            "DEBUG": "white",
+                            "DEBUG": "cyan",
                             "INFO": "green",
                             "WARNING": "yellow",
                             "ERROR": "red,",
@@ -88,9 +91,65 @@ class ConfigureApplication(apps.AppContainer, apps.PluginMixin):
         # enable deprecation warnings by default
         logging.captureWarnings(True)
         warnings.simplefilter("default", DeprecationWarning)
+        # our modified `showwarning` method logs warnings with the module logger that emitted it
+        warnings.showwarning = showwarning
         logger.debug("done configuring logging")
 
     @apps.fallback_group(AppConfigs.LOGGERS)
     def _default_loggers(self) -> Iterator[LoggerConfigEntry]:
-        yield "", {"level": "INFO", "handlers": ["console"]}
-        yield "azure", {"level": "WARNING", "handlers": ["console"]}
+        logger_mapping = {
+            "": "INFO",
+            "azure": "WARNING",
+            "py.warnings": "CRITICAL",
+        }
+        searched_prefixes = [
+            "DEBUG_LOGS",
+            "QUIET_LOGS",
+            "LEVEL_LOGS",
+        ]
+        for name in os.environ.keys():
+            env_prefix = name[0:10]
+            if env_prefix not in searched_prefixes:
+                # this isn't a logging config env
+                continue
+
+            # our above prefixes are conveniently all 10 characters
+            # everything after the prefix is the logger name, skip the underscore after the prefix
+            logger_name = name.lower()[11:].replace("_", ".")
+            if logger_name not in logger_mapping:
+                # the default here is ignored
+                logger_mapping[logger_name] = "INFO"
+
+        for name, default in logger_mapping.items():
+            yield self._build_logger_entry(name, default)
+
+    def _build_logger_entry(self, name: str, default: str = "INFO") -> LoggerConfigEntry:
+        # https://docs.python.org/3/library/logging.html#logging-levels
+        valid_levels = [
+            "NOTSET",
+            "DEBUG",
+            "INFO",
+            "WARNING",
+            "ERROR",
+            "CRITICAL",
+        ]
+        suffix = f"_{'_'.join(name.split('.')).upper()}" if name != "" else ""
+
+        debug_env_name = f"DEBUG_LOGS{suffix}"
+        quiet_env_name = f"QUIET_LOGS{suffix}"
+        level_env_name = f"LEVEL_LOGS{suffix}"
+        if os.environ.get(level_env_name):
+            # user specified exactly what log level is wanted for this module
+            lvl = os.environ[level_env_name].upper()
+            if lvl not in valid_levels:
+                raise ValueError(f"invalid log level specified: {level_env_name}={lvl}")
+            return name, {"level": lvl, "handlers": ["console"], "propagate": False}
+        elif os.environ.get(debug_env_name):
+            # show as many logs as possible
+            return name, {"level": "DEBUG", "handlers": ["console"], "propagate": False}
+        elif os.environ.get(quiet_env_name):
+            # only show critical logs when QUIET_LOGS is enabled
+            return name, {"level": "CRITICAL", "handlers": ["console"], "propagate": False}
+        else:
+            # set default logging to INFO
+            return name, {"level": default, "handlers": ["console"], "propagate": False}

rats/logs/_showwarning.py

@@ -0,0 +1,51 @@
+import logging
+import sys
+import warnings
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def showwarning(
+    message: Warning | str,
+    category: type[Warning],
+    filename: str,
+    lineno: int,
+    file: str | None = None,
+    line: str | None = None,
+) -> None:
+    """
+    Handler that logs warnings using the module logger from the module that emitted the warning.
+
+    ```python
+    import warnings
+    from rats.logs import showwarning
+
+    warnings.showwarning = showwarning
+    warnings.warn("This is a custom warning", UserWarning)
+    ```
+
+    Args:
+        message: The warning message instance or string.
+        category: The category of the warning (e.g., [DeprecationWarning][], [UserWarning][]).
+        filename: The path to the file where the warning originated.
+        lineno: The line number in the file where the warning originated.
+        file: Ignored. Included for compatibility with the standard warnings.showwarning signature.
+        line: The line of source code to be included in the warning message, if available.
+    """
+    if file is not None:
+        raise ValueError(file)
+
+    formatted_message = warnings.formatwarning(message, category, filename, lineno, line)
+
+    for _module_name, module in sys.modules.items():
+        module_path = getattr(module, "__file__", None)
+        if module_path and Path(filename).is_file() and Path(module_path).samefile(filename):
+            module_name = _module_name
+            break
+    else:
+        # unsure what module to use, but we can default to "py.warnings" like the original handler
+        module_name = "py.warnings"
+
+    source_logger = logging.getLogger(module_name)
+    source_logger.warning(formatted_message)

{rats_apps-0.11.1.dev20250527164358.dist-info → rats_apps-0.11.1.dev20250527164753.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: rats-apps
-Version: 0.11.1.dev20250527164358
+Version: 0.11.1.dev20250527164753
 Summary: research analysis tools for building applications
 License: MIT
 Keywords: pipelines,machine learning,research

{rats_apps-0.11.1.dev20250527164358.dist-info → rats_apps-0.11.1.dev20250527164753.dist-info}/RECORD

@@ -26,12 +26,13 @@ rats/cli/__main__.py,sha256=WeldAKjA3Kmz9ZRnZVd3G8Ud66Y_gSRDLIPNE1JyhV0,1418
 rats/cli/_annotations.py,sha256=-B2Y1bYjPbeTNTBMZzMdAU92qu9AyutKHN_NdFy-xhA,2964
 rats/cli/_click_app.py,sha256=Jvs6OqNC4Yoe6kbc2tCzjzUieNFa1n_zwXPsdo971Wc,1450
 rats/cli/_command.py,sha256=kyU3UqqF9aiTTaFvlQFBKDLXvArQS1QgjoQqlMbKzok,597
-rats/cli/_container.py,sha256=FIQBqi9PTNpE2P52qkfGET51BczdD-JvcWXLTjCNPDI,3512
+rats/cli/_container.py,sha256=BoZLOu-eT4SzweNwMepWHd4PyxQAg--_p-rM7XkQNAA,3529
 rats/cli/_functions.py,sha256=BNmgWVquQUEqJAYsed_l8vLnlLP7u3XC1TDyEFI1AiU,1552
 rats/cli/_plugin.py,sha256=o-pmEqU6mVH3QoRfRBrbG-XRTWCzt6pLKtSV3-5VSx0,1144
 rats/cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rats/logs/__init__.py,sha256=dSO-V2eu2W7w4w7oRau-UOfXXIkyZ2bHB6-kaasbeFM,970
-rats/logs/_app.py,sha256=SoTxk6g84tygOP_346NwXPcG1o6KZLd7lIgayq5vMdc,3239
+rats/logs/__init__.py,sha256=_ZdkBmvW1yr5UOIB_m4OldNsUxK6NTDunNW4mvgQmpI,2115
+rats/logs/_app.py,sha256=EVjSjSaxJIL5LMJZf4yo9EpUBkkavaVXyg42cDsUt3I,5702
+rats/logs/_showwarning.py,sha256=g5Gq0I7GoHgABI4eCobq6xd4NaKuLGJFyK-SCvegDHA,1726
 rats/logs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats/runtime/__init__.py,sha256=f9aEnynHuePP9OP5XCtB-6nCBvNWWlQQLTzuxFEueoQ,2150
 rats/runtime/__main__.py,sha256=y01yOymsL075poX95pc02sJR1HD0pDNFRZdpOdi0R6Y,79
@@ -54,7 +55,7 @@ rats_e2e/runtime/_data.py,sha256=3d1F_JO2gEOPUjBp_KYMP3TefyneiG_ktlJjdIIYUy8,125
 rats_e2e/runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats_resources/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats_resources/runtime/example-context.yaml,sha256=eiLsNFquFfkIpUhxUCQLzLigH21QF2F00fzA_e_aOKk,215
-rats_apps-0.11.1.dev20250527164358.dist-info/METADATA,sha256=pxkR1NF65RfrYcBemvO87N8bYjEdLprXgvi0NQ9ygYw,889
-rats_apps-0.11.1.dev20250527164358.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-rats_apps-0.11.1.dev20250527164358.dist-info/entry_points.txt,sha256=Gf6bPwxIVjWd3Xx71upZo7eDJA5cujniLew6fxJMgA4,117
-rats_apps-0.11.1.dev20250527164358.dist-info/RECORD,,
+rats_apps-0.11.1.dev20250527164753.dist-info/METADATA,sha256=kgJQUzcaMgofZndS9ETn14z0uY0ZE50-Y1Yh8pqVqYA,889
+rats_apps-0.11.1.dev20250527164753.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+rats_apps-0.11.1.dev20250527164753.dist-info/entry_points.txt,sha256=Gf6bPwxIVjWd3Xx71upZo7eDJA5cujniLew6fxJMgA4,117
+rats_apps-0.11.1.dev20250527164753.dist-info/RECORD,,