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: 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[Union[str, int, float, dict]]

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: 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: 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[Step]

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: 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: The width of a presentation story.
            height: 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 storing the width of a presentation story.

        Returns:
            The width of a presentation story.
        """

        return self._width

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

        Returns:
            The height of a presentation story.
        """

        return self._height

    @property
    def style(self) -> str:
        """
        A property for storing the style of a presentation story.

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

        Returns:
            The cssText width and height of a presentation story.
        """

        return self._style

    @staticmethod
    def is_pixel(value: Any) -> bool:
        """
        A static method for checking the type of the given value.

        Args:
            value: The value to check.

        Returns:
            True if the value is pixel, False otherwise.
        """

        value_is_pixel = False
        if isinstance(value, str):
            if value.endswith("px"):
                value_is_pixel = value[:-2].isnumeric()
        return value_is_pixel
width: Optional[str] property

A property for storing the width of a presentation story.

Returns:

Type Description
Optional[str]

The width of a presentation story.
height: Optional[str] property

A property for storing the height of a presentation story.

Returns:

Type Description
Optional[str]

The height of a presentation story.
style: str property

A property for storing the style of a presentation story.

Note

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

Returns:

Type Description
str

The cssText width and height of a presentation story.
__init__(width=None, height=None)

StorySize constructor.

Parameters:

Name Type Description Default
width Optional[str]

The width of a presentation story.

 None
height Optional[str]

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: The width of a presentation story.
        height: 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}'"
is_pixel(value) staticmethod

A static method for checking the type of the given value.

Parameters:

Name Type Description Default
value Any

The value to check.

 required

Returns:

Type Description
bool

True if the value is pixel, False otherwise.
Source code in ipyvizzustory/storylib/story.py 
@staticmethod
def is_pixel(value: Any) -> bool:
    """
    A static method for checking the type of the given value.

    Args:
        value: The value to check.

    Returns:
        True if the value is pixel, False otherwise.
    """

    value_is_pixel = False
    if isinstance(value, str):
        if value.endswith("px"):
            value_is_pixel = value[:-2].isnumeric()
    return value_is_pixel

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: 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: The width of the presentation story.
            height: The height of the presentation story.
        """

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

    def _repr_html_(self) -> str:
        return self.to_html()

    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]

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: 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[str]

The width of the presentation story.

 None
height Optional[str]

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: The width of the presentation story.
        height: 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.