cmdkit.logging

An extension of the standard library’s logging module.

We extend the Logger and the LogRecord implementations to allow for an extended range of levels and attributes. Also included is a preset definition of logging styles.

Merely importing this module in your application will trigger the extensions; which will have an effect on any package using the standard logging implementation.

---

Reference

class Logger(name, level=0)

Extend standard logging.Logger with NOTICE, TRACE, and DEVEL levels.

classmethod with_name(name: str) → Logger

Shorthand for log: Logger = logging.getLogger(name).

classmethod default(name: str = '', format: str = '%(ansi_bold)s%(ansi_level)s%(levelname)8s%(ansi_reset)s %(ansi_faint)s[%(name)s]%(ansi_reset)s %(message)s', **kwargs) → Logger

Calls standard logging.basicConfig and returns logger.

class LogRecord(*args, **kwargs)

Extends standard logging.LogRecord to include ANSI colors, time formats, and other attributes.

New program-level attributes.

app_id

A UUID specific to the running Python process.

hostname

Output of socket.gethostname().

hostname_short

Trimmed version of hostname without subdomains.

relative_name

Trimmed version of the program name without the leading package; e.g., mypackage.server becomes server.

Available Ansi escape sequences. The value of ansi_level corresponds to the defined level_color mapping for the current record’s level.

ansi_level

ansi_reset

ansi_bold

ansi_faint

ansi_italic

ansi_underline

ansi_black

ansi_red

ansi_green

ansi_yellow

ansi_blue

ansi_magenta

ansi_cyan

ansi_white

Newly available time attributes. Beyond the standard %(asctime)s you can use one of the following formats with respect to the elapsed time since application start.

elapsed

The current elapsed time in seconds.

elapsed_ms

The current elapsed time in milliseconds.

elapsed_delta

The current elapsed time as formatted by datetime.timedelta.

elapsed_hms

The current elapsed time formatted as dd-hh:mm:ss.sss.

HOSTNAME: str

Result of call to socket.gethostname().

HOSTNAME_SHORT: str

Trimmed version of HOSTNAME with only the initial part of the domain.

INSTANCE: str

A UUID (uuid.uuid4()) unique to the Python process.

level_by_name: Dict[str, int]

Get the actual level from its str representation.

levelname = 'info'
level = level_by_name[levelname.upper()]

logging_styles: Dict[str, Dict[str, str]]

Dictionary containing preset definitions (essentially just the format). Other things would be named parameters to Logger.default() (or the standard library logging.basicConfig()).

Available styles include:

• default (colorized level, module name)

• short (colorized level name only)

• detailed (colorized time stamp, hostname, level name, module name)

• detailed-compact (colorized relative time stamp, short hostname, level name, relative module name)

• system (similar to detailed but without colorization and includes application UUID).

import os
from cmdkit.logging import Logger, level_by_name, logging_styles

level = os.getenv('MYAPP_LOGGING_LEVEL', 'INFO')
style = os.getenv('MYAPP_LOGGING_STYLE', 'DEFAULT')

log = Logger.default(name='myapp',
                     level=level_by_name[level.upper()],
                     **logging_styles[style.lower()])

DEFAULT_LOGGING_STYLE: str = 'default'

Used by Logger.default() to select from logging_styles dictionary.

NOTSET: int = 0

DEVEL: int = 1

TRACE: int = 5

DEBUG: int = 10

INFO: int = 20

NOTICE: int = 25

WARNING: int = 30

ERROR: int = 40

CRITICAL: int = 50