##############################################################################
#
# Copyright (c) 2005 Philipp "philiKON" von Weitershausen
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""WSGI interfaces

$Id$
"""
from zope.interface import Interface

class IWSGIInputStream(Interface):
    """WSGI input stream.

    See http://python.org/peps/pep-0333.html#input-and-error-streams
    """

    def read(size):
	"""Read number ``size`` number of bytes.

	The server is not required to read past the client's specified
	Content-Length, and is allowed to simulate an end-of-file
	condition if the application attempts to read past that
	point. The application should not attempt to read more data
	than is specified by the CONTENT_LENGTH variable."""

    def readline():
	"""Read one entire line. The optional ``size`` argument is not
	supported."""

    def readlines(hint):
	"""Read all lines.

	The hint argument is optional for both caller and implementer.
	The application is free not to supply it, and the server or
	gateway is free to ignore it."""

    def __iter__():
	"""Return an iterator that iterates over the lines in the input
	stream."""

class IWSGIErrorStream(Interface):
    """WSGI error stream.

    See http://python.org/peps/pep-0333.html#input-and-error-streams
    """

    def flush():
	"""Flush the internal buffer.

	Since the errors stream may not be rewound, servers and
	gateways are free to forward write operations immediately,
	without buffering. In this case, the flush() method may be a
	no-op. Portable applications, however, cannot assume that
	output is unbuffered or that flush() is a no-op. They must
	call flush() if they need to ensure that output has in fact
	been written. (For example, to minimize intermingling of data
	from multiple processes writing to the same error log.)"""

    def write(str):
	"""Write string to the stream."""

    def writelines(seq):
	"""Write sequence of lines to the stream.  This does not add line
	separators."""