blob: e4cb217a05ae10859a83612927b1283c2d79e921 [file] [log] [blame]
Guido van Rossum152f9d91997-02-18 16:55:33 +00001#! /usr/local/bin/python
Guido van Rossum1c9daa81995-09-18 21:52:37 +00002
Guido van Rossum72755611996-03-06 07:20:06 +00003"""Support module for CGI (Common Gateway Interface) scripts.
Guido van Rossum1c9daa81995-09-18 21:52:37 +00004
Guido van Rossum7aee3841996-03-07 18:00:44 +00005This module defines a number of utilities for use by CGI scripts
6written in Python.
Guido van Rossum9a22de11995-01-12 12:29:47 +00007
8
Guido van Rossum72755611996-03-06 07:20:06 +00009Introduction
10------------
11
Guido van Rossum391b4e61996-03-06 19:11:33 +000012A CGI script is invoked by an HTTP server, usually to process user
13input submitted through an HTML <FORM> or <ISINPUT> element.
Guido van Rossum72755611996-03-06 07:20:06 +000014
Guido van Rossum391b4e61996-03-06 19:11:33 +000015Most often, CGI scripts live in the server's special cgi-bin
16directory. The HTTP server places all sorts of information about the
17request (such as the client's hostname, the requested URL, the query
18string, and lots of other goodies) in the script's shell environment,
19executes the script, and sends the script's output back to the client.
Guido van Rossum72755611996-03-06 07:20:06 +000020
Guido van Rossum391b4e61996-03-06 19:11:33 +000021The script's input is connected to the client too, and sometimes the
22form data is read this way; at other times the form data is passed via
23the "query string" part of the URL. This module (cgi.py) is intended
24to take care of the different cases and provide a simpler interface to
25the Python script. It also provides a number of utilities that help
26in debugging scripts, and the latest addition is support for file
27uploads from a form (if your browser supports it -- Grail 0.3 and
28Netscape 2.0 do).
Guido van Rossum72755611996-03-06 07:20:06 +000029
Guido van Rossum391b4e61996-03-06 19:11:33 +000030The output of a CGI script should consist of two sections, separated
31by a blank line. The first section contains a number of headers,
32telling the client what kind of data is following. Python code to
33generate a minimal header section looks like this:
Guido van Rossum72755611996-03-06 07:20:06 +000034
Guido van Rossum243ddcd1996-03-07 06:33:07 +000035 print "Content-type: text/html" # HTML is following
36 print # blank line, end of headers
Guido van Rossum72755611996-03-06 07:20:06 +000037
Guido van Rossum391b4e61996-03-06 19:11:33 +000038The second section is usually HTML, which allows the client software
39to display nicely formatted text with header, in-line images, etc.
40Here's Python code that prints a simple piece of HTML:
Guido van Rossum72755611996-03-06 07:20:06 +000041
42 print "<TITLE>CGI script output</TITLE>"
43 print "<H1>This is my first CGI script</H1>"
44 print "Hello, world!"
45
Guido van Rossum43055421997-05-28 15:11:01 +000046It may not be fully legal HTML according to the letter of the
47standard, but any browser will understand it.
Guido van Rossum72755611996-03-06 07:20:06 +000048
49
50Using the cgi module
51--------------------
52
Guido van Rossum391b4e61996-03-06 19:11:33 +000053Begin by writing "import cgi". Don't use "from cgi import *" -- the
Guido van Rossum0147db01996-03-09 03:16:04 +000054module defines all sorts of names for its own use or for backward
55compatibility that you don't want in your namespace.
Guido van Rossum72755611996-03-06 07:20:06 +000056
Guido van Rossum0147db01996-03-09 03:16:04 +000057It's best to use the FieldStorage class. The other classes define in this
58module are provided mostly for backward compatibility. Instantiate it
59exactly once, without arguments. This reads the form contents from
60standard input or the environment (depending on the value of various
61environment variables set according to the CGI standard). Since it may
62consume standard input, it should be instantiated only once.
Guido van Rossum72755611996-03-06 07:20:06 +000063
Guido van Rossum0147db01996-03-09 03:16:04 +000064The FieldStorage instance can be accessed as if it were a Python
65dictionary. For instance, the following code (which assumes that the
66Content-type header and blank line have already been printed) checks that
67the fields "name" and "addr" are both set to a non-empty string:
Guido van Rossum72755611996-03-06 07:20:06 +000068
Guido van Rossum503e50b1996-05-28 22:57:20 +000069 form = cgi.FieldStorage()
Guido van Rossum72755611996-03-06 07:20:06 +000070 form_ok = 0
71 if form.has_key("name") and form.has_key("addr"):
Guido van Rossum0147db01996-03-09 03:16:04 +000072 if form["name"].value != "" and form["addr"].value != "":
Guido van Rossum72755611996-03-06 07:20:06 +000073 form_ok = 1
74 if not form_ok:
75 print "<H1>Error</H1>"
76 print "Please fill in the name and addr fields."
77 return
Guido van Rossum0147db01996-03-09 03:16:04 +000078 ...further form processing here...
Guido van Rossum72755611996-03-06 07:20:06 +000079
Guido van Rossum4032c2c1996-03-09 04:04:35 +000080Here the fields, accessed through form[key], are themselves instances
81of FieldStorage (or MiniFieldStorage, depending on the form encoding).
Guido van Rossum72755611996-03-06 07:20:06 +000082
Guido van Rossum4032c2c1996-03-09 04:04:35 +000083If the submitted form data contains more than one field with the same
84name, the object retrieved by form[key] is not a (Mini)FieldStorage
Guido van Rossum43055421997-05-28 15:11:01 +000085instance but a list of such instances. If you are expecting this
86possibility (i.e., when your HTML form comtains multiple fields with
87the same name), use the type() function to determine whether you have
88a single instance or a list of instances. For example, here's code
89that concatenates any number of username fields, separated by commas:
Guido van Rossum4032c2c1996-03-09 04:04:35 +000090
91 username = form["username"]
Guido van Rossum0147db01996-03-09 03:16:04 +000092 if type(username) is type([]):
93 # Multiple username fields specified
94 usernames = ""
95 for item in username:
96 if usernames:
97 # Next item -- insert comma
98 usernames = usernames + "," + item.value
99 else:
100 # First item -- don't insert comma
101 usernames = item.value
102 else:
103 # Single username field specified
Guido van Rossum4032c2c1996-03-09 04:04:35 +0000104 usernames = username.value
Guido van Rossum0147db01996-03-09 03:16:04 +0000105
106If a field represents an uploaded file, the value attribute reads the
107entire file in memory as a string. This may not be what you want. You can
108test for an uploaded file by testing either the filename attribute or the
109file attribute. You can then read the data at leasure from the file
110attribute:
111
112 fileitem = form["userfile"]
113 if fileitem.file:
114 # It's an uploaded file; count lines
115 linecount = 0
116 while 1:
117 line = fileitem.file.readline()
118 if not line: break
119 linecount = linecount + 1
120
Guido van Rossum4032c2c1996-03-09 04:04:35 +0000121The file upload draft standard entertains the possibility of uploading
122multiple files from one field (using a recursive multipart/*
123encoding). When this occurs, the item will be a dictionary-like
124FieldStorage item. This can be determined by testing its type
125attribute, which should have the value "multipart/form-data" (or
126perhaps another string beginning with "multipart/"). It this case, it
127can be iterated over recursively just like the top-level form object.
128
Guido van Rossum0147db01996-03-09 03:16:04 +0000129When a form is submitted in the "old" format (as the query string or as a
130single data part of type application/x-www-form-urlencoded), the items
131will actually be instances of the class MiniFieldStorage. In this case,
132the list, file and filename attributes are always None.
Guido van Rossum7aee3841996-03-07 18:00:44 +0000133
Guido van Rossum72755611996-03-06 07:20:06 +0000134
Guido van Rossum0147db01996-03-09 03:16:04 +0000135Old classes
136-----------
Guido van Rossum72755611996-03-06 07:20:06 +0000137
Guido van Rossum0147db01996-03-09 03:16:04 +0000138These classes, present in earlier versions of the cgi module, are still
Guido van Rossum16d5b111996-10-24 14:44:32 +0000139supported for backward compatibility. New applications should use the
140FieldStorage class.
Guido van Rossum7aee3841996-03-07 18:00:44 +0000141
Guido van Rossum0147db01996-03-09 03:16:04 +0000142SvFormContentDict: single value form content as dictionary; assumes each
143field name occurs in the form only once.
Guido van Rossum72755611996-03-06 07:20:06 +0000144
Guido van Rossum391b4e61996-03-06 19:11:33 +0000145FormContentDict: multiple value form content as dictionary (the form
146items are lists of values). Useful if your form contains multiple
147fields with the same name.
Guido van Rossum72755611996-03-06 07:20:06 +0000148
Guido van Rossum391b4e61996-03-06 19:11:33 +0000149Other classes (FormContent, InterpFormContentDict) are present for
Guido van Rossum0147db01996-03-09 03:16:04 +0000150backwards compatibility with really old applications only. If you still
151use these and would be inconvenienced when they disappeared from a next
152version of this module, drop me a note.
Guido van Rossum72755611996-03-06 07:20:06 +0000153
154
Guido van Rossum0147db01996-03-09 03:16:04 +0000155Functions
156---------
Guido van Rossum72755611996-03-06 07:20:06 +0000157
Guido van Rossum391b4e61996-03-06 19:11:33 +0000158These are useful if you want more control, or if you want to employ
159some of the algorithms implemented in this module in other
160circumstances.
Guido van Rossum72755611996-03-06 07:20:06 +0000161
Guido van Rossume08c04c1996-11-11 19:29:11 +0000162parse(fp, [environ, [keep_blank_values, [strict_parsing]]]): parse a
163form into a Python dictionary.
Guido van Rossum72755611996-03-06 07:20:06 +0000164
Guido van Rossume08c04c1996-11-11 19:29:11 +0000165parse_qs(qs, [keep_blank_values, [strict_parsing]]): parse a query
166string (data of type application/x-www-form-urlencoded).
Guido van Rossum72755611996-03-06 07:20:06 +0000167
Guido van Rossum0147db01996-03-09 03:16:04 +0000168parse_multipart(fp, pdict): parse input of type multipart/form-data (for
Guido van Rossum391b4e61996-03-06 19:11:33 +0000169file uploads).
Guido van Rossum72755611996-03-06 07:20:06 +0000170
Guido van Rossum391b4e61996-03-06 19:11:33 +0000171parse_header(string): parse a header like Content-type into a main
172value and a dictionary of parameters.
Guido van Rossum72755611996-03-06 07:20:06 +0000173
174test(): complete test program.
175
176print_environ(): format the shell environment in HTML.
177
178print_form(form): format a form in HTML.
179
Guido van Rossum391b4e61996-03-06 19:11:33 +0000180print_environ_usage(): print a list of useful environment variables in
181HTML.
Guido van Rossum72755611996-03-06 07:20:06 +0000182
Guido van Rossum391b4e61996-03-06 19:11:33 +0000183escape(): convert the characters "&", "<" and ">" to HTML-safe
184sequences. Use this if you need to display text that might contain
185such characters in HTML. To translate URLs for inclusion in the HREF
186attribute of an <A> tag, use urllib.quote().
Guido van Rossum72755611996-03-06 07:20:06 +0000187
Guido van Rossumc204c701996-09-05 19:07:11 +0000188log(fmt, ...): write a line to a log file; see docs for initlog().
189
Guido van Rossum72755611996-03-06 07:20:06 +0000190
191Caring about security
192---------------------
193
Guido van Rossum391b4e61996-03-06 19:11:33 +0000194There's one important rule: if you invoke an external program (e.g.
195via the os.system() or os.popen() functions), make very sure you don't
196pass arbitrary strings received from the client to the shell. This is
197a well-known security hole whereby clever hackers anywhere on the web
198can exploit a gullible CGI script to invoke arbitrary shell commands.
199Even parts of the URL or field names cannot be trusted, since the
200request doesn't have to come from your form!
Guido van Rossum72755611996-03-06 07:20:06 +0000201
Guido van Rossum391b4e61996-03-06 19:11:33 +0000202To be on the safe side, if you must pass a string gotten from a form
203to a shell command, you should make sure the string contains only
204alphanumeric characters, dashes, underscores, and periods.
Guido van Rossum72755611996-03-06 07:20:06 +0000205
206
207Installing your CGI script on a Unix system
208-------------------------------------------
209
Guido van Rossum391b4e61996-03-06 19:11:33 +0000210Read the documentation for your HTTP server and check with your local
211system administrator to find the directory where CGI scripts should be
Guido van Rossum72755611996-03-06 07:20:06 +0000212installed; usually this is in a directory cgi-bin in the server tree.
213
Guido van Rossum391b4e61996-03-06 19:11:33 +0000214Make sure that your script is readable and executable by "others"; the
215Unix file mode should be 755 (use "chmod 755 filename"). Make sure
Guido van Rossum43055421997-05-28 15:11:01 +0000216that the first line of the script contains #! starting in column 1
Guido van Rossum391b4e61996-03-06 19:11:33 +0000217followed by the pathname of the Python interpreter, for instance:
Guido van Rossum72755611996-03-06 07:20:06 +0000218
Guido van Rossumf06ee5f1996-11-27 19:52:01 +0000219 #! /usr/local/bin/python
Guido van Rossum72755611996-03-06 07:20:06 +0000220
Guido van Rossum391b4e61996-03-06 19:11:33 +0000221Make sure the Python interpreter exists and is executable by "others".
Guido van Rossum72755611996-03-06 07:20:06 +0000222
Guido van Rossum43055421997-05-28 15:11:01 +0000223Note that it's probably not a good idea to use #! /usr/bin/env python
Guido van Rossumf06ee5f1996-11-27 19:52:01 +0000224here, since the Python interpreter may not be on the default path
Guido van Rossum43055421997-05-28 15:11:01 +0000225given to CGI scripts!!!
Guido van Rossumf06ee5f1996-11-27 19:52:01 +0000226
Guido van Rossum391b4e61996-03-06 19:11:33 +0000227Make sure that any files your script needs to read or write are
228readable or writable, respectively, by "others" -- their mode should
229be 644 for readable and 666 for writable. This is because, for
230security reasons, the HTTP server executes your script as user
231"nobody", without any special privileges. It can only read (write,
232execute) files that everybody can read (write, execute). The current
233directory at execution time is also different (it is usually the
234server's cgi-bin directory) and the set of environment variables is
235also different from what you get at login. in particular, don't count
236on the shell's search path for executables ($PATH) or the Python
237module search path ($PYTHONPATH) to be set to anything interesting.
Guido van Rossum72755611996-03-06 07:20:06 +0000238
Guido van Rossum391b4e61996-03-06 19:11:33 +0000239If you need to load modules from a directory which is not on Python's
240default module search path, you can change the path in your script,
241before importing other modules, e.g.:
Guido van Rossum72755611996-03-06 07:20:06 +0000242
243 import sys
244 sys.path.insert(0, "/usr/home/joe/lib/python")
245 sys.path.insert(0, "/usr/local/lib/python")
246
Guido van Rossum43055421997-05-28 15:11:01 +0000247This way, the directory inserted last will be searched first!
Guido van Rossum72755611996-03-06 07:20:06 +0000248
Guido van Rossum391b4e61996-03-06 19:11:33 +0000249Instructions for non-Unix systems will vary; check your HTTP server's
Guido van Rossum72755611996-03-06 07:20:06 +0000250documentation (it will usually have a section on CGI scripts).
251
252
253Testing your CGI script
254-----------------------
255
Guido van Rossum391b4e61996-03-06 19:11:33 +0000256Unfortunately, a CGI script will generally not run when you try it
257from the command line, and a script that works perfectly from the
258command line may fail mysteriously when run from the server. There's
259one reason why you should still test your script from the command
260line: if it contains a syntax error, the python interpreter won't
261execute it at all, and the HTTP server will most likely send a cryptic
262error to the client.
Guido van Rossum72755611996-03-06 07:20:06 +0000263
Guido van Rossum391b4e61996-03-06 19:11:33 +0000264Assuming your script has no syntax errors, yet it does not work, you
265have no choice but to read the next section:
Guido van Rossum72755611996-03-06 07:20:06 +0000266
267
268Debugging CGI scripts
269---------------------
270
Guido van Rossum391b4e61996-03-06 19:11:33 +0000271First of all, check for trivial installation errors -- reading the
272section above on installing your CGI script carefully can save you a
273lot of time. If you wonder whether you have understood the
274installation procedure correctly, try installing a copy of this module
275file (cgi.py) as a CGI script. When invoked as a script, the file
276will dump its environment and the contents of the form in HTML form.
277Give it the right mode etc, and send it a request. If it's installed
278in the standard cgi-bin directory, it should be possible to send it a
279request by entering a URL into your browser of the form:
Guido van Rossum72755611996-03-06 07:20:06 +0000280
281 http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
282
Guido van Rossum391b4e61996-03-06 19:11:33 +0000283If this gives an error of type 404, the server cannot find the script
284-- perhaps you need to install it in a different directory. If it
285gives another error (e.g. 500), there's an installation problem that
286you should fix before trying to go any further. If you get a nicely
287formatted listing of the environment and form content (in this
288example, the fields should be listed as "addr" with value "At Home"
289and "name" with value "Joe Blow"), the cgi.py script has been
290installed correctly. If you follow the same procedure for your own
291script, you should now be able to debug it.
Guido van Rossum72755611996-03-06 07:20:06 +0000292
Guido van Rossum391b4e61996-03-06 19:11:33 +0000293The next step could be to call the cgi module's test() function from
294your script: replace its main code with the single statement
Guido van Rossum72755611996-03-06 07:20:06 +0000295
296 cgi.test()
297
Guido van Rossum391b4e61996-03-06 19:11:33 +0000298This should produce the same results as those gotten from installing
299the cgi.py file itself.
Guido van Rossum72755611996-03-06 07:20:06 +0000300
Guido van Rossum43055421997-05-28 15:11:01 +0000301When an ordinary Python script raises an unhandled exception (e.g.,
302because of a typo in a module name, a file that can't be opened,
Guido van Rossum391b4e61996-03-06 19:11:33 +0000303etc.), the Python interpreter prints a nice traceback and exits.
304While the Python interpreter will still do this when your CGI script
305raises an exception, most likely the traceback will end up in one of
306the HTTP server's log file, or be discarded altogether.
Guido van Rossum72755611996-03-06 07:20:06 +0000307
Guido van Rossum391b4e61996-03-06 19:11:33 +0000308Fortunately, once you have managed to get your script to execute
309*some* code, it is easy to catch exceptions and cause a traceback to
310be printed. The test() function below in this module is an example.
311Here are the rules:
Guido van Rossum72755611996-03-06 07:20:06 +0000312
Guido van Rossum391b4e61996-03-06 19:11:33 +0000313 1. Import the traceback module (before entering the
314 try-except!)
Guido van Rossum72755611996-03-06 07:20:06 +0000315
Guido van Rossum391b4e61996-03-06 19:11:33 +0000316 2. Make sure you finish printing the headers and the blank
317 line early
Guido van Rossum72755611996-03-06 07:20:06 +0000318
319 3. Assign sys.stderr to sys.stdout
320
321 3. Wrap all remaining code in a try-except statement
322
323 4. In the except clause, call traceback.print_exc()
324
325For example:
326
327 import sys
328 import traceback
329 print "Content-type: text/html"
330 print
331 sys.stderr = sys.stdout
332 try:
333 ...your code here...
334 except:
335 print "\n\n<PRE>"
336 traceback.print_exc()
337
Guido van Rossum391b4e61996-03-06 19:11:33 +0000338Notes: The assignment to sys.stderr is needed because the traceback
339prints to sys.stderr. The print "\n\n<PRE>" statement is necessary to
340disable the word wrapping in HTML.
Guido van Rossum72755611996-03-06 07:20:06 +0000341
Guido van Rossum391b4e61996-03-06 19:11:33 +0000342If you suspect that there may be a problem in importing the traceback
343module, you can use an even more robust approach (which only uses
344built-in modules):
Guido van Rossum72755611996-03-06 07:20:06 +0000345
346 import sys
347 sys.stderr = sys.stdout
348 print "Content-type: text/plain"
349 print
350 ...your code here...
351
Guido van Rossum391b4e61996-03-06 19:11:33 +0000352This relies on the Python interpreter to print the traceback. The
353content type of the output is set to plain text, which disables all
354HTML processing. If your script works, the raw HTML will be displayed
355by your client. If it raises an exception, most likely after the
356first two lines have been printed, a traceback will be displayed.
357Because no HTML interpretation is going on, the traceback will
358readable.
Guido van Rossum72755611996-03-06 07:20:06 +0000359
Guido van Rossumc204c701996-09-05 19:07:11 +0000360When all else fails, you may want to insert calls to log() to your
361program or even to a copy of the cgi.py file. Note that this requires
362you to set cgi.logfile to the name of a world-writable file before the
363first call to log() is made!
364
Guido van Rossum72755611996-03-06 07:20:06 +0000365Good luck!
366
367
368Common problems and solutions
369-----------------------------
370
Guido van Rossum391b4e61996-03-06 19:11:33 +0000371- Most HTTP servers buffer the output from CGI scripts until the
372script is completed. This means that it is not possible to display a
373progress report on the client's display while the script is running.
Guido van Rossum72755611996-03-06 07:20:06 +0000374
375- Check the installation instructions above.
376
Guido van Rossum391b4e61996-03-06 19:11:33 +0000377- Check the HTTP server's log files. ("tail -f logfile" in a separate
Guido van Rossum72755611996-03-06 07:20:06 +0000378window may be useful!)
379
Guido van Rossum391b4e61996-03-06 19:11:33 +0000380- Always check a script for syntax errors first, by doing something
381like "python script.py".
Guido van Rossum72755611996-03-06 07:20:06 +0000382
383- When using any of the debugging techniques, don't forget to add
384"import sys" to the top of the script.
385
Guido van Rossum391b4e61996-03-06 19:11:33 +0000386- When invoking external programs, make sure they can be found.
387Usually, this means using absolute path names -- $PATH is usually not
388set to a very useful value in a CGI script.
Guido van Rossum72755611996-03-06 07:20:06 +0000389
Guido van Rossum391b4e61996-03-06 19:11:33 +0000390- When reading or writing external files, make sure they can be read
391or written by every user on the system.
Guido van Rossum72755611996-03-06 07:20:06 +0000392
Guido van Rossum391b4e61996-03-06 19:11:33 +0000393- Don't try to give a CGI script a set-uid mode. This doesn't work on
394most systems, and is a security liability as well.
Guido van Rossum72755611996-03-06 07:20:06 +0000395
396
397History
398-------
399
Guido van Rossum391b4e61996-03-06 19:11:33 +0000400Michael McLay started this module. Steve Majewski changed the
401interface to SvFormContentDict and FormContentDict. The multipart
402parsing was inspired by code submitted by Andreas Paepcke. Guido van
403Rossum rewrote, reformatted and documented the module and is currently
404responsible for its maintenance.
Guido van Rossum72755611996-03-06 07:20:06 +0000405
Guido van Rossum0147db01996-03-09 03:16:04 +0000406
407XXX The module is getting pretty heavy with all those docstrings.
408Perhaps there should be a slimmed version that doesn't contain all those
409backwards compatible and debugging classes and functions?
410
Guido van Rossum72755611996-03-06 07:20:06 +0000411"""
412
Guido van Rossum5f322481997-04-11 18:20:42 +0000413__version__ = "2.2"
Guido van Rossum0147db01996-03-09 03:16:04 +0000414
Guido van Rossum72755611996-03-06 07:20:06 +0000415
416# Imports
417# =======
418
419import string
Guido van Rossum72755611996-03-06 07:20:06 +0000420import sys
421import os
Guido van Rossuma5e9fb61997-08-12 18:18:13 +0000422import urllib
Guido van Rossuma5e9fb61997-08-12 18:18:13 +0000423import mimetools
424import rfc822
425from StringIO import StringIO
Guido van Rossum72755611996-03-06 07:20:06 +0000426
Guido van Rossumc204c701996-09-05 19:07:11 +0000427
428# Logging support
429# ===============
430
431logfile = "" # Filename to log to, if not empty
432logfp = None # File object to log to, if not None
433
434def initlog(*allargs):
435 """Write a log message, if there is a log file.
436
437 Even though this function is called initlog(), you should always
438 use log(); log is a variable that is set either to initlog
439 (initially), to dolog (once the log file has been opened), or to
440 nolog (when logging is disabled).
441
442 The first argument is a format string; the remaining arguments (if
443 any) are arguments to the % operator, so e.g.
444 log("%s: %s", "a", "b")
445 will write "a: b" to the log file, followed by a newline.
446
447 If the global logfp is not None, it should be a file object to
448 which log data is written.
449
450 If the global logfp is None, the global logfile may be a string
451 giving a filename to open, in append mode. This file should be
452 world writable!!! If the file can't be opened, logging is
453 silently disabled (since there is no safe place where we could
454 send an error message).
455
456 """
457 global logfp, log
458 if logfile and not logfp:
459 try:
460 logfp = open(logfile, "a")
461 except IOError:
462 pass
463 if not logfp:
464 log = nolog
465 else:
466 log = dolog
467 apply(log, allargs)
468
469def dolog(fmt, *args):
470 """Write a log message to the log file. See initlog() for docs."""
471 logfp.write(fmt%args + "\n")
472
473def nolog(*allargs):
474 """Dummy function, assigned to log when logging is disabled."""
475 pass
476
477log = initlog # The current logging function
478
479
Guido van Rossum72755611996-03-06 07:20:06 +0000480# Parsing functions
481# =================
482
Guido van Rossumad164711997-05-13 19:03:23 +0000483# Maximum input we will accept when REQUEST_METHOD is POST
484# 0 ==> unlimited input
485maxlen = 0
486
Guido van Rossume08c04c1996-11-11 19:29:11 +0000487def parse(fp=None, environ=os.environ, keep_blank_values=0, strict_parsing=0):
Guido van Rossum773ab271996-07-23 03:46:24 +0000488 """Parse a query in the environment or from a file (default stdin)
489
490 Arguments, all optional:
491
492 fp : file pointer; default: sys.stdin
493
494 environ : environment dictionary; default: os.environ
495
496 keep_blank_values: flag indicating whether blank values in
497 URL encoded forms should be treated as blank strings.
498 A true value inicates that blanks should be retained as
499 blank strings. The default false value indicates that
500 blank values are to be ignored and treated as if they were
501 not included.
Guido van Rossume08c04c1996-11-11 19:29:11 +0000502
503 strict_parsing: flag indicating what to do with parsing errors.
504 If false (the default), errors are silently ignored.
505 If true, errors raise a ValueError exception.
Guido van Rossum773ab271996-07-23 03:46:24 +0000506 """
Guido van Rossum7aee3841996-03-07 18:00:44 +0000507 if not fp:
508 fp = sys.stdin
509 if not environ.has_key('REQUEST_METHOD'):
510 environ['REQUEST_METHOD'] = 'GET' # For testing stand-alone
511 if environ['REQUEST_METHOD'] == 'POST':
512 ctype, pdict = parse_header(environ['CONTENT_TYPE'])
513 if ctype == 'multipart/form-data':
Guido van Rossum0147db01996-03-09 03:16:04 +0000514 return parse_multipart(fp, pdict)
Guido van Rossum7aee3841996-03-07 18:00:44 +0000515 elif ctype == 'application/x-www-form-urlencoded':
516 clength = string.atoi(environ['CONTENT_LENGTH'])
Guido van Rossumad164711997-05-13 19:03:23 +0000517 if maxlen and clength > maxlen:
518 raise ValueError, 'Maximum content length exceeded'
Guido van Rossum7aee3841996-03-07 18:00:44 +0000519 qs = fp.read(clength)
Guido van Rossum1c9daa81995-09-18 21:52:37 +0000520 else:
Guido van Rossum0147db01996-03-09 03:16:04 +0000521 qs = '' # Unknown content-type
Guido van Rossumafb5e931996-08-08 18:42:12 +0000522 if environ.has_key('QUERY_STRING'):
523 if qs: qs = qs + '&'
524 qs = qs + environ['QUERY_STRING']
525 elif sys.argv[1:]:
526 if qs: qs = qs + '&'
527 qs = qs + sys.argv[1]
Guido van Rossum7aee3841996-03-07 18:00:44 +0000528 environ['QUERY_STRING'] = qs # XXX Shouldn't, really
529 elif environ.has_key('QUERY_STRING'):
530 qs = environ['QUERY_STRING']
531 else:
532 if sys.argv[1:]:
533 qs = sys.argv[1]
534 else:
535 qs = ""
536 environ['QUERY_STRING'] = qs # XXX Shouldn't, really
Guido van Rossume08c04c1996-11-11 19:29:11 +0000537 return parse_qs(qs, keep_blank_values, strict_parsing)
Guido van Rossume7808771995-08-07 20:12:09 +0000538
539
Guido van Rossume08c04c1996-11-11 19:29:11 +0000540def parse_qs(qs, keep_blank_values=0, strict_parsing=0):
541 """Parse a query given as a string argument.
Guido van Rossum773ab271996-07-23 03:46:24 +0000542
543 Arguments:
544
Guido van Rossume08c04c1996-11-11 19:29:11 +0000545 qs: URL-encoded query string to be parsed
Guido van Rossum773ab271996-07-23 03:46:24 +0000546
547 keep_blank_values: flag indicating whether blank values in
548 URL encoded queries should be treated as blank strings.
549 A true value inicates that blanks should be retained as
550 blank strings. The default false value indicates that
551 blank values are to be ignored and treated as if they were
552 not included.
Guido van Rossume08c04c1996-11-11 19:29:11 +0000553
554 strict_parsing: flag indicating what to do with parsing errors.
555 If false (the default), errors are silently ignored.
556 If true, errors raise a ValueError exception.
Guido van Rossum773ab271996-07-23 03:46:24 +0000557 """
Guido van Rossum7aee3841996-03-07 18:00:44 +0000558 name_value_pairs = string.splitfields(qs, '&')
559 dict = {}
560 for name_value in name_value_pairs:
561 nv = string.splitfields(name_value, '=')
562 if len(nv) != 2:
Guido van Rossume08c04c1996-11-11 19:29:11 +0000563 if strict_parsing:
564 raise ValueError, "bad query field: %s" % `name_value`
Guido van Rossum7aee3841996-03-07 18:00:44 +0000565 continue
Guido van Rossum00f9fea1997-12-24 21:18:41 +0000566 name = urllib.unquote(string.replace(nv[0], '+', ' '))
567 value = urllib.unquote(string.replace(nv[1], '+', ' '))
Guido van Rossum773ab271996-07-23 03:46:24 +0000568 if len(value) or keep_blank_values:
Guido van Rossum7aee3841996-03-07 18:00:44 +0000569 if dict.has_key (name):
570 dict[name].append(value)
571 else:
572 dict[name] = [value]
573 return dict
Guido van Rossum9a22de11995-01-12 12:29:47 +0000574
575
Guido van Rossum0147db01996-03-09 03:16:04 +0000576def parse_multipart(fp, pdict):
Guido van Rossum7aee3841996-03-07 18:00:44 +0000577 """Parse multipart input.
Guido van Rossum9a22de11995-01-12 12:29:47 +0000578
Guido van Rossum7aee3841996-03-07 18:00:44 +0000579 Arguments:
580 fp : input file
Guido van Rossum7aee3841996-03-07 18:00:44 +0000581 pdict: dictionary containing other parameters of conten-type header
Guido van Rossum72755611996-03-06 07:20:06 +0000582
Guido van Rossum0147db01996-03-09 03:16:04 +0000583 Returns a dictionary just like parse_qs(): keys are the field names, each
584 value is a list of values for that field. This is easy to use but not
585 much good if you are expecting megabytes to be uploaded -- in that case,
586 use the FieldStorage class instead which is much more flexible. Note
587 that content-type is the raw, unparsed contents of the content-type
588 header.
589
590 XXX This does not parse nested multipart parts -- use FieldStorage for
591 that.
592
593 XXX This should really be subsumed by FieldStorage altogether -- no
594 point in having two implementations of the same parsing algorithm.
Guido van Rossum72755611996-03-06 07:20:06 +0000595
Guido van Rossum7aee3841996-03-07 18:00:44 +0000596 """
Guido van Rossum7aee3841996-03-07 18:00:44 +0000597 if pdict.has_key('boundary'):
598 boundary = pdict['boundary']
599 else:
600 boundary = ""
601 nextpart = "--" + boundary
602 lastpart = "--" + boundary + "--"
603 partdict = {}
604 terminator = ""
605
606 while terminator != lastpart:
607 bytes = -1
608 data = None
609 if terminator:
610 # At start of next part. Read headers first.
611 headers = mimetools.Message(fp)
612 clength = headers.getheader('content-length')
613 if clength:
614 try:
615 bytes = string.atoi(clength)
616 except string.atoi_error:
617 pass
618 if bytes > 0:
Guido van Rossumad164711997-05-13 19:03:23 +0000619 if maxlen and bytes > maxlen:
620 raise ValueError, 'Maximum content length exceeded'
Guido van Rossum7aee3841996-03-07 18:00:44 +0000621 data = fp.read(bytes)
622 else:
623 data = ""
624 # Read lines until end of part.
625 lines = []
626 while 1:
627 line = fp.readline()
628 if not line:
629 terminator = lastpart # End outer loop
630 break
631 if line[:2] == "--":
632 terminator = string.strip(line)
633 if terminator in (nextpart, lastpart):
634 break
Guido van Rossum7aee3841996-03-07 18:00:44 +0000635 lines.append(line)
636 # Done with part.
637 if data is None:
638 continue
639 if bytes < 0:
Guido van Rossum99aa2a41996-07-23 17:27:05 +0000640 if lines:
641 # Strip final line terminator
642 line = lines[-1]
643 if line[-2:] == "\r\n":
644 line = line[:-2]
645 elif line[-1:] == "\n":
646 line = line[:-1]
647 lines[-1] = line
648 data = string.joinfields(lines, "")
Guido van Rossum7aee3841996-03-07 18:00:44 +0000649 line = headers['content-disposition']
650 if not line:
651 continue
652 key, params = parse_header(line)
653 if key != 'form-data':
654 continue
655 if params.has_key('name'):
656 name = params['name']
Guido van Rossum72755611996-03-06 07:20:06 +0000657 else:
Guido van Rossum7aee3841996-03-07 18:00:44 +0000658 continue
Guido van Rossum7aee3841996-03-07 18:00:44 +0000659 if partdict.has_key(name):
660 partdict[name].append(data)
661 else:
662 partdict[name] = [data]
Guido van Rossum72755611996-03-06 07:20:06 +0000663
Guido van Rossum7aee3841996-03-07 18:00:44 +0000664 return partdict
Guido van Rossum9a22de11995-01-12 12:29:47 +0000665
666
Guido van Rossum72755611996-03-06 07:20:06 +0000667def parse_header(line):
Guido van Rossum7aee3841996-03-07 18:00:44 +0000668 """Parse a Content-type like header.
669
670 Return the main content-type and a dictionary of options.
671
672 """
673 plist = map(string.strip, string.splitfields(line, ';'))
674 key = string.lower(plist[0])
675 del plist[0]
676 pdict = {}
677 for p in plist:
678 i = string.find(p, '=')
679 if i >= 0:
680 name = string.lower(string.strip(p[:i]))
681 value = string.strip(p[i+1:])
682 if len(value) >= 2 and value[0] == value[-1] == '"':
683 value = value[1:-1]
684 pdict[name] = value
685 return key, pdict
Guido van Rossum72755611996-03-06 07:20:06 +0000686
687
Guido van Rossum243ddcd1996-03-07 06:33:07 +0000688# Classes for field storage
689# =========================
690
691class MiniFieldStorage:
692
Guido van Rossum0147db01996-03-09 03:16:04 +0000693 """Like FieldStorage, for use when no file uploads are possible."""
Guido van Rossum243ddcd1996-03-07 06:33:07 +0000694
Guido van Rossum7aee3841996-03-07 18:00:44 +0000695 # Dummy attributes
696 filename = None
697 list = None
698 type = None
Guido van Rossum773ab271996-07-23 03:46:24 +0000699 file = None
Guido van Rossum4032c2c1996-03-09 04:04:35 +0000700 type_options = {}
Guido van Rossum7aee3841996-03-07 18:00:44 +0000701 disposition = None
702 disposition_options = {}
703 headers = {}
Guido van Rossum243ddcd1996-03-07 06:33:07 +0000704
Guido van Rossum7aee3841996-03-07 18:00:44 +0000705 def __init__(self, name, value):
706 """Constructor from field name and value."""
Guido van Rossum7aee3841996-03-07 18:00:44 +0000707 self.name = name
708 self.value = value
Guido van Rossum773ab271996-07-23 03:46:24 +0000709 # self.file = StringIO(value)
Guido van Rossum7aee3841996-03-07 18:00:44 +0000710
711 def __repr__(self):
712 """Return printable representation."""
713 return "MiniFieldStorage(%s, %s)" % (`self.name`, `self.value`)
Guido van Rossum243ddcd1996-03-07 06:33:07 +0000714
715
716class FieldStorage:
717
Guido van Rossum7aee3841996-03-07 18:00:44 +0000718 """Store a sequence of fields, reading multipart/form-data.
Guido van Rossum243ddcd1996-03-07 06:33:07 +0000719
Guido van Rossum7aee3841996-03-07 18:00:44 +0000720 This class provides naming, typing, files stored on disk, and
721 more. At the top level, it is accessible like a dictionary, whose
722 keys are the field names. (Note: None can occur as a field name.)
723 The items are either a Python list (if there's multiple values) or
724 another FieldStorage or MiniFieldStorage object. If it's a single
725 object, it has the following attributes:
Guido van Rossum243ddcd1996-03-07 06:33:07 +0000726
Guido van Rossum7aee3841996-03-07 18:00:44 +0000727 name: the field name, if specified; otherwise None
Guido van Rossum243ddcd1996-03-07 06:33:07 +0000728
Guido van Rossum7aee3841996-03-07 18:00:44 +0000729 filename: the filename, if specified; otherwise None; this is the
730 client side filename, *not* the file name on which it is
Guido van Rossum0147db01996-03-09 03:16:04 +0000731 stored (that's a temporary file you don't deal with)
Guido van Rossum243ddcd1996-03-07 06:33:07 +0000732
Guido van Rossum7aee3841996-03-07 18:00:44 +0000733 value: the value as a *string*; for file uploads, this
734 transparently reads the file every time you request the value
735
736 file: the file(-like) object from which you can read the data;
737 None if the data is stored a simple string
738
739 type: the content-type, or None if not specified
740
741 type_options: dictionary of options specified on the content-type
742 line
743
744 disposition: content-disposition, or None if not specified
745
746 disposition_options: dictionary of corresponding options
747
748 headers: a dictionary(-like) object (sometimes rfc822.Message or a
749 subclass thereof) containing *all* headers
750
751 The class is subclassable, mostly for the purpose of overriding
752 the make_file() method, which is called internally to come up with
753 a file open for reading and writing. This makes it possible to
754 override the default choice of storing all files in a temporary
755 directory and unlinking them as soon as they have been opened.
756
757 """
758
Guido van Rossum773ab271996-07-23 03:46:24 +0000759 def __init__(self, fp=None, headers=None, outerboundary="",
Guido van Rossume08c04c1996-11-11 19:29:11 +0000760 environ=os.environ, keep_blank_values=0, strict_parsing=0):
Guido van Rossum7aee3841996-03-07 18:00:44 +0000761 """Constructor. Read multipart/* until last part.
762
763 Arguments, all optional:
764
765 fp : file pointer; default: sys.stdin
766
767 headers : header dictionary-like object; default:
768 taken from environ as per CGI spec
769
Guido van Rossum773ab271996-07-23 03:46:24 +0000770 outerboundary : terminating multipart boundary
Guido van Rossum7aee3841996-03-07 18:00:44 +0000771 (for internal use only)
772
Guido van Rossum773ab271996-07-23 03:46:24 +0000773 environ : environment dictionary; default: os.environ
774
775 keep_blank_values: flag indicating whether blank values in
776 URL encoded forms should be treated as blank strings.
777 A true value inicates that blanks should be retained as
778 blank strings. The default false value indicates that
779 blank values are to be ignored and treated as if they were
780 not included.
781
Guido van Rossume08c04c1996-11-11 19:29:11 +0000782 strict_parsing: flag indicating what to do with parsing errors.
783 If false (the default), errors are silently ignored.
784 If true, errors raise a ValueError exception.
785
Guido van Rossum7aee3841996-03-07 18:00:44 +0000786 """
Guido van Rossumd7c9d961997-05-28 15:39:15 +0000787 method = 'GET'
Guido van Rossum773ab271996-07-23 03:46:24 +0000788 self.keep_blank_values = keep_blank_values
Guido van Rossume08c04c1996-11-11 19:29:11 +0000789 self.strict_parsing = strict_parsing
Guido van Rossum7aee3841996-03-07 18:00:44 +0000790 if environ.has_key('REQUEST_METHOD'):
791 method = string.upper(environ['REQUEST_METHOD'])
792 if not fp and method == 'GET':
Guido van Rossum7aee3841996-03-07 18:00:44 +0000793 if environ.has_key('QUERY_STRING'):
794 qs = environ['QUERY_STRING']
Guido van Rossumd7c9d961997-05-28 15:39:15 +0000795 elif sys.argv[1:]:
796 qs = sys.argv[1]
797 else:
798 qs = ""
Guido van Rossumd7c9d961997-05-28 15:39:15 +0000799 fp = StringIO(qs)
Guido van Rossum7aee3841996-03-07 18:00:44 +0000800 if headers is None:
801 headers = {'content-type':
802 "application/x-www-form-urlencoded"}
803 if headers is None:
804 headers = {}
805 if environ.has_key('CONTENT_TYPE'):
806 headers['content-type'] = environ['CONTENT_TYPE']
807 if environ.has_key('CONTENT_LENGTH'):
808 headers['content-length'] = environ['CONTENT_LENGTH']
809 self.fp = fp or sys.stdin
810 self.headers = headers
811 self.outerboundary = outerboundary
812
813 # Process content-disposition header
814 cdisp, pdict = "", {}
815 if self.headers.has_key('content-disposition'):
816 cdisp, pdict = parse_header(self.headers['content-disposition'])
817 self.disposition = cdisp
818 self.disposition_options = pdict
819 self.name = None
820 if pdict.has_key('name'):
821 self.name = pdict['name']
822 self.filename = None
823 if pdict.has_key('filename'):
824 self.filename = pdict['filename']
825
826 # Process content-type header
827 ctype, pdict = "text/plain", {}
828 if self.headers.has_key('content-type'):
829 ctype, pdict = parse_header(self.headers['content-type'])
830 self.type = ctype
831 self.type_options = pdict
832 self.innerboundary = ""
833 if pdict.has_key('boundary'):
834 self.innerboundary = pdict['boundary']
835 clen = -1
836 if self.headers.has_key('content-length'):
837 try:
838 clen = string.atoi(self.headers['content-length'])
839 except:
840 pass
Guido van Rossumad164711997-05-13 19:03:23 +0000841 if maxlen and clen > maxlen:
842 raise ValueError, 'Maximum content length exceeded'
Guido van Rossum7aee3841996-03-07 18:00:44 +0000843 self.length = clen
844
845 self.list = self.file = None
846 self.done = 0
847 self.lines = []
848 if ctype == 'application/x-www-form-urlencoded':
849 self.read_urlencoded()
850 elif ctype[:10] == 'multipart/':
851 self.read_multi()
852 else:
853 self.read_single()
854
855 def __repr__(self):
856 """Return a printable representation."""
857 return "FieldStorage(%s, %s, %s)" % (
858 `self.name`, `self.filename`, `self.value`)
859
860 def __getattr__(self, name):
861 if name != 'value':
862 raise AttributeError, name
863 if self.file:
864 self.file.seek(0)
865 value = self.file.read()
866 self.file.seek(0)
867 elif self.list is not None:
868 value = self.list
869 else:
870 value = None
871 return value
872
873 def __getitem__(self, key):
874 """Dictionary style indexing."""
875 if self.list is None:
876 raise TypeError, "not indexable"
877 found = []
878 for item in self.list:
879 if item.name == key: found.append(item)
880 if not found:
881 raise KeyError, key
Guido van Rossum0147db01996-03-09 03:16:04 +0000882 if len(found) == 1:
883 return found[0]
884 else:
885 return found
Guido van Rossum7aee3841996-03-07 18:00:44 +0000886
887 def keys(self):
888 """Dictionary style keys() method."""
889 if self.list is None:
890 raise TypeError, "not indexable"
891 keys = []
892 for item in self.list:
893 if item.name not in keys: keys.append(item.name)
894 return keys
895
Guido van Rossum0147db01996-03-09 03:16:04 +0000896 def has_key(self, key):
897 """Dictionary style has_key() method."""
898 if self.list is None:
899 raise TypeError, "not indexable"
900 for item in self.list:
901 if item.name == key: return 1
902 return 0
903
Guido van Rossum88b85d41997-01-11 19:21:33 +0000904 def __len__(self):
905 """Dictionary style len(x) support."""
906 return len(self.keys())
907
Guido van Rossum7aee3841996-03-07 18:00:44 +0000908 def read_urlencoded(self):
909 """Internal: read data in query string format."""
910 qs = self.fp.read(self.length)
Guido van Rossume08c04c1996-11-11 19:29:11 +0000911 dict = parse_qs(qs, self.keep_blank_values, self.strict_parsing)
Guido van Rossum7aee3841996-03-07 18:00:44 +0000912 self.list = []
913 for key, valuelist in dict.items():
914 for value in valuelist:
915 self.list.append(MiniFieldStorage(key, value))
916 self.skip_lines()
917
918 def read_multi(self):
919 """Internal: read a part that is itself multipart."""
Guido van Rossum7aee3841996-03-07 18:00:44 +0000920 self.list = []
921 part = self.__class__(self.fp, {}, self.innerboundary)
922 # Throw first part away
923 while not part.done:
924 headers = rfc822.Message(self.fp)
925 part = self.__class__(self.fp, headers, self.innerboundary)
926 self.list.append(part)
927 self.skip_lines()
928
929 def read_single(self):
930 """Internal: read an atomic part."""
931 if self.length >= 0:
932 self.read_binary()
933 self.skip_lines()
934 else:
935 self.read_lines()
936 self.file.seek(0)
937
938 bufsize = 8*1024 # I/O buffering size for copy to file
939
940 def read_binary(self):
941 """Internal: read binary data."""
942 self.file = self.make_file('b')
943 todo = self.length
944 if todo >= 0:
945 while todo > 0:
946 data = self.fp.read(min(todo, self.bufsize))
947 if not data:
948 self.done = -1
949 break
950 self.file.write(data)
951 todo = todo - len(data)
952
953 def read_lines(self):
954 """Internal: read lines until EOF or outerboundary."""
955 self.file = self.make_file('')
956 if self.outerboundary:
957 self.read_lines_to_outerboundary()
958 else:
959 self.read_lines_to_eof()
960
961 def read_lines_to_eof(self):
962 """Internal: read lines until EOF."""
963 while 1:
964 line = self.fp.readline()
965 if not line:
966 self.done = -1
967 break
968 self.lines.append(line)
Guido van Rossum7aee3841996-03-07 18:00:44 +0000969 self.file.write(line)
970
971 def read_lines_to_outerboundary(self):
972 """Internal: read lines until outerboundary."""
973 next = "--" + self.outerboundary
974 last = next + "--"
975 delim = ""
976 while 1:
977 line = self.fp.readline()
978 if not line:
979 self.done = -1
980 break
981 self.lines.append(line)
982 if line[:2] == "--":
983 strippedline = string.strip(line)
984 if strippedline == next:
985 break
986 if strippedline == last:
987 self.done = 1
988 break
Guido van Rossume5e46e01996-09-05 19:03:36 +0000989 odelim = delim
Guido van Rossum7aee3841996-03-07 18:00:44 +0000990 if line[-2:] == "\r\n":
Guido van Rossum99aa2a41996-07-23 17:27:05 +0000991 delim = "\r\n"
Guido van Rossum7aee3841996-03-07 18:00:44 +0000992 line = line[:-2]
993 elif line[-1] == "\n":
Guido van Rossum99aa2a41996-07-23 17:27:05 +0000994 delim = "\n"
Guido van Rossum7aee3841996-03-07 18:00:44 +0000995 line = line[:-1]
Guido van Rossum99aa2a41996-07-23 17:27:05 +0000996 else:
997 delim = ""
Guido van Rossume5e46e01996-09-05 19:03:36 +0000998 self.file.write(odelim + line)
Guido van Rossum7aee3841996-03-07 18:00:44 +0000999
1000 def skip_lines(self):
1001 """Internal: skip lines until outer boundary if defined."""
1002 if not self.outerboundary or self.done:
1003 return
1004 next = "--" + self.outerboundary
1005 last = next + "--"
1006 while 1:
1007 line = self.fp.readline()
1008 if not line:
1009 self.done = -1
1010 break
1011 self.lines.append(line)
1012 if line[:2] == "--":
1013 strippedline = string.strip(line)
1014 if strippedline == next:
1015 break
1016 if strippedline == last:
1017 self.done = 1
1018 break
1019
Guido van Rossuma5e9fb61997-08-12 18:18:13 +00001020 def make_file(self, binary=None):
Guido van Rossum7aee3841996-03-07 18:00:44 +00001021 """Overridable: return a readable & writable file.
1022
1023 The file will be used as follows:
1024 - data is written to it
1025 - seek(0)
1026 - data is read from it
1027
Guido van Rossuma5e9fb61997-08-12 18:18:13 +00001028 The 'binary' argument is unused -- the file is always opened
1029 in binary mode.
Guido van Rossum7aee3841996-03-07 18:00:44 +00001030
Guido van Rossum4032c2c1996-03-09 04:04:35 +00001031 This version opens a temporary file for reading and writing,
1032 and immediately deletes (unlinks) it. The trick (on Unix!) is
1033 that the file can still be used, but it can't be opened by
1034 another process, and it will automatically be deleted when it
1035 is closed or when the current process terminates.
1036
1037 If you want a more permanent file, you derive a class which
1038 overrides this method. If you want a visible temporary file
1039 that is nevertheless automatically deleted when the script
1040 terminates, try defining a __del__ method in a derived class
1041 which unlinks the temporary files you have created.
Guido van Rossum7aee3841996-03-07 18:00:44 +00001042
1043 """
Guido van Rossum4032c2c1996-03-09 04:04:35 +00001044 import tempfile
Guido van Rossuma5e9fb61997-08-12 18:18:13 +00001045 return tempfile.TemporaryFile("w+b")
1046
Guido van Rossum243ddcd1996-03-07 06:33:07 +00001047
1048
Guido van Rossum4032c2c1996-03-09 04:04:35 +00001049# Backwards Compatibility Classes
1050# ===============================
Guido van Rossum9a22de11995-01-12 12:29:47 +00001051
1052class FormContentDict:
Guido van Rossum7aee3841996-03-07 18:00:44 +00001053 """Basic (multiple values per field) form content as dictionary.
Guido van Rossum72755611996-03-06 07:20:06 +00001054
Guido van Rossum7aee3841996-03-07 18:00:44 +00001055 form = FormContentDict()
1056
1057 form[key] -> [value, value, ...]
1058 form.has_key(key) -> Boolean
1059 form.keys() -> [key, key, ...]
1060 form.values() -> [[val, val, ...], [val, val, ...], ...]
1061 form.items() -> [(key, [val, val, ...]), (key, [val, val, ...]), ...]
1062 form.dict == {key: [val, val, ...], ...}
1063
1064 """
Guido van Rossum773ab271996-07-23 03:46:24 +00001065 def __init__(self, environ=os.environ):
Guido van Rossumafb5e931996-08-08 18:42:12 +00001066 self.dict = parse(environ=environ)
Guido van Rossum7aee3841996-03-07 18:00:44 +00001067 self.query_string = environ['QUERY_STRING']
1068 def __getitem__(self,key):
1069 return self.dict[key]
1070 def keys(self):
1071 return self.dict.keys()
1072 def has_key(self, key):
1073 return self.dict.has_key(key)
1074 def values(self):
1075 return self.dict.values()
1076 def items(self):
1077 return self.dict.items()
1078 def __len__( self ):
1079 return len(self.dict)
Guido van Rossum9a22de11995-01-12 12:29:47 +00001080
1081
Guido van Rossum9a22de11995-01-12 12:29:47 +00001082class SvFormContentDict(FormContentDict):
Guido van Rossum7aee3841996-03-07 18:00:44 +00001083 """Strict single-value expecting form content as dictionary.
1084
1085 IF you only expect a single value for each field, then form[key]
1086 will return that single value. It will raise an IndexError if
1087 that expectation is not true. IF you expect a field to have
1088 possible multiple values, than you can use form.getlist(key) to
1089 get all of the values. values() and items() are a compromise:
1090 they return single strings where there is a single value, and
1091 lists of strings otherwise.
1092
1093 """
1094 def __getitem__(self, key):
1095 if len(self.dict[key]) > 1:
1096 raise IndexError, 'expecting a single value'
1097 return self.dict[key][0]
1098 def getlist(self, key):
1099 return self.dict[key]
1100 def values(self):
1101 lis = []
1102 for each in self.dict.values():
1103 if len( each ) == 1 :
1104 lis.append(each[0])
1105 else: lis.append(each)
1106 return lis
1107 def items(self):
1108 lis = []
1109 for key,value in self.dict.items():
1110 if len(value) == 1 :
1111 lis.append((key, value[0]))
1112 else: lis.append((key, value))
1113 return lis
Guido van Rossum9a22de11995-01-12 12:29:47 +00001114
1115
Guido van Rossum9a22de11995-01-12 12:29:47 +00001116class InterpFormContentDict(SvFormContentDict):
Guido van Rossum7aee3841996-03-07 18:00:44 +00001117 """This class is present for backwards compatibility only."""
1118 def __getitem__( self, key ):
1119 v = SvFormContentDict.__getitem__( self, key )
1120 if v[0] in string.digits+'+-.' :
1121 try: return string.atoi( v )
1122 except ValueError:
1123 try: return string.atof( v )
1124 except ValueError: pass
1125 return string.strip(v)
1126 def values( self ):
1127 lis = []
1128 for key in self.keys():
1129 try:
1130 lis.append( self[key] )
1131 except IndexError:
1132 lis.append( self.dict[key] )
1133 return lis
1134 def items( self ):
1135 lis = []
1136 for key in self.keys():
1137 try:
1138 lis.append( (key, self[key]) )
1139 except IndexError:
1140 lis.append( (key, self.dict[key]) )
1141 return lis
Guido van Rossum9a22de11995-01-12 12:29:47 +00001142
1143
Guido van Rossum9a22de11995-01-12 12:29:47 +00001144class FormContent(FormContentDict):
Guido van Rossum7aee3841996-03-07 18:00:44 +00001145 """This class is present for backwards compatibility only."""
Guido van Rossum0147db01996-03-09 03:16:04 +00001146 def values(self, key):
1147 if self.dict.has_key(key) :return self.dict[key]
Guido van Rossum7aee3841996-03-07 18:00:44 +00001148 else: return None
Guido van Rossum0147db01996-03-09 03:16:04 +00001149 def indexed_value(self, key, location):
Guido van Rossum7aee3841996-03-07 18:00:44 +00001150 if self.dict.has_key(key):
1151 if len (self.dict[key]) > location:
1152 return self.dict[key][location]
1153 else: return None
1154 else: return None
Guido van Rossum0147db01996-03-09 03:16:04 +00001155 def value(self, key):
1156 if self.dict.has_key(key): return self.dict[key][0]
Guido van Rossum7aee3841996-03-07 18:00:44 +00001157 else: return None
Guido van Rossum0147db01996-03-09 03:16:04 +00001158 def length(self, key):
1159 return len(self.dict[key])
1160 def stripped(self, key):
1161 if self.dict.has_key(key): return string.strip(self.dict[key][0])
Guido van Rossum7aee3841996-03-07 18:00:44 +00001162 else: return None
1163 def pars(self):
1164 return self.dict
Guido van Rossum9a22de11995-01-12 12:29:47 +00001165
1166
Guido van Rossum72755611996-03-06 07:20:06 +00001167# Test/debug code
1168# ===============
Guido van Rossum9a22de11995-01-12 12:29:47 +00001169
Guido van Rossum773ab271996-07-23 03:46:24 +00001170def test(environ=os.environ):
Guido van Rossum7aee3841996-03-07 18:00:44 +00001171 """Robust test CGI script, usable as main program.
Guido van Rossum9a22de11995-01-12 12:29:47 +00001172
Guido van Rossum7aee3841996-03-07 18:00:44 +00001173 Write minimal HTTP headers and dump all information provided to
1174 the script in HTML form.
1175
1176 """
1177 import traceback
1178 print "Content-type: text/html"
1179 print
1180 sys.stderr = sys.stdout
1181 try:
Guido van Rossum0147db01996-03-09 03:16:04 +00001182 form = FieldStorage() # Replace with other classes to test those
1183 print_form(form)
Guido van Rossum773ab271996-07-23 03:46:24 +00001184 print_environ(environ)
Guido van Rossum7aee3841996-03-07 18:00:44 +00001185 print_directory()
Guido van Rossuma8738a51996-03-14 21:30:28 +00001186 print_arguments()
Guido van Rossum7aee3841996-03-07 18:00:44 +00001187 print_environ_usage()
Guido van Rossumf85de8a1996-08-20 20:22:39 +00001188 def f():
1189 exec "testing print_exception() -- <I>italics?</I>"
1190 def g(f=f):
1191 f()
1192 print "<H3>What follows is a test, not an actual exception:</H3>"
1193 g()
Guido van Rossum7aee3841996-03-07 18:00:44 +00001194 except:
Guido van Rossumf85de8a1996-08-20 20:22:39 +00001195 print_exception()
1196
Guido van Rossumad164711997-05-13 19:03:23 +00001197 # Second try with a small maxlen...
1198 global maxlen
1199 maxlen = 50
1200 try:
1201 form = FieldStorage() # Replace with other classes to test those
1202 print_form(form)
1203 print_environ(environ)
1204 print_directory()
1205 print_arguments()
1206 print_environ_usage()
1207 except:
1208 print_exception()
1209
Guido van Rossumf85de8a1996-08-20 20:22:39 +00001210def print_exception(type=None, value=None, tb=None, limit=None):
1211 if type is None:
Guido van Rossumf15d1591997-09-29 23:22:12 +00001212 type, value, tb = sys.exc_info()
Guido van Rossumf85de8a1996-08-20 20:22:39 +00001213 import traceback
1214 print
1215 print "<H3>Traceback (innermost last):</H3>"
1216 list = traceback.format_tb(tb, limit) + \
1217 traceback.format_exception_only(type, value)
1218 print "<PRE>%s<B>%s</B></PRE>" % (
1219 escape(string.join(list[:-1], "")),
1220 escape(list[-1]),
1221 )
Guido van Rossumf15d1591997-09-29 23:22:12 +00001222 del tb
Guido van Rossum9a22de11995-01-12 12:29:47 +00001223
Guido van Rossum773ab271996-07-23 03:46:24 +00001224def print_environ(environ=os.environ):
Guido van Rossum7aee3841996-03-07 18:00:44 +00001225 """Dump the shell environment as HTML."""
1226 keys = environ.keys()
1227 keys.sort()
1228 print
Guido van Rossum503e50b1996-05-28 22:57:20 +00001229 print "<H3>Shell Environment:</H3>"
Guido van Rossum7aee3841996-03-07 18:00:44 +00001230 print "<DL>"
1231 for key in keys:
1232 print "<DT>", escape(key), "<DD>", escape(environ[key])
1233 print "</DL>"
1234 print
Guido van Rossum72755611996-03-06 07:20:06 +00001235
1236def print_form(form):
Guido van Rossum7aee3841996-03-07 18:00:44 +00001237 """Dump the contents of a form as HTML."""
1238 keys = form.keys()
1239 keys.sort()
1240 print
Guido van Rossum503e50b1996-05-28 22:57:20 +00001241 print "<H3>Form Contents:</H3>"
Guido van Rossum7aee3841996-03-07 18:00:44 +00001242 print "<DL>"
1243 for key in keys:
1244 print "<DT>" + escape(key) + ":",
1245 value = form[key]
1246 print "<i>" + escape(`type(value)`) + "</i>"
1247 print "<DD>" + escape(`value`)
1248 print "</DL>"
1249 print
1250
1251def print_directory():
1252 """Dump the current directory as HTML."""
1253 print
1254 print "<H3>Current Working Directory:</H3>"
1255 try:
1256 pwd = os.getcwd()
1257 except os.error, msg:
1258 print "os.error:", escape(str(msg))
1259 else:
1260 print escape(pwd)
1261 print
Guido van Rossum9a22de11995-01-12 12:29:47 +00001262
Guido van Rossuma8738a51996-03-14 21:30:28 +00001263def print_arguments():
1264 print
Guido van Rossum503e50b1996-05-28 22:57:20 +00001265 print "<H3>Command Line Arguments:</H3>"
Guido van Rossuma8738a51996-03-14 21:30:28 +00001266 print
1267 print sys.argv
1268 print
1269
Guido van Rossum9a22de11995-01-12 12:29:47 +00001270def print_environ_usage():
Guido van Rossum7aee3841996-03-07 18:00:44 +00001271 """Dump a list of environment variables used by CGI as HTML."""
1272 print """
Guido van Rossum72755611996-03-06 07:20:06 +00001273<H3>These environment variables could have been set:</H3>
1274<UL>
Guido van Rossum9a22de11995-01-12 12:29:47 +00001275<LI>AUTH_TYPE
1276<LI>CONTENT_LENGTH
1277<LI>CONTENT_TYPE
1278<LI>DATE_GMT
1279<LI>DATE_LOCAL
1280<LI>DOCUMENT_NAME
1281<LI>DOCUMENT_ROOT
1282<LI>DOCUMENT_URI
1283<LI>GATEWAY_INTERFACE
1284<LI>LAST_MODIFIED
1285<LI>PATH
1286<LI>PATH_INFO
1287<LI>PATH_TRANSLATED
1288<LI>QUERY_STRING
1289<LI>REMOTE_ADDR
1290<LI>REMOTE_HOST
1291<LI>REMOTE_IDENT
1292<LI>REMOTE_USER
1293<LI>REQUEST_METHOD
1294<LI>SCRIPT_NAME
1295<LI>SERVER_NAME
1296<LI>SERVER_PORT
1297<LI>SERVER_PROTOCOL
1298<LI>SERVER_ROOT
1299<LI>SERVER_SOFTWARE
1300</UL>
Guido van Rossum7aee3841996-03-07 18:00:44 +00001301In addition, HTTP headers sent by the server may be passed in the
1302environment as well. Here are some common variable names:
1303<UL>
1304<LI>HTTP_ACCEPT
1305<LI>HTTP_CONNECTION
1306<LI>HTTP_HOST
1307<LI>HTTP_PRAGMA
1308<LI>HTTP_REFERER
1309<LI>HTTP_USER_AGENT
1310</UL>
Guido van Rossum9a22de11995-01-12 12:29:47 +00001311"""
1312
Guido van Rossum9a22de11995-01-12 12:29:47 +00001313
Guido van Rossum72755611996-03-06 07:20:06 +00001314# Utilities
1315# =========
Guido van Rossum9a22de11995-01-12 12:29:47 +00001316
Guido van Rossum64c66201997-07-19 20:11:53 +00001317def escape(s, quote=None):
Guido van Rossum7aee3841996-03-07 18:00:44 +00001318 """Replace special characters '&', '<' and '>' by SGML entities."""
Guido van Rossum00f9fea1997-12-24 21:18:41 +00001319 s = string.replace(s, "&", "&amp;") # Must be done first!
1320 s = string.replace(s, "<", "&lt;")
1321 s = string.replace(s, ">", "&gt;",)
Guido van Rossum64c66201997-07-19 20:11:53 +00001322 if quote:
Guido van Rossum00f9fea1997-12-24 21:18:41 +00001323 s = string.replace(s, '"', "&quot;")
Guido van Rossum7aee3841996-03-07 18:00:44 +00001324 return s
Guido van Rossum9a22de11995-01-12 12:29:47 +00001325
Guido van Rossum9a22de11995-01-12 12:29:47 +00001326
Guido van Rossum72755611996-03-06 07:20:06 +00001327# Invoke mainline
1328# ===============
1329
1330# Call test() when this file is run as a script (not imported as a module)
1331if __name__ == '__main__':
Guido van Rossum7aee3841996-03-07 18:00:44 +00001332 test()