from abc import ABCMeta, abstractmethod
from six import add_metaclass

class LogsIterationTimeout(Exception):
  """ Exception raised if logs iteration times out. """


@add_metaclass(ABCMeta)
class ActionLogsDataInterface(object):
  """ Interface for code to work with the logs data model. The logs data model consists
      of all access for reading and writing action logs.
  """
  @abstractmethod
  def lookup_logs(self, start_datetime, end_datetime, performer_name=None, repository_name=None,
                  namespace_name=None, filter_kinds=None, page_token=None, max_page_count=None):
    """ Looks up all logs between the start_datetime and end_datetime, filtered
        by performer (a user), repository or namespace. Note that one (and only one) of the three
        can be specified. Returns a LogEntriesPage. filter, if specified, is a set/list of the
        kinds of logs to filter.
    """

  @abstractmethod
  def get_aggregated_log_counts(self, start_datetime, end_datetime, performer_name=None,
                                repository_name=None, namespace_name=None, filter_kinds=None):
    """ Returns the aggregated count of logs, by kind, between the start_datetime and end_datetime,
        filtered by performer (a user), repository or namespace. Note that one (and only one) of
        the three can be specified. Returns a list of AggregatedLogCount.
    """

  @abstractmethod
  def count_repository_actions(self, repository, day):
    """ Returns the total number of repository actions over the given day, in the given repository
        or None on error.
    """

  @abstractmethod
  def queue_logs_export(self, start_datetime, end_datetime, export_action_logs_queue,
                        namespace_name=None, repository_name=None, callback_url=None,
                        callback_email=None, filter_kinds=None):
    """ Queues logs between the start_datetime and end_time, filtered by a repository or namespace,
        for export to the specified URL and/or email address. Returns the ID of the export job
        queued or None if error.
    """

  @abstractmethod
  def log_action(self, kind_name, namespace_name=None, performer=None, ip=None, metadata=None,
                 repository=None, repository_name=None, timestamp=None):
    """ Logs a single action as having taken place. """

  @abstractmethod
  def yield_logs_for_export(self, start_datetime, end_datetime, repository_id=None,
                            namespace_id=None, max_query_time=None):
    """ Returns an iterator that yields bundles of all logs found between the start_datetime and
        end_datetime, optionally filtered by the repository or namespace. This function should be
        used for any bulk lookup operations, and should be implemented by implementors to put
        minimal strain on the backing storage for large operations. If there was an error in setting
        up, returns None.

        If max_query_time is specified, each iteration that yields a log bundle will have its
        queries run with a maximum timeout of that specified, and, if any exceed that threshold,
        LogsIterationTimeout will be raised instead of returning the logs bundle.
    """