Logging - tmuxp.log

Log utilities for tmuxp.

class tmuxp.log.TmuxpLoggerAdapter

class

Bases: LoggerAdapter

LoggerAdapter that merges extra dictionary on Python < 3.13.

Follows the portable pattern to avoid repeating the same extra on every call while preserving the ability to add per-call extra kwargs.

Examples

>>> adapter = TmuxpLoggerAdapter(
...     logging.getLogger("test"),
...     {"tmux_session": "my-session"},
... )
>>> msg, kwargs = adapter.process("hello %s", {"extra": {"tmux_window": "editor"}})
>>> msg
'hello %s'
>>> kwargs["extra"]["tmux_session"]
'my-session'
>>> kwargs["extra"]["tmux_window"]
'editor'

process(msg, kwargs)

method

Merge extra dictionary on Python < 3.13.

Parameters:

• msg (Any)

• kwargs (MutableMapping[str, Any])

Return type:

tuple[Any, MutableMapping[str, Any]]

tmuxp.log.setup_logger(logger=None, level='INFO')

function

Configure tmuxp’s logging for CLI use.

Can checks for any existing loggers to prevent loading handlers twice.

Parameters:

• logger (Logger) – logger instance for tmuxp

• level (str)

Return type:

None

tmuxp.log.set_style(message, stylized, style_before='', style_after='', prefix='', suffix='')

function

Stylize terminal logging output.

Parameters:

• message (str)

• stylized (bool)

• style_before (str)

• style_after (str)

• prefix (str)

• suffix (str)

Return type:

str

class tmuxp.log.LogFormatter

class

Bases: Formatter

Format logs for tmuxp.

template(record, stylized=False, **kwargs)

method

Return the prefix for the log message. Template for Formatter.

Parameters:

• record (logging.LogRecord) – Object passed from logging.Formatter.format().

• self (Formatter)

• stylized (bool)

• kwargs (Any)

Returns:

Template for logger message.

Return type:

str

__init__(color=True, **kwargs)

method

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

Parameters:

• color (bool)

• kwargs (Any)

Return type:

None

format(record)

method

Format a log record.

Parameters:

record (LogRecord)

Return type:

str

tmuxp.log.debug_log_template(self, record, stylized=False, **kwargs)

function

Return the prefix for the log message. Template for Formatter.

Parameters:

• record (logging.LogRecord) – Object passed from logging.Formatter.format().

• self (type[Formatter])

• stylized (bool | None)

• kwargs (Any)

Returns:

Log template.

Return type:

str

class tmuxp.log.DebugLogFormatter

class

Bases: LogFormatter

Provides greater technical details than standard log Formatter.

template(record, stylized=False, **kwargs)

method

Return the prefix for the log message. Template for Formatter.

Parameters:

• record (logging.LogRecord) – Object passed from logging.Formatter.format().

• self (type[Formatter])

• stylized (bool | None)

• kwargs (Any)

Returns:

Log template.

Return type:

str

tmuxp.log.setup_log_file(log_file, level='INFO')

function

Attach a file handler to the tmuxp logger.

Parameters:

• log_file (str) – Path to the log file.

• level (str) – Log level name (e.g. “DEBUG”, “INFO”). Selects formatter and sets handler filtering level.

Return type:

None

Examples

>>> import tempfile, os, logging
>>> f = tempfile.NamedTemporaryFile(suffix=".log", delete=False)
>>> f.close()
>>> setup_log_file(f.name, level="INFO")
>>> tmuxp_logger = logging.getLogger("tmuxp")
>>> tmuxp_logger.handlers = [
...     h for h in tmuxp_logger.handlers if not isinstance(h, logging.FileHandler)
... ]
>>> os.unlink(f.name)

tmuxp.log.tmuxp_echo(message=None, file=None)

function

Print user-facing CLI output.

Parameters:

• message (str | None) – Message to print. If None, does nothing.

• file (t.TextIO | None) – Output stream. Defaults to sys.stdout.

Return type:

None

Examples

>>> tmuxp_echo("Session loaded")
Session loaded

>>> tmuxp_echo("Warning message")
Warning message