Cookies

The term "cookie" is a technical term describing information which is set in a response sent to a user and which is then provided every time the user accesses the application. In effect, the application asks the user to remember something on its behalf and to remind the application of that thing over and over again.

Potential Uses

Although there are some restrictions on how much information can be stored in a cookie and the type of that information (it must be a plain Python string), the mechanism is useful for identifying users or remembering simple things about the operations that the user has been performing. Some uses include:

WebStack API - Using Cookies

The transaction object provides the following methods for setting cookie information and accessing it on later occasions:

set_cookie_value
This method stores a piece of information associated with a given name and having a given plain Python string value as a cookie. Other information can also be specified which controls the way the cookie is used, notably the path (to which applications the cookie is sent) and expiry time (a UNIX time style number which states when the cookie should stop being exchanged).
set_cookie
This method stores an existing cookie object as a cookie in future communications with the user concerned. The form of such objects is described below.
get_cookies
This method returns a dictionary mapping names to cookie objects.
get_cookie
This method returns a specific cookie object for a given name.
delete_cookie
This method deletes a cookie, ensuring that the information within it is not exchanged in future.

Cookie objects can be any objects having the following properties:

name
This is the name associated with the cookie. It must be a plain Python string.
value
This is the information stored in the cookie. It must be a plain Python string.

How and When to Get and Set Cookies

Cookies which were set in previous interactions are always available straight away unless they were deleted at some earlier point in time. Typically, your application will have reserved a cookie name and will then access the cookie using that name; for example:

        # In the respond method...
my_cookie = trans.get_cookie("my_cookie") # this gets a cookie object
my_information = my_cookie.value # trans.get_cookie_value would get this value directly

It is possible to modify the cookie object, but on its own this has no effect on the value exchanged between the application and the user. To update the cookie in that way, you must also use the set_cookie method, or instead use the set_cookie_value method:

        # In the respond method after getting the cookie...
my_cookie.value = "Something else!" # this must be a plain string
trans.set_cookie(my_cookie) # this uses the existing object
trans.set_cookie_value("another_cookie", "More information!") # this adds a new cookie with the given name

Note that changing a cookie's value directly using set_cookie_value will not necessarily change the value found in cookie objects returned by subsequent calls to get_cookie during the handling of the same request.

To delete cookies, actual cookie objects must be provided:

        # In the respond method after getting the cookie...
trans.delete_cookie(my_cookie)

This does not necessarily remove the cookie from the dictionary returned by get_cookies or prevent get_cookie returning a cookie object for the name specified in the deleted cookie during the handling of the same request.