perspective-python 4.4.1

#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
#  ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
#  ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
#  ┃ This file is part of the Perspective library, distributed under the terms ┃
#  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
#  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

from random import random
from .viewer_traitlets import PerspectiveTraitlets
import perspective

# from .. import Server

# ─  │  ┌ ┬ ┐
# ┄  ┆  ├ ┼ ┤ ╲ ╱
# ┈  ┊  └ ┴ ┘
# ━  ┃  ┏ ┳ ┓ ┏ ┯ ┓ ┏ ┳ ┓ ┏ ┯ ┓
# ┅  ┇  ┣ ╋ ┫ ┣ ┿ ┫ ┠ ╂ ┨ ┠ ┼ ┨
# ┉  ┋  ┗ ┻ ┛ ┗ ┷ ┛ ┗ ┻ ┛ ┗ ┷ ┛

# global_server = PySyncServer()


class PerspectiveViewer(PerspectiveTraitlets, object):
    """PerspectiveViewer wraps the `perspective.Table` API and exposes an API
    around creating views, loading data, and updating data.
    """

    # Viewer attributes that should be saved in `save()` and restored using
    # `restore()`. Symmetric to `PERSISTENT_ATTRIBUTES` in `perspective-viewer`.
    PERSISTENT_ATTRIBUTES = (
        "group_by",
        "split_by",
        "filter",
        "sort",
        "aggregates",
        "columns",
        "expressions",
        "plugin",
        "plugin_config",
        "theme",
        "settings",
        "title",
        "version",
    )

    def __init__(
        self,
        plugin="Datagrid",
        columns=None,
        group_by=None,
        split_by=None,
        aggregates=None,
        sort=None,
        filter=None,
        expressions=None,
        plugin_config=None,
        settings=True,
        theme=None,
        title=None,
        # ignored, here for restore compatibility
        version=None,
    ):
        """Initialize an instance of `PerspectiveViewer` with the given viewer
        configuration.  Do not pass a `Table` or data into the constructor -
        use the :func:`load()` method to provide the viewer with data.

        Keyword Arguments:
            columns (:obj:`list` of :obj:`str`): A list of column names to be
                visible to the user.
            group_by (:obj:`list` of :obj:`str`): A list of column names to
                use as group by.
            split_by (:obj:`list` of :obj:`str`): A list of column names
                to use as split by.
            aggregates (:obj:`dict` of :obj:`str` to :obj:`str`):  A dictionary
                of column names to aggregate types, which specify aggregates
                for individual columns.
            sort (:obj:`list` of :obj:`list` of :obj:`str`): A list of lists,
                each list containing a column name and a sort direction
                (``asc``, ``desc``, ``asc abs``, ``desc abs``, ``col asc``,
                ``col desc``, ``col asc abs``, ``col desc abs``).
            filter (:obj:`list` of :obj:`list` of :obj:`str`): A list of lists,
                each list containing a column name, a filter comparator, and a
                value to filter by.
            expressions (:obj:`list` of :obj:`str`): A list of string
                expressions which are applied to the view.
            plugin (:obj:`str`/:obj:`perspective.Plugin`): Which plugin to
                select by default.
            plugin_config (:obj:`dict`): A configuration for the plugin, i.e.
                the datagrid plugin or a chart plugin.
            settings(:obj:`bool`): Whether the perspective query settings
                panel should be open.
            theme (:obj:`str`): The color theme to use.
            version (:obj:`str`): The version this configuration is restored from.
                This should only be used when restoring a configuration,
                and should not be set manually.

        Examples:
            >>> viewer = PerspectiveViewer(
            ...     aggregates={"a": "avg"},
            ...     group_by=["a"],
            ...     sort=[["b", "desc"]],
            ...     filter=[["a", ">", 1]],
            ...     expressions=["\"a\" + 100"]
            ... )
        """

        # The Table under management by this viewer and its
        # attached PerspectiveManager
        self._table = None
        self._client = None

        # Viewer configuration
        self.plugin = plugin  # validate_plugin(plugin)
        self.columns = columns or []  # validate_columns(columns) or []
        self.group_by = group_by or []  # validate_group_by(group_by) or []
        self.split_by = split_by or []  # validate_split_by(split_by) or []
        self.aggregates = aggregates or {}  # validate_aggregates(aggregates) or {}
        self.sort = sort or []  # validate_sort(sort) or []
        self.filter = filter or []  # validate_filter(filter) or []
        self.expressions = expressions or {}  # validate_expressions(expressions) or {}
        self.plugin_config = (
            plugin_config or {}
        )  # validate_plugin_config(plugin_config) or {}
        self.settings = settings
        self.theme = theme
        self.title = title

    def new_proxy_session(self, cb):
        return perspective.ProxySession(self._client, cb)

    @property
    def client(self):
        """Returns the ``perspective.Client`` or ``perspective.AsyncClient`` under management by the viewer."""
        return self._client

    @property
    def table(self):
        """Returns the ``perspective.Table`` or ``perspective.AsyncTable`` under management by the viewer."""
        return self._table

    def is_async(self):
        """Returns whether this widget has an async interface or synchronous"""
        return isinstance(self._table, perspective.perspective.AsyncTable)

    def load(self, data, **options):
        """Given a ``perspective.Table``, a ``perspective.AsyncTable``,
        or data that can be handled by ``perspective.Table``, pass it to the
        viewer.  Like `__init__`, load accepts a `perspective.Table`, a dataset,
        or a schema.

        ``load()`` resets the state of the viewer: if a ``perspective.Table``
        has already been  loaded, ``**options`` is ignored as the options
        already set on the ``Table`` take precedence.

        If data is passed in, a ``perspective.Table`` is automatically created
        by this method, and the options passed to ``**config`` are extended to
        the new Table.  If the widget already has a dataset, and the new data
        has different columns to the old one, then the widget state (pivots,
        sort, etc.) is cleared to prevent applying settings on columns that
        don't exist.

        When a ``perspective.AsyncTable`` is loaded, the widget's interface
        becomes async. Methods which operate on the underlying Perspective
        view, inclusive of the ``load()`` call itself, return coroutine values
        which must be awaited.

        Loading a ``perspective.Table`` or plain data will make the interface
        synchronous again.

        Args:
            data (:obj:`Table`|:obj:`AsyncTable`|:obj:`dict`|:obj:`list`|:obj:`pandas.DataFrame`|:obj:`bytes`|:obj:`str`): a
                `perspective.Table` instance, a `perspective.AsyncTable`
                instance, or a dataset to be loaded in the viewer.

        Keyword Arguments:
            name (:obj:`str`): An optional name to reference the table by so it can
                be accessed from the front-end. If not provided, a name will
                be generated.
            index (:obj:`str`): A column name to be used as the primary key.
                Ignored if a ``Table`` or ``AsyncTable`` is supplied.
            limit (:obj:`int`): A upper limit on the number of rows in the Table.
                Cannot be set at the same time as `index`. Ignored if a
                ``Table`` or ``AsyncTable`` is supplied.

        Returns:
            coro (:obj:`coroutine`): when `AsyncTable` is passed, the `load()` call must be awaited
        """
        name = options.pop("name", str(random()))

        # Reset the viewer when `load()` is called multiple times.
        if self.table is not None:
            self.reset()

        if isinstance(data, perspective.perspective.AsyncTable):
            self._table = data
            async def load_table():
                self._client = await self.table.get_client()
                self.table_name = self.table.get_name()
                # If the user does not set columns to show, synchronize viewer state
                # with dataset.
                if len(self.columns) == 0:
                    self.columns = await self.table.columns()

            return load_table()
        elif isinstance(data, perspective.perspective.Table):
            self._table = data
            self._client = data.get_client()
        elif isinstance(data, perspective.perspective.View) or isinstance(data, perspective.perspective.AsyncView):
            raise TypeError(
                "Views cannot be loaded directly, load a table or raw data instead"
            )
        else:
            self._table = perspective.table(data, name=name, **options)
            self._client = perspective.GLOBAL_CLIENT

        # If the user does not set columns to show, synchronize viewer state
        # with dataset.
        if len(self.columns) == 0:
            self.columns = self.table.columns()

        self.table_name = self.table.get_name()

    def update(self, data):
        """Update the table under management by the viewer with new data.
        This function follows the semantics of `Table.update()`, and will be
        affected by whether an index is set on the underlying table.

        When this widget has loaded an ``AsyncTable``, returns a coroutine
        which must be awaited.

        Args:
            data (:obj:`dict`|:obj:`list`|:obj:`pandas.DataFrame`): the
            update data for the table.

        Returns:
            coro (:obj:`coroutine`): when async, must be awaited
        """
        return self.table.update(data)

    def clear(self):
        """Clears the rows of this viewer's ``Table``."""
        if self.table is not None:
            return self.table.clear()

    def replace(self, data):
        """Replaces the rows of this viewer's `Table` with new data.

        Args:
            data (:obj:`dict`|:obj:`list`|:obj:`pandas.DataFrame`): new data
            to set into the table - must conform to the table's schema.

        Returns:
            coro (:obj:`coroutine`): when async, must be awaited
        """
        if self.table is not None:
            return self.table.replace(data)

    def save(self):
        """Get the viewer's attributes as a dictionary, symmetric with `restore`
        so that a viewer's configuration can be reproduced."""
        return {
            attr: getattr(self, attr)
            for attr in PerspectiveViewer.PERSISTENT_ATTRIBUTES
        }

    def restore(self, **kwargs):
        """Restore a given set of attributes, passed as kwargs
        (e.g. dictionary). Symmetric with `save` so that a given viewer's
        configuration can be reproduced."""
        for k, v in kwargs.items():
            if k in PerspectiveViewer.PERSISTENT_ATTRIBUTES:
                setattr(self, k, v)

    def to_kwargs(self):
        """Get the viewer's attributes as a list of kwargs, which can be passed to
        the viewer constructor"""
        attrs = self.save()
        defaults = {
            "columns": [],
            "group_by": [],
            "split_by": [],
            "aggregates": {},
            "sort": [],
            "filter": [],
            "expressions": {},
            "plugin_config": {},
            "version": "2.10.0",
        }
        kwargs = {}
        for key, default in defaults.items():
            if attrs.get(key) != default:
                kwargs[key] = attrs[key]
        return ", ".join(
            ["{}={}".format(attr, repr(val)) for attr, val in kwargs.items()]
        )

    def reset(self):
        """Resets the viewer's attributes and state, but does not delete or
        modify the underlying `Table`.

        Example:
            widget = PerspectiveWidget(data, group_by=["date"], plugin=Plugin.XBAR)
            widget.reset()
            widget.plugin  #
        """
        self.group_by = []
        self.split_by = []
        self.filter = []
        self.sort = []
        self.expressions = {}
        self.aggregates = {}
        self.columns = []
        self.plugin = "Datagrid"
        self.plugin_config = {}

    def delete(self, delete_table=True):
        """Delete the Viewer's data and clears its internal state. If
        ``delete_table`` is True, the underlying `perspective.Table` and the
        internal `View` object will be deleted.

        Args:
            delete_table (:obj:`bool`) : whether the underlying `Table` will be
                deleted. Defaults to True.

        Returns:
            coro (:obj:`coroutine`): when async and `delete_table` is `True`,
                must be awaited
        """
        ret = None
        if delete_table:
            # Delete table
            ret = self.table.delete()
            self.table_name = None
            self._table = None

        self.reset()
        return ret