Documentation for quicklogging

Resources

  • doc: Documentation Status - read the doc on readthedocs (github rst is broken)
  • source code: on github
  • package: package
  • ci tests: Tests status with github actions

What is quicklogging

quicklogging is a Python logging wrapper to

  • remove a bit of logging boilerplate,
  • redirect print output.

quicklogging transparently provides a logger with a name relevant to the code at hand:

Important

The name of the logger is the name of the module making the call.

For instance, if you log from project/models/chair.py, your logger will be named project.models.chair.

This is a very important feature:

Advantage #1 of this naming scheme

the configuration of the logging.Logger s and handlers is much easier —muting, changing verbosity for a particular piece of code etc

Advantage #2

we can provide a quicklogging.catch_prints() and a quicklogging.warn_prints() functionality to catch calls to print() from specific modules (typically: the module you’re editing).

Licence, original authors

  • MIT (see file LICENCE ).
  • authors: majerti - Feth AREZKI

Requirements

Python versions

I tested 3.5 to 3.10 without annoyances.

Cannot test, but should work because I don’t know of API changes:

Libs required

None ! unless you’re running the tests (then you need stringimporter). . So I’ve got this easy badge: Requirements Status.

Doc contents

(if toctree is not displayed, then build the docs with sphinx or read them on readthedocs : Documentation Status.

How to use

The following examples assume a log format of

[%(name)s - %(level)s] %(message)s

You may want to read the Annex: Quick survival guide with the logging module to achieve this.

Quick, log once

Say you’re in myapp/models/music.py

import quicklogging
quicklogging.error("Hello world")

Your output will be:

[myapp.models.music - ERROR] Hello world

Log twice

Actually you’re logging more than once in myapp/views/music.py and want to optimize:

import quicklogging
logger = quicklogging.get_logger()
logger.debug("Howdy?")

This produces:

[myapp.views.music - DEBUG] Howdy?

then,

logger.warning("plop")

produces:

[myapp.views.music - WARNING] plop

Task oriented doc

Note

Many functions take a stackoverhead param, which is documented in quicklogging.base.get_logger().

Fetch a logger

Use quicklogging.base.get_logger() also available as quicklogging.get_logger().

Then, you can use the logger normally.

Available log wrappers

If logging multiple times, it is slower to use these than to use quicklogging.get_logger() and log with received object.

Source doc

Module quicklogging

(logging with a bit of cozyness)

log wrappers
Supplied convenience functions fetch a logger with the name of the module from which you’re calling them.
quicklogging.debug(*args, **kwargs)[source]

wrapper for logging.Logger.debug()

Variadic parameters: see logging.Logger.debug()

Parameters:stackoverhead (int) – see quicklogging.base.get_logger()
quicklogging.info(*args, **kwargs)[source]

wrapper for logging.Logger.info()

Variadic parameters: see logging.Logger.info()

Parameters:stackoverhead (int) – see quicklogging.base.get_logger()
quicklogging.warning(*args, **kwargs)[source]

wrapper for logging.Logger.warning()

Variadic parameters: see logging.Logger.warning()

Parameters:stackoverhead (int) – see quicklogging.base.get_logger()
quicklogging.error(*args, **kwargs)[source]

wrapper for logging.Logger.error()

Variadic parameters: see logging.Logger.error()

Parameters:stackoverhead (int) – see quicklogging.base.get_logger()
quicklogging.critical(*args, **kwargs)[source]

wrapper for logging.Logger.critical()

Variadic parameters: see logging.Logger.critical()

Parameters:stackoverhead (int) – see quicklogging.base.get_logger()
quicklogging.exception(*args, **kwargs)[source]

wrapper for logging.Logger.exception()

Variadic parameters: see logging.Logger.exception()

Parameters:stackoverhead (int) – see quicklogging.base.get_logger()

Module quicklogging.base

quicklogging.base.get_logger(stackoverhead=0)[source]

wrapper for getLogger

Typical use, say you’re in project/module/submodule.py and you want a logger.

l = get_logger()
print(l)

<logging.Logger at ... >

print(l.name)

project.module.submodule
Parameters:stackoverhead (int) – defaults to 0. How deep to look in the stack for fetching the logger name.
Returns:a logger named after the module at depth stackoverhead.
Return type:logging.Logger
quicklogging.base._log_with_level(func_name, *args, **kwargs)[source]

Internal convenience function to log with appropriate level

This function is called by the main log wrappers.

Fetches the appropriate logger, then the function named after the param func_name. This is slow, you’d better use :py:func`get_logger`.

Parameters:
  • func_name (str) – One of ‘debug’, ‘info’, ‘error’, etc
  • stackoverhead (int) – defaults to 0. How deep to look in the stack for
Return type:

None

Module quicklogging.stream_wrapper

class quicklogging.stream_wrapper.StreamWrapper(original_stream, logfunc, catch_all=False, warn=False)[source]

Implementation detail

Annex: Quick survival guide with the logging module

Sadly, some config still needs to take place for the logging module.

Disclaimer: we are not responsible for the boilerplate required by the logging API

You still need to configure logging somewhere at the start of your script -for complex apps (pyramid for example), initial scaffolding is likely to do this for you (see generated .ini file).

Example boilerplate for a script logging to my_app.log:

import logging
import logging.handlers
import quicklogging

# basicConfig is only effective once (if the root logger was not configured before)
logging.basicConfig(
    handlers=[logging.handlers.WatchedFileHandler('my_app.log')],
    format="%(asctime)s %(pathname)s:%(lineno)s%(message)s\\n",
    level=logging.WARNING
)