=======================
sampo.api.sampo_logging
=======================
.. py:function:: sampo.api.sampo_logging.configure(level, filename=None, format=None, colorize=False)

    Configures logging of SAMPO.

    When the filename parameter is set, logging.handlers.RotatingFileHandler
    is used as root logger with ``maxBytes`` set at 10MB and ``backupCount`` set at 1000.
    See the Python Standard Library documents for more details on the specification.

    WARNING and higher level messages will be output to the stderr stream.

    :param level: Log level.
    :type level: logging.DEBUG, logging.INFO, logging.WARN
    :param filename: Log file path. Specifies the filename with 'a' file mode.
        If specified, logging.FileHandler is created.
        If None, log messages will be output to stdout stream.
    :type filename: str or None
    :param format: Log output format. The usable keywords are defined by LogRecord class
        of python's logging library. If None, default log formats will be used:

        * for console: '[%(levelname)s] %(message)s'
        * for file: '[PID:%(process)d] [%(asctime)s] [%(name)s] [%(levelname)s] %(message)s'

    :type format: str or None
    :param colorize: Colorizes log output or not.
    :type colorize: bool
    :raises ValueError:
          * If level is not in {logging.DEBUG, logging.INFO, logging.WARN}.
          * If filename is not str or None.
          * If format is not str or None.
          * If colorize is not bool.

    .. code-block :: python

        >>> import logging
        >>> from sampo.api import sampo_logging
        >>> sampo_logging.configure(logging.INFO, filename='/var/log/process.log')
