# The Response class borrows most of its methods from Zope's
# HTTPResponse class.

class Response:
    """
    Attributes:
    status: HTTP status code to return
    headers: dictionary of response headers
    body: string containing the body of the HTTP response
    """

    def __init__(self, status=200, headers={}, body=""):
        pass

    def setStatus(self, status, reason=None):
        "Set the numeric HTTP response code"
        pass

    def setHeader(self, name, value):
        "Set an HTTP header"
        pass

    def setBody(self, body):
        "Set the body of the response"
        pass

    def setCookie(self, name, value,
                  path = '/',
                  comment = None,
                  domain = None,
                  max-age = None,
                  expires = None,
                  secure = 0
                  ):
        "Set a cookie"
        pass

    def expireCookie(self, name):
        "Remove a cookie from the user"
        pass

    def redirect(self, url):
        "Redirect the browser to another URL"
        pass

    def __str__(self):
        "Convert entire response to a string"
        pass

    def dump(self):
        "Return a string representation useful for debugging"
        pass

    # XXX methods for specific classes of error:serverError,
    # badRequest, etc.?


class Request:

    """
    Attributes:

    XXX should these be dictionaries, or dictionary-like objects?
    .headers : dictionary containing HTTP headers
    .cookies : dictionary of cookies
    .fields  : data from the form
    .env     : environment dictionary
    """

    def __init__(self, environ=os.environ, stdin=sys.stdin,
                 keep_blank_values=1, strict_parsing=0):
        """Initialize the request object, using the provided environment
        and standard input."""
        pass

    # Should people just use the dictionaries directly?
    def getHeader(self, name, default=None):
        pass

    def getCookie(self, name, default=None):
        pass

    def getField(self, name, default=None):
        "Return field's value as a string (even if it's an uploaded file)"
        pass

    def getUploadedFile(self, name):
        """Returns a file object that can be read to obtain the contents
        of an uploaded file.  XXX should this report an error if the
        field isn't actually an uploaded file?  Or should it wrap
        a StringIO around simple fields for consistency?
        """

    def getURL(self, n=0, query_string=0):
        """Return the URL of the current request, chopping off 'n' path
        components from the right.  Eg. if the URL is
        "http://foo.com/bar/baz/quux", n=2 would return
        "http://foo.com/bar".  Does not include the query string (if
        any)
        """

    def getBaseURL(self, n=0):
        """Return the base URL of the current request, adding 'n' path
        components to the end to recreate more of the whole URL.

        Eg. if the request URL is
        "http://foo.com/q/bar/baz/qux", n=0 would return
        "http://foo.com/", and n=2 "http://foo.com/q/bar".

        Returned URL does not include the query string, if any.
        """

    def dump(self):
        "String representation suitable for debugging output"
        pass

    # Possibilities?  I don't know if these are worth doing in the
    # basic objects.
    def getBrowser(self):
        "Returns Mozilla/IE/Lynx/Opera/whatever"

    def isSecure(self):
        "Return true if this is an SSLified request"


# Module-level function
def wrapper(func, logfile=sys.stderr):
    """
    Calls the function 'func', passing it the arguments
    (request, response, logfile).  Exceptions are trapped and
    sent to the file 'logfile'.
    """
    # This wrapper will detect if it's being called from the command-line,
    # and if so, it will run in a debugging mode; name=value pairs
    # can be entered on standard input to set field values.
    # (XXX how to do file uploads in this syntax?)