oasislmf.utils.log_config
=========================

.. py:module:: oasislmf.utils.log_config


Classes
-------

.. autoapisummary::

   oasislmf.utils.log_config.OasisLogConfig


Module Contents
---------------

.. py:class:: OasisLogConfig(config: Optional[Dict[str, Any]] = None)

   Configuration handler for OasisLMF CLI/console logging.

   Handles log level resolution, format management, and validation for CLI-based logging.
   Designed to work alongside existing file-based logging in log.py.

   Environment Variables:
       OASISLMF_LOG_LEVEL: Override log level (e.g., 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')

   Example:
       >>> # Basic usage with config file
       >>> config = OasisLogConfig({'logging': {'level': 'INFO', 'format': 'compact'}})
       >>> formatter = config.create_formatter()
       >>> level = config.get_log_level()

       >>> # CLI override example
       >>> level = config.get_log_level('DEBUG')  # Override config file
       >>> available_formats = config.get_available_formats()
       >>> available_levels = config.get_available_levels()


   .. py:attribute:: STANDARD_LEVELS
      :value: ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']



   .. py:attribute:: FORMAT_TEMPLATES


   .. py:attribute:: DATE_FORMATS


   .. py:attribute:: config


   .. py:method:: get_log_level(cli_level: Optional[str] = None, is_verbose: bool = False) -> int

      Get effective log level from various sources.

      Priority order: CLI args > env vars > config file > verbose flag > default

      Args:
          cli_level: Log level from command line (e.g., 'INFO', 'DEBUG')
          is_verbose: Legacy verbose flag for backward compatibility

      Returns:
          Numeric log level (e.g., 20 for INFO, 10 for DEBUG)

      Examples:
          >>> config = OasisLogConfig()
          >>> config.get_log_level('DEBUG')
          10
          >>> config.get_log_level(is_verbose=True)
          10



   .. py:method:: get_ods_tools_level(main_level: int) -> int

      Get ods_tools logger level based on main logger level.

      Args:
          main_level: Main oasislmf logger level to use as reference

      Returns:
          Numeric log level for ods_tools logger



   .. py:method:: get_format_string(format_name: Optional[str] = None) -> str

      Get log format string.

      Args:
          format_name: Format template name from CLI or None for config/default

      Returns:
          Format string for logging.Formatter



   .. py:method:: get_date_format(format_name: Optional[str] = None) -> Optional[str]

      Get date format string for the specified template.

      Args:
          format_name: Format template name

      Returns:
          Date format string or None for logging default



   .. py:method:: create_formatter(format_name: Optional[str] = None) -> logging.Formatter

      Create a logging formatter with appropriate format and date format.

      Args:
          format_name: Format template name from CLI

      Returns:
          Configured logging.Formatter instance



   .. py:method:: get_available_formats() -> List[str]

      Get list of available format template names.

      Returns:
          List of format template names that can be used with get_format_string()

      Example:
          >>> config = OasisLogConfig()
          >>> formats = config.get_available_formats()
          >>> 'standard' in formats
          True



   .. py:method:: get_available_levels() -> List[str]

      Get list of available log level names.

      Returns:
          List of standard log level names that can be used with get_log_level()

      Example:
          >>> config = OasisLogConfig()
          >>> levels = config.get_available_levels()
          >>> 'DEBUG' in levels
          True



   .. py:method:: validate_config() -> List[str]

      Validate logging configuration and return any issues.

      Returns:
          List of warning messages about configuration issues