logot

Main logot API for log-based testing.

See also

See Log-based testing 🪵 usage guide.

API reference

class logot.Logot(*, capturer: Callable[[], Capturer] = logot.logging.LoggingCapturer, timeout: float = 3.0, async_waiter: Callable[[], AsyncWaiter] = logot.asyncio.AsyncioWaiter)

The main logot API for capturing and waiting for logs.

See also

See Log-based testing 🪵 usage guide.

Parameters:

• capturer – See Logot.capturer.

• timeout – See Logot.timeout.

• async_waiter – See Logot.async_waiter.

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

The default level used by capturing().

DEFAULT_NAME: ClassVar[str | None] = None

The default name used by capturing().

Defaults to None, representing the root logger.

DEFAULT_CAPTURER: ClassVar[Callable[[], Capturer]] = logot.logging.LoggingCapturer

The default capturer for new Logot instances.

DEFAULT_TIMEOUT: ClassVar[float] = 3.0

The default timeout (in seconds) for new Logot instances.

DEFAULT_ASYNC_WAITER: ClassVar[Callable[[], AsyncWaiter]] = logot.asyncio.AsyncioWaiter

The default async_waiter for new Logot instances.

capturer: Callable[[], Capturer]

The default capturer used by capturing().

Note

This is for integration with 3rd-party logging frameworks.

Defaults to Logot.DEFAULT_CAPTURER.

timeout: float

The default timeout (in seconds) for calls to wait_for() and await_for().

Defaults to Logot.DEFAULT_TIMEOUT.

async_waiter: Callable[[], AsyncWaiter]

The default async_waiter for calls to await_for().

Note

This is for integration with 3rd-party asynchronous frameworks.

Defaults to Logot.DEFAULT_ASYNC_WAITER.

capturing(*, level: str | int = 'DEBUG', name: str | None = None, capturer: Callable[[], Capturer] | None = None) → AbstractContextManager[Logot]

Captures logs emitted at the given level (or higher) by the given logger name for the duration of the context.

If the named 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:

• level – A log level name (e.g. "DEBUG") or numeric level (e.g. logging.DEBUG). Defaults to Logot.DEFAULT_LEVEL.

• name – A logger name to capture logs from. Defaults to Logot.DEFAULT_NAME.

• capturer – Protocol used to capture logs. This is for integration with 3rd-party logging frameworks. Defaults to Logot.capturer.

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.

Parameters:

captured – The captured log.

assert_logged(logged: Logged) → None

Fails immediately if the expected log pattern has not arrived.

Parameters:

logged – The expected log pattern.

Raises:

AssertionError – If the expected log pattern has not arrived.

assert_not_logged(logged: Logged) → None

Fails immediately if the expected log pattern has arrived.

Parameters:

logged – The expected log pattern.

Raises:

AssertionError – If the expected log pattern has arrived.

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

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

Parameters:

• logged – The expected log pattern.

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

Raises:

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

async await_for(logged: Logged, *, timeout: float | None = None, async_waiter: Callable[[], AsyncWaiter] | None = None) → None

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

Parameters:

• logged – The expected log pattern.

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

• async_waiter – Protocol used to pause tests until expected logs arrive. This is for integration with 3rd-party asynchronous frameworks. Defaults to Logot.async_waiter.

Raises:

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

reduce(logged: Logged) → Logged | None

Reduces the expected log pattern using captured logs.

• No match - The same log pattern is returned.

• Partial match - A smaller log pattern is returned.

• Full match - None is returned.

Note

This method is for building high-level log assertions. It is not generally used when writing tests.

Parameters:

logged – The expected log pattern.

clear() → None

Clears any captured logs.

class logot.Capturer

Protocol used by Logot.capturing() to capture logs.

Note

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

abstract start_capturing(logot: Logot, /, *, level: str | int, name: str | None) → None

Starts capturing logs for the given Logot.

Captured logs should be converted to a Captured instance and sent to Logot.capture().

Parameters:

• logot – The Logot instance.

• level – A log level name (e.g. "DEBUG") or numeric level (e.g. logging.DEBUG).

• name – A logger name to capture logs from.

abstract stop_capturing() → None

Stops capturing logs.

class logot.Captured(levelname: str, msg: str, *, levelno: int = ..., name: str | None = ...)

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.

Parameters:

• levelname – See Captured.levelname.

• msg – See Captured.msg.

• levelno – See Captured.levelno.

• name – See Captured.name.

levelname: str

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

msg: str

The log message.

levelno: int | None

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

This is an optional log capture field. When provided, it allows matching log patterns from logged.log() with a numeric level.

name: str | None

The logger name.

This is an optional log capture field. When provided, it allows matching log patterns from logged.log() with a name.

class logot.Logged

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

Important

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

Logged instances are immutable and can be reused between tests.

See also

See Log pattern matching usage guide.

abstract reduce(captured: Captured) → Logged | None

Reduces this log pattern using the given Captured log.

• No match - The same log pattern is returned.

• Partial match - A smaller log pattern is returned.

• Full match - None is returned.

Note

This method is for building high-level log assertions. It is not generally used when writing tests.

Parameters:

captured – The Captured log.

class logot.AsyncWaiter

Protocol used by Logot.await_for() to pause tests until expected logs arrive.

Note

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

abstract release() → None

Releases the test waiting on wait(), allowing it to resume immediately.

abstract async wait(*, timeout: float) → None

Waits asynchronously for release() to be called or the timeout to expire.

Parameters:

timeout – How long to wait (in seconds) before resuming.