First steps

To install this library, simply type this command (Windows variant):

$ pip install pyrolog

On linux systems, you must use pip3 instead of. Command:

$ pip3 install pyrolog

Formatters

Formatters allow us to pretty format our logs. Library has these formatters by default: PlainFormatter - only plain text, ColoredFormatter - colored logs.

Formatters has some options as:

* format string - String responsible for formatting.
* time format string - String responsible for formatting time.
* static variables - Static variables, that can be used by {...} syntax.
* logging context - Current logging context.
* offsets - enable\disable offsets.

About the format strings, by default there has many variants, see :module:`pyrolog.defaults`.

To use handlers, you must firsly create formatter instance!

Handlers

To create a handler for the stdout (console output) you can use pyrolog.handlers.StdoutHandler.

import pyrolog

# NOTE: Exception is a log level little than info.
#       It recommended to use it for exception logging.
stdout_handler = pyrolog.StdoutHandler(
    log_level='exception',
    formatter=pyrolog.ColoredFormatter(pyrolog.defaults.COLORED_TIMED_MINIMAL_FORMAT_STRING),
)

Note

You can also use pyrolog.utils.LogLevel to set the log_level parameter.

There also have support for file handler. This class named as pyrolog.handlers.FileHandler.

import pyrolog

file_handler = pyrolog.FileHandler(
    'logs/{timestamp}.log', # filename
    timestamp=True, # enables {timestamp} feature
    log_level='debug', # log level
    formatter=pyrolog.PlainFormatter(pyrolog.defaults.TIMED_MINIMAL_FORMAT_STRING),
)

Lets combine them into one code:

import pyrolog

stdout_handler  = pyrolog.StdoutHandler(
    log_level='exception',
    formatter=pyrolog.ColoredFormatter(pyrolog.defaults.COLORED_TIMED_MINIMAL_FORMAT_STRING),
)
file_handler    = pyrolog.FileHandler(
    'logs/{timestamp}.log', # filename
    timestamp=True, # enables {timestamp} feature
    log_level='debug', # log level
    formatter=pyrolog.PlainFormatter(pyrolog.defaults.TIMED_MINIMAL_FORMAT_STRING),
)

Our first handlers are done.

Logger group

Lets create our first logger group. Group contains all parameters for child loggers. This is useful in case of multiple loggers usage. To create it, you can use pyrolog.loggergroup.Group.

You can create loggers without groups.

Create MyApp group:

import pyrolog

myapp_group = pyrolog.Group('MyApp')

See also

You can see it reference: pyrolog.loggergroup.Group

Lets add our loggers by examples above to this group.

Note

Handlers can be pinned to groups by handlers parameter. This parameter is named and takes Handler | list[Handler] type. Example is bottom.

import pyrolog

# Our first handlers for stdout and file
stdout_handler  = pyrolog.StdoutHandler(
    log_level='exception',
    formatter=pyrolog.ColoredFormatter(pyrolog.defaults.COLORED_TIMED_MINIMAL_FORMAT_STRING),
)
file_handler    = pyrolog.FileHandler(
    'logs/{timestamp}.log', # filename
    timestamp=True, # enables {timestamp} feature
    log_level='debug', # log level
    formatter=pyrolog.PlainFormatter(pyrolog.defaults.TIMED_MINIMAL_FORMAT_STRING),
)

# Our first group by name MyApp
myapp_group = pyrolog.Group('MyApp', handlers=[stdout_handler, file_handler])

Our first group done!

Logging

Loggers can be created by pyrolog.logger.Logger class. It, how as a logger groups, takes a handlers parameter. But, as I said, if you use logger group, it stores all parameters for child loggers and set it automatically. All that required from Loggers is a group parameter. To get more info see Loggers reference (just click on pyrolog.logger.Logger).

import pyrolog

# Our first handlers for stdout and file
stdout_handler  = pyrolog.StdoutHandler(
    log_level='exception',
    formatter=pyrolog.ColoredFormatter(pyrolog.defaults.COLORED_TIMED_MINIMAL_FORMAT_STRING),
)
file_handler    = pyrolog.FileHandler(
    'logs/{timestamp}.log', # filename
    timestamp=True, # enables {timestamp} feature
    log_level='debug', # log level
    formatter=pyrolog.PlainFormatter(pyrolog.defaults.TIMED_MINIMAL_FORMAT_STRING),
)

# Our first group by name MyApp
myapp_group = pyrolog.Group('MyApp', handlers=[stdout_handler, file_handler])

# Create a Main logger that includes MyApp group
logger = pyrolog.Logger('Main', group=myapp_group)

Our logger is done! Now, we can log messages to it. By default, logger hasn’t debug, exception, info and other methods. It adds via pyrolog.logger.Logger.bind_log_methods(). This methods calls by default, and uses this list of the log levels -> pyrolog.defaults.DEFAULT_LOG_LEVELS :module:`pyrolog.defaults`.

List of all the default log levels:

number1 = 15
logger.debug('Defined number 1: {}', number1)

number2 = 2
logger.debug('Defined number 2: {}', number2)

result = number1 + number2
logger.info('Adding number 1 to number2. Result: {}', result)

Note

To log methods you can pass format variables as long as you need.

You can also use all features of the python string formatting.

Warning

All

import math

logger.info('{:<20}--{:>19}', 'pi is', f'{math.pi:.2f}')

Code above will produce info log with message: pi is  --  3.14.

Log exceptions

All methods of logging are defines named parameter exception=. It takes any exception and log it after the message.

try:
    printt('Hello, world!')
except Exception as e:
    # You can use any function to log exception. But, recommended to use
    # only exception level for exceptions.

    logger_main.debug('An exception occurred: {}', e, exc=e)
    logger_main.exception('An exception occurred: {}', e, exc=e)
    logger_main.info('An exception occurred: {}', e, exc=e)
    logger_main.warning('An exception occurred: {}', e, exc=e)
    logger_main.error('An exception occurred: {}', e, exc=e)
    logger_main.critical(f'An exception occurred: {e}', exc=e)