# Copyright (C) 2019-2022 HERE Global B.V. and its affiliate(s).
# All rights reserved.
#
# This software and other materials contain proprietary information
# controlled by HERE and are protected by applicable copyright legislation.
# Any use and utilization of this software and other materials and
# disclosure to any third parties is conditional upon having a separate
# agreement with HERE for the access, use, utilization or disclosure of this
# software. In the absence of such agreement, the use of the software is not
# allowed.

"""This module defines base class for HERE inspector package."""

import abc
from typing import Dict, List, Optional, Union

from here.inspector.styles import Color, Theme
from here.inspector.utils import Features, Tiles
from shapely.geometry import Point
from xyzservices.lib import TileProvider


class Inspector(abc.ABC):
    """
    An interactive map data inspector that can be rendered in Jupyter.

    Use ``add_features`` and/or ``add_tiles`` functions to add content.
    Configure, if needed, via the ``set_*`` functions.
    Call ``show()`` to render the result.
    """

    @abc.abstractmethod
    def add_features(
        self,
        features: Features,
        name=None,
        style: Optional[Union[Color, Dict]] = None,
    ) -> "Inspector":
        """
        Add to the inspector a collection of map features (attributed geometries) as new layer.

        The features layer can be named and styled.

        :param features: the attributed geometries to render. Supported types:
          - ``gpd.GeoSeries``, unattributed geometries
          - ``gpd.GeoDataFrame``, attributes geometries
          - ``Iterable`` of `BaseGeometry`, it can be any container
                         but also a ``Generator`` of unattributed geometries
          - ``Iterable`` of pair of ``BaseGeometry`` and ``Dict``, it can be any container
                         but also a ``Generator`` of geometries paired with attributes
          - ``Dict``     a parsed GeoJSON ``FeatureCollection`` or ``Feature``
          - ``Iterable`` of parsed GeoJSON `Feature`, it can be any container
                         but also a ``Generator`` of parsed GeoJSON features
        :param name: an optional name to assign to the layer
        :param style: an optional style for the features. If not present, a default one is picked.
          It can be a generic inspector style, as defined in ``here.inspector.styles``,
          or directly a style dictionary, compatible with the inspector implementation.
        :return: ``self``, for further chaining  # noqa
        """

    @abc.abstractmethod
    def add_tiles(
        self,
        tiles: Optional[Tiles] = None,
        name=None,
        style: Optional[Union[Color, Dict]] = None,
    ) -> "Inspector":
        """
        Add to the inspector a tiling grid as new layer.

        The grid can be a complete grid or contain only some tiles.
        The grid layer can be named and styled.

        :param tiles: the identifier of the tiles to render. Supported types:
          - ``pd.Series`` of tile identifiers
          - ``Iterable``  of tile identifiers, it can be any container but also a ``Generator``
          - ``None``      add the complete grid of all the tiles defined by the tiling scheme
        :param name: an optional name to assign to the layer
        :param style:
          an optional style for the tiling grid. If not present, a default one is picked.
          It can be a generic inspector style, as defined in ``here.inspector.styles``,
          or directly a style dictionary, compatible with the inspector implementation.
        :return: ``self``, for further chaining  # noqa
        """

    @abc.abstractmethod
    def set_center(self, center: Point) -> "Inspector":
        """
        Configure the location to show in the inspector when opened.

        If not set, an optimal starting location
        is calculated from the geodata and tiling grids.

        :param center: the center point of the map
        :return: ``self``, for further chaining  # noqa
        """

    @abc.abstractmethod
    def set_zoom(self, zoom: int) -> "Inspector":
        """
        Configure the starting zoom level of the inspector.

        If not set, an optimal starting zoom level
        is calculated from the geodata and tiling grids.

        :param zoom: the zoom level, from 0 to 31
        :return: ``self``, for further chaining  # noqa
        """

    @abc.abstractmethod
    def set_colors(self, colors: List[Color]) -> "Inspector":
        """
        Set the list of colors the inspector cycles through
        to render content when no color or style is specified.

        The default color list can be overridden in
        ``here.inspector.options.default_colors``.

        :param colors: a non-empty list of colors
        :return: ``self``, for further chaining  # noqa
        :raises ValueError: in case the colors are not valid  # noqa
        """

    @abc.abstractmethod
    def set_theme(self, theme: Theme) -> "Inspector":
        """
        Set the inspector theme.

        This determines the background map, if any, and colors.
        The default theme can be overridden in ``here.inspector.options.default_theme``.

        :param theme: one of the predefined inspector themes
        :return: ``self``, for further chaining  # noqa
        """

    @abc.abstractmethod
    def set_basemap(self, basemap: Optional[Union[dict, TileProvider]] = None) -> "Inspector":
        """Set a custom basemap to use as a background.

        This overrides the default base map of the theme, if any is defined.
        Setting it to ``None`` restores the default base map.

        :param basemap: Either a dictionary or an object of class:`xyzservices.lib.TileProvider`.
        :returns: ``self`, for further chaining  # noqa
        """

    @abc.abstractmethod
    def show(self):
        """
        Show the inspector in a Jupyter notebook.

        :returns: an object renderable by Jupyter  # noqa
        """

    @abc.abstractmethod
    def backend(self):
        """
        Expose the main abstraction of the rendering backend, to give
        advanced users the possibility to further customize the inspector.

        The type of the returned object depends on the rendering backend:

        - ``ipyleaflet.Map`` for the _ipyleaflet_ backend.

        The component is configured and loaded with data passed
        to the inspector so far. After further configuration of the
        rendering backend, users should call the ``show()`` function
        of the inspector to render the result. Alternatively, users
        can use the native API of the abstraction returned.

        :returns: main abstraction of the rendering backend  # noqa
        :raises ValueError: in case the backend can't be configured with the data provided  # noqa
        """

    # Possible additions:
    #
    # - restore the `selection` parameter to highlight some features
    # - restore (and redesign) a mechanism to represent multiple base maps
    # - restore callback-based styling
    # - a separate `select` method to simplify `add_features` and `add_tiles`
    # - a way to add generic ipyleaflet layers (or another type for another backend)
    # - functions to render selected use cases directly, like heatmaps, vector fields, ...
    # - support for multiple tiling schemes (so far `heretile` is assumed)
    # - labelling, selected attributes are places on the map in representative positions
    # - way to inspect id and attributes of objects when clicked
