API reference

Import the logot API in your tests:

from logot import Logot, logged

logot

class logot.Logot(*, timeout: float = 3.0)

The main logot API for capturing and waiting for logs.

See also

See Log-based testing 🪵 usage guide.

Parameters:

timeout (float) – The default timeout (in seconds) for calls to wait_for() and await_for(). Defaults to DEFAULT_TIMEOUT.

capturing(*, level: int | str = 0, logger: Logger | str | None = None) → AbstractContextManager[Logot]

Captures logs emitted at the given level by the given logger for the duration of the context.

If the given logger level is less verbose than the requested level, it will be temporarily adjusted to the requested level for the duration of the context.

Parameters:

• level (int | str) – A log level (e.g. logging.DEBUG) or string name (e.g. "DEBUG"). Defaults to logging.NOTSET, specifying that all logs are captured.

• logger (Logger | str | None) – A logger or logger name to capture logs from. Defaults to the root logger.

Return type:

AbstractContextManager[Logot]

wait_for(log: Logged, *, timeout: float | None = None) → None

Waits for the expected log pattern to arrive or the timeout to expire.

Parameters:

• log (Logged) – The expected log pattern.

• timeout (float | None) – How long to wait (in seconds) before failing the test. Defaults to the timeout passed to Logot.

Raises:

AssertionError – If the expected log pattern does not arrive within timeout seconds.

Return type:

None

async await_for(log: Logged, *, timeout: float | None = None) → None

Waits asynchronously for the expected log pattern to arrive or the timeout to expire.

Parameters:

• log (Logged) – The expected log pattern.

• timeout (float | None) – How long to wait (in seconds) before failing the test. Defaults to the timeout passed to Logot.

Raises:

AssertionError – If the expected log pattern does not arrive within timeout seconds.

Return type:

None

assert_logged(log: Logged) → None

Fails immediately if the expected log pattern has not arrived.

Parameters:

log (Logged) – The expected log pattern.

Raises:

AssertionError – If the expected log pattern has not arrived.

Return type:

None

assert_not_logged(log: Logged) → None

Fails immediately if the expected log pattern has arrived.

Parameters:

log (Logged) – The expected log pattern.

Raises:

AssertionError – If the expected log pattern has arrived.

Return type:

None

DEFAULT_LEVEL: ClassVar[int | str] = 0

The default level used by capturing().

This is logging.NOTSET, specifying that all logs are captured.

DEFAULT_LOGGER: ClassVar[Logger | str | None] = None

The default logger used by capturing().

This is the root logger.

DEFAULT_TIMEOUT: ClassVar[float] = 3.0

The default timeout used by wait_for() and await_for().

This is 3 seconds.

class logot.Logged

A log pattern passed to Logot.wait_for(), Logot.await_for() and similar APIs.

Important

Logged instances are immutable and can be reused between tests.

Note

This is an abstract class and cannot be instantiated. Use the helpers in logot.logged to create log patterns.

See also

See Log pattern matching usage guide.

logot.logged

logot.logged.log(level: int | str, msg: str) → Logged

Creates a log pattern representing a log record at the given level with the given msg.

Parameters:

• level (int | str) – A log level (e.g. logging.DEBUG) or string name (e.g. "DEBUG").

• msg (str) – A log message pattern.

Return type:

Logged

logot.logged.debug(msg: str) → Logged

Creates a log pattern representing a log record at DEBUG level with the given msg.

Parameters:

msg (str) – A log message pattern.

Return type:

Logged

logot.logged.info(msg: str) → Logged

Creates a log pattern representing a log record at INFO level with the given msg.

Parameters:

msg (str) – A log message pattern.

Return type:

Logged

logot.logged.warning(msg: str) → Logged

Creates a log pattern representing a log record at WARNING level with the given msg.

Parameters:

msg (str) – A log message pattern.

Return type:

Logged

logot.logged.error(msg: str) → Logged

Creates a log pattern representing a log record at ERROR level with the given msg.

Parameters:

msg (str) – A log message pattern.

Return type:

Logged

logot.logged.critical(msg: str) → Logged

Creates a log pattern representing a log record at CRITICAL level with the given msg.

Parameters:

msg (str) – A log message pattern.

Return type:

Logged