==================
The Request Object
==================

The request object is the core of each Colubrid application. It handles form
data as well as cookies and file uploads.


Request
=======

Since Colubrid 0.9.8, the prefered way is using `Request` object for receiving
data and a `HttpResponse` object for sending the response to the browser.

If you have used Colubrid before and have to upgrade your application, you
can use the `ResponseRequest`_ object which behaves like the original request
object used before.

Since Colubrid 0.10, the parser for `args`_ and `form`_ doesn't ignore keys
with empty values any more.


args
----

The request object provides a MultiDict containing all URL paramters.
When the user requests ``http://server.tld/?action=show&p=spam&p=eggs``, ``args``
would look like this:

    ========  ====================
    Key       Value
    ========  ====================
    `action`  ``['show']``
    `p`       ``['spam', 'eggs']``
    ========  ====================

As you can see a parameter can have more than one value. In this case you
can request the paramters like this::

    request.args['p']
    # results in "eggs"
    request.args.getlist('p')
    # results in ['spam', 'eggs']

So, if you want the first paramter from the list you can use this code::

    request.args.getlist('p')[0]


form
----

Behaves like `args`_ but contains the form data.


files
-----

Behaves like `args`_ but contains the submitted files. Each key returns
a `FileStorage` object with the following method and parameters:

  ===============  ========================================
  Attribute        Description
  ===============  ========================================
  ``name``         name of the input field
  ``filename``     the filename of the uploaded file
  ``type``         mimetype of the upload
  ``data``         string containing the data
  ``__iter__``     yields all lines
  ``read()``       returns the whole data
  ``readline()``   returns one line
  ``readlines()``  returns a list of all lines
  ===============  ========================================

Here is a small example to save the submitted data in a temporary file::

    def handle_upload(self):
        from tempfile import mktemp
        fn = mktemp()
        orig = self.request.files['myfile'].filename
        file(fn, 'w').write(self.request.files['myfile'].data)
        self.request.write('File %s uploaded to %s.' % (orig, fn))

Because of an Internet Explorer workaround, filenames like ``"hello\world"``
end up in ``"world"``.


cookies
-------

Stores the cookies the browser has sent to the webserver in a `SimpleCookie`_
instance. You can modify cookies using the `set_cookie` method of a
`ResponseRequest`_ object or an `Response Object`_.


values
------

Values is a read only dict providing both the values from `args_` and `form`_.


data
----

The same as calling ``request.read()``.


read()
------

Read data from the input stream. (buffered)


ResponseRequest
===============

The response request object is ``Request`` and ``HttpResponse`` in one object.

All you have to do is to enable it by overwriting the ``__init__`` method of
your application::

    from colubrid import BaseApplication, ResponseRequest

    class MyApplication(BaseApplication):

        def __init__(self, environ, start_response):
            super(MyApplication, self).__init__(environ, start_response)
            self.request = ResponseRequest(environ, self.charset)

        def process_request(self):
            self.request.write('Hello World!')
            return self.request

Additionally you have to return the request object in the process_request
method since every application type requires a valid response object
as return value.


Old "Magic" Parameters
======================

Since the 0.9.8 release of colubrid, you should use ``request.args`` instead of
the old PHP like variable name ``request.GET``. The old ones will work too but you
shouldn't use those.

Here the list of the old variable names and the new ones:

    ==============  ===============
    Old             New
    ==============  ===============
    ``GET``         ``args``
    ``POST``        ``form``
    ``FILES``       ``files``
    ``COOKIES``     ``cookies``
    ``REQUEST``     ``values``
    ``DATA``        ``data``
    ==============  ===============



.. _SimpleCookie: http://docs.python.org/lib/module-Cookie.html
.. _here: http://wsgiarea.pocoo.org/colubrid/examples/#dynamic-output
.. _Response Object: ../response/