Project

General

Profile

Request » History » Version 7

Elmer de Looff, 2012-04-27 18:55
Cookies cookies cookies!

1 1 Jan Klopper
h1. Request
2 1 Jan Klopper
3 5 Elmer de Looff
{{>toc}}
4 5 Elmer de Looff
5 3 Elmer de Looff
The @Request@ object is an abstraction of the incoming HTTP request. This allows one simple interface that is independent of the underlying server that µWeb runs on (either [[Standalone]] using BaseHTTPServer, or [[Apache]] mode on @mod_python@).
6 1 Jan Klopper
7 4 Elmer de Looff
From PageMaker methods, the request object is accessible as the @self.req@ member. The request object contains all the information about the incoming request: query arguments, post data, cookies and environment data. It is also the object where you define cookies that need to be provided to the client.
8 1 Jan Klopper
9 4 Elmer de Looff
h1. Query arguments
10 4 Elmer de Looff
11 4 Elmer de Looff
All query arguments provided by the client are present on the request object. They are also accessible directly on the [[PageMaker]] object. The following code demonstrates both ways to access a query argument:
12 4 Elmer de Looff
13 5 Elmer de Looff
<pre><code class="html">
14 5 Elmer de Looff
...
15 5 Elmer de Looff
<form>
16 5 Elmer de Looff
  <label for="name">Name: </label><input id="name" name="name" />
17 5 Elmer de Looff
  <input type="submit" value="Tell us your name" />
18 5 Elmer de Looff
</form>
19 5 Elmer de Looff
...
20 5 Elmer de Looff
</code></pre>
21 5 Elmer de Looff
22 1 Jan Klopper
<pre><code class="python">
23 5 Elmer de Looff
def NameFromQuery(self):
24 4 Elmer de Looff
  # Retrieves the 'name' argument from the request object:
25 4 Elmer de Looff
  name = self.req.vars['get'].getfirst('name')
26 4 Elmer de Looff
27 4 Elmer de Looff
  # Retrieves the 'name' argument directly from the PageMaker instance (linked to the request):
28 4 Elmer de Looff
  name = self.get.getfirst('name')
29 4 Elmer de Looff
  return name
30 4 Elmer de Looff
</code></pre>
31 4 Elmer de Looff
32 4 Elmer de Looff
Using the @getfirst@ method, you get a single string returned from the query argument mapping, or a @None@ if no such value exists. Much like a dictionary's @get@ method, you can provide a second argument to the method, and have that returned instead as the default. 
33 4 Elmer de Looff
34 1 Jan Klopper
Now, HTTP allows the client to provide the same query argument multiple times. Using @getfirst@ you would only get the very first defined argument. So a request that looks like @http://example.org/group?name=Bob&name=Mark&name=Jenny@ would only return 'Bob' in the previous example. To get all their names printed, you can use the following:
35 1 Jan Klopper
36 5 Elmer de Looff
<pre><code class="html">
37 5 Elmer de Looff
...
38 5 Elmer de Looff
<form action="/group">
39 5 Elmer de Looff
  <h2>Names in this group</h2>
40 5 Elmer de Looff
  <!-- These would likely be generated with Javascript, but written here for demonstrative purposes -->
41 5 Elmer de Looff
  <label for="name_1">Name: </label><input id="name_1" name="name" />
42 5 Elmer de Looff
  <label for="name_2">Name: </label><input id="name_2" name="name" />
43 5 Elmer de Looff
  <label for="name_3">Name: </label><input id="name_3" name="name" />
44 5 Elmer de Looff
  <input type="submit" value="Send these names" />
45 5 Elmer de Looff
</form>
46 5 Elmer de Looff
...
47 5 Elmer de Looff
</code></pre>
48 5 Elmer de Looff
49 1 Jan Klopper
<pre><code class="python">
50 5 Elmer de Looff
def MemberNames(self):
51 1 Jan Klopper
  names = self.get.getlist('name')
