Skip to content

Storylib

ipyvizzustory.storylib

Environment independent modules.

ipyvizzustory.storylib.animation

A module for working with chart animations.

DataFilter

Bases: Data

A class for representing a data filter.

Source code in ipyvizzustory/storylib/animation.py 
class DataFilter(Data):
    """A class for representing a data filter."""

    def build(self) -> dict:
        """
        A method for overwriting `ipyvizzu.Data.build()` method.
        Data initialized with a `DataFilter` must contain only a filter.

        Returns:
            A dictionary contains the filter key with the filter expression.

        Raises:
            ValueError: If `DataFilter` does not contain filter or contains anything else.
        """

        if len(self.keys()) != 1 or "filter" not in self:
            raise KeyError("Data must contain filter and only that.")
        return {"filter": self["filter"]}
build()

A method for overwriting ipyvizzu.Data.build() method. Data initialized with a DataFilter must contain only a filter.

Returns:

Type Description
dict

A dictionary contains the filter key with the filter expression.

Raises:

Type Description
ValueError

If DataFilter does not contain filter or contains anything else.
Source code in ipyvizzustory/storylib/animation.py 
def build(self) -> dict:
    """
    A method for overwriting `ipyvizzu.Data.build()` method.
    Data initialized with a `DataFilter` must contain only a filter.

    Returns:
        A dictionary contains the filter key with the filter expression.

    Raises:
        ValueError: If `DataFilter` does not contain filter or contains anything else.
    """

    if len(self.keys()) != 1 or "filter" not in self:
        raise KeyError("Data must contain filter and only that.")
    return {"filter": self["filter"]}

ipyvizzustory.storylib.story

A module for working with presentation stories.

Step

Bases: dict

A class for representing a step of a slide.

Source code in 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.

        Note:
            Do not set `anim_options` argument, it will raise `NotImplementedError` error.

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

        Raises:
            ValueError: If `animations` are not set.
            NotImplementedError: If `anim_options` are set.
        """

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

        if anim_options:
            # self["animOptions"] = PlainAnimation(**anim_options).build()
            raise NotImplementedError("Anim options are not supported.")

    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.

Note

Do not set anim_options argument, it will raise NotImplementedError error.

Parameters:

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

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

 ()
**anim_options optional

Animation options such as duration.

 {}

Raises:

Type Description
ValueError

If animations are not set.
NotImplementedError

If anim_options are set.
Source code in ipyvizzustory/storylib/story.py 
def __init__(
    self,
    *animations: Union[Data, Style, Config],
    **anim_options: Optional[Union[str, int, float, dict]],
):
    """
    Step constructor.

    Note:
        Do not set `anim_options` argument, it will raise `NotImplementedError` error.

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

    Raises:
        ValueError: If `animations` are not set.
        NotImplementedError: If `anim_options` are set.
    """

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

    if anim_options:
        # self["animOptions"] = PlainAnimation(**anim_options).build()
        raise NotImplementedError("Anim options are not supported.")

Slide

Bases: list

A class for representing a slide of a presentation story.

Source code in 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 (optional): The first step can also be added to the slide in the constructor.
        """

        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`.
        """

        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

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

 None
Source code in ipyvizzustory/storylib/story.py 
def __init__(self, step: Optional[Step] = None):
    """
    Slide constructor.

    Args:
        step (optional): The first step can also be added to the slide in the constructor.
    """

    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.
Source code in 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`.
    """

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

StorySize

A class for representing the size of a presentation story.

Source code in ipyvizzustory/storylib/story.py 
class StorySize:
    """A class for representing the size of a presentation story."""

    def __init__(self, width: Optional[str] = None, height: Optional[str] = None):
        """
        StorySize constructor.

        Args:
            width (optional): The width of a presentation story.
            height (optional): The height of a presentation story.
        """
        self._width = width
        self._height = height

        self._style = ""
        if any([width is not None, height is not None]):
            width = "" if width is None else f"width: {width};"
            height = "" if height is None else f"height: {height};"
            self._style = f"vizzuPlayer.style.cssText = '{width}{height}'"

    @property
    def width(self) -> Optional[str]:
        """A property for returning the width of a presentation story."""

        return self._width

    @property
    def height(self) -> Optional[str]:
        """A property for returning the height of a presentation story."""

        return self._height

    @property
    def style(self) -> str:
        """
        A property for returning the cssText width and height of a presentation story.

        Note:
            If `width` and `height` are not set it returns an empty string.
        """

        return self._style
width: Optional[str] property

A property for returning the width of a presentation story.

height: Optional[str] property

A property for returning the height of a presentation story.

style: str property

A property for returning the cssText width and height of a presentation story.

Note

If width and height are not set it returns an empty string.

__init__(width=None, height=None)

StorySize constructor.

Parameters:

Name Type Description Default
width optional

The width of a presentation story.

 None
height optional

The height of a presentation story.

 None
Source code in ipyvizzustory/storylib/story.py 
def __init__(self, width: Optional[str] = None, height: Optional[str] = None):
    """
    StorySize constructor.

    Args:
        width (optional): The width of a presentation story.
        height (optional): The height of a presentation story.
    """
    self._width = width
    self._height = height

    self._style = ""
    if any([width is not None, height is not None]):
        width = "" if width is None else f"width: {width};"
        height = "" if height is None else f"height: {height};"
        self._style = f"vizzuPlayer.style.cssText = '{width}{height}'"

Story

Bases: dict

A class for representing a presentation story.

Source code in ipyvizzustory/storylib/story.py 
class Story(dict):
    """A class for representing a presentation story."""

    def __init__(self, data: Data, style: Optional[Style] = None):
        """
        Presentation Story constructor.

        Args:
            data: Data set for the whole presentation story.
                After initialization `data` can not be modified,
                but it can be filtered.
            style (optional): Style settings for the presentation story.
                `style` can be changed at each presentation step.

        Raises:
            TypeError: If the type of the `data` is not `ipyvizzu.Data`.
            TypeError: If the type of the `style` is not `ipyvizzu.Style`.
        """

        super().__init__()

        self._size: StorySize = StorySize()

        self._features: List[str] = []
        self._events: List[str] = []

        if not data or type(data) != Data:  # pylint: disable=unidiomatic-typecheck
            raise TypeError("Type must be Data.")
        self.update(data.build())

        if style:
            if type(style) != Style:  # pylint: disable=unidiomatic-typecheck
                raise TypeError("Type must be Style.")
            self.update(style.build())

        self["slides"] = []

    def add_slide(self, slide: Slide) -> None:
        """
        A method for adding a slide for the story.

        Args:
            slide: The next slide of the story.

        Raises:
            TypeError: If the type of the `slide` is not `Slide`.
        """

        if not slide or type(slide) != Slide:  # pylint: disable=unidiomatic-typecheck
            raise TypeError("Type must be Slide.")
        self["slides"].append(slide)

    def set_feature(self, name: str, enabled: bool) -> None:
        """
        A method for enabling or disabling a feature of the story.

        Args:
            name: The name of the feature.
            enabled: True if enabled or False if disabled.
        """

        self._features.append(f"chart.feature('{name}', {json.dumps(enabled)});")

    def add_event(self, event: str, handler: str) -> None:
        """
        A method for creating and turning on an event handler.

        Args:
            event: The name of the event.
            handler: The handler JavaScript expression as string.
        """

        self._events.append(
            f"chart.on('{event}', event => {{{' '.join(handler.split())}}});"
        )

    def set_size(
        self, width: Optional[str] = None, height: Optional[str] = None
    ) -> None:
        """
        A method for setting width/height settings.

        Args:
            width (optional): The width of the presentation story.
            height (optional): The height of the presentation story.
        """

        self._size = StorySize(width=width, height=height)

    def to_html(self) -> str:
        """
        A method for assembling the html code.

        Returns:
            The assembled html code as string.
        """

        vizzu_player_data = f"{json.dumps(self, cls=RawJavaScriptEncoder)}"
        return DISPLAY_TEMPLATE.format(
            id=uuid.uuid4().hex[:7],
            vizzu_story=VIZZU_STORY,
            vizzu_player_data=vizzu_player_data,
            chart_size=self._size.style,
            chart_features=f"\n{DISPLAY_INDENT * 3}".join(self._features),
            chart_events=f"\n{DISPLAY_INDENT * 3}".join(self._events),
        )

    def export_to_html(self, filename: PathLike) -> None:
        """
        A method for exporting the story into html file.

        Args:
            filename: The path of the target html file.
        """

        with open(filename, "w", encoding="utf8") as file_desc:
            file_desc.write(self.to_html())
__init__(data, style=None)

Presentation Story constructor.

Parameters:

Name Type Description Default
data Data

Data set for the whole presentation story. After initialization data can not be modified, but it can be filtered.

 required
style optional

Style settings for the presentation story. style can be changed at each presentation step.

 None

Raises:

Type Description
TypeError

If the type of the data is not ipyvizzu.Data.
TypeError

If the type of the style is not ipyvizzu.Style.
Source code in ipyvizzustory/storylib/story.py 
def __init__(self, data: Data, style: Optional[Style] = None):
    """
    Presentation Story constructor.

    Args:
        data: Data set for the whole presentation story.
            After initialization `data` can not be modified,
            but it can be filtered.
        style (optional): Style settings for the presentation story.
            `style` can be changed at each presentation step.

    Raises:
        TypeError: If the type of the `data` is not `ipyvizzu.Data`.
        TypeError: If the type of the `style` is not `ipyvizzu.Style`.
    """

    super().__init__()

    self._size: StorySize = StorySize()

    self._features: List[str] = []
    self._events: List[str] = []

    if not data or type(data) != Data:  # pylint: disable=unidiomatic-typecheck
        raise TypeError("Type must be Data.")
    self.update(data.build())

    if style:
        if type(style) != Style:  # pylint: disable=unidiomatic-typecheck
            raise TypeError("Type must be Style.")
        self.update(style.build())

    self["slides"] = []
add_slide(slide)

A method for adding a slide for the story.

Parameters:

Name Type Description Default
slide Slide

The next slide of the story.

 required

Raises:

Type Description
TypeError

If the type of the slide is not Slide.
Source code in ipyvizzustory/storylib/story.py 
def add_slide(self, slide: Slide) -> None:
    """
    A method for adding a slide for the story.

    Args:
        slide: The next slide of the story.

    Raises:
        TypeError: If the type of the `slide` is not `Slide`.
    """

    if not slide or type(slide) != Slide:  # pylint: disable=unidiomatic-typecheck
        raise TypeError("Type must be Slide.")
    self["slides"].append(slide)
set_feature(name, enabled)

A method for enabling or disabling a feature of the story.

Parameters:

Name Type Description Default
name str

The name of the feature.

 required
enabled bool

True if enabled or False if disabled.

 required
Source code in ipyvizzustory/storylib/story.py 
def set_feature(self, name: str, enabled: bool) -> None:
    """
    A method for enabling or disabling a feature of the story.

    Args:
        name: The name of the feature.
        enabled: True if enabled or False if disabled.
    """

    self._features.append(f"chart.feature('{name}', {json.dumps(enabled)});")
add_event(event, handler)

A method for creating and turning on an event handler.

Parameters:

Name Type Description Default
event str

The name of the event.

 required
handler str

The handler JavaScript expression as string.

 required
Source code in ipyvizzustory/storylib/story.py 
def add_event(self, event: str, handler: str) -> None:
    """
    A method for creating and turning on an event handler.

    Args:
        event: The name of the event.
        handler: The handler JavaScript expression as string.
    """

    self._events.append(
        f"chart.on('{event}', event => {{{' '.join(handler.split())}}});"
    )
set_size(width=None, height=None)

A method for setting width/height settings.

Parameters:

Name Type Description Default
width optional

The width of the presentation story.

 None
height optional

The height of the presentation story.

 None
Source code in ipyvizzustory/storylib/story.py 
def set_size(
    self, width: Optional[str] = None, height: Optional[str] = None
) -> None:
    """
    A method for setting width/height settings.

    Args:
        width (optional): The width of the presentation story.
        height (optional): The height of the presentation story.
    """

    self._size = StorySize(width=width, height=height)
to_html()

A method for assembling the html code.

Returns:

Type Description
str

The assembled html code as string.
Source code in ipyvizzustory/storylib/story.py 
def to_html(self) -> str:
    """
    A method for assembling the html code.

    Returns:
        The assembled html code as string.
    """

    vizzu_player_data = f"{json.dumps(self, cls=RawJavaScriptEncoder)}"
    return DISPLAY_TEMPLATE.format(
        id=uuid.uuid4().hex[:7],
        vizzu_story=VIZZU_STORY,
        vizzu_player_data=vizzu_player_data,
        chart_size=self._size.style,
        chart_features=f"\n{DISPLAY_INDENT * 3}".join(self._features),
        chart_events=f"\n{DISPLAY_INDENT * 3}".join(self._events),
    )
export_to_html(filename)

A method for exporting the story into html file.

Parameters:

Name Type Description Default
filename PathLike

The path of the target html file.

 required
Source code in ipyvizzustory/storylib/story.py 
def export_to_html(self, filename: PathLike) -> None:
    """
    A method for exporting the story into html file.

    Args:
        filename: The path of the target html file.
    """

    with open(filename, "w", encoding="utf8") as file_desc:
        file_desc.write(self.to_html())

ipyvizzustory.storylib.template

A module for storing the html templates.

VIZZU_STORY = 'https://cdn.jsdelivr.net/npm/vizzu-story@~0.1.0/dist/vizzu-story.min.js' module-attribute

str: A variable for storing the default url of vizzu-story package.

DISPLAY_INDENT = ' ' module-attribute

str: A variable for storing the default indent in the html template.

DISPLAY_TEMPLATE = '\n<div>\n <vizzu-player id="{id}" controller></vizzu-player>\n <script type="module">\n import VizzuPlayer, {{ Vizzu as lib }} from "{vizzu_story}";\n\n\n const vizzuPlayerData = {vizzu_player_data};\n const vizzuPlayer = document.getElementById("{id}")\n // story.set_size()\n {chart_size}\n vizzuPlayer.slides = vizzuPlayerData;\n vizzuPlayer.vizzu.initializing.then(chart => {{\n // story.set_feature()\n {chart_features}\n // story.add_event()\n {chart_events}\n }});\n </script>\n</div>\n' module-attribute

str: A variable for storing the vizzu-story html template.