research_helpers.log

Provides structured logging over the standard library. Requires the log extra. See Logging.

research_helpers.log.get_logger(name=None, **context)

Return a logger.

Parameters:

• name (str | None, default: None) – logger name, normally ‘__name__’.

• **context (Any) – fields bound to every event from this logger, e.g. task=’resolution’.

Return type:

BoundLogger

Returns:

The logger.

research_helpers.log.reset_logging()

Remove the handlers this module installed.

Return type:

None

research_helpers.log.set_log_file(name, filename)

Route one logger’s records to their own file.

Parameters:

• name (str) – the logger name, as passed to ‘get_logger’ (normally a module’s ‘__name__’).

• filename (str) – the file, relative to the configured log directory.

Return type:

Path

Returns:

The path records will be written to.

Raises:

RuntimeError – if file logging is not configured.

research_helpers.log.setup_logging(*, console_level=None, file_level=None, directory=None, colour=None, stream=None)

Configure logging, replacing any configuration this module made earlier.

Parameters:

• console_level (int | str | None, default: None) – minimum level shown on the console.

• file_level (int | str | None, default: None) – minimum level written to file.

• directory (Path | str | None, default: None) – where to write log files. None means console output only.

• colour (str | None, default: None) – ‘auto’ to colour only a terminal, or ‘always’ / ‘never’.

• stream (TextIO | None, default: None) – where console output goes, defaulting to stdout.

Return type:

None

class research_helpers.log.Renderer(*, colours=False, clock_only=False)

Bases: object

Render one event as a line, with any traceback on the lines after it.

Parameters:

• colours (bool)

• clock_only (bool)

class research_helpers.log.MultiFileHandler(base_dir, level=logging.DEBUG)

Bases: Handler

Write each record to the file its logger is mapped to or to a shared default.

Parameters:

• base_dir (Path | str)

• level (int)

set_target_file(logger_name, filename)

Route one logger’s records to ‘filename’.

Parameters:

• logger_name (str) – the logger to route, as passed to ‘get_logger’.

• filename (str) – name of the file, relative to the handler’s directory.

Return type:

Path

Returns:

The path records will be written to.

emit(record)

Write a record to the file its logger is mapped to.

Return type:

None

Parameters:

record (LogRecord)

setFormatter(fmt)

Set the formatter on this handler and every file it writes.

Return type:

None

Parameters:

fmt (Formatter | None)

close()

Close every open file.

Return type:

None

class research_helpers.log.LoggingTqdm(*args, **kwargs)

Bases: tqdm_asyncio

A tqdm writing to stdout and sizing itself to the terminal.

Parameters:

• args (Any)

• kwargs (Any)

research_helpers.log.progress()

Route log output through ‘tqdm.write’ for the duration.

Return type:

Iterator[None]