Source code for archelond.data.abstract

"""
Abstract base class for data stores
"""
from __future__ import absolute_import, unicode_literals
from abc import ABCMeta, abstractmethod

from six import with_metaclass


[docs]class HistoryData(with_metaclass(ABCMeta, object)):
    """Abstract Data storage for command history

    Abstract class implementation of a database for use with command
    history.  Generally a command data item needs just two things, an
    ID and the command itself.  It also needs order.  See the
    :py:class:`archelond.data.MemoryData` class as the simplest
    structure using an :py:class:`collections.OrderedDict`.

    An ID can be any string, and the concrete implementation of
    :py:class:`HistoryData` is responsible for type casting it if
    needed.

    It is also required implicitly that there is only one entry
    per command.  Thus ``add`` ing the same command multiple times
    should result in the return of just one command when filtered
    by a term equal to that command.

    """

    @abstractmethod
    def __init__(self, config):
        """Setup and configuration of data storage.

        Any connections and configuration of the data store should be
        done here. It receives the full flask configuration
        dictionary.

        Args:
            config (dict): The flask application configuration
                dictionary.
        """
        self.config = config

    @abstractmethod
[docs]    def add(self, command, username, host, **kwargs):
        """Add or update a command

        Save (update or create) a command to the data store.

        Args:
            command (str): The command to store
            username (str): The username of the person adding it
            host (str): The IP address of API caller
        Returns:
            Command ID (str): The id of the command stored
        """
        pass  # pragma: no cover

    @abstractmethod
[docs]    def delete(self, command_id, username, host, **kwargs):
        """Delete a command

        Remove a command from the data store, raise a KeyError
        if it is not available to be deleted.

        Args:
            command_id (str): Unique command identifier
            username (str): The username of the person adding it
            host (str): The IP address of API caller
        """
        pass  # pragma: no cover

    @abstractmethod
[docs]    def get(self, command_id, username, host, **kwargs):
        """Get a single command

        Retrieve a single command by username and id. Raise a
        KeyError if the command does not exist.

        Args:
            command_id (str): Unique command identifier
            username (str): The username of the person adding it
            host (str): The IP address of API caller

        Returns:
            Command (dict): Dictionary with at least the keys ``id``
                            and ``command``
        """
        pass  # pragma: no cover

    @abstractmethod
[docs]    def all(self, order, username, host, **kwargs):
        """Unfiltered but ordered command history

        Return the full data set as a list of dict structures
        in the specified order.

        Args:
            order (str): An ordering from :py:const:`ORDER_TYPES`
            username (str): The username of the person adding it
            host (str): The IP address of API caller

        Returns:

            list: A list of dictionaries where each dictionary must
                have at least a ``command`` key and an ``id`` key.
        """
        pass  # pragma: no cover

    @abstractmethod
[docs]    def filter(self, term, order, username, host, **kwargs):
        """Get a filtered by term and ordered command history

        Args:
            term (str): The term being searched for/filtered by.
            order (str): An ordering from :py:const:`ORDER_TYPES`
            username (str): The username of the person adding it
            host (str): The IP address of API caller

        Returns:

            list: A list of dictionaries where each dictionary must
                have at least a ``command`` key and an ``id`` key.
        """
        pass  # pragma: no cover