#!/usr/bin/python
"""
runs on the server, prints HTML to create a new page;
url=http://localhost/cgi-bin/tutor0.py
"""
print('Content-type: text/html\n')
print('')
print('
A First CGI Script
')
print('
Hello, CGI World!
')

Figure 15-3. A simple web page from a CGI script

Directory and filename
conventions

First, CGI scripts
need to be placed in a directory that your web
server recognizes as a program directory, and they need to be
given a name that your server recognizes as a CGI script. In the
local web server we’re using in this chapter, scripts need to be
placed in a special
cgi-bin
subdirectory
and be named with a
.py
extension. On the
server used for this book’s second edition, CGI scripts instead
were stored in the user’s
public_html
directory just like HTML files, but they required a filename
ending in a
.cgi
, not a
.py
. Some servers may allow other suffixes
and program directories; this varies widely and can sometimes be
configured per server or per user.

Execution conventions

Because they
must be executed by the web server on behalf of
arbitrary users on the Web, CGI script files may also need to be
given executable file permissions to mark them as programs and
be made executable by others. Again, a shell command
chmod 0755
filename
does the trick on most
servers.

Under some servers, CGI scripts also need the special
#!
line at the top, to
identify the Python interpreter that runs the file’s code. The
text after the
#!
in the
first line simply gives the directory path to the Python
executable on your server machine. See
Chapter 3
for more details on this
special first line, and be sure to check your server’s
conventions for more details on non-Unix platforms.

Some servers may expect this line, even outside Unix. Most
of the CGI scripts in this book include the
#!
line just in case they will ever be
run on Unix-like platforms; under our locally running web server
on Windows, this first line is simply ignored as a Python
comment.

One subtlety worth noting: as we saw earlier in the book,
the special first line in executable text files can normally
contain either a hardcoded path to the Python interpreter (e.g.,
#!/usr/bin/python
) or an invocation of the
env
program (e.g.,
#!/usr/bin/env python
), which
deduces where Python lives from environment variable settings
(i.e., your
$PATH
). The
env
trick is less useful in
CGI scripts, though, because their environment settings may be
those of the user “nobody” (not your own), as explained in the
next paragraph.

Module search path configuration
(optional)

Some HTTP
servers may run CGI scripts with the username
“nobody” for security reasons (this limits the user’s access to
the server machine). That’s why files you publish on the Web
must have special permission settings that make them accessible
to other users. It also means that some CGI scripts can’t rely
on the Python module search path to be configured in any
particular way. As you’ve learned by now, the module path is
normally initialized from the user’s
PYTHONPATH
setting and
.pth
files, plus defaults which normally
include the current working directory. But because CGI scripts
are run by the user “nobody,”
PYTHONPATH
may be arbitrary when a CGI
script runs.

Before you puzzle over this too hard, you should know that
this is often not a concern in practice. Because Python usually
searches the current directory for imported modules by default,
this is not an issue if all of your scripts and any modules and
packages they use are stored in your web directory, and your web
server launches CGI scripts in the directory in which they
reside. But if the module lives elsewhere, you may need to
modify the
sys.path
list in
your scripts to adjust the search path manually before
imports—for instance, with
sys.path.append(
dirname
)
calls, index assignments, and so
on.

End-of-line conventions
(optional)

On some Unix
(and Linux) servers, you might also have to make
sure that your script text files follow the Unix end-of-line
convention (
\n
), not DOS
(
\r\n
). This isn’t an issue
if you edit and debug right on the server (or on another Unix
machine) or FTP files one by one in text mode. But if you edit
and upload your scripts from a PC to a Unix server in a
tar
file (or in FTP binary mode), you may
need to convert end-of-lines after the upload. For instance, the
server that was used for the second edition of this text returns
a default error page for scripts whose end-of-lines are in DOS
format. See
Chapter 6
for
techniques and a note on automated end-of-line converter
scripts.

Unbuffered output streams
(optional)

Under some servers, the
print
call statement may buffer its
output. If you have a long-running CGI script, to avoid making
the user wait to see results, you may wish to manually flush
your printed text (call
sys.stdout.flush()
) or run your Python
scripts in unbuffered mode. Recall from
Chapter 5
that you can make streams
unbuffered by running with the
-u
command-line flag or by setting
your
PYTHON
UNBUFFERED
environment variable
to a nonempty value.

To use
-u
in the CGI
world, try using a first line on Unix-like platforms like
#!/usr/bin/python -u
. In
typical usage, output buffering is not usually a factor. On some
servers and clients, though, this may be a resolution for empty
reply pages, or premature end-of-script header errors—the client
may time out before the buffered output stream is sent (though
more commonly, these cases reflect genuine program errors in
your script).

• Are named according to your web server’s conventions (e.g.,
  file.py
  )
  

• Are stored in a directory recognized by your web server
  (e.g.,
  cgi-bin/
  )
  

• Are given executable file permissions if required (e.g.,
  chmod 755 file.py
)
  

• May require the special
  #!
pythonpath
line at the top for some servers
  

• Configure
  sys.path
only
  if needed to see modules in other directories
  

• Use Unix end-of-line conventions if your server rejects DOS
  format
  

• Flush output buffers if required, or to send portions of the
  reply periodically
  

• Especially on Unix systems, you should first assume that
  Python lives in a standard place (e.g.,
  /usr/local/bin/python
  ): type
  python
(or
  which python
) in a shell window and see
  if it works. Chances are that Python already lives on such
  machines. If you have Telnet or SSH access on your server, a Unix
  find
command starting at
  /usr
  may help.
  

• If your server runs Linux, you’re probably set to go. Python
  ships as a standard part of Linux distributions these days, and
  many websites and Internet Service Providers (ISPs) run the Linux
  operating system; at such sites, Python probably already lives at
  /usr/bin/python
  .
  

• In other environments where you cannot control the server
  machine yourself, it may be harder to obtain access to an already
  installed Python. If so, you can relocate your site to a server
  that does have Python installed, talk your ISP into installing
  Python on the machine you’re trying to use, or install Python on
  the server machine yourself.