mylogging package

My python logging-warning module. It logs to console or to file based on configuration.

1. It’s automatically colorized and formatted to be more readable and noticeable (you can immediately see what errors are yours)

2. It’s possible to control logs and warnings behavior (ignore, once, always) as in warnings.

3. It’s possible to filter messages by level (INFO, DEBUG, WARNING, ERROR, CRITICAL) as in logging.

Motivation for this project is to be able to have one very simple code base for logging and warning at once and setup logging at one place, not in every project.

You can use one code for logging apps running on server (developers see what happens on server) and the same code for printing info and warnings from developed library.

Links

Official documentation - https://mylogging.readthedocs.io/

Official repo - https://github.com/Malachov/mylogging

Installation

Python >=3.6 (Python 2 is not supported).

Install just with:

pip install mylogging

Output

This is how the results of examples below look like in console.

For log file, just open example.log in your IDE. This is how the results in log file opened in VS Code look like.

Examples:

Library is made to be as simple as possible, so configuration should be easy (you don’t need to configure anything actually)… Just setup path to log file (will be created if not exists). If you will not setup it, log to console will be used. Change filter (defaults to once) and level (defaults to WARNING) if you need. Then syntax is same as in logging module. Functions debug, info, warn, error and critical are available.

>>> import mylogging
...
>>> mylogging.config.level = "WARNING"
...
>>> mylogging.warn("I am interesting warning.")

You can log your caught errors with traceback, where you set level as input parameter. You can use traceback also with no parameters, traceback type will be used as heading then. Stack trace in this example starts in the try block.

>>> try:
...     bad = 10 / 0
... except ZeroDivisionError:
...     mylogging.traceback("Maybe try to use something different than 0.")

There is also a way how to work with raised errors. Stack trace is then used from the beginning of the script. Exceptions are formated by default and it’s not necessary to setup anything. If you want to turn this feature off, use

>>> mylogging.my_traceback.enhance_excepthook_reset()

format_str will return edited string (Color, indent and around signs).

print function omit the details like file name, line etc. and print formatted text.

>>> mylogging.print("No details about me.")

Another function is for ignoring specified warnings from imported libraries. Global warnings settings are edited, so if you use it in some library that other users will use, don’t forget to reset user settings after end of your call with reset_filter_always() or use it in witch.catch_warnings(): block.

Sometimes only message does not work, then ignore it with class and warning type

>>> import warnings
...
>>> ignored_warnings = ["mean of empty slice"]
>>> ignored_warnings_class_type = [
...     ("TestError", FutureWarning),
... ]
...
>>> mylogging.my_warnings.filter_always(ignored_warnings, ignored_warnings_class_type)
...
>>> warnings.warn("mean of empty slice")
...
>>> mylogging.my_warnings.reset_filter_always()

If somebody is curious how it looks like on light color theme, here it goes…

Config

Some config, that can be configured globally for not having to use in each function call.

Config values has docstrings, so description should be visible in IDE help.

output - Whether log to file or to console. ‘console’ or path to file (string or pathlib.Path). Defaults by “console”

level - Set level of severity that will be printed, e.g. DEBUG, ERROR, CRITICAL. Defaults to ‘WARNING’.

filter - If the same logs, print it always, once or turn all logging off. Possible values “ignore”, “once”, “always” or “error”. Defaults to “once”.

Usually that’s everything you will set up. If you need different formatting of output, you can define

blacklist - You can filter out some specific messages by content.

formatter_console_str or formatter_file_str with for example:

"{asctime} {levelname} " + "{filename}:{lineno}" + "{message}"

Rest options should be OK by default, but it’s all up to you of course: You can set up for example

around - Whether separate logs with line breaks and ==== or shrink to save space. Defaults to True.

colorize - Possible options: [True, False, ‘auto’]. Colorize is automated. If to console, it is colorized, if to file, it’s not (.log files can be colorized by IDE). Defaults to ‘auto’.

to_list - You can save all the logs in the list and log it later (use case: used in multiprocessing processes to be able to use once filter)

stream - If you want to use a stream (for example io.StringIO)

logger

It’s possible to use logger in any other way if you need (though it’s usually not necessary), you can find used logger in logger_module. There are also used filters and handlers.

multiprocessing

If using in subprocesses, to be able to use filters (just once), it’s possible to redirect logs and warnings, send as results as log later in main process

>>> logs_list = []
>>> warnings_list = []
...
>>> logs_redirect = mylogging.misc.redirect_logs_and_warnings(logs_list, warnings_list)
...
>>> logs_redirect.close_redirect()
...
>>> mylogging.misc.log_and_warn_from_lists(logs_list, warnings_list)

mylogging.critical(message: str, caption: str = '') → None

Same as warning, but usually describe error that stopped the application.

Parameters

• message (str) – Any string content of error.

• caption (str, optional) – Heading of error. Defaults to ‘User message’.

mylogging.debug(message: str, caption: str = '') → None

Log debug info. Only difference with info is filtering level in config.

Parameters

• message (str) – Message to be logged.

• caption (str, optional) – Heading of warning. Defaults to ‘User message’.

mylogging.error(message: str, caption: str = '') → None

Same as warn, but can be filtered different way with level. This is only for logging message. If you want to log error code, you can use function traceback.

Parameters

• message (str) – Any string content of error.

• caption (str, optional) – Heading of error. Defaults to ‘User message’.

mylogging.format_str(message: str, caption: str = 'User message', around: Union[bool, str] = 'config', use_object_conversion: bool = True, indent: int = 4, uncolored_message: None | str = None, level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'WARNING') → str

Return enhanced colored message. Used for raising exceptions, assertions.

Parameters

• message (str) – Any string content of warning.

• caption (str, optional) – Heading of warning. Defaults to ‘User message’.

• around (Union[bool, str], optional) – If print to file - whether print ====== lines around. If ‘auto’, then if output is to file, then around = False, if output == “console”, around = True. If ‘config’, use global config (defaults ‘auto’). Defaults to ‘config’.

• use_object_conversion (bool, optional) – Turn into object (If call in raise - only way to print colors). If you need string to variable, call str(). Defaults to True.

• indent (int, optional) – By how many spaces are logs indented (for better visibility). If 0, than no indentation. Defaults to 4.

• uncolored_message (None | str, optional) – Appendix added to end that will not be colorized (or already is colorized). Used for example for tracebacks. Defaults to None.

• level (str, optional) – Defaults to “DEBUG”.

Returns

Enhanced message as a string, that is wrapped by and can be colorized.

Return type

str

Example

>>> format_str("Formated", caption="Caption")


    ========= Caption =========

    Formated

    ===========================

mylogging.info(message: str, caption: str = '') → None

Log info.

Parameters

• message (str) – Message to be logged.

• caption (str, optional) – Heading of warning. Defaults to ‘User message’.

mylogging.print(message: str, caption: str = '', level: typing_extensions.Literal[DEBUG, INFO, WARNING, ERROR, CRITICAL] = 'DEBUG') → None

Log message without details (file, line etc.). Only difference with normal print is filter and level in config.

Parameters

• message (str) – Message to be logged.

• caption (str, optional) – Heading of warning. Defaults to ‘User message’.

• level (Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]) – Print can have also levels same as logs to be able to filter. Defaults to “DEBUG”

mylogging.traceback(message: str = '', caption: str = 'error_type', level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'ERROR', stack_level: int = 3, remove_frame_by_line_str: None | list = None) → None

Log message with current traceback as content. It means, that error was caught, but still something crashed.

Parameters

• message (str) – Any string content of traceback.

• caption (str, optional) – Caption of warning. If ‘error_type’, than Error type (e.g. ZeroDivisionError) is used. Defaults to ‘error_type’.

• level (Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], optional) – Defaults to “DEBUG”.

• stack_level (int, optional) – How many calls to log from error. Defaults to 3.

• remove_frame_by_line_str (None | list, optional) – If there is some level in stack that should be omitted, add line here. Defaults to None.

mylogging.warn(message: str, caption: str = '') → None

Raise warning - just message, not traceback. Can be colorized. Display of warning is based on warning settings. You can configure how to cope with warnings with function set_warnings with debug parameter. Instead of traceback_warning this is not from caught error. It usually bring some information good to know.

Parameters

• message (str) – Any string content of warning.

• caption (str, optional) – Heading of warning. Defaults to ‘User message’.

Subpackages

• mylogging.colors package
  • Submodules
    • mylogging.colors.colors_module module
• mylogging.misc package
  • Submodules
    • mylogging.misc.misc_module module
• mylogging.my_logging package
  • Submodules
    • mylogging.my_logging.logger_module module
• mylogging.my_traceback package
  • Submodules
    • mylogging.my_traceback.my_traceback_module module
• mylogging.my_warnings package
  • Submodules
    • mylogging.my_warnings.warnings_module module

Submodules

• mylogging.config_module module
• mylogging.helpers module
• mylogging.internal_module module
• mylogging.log_functions module
• mylogging.str_formating module