How to use the waitress.interfaces.Interface function in waitress

"""

    def cancel():
        """
        Called instead of service() during shutdown or if an
        exception occurs that prevents the task from being
        serviced.  Must return quickly and should not throw exceptions.
        """

    def defer():
        """
        Called just before the task is queued to be executed in
        a different thread.
        """

class IDispatcherEventHandler(Interface):
    """The Dispatcher can receive several different types of events. This
       interface describes the necessary methods that handle these common
       event types.
    """

    def handle_read_event():
        """Given a read event, a server has to handle the event and
           read the input from the client.
        """

    def handle_write_event():
        """Given a write event, a server has to handle the event and
           write the output to the client.
        """

    def handle_expt_event():

argument has the same meaning as for recv() above. Returns the number
        of bytes sent. Applications are responsible for checking that all data
        has been sent; if only some of the data was transmitted, the
        application needs to attempt delivery of the remaining data.
        """

    def close():
        """Close the socket.

        All future operations on the socket object will fail. The remote end
        will receive no more data (after queued data is flushed). Sockets are
        automatically closed when they are garbage-collected.
        """


class ITaskDispatcher(Interface):
    """An object that accepts tasks and dispatches them to threads.
    """

    def set_thread_count(count):
        """Sets the number of handler threads.
        """

    def add_task(task):
        """Receives a task and dispatches it to a thread.

        Note that, depending on load, a task may have to wait a
        while for its turn.
        """

    def shutdown(cancel_pending=True, timeout=5):
        """Shuts down all handler threads and may cancel pending tasks.

class IStreamConsumer(Interface):
    """Consumes a data stream until reaching a completion point.

    The actual amount to be consumed might not be known ahead of time.
    """

    def received(data):
        """Accepts data, returning the number of bytes consumed."""

    completed = Attribute(
        'completed', 'Set to a true value when finished consuming data.')


class IServer(Interface):
    """This interface describes the basic base server.

       The most unusual part about the Zope servers (since they all
       implement this interface or inherit its base class) is that it
       uses a mix of asynchronous and thread-based mechanism to
       serve. While the low-level socket listener uses async, the
       actual request is executed in a thread.  This is important
       because even if a request takes a long time to process, the
       server can service other requests simultaneously.
    """

    channel_class = Attribute("""
                        The channel class defines the type of channel
                        to be used by the server. See IServerChannel
                        for more information.
                              """)

"""

    def handle_connect():
        """A client requests a connection, now we need to do soemthing.
        """

    def handle_accept():
        """A connection is accepted.
        """

    def handle_close():
        """A connection is being closed.
        """


class IStreamConsumer(Interface):
    """Consumes a data stream until reaching a completion point.

    The actual amount to be consumed might not be known ahead of time.
    """

    def received(data):
        """Accepts data, returning the number of bytes consumed."""

    completed = Attribute(
        'completed', 'Set to a true value when finished consuming data.')


class IServer(Interface):
    """This interface describes the basic base server.

       The most unusual part about the Zope servers (since they all

# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Server interfaces.
"""

class Attribute(object):
    def __init__(self, title, description=None):
        self.title = title
        self.description = description

class Interface(object):
    pass

class ISocket(Interface):
    """Represents a socket.

    Note: Most of this documentation is taken from the Python Library
    Reference.
    """

    def listen(backlog):
        """Listen for connections made to the socket.

        The 'backlog' argument specifies the maximum number of queued
        connections and should be at least 1; the maximum value is
        system-dependent (usually 5).
        """

    def bind(addr):
        """Bind the socket to address.

because even if a request takes a long time to process, the
       server can service other requests simultaneously.
    """

    channel_class = Attribute("""
                        The channel class defines the type of channel
                        to be used by the server. See IServerChannel
                        for more information.
                              """)

    def getsockname():
        """ Return the IP-address, port number pair to which this server's
        socket is bound"""


class IDispatcherLogging(Interface):
    """This interface provides methods through which the Dispatcher will
       write its logs. A distinction is made between hit and message logging,
       since they often go to different output types and can have very
       different structure.
    """

    def log (message):
        """Logs general requests made to the server.
        """

    def log_info(message, type='info'):
        """Logs informational messages, warnings and errors.
        """


class IServerChannel(Interface):

def set_thread_count(count):
        """Sets the number of handler threads.
        """

    def add_task(task):
        """Receives a task and dispatches it to a thread.

        Note that, depending on load, a task may have to wait a
        while for its turn.
        """

    def shutdown(cancel_pending=True, timeout=5):
        """Shuts down all handler threads and may cancel pending tasks.
        """

class ITask(Interface):
    """
    The interface expected of an object placed in the queue of
    a ThreadedTaskDispatcher.  Provides facilities for executing
    or canceling the task.
    """

    def service():
        """
        Services the task.  Either service() or cancel() is called
        for every task queued.
        """

    def cancel():
        """
        Called instead of service() during shutdown or if an
        exception occurs that prevents the task from being

"""Each time through the select() loop, the set of sockets is
           scanned, and this method is called to see if there is any
           interest in reading. The default method simply returns 1,
           indicating that by default, all channels will be
           interested.
        """

    def writable():
        """Each time through the select() loop, the set of sockets is
           scanned, and this method is called to see if there is any
           interest in writing. The default method simply returns 1,
           indicating that by default, all channels will be
           interested.
        """

class IHeaderOutput(Interface):
    """Interface for setting HTTP response headers.

    This allows the HTTP server and the application to both set response
    headers.
    """

    def setResponseStatus(status, reason):
        """Sets the status code and the accompanying message.
        """

    def appendResponseHeaders(lst):
        """Sets headers that can potentially repeat.

        Takes a list of strings.
        """

"""This interface provides methods through which the Dispatcher will
       write its logs. A distinction is made between hit and message logging,
       since they often go to different output types and can have very
       different structure.
    """

    def log (message):
        """Logs general requests made to the server.
        """

    def log_info(message, type='info'):
        """Logs informational messages, warnings and errors.
        """


class IServerChannel(Interface):

    parser_class = Attribute("""Subclasses must provide a parser class""")
    task_class = Attribute("""Specifies the ITask class to be used for
                           generating tasks.""")

    def queue_task(task):
        """Queues a channel-related task to be processed in sequence.
        """


class IDispatcher(ISocket, IDispatcherEventHandler, IDispatcherLogging):
    """The dispatcher is the most low-level component of a server.

       1. It manages the socket connections and distributes the
          request to the appropriate channel.