Example 15-4. PP4E\Internet\Web\cgi-bin\tutor1.py

#!/usr/bin/python
text = """Content-type: text/html

A Second CGI Script


Hello, CGI World!



"""
print(text)

Figure 15-4. A page with an image generated by tutor1.py

Example 15-5. PP4E\Internet\Web\cgi-bin\tutor2.py

#!/usr/bin/python
print("""Content-type: text/html

A Third CGI Script


Hello, CGI World!


""")
for i in range(5):
print('')
for j in range(4):
print('' % (i, j))
print('')
print("""
%d.%d


""")

The script
in
Example 15-5
generates HTML table tags. Again, we’re not out to learn HTML here,
but we’ll take a quick look just so that you can make sense of this
book’s examples. Tables are declared by the text between

For instance, here is part of the script’s output, defining the
first two rows (to see the full output, run the script standalone from
a system command line, or select your browser’s View Source
option):

. . .
0.0
0.1
0.2
0.3
1.0
1.1
1.2
1.3

Other table tags and options let us specify a row title
(

), lay out borders, and
so on. We’ll use more table syntax to lay out forms in a uniform
fashion later in
this tutorial.

That description
sounds simple enough, but the process of collecting user
inputs requires an understanding of a special HTML tag,

A first user interaction: forms



Enter your name:

tutor3.html
is a simple HTML file, not a
CGI script (though its contents could be printed from a script as
well). When this file is accessed, all the text between its

Figure 15-6. A simple form page generated by tutor3.html

We won’t go into all the
details behind coding HTML forms, but a few highlights
are worth underscoring. The following occurs within a form’s HTML
code:

Notice that the
action
URL in
this example’s form spells out the full address for illustration.
Because the browser remembers where the enclosing HTML page came from,
it works the same with just the script’s filename, as shown in
Example 15-7
.

A first user interaction: forms



Enter your name:

It may help to remember that URLs embedded in form action tags
and hyperlinks are directions to the browser first, not to the script.
The
tutor3.py
script itself doesn’t care which
URL form is used to trigger it—minimal or complete. In fact, all parts
of a URL through the script filename (and up to URL query parameters)
are used in the conversation between browser and HTTP server, before a
CGI script is ever spawned. As long as the browser knows which server
to contact, the URL will work.

On the other hand, URLs submitted outside of a page (e.g., typed
into a browser’s address field or sent to the Python
urllib.request
module we’ll revisit later)
usually must be completely specified, because there is no notion of a
prior page.

So far, we’ve
created only a static page with an input field. But the
Submit button on this page is loaded to work magic. When pressed, it
triggers the possibly remote program whose URL is listed in the form’s
action
option, and passes this
program the input data typed by the user, according to the form’s
method
encoding style option. On
the server, a Python script is started to handle the form’s input data
while the user waits for a reply on the client; that script is shown
in
Example 15-8
.

#!/usr/bin/python
"""
runs on the server, reads form input, prints HTML;
url=http://server-name/cgi-bin/tutor3.py
"""
import cgi
form = cgi.FieldStorage()            # parse form data
print('Content-type: text/html')     # plus blank line
html = """

Greetings


%s

"""
if not 'user' in form:
print(html % 'Who are you?')
else:
print(html % ('Hello, %s.' % form['user'].value))

As before, this Python CGI script prints HTML to generate a
response page in the client’s browser. But this script does a bit
more: it also uses the standard
cgi
module to parse the input data entered by the user on the prior web
page (see
Figure 15-6
).

Luckily, this is automatic in Python: a call to the standard
library
cgi
module’s
FieldStorage
class
does all the work of extracting form data from the input stream and
environment variables, regardless of how that data was passed—in a
post
style stream or in
get
style parameters appended to the URL.
Inputs sent in both styles look the same to Python scripts.

Scripts should call
cgi.FieldStorage
only once and before
accessing any field values. When it is called, we get back an object
that looks like a dictionary—user input fields from the form (or URL)
show up as values of keys in this object. For example, in the script,
form['user']
is an object whose
value
attribute is a string
containing the text typed into the form’s text field. If you flip back
to the form page’s HTML, you’ll notice that the input field’s
name
option was
user
—the name in the form’s HTML has become
a key we use to fetch the input’s value from a dictionary. The object
returned by
FieldStorage
supports
other dictionary operations, too—for instance, the
in
expression may be used to check whether a
field is present in the input data.

Before exiting, this script prints HTML to produce a result page
that echoes back what the user typed into the form. Two
string-formatting expressions (
%
)
are used to insert the input text into a reply string, and the reply
string into the triple-quoted HTML string block. The body of the
script’s output looks like this:

Greetings


Hello, King Arthur.

In a browser, the output is rendered into a page like the one in
Figure 15-7
.

Figure 15-7. tutor3.py result for parameters in a form

Notice that the URL
address of the script that generated this page shows up
at the top of the browser. We didn’t type this URL itself—it came from
the
action
tag of the prior page’s
form
HTML. However, nothing is
stopping us from typing the script’s URL explicitly in our browser’s
address field to invoke the script, just as we did for our earlier CGI
script and HTML file examples.

But there’s a catch here: where does the input field’s value
come from if there is no form page? That is, if we type the CGI
script’s URL ourselves, how does the input field get filled in?
Earlier, when we talked about URL formats, I mentioned that the
get
encoding scheme tacks input
parameters onto the end of URLs. When we type script addresses
explicitly, we can also append input values on the end of URLs, where
they serve the same purpose as

fields in forms. Moreover, the
Python
cgi
module makes URL and
form inputs look identical to scripts.

For instance, we can skip filling out the input form page
completely and directly invoke our
tutor3.py
script by visiting a URL of this form (type this in your browser’s
address field):

http://localhost/cgi-bin/tutor3.py?user=Brian

In this URL, a value for the input named
user
is specified explicitly, as if the user
had filled out the input page. When called this way, the only
constraint is that the parameter name
user
must match the name expected by the
script (and hardcoded in the form’s HTML). We use just one parameter
here, but in general, URL parameters are typically introduced with a
?
and are followed by one or more
name=value
assignments, separated
by
&
characters if there is
more than one.
Figure 15-8
shows the
response page we get after typing a URL with explicit inputs.

Figure 15-8. tutor3.py result for parameters in a URL

In fact, HTML forms that specify the
get
encoding style also cause inputs to be
added to URLs this way. Try changing
Example 15-6
to use
method=GET
, and submit the
form—
the name input in the form shows up
as a query parameter in the reply page address field, just like the
URL we manually entered in
Figure 15-8
. Forms can use
the
post
or
get
style. Manually typed URLs with
parameters use
get
.

Generally, any CGI script can be invoked either by filling out
and submitting a form page or by passing inputs at the end of a URL.
Although hand-coding parameters in URLs can become difficult for
scripts that expect many complex parameters, other programs can
automate the construction process.

When CGI scripts are invoked with explicit input parameters this
way, it’s not too difficult to see their similarity to
functions
, albeit ones that live
remotely on the Net. Passing data to scripts in URLs is similar to
keyword arguments in Python functions, both operationally and
syntactically. In fact, some advanced web frameworks such as Zope make
the relationship between URLs and Python function calls even more
literal: URLs become more direct calls to Python functions.

Incidentally, if you clear out the name input field in the form
input page (i.e., make it empty) and press Submit, the
user
name field becomes empty. More
accurately, the browser may not send this field along with the form
data at all, even though it is listed in the form layout HTML. The CGI
script detects such a missing field with the dictionary
in
expression and produces the page captured
in
Figure 15-9
in
response.

Figure 15-9. An empty name field producing an error page

In general, CGI scripts must check to see whether any inputs are
missing, partly because they might not be typed by a user in the form,
but also because there may be no form at all—input fields might not be
tacked onto the end of an explicitly typed or constructed
get
-style URL. For instance, if we type the
script’s URL without any parameters at all—by omitting the text from
the
?
and beyond, and visiting
http://localhost/cgi-bin/tutor3.py
with an
explicitly entered URL—we get this same error response page. Since we
can invoke any CGI through a form or URL, scripts must anticipate both
scenarios.