Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 1 | :mod:`cgi` --- Common Gateway Interface support |
| 2 | =============================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: cgi |
| 5 | :synopsis: Helpers for running Python scripts via the Common Gateway Interface. |
| 6 | |
| 7 | |
| 8 | .. index:: |
| 9 | pair: WWW; server |
| 10 | pair: CGI; protocol |
| 11 | pair: HTTP; protocol |
| 12 | pair: MIME; headers |
| 13 | single: URL |
| 14 | single: Common Gateway Interface |
| 15 | |
Raymond Hettinger | a199368 | 2011-01-27 01:20:32 +0000 | [diff] [blame] | 16 | **Source code:** :source:`Lib/cgi.py` |
| 17 | |
| 18 | -------------- |
| 19 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | Support module for Common Gateway Interface (CGI) scripts. |
| 21 | |
| 22 | This module defines a number of utilities for use by CGI scripts written in |
| 23 | Python. |
| 24 | |
| 25 | |
| 26 | Introduction |
| 27 | ------------ |
| 28 | |
| 29 | .. _cgi-intro: |
| 30 | |
| 31 | A CGI script is invoked by an HTTP server, usually to process user input |
| 32 | submitted through an HTML ``<FORM>`` or ``<ISINDEX>`` element. |
| 33 | |
| 34 | Most often, CGI scripts live in the server's special :file:`cgi-bin` directory. |
| 35 | The HTTP server places all sorts of information about the request (such as the |
| 36 | client's hostname, the requested URL, the query string, and lots of other |
| 37 | goodies) in the script's shell environment, executes the script, and sends the |
| 38 | script's output back to the client. |
| 39 | |
| 40 | The script's input is connected to the client too, and sometimes the form data |
| 41 | is read this way; at other times the form data is passed via the "query string" |
| 42 | part of the URL. This module is intended to take care of the different cases |
| 43 | and provide a simpler interface to the Python script. It also provides a number |
| 44 | of utilities that help in debugging scripts, and the latest addition is support |
| 45 | for file uploads from a form (if your browser supports it). |
| 46 | |
| 47 | The output of a CGI script should consist of two sections, separated by a blank |
| 48 | line. The first section contains a number of headers, telling the client what |
| 49 | kind of data is following. Python code to generate a minimal header section |
| 50 | looks like this:: |
| 51 | |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 52 | print("Content-Type: text/html") # HTML is following |
| 53 | print() # blank line, end of headers |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
| 55 | The second section is usually HTML, which allows the client software to display |
| 56 | nicely formatted text with header, in-line images, etc. Here's Python code that |
| 57 | prints a simple piece of HTML:: |
| 58 | |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 59 | print("<TITLE>CGI script output</TITLE>") |
| 60 | print("<H1>This is my first CGI script</H1>") |
| 61 | print("Hello, world!") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | |
| 63 | |
| 64 | .. _using-the-cgi-module: |
| 65 | |
| 66 | Using the cgi module |
| 67 | -------------------- |
| 68 | |
Georg Brandl | 49d1b4f | 2008-05-11 21:42:51 +0000 | [diff] [blame] | 69 | Begin by writing ``import cgi``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | |
Benjamin Peterson | ad3d5c2 | 2009-02-26 03:38:59 +0000 | [diff] [blame] | 71 | When you write a new script, consider adding these lines:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
Benjamin Peterson | ad3d5c2 | 2009-02-26 03:38:59 +0000 | [diff] [blame] | 73 | import cgitb |
| 74 | cgitb.enable() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
| 76 | This activates a special exception handler that will display detailed reports in |
| 77 | the Web browser if any errors occur. If you'd rather not show the guts of your |
| 78 | program to users of your script, you can have the reports saved to files |
Benjamin Peterson | ad3d5c2 | 2009-02-26 03:38:59 +0000 | [diff] [blame] | 79 | instead, with code like this:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
Benjamin Peterson | ad3d5c2 | 2009-02-26 03:38:59 +0000 | [diff] [blame] | 81 | import cgitb |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 82 | cgitb.enable(display=0, logdir="/path/to/logdir") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
| 84 | It's very helpful to use this feature during script development. The reports |
| 85 | produced by :mod:`cgitb` provide information that can save you a lot of time in |
| 86 | tracking down bugs. You can always remove the ``cgitb`` line later when you |
| 87 | have tested your script and are confident that it works correctly. |
| 88 | |
Senthil Kumaran | 290416f | 2012-04-30 22:43:13 +0800 | [diff] [blame] | 89 | To get at submitted form data, use the :class:`FieldStorage` class. If the form |
| 90 | contains non-ASCII characters, use the *encoding* keyword parameter set to the |
| 91 | value of the encoding defined for the document. It is usually contained in the |
| 92 | META tag in the HEAD section of the HTML document or by the |
| 93 | :mailheader:`Content-Type` header). This reads the form contents from the |
| 94 | standard input or the environment (depending on the value of various |
| 95 | environment variables set according to the CGI standard). Since it may consume |
| 96 | standard input, it should be instantiated only once. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 97 | |
Ezio Melotti | c7e994d | 2009-07-22 21:17:14 +0000 | [diff] [blame] | 98 | The :class:`FieldStorage` instance can be indexed like a Python dictionary. |
| 99 | It allows membership testing with the :keyword:`in` operator, and also supports |
Serhiy Storchaka | fd1c3d3 | 2013-10-13 18:28:26 +0300 | [diff] [blame] | 100 | the standard dictionary method :meth:`~dict.keys` and the built-in function |
Ezio Melotti | c7e994d | 2009-07-22 21:17:14 +0000 | [diff] [blame] | 101 | :func:`len`. Form fields containing empty strings are ignored and do not appear |
| 102 | in the dictionary; to keep such values, provide a true value for the optional |
| 103 | *keep_blank_values* keyword parameter when creating the :class:`FieldStorage` |
| 104 | instance. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
| 106 | For instance, the following code (which assumes that the |
| 107 | :mailheader:`Content-Type` header and blank line have already been printed) |
| 108 | checks that the fields ``name`` and ``addr`` are both set to a non-empty |
| 109 | string:: |
| 110 | |
| 111 | form = cgi.FieldStorage() |
Ezio Melotti | c7e994d | 2009-07-22 21:17:14 +0000 | [diff] [blame] | 112 | if "name" not in form or "addr" not in form: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 113 | print("<H1>Error</H1>") |
| 114 | print("Please fill in the name and addr fields.") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | return |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 116 | print("<p>name:", form["name"].value) |
| 117 | print("<p>addr:", form["addr"].value) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | ...further form processing here... |
| 119 | |
| 120 | Here the fields, accessed through ``form[key]``, are themselves instances of |
| 121 | :class:`FieldStorage` (or :class:`MiniFieldStorage`, depending on the form |
Serhiy Storchaka | fd1c3d3 | 2013-10-13 18:28:26 +0300 | [diff] [blame] | 122 | encoding). The :attr:`~FieldStorage.value` attribute of the instance yields |
| 123 | the string value of the field. The :meth:`~FieldStorage.getvalue` method |
| 124 | returns this string value directly; it also accepts an optional second argument |
| 125 | as a default to return if the requested key is not present. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | If the submitted form data contains more than one field with the same name, the |
| 128 | object retrieved by ``form[key]`` is not a :class:`FieldStorage` or |
| 129 | :class:`MiniFieldStorage` instance but a list of such instances. Similarly, in |
| 130 | this situation, ``form.getvalue(key)`` would return a list of strings. If you |
| 131 | expect this possibility (when your HTML form contains multiple fields with the |
Serhiy Storchaka | fd1c3d3 | 2013-10-13 18:28:26 +0300 | [diff] [blame] | 132 | same name), use the :meth:`~FieldStorage.getlist` method, which always returns |
| 133 | a list of values (so that you do not need to special-case the single item |
| 134 | case). For example, this code concatenates any number of username fields, |
| 135 | separated by commas:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 136 | |
| 137 | value = form.getlist("username") |
| 138 | usernames = ",".join(value) |
| 139 | |
| 140 | If a field represents an uploaded file, accessing the value via the |
Serhiy Storchaka | fd1c3d3 | 2013-10-13 18:28:26 +0300 | [diff] [blame] | 141 | :attr:`~FieldStorage.value` attribute or the :meth:`~FieldStorage.getvalue` |
| 142 | method reads the entire file in memory as bytes. This may not be what you |
| 143 | want. You can test for an uploaded file by testing either the |
| 144 | :attr:`~FieldStorage.filename` attribute or the :attr:`~FieldStorage.file` |
Brett Cannon | c089f70 | 2014-01-17 11:03:19 -0500 | [diff] [blame] | 145 | attribute. You can then read the data from the :attr:`!file` |
| 146 | attribute before it is automatically closed as part of the garbage collection of |
| 147 | the :class:`FieldStorage` instance |
| 148 | (the :func:`~io.RawIOBase.read` and :func:`~io.IOBase.readline` methods will |
| 149 | return bytes):: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
| 151 | fileitem = form["userfile"] |
| 152 | if fileitem.file: |
| 153 | # It's an uploaded file; count lines |
| 154 | linecount = 0 |
Collin Winter | 4633448 | 2007-09-10 00:49:57 +0000 | [diff] [blame] | 155 | while True: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | line = fileitem.file.readline() |
| 157 | if not line: break |
| 158 | linecount = linecount + 1 |
| 159 | |
Sean Reifscheider | 782d6b4 | 2007-09-18 23:39:35 +0000 | [diff] [blame] | 160 | If an error is encountered when obtaining the contents of an uploaded file |
| 161 | (for example, when the user interrupts the form submission by clicking on |
Serhiy Storchaka | fd1c3d3 | 2013-10-13 18:28:26 +0300 | [diff] [blame] | 162 | a Back or Cancel button) the :attr:`~FieldStorage.done` attribute of the |
| 163 | object for the field will be set to the value -1. |
Sean Reifscheider | 782d6b4 | 2007-09-18 23:39:35 +0000 | [diff] [blame] | 164 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 165 | The file upload draft standard entertains the possibility of uploading multiple |
| 166 | files from one field (using a recursive :mimetype:`multipart/\*` encoding). |
| 167 | When this occurs, the item will be a dictionary-like :class:`FieldStorage` item. |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 168 | This can be determined by testing its :attr:`!type` attribute, which should be |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 169 | :mimetype:`multipart/form-data` (or perhaps another MIME type matching |
| 170 | :mimetype:`multipart/\*`). In this case, it can be iterated over recursively |
| 171 | just like the top-level form object. |
| 172 | |
| 173 | When a form is submitted in the "old" format (as the query string or as a single |
| 174 | data part of type :mimetype:`application/x-www-form-urlencoded`), the items will |
| 175 | actually be instances of the class :class:`MiniFieldStorage`. In this case, the |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 176 | :attr:`!list`, :attr:`!file`, and :attr:`filename` attributes are always ``None``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 177 | |
Benjamin Peterson | dcf97b9 | 2008-07-02 17:30:14 +0000 | [diff] [blame] | 178 | A form submitted via POST that also has a query string will contain both |
| 179 | :class:`FieldStorage` and :class:`MiniFieldStorage` items. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 180 | |
Brett Cannon | c089f70 | 2014-01-17 11:03:19 -0500 | [diff] [blame] | 181 | .. versionchanged:: 3.4 |
| 182 | The :attr:`~FieldStorage.file` attribute is automatically closed upon the |
| 183 | garbage collection of the creating :class:`FieldStorage` instance. |
| 184 | |
| 185 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 186 | Higher Level Interface |
| 187 | ---------------------- |
| 188 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 189 | The previous section explains how to read CGI form data using the |
| 190 | :class:`FieldStorage` class. This section describes a higher level interface |
| 191 | which was added to this class to allow one to do it in a more readable and |
| 192 | intuitive way. The interface doesn't make the techniques described in previous |
| 193 | sections obsolete --- they are still useful to process file uploads efficiently, |
| 194 | for example. |
| 195 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 196 | .. XXX: Is this true ? |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 197 | |
| 198 | The interface consists of two simple methods. Using the methods you can process |
| 199 | form data in a generic way, without the need to worry whether only one or more |
| 200 | values were posted under one name. |
| 201 | |
| 202 | In the previous section, you learned to write following code anytime you |
| 203 | expected a user to post more than one value under one name:: |
| 204 | |
| 205 | item = form.getvalue("item") |
| 206 | if isinstance(item, list): |
| 207 | # The user is requesting more than one item. |
| 208 | else: |
| 209 | # The user is requesting only one item. |
| 210 | |
| 211 | This situation is common for example when a form contains a group of multiple |
| 212 | checkboxes with the same name:: |
| 213 | |
| 214 | <input type="checkbox" name="item" value="1" /> |
| 215 | <input type="checkbox" name="item" value="2" /> |
| 216 | |
| 217 | In most situations, however, there's only one form control with a particular |
| 218 | name in a form and then you expect and need only one value associated with this |
| 219 | name. So you write a script containing for example this code:: |
| 220 | |
| 221 | user = form.getvalue("user").upper() |
| 222 | |
| 223 | The problem with the code is that you should never expect that a client will |
| 224 | provide valid input to your scripts. For example, if a curious user appends |
| 225 | another ``user=foo`` pair to the query string, then the script would crash, |
| 226 | because in this situation the ``getvalue("user")`` method call returns a list |
Benjamin Peterson | 8719ad5 | 2009-09-11 22:24:02 +0000 | [diff] [blame] | 227 | instead of a string. Calling the :meth:`~str.upper` method on a list is not valid |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 228 | (since lists do not have a method of this name) and results in an |
| 229 | :exc:`AttributeError` exception. |
| 230 | |
| 231 | Therefore, the appropriate way to read form data values was to always use the |
| 232 | code which checks whether the obtained value is a single value or a list of |
| 233 | values. That's annoying and leads to less readable scripts. |
| 234 | |
Serhiy Storchaka | fd1c3d3 | 2013-10-13 18:28:26 +0300 | [diff] [blame] | 235 | A more convenient approach is to use the methods :meth:`~FieldStorage.getfirst` |
| 236 | and :meth:`~FieldStorage.getlist` provided by this higher level interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 237 | |
| 238 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 239 | .. method:: FieldStorage.getfirst(name, default=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 240 | |
| 241 | This method always returns only one value associated with form field *name*. |
| 242 | The method returns only the first value in case that more values were posted |
| 243 | under such name. Please note that the order in which the values are received |
| 244 | may vary from browser to browser and should not be counted on. [#]_ If no such |
| 245 | form field or value exists then the method returns the value specified by the |
| 246 | optional parameter *default*. This parameter defaults to ``None`` if not |
| 247 | specified. |
| 248 | |
| 249 | |
| 250 | .. method:: FieldStorage.getlist(name) |
| 251 | |
| 252 | This method always returns a list of values associated with form field *name*. |
| 253 | The method returns an empty list if no such form field or value exists for |
| 254 | *name*. It returns a list consisting of one item if only one such value exists. |
| 255 | |
| 256 | Using these methods you can write nice compact code:: |
| 257 | |
| 258 | import cgi |
| 259 | form = cgi.FieldStorage() |
| 260 | user = form.getfirst("user", "").upper() # This way it's safe. |
| 261 | for item in form.getlist("item"): |
| 262 | do_something(item) |
| 263 | |
| 264 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 265 | .. _functions-in-cgi-module: |
| 266 | |
| 267 | Functions |
| 268 | --------- |
| 269 | |
| 270 | These are useful if you want more control, or if you want to employ some of the |
| 271 | algorithms implemented in this module in other circumstances. |
| 272 | |
| 273 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 274 | .. function:: parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 275 | |
| 276 | Parse a query in the environment or from a file (the file defaults to |
| 277 | ``sys.stdin``). The *keep_blank_values* and *strict_parsing* parameters are |
Facundo Batista | c469d4c | 2008-09-03 22:49:01 +0000 | [diff] [blame] | 278 | passed to :func:`urllib.parse.parse_qs` unchanged. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 279 | |
| 280 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 281 | .. function:: parse_qs(qs, keep_blank_values=False, strict_parsing=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 282 | |
Facundo Batista | c469d4c | 2008-09-03 22:49:01 +0000 | [diff] [blame] | 283 | This function is deprecated in this module. Use :func:`urllib.parse.parse_qs` |
Georg Brandl | ae2dbe2 | 2009-03-13 19:04:40 +0000 | [diff] [blame] | 284 | instead. It is maintained here only for backward compatibility. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 286 | .. function:: parse_qsl(qs, keep_blank_values=False, strict_parsing=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 287 | |
Martin Panter | cebfdac | 2015-09-20 00:28:50 +0000 | [diff] [blame] | 288 | This function is deprecated in this module. Use :func:`urllib.parse.parse_qsl` |
Georg Brandl | ae2dbe2 | 2009-03-13 19:04:40 +0000 | [diff] [blame] | 289 | instead. It is maintained here only for backward compatibility. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 290 | |
| 291 | .. function:: parse_multipart(fp, pdict) |
| 292 | |
| 293 | Parse input of type :mimetype:`multipart/form-data` (for file uploads). |
| 294 | Arguments are *fp* for the input file and *pdict* for a dictionary containing |
| 295 | other parameters in the :mailheader:`Content-Type` header. |
| 296 | |
Facundo Batista | c469d4c | 2008-09-03 22:49:01 +0000 | [diff] [blame] | 297 | Returns a dictionary just like :func:`urllib.parse.parse_qs` keys are the field names, each |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 298 | value is a list of values for that field. This is easy to use but not much good |
| 299 | if you are expecting megabytes to be uploaded --- in that case, use the |
| 300 | :class:`FieldStorage` class instead which is much more flexible. |
| 301 | |
| 302 | Note that this does not parse nested multipart parts --- use |
| 303 | :class:`FieldStorage` for that. |
| 304 | |
| 305 | |
| 306 | .. function:: parse_header(string) |
| 307 | |
| 308 | Parse a MIME header (such as :mailheader:`Content-Type`) into a main value and a |
| 309 | dictionary of parameters. |
| 310 | |
| 311 | |
| 312 | .. function:: test() |
| 313 | |
| 314 | Robust test CGI script, usable as main program. Writes minimal HTTP headers and |
| 315 | formats all information provided to the script in HTML form. |
| 316 | |
| 317 | |
| 318 | .. function:: print_environ() |
| 319 | |
| 320 | Format the shell environment in HTML. |
| 321 | |
| 322 | |
| 323 | .. function:: print_form(form) |
| 324 | |
| 325 | Format a form in HTML. |
| 326 | |
| 327 | |
| 328 | .. function:: print_directory() |
| 329 | |
| 330 | Format the current directory in HTML. |
| 331 | |
| 332 | |
| 333 | .. function:: print_environ_usage() |
| 334 | |
| 335 | Print a list of useful (used by CGI) environment variables in HTML. |
| 336 | |
| 337 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 338 | .. function:: escape(s, quote=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 339 | |
| 340 | Convert the characters ``'&'``, ``'<'`` and ``'>'`` in string *s* to HTML-safe |
| 341 | sequences. Use this if you need to display text that might contain such |
| 342 | characters in HTML. If the optional flag *quote* is true, the quotation mark |
Georg Brandl | 1800934 | 2010-08-02 21:51:18 +0000 | [diff] [blame] | 343 | character (``"``) is also translated; this helps for inclusion in an HTML |
| 344 | attribute value delimited by double quotes, as in ``<a href="...">``. Note |
| 345 | that single quotes are never translated. |
| 346 | |
Georg Brandl | 1f7fffb | 2010-10-15 15:57:45 +0000 | [diff] [blame] | 347 | .. deprecated:: 3.2 |
| 348 | This function is unsafe because *quote* is false by default, and therefore |
| 349 | deprecated. Use :func:`html.escape` instead. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 350 | |
| 351 | |
| 352 | .. _cgi-security: |
| 353 | |
| 354 | Caring about security |
| 355 | --------------------- |
| 356 | |
| 357 | .. index:: pair: CGI; security |
| 358 | |
| 359 | There's one important rule: if you invoke an external program (via the |
| 360 | :func:`os.system` or :func:`os.popen` functions. or others with similar |
| 361 | functionality), make very sure you don't pass arbitrary strings received from |
| 362 | the client to the shell. This is a well-known security hole whereby clever |
| 363 | hackers anywhere on the Web can exploit a gullible CGI script to invoke |
| 364 | arbitrary shell commands. Even parts of the URL or field names cannot be |
| 365 | trusted, since the request doesn't have to come from your form! |
| 366 | |
| 367 | To be on the safe side, if you must pass a string gotten from a form to a shell |
| 368 | command, you should make sure the string contains only alphanumeric characters, |
| 369 | dashes, underscores, and periods. |
| 370 | |
| 371 | |
| 372 | Installing your CGI script on a Unix system |
| 373 | ------------------------------------------- |
| 374 | |
| 375 | Read the documentation for your HTTP server and check with your local system |
| 376 | administrator to find the directory where CGI scripts should be installed; |
| 377 | usually this is in a directory :file:`cgi-bin` in the server tree. |
| 378 | |
| 379 | Make sure that your script is readable and executable by "others"; the Unix file |
Georg Brandl | f4a4123 | 2008-05-26 17:55:52 +0000 | [diff] [blame] | 380 | mode should be ``0o755`` octal (use ``chmod 0755 filename``). Make sure that the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 381 | first line of the script contains ``#!`` starting in column 1 followed by the |
| 382 | pathname of the Python interpreter, for instance:: |
| 383 | |
| 384 | #!/usr/local/bin/python |
| 385 | |
| 386 | Make sure the Python interpreter exists and is executable by "others". |
| 387 | |
| 388 | Make sure that any files your script needs to read or write are readable or |
Georg Brandl | f4a4123 | 2008-05-26 17:55:52 +0000 | [diff] [blame] | 389 | writable, respectively, by "others" --- their mode should be ``0o644`` for |
| 390 | readable and ``0o666`` for writable. This is because, for security reasons, the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 391 | HTTP server executes your script as user "nobody", without any special |
| 392 | privileges. It can only read (write, execute) files that everybody can read |
| 393 | (write, execute). The current directory at execution time is also different (it |
| 394 | is usually the server's cgi-bin directory) and the set of environment variables |
| 395 | is also different from what you get when you log in. In particular, don't count |
| 396 | on the shell's search path for executables (:envvar:`PATH`) or the Python module |
| 397 | search path (:envvar:`PYTHONPATH`) to be set to anything interesting. |
| 398 | |
| 399 | If you need to load modules from a directory which is not on Python's default |
| 400 | module search path, you can change the path in your script, before importing |
| 401 | other modules. For example:: |
| 402 | |
| 403 | import sys |
| 404 | sys.path.insert(0, "/usr/home/joe/lib/python") |
| 405 | sys.path.insert(0, "/usr/local/lib/python") |
| 406 | |
| 407 | (This way, the directory inserted last will be searched first!) |
| 408 | |
| 409 | Instructions for non-Unix systems will vary; check your HTTP server's |
| 410 | documentation (it will usually have a section on CGI scripts). |
| 411 | |
| 412 | |
| 413 | Testing your CGI script |
| 414 | ----------------------- |
| 415 | |
| 416 | Unfortunately, a CGI script will generally not run when you try it from the |
| 417 | command line, and a script that works perfectly from the command line may fail |
| 418 | mysteriously when run from the server. There's one reason why you should still |
| 419 | test your script from the command line: if it contains a syntax error, the |
| 420 | Python interpreter won't execute it at all, and the HTTP server will most likely |
| 421 | send a cryptic error to the client. |
| 422 | |
| 423 | Assuming your script has no syntax errors, yet it does not work, you have no |
| 424 | choice but to read the next section. |
| 425 | |
| 426 | |
| 427 | Debugging CGI scripts |
| 428 | --------------------- |
| 429 | |
| 430 | .. index:: pair: CGI; debugging |
| 431 | |
| 432 | First of all, check for trivial installation errors --- reading the section |
| 433 | above on installing your CGI script carefully can save you a lot of time. If |
| 434 | you wonder whether you have understood the installation procedure correctly, try |
| 435 | installing a copy of this module file (:file:`cgi.py`) as a CGI script. When |
| 436 | invoked as a script, the file will dump its environment and the contents of the |
| 437 | form in HTML form. Give it the right mode etc, and send it a request. If it's |
| 438 | installed in the standard :file:`cgi-bin` directory, it should be possible to |
| 439 | send it a request by entering a URL into your browser of the form:: |
| 440 | |
| 441 | http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home |
| 442 | |
| 443 | If this gives an error of type 404, the server cannot find the script -- perhaps |
| 444 | you need to install it in a different directory. If it gives another error, |
| 445 | there's an installation problem that you should fix before trying to go any |
| 446 | further. If you get a nicely formatted listing of the environment and form |
| 447 | content (in this example, the fields should be listed as "addr" with value "At |
| 448 | Home" and "name" with value "Joe Blow"), the :file:`cgi.py` script has been |
| 449 | installed correctly. If you follow the same procedure for your own script, you |
| 450 | should now be able to debug it. |
| 451 | |
| 452 | The next step could be to call the :mod:`cgi` module's :func:`test` function |
| 453 | from your script: replace its main code with the single statement :: |
| 454 | |
| 455 | cgi.test() |
| 456 | |
| 457 | This should produce the same results as those gotten from installing the |
| 458 | :file:`cgi.py` file itself. |
| 459 | |
| 460 | When an ordinary Python script raises an unhandled exception (for whatever |
| 461 | reason: of a typo in a module name, a file that can't be opened, etc.), the |
| 462 | Python interpreter prints a nice traceback and exits. While the Python |
| 463 | interpreter will still do this when your CGI script raises an exception, most |
| 464 | likely the traceback will end up in one of the HTTP server's log files, or be |
| 465 | discarded altogether. |
| 466 | |
| 467 | Fortunately, once you have managed to get your script to execute *some* code, |
| 468 | you can easily send tracebacks to the Web browser using the :mod:`cgitb` module. |
Benjamin Peterson | ad3d5c2 | 2009-02-26 03:38:59 +0000 | [diff] [blame] | 469 | If you haven't done so already, just add the lines:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 470 | |
Benjamin Peterson | ad3d5c2 | 2009-02-26 03:38:59 +0000 | [diff] [blame] | 471 | import cgitb |
| 472 | cgitb.enable() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 473 | |
| 474 | to the top of your script. Then try running it again; when a problem occurs, |
| 475 | you should see a detailed report that will likely make apparent the cause of the |
| 476 | crash. |
| 477 | |
| 478 | If you suspect that there may be a problem in importing the :mod:`cgitb` module, |
| 479 | you can use an even more robust approach (which only uses built-in modules):: |
| 480 | |
| 481 | import sys |
| 482 | sys.stderr = sys.stdout |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 483 | print("Content-Type: text/plain") |
| 484 | print() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 485 | ...your code here... |
| 486 | |
| 487 | This relies on the Python interpreter to print the traceback. The content type |
| 488 | of the output is set to plain text, which disables all HTML processing. If your |
| 489 | script works, the raw HTML will be displayed by your client. If it raises an |
| 490 | exception, most likely after the first two lines have been printed, a traceback |
| 491 | will be displayed. Because no HTML interpretation is going on, the traceback |
| 492 | will be readable. |
| 493 | |
| 494 | |
| 495 | Common problems and solutions |
| 496 | ----------------------------- |
| 497 | |
| 498 | * Most HTTP servers buffer the output from CGI scripts until the script is |
| 499 | completed. This means that it is not possible to display a progress report on |
| 500 | the client's display while the script is running. |
| 501 | |
| 502 | * Check the installation instructions above. |
| 503 | |
| 504 | * Check the HTTP server's log files. (``tail -f logfile`` in a separate window |
| 505 | may be useful!) |
| 506 | |
| 507 | * Always check a script for syntax errors first, by doing something like |
| 508 | ``python script.py``. |
| 509 | |
| 510 | * If your script does not have any syntax errors, try adding ``import cgitb; |
| 511 | cgitb.enable()`` to the top of the script. |
| 512 | |
| 513 | * When invoking external programs, make sure they can be found. Usually, this |
| 514 | means using absolute path names --- :envvar:`PATH` is usually not set to a very |
| 515 | useful value in a CGI script. |
| 516 | |
| 517 | * When reading or writing external files, make sure they can be read or written |
| 518 | by the userid under which your CGI script will be running: this is typically the |
| 519 | userid under which the web server is running, or some explicitly specified |
| 520 | userid for a web server's ``suexec`` feature. |
| 521 | |
| 522 | * Don't try to give a CGI script a set-uid mode. This doesn't work on most |
| 523 | systems, and is a security liability as well. |
| 524 | |
| 525 | .. rubric:: Footnotes |
| 526 | |
Georg Brandl | 1f7fffb | 2010-10-15 15:57:45 +0000 | [diff] [blame] | 527 | .. [#] Note that some recent versions of the HTML specification do state what |
| 528 | order the field values should be supplied in, but knowing whether a request |
| 529 | was received from a conforming browser, or even from a browser at all, is |
| 530 | tedious and error-prone. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 531 | |