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: str | int = 'DEBUG', 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.

See also

See Log capturing usage guide.

Parameters:
Return type:

AbstractContextManager[Logot]

capture(captured: Captured) → None#

Adds the given captured log record to the internal capture queue.

Any waiters blocked on wait_for() to await_for() will be notified and wake up if their log pattern is satisfied.

Note

This method is for integration with 3rd-party logging frameworks. It is not generally used when writing tests.

See also

See Capturing 3rd-party logs usage guide.

Parameters:

captured (Captured) – The captured log.

Return type:

None

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

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

Parameters:

  • logged (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(logged: Logged, *, timeout: float | None = None) → None#

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

Parameters:

  • logged (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(logged: Logged) → None#

Fails immediately if the expected log pattern has not arrived.

Parameters:

logged (Logged) – The expected log pattern.

Raises:

AssertionError – If the expected log pattern has not arrived.

Return type:

None

assert_not_logged(logged: Logged) → None#

Fails immediately if the expected log pattern has arrived.

Parameters:

logged (Logged) – The expected log pattern.

Raises:

AssertionError – If the expected log pattern has arrived.

Return type:

None

clear() → None#

Clears any captured logs.

Return type:

None

DEFAULT_LEVEL: ClassVar[str | int] = 'DEBUG'#

The default level used by capturing().

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 (in seconds) used by wait_for() and await_for().

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.

class logot.Captured(levelname: str, msg: str, *, levelno: int)#

A captured log record.

Send Captured logs to Logot.capture() to integrate with 3rd-party logging frameworks

Note

This class is for integration with 3rd-party logging frameworks. It is not generally used when writing tests.

See also

See Capturing 3rd-party logs usage guide.

Parameters:

  • levelname (str) – The log level name (e.g. "DEBUG").

  • msg (str) – The log message.

  • levelno (int) – The log level number (e.g. logging.DEBUG).

levelname: str#

The log level name (e.g. "DEBUG").

msg: str#

The log message.

levelno: int#

The log level number (e.g. logging.DEBUG).

logot.logged#

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

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

Parameters:
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