from zope.interface import Attribute, Interface


class IQuoteDatabase(Interface):
    """
    A quote database.
    """

    def getQuote(qid):
        """
        Retrieve a quote from the database by identifier.

        @type qid: C{unicode}
        @param qid: The ID of the desired quote

        @rtype: L{IQuote}
        """

    def getRandomQuotes(limit=None):
        """
        Retrieve random quotes from the database.

        @type limit: C{int}
        @param limit: Maximum number of quotes to retrieve

        @rtype: C{iterable} of L{IQuote}
        """


class IQuote(Interface):
    """
    A quote entry that tracks the number of votes for and against itself.
    """

    qid = Attribute("""
    Quote unique identifier.
    """)

    content = Attribute("""
    Quote content.
    """)

    added = Attribute("""
    Timestamp representing the date of creation.
    """)

    votesFor = Attribute("""
    The number of votes for this quote.
    """)

    votesAgainst = Attribute("""
    The number of votes against this quote.
    """)

    rating = Attribute("""
    Quote rating, this is equivalent to C{votesFor - votesAgainst}.
    """)

    votes = Attribute("""
    Total number of votes for this quote.
    """)

    userID = Attribute("""
    User ID of the user that submitted this quote.
    """)

    status = Attribute("""
    Status of the quote.

    Can be one of the following values::

        - accepted:
          The quote was added to the database.

        - moderate:
          The quote has been flagged for moderation.

        - rejected:
          The quote has been moderated and was rejected.
    """)

    def plus():
        """
        Add a vote for this quote.
        """

    def minus():
        """
        Add a vote against this quote.
        """

    def requestModeration():
        """
        Put the quote into a state of C{moderate}.
        """

    def getParticipants():
        """
        Get an iterable of participant nicknames.

        @rtype: C{iterable} of C{unicode}
        """

    def getUsername():
        """
        Get the username of the user who submitted this quote.
        """


class IQuoteAdder(Interface):
    """
    Create new L{IQuote}s.
    """

    def addQuote(content):
        """
        Add a quote to the database.

        @type content: C{unicode}
        @param content: The quote content

        @rtype: L{IQuote}
        """


class IQuoteModeration(Interface):
    """
    Quote moderation access.
    """

    def reject():
        """
        Put an L{IQuote} into a state of C{rejected}.
        """

    def accept():
        """
        Put an L{IQuote} into a state of C{accepted}.
        """

class IQuoteSearcher(Interface):
    """
    Quote searching.
    """

    def search(term, limit=None):
        """
        Search for quotes matching C{term}.

        @type term: C{unicode}

        @type limit: C{int}

        @rtype: Axiom query
        """