ticterm.log

Default Logger

ticterm.log.default_logger

Default Logger instance for convenience.

ticterm.log.config

Alias for default_logger.config (Logger.config)

ticterm.log.debug(*message, stack_ascend=0)

Alias for default_logger.debug() (Logger.debug())

Return type:

None

ticterm.log.info(*message, stack_ascend=0)

Alias for default_logger.info() (Logger.info())

Return type:

None

ticterm.log.log(*message, level=2, stack_ascend=0)

Alias for default_logger.log() (Logger.log())

Return type:

None

ticterm.log.warn(*message, stack_ascend=0)

Alias for default_logger.warn() (Logger.warn())

Return type:

None

ticterm.log.error(*message, stack_ascend=0)

Alias for default_logger.error() (Logger.error())

Return type:

None

ticterm.log.set_progress(value=None, target=None)

Alias for default_logger.set_progress() (Logger.set_progress())

Return type:

ProgressContext

Constants

ticterm.log.LOG_LEVEL_PAD
ticterm.log.Logger.lib.LOG_LEVEL_PAD: int = 5

Longest level name length

ticterm.log.level_names
ticterm.log.Logger.lib.level_names: list[str] = ['debug', 'info', 'log', 'warn', 'error']

List of all level names

Enums

class ticterm.log.EmptyMessageMode(*values)

Bases: Enum

NEWLINE_ONLY = 0

Print just a newline (i.e. print())

NORMAL = 1

Print log output as normal just with a blank message.

class ticterm.log.Level

Bases: object

Log severity levels

DEBUG = 0

Debug

INFO = 1

Info

LOG = 2

Log

WARN = 3

Warn

ERROR = 4

Error

MAX = 4

Error

class ticterm.log.LevelLabelMode(*values)

Bases: Enum

OFF = 0

Disables log level label

ON = 1

Enables log level label

class ticterm.log.StackMode(*values)

Bases: Enum

OFF = 0

Disables stacks

ON = 1

Enables stacks

ONLY_BAD = 2

Only show on Level.WARN or above

class ticterm.log.TimestampMode(*values)

Bases: Enum

Timestamp Modes

OFF = 0

Disables timestamps

SINCE_START = 1

Shows time since start

EPOCH = 2

Shows time since epoch (unix time)

Classes

class ticterm.log.Config
reset(**kwargs)

Calls Config.update() with all kwargs set to Config.FLAG_DEFAULT. Any kwargs passed to this function will override the former kwargs. e.g. Config.reset(start_time=None) will reset everything but start_time

update(*, verbosity=None, tags=None, pad_char=None, timestamp_mode=None, timestamp_precision=None, stack_mode=None, stack_limit=None, level_label_mode=None, empty_message_mode=None, progress_width=None, project_root=None, start_time=None)

All parameters will accept Config.FLAG_DEFAULT to reset to default value or None to keep current value.

Parameters:
  • verbosity (int | None) – Should be a level/severity int

  • tags (list[str] | None) – A list of tags to prepend to log messages

  • pad_char (str | None) – Character to use when padding strings.

  • timestamp_mode (TimestampMode | None) – Should be a TimestampMode enum.

  • timestamp_precision (int | None) – Number of decimal points to be displayed for timestamps.

  • stack_mode (StackMode | None) – Should be a StackMode enum.

  • stack_limit (int | None) – Stack levels to show.

  • level_label_mode (LevelLabelMode | None) – Should be a LevelLabelMode enum.

  • empty_message_mode (EmptyMessageMode | None) – Should be an EmptyMessageMode enum.

  • progress_width (int | None) – Progress bar width in characters.

  • project_root (str | Any | None) – can be truthy to get from top-level module (default), a str (path), or falsey to unset.

  • start_time (bool | int | None) – None will reset start_time if it hasn’t already been set (default), truthy will reset it to time.time(),

any int will set it to that int.

DEFAULT_EMPTY_MESSAGE_MODE: EmptyMessageMode = 0
DEFAULT_LEVEL_LABEL_MODE: LevelLabelMode = 1
DEFAULT_PAD_CHAR: str = ' '
DEFAULT_PROGRESS_WIDTH: int = 40
DEFAULT_STACK_LIMIT: int = 1
DEFAULT_STACK_MODE: StackMode = 0
DEFAULT_TAGS: list[str] = []
DEFAULT_TIMESTAMP_MODE: TimestampMode = 0
DEFAULT_TIMESTAMP_PRECISION: int = 4
DEFAULT_VERBOSITY: int = 2
FLAG_DEFAULT: UpdateFlag = UpdateFlag(name='DEFAULT')

Flag that indicates value should reset to default

MEMBERS: list[str] = ['verbosity', 'tags', 'pad_char', 'timestamp_mode', 'timestamp_precision', 'stack_mode', 'stack_limit', 'empty_message_mode', 'level_label_mode', 'progress_width', 'project_root', 'start_time']

All configuration flags that vary between instances

empty_message_mode: EmptyMessageMode

Logger.log behavior when passed an empty message. Defaults to Config.DEFAULT_EMPTY_MESSAGE_MODE

level_label_mode: LevelLabelMode

Should generally be ON for accessiblity or readability in non-interactive (i.e. black-and-white) terminals. Defaults to Config.DEFAULT_LEVEL_LABEL_MODE

pad_char: str

Character to use when padding strings Defaults to Config.DEFAULT_PAD_CHAR

progress_width: int

Progress bar width in characters Defaults to Config.DEFAULT_PROGRESS_WIDTH

project_root: str

Path root for stack frames

stack_limit: StackMode

Defaults to Config.DEFAULT_STACK_LIMIT

stack_mode: StackMode

Defaults to Config.DEFAULT_STACK_MODE

start_time: float

Logging time start for TimestampMode.SINCE_START

tags: list[str]

A list of tags to prepend to log messages. Defaults to an empty list

timestamp_mode: TimestampMode

Defaults to Config.DEFAULT_TIMESTAMP_MODE

timestamp_precision: int

Number of decimal points to be displayed for timestamps. Defaults to Config.DEFAULT_TIMESTAMP_PRECISION

verbosity: int

Defaults to Config.DEFAULT_VERBOSITY

class ticterm.log.Logger(*, config=None)
debug(*message, stack_ascend=0)

Alias for log() with level kwarg set to Level.DEBUG

Return type:

None

error(*message, stack_ascend=0)

Alias for log() with level kwarg set to Level.ERROR

Return type:

None

info(*message, stack_ascend=0)

Alias for log() with level kwarg set to Level.INFO

Return type:

None

log(*message, level=2, stack_ascend=0)

Write log message to console

Parameters:
  • level (int) – Log message severity

  • stack_ascend (int) – Number of stack frames to ignore. e.g. If this is called from a custom log function, stack_ascend = 1 would prevent every message saying it originated in your custom log function.

Return type:

None

set_progress(value=None, target=None)

Updates current logger progress.

Parameters:
  • value (float, int, bool, None, optional) – Can be a float or int above 0, True to finalize progress bar and prevent it from being overwritten then disable it, or None to disable progress bar. Defaults to None

  • target (float, int, optional) – Can be a float or int above 0 or None to not change.

Return type:

ProgressContext

warn(*message, stack_ascend=0)

Alias for log() with level kwarg set to Level.WARN

Return type:

None

config: Config

Instance Configuration

progress_context: ProgressContext

Instance progress context for with statements

state: LoggerState

Instance state

class ticterm.log.LoggerState(progress=None, progress_target=None)

State object for Logger instances.

progress: float | None = None

Current progress bar value

progress_target: float | int | None = None

Current progress bar target value

class ticterm.log.ProgressContext(logger)

Context object for Logger progress bars for use in with statements.

Calls logger.set_progress(True) to finalize progress bar on exit.

Usage:

logger = Logger()

with logger.set_progress(0, 100) as update:
  for value in range(0, 100, 5):
    update(value)
    # or
    logger.set_progress(value)
class ticterm.log.UpdateFlag(name)

Special flags recognized by Config.update()