52 1 Jan Klopper
  return ', '.join(names)
53 1 Jan Klopper
</code></pre>
54 1 Jan Klopper
55 1 Jan Klopper
This returns a neat comma-separated string with all the provided names. The @getlist@ method does not take a default, but will instead return an empty list when there are no values for the requested argument name.
56 1 Jan Klopper
57 5 Elmer de Looff
h1. Post data
58 1 Jan Klopper
59 5 Elmer de Looff
Submitted form data is available on the request object as well. The interface is similar to that of the query arguments, and the @FieldStorage@ class already present in the @cgi@ module. If we take our initial example form handler, but now receive the data through HTTP POST, the code would look like this:
60 1 Jan Klopper
61 5 Elmer de Looff
<pre><code class="html">
62 5 Elmer de Looff
...
63 5 Elmer de Looff
<form method="post">
64 5 Elmer de Looff
  <label for="name">Name: </label><input id="name" name="name" />
65 5 Elmer de Looff
  <input type="submit" value="Tell us your name" />
66 5 Elmer de Looff
</form>
67 5 Elmer de Looff
...
68 5 Elmer de Looff
</code></pre>
69 1 Jan Klopper
70 5 Elmer de Looff
<pre><code class="python">
71 5 Elmer de Looff
def NameFromPost(self):
72 5 Elmer de Looff
  # Retrieves the 'name' value from the request object:
73 5 Elmer de Looff
  name = self.req.vars['post'].getfirst('name')
74 1 Jan Klopper
75 5 Elmer de Looff
  # Retrieves the 'name' value directly from the PageMaker instance (linked to the request):
76 5 Elmer de Looff
  name = self.post.getfirst('name')
77 5 Elmer de Looff
  return name
78 5 Elmer de Looff
</code></pre>
79 1 Jan Klopper
80 5 Elmer de Looff
Like with the query arguments, @getfirst@ accepts a second argument that provides a default other than @None@.
81 1 Jan Klopper
82 6 Elmer de Looff
Multiple values are again possible in the FieldStorage, and these work similar to how they do in query arguments:
83 1 Jan Klopper
84 6 Elmer de Looff
<pre><code class="html">
85 6 Elmer de Looff
...
86 6 Elmer de Looff
<form action="/group" method="post">
87 6 Elmer de Looff
  <h2>Names in this group</h2>
88 6 Elmer de Looff
  <!-- These would likely be generated with Javascript, but written here for demonstrative purposes -->
89 6 Elmer de Looff
  <label for="name_1">Name: </label><input id="name_1" name="name" />
90 6 Elmer de Looff
  <label for="name_2">Name: </label><input id="name_2" name="name" />
91 6 Elmer de Looff
  <label for="name_3">Name: </label><input id="name_3" name="name" />
92 6 Elmer de Looff
  <input type="submit" value="Send these names" />
93 6 Elmer de Looff
</form>
94 6 Elmer de Looff
...
95 6 Elmer de Looff
</code></pre>
96 6 Elmer de Looff
97 6 Elmer de Looff
<pre><code class="python">
98 6 Elmer de Looff
def MemberNames(self):
99 6 Elmer de Looff
  names = self.post.getlist('name')
100 6 Elmer de Looff
  return ', '.join(names)
101 6 Elmer de Looff
</code></pre>
102 6 Elmer de Looff
103 5 Elmer de Looff
h2. Uploading files
104 1 Jan Klopper
105 6 Elmer de Looff
Processing an uploaded file is done using the the same @FieldStorage@ system as the rest of the POST data, and roughly looks like the following. When performing file uploads, be sure to define the @enctype@ of your form, or the uploaded file will have no contents.
106 6 Elmer de Looff
107 6 Elmer de Looff
<pre><code class="html">
108 6 Elmer de Looff
...
109 6 Elmer de Looff
<form method="post" enctype="multipart/form-data">
110 6 Elmer de Looff
  <label for="avatar">Avatar: </label><input id="avatar" name="avatar" type="file" />
111 6 Elmer de Looff
  <input type="submit" value="submit!" />
112 6 Elmer de Looff
</form>
113 6 Elmer de Looff
...
114 6 Elmer de Looff
</code></pre>
115 6 Elmer de Looff
116 6 Elmer de Looff
<pre><code class="python">
117 6 Elmer de Looff
def UpdateAvatar(self):
118 6 Elmer de Looff
  # Retrieve the currently logged-in user
119 6 Elmer de Looff
  user = self.GetCurrentUser()
120 6 Elmer de Looff
121 6 Elmer de Looff
  # This gets the name of the file that was uploaded
122 6 Elmer de Looff
  avatar_name = self.post['avatar'].filename
123 6 Elmer de Looff
124 6 Elmer de Looff
  # This retrieves the content of the uploaded file, 
125 6 Elmer de Looff
  avatar_data = self.post['avatar'].value
126 6 Elmer de Looff
127 6 Elmer de Looff
  self.SaveAvatar(user, avatar_data)
128 6 Elmer de Looff
  return 'Your avatar has been replaced by %r' % avatar_name
129 6 Elmer de Looff
</code></pre>
130 6 Elmer de Looff
131 1 Jan Klopper
h2. Structured data using POST
132 6 Elmer de Looff
133 6 Elmer de Looff
One of the things that has been extended on the basic @FieldStorage@ in µWeb is the way it treats square backets ( [ and ] ) in POST data. A form field with the name @person[name]@ will result in a dictionary @person@ being created in the resulting @FieldStorage@:
134 6 Elmer de Looff
135 6 Elmer de Looff
<pre><code class="html">
136 6 Elmer de Looff
...
137 6 Elmer de Looff
<form method="post">
138 6 Elmer de Looff
  <label for="name">Name: </label><input id="name" name="person[name]" />
139 6 Elmer de Looff
  <label for="age">Age: </label><input id="age" name="person[age]" />
140 6 Elmer de Looff
  <label for="job">Job: </label><input id="job" name="person[job]" />
141 6 Elmer de Looff
  <input type="submit" value="Update your profile" />
142 6 Elmer de Looff
</form>
143 6 Elmer de Looff
...
144 6 Elmer de Looff
</code></pre>
145 6 Elmer de Looff
146 6 Elmer de Looff
<pre><code class="python">
147 6 Elmer de Looff
def PersonalData(self):
148 6 Elmer de Looff
  person = self.post.getfirst('person')
149 6 Elmer de Looff
  return uweb.Response(json.dumps(person), content_type="application/json")
150 6 Elmer de Looff
</code></pre>
151 6 Elmer de Looff
152 6 Elmer de Looff
In the above code here, the @person@ variable is a dictionary retrieved from the POST data, which is then presented to the client in JSON, by using a custom [[Response|repsonse]].
153 6 Elmer de Looff
154 6 Elmer de Looff
Note that the 'numeric' age value is a string. This is of course because everything submitted in forms is in the form of a string. Conversion to appropriate types will have to be handled by the [[PageMaker]]. The @person@ dictionary itself looks like this:
155 6 Elmer de Looff
<pre><code class="python">
156 6 Elmer de Looff
{'age': '28', 'job': 'Engineer', 'name': 'Elmer'}
157 6 Elmer de Looff
</code></pre>
158 6 Elmer de Looff
159 6 Elmer de Looff
*N.B.:* When using structured form data, you still need to use the @getfirst@ method, because there might me separate (non-dictionary) values for the form name. There will never be more than one dictionary in the form values; if a single key is set more than once, the last-set value will be the one present in the dictionary.
160 5 Elmer de Looff
161 5 Elmer de Looff
h1. Cookies
162 5 Elmer de Looff
163 7 Elmer de Looff
h2. Reading cookies
164 1 Jan Klopper
165 7 Elmer de Looff
Cookies provided by the client will also end up in the request object. They are both present on the request itself, as @self.req.vars['cookies']@, or through the @PageMaker@ instance itself as @self.cookies@ (both are from the scope of the PageMaker instance).
166 7 Elmer de Looff
167 7 Elmer de Looff
The cookie storage itself is a plain Python dictionary, which makes for particularly easy access. 
168 7 Elmer de Looff
169 7 Elmer de Looff
<pre><code class="python">
170 7 Elmer de Looff
def CookieInfo(self):
171 7 Elmer de Looff
  sample = self.cookies['sample']
172 7 Elmer de Looff
  return 'The sample cookie is set to %r' % sample
173 7 Elmer de Looff
</code></pre>
174 7 Elmer de Looff
175 7 Elmer de Looff
Cookies cannot be set by using this dictionary though, for that the @AddCookie@ method is required:
176 7 Elmer de Looff
177 7 Elmer de Looff
h2. Setting cookies
178 7 Elmer de Looff
179 7 Elmer de Looff
Response cookies are set using the request object. The method to use for this is @AddCookie@, the easiest use of which looks like this:
180 7 Elmer de Looff
181 7 Elmer de Looff
<pre><code class="python">
182 7 Elmer de Looff
def SetCookie(self):
183 7 Elmer de Looff
  self.req.AddCookie('example', 'this is an example cookie value set by µWeb')
184 7 Elmer de Looff
  return 'A cookie named "example" was set.'
185 7 Elmer de Looff
</code></pre>
186 7 Elmer de Looff
187 7 Elmer de Looff
This creates a cookie that does not expire, will be provided with every request to the originating domain, and can be read from Javascript. To change these default behaviors, there are a number of optional arguments that can be provided, as detailed below. Of course, while the examples show one argument used at a time, they can all be combined:
188 7 Elmer de Looff
189 7 Elmer de Looff
<pre><code class="python">
190 7 Elmer de Looff
def ShortLivedCookie(self):
191 7 Elmer de Looff
  """Sets an expiry time of the cookie, in this case 10 seconds."""
192 7 Elmer de Looff
  self.req.AddCookie('quick', 'I will be gone soon', max_age=10)
193 7 Elmer de Looff
194 7 Elmer de Looff
195 7 Elmer de Looff
def SecureCookie(self):
196 7 Elmer de Looff
  """Sets a cookie with the 'secure' flag enabled.
197 7 Elmer de Looff
198 7 Elmer de Looff
  This means the cookie will only be provided with requests that the browser
199 7 Elmer de Looff
  considers secure. This typically means they will only be present in requests
200 7 Elmer de Looff
  that use SSL (https://).
201 7 Elmer de Looff
  """
202 7 Elmer de Looff
  self.req.AddCookie('secret', 'This server adores you', secure=True)
203 7 Elmer de Looff
204 7 Elmer de Looff
205 7 Elmer de Looff
def HttpOnlyCookie(self):
206 7 Elmer de Looff
  """Sets a cookie that is only transferred in HTTP requests.
207 7 Elmer de Looff
208 7 Elmer de Looff
  The cookie will not be readable from Javascript. This defaults to False.
209 7 Elmer de Looff
  """
210 7 Elmer de Looff
  self.req.AddCookie('secret', 'Please no Javascript', httponly=True)
211 7 Elmer de Looff
212 7 Elmer de Looff
213 7 Elmer de Looff
def PathBoundCookie(self):
214 7 Elmer de Looff
  """Sets a cookie that is is only valid for the path '/admin'.
215 7 Elmer de Looff
216 7 Elmer de Looff
  This means that the client (browser) will only provide it for requests
217 7 Elmer de Looff
  that go to '/admin' or a deeper nested path (such as '/admin/users'
218 7 Elmer de Looff
  but will not be provided for requests that go to '/blog'
219 7 Elmer de Looff
  """
220 7 Elmer de Looff
  self.req.AddCookie('user', 'bobbytables', path='/login')
221 7 Elmer de Looff
222 7 Elmer de Looff
223 7 Elmer de Looff
def DomainBoundCookie(self):
224 7 Elmer de Looff
  """Sets a cookie that is is only valid for the specified domain.
225 7 Elmer de Looff
226 7 Elmer de Looff
  By default, if a cookie is set for 'www.example.com' it will not be provided
227 7 Elmer de Looff
  for requests that go to 'example.com' itself. If we set the cookie to be valid
228 7 Elmer de Looff
  for '.domain.com', it will be valid for domain.com and all sub-domains.
229 7 Elmer de Looff
230 7 Elmer de Looff
  Explicitly specified domains MUST begin with a dot, or they will be rejected
231 7 Elmer de Looff
  as per RFC2109. Additionally, cookies set by 'x.y.example.com' MAY NOT set
232 7 Elmer de Looff
  their valid domain to be '.example.com' or they will be rejected.
233 7 Elmer de Looff
  
234 7 Elmer de Looff
  If the 'domain' is not specified, the cookie will be valid for the domain that
235 7 Elmer de Looff
  set the cookie (as per HTTP_HOST from the environment)
236 7 Elmer de Looff
  """
237 7 Elmer de Looff
  self.req.AddCookie('session', 'SMqfUYLk3vCjkWL6', domain='.example.com')
238 7 Elmer de Looff
</code></pre>
239 7 Elmer de Looff
240 1 Jan Klopper
241 5 Elmer de Looff
h1. Environment
242 1 Jan Klopper
243 1 Jan Klopper
The env variable is a dictionary containing the following items;
244 1 Jan Klopper
* CONTENT_TYPE
245 1 Jan Klopper
* CONTENT_LENGTH
246 1 Jan Klopper
* HTTP_COOKIE
247 1 Jan Klopper
* HTTP_HOST
248 1 Jan Klopper
* HTTP_REFERER
249 1 Jan Klopper
* HTTP_USER_AGENT
250 1 Jan Klopper
* PATH_INFO
251 1 Jan Klopper
* QUERY_STRING
252 1 Jan Klopper
* REMOTE_ADDR
253 1 Jan Klopper
* REQUEST_METHOD
254 1 Jan Klopper
* UWEB_MODE 'STANDALONE' / 'MOD_PYTHON'
255 1 Jan Klopper
256 5 Elmer de Looff
h2. Extended environment
257 5 Elmer de Looff
258 1 Jan Klopper
If more detail is required about the environment, you can issue a call to the self.req.ExtendedEnvironment() method, which will inject more details into the env var. This is a much slower operation than the normal env call, so that's why its tucked away in a separate method.
259 1 Jan Klopper
260 1 Jan Klopper
* AUTH_TYPE
261 1 Jan Klopper
* CONNECTION_ID
262 1 Jan Klopper
* DOCUMENT_ROOT
263 1 Jan Klopper
* RAW_REQUEST
264 1 Jan Klopper
* REMOTE_HOST
265 1 Jan Klopper
* REMOTE_USER
266 1 Jan Klopper
* SERVER_NAME
267 1 Jan Klopper
* SERVER_PORT
268 1 Jan Klopper
* SERVER_LOCAL_NAME
269 1 Jan Klopper
* SERVER_LOCAL_IP
270 2 Elmer de Looff
* SERVER_PROTOCOL
271 1 Jan Klopper
272 1 Jan Klopper
And in case of a @mod_python@ setup you will also get:
273 1 Jan Klopper
* MODPYTHON_HANDLER
274 1 Jan Klopper
* MODPYTHON_INTERPRETER
275 1 Jan Klopper
* MODPYTHON_PHASE
276 5 Elmer de Looff
277 5 Elmer de Looff
h1. Setting cookies