# XXX This should actually be provided by zope.interface.
"""Sequence Interfaces
"""
from zope.interface import Interface

class IItemSequence(Interface):
    """Simplest readable sequence object.
    """

    def __getitem__(index):
        """Get an item at an index, or a slice of the list.

        An IndexError is raised if an out-of-range index is given.
        """


class IBasicReadSequence(IItemSequence):
    """Basic readable sequence object.
    """

    def __contains__(value):
        """Tell if a value exists in the sequence."""


class IReadSequence(IBasicReadSequence):
    """Readable sequence object.
    """

    def count(value):
        """Return the number of occurrences of a value in the sequence.
        """

    def index(value):
        """Return smallest index where a value occurs in the sequence.

        A ValueError is raised if the value is not in the sequence.
        """


class IBasicWriteSequence(Interface):
    """Basic sequence object whose items can be modified.
    """

    def __delitem__(index):
        """Delete an indexed item or a slice from the sequence.

        An IndexError is raised if an out-of-range index is given.
        """

    def __setitem__(index, value):
        """Set an indexed item or a slice of the sequence.

        An IndexError is raised if an out-of-range index is given.
        """


class IWriteSequence(IBasicWriteSequence):
    """Sequence object whose items can be modified.
    """

    def append(value):
        """Add a value to the end of the sequence.
        """

    def extend(sequence):
        """Add all items of a sequence to the end of the sequence.
        """

    def insert(index, value):
        """Insert a value into the sequence at an index.

        An item is appended to the end of the sequence if an
        out-of-range index is given.
        """

    def pop(index=-1):
        """Return an item at an index and delete it from the sequence.

        An IndexError is raised if an out-of-range index is given.
        """

    def remove(value):
        """Remove the first occurrence of a value from the sequence.

        A ValueError is raised if the value is not in the sequence.
        """

    def reverse():
        """Reverse the order of items of the sequence in-place.
        """

    def sort(cmpfunc=None):
        """Sort the items of the sequence in-place, possibly applying a
        comparison function.
        """


class IEnumerableSequence(IItemSequence):
    """Sequence object whose items can be enumerated.
    """

    def __iter__():
        """Return an iterator for the items of the sequence object.
        """

    def __len__():
        """Return the number of items.
        """


class ISequence(IReadSequence, IWriteSequence, IEnumerableSequence):
    """Full sequence interface.
    """