Skip to content

Code reference

Build, present and share animated data stories in Jupyter Notebook and similar environments.

ipyvizzu-story package consists of two main parts:

  • Storylib: environment independent modules
  • Env: environment dependent modules

ipyvizzu-story package tries to figure out the environment and import the correct type of Story, however Story could be imported with full path.

ipyvizzu-story package imports the following objects in __init__.py:

ipyvizzustory.get_story()

A method for returning the appropriate Story for the environment.

Returns:

Type Description
Union[Story, Story, Story]

The appropriate Story for the environment.
Source code in src/ipyvizzustory/__init__.py 
def get_story():
    """
    A method for returning the appropriate Story for the environment.

    Returns:
        (Union[ipyvizzustory.env.py.story.Story, ipyvizzustory.env.ipy.story.Story, ipyvizzustory.env.st.story.Story]):
            The appropriate `Story` for the environment.
    """  # pylint: disable=line-too-long

    return JupyterStory or StreamlitStory or PythonStory  # type: ignore

ipyvizzustory.Story = get_story() module-attribute

Available types:

ipyvizzustory.Slide

Bases: list

A class for representing a slide of a presentation story.

Source code in src/ipyvizzustory/storylib/story.py 
class Slide(list):
    """A class for representing a slide of a presentation story."""

    def __init__(self, step: Optional[Step] = None):
        """
        Slide constructor.

        Args:
            step: The first step can also be added to the slide in the constructor.

        Example:
            Initialize a slide without step:

                slide = Slide()

            Initialize a slide with a step:

                slide = Slide(
                    Step(
                        Config({"x": "Foo", "y": "Bar"})
                    )
                )
        """

        super().__init__()
        if step:
            self.add_step(step)

    def add_step(self, step: Step) -> None:
        """
        A method for adding a step for the slide.

        Args:
            step: The next step of the slide.

        Raises:
            TypeError: If the type of the `step` is not
                [Step][ipyvizzustory.storylib.story.Step].

        Example:
            Add steps to a slide:

                slide = Slide()
                slide.add_step(
                    Step(
                        Config({"x": "Foo", "y": "Bar"})
                    )
                )
                slide.add_step(
                    Step(
                        Config({"color": "Foo", "x": "Baz", "geometry": "circle"})
                    )
                )
        """

        if not step or type(step) != Step:  # pylint: disable=unidiomatic-typecheck
            raise TypeError("Type must be Step.")
        self.append(step)

__init__(step=None)

Slide constructor.

Parameters:

Name Type Description Default
step Optional[Step]

The first step can also be added to the slide in the constructor.

 None
Example

Initialize a slide without step:

slide = Slide()

Initialize a slide with a step:

slide = Slide(
    Step(
        Config({"x": "Foo", "y": "Bar"})
    )
)
Source code in src/ipyvizzustory/storylib/story.py 
def __init__(self, step: Optional[Step] = None):
    """
    Slide constructor.

    Args:
        step: The first step can also be added to the slide in the constructor.

    Example:
        Initialize a slide without step:

            slide = Slide()

        Initialize a slide with a step:

            slide = Slide(
                Step(
                    Config({"x": "Foo", "y": "Bar"})
                )
            )
    """

    super().__init__()
    if step:
        self.add_step(step)

add_step(step)

A method for adding a step for the slide.

Parameters:

Name Type Description Default
step Step

The next step of the slide.

 required

Raises:

Type Description
TypeError

If the type of the step is not Step.
Example

Add steps to a slide:

slide = Slide()
slide.add_step(
    Step(
        Config({"x": "Foo", "y": "Bar"})
    )
)
slide.add_step(
    Step(
        Config({"color": "Foo", "x": "Baz", "geometry": "circle"})
    )
)
Source code in src/ipyvizzustory/storylib/story.py 
def add_step(self, step: Step) -> None:
    """
    A method for adding a step for the slide.

    Args:
        step: The next step of the slide.

    Raises:
        TypeError: If the type of the `step` is not
            [Step][ipyvizzustory.storylib.story.Step].

    Example:
        Add steps to a slide:

            slide = Slide()
            slide.add_step(
                Step(
                    Config({"x": "Foo", "y": "Bar"})
                )
            )
            slide.add_step(
                Step(
                    Config({"color": "Foo", "x": "Baz", "geometry": "circle"})
                )
            )
    """

    if not step or type(step) != Step:  # pylint: disable=unidiomatic-typecheck
        raise TypeError("Type must be Step.")
    self.append(step)

ipyvizzustory.Step

Bases: dict

A class for representing a step of a slide.

Source code in src/ipyvizzustory/storylib/story.py 
class Step(dict):
    """A class for representing a step of a slide."""

    def __init__(
        self,
        *animations: Union[Data, Style, Config],
        **anim_options: Optional[Union[str, int, float, dict]],
    ):
        """
        Step constructor.

        Args:
            *animations: List of [Data][ipyvizzu.Data],
                [Config][ipyvizzu.Config] and [Style][ipyvizzu.Style] objects.
                A `Step` can contain each of the above once.
            **anim_options: Animation options such as duration.

        Raises:
            ValueError: If `animations` are not set.

        Example:
            Initialize a step with a [Config][ipyvizzu.Config] object:

                step = Step(
                    Config({"x": "Foo", "y": "Bar"})
                )
        """

        super().__init__()
        if not animations:
            raise ValueError("No animation was set.")
        self._update(*animations)

        if anim_options:
            self["animOptions"] = anim_options

    def _update(self, *animations: Union[Data, Style, Config]) -> None:
        for animation in animations:
            if not animation or type(animation) not in [
                Data,
                Style,
                Config,
            ]:  # pylint: disable=unidiomatic-typecheck
                raise TypeError("Type must be Data, Style or Config.")
            if type(animation) == Data:  # pylint: disable=unidiomatic-typecheck
                animation = DataFilter(animation)

            builded_animation = animation.build()
            common_keys = set(builded_animation).intersection(set(self))
            if common_keys:
                raise ValueError(f"Animation is already merged: {common_keys}")
            self.update(builded_animation)

__init__(*animations, **anim_options)

Step constructor.

Parameters:

Name Type Description Default
*animations Union[Data, Style, Config]

List of Data, Config and Style objects. A Step can contain each of the above once.

 ()
**anim_options Optional[Union[str, int, float, dict]]

Animation options such as duration.

 {}

Raises:

Type Description
ValueError

If animations are not set.
Example

Initialize a step with a Config object:

step = Step(
    Config({"x": "Foo", "y": "Bar"})
)
Source code in src/ipyvizzustory/storylib/story.py 
def __init__(
    self,
    *animations: Union[Data, Style, Config],
    **anim_options: Optional[Union[str, int, float, dict]],
):
    """
    Step constructor.

    Args:
        *animations: List of [Data][ipyvizzu.Data],
            [Config][ipyvizzu.Config] and [Style][ipyvizzu.Style] objects.
            A `Step` can contain each of the above once.
        **anim_options: Animation options such as duration.

    Raises:
        ValueError: If `animations` are not set.

    Example:
        Initialize a step with a [Config][ipyvizzu.Config] object:

            step = Step(
                Config({"x": "Foo", "y": "Bar"})
            )
    """

    super().__init__()
    if not animations:
        raise ValueError("No animation was set.")
    self._update(*animations)

    if anim_options:
        self["animOptions"] = anim_options