k3log

k3log is a collection of log utilities for logging.

# make a file logger in one line
logger = pk3logutil.make_logger('/tmp', level='INFO', fmt='%(message)s',
                                datefmt="%H:%M:%S")
logger.info('foo')

logger.stack_str(fmt="{fn}:{ln} in {func}\n  {statement}", sep="\n")
# runpy.py:174 in _run_module_as_main
#   "__main__", fname, loader, pkg_name)
# runpy.py:72 in _run_code
#   exec code in run_globals
# ...
# test_logutil.py:82 in test_deprecate
#   pk3logutil.deprecate()
#   'foo', fmt='{fn}:{ln} in {func}\n  {statement}', sep='\n')

Documentation for the Code

Functions

k3log.add_std_handler(logger, stream=None, fmt=None, datefmt=None, level=None)

It adds a stdout or stderr steam handler to the logger.

Parameters
  • logger – is an instance of logging.Logger to add handler to.

  • stream – specifies the stream, it could be: - sys.stdout or a string stdout. - sys.stderr or a string stderr.

  • fmt (str) – is the log message format. It can be an alias name(like default) that can be used in get_fmt(). By default it is default: [%(asctime)s,%(process)d-%(thread)d,%(filename)s,%(lineno)d,%(levelname)s] %(message)s.

  • datefmt (str) – is the format for date. It can be an alias name(like time) that can be used in get_datefmt(). By default it is None.

  • level – is the log level. It can be int value such as logging.DEBUG or string such as DEBUG. By default it is the logger’s level.

Returns

the logger in argument.

k3log.deprecate(msg=None, fmt=None, sep=None)

Print a deprecate message, at warning level. The printed message includes:

  • User defined message msg,

  • And calling stack of where this warning occurs. <frame-n> is where deprecate is called.

<msg> Deprecated: <frame-1> --- <frame-2> --- ... --- <frame-n>

The default frame format is {fn}:{ln} in {func} {statement}. It can be changed with argument fmt. Frame separator by default is ` — , and can be changed with argument `sep.

For example, the following statement:

def foo():
    deprecate('should not be here.',
              fmt="{fn}:{ln} in {func}\n  {statement}",
              sep="\n"
              )

Would produce a message:

Deprecated: should not be here.
runpy.py:174 in _run_module_as_main
  "__main__", fname, loader, pkg_name)
runpy.py:72 in _run_code
  exec code in run_globals
...
test_log.py:82 in test_deprecate
  deprecate()
  'foo', fmt='{fn}:{ln} in {func}\n  {statement}', sep='\n')
Parameters
  • msg – is description of the deprecated statement. It could be None.

  • fmt – is call stack frame format. By default it is {fn}:{ln} in {func} {statement}.

  • sep – is the separator string between each frame. By default it is " --- ". Thus all frames are printed in a single line.

k3log.get_datefmt(datefmt)

It translates a predefined datefmt alias to actual datefmt. Predefined alias includes:

{
    'default':  None,       # use the system default datefmt
    'time':     '%H:%M:%S',
}
Parameters

datefmt – is the alias name. If no predefined alias name is found, it returns the passed in value of datefmt.

Returns

translated datefmt or the original value of argument datefmt.

k3log.get_fmt(fmt)

It translate a predefined fmt alias to actual fmt. Predefined alias includes:

{
    'default':    '[%(asctime)s,%(process)d-%(thread)d,%(filename)s,%(lineno)d,%(levelname)s] %(message)s',
    'time_level': "[%(asctime)s,%(levelname)s] %(message)s",
    'message':    '%(message)s',
}
Parameters

fmt – is the alias name. If no predefined alias name is found, it returns the passed in value of fmt.

Returns

translated fmt or the original value of argument fmt.

k3log.get_root_log_fn()

Returns the log file name for root logger. The log file name suffix is .out.

  • pyfn.out: if program is started with python pyfn.py.

  • __instant_command__.out: if instance python command is called: python -c "import k3log; print k3log.get_root_log_fn().

  • __stdin__.out: if python statement is passed in as stdin: echo "from pykit import k3log; print k3log.get_root_log_fn()" | python.

Returns

log file name.

k3log.make_file_handler(base_dir=None, log_fn=None, fmt=None, datefmt=None)

It creates a rolling log file handler.

A rolling file can be removed at any time. This handler checks file status everytime write log to it. If file is changed(removed or moved), this handler automatically creates a new log file.

Parameters
  • base_dir – specifies the dir of log file. If it is None, use k3conf.log_dir as default.

  • log_fn – specifies the log file name. If it is None, use k3log.get_root_log_fn to make a log file name.

  • fmt – specifies log format. It can be an alias that can be used in k3log.get_fmt(), or None to used the default log format.

  • datefmt – specifies log date format. It can be an alias that can be used in k3log.get_datefmt(), or None to used the default date format.

Returns

an instance of logging.handlers.WatchedFileHandler.

k3log.make_formatter(fmt=None, datefmt=None)

It creates an logging.Formatter instance, with specified fmt and datefmt.

Parameters
  • fmt – specifies log format. It can be an alias that can be used in get_fmt(), or None to used the default log format.

  • datefmt – specifies log date format. It can be an alias that can be used in get_datefmt(), or None to used the default date format.

Returns

an logging.Formatter instance.

k3log.make_logger(base_dir=None, log_name=None, log_fn=None, level=10, fmt=None, datefmt=None)

It creates a logger with a rolling file hander and specified formats.

Parameters
  • base_dir – specifies the dir of log file. If it is None, use config.log_dir as default.

  • log_name – is the name of the logger to create. None means the root logger.

  • log_fn – specifies the log file name. If it is None, use k3log.get_root_log_fn to make a log file name.

  • level – specifies log level. It could be int value such as logging.DEBUG or string such as DEBUG.

  • fmt – specifies log format. It can be an alias that can be used in k3log.get_fmt(), or None to used the default log format.

  • datefmt – specifies log date format. It can be an alias that can be used in k3log.get_datefmt(), or None to used the default date format.

Returns

a logging.Logger instance.

k3log.set_logger_level(level=20, name_prefixes=None)

Set all logger level that matches name_prefixes.

Parameters
  • level – specifies log level. It could be int value such as logging.DEBUG or string such as DEBUG.

  • name_prefixes – specifies log prefixes which is operated. It can be None, str or a tuple of str. If name_prefixes is None, set the log level for all logger.

k3log.stack_format(stacks, fmt=None, sep=None)

It formats stack made from k3log.stack_list.

With fmt="{fn}:{ln} in {func}\n  {statement}" and sep="\n", a formatted stack would be:

runpy.py:174 in _run_module_as_main
  "__main__", fname, loader, pkg_name)
runpy.py:72 in _run_code
  exec code in run_globals
...
test_logutil.py:82 in test_deprecate
  k3log.deprecate()
  'foo', fmt='{fn}:{ln} in {func}\n  {statement}', sep='\n')
Parameters
  • stacks

    is stack from k3log.stack_list:

    [
        {
            'fn': ...
            'ln': ...
            'func': ...
            'statement': ...
        }
        ...
    ]
    

  • fmt – specifies the template to format a stack frame. By default it is: {fn}:{ln} in {func} {statement}.

  • sep – specifies the separator string between each stack frame. By default it is " --- ". Thus all frames are in the same line.

Returns

a string repesenting a calling stack.

k3log.stack_list(offset=0)

It returns the calling stack from where it is called.

Parameters

offset – remove the lowest offset frames.

Returns

list of:

{
    'fn': ...
    'ln': ...
    'func': ...
    'statement': ...
}

k3log.stack_str(offset=0, fmt=None, sep=None)

It creates a string representing calling stack from where this function is called.

Parameters
  • offset – remove the lowest offset frames. Because usually one does not need the frame of the k3log.stack_str line.

  • fmt – is same as k3log.stack_format.

  • sep – is same as k3log.stack_format.

Returns

a string repesenting a calling stack.

Indices and tables