Logging - tmuxp.log

Log utilities for tmuxp.

class tmuxp.log.TmuxpLoggerAdapter(logger, extra=None, merge_extra=False)

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)

Merge extra dictionary on Python < 3.13.

Return type:

tuple[Any, MutableMapping[str, Any]]

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

Configure tmuxp’s logging for CLI use.

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

Return type:

None

Parameters:

logger (Logger) – logger instance for tmuxp

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

Stylize terminal logging output.

Return type:

str

class tmuxp.log.LogFormatter(color=True, **kwargs)

Bases: Formatter

Format logs for tmuxp.

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

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

Return type:

str

Parameters:

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

Returns:

Template for logger message.

Return type:

str

format(record)

Format a log record.

Return type:

str

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

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

Return type:

str

Parameters:

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

Returns:

Log template.

Return type:

str

class tmuxp.log.DebugLogFormatter(color=True, **kwargs)

Bases: LogFormatter

Provides greater technical details than standard log Formatter.

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

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

Return type:

str

Parameters:

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

Returns:

Log template.

Return type:

str

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

Attach a file handler to the tmuxp logger.

Return type:

None

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.

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)

Print user-facing CLI output.

Return type:

None

Parameters:

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

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

Examples

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

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