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.
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:
The transaction object provides the following methods for setting cookie information and accessing it on later occasions:
set_cookie_value
set_cookie
get_cookies
get_cookie
delete_cookie
Cookie objects can be any objects having the following properties:
name
value
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.