API Reference

Decks and Slides

spiel.Deck dataclass

Bases: Sequence[Slide]

Represents a "deck" of "slides": a presentation.

name: str instance-attribute

The name of the Deck, which will be displayed in the footer.

default_transition: Type[Transition] | None = Swipe class-attribute instance-attribute

The default slide transition animation; used if the slide being moved to does not specify its own transition. Defaults to the Swipe transition. Set to None for no transition animation.

slide(title='', bindings=None, transition=None)

A decorator that creates a new slide in the deck, with the decorated function as the Slide.content.

PARAMETER	DESCRIPTION
title	The title to display for the slide. TYPE: str DEFAULT: ''
bindings	A mapping of keys to callables to be executed when those keys are pressed, when on this slide. TYPE: Mapping[str, Callable[..., None]] | None DEFAULT: None
transition	The transition animation to use when moving to this slide. Set to None to use the Deck.default_transition of the deck this slide is in. TYPE: Type[Transition] | None DEFAULT: None

add_slides(*slides)

Add Slides to a Deck.

This function is primarily useful when adding multiple slides at once, probably generated programmatically. If adding a single slide, prefer the Deck.slide decorator.

PARAMETER	DESCRIPTION
*slides	The Slides to add. TYPE: Slide DEFAULT: ()

spiel.Slide dataclass

Represents a single slide in the presentation.

title: str = '' class-attribute instance-attribute

The title of the Slide, which will be displayed in the footer.

content: Content = Text class-attribute instance-attribute

A callable that is invoked by Spiel to display the slide's content.

The function may optionally take arguments with these names:

• trigger: The current Trigger state, for use in animations.

bindings: Mapping[str, Callable[..., None]] = field(default_factory=dict) class-attribute instance-attribute

A mapping of keys to callables to be executed when those keys are pressed, when on this slide.

transition: Type[Transition] | None = Swipe class-attribute instance-attribute

The transition animation to use when moving to this slide. Set to None to use the Deck.default_transition of the deck this slide is in.

Rendering Content

spiel.Triggers dataclass

Bases: Sequence[float]

Provides information to Slide.content about the current slide's "trigger state".

Triggers is a Sequence of times (produced by time.monotonic) that the current slide was triggered at. Note that the slide will be triggered once when it starts being displayed, so the first trigger time will be the time when the slide started being displayed.

now: float instance-attribute

The time that the slide content is being rendered at. Use this is as a single consistent value to base relative times on.

time_since_last_trigger: float cached property

The elapsed time since the most recent trigger.

time_since_first_trigger: float cached property

The elapsed time since the first trigger, which is equivalent to the time since the slide started being displayed.

triggered: bool cached property

Returns whether the slide has been manually triggered (i.e., this ignores the initial trigger from when the slide starts being displayed).

take(iter, offset=1)

Takes elements from the iterable iter equal to the number of times in the Triggers minus the offset.

PARAMETER	DESCRIPTION
iter	The iterable to take elements from. TYPE: Iterable[T]
offset	This offset will be subtracted from the number of triggers, reducing the number of elements that will be returned. It defaults to 1 to ignore the automatic trigger from when the slide starts being shown. TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
Iterator[T]	An iterator over the first len(self) - offset elements of iter.

Transitions

spiel.Direction

Bases: Enum

An enumeration that describes which direction a slide transition animation should move in: whether we're going to the next slide, or to the previous slide.

Next = 'next' class-attribute instance-attribute

Indicates that the transition should handle going to the next slide.

Previous = 'previous' class-attribute instance-attribute

Indicates that the transition should handle going to the previous slide.

spiel.Transition

Bases: Protocol

A protocol that describes how to implement a transition animation.

See Writing Custom Transitions for more details on how to implement the protocol.

initialize(from_widget, to_widget, direction)

A hook function to set up any CSS that should be present at the start of the transition.

PARAMETER	DESCRIPTION
from_widget	The widget showing the slide that we are leaving. TYPE: Widget
to_widget	The widget showing the slide that we are entering. TYPE: Widget
direction	The desired direction of the transition animation. TYPE: Direction

progress(from_widget, to_widget, direction, progress)

A hook function that is called each time the progress of the transition animation updates.

PARAMETER	DESCRIPTION
from_widget	The widget showing the slide that we are leaving. TYPE: Widget
to_widget	The widget showing the slide that we are entering. TYPE: Widget
direction	The desired direction of the transition animation. TYPE: Direction
progress	The progress of the animation, as a percentage (e.g., initial state is 0, final state is 100). Note that this is not necessarily bounded between 0 and 100, nor is it necessarily monotonically increasing, depending on the underlying Textual animation easing function, which may overshoot or bounce. However, it will always start at 0 and end at 100, no matter which direction the transition should move in. TYPE: float

spiel.Swipe

Bases: Transition

A transition where the current and incoming slide are placed side-by-side and gradually slide across the screen, with the current slide leaving and the incoming slide entering.

Presenting Decks

spiel.present(deck_path, watch_path=None)

Present the deck defined in the given deck_path.

PARAMETER	DESCRIPTION
deck_path	The file to look for a deck in. TYPE: Path | str
watch_path	When filesystem changes are detected below this path (recursively), reload the deck from the deck_path. If None (the default), use the parent directory of the deck_path. TYPE: Path | str | None DEFAULT: None