Narrator API

The Narrator has several methods which can change the logging behavior as you need.

class Narrator(adapters: list[Adapter] | None = None)

The narrator conveys the story to the audience.

attach_adapter(adapter: Adapter) → None

Attach a new adapter to the Narrator’s microphone.

property cable_kinked: bool

Whether or not the Narrator’s microphone cable is kinked.

off_the_air() → Generator

Turns off narration completely during this context.

mic_cable_kinked() → Generator

Put a kink in the microphone line, storing narrations.

Once this context is left, all stored narrations will be flushed. You can call clear_backup to drop all stored narrations, or flush_backup to log them all (and clear them afterward).

clear_backup() → None

Clear the backed-up narrations from a kinked cable.

flush_backup() → None

Let all the backed-up narration flow through the kink.

narrate(channel: str, **kwargs: Kwargs | None) → ContextManager

Speak the message into the microphone plugged in to all the adapters.

announcing_the_act(func: Callable, line: str, gravitas: str | None = None) → ContextManager

Narrate the title of the act.

setting_the_scene(func: Callable, line: str, gravitas: str | None = None) → ContextManager

Narrate the title of the scene.

stating_a_beat(func: Callable, line: str, gravitas: str | None = None) → ContextManager

Narrate an emotional beat.

whispering_an_aside(line: str, gravitas: str | None = None) → ContextManager

Narrate a conspiratorial aside (as a stage-whisper).

explains_the_error(exc: Exception) → None

Explain the exception to all the adapters.

attaches_a_file(filepath: str, **kwargs: Any) → None

Attach a file for the various adapters.

Adapters

There is one adapter included in ScreenPy, which allows the Narrator to reach stdout.

StdOutAdapter

class StdOutAdapter(stdout_manager: StdOutManager | None = None)

Adapt the Narrator’s microphone to allow narration to stdout.

Examples:

the_narrator.attach_adapter(StdOutAdapter())