You are viewing a plain text version of this content. The canonical link for it is here.
Posted to mod_python-commits@quetz.apache.org by gr...@apache.org on 2003/06/30 21:52:59 UTC
cvs commit: httpd-python/Doc modpython1.tex modpython2.tex modpython3.tex modpython4.tex modpython5.tex modpython6.tex
grisha 2003/06/30 12:52:59
Modified: Doc modpython1.tex modpython2.tex modpython3.tex
modpython4.tex modpython5.tex modpython6.tex
Log:
Cleaned up the poblems with double-quotes in Latex, added some indentation
, inserted notation tags and some other clean up stuff.
Revision Changes Path
1.7 +44 -41 httpd-python/Doc/modpython1.tex
Index: modpython1.tex
===================================================================
RCS file: /home/cvs/httpd-python/Doc/modpython1.tex,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- modpython1.tex 22 Aug 2002 21:09:08 -0000 1.6
+++ modpython1.tex 30 Jun 2003 19:52:55 -0000 1.7
@@ -2,15 +2,15 @@
\section{Performance\label{intr-performance}}
-One of the main advantages of mod_python is the increase in
-performance over traditional CGI. Below are results of a very crude
-test. The test was done on a 1.2Ghz Pentium machine running RedHat
-Linux
-7.3. \citetitle[http://httpd.apache.org/docs-2.0/programs/ab.html]{Ab}
-was used to poll 4 kinds of scripts, all of which imported the
-standard cgi module (because this is how a typical Python cgi script
-begins), then output a single word "Hello!". The results are based on
-10000 requests with concurrency of 1.
+ One of the main advantages of mod_python is the increase in
+ performance over traditional CGI. Below are results of a very crude
+ test. The test was done on a 1.2Ghz Pentium machine running RedHat
+ Linux
+ 7.3. \citetitle[http://httpd.apache.org/docs-2.0/programs/ab.html]{Ab}
+ was used to poll 4 kinds of scripts, all of which imported the
+ standard cgi module (because this is how a typical Python cgi script
+ begins), then output a single word \samp{Hello!}. The results are
+ based on 10000 requests with concurrency of 1.
\begin{verbatim}
@@ -23,19 +23,21 @@
\section{Flexibility\label{intr-flexibility}}
-Apache processes requests in phases (e.g. read the request, parse
-headers, check access, etc.). These phases can be implemented by
-functions called handlers. Traditionally, handlers are written in C
-and compiled into Apache modules. Mod_python provides a way to extend
-Apache functionality by writing Apache handlers in Python. For a
-detailed description of the Apache request processing process, see the
-\citetitle[http://dev.apache.org/API.html]{Apache API Notes}, as well
-as the \citetitle[http://www.modpython.org/python10/]{Mod_python -
-Integrating Python with Apache} paper.
-
-To ease migration from CGI, a standard mod_python handler is provided
-that simulates the CGI environment allowing a user to run legacy scripts
-under mod_python with no changes to the code (in most cases).
+ Apache processes requests in phases (e.g. read the request, parse
+ headers, check access, etc.). These phases can be implemented by
+ functions called handlers. Traditionally, handlers are written in C
+ and compiled into Apache modules. Mod_python provides a way to
+ extend Apache functionality by writing Apache handlers in
+ Python. For a detailed description of the Apache request processing
+ process, see the \citetitle[http://dev.apache.org/API.html]{Apache
+ API Notes}, as well as the
+ \citetitle[http://www.modpython.org/python10/]{Mod_python -
+ Integrating Python with Apache} paper.
+
+ To ease migration from CGI, a standard mod_python handler is
+ provided that simulates the CGI environment allowing a user to run
+ legacy scripts under mod_python with no changes to the code (in most
+ cases).
\begin{seealso}
\seeurl{http://dev.apache.org/}{Apache Developer Resources}
@@ -44,16 +46,16 @@
\section{History\label{intr-history}}
-Mod_python originates from a project called
-\citetitle[http://www.ispol.com/home/grisha/httpdapy/]{Httpdapy}
-(1997). For a long time Httpdapy was not called mod_python because
-Httpdapy was not meant to be Apache-specific. Httpdapy was designed to
-be cross-platform and in fact was initially written for the Netscape
-server (back then it was called Nsapy (1997).
-
-This excerpt from the Httpdapy README file describes well the
-challenges and the solution provided by embedding Python within the
-HTTP server:
+ Mod_python originates from a project called
+ \citetitle[http://www.ispol.com/home/grisha/httpdapy/]{Httpdapy}
+ (1997). For a long time Httpdapy was not called mod_python because
+ Httpdapy was not meant to be Apache-specific. Httpdapy was designed
+ to be cross-platform and in fact was initially written for the
+ Netscape server (back then it was called Nsapy (1997).
+
+ This excerpt from the Httpdapy README file describes well the
+ challenges and the solution provided by embedding Python within the
+ HTTP server:
\begin{verbatim}
@@ -89,14 +91,15 @@
\end{verbatim}
-...continuing this saga, yours truly later learned that writing Httpdapy for
-every server is a task a little bigger and less interesting than I
-originally imagined.
-
-Instead, it seemed like providing a Python counterpart to the popular
-Perl Apache extension mod_perl that would give Python users the same
-(or better) capability would be a much more exciting thing to do.
+ ...continuing this saga, yours truly later learned that writing
+ Httpdapy for every server is a task a little bigger and less
+ interesting than I originally imagined.
+
+ Instead, it seemed like providing a Python counterpart to the
+ popular Perl Apache extension mod_perl that would give Python users
+ the same (or better) capability would be a much more exciting thing
+ to do.
-And so it was done. The first release of mod_python happened in May of
-2000.
+ And so it was done. The first release of mod_python happened in May
+ of 2000.
1.14 +146 -194 httpd-python/Doc/modpython2.tex
Index: modpython2.tex
===================================================================
RCS file: /home/cvs/httpd-python/Doc/modpython2.tex,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- modpython2.tex 27 May 2003 16:14:58 -0000 1.13
+++ modpython2.tex 30 Jun 2003 19:52:55 -0000 1.14
@@ -1,18 +1,22 @@
\chapter{Installation\label{installation}}
\indexii{installation}{UNIX}
\indexii{mod_python}{mailing list}
-NOTE: By far the best place to get help with installation and other
-issues is the mod_python mailing list. Please take a moment to join
-the mod_python mailing list by sending an e-mail with the word
-"subscribe" in the subject to \email{mod_python-request@modpython.org}.
+
+\begin{notice}
+ By far the best place to get help with installation and other issues
+ is the mod_python mailing list. Please take a moment to join the
+ mod_python mailing list by sending an e-mail with the word
+ \samp{subscribe} in the subject to
+ \email{mod_python-request@modpython.org}.
+\end{notice}
\section{Prerequisites\label{inst-prerequisites}}
\begin{itemize}
\item
-Python 2.2.1 or later. Earlier versions of Python will not work.
+ Python 2.2.1 or later. Earlier versions of Python will not work.
\item
-Apache 2.0.40 or later (For Apache 1.3.x, use mod_python version 2.7.x).
+ Apache 2.0.40 or later (For Apache 1.3.x, use mod_python version 2.7.x).
\end{itemize}
In order to compile mod_python you will need to have the include files
@@ -23,7 +27,7 @@
sunsite, etc) then chances are, you have just the binaries and not the
sources on your system. Often, the Apache and Python include files and
libraries necessary to compile mod_python are part of separate
-"development" package. If you are not sure whether you have all the
+``development'' package. If you are not sure whether you have all the
necessary files, either compile and install Python and Apache from
source, or refer to the documentation for your system on how to get
the development packages.
@@ -60,52 +64,39 @@
\begin{itemize}
\item
-\index{apxs}
-\indexii{./configure}{\longprogramopt{with-apxs}}
-Finds out whether a program called \program{apxs} is available. This
-program is part of the standard Apache distribution, and is necessary
-for DSO compilation. If apxs cannot be found in your \envvar{PATH} or in
-\filenq{/usr/local/apache/bin}, DSO compilation will not be available.
-
-You can manually specify the location of apxs by using the
-\longprogramopt{with-apxs} option, e.g.:
-
-\begin{verbatim}
-$ ./configure --with-apxs=/usr/local/apache/bin/apxs
-\end{verbatim}
-%$ keep emacs happy
-
-It is strongly recommended that you do specify this option.
-
-%\item
-%\indexii{./configure}{\longprogramopt{with-apache}}
-%Checks for \longprogramopt{with-apache} option. Use this option to
-%tell \program{./configure} where the Apache sources are on your
-%system. The Apache sources are necessary for static compilation. If
-%you do not specify this option, static compilation will not be
-%available. Here is an example:
-
-%\begin{verbatim}
-%$ ./configure --with-apache=../src/apache_1.3.12 --with-apxs=/usr/local/apache/bin/apxs
-%\end{verbatim}
-%%$ keep emacs happy
-
-\item
-\index{libpython.a}
-Checks your Python version and attempts to figure out where
-\program{libpython} is by looking at various parameters compiled into
-your Python binary. By default, it will use the \program{python}
-program found in your \envvar{PATH}.
-
-\indexii{./configure}{\longprogramopt{with-python}} If the fist Python
-binary in the path is not suitable or not the one desired for
-mod_python, you can specify an alternative location with the
-\longprogramopt{with-python} options, e.g:
-
-\begin{verbatim}
-$ ./configure --with-python=/usr/local/bin/python2.2
-\end{verbatim}
-%$ keep emacs happy
+ \index{apxs}
+ \indexii{./configure}{\longprogramopt{with-apxs}}
+ Finds out whether a program called \program{apxs} is available. This
+ program is part of the standard Apache distribution, and is necessary
+ for DSO compilation. If apxs cannot be found in your \envvar{PATH} or in
+ \filenq{/usr/local/apache/bin}, DSO compilation will not be available.
+
+ You can manually specify the location of apxs by using the
+ \longprogramopt{with-apxs} option, e.g.:
+
+ \begin{verbatim}
+ $ ./configure --with-apxs=/usr/local/apache/bin/apxs
+ \end{verbatim}
+ %$ keep emacs happy
+
+ It is recommended that you specify this option.
+
+\item
+ \index{libpython.a}
+ Checks your Python version and attempts to figure out where
+ \program{libpython} is by looking at various parameters compiled into
+ your Python binary. By default, it will use the \program{python}
+ program found in your \envvar{PATH}.
+
+ \indexii{./configure}{\longprogramopt{with-python}} If the fist Python
+ binary in the path is not suitable or not the one desired for
+ mod_python, you can specify an alternative location with the
+ \longprogramopt{with-python} options, e.g:
+
+ \begin{verbatim}
+ $ ./configure --with-python=/usr/local/bin/python2.2
+ \end{verbatim}
+ %$ keep emacs happy
\end{itemize}
@@ -114,29 +105,14 @@
\begin{itemize}
\item
-%If possible, the \program{./configure} script will default to DSO
-%compilation, otherwise, it will default to static. To stay with
-%whatever \program{./configure} decided, simply run
-To start the build process, simply run
-\begin{verbatim}
-$ make
-\end{verbatim}
-%$ emacs happy
-
-%\indexii{make targets}{static}
-%\indexii{make targets}{dso}
-
-%Or, if you would like to be specific, give \program{make} a
-%\programopt{dso} or \programopt{static} target:
-%\begin{verbatim}
-%$ make dso
-%\end{verbatim}
-%%$ emacs happy
-%OR
-%\begin{verbatim}
-%$ make static
-%\end{verbatim}
-%%$
+ %If possible, the \program{./configure} script will default to DSO
+ %compilation, otherwise, it will default to static. To stay with
+ %whatever \program{./configure} decided, simply run
+ To start the build process, simply run
+ \begin{verbatim}
+ $ make
+ \end{verbatim}
+ %$ emacs happy
\end{itemize}
@@ -147,38 +123,38 @@
\begin{itemize}
\item
-This part of the installation needs to be done as root.
-\begin{verbatim}
-$ su
-# make install
-\end{verbatim}
-%$ emacs happy
-
-\begin{itemize}
-
-\item
-%For DSO, this will simply copy the library into your Apache \filenq{libexec}
-This will simply copy the library into your Apache \filenq{libexec}
-directory, where all the other modules are.
-
-%\item
-%For static, it will copy some files into your Apache source tree.
-
-\item
-Lastly, it will install the Python libraries in \filenq{site-packages} and
-compile them.
-
-\end{itemize}
-
-\indexii{make targets}{install_py_lib}
-%\indexii{make targets}{install_static}
-\indexii{make targets}{install_dso}
-\strong{NB:} If you wish to selectively install just the Python libraries
-%the static library or the DSO (which may not always require superuser
-or the DSO (which may not always require superuser
-privileges), you can use the following \program{make} targets:
-\programopt{install_py_lib} and \programopt{install_dso}
-%\programopt{install_static} and \programopt{install_dso}
+ This part of the installation needs to be done as root.
+ \begin{verbatim}
+ $ su
+ # make install
+ \end{verbatim}
+ %$ emacs happy
+
+ \begin{itemize}
+
+ \item
+ %For DSO, this will simply copy the library into your Apache \filenq{libexec}
+ This will simply copy the library into your Apache \filenq{libexec}
+ directory, where all the other modules are.
+
+ %\item
+ %For static, it will copy some files into your Apache source tree.
+
+ \item
+ Lastly, it will install the Python libraries in \filenq{site-packages} and
+ compile them.
+
+ \end{itemize}
+
+ \indexii{make targets}{install_py_lib}
+ %\indexii{make targets}{install_static}
+ \indexii{make targets}{install_dso}
+ \strong{NB:} If you wish to selectively install just the Python libraries
+ %the static library or the DSO (which may not always require superuser
+ or the DSO (which may not always require superuser
+ privileges), you can use the following \program{make} targets:
+ \programopt{install_py_lib} and \programopt{install_dso}
+ %\programopt{install_static} and \programopt{install_dso}
\end{itemize}
@@ -187,43 +163,19 @@
\begin{itemize}
\item
-If you compiled mod_python as a DSO, you will need to tell Apache to
-load the module by adding the following line in the Apache
-configuration file, usually called \filenq{httpd.conf} or
-\filenq{apache.conf}:
-
-\begin{verbatim}
-LoadModule python_module libexec/mod_python.so
-\end{verbatim}
-
-\index{mod_python.so}
-The actual path to \program{mod_python.so} may vary, but make install
-should report at the very end exactly where \program{mod_python.so}
-was placed and how the \code{LoadModule} directive should appear.
-
-%\item
-%If you used the static installation, you now need to recompile Apache:
-
-%\begin{verbatim}
-%$ cd ../src/apache_1.3.12
-%$ ./configure --activate-module=src/modules/python/libpython.a
-%$ make
-%\end{verbatim}
-%%$ emacs happy
-
-%Or, if you prefer the old "Configure" style, edit
-%\filenq{src/Configuration} to have
-
-%\begin{verbatim}
-%AddModule modules/python/libpython.a
-%\end{verbatim}
-%then run
-%\begin{verbatim}
-%$ cd src
-%$ ./Configure
-%$ Make
-%\end{verbatim}
-%%$ emacs happy
+ If you compiled mod_python as a DSO, you will need to tell Apache to
+ load the module by adding the following line in the Apache
+ configuration file, usually called \filenq{httpd.conf} or
+ \filenq{apache.conf}:
+
+ \begin{verbatim}
+ LoadModule python_module libexec/mod_python.so
+ \end{verbatim}
+
+ \index{mod_python.so}
+ The actual path to \program{mod_python.so} may vary, but make install
+ should report at the very end exactly where \program{mod_python.so}
+ was placed and how the \code{LoadModule} directive should appear.
\end{itemize}
@@ -232,57 +184,57 @@
\begin{enumerate}
\item
-Make some directory that would be visible on your web site, for
-example, htdocs/test.
+ Make some directory that would be visible on your web site, for
+ example, htdocs/test.
\item
-Add the following Apache directives, which can appear in either the
-main server configuration file, or \filenq{.htaccess}. If you are
-going to be using the \filenq{.htaccess} file, you will not need the
-\code{<Directory>} tag below (the directory then becomes the one in
-which the \filenq{.htaccess} file is located), and you will need to
-make sure the \code{AllowOverride} directive applicable to this
-directory has at least \code{FileInfo} specified. (The default is
-\code{None}, which will not work.)
-% the above has been verified to be still true for Apache 2.0
+ Add the following Apache directives, which can appear in either the
+ main server configuration file, or \filenq{.htaccess}. If you are
+ going to be using the \filenq{.htaccess} file, you will not need the
+ \code{<Directory>} tag below (the directory then becomes the one in
+ which the \filenq{.htaccess} file is located), and you will need to
+ make sure the \code{AllowOverride} directive applicable to this
+ directory has at least \code{FileInfo} specified. (The default is
+ \code{None}, which will not work.)
+ % the above has been verified to be still true for Apache 2.0
-\begin{verbatim}
-<Directory /some/directory/htdocs/test>
- AddHandler python-program .py
- PythonHandler mptest
- PythonDebug On
-</Directory>
-\end{verbatim}
+ \begin{verbatim}
+ <Directory /some/directory/htdocs/test>
+ AddHandler python-program .py
+ PythonHandler mptest
+ PythonDebug On
+ </Directory>
+ \end{verbatim}
-(Substitute \filenq{/some/directory} above for something applicable to
-your system, usually your Apache ServerRoot)
+ (Substitute \filenq{/some/directory} above for something applicable to
+ your system, usually your Apache ServerRoot)
\item
-At this time, if you made changes to the main configuration file, you
-will need to restart Apache in order for the changes to take effect.
+ At this time, if you made changes to the main configuration file, you
+ will need to restart Apache in order for the changes to take effect.
\item
-Edit \filenq{mptest.py} file in the \filenq{htdocs/test} directory so
-that is has the following lines (be careful when cutting and pasting
-from your browser, you may end up with incorrect indentation and a
-syntax error):
+ Edit \filenq{mptest.py} file in the \filenq{htdocs/test} directory so
+ that is has the following lines (be careful when cutting and pasting
+ from your browser, you may end up with incorrect indentation and a
+ syntax error):
-\begin{verbatim}
-from mod_python import apache
+ \begin{verbatim}
+ from mod_python import apache
-def handler(req):
+ def handler(req):
req.write("Hello World!")
return apache.OK
-\end{verbatim}
+ \end{verbatim}
\item
-Point your browser to the URL referring to the \filenq{mptest.py}; you
-should see \code{"Hello World!"}. If you didn't - refer to the
-troubleshooting section next.
+ Point your browser to the URL referring to the \filenq{mptest.py};
+ you should see \samp{Hello World!}. If you didn't - refer to the
+ troubleshooting section next.
\item
-If everything worked well, move on to Chapter \ref{tutorial},
-\citetitle[tutorial.html]{Tutorial}.
+ If everything worked well, move on to Chapter \ref{tutorial},
+ \citetitle[tutorial.html]{Tutorial}.
\end{enumerate}
@@ -297,24 +249,24 @@
\item Check the server error log file, it may contain useful clues.
\item Try running Apache from the command line in single process mode:
-\begin{verbatim}
- ./httpd -DONE_PROCESS
-\end{verbatim}
-This prevents it from backgrounding itself and may provide some useful
-information.
+ \begin{verbatim}
+ ./httpd -DONE_PROCESS
+ \end{verbatim}
+ This prevents it from backgrounding itself and may provide some useful
+ information.
\item
-Ask on the mod_python list. Make sure to provide specifics such as:
+ Ask on the mod_python list. Make sure to provide specifics such as:
-\begin{itemize}
+ \begin{itemize}
-\item Mod_python version.
-\item Your operating system type, name and version.
-\item Your Python version, and any unusual compilation options.
-\item Your Apache version.
-\item Relevant parts of the Apache config, .htaccess.
-\item Relevant parts of the Python code.
+ \item Mod_python version.
+ \item Your operating system type, name and version.
+ \item Your Python version, and any unusual compilation options.
+ \item Your Apache version.
+ \item Relevant parts of the Apache config, .htaccess.
+ \item Relevant parts of the Python code.
-\end{itemize}
+ \end{itemize}
\end{itemize}
1.14 +203 -200 httpd-python/Doc/modpython3.tex
Index: modpython3.tex
===================================================================
RCS file: /home/cvs/httpd-python/Doc/modpython3.tex,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- modpython3.tex 23 May 2003 12:43:59 -0000 1.13
+++ modpython3.tex 30 Jun 2003 19:52:56 -0000 1.14
@@ -1,16 +1,16 @@
\chapter{Tutorial\label{tutorial}}
\begin{flushright}
-\emph{So how can I make this work?}
+ \emph{So how can I make this work?}
\end{flushright}
\emph{This is a quick guide to getting started with mod_python
-programming once you have it installed. This is \textbf{not} an
-installation manual!}
+ programming once you have it installed. This is \textbf{not} an
+ installation manual!}
\emph{It is also highly recommended to read (at least the top part of)
-Section \ref{pythonapi}, \citetitle[pythonapi.html]{Python API} after
-completing this tutorial.}
+ Section \ref{pythonapi}, \citetitle[pythonapi.html]{Python API} after
+ completing this tutorial.}
\section{A Quick Start with the Publisher Handler\label{tut-pub}}
@@ -21,13 +21,13 @@
tutorial.
The \code{publisher} handler is provided as one of the standard
-mod_python handlers. To get the publisher handler working,
-you will need the following lines in your config:
+mod_python handlers. To get the publisher handler working, you will
+need the following lines in your config:
\begin{verbatim}
-AddHandler python-program .py
-PythonHandler mod_python.publisher
-PythonDebug On
+ AddHandler python-program .py
+ PythonHandler mod_python.publisher
+ PythonDebug On
\end{verbatim}
The following example will demonstrate a simple feedback form. The
@@ -40,70 +40,70 @@
Here is the html for the form:
\begin{verbatim}
-<html>
+ <html>
Please provide feedback below:
<p>
<form action="form.py/email" method="POST">
- Name: <input type="text" name="name"><br>
- Email: <input type="text" name="email"><br>
- Comment: <textarea name="comment" rows=4 cols=20></textarea><br>
- <input type="submit">
+ Name: <input type="text" name="name"><br>
+ Email: <input type="text" name="email"><br>
+ Comment: <textarea name="comment" rows=4 cols=20></textarea><br>
+ <input type="submit">
</form>
-</html>
+ </html>
\end{verbatim}
Note the \code{action} element of the \code{<form>} tag points to
-\code{form.py/email}. We are going to create a file called \filenq{form.py},
-like this:
+\code{form.py/email}. We are going to create a file called
+\filenq{form.py}, like this:
\begin{verbatim}
-import smtplib
+ import smtplib
-WEBMASTER = "webmaster" # webmaster e-mail
-SMTP_SERVER = "localhost" # your SMTP server
+ WEBMASTER = "webmaster" # webmaster e-mail
+ SMTP_SERVER = "localhost" # your SMTP server
-def email(req, name, email, comment):
+ def email(req, name, email, comment):
- # make sure the user provided all the parameters
- if not (name and email and comment):
- return "A required parameter is missing, \
-please go back and correct the error"
+ # make sure the user provided all the parameters
+ if not (name and email and comment):
+ return "A required parameter is missing, \
+ please go back and correct the error"
- # create the message text
- msg = """\
-From: %s
-Subject: feedback
-To: %s
+ # create the message text
+ msg = """\
+ From: %s
+ Subject: feedback
+ To: %s
-I have the following comment:
+ I have the following comment:
-%s
+ %s
-Thank You,
+ Thank You,
-%s
+ %s
-""" % (email, WEBMASTER, comment, name)
+ """ % (email, WEBMASTER, comment, name)
- # send it out
- conn = smtplib.SMTP(SMTP_SERVER)
- conn.sendmail(email, [WEBMASTER], msg)
- conn.quit()
+ # send it out
+ conn = smtplib.SMTP(SMTP_SERVER)
+ conn.sendmail(email, [WEBMASTER], msg)
+ conn.quit()
- # provide feedback to the user
- s = """\
-<html>
+ # provide feedback to the user
+ s = """\
+ <html>
-Dear %s,<br>
+ Dear %s,<br>
-Thank You for your kind comments, we
-will get back to you shortly.
+ Thank You for your kind comments, we
+ will get back to you shortly.
-</html>""" % name
+ </html>""" % name
- return s
+ return s
\end{verbatim}
When the user clicks the Submit button, the publisher handler will
@@ -121,7 +121,7 @@
Even though the Publisher handler simplifies mod_python programming a
grat deal, all the power of mod_python is still available to this
program, since it has access to the request object. You can do all the
-same things you can do with a "native" mod_python handler, e.g. set
+same things you can do with a ``native'' mod_python handler, e.g. set
custom headers via \code{req.headers_out}, return errors by raising
\exception{apache.SERVER_ERROR} exceptions, write or read directly to
and from the client via \method{req.write()} and \method{req.read()},
@@ -173,11 +173,11 @@
Let's pretend we have the following configuration:
\begin{verbatim}
-<Directory /mywebdir>
- AddHandler python-program .py
- PythonHandler myscript
- PythonDebug On
-</Directory>
+ <Directory /mywebdir>
+ AddHandler python-program .py
+ PythonHandler myscript
+ PythonDebug On
+ </Directory>
\end{verbatim}
\strong{NB:} \filenq{/mywebdir} is an absolute physical path.
@@ -187,14 +187,14 @@
this:
\begin{verbatim}
- from mod_python import apache
+ from mod_python import apache
- def handler(req):
+ def handler(req):
- req.content_type = "text/plain"
- req.write("Hello World!")
+ req.content_type = "text/plain"
+ req.write("Hello World!")
- return apache.OK
+ return apache.OK
\end{verbatim}
Here is what's going to happen: The \code{AddHandler} directive tells
@@ -206,98 +206,99 @@
mod_python in case of an Python error to send error output to the
client (in addition to the logs), very useful during development.
-When a request comes in, Apache starts stepping through its
-request processing phases calling handlers in mod_python. The
-mod_python handlers check whether a directive for that handler was
-specified in the configuration. (Remember, it acts as a dispatcher.)
-In our example, no action will be taken by mod_python for
-all handlers except for the generic handler. When we get to the
-generic handler, mod_python will notice \samp{PythonHandler
-myscript} directive and do the following:
+When a request comes in, Apache starts stepping through its request
+processing phases calling handlers in mod_python. The mod_python
+handlers check whether a directive for that handler was specified in
+the configuration. (Remember, it acts as a dispatcher.) In our
+example, no action will be taken by mod_python for all handlers except
+for the generic handler. When we get to the generic handler,
+mod_python will notice \samp{PythonHandler myscript} directive and do
+the following:
\begin{enumerate}
\item
-If not already done, prepend the directory in which the
-\code{PythonHandler} directive was found to \code{sys.path}.
+ If not already done, prepend the directory in which the
+ \code{PythonHandler} directive was found to \code{sys.path}.
\item
-Attempt to import a module by name \code{myscript}. (Note that if
-\code{myscript} was in a subdirectory of the directory where
-\code{PythonHandler} was specified, then the import would not work
-because said subdirectory would not be in the \code{sys.path}. One way
-around this is to use package notation, e.g. \samp{PythonHandler
-subdir.myscript}.)
+ Attempt to import a module by name \code{myscript}. (Note that if
+ \code{myscript} was in a subdirectory of the directory where
+ \code{PythonHandler} was specified, then the import would not work
+ because said subdirectory would not be in the \code{sys.path}. One
+ way around this is to use package notation, e.g. \samp{PythonHandler
+ subdir.myscript}.)
\item
-Look for a function called \code{handler} in \code{myscript}.
+ Look for a function called \code{handler} in \code{myscript}.
\item
-Call the function, passing it a request object. (More on what a
-request object is later)
+ Call the function, passing it a request object. (More on what a
+ request object is later)
\item
-At this point we're inside the script:
+ At this point we're inside the script:
-\begin{itemize}
-
-\item
-\begin{verbatim}
-from mod_python import apache
-\end{verbatim}
-
-This imports the apache module which provides us the interface to
-Apache. With a few rare exceptions, every mod_python program will have
-this line.
-
-\item
-\begin{verbatim}
-def handler(req):
-\end{verbatim}
-
-\index{handler} This is our \dfn{handler} function declaration. It is
-called \code{"handler"} because mod_python takes the name of the
-directive, converts it to lower case and removes the word
-\code{"python"}. Thus \code{"PythonHandler"} becomes
-\code{"handler"}. You could name it something else, and specify it
-explicitly in the directive using \samp{::}. For example, if the
-handler function was called \samp{spam}, then the directive would be
-\samp{PythonHandler myscript::spam}.
-
-Note that a handler must take one argument - the request object. The
-request object is an object that provides all of the information about
-this particular request - such as the IP of client, the headers, the
-URI, etc. The communication back to the client is also done via the
-request object, i.e. there is no "response" object.
-
-\item
-\begin{verbatim}
- req.content_type = "text/plain"
-\end{verbatim}
-
-This sets the content type to \code{"text/plain"}. The default is usually
-\code{"text/html"}, but since our handler doesn't produce any html,
-\code{"text/plain"} is more appropriate.
-
-\item
-\begin{verbatim}
- req.write("Hello World!")
-\end{verbatim}
-
-This writes the \code{"Hello World!"} string to the client. (Did I really
-have to explain this one?)
-
-\item
-\begin{verbatim}
- return apache.OK
-\end{verbatim}
-
-This tells Apache that everything went OK and that the request has
-been processed. If things did not go OK, that line could be return
-\constant{apache.HTTP_INTERNAL_SERVER_ERROR} or return
-\constant{apache.HTTP_FORBIDDEN}. When things do not go OK, Apache
-will log the error and generate an error message for the client.
-\end{itemize}
+ \begin{itemize}
+
+ \item
+ \begin{verbatim}
+ from mod_python import apache
+ \end{verbatim}
+
+ This imports the apache module which provides us the interface to
+ Apache. With a few rare exceptions, every mod_python program will have
+ this line.
+
+ \item
+ \begin{verbatim}
+ def handler(req):
+ \end{verbatim}
+
+ \index{handler} This is our \dfn{handler} function declaration. It
+ is called \samp{handler} because mod_python takes the name of the
+ directive, converts it to lower case and removes the word
+ \samp{python}. Thus \samp{PythonHandler} becomes
+ \samp{handler}. You could name it something else, and specify it
+ explicitly in the directive using \samp{::}. For example, if the
+ handler function was called \samp{spam}, then the directive would
+ be \samp{PythonHandler myscript::spam}.
+
+ Note that a handler must take one argument - the request
+ object. The request object is an object that provides all of the
+ information about this particular request - such as the IP of
+ client, the headers, the URI, etc. The communication back to the
+ client is also done via the request object, i.e. there is no
+ ``response'' object.
+
+ \item
+ \begin{verbatim}
+ req.content_type = "text/plain"
+ \end{verbatim}
+
+ This sets the content type to \samp{text/plain}. The default is usually
+ \samp{text/html}, but since our handler doesn't produce any html,
+ \samp{text/plain} is more appropriate.
+
+ \item
+ \begin{verbatim}
+ req.write("Hello World!")
+ \end{verbatim}
+
+ This writes the \samp{Hello World!} string to the client. (Did I really
+ have to explain this one?)
+
+ \item
+ \begin{verbatim}
+ return apache.OK
+ \end{verbatim}
+
+ This tells Apache that everything went OK and that the request has
+ been processed. If things did not go OK, that line could be return
+ \constant{apache.HTTP_INTERNAL_SERVER_ERROR} or return
+ \constant{apache.HTTP_FORBIDDEN}. When things do not go OK, Apache
+ will log the error and generate an error message for the client.
+ \end{itemize}
\end{enumerate}
\strong{Some food for thought:} If you were paying attention, you
@@ -310,10 +311,10 @@
\samp{http://myserver/mywebdir/montypython.py} would give the exact
same result. The important thing to understand here is that a handler
augments the server behaviour when processing a specific type of file,
-not an individual file.
+not an individual file.
\emph{At this point, if you didn't understand the above paragraph, go
-back and read it again, until you do.}
+ back and read it again, until you do.}
\section{Now something More Complicated - Authentication\label{tut-more-complicated}}
@@ -321,19 +322,19 @@
something more complicated.
Let's say we want to password-protect this directory. We want the
-login to be "spam", and the password to be "eggs".
+login to be \samp{spam}, and the password to be \samp{eggs}.
-First, we need to tell Apache to call our \emph{authentication} handler when
-authentication is needed. We do this by adding the
+First, we need to tell Apache to call our \emph{authentication}
+handler when authentication is needed. We do this by adding the
\code{PythonAuthenHandler}. So now our config looks like this:
\begin{verbatim}
-<Directory /mywebdir>
- AddHandler python-program .py
- PythonHandler myscript
- PythonAuthenHandler myscript
- PythonDebug On
-</Directory>
+ <Directory /mywebdir>
+ AddHandler python-program .py
+ PythonHandler myscript
+ PythonAuthenHandler myscript
+ PythonDebug On
+ </Directory>
\end{verbatim}
Notice that the same script is specified for two different
@@ -346,33 +347,34 @@
looks like this now:
\begin{verbatim}
-<Directory /mywebdir>
- AddHandler python-program .py
- PythonHandler myscript
- PythonAuthenHandler myscript
- PythonDebug On
- AuthType Basic
- AuthName "Restricted Area"
- require valid-user
-</Directory>
+ <Directory /mywebdir>
+ AddHandler python-program .py
+ PythonHandler myscript
+ PythonAuthenHandler myscript
+ PythonDebug On
+ AuthType Basic
+ AuthName "Restricted Area"
+ require valid-user
+ </Directory>
\end{verbatim}
Now we need to write an authentication handler function in
-\file{myscript.py}. A basic authentication handler would look like this:
+\file{myscript.py}. A basic authentication handler would look like
+this:
\begin{verbatim}
-from mod_python import apache
+ from mod_python import apache
-def authenhandler(req):
+ def authenhandler(req):
- user = req.user
- pw = req.get_basic_auth_pw()
+ user = req.user
+ pw = req.get_basic_auth_pw()
- if user == "spam" and pw == "eggs":
- return apache.OK
- else:
- return apache.HTTP_UNAUTHORIZED
+ if user == "spam" and pw == "eggs":
+ return apache.OK
+ else:
+ return apache.HTTP_UNAUTHORIZED
\end{verbatim}
Let's look at this line by line:
@@ -380,53 +382,54 @@
\begin{itemize}
\item
-\begin{verbatim}
-def authenhandler(req):
-\end{verbatim}
-
-This is the handler function declaration. This one is called
-\code{authenhandler} because, as we already described above, mod_python takes
-the name of the directive (\code{PythonAuthenHandler}), drops the word
-"Python" and converts it lower case.
+ \begin{verbatim}
+ def authenhandler(req):
+ \end{verbatim}
+
+ This is the handler function declaration. This one is called
+ \code{authenhandler} because, as we already described above,
+ mod_python takes the name of the directive
+ (\code{PythonAuthenHandler}), drops the word \samp{Python} and converts
+ it lower case.
\item
-\begin{verbatim}
+ \begin{verbatim}
user = req.user
-\end{verbatim}
-
-This is how you obtain the username that the user entered.
+ \end{verbatim}
+
+ This is how you obtain the username that the user entered.
\item
-\begin{verbatim}
+ \begin{verbatim}
pw = req.get_basic_auth_pw()
-\end{verbatim}
-
-This is how we obtain the password. The basic HTTP authentication
-transmits the password in base64 encoded form to make it a little bit
-less obvious. This function decodes the password and returns it as a
-string.
+ \end{verbatim}
+
+ This is how we obtain the password. The basic HTTP authentication
+ transmits the password in base64 encoded form to make it a little
+ bit less obvious. This function decodes the password and returns it
+ as a string.
\item
-\begin{verbatim}
+ \begin{verbatim}
if user == "spam" and pw == "eggs":
- return apache.OK
-\end{verbatim}
+ return apache.OK
+ \end{verbatim}
-We compare the values provided by the user, and if they are what we
-were expecting, we tell Apache to go ahead and proceed by returning
-\constant{apache.OK}. Apache will then consider this phase of the
-request complete, and proceed to the next phase. (Which in this case
-would be \function{handler()} if it's a \code{.py} file).
+ We compare the values provided by the user, and if they are what we
+ were expecting, we tell Apache to go ahead and proceed by returning
+ \constant{apache.OK}. Apache will then consider this phase of the
+ request complete, and proceed to the next phase. (Which in this case
+ would be \function{handler()} if it's a \code{.py} file).
\item
-\begin{verbatim}
+ \begin{verbatim}
else:
- return apache.HTTP_UNAUTHORIZED
-\end{verbatim}
+ return apache.HTTP_UNAUTHORIZED
+ \end{verbatim}
-Else, we tell Apache to return \constant{HTTP_UNAUTHORIZED} to the
-client, which usually causes the browser to pop a dialog box asking
-for username and password.
+ Else, we tell Apache to return \constant{HTTP_UNAUTHORIZED} to the
+ client, which usually causes the browser to pop a dialog box asking
+ for username and password.
\end{itemize}
1.34 +809 -795 httpd-python/Doc/modpython4.tex
Index: modpython4.tex
===================================================================
RCS file: /home/cvs/httpd-python/Doc/modpython4.tex,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- modpython4.tex 24 Jun 2003 04:16:00 -0000 1.33
+++ modpython4.tex 30 Jun 2003 19:52:56 -0000 1.34
@@ -50,7 +50,7 @@
\begin{seealso}
\seetitle[http://www.python.org/doc/current/api/api.html]
- {Python C Language API}{Python C Language API}
+ {Python C Language API}{Python C Language API}
\end{seealso}
\section{Overview of a Request Handler\label{pyapi-handler}}
@@ -73,68 +73,68 @@
\begin{itemize}
\item
-\constant{apache.OK}, meaning this phase of the request was handled by this
-handler and no errors occurred.
+ \constant{apache.OK}, meaning this phase of the request was handled by this
+ handler and no errors occurred.
\item
-\constant{apache.DECLINED}, meaning this handler has not handled this
-phase of the request to completion and Apache needs to look for
-another handler in subsequent modules.
-
+ \constant{apache.DECLINED}, meaning this handler has not handled this
+ phase of the request to completion and Apache needs to look for
+ another handler in subsequent modules.
+
\item
-\constant{apache.\emph{HTTP_ERROR}}, meaning an HTTP error occurred.
-\var{HTTP_ERROR} can be any of the following:
+ \constant{apache.\emph{HTTP_ERROR}}, meaning an HTTP error occurred.
+ \var{HTTP_ERROR} can be any of the following:
-\begin{verbatim}
-HTTP_CONTINUE = 100
-HTTP_SWITCHING_PROTOCOLS = 101
-HTTP_PROCESSING = 102
-HTTP_OK = 200
-HTTP_CREATED = 201
-HTTP_ACCEPTED = 202
-HTTP_NON_AUTHORITATIVE = 203
-HTTP_NO_CONTENT = 204
-HTTP_RESET_CONTENT = 205
-HTTP_PARTIAL_CONTENT = 206
-HTTP_MULTI_STATUS = 207
-HTTP_MULTIPLE_CHOICES = 300
-HTTP_MOVED_PERMANENTLY = 301
-HTTP_MOVED_TEMPORARILY = 302
-HTTP_SEE_OTHER = 303
-HTTP_NOT_MODIFIED = 304
-HTTP_USE_PROXY = 305
-HTTP_TEMPORARY_REDIRECT = 307
-HTTP_BAD_REQUEST = 400
-HTTP_UNAUTHORIZED = 401
-HTTP_PAYMENT_REQUIRED = 402
-HTTP_FORBIDDEN = 403
-HTTP_NOT_FOUND = 404
-HTTP_METHOD_NOT_ALLOWED = 405
-HTTP_NOT_ACCEPTABLE = 406
-HTTP_PROXY_AUTHENTICATION_REQUIRED= 407
-HTTP_REQUEST_TIME_OUT = 408
-HTTP_CONFLICT = 409
-HTTP_GONE = 410
-HTTP_LENGTH_REQUIRED = 411
-HTTP_PRECONDITION_FAILED = 412
-HTTP_REQUEST_ENTITY_TOO_LARGE = 413
-HTTP_REQUEST_URI_TOO_LARGE = 414
-HTTP_UNSUPPORTED_MEDIA_TYPE = 415
-HTTP_RANGE_NOT_SATISFIABLE = 416
-HTTP_EXPECTATION_FAILED = 417
-HTTP_UNPROCESSABLE_ENTITY = 422
-HTTP_LOCKED = 423
-HTTP_FAILED_DEPENDENCY = 424
-HTTP_INTERNAL_SERVER_ERROR = 500
-HTTP_NOT_IMPLEMENTED = 501
-HTTP_BAD_GATEWAY = 502
-HTTP_SERVICE_UNAVAILABLE = 503
-HTTP_GATEWAY_TIME_OUT = 504
-HTTP_VERSION_NOT_SUPPORTED = 505
-HTTP_VARIANT_ALSO_VARIES = 506
-HTTP_INSUFFICIENT_STORAGE = 507
-HTTP_NOT_EXTENDED = 510
-\end{verbatim}
+ \begin{verbatim}
+ HTTP_CONTINUE = 100
+ HTTP_SWITCHING_PROTOCOLS = 101
+ HTTP_PROCESSING = 102
+ HTTP_OK = 200
+ HTTP_CREATED = 201
+ HTTP_ACCEPTED = 202
+ HTTP_NON_AUTHORITATIVE = 203
+ HTTP_NO_CONTENT = 204
+ HTTP_RESET_CONTENT = 205
+ HTTP_PARTIAL_CONTENT = 206
+ HTTP_MULTI_STATUS = 207
+ HTTP_MULTIPLE_CHOICES = 300
+ HTTP_MOVED_PERMANENTLY = 301
+ HTTP_MOVED_TEMPORARILY = 302
+ HTTP_SEE_OTHER = 303
+ HTTP_NOT_MODIFIED = 304
+ HTTP_USE_PROXY = 305
+ HTTP_TEMPORARY_REDIRECT = 307
+ HTTP_BAD_REQUEST = 400
+ HTTP_UNAUTHORIZED = 401
+ HTTP_PAYMENT_REQUIRED = 402
+ HTTP_FORBIDDEN = 403
+ HTTP_NOT_FOUND = 404
+ HTTP_METHOD_NOT_ALLOWED = 405
+ HTTP_NOT_ACCEPTABLE = 406
+ HTTP_PROXY_AUTHENTICATION_REQUIRED= 407
+ HTTP_REQUEST_TIME_OUT = 408
+ HTTP_CONFLICT = 409
+ HTTP_GONE = 410
+ HTTP_LENGTH_REQUIRED = 411
+ HTTP_PRECONDITION_FAILED = 412
+ HTTP_REQUEST_ENTITY_TOO_LARGE = 413
+ HTTP_REQUEST_URI_TOO_LARGE = 414
+ HTTP_UNSUPPORTED_MEDIA_TYPE = 415
+ HTTP_RANGE_NOT_SATISFIABLE = 416
+ HTTP_EXPECTATION_FAILED = 417
+ HTTP_UNPROCESSABLE_ENTITY = 422
+ HTTP_LOCKED = 423
+ HTTP_FAILED_DEPENDENCY = 424
+ HTTP_INTERNAL_SERVER_ERROR = 500
+ HTTP_NOT_IMPLEMENTED = 501
+ HTTP_BAD_GATEWAY = 502
+ HTTP_SERVICE_UNAVAILABLE = 503
+ HTTP_GATEWAY_TIME_OUT = 504
+ HTTP_VERSION_NOT_SUPPORTED = 505
+ HTTP_VARIANT_ALSO_VARIES = 506
+ HTTP_INSUFFICIENT_STORAGE = 507
+ HTTP_NOT_EXTENDED = 510
+ \end{verbatim}
\end{itemize}
@@ -144,29 +144,31 @@
e.g.
\begin{verbatim}
-raise apache.SERVER_RETURN, apache.HTTP_FORBIDDEN
+ raise apache.SERVER_RETURN, apache.HTTP_FORBIDDEN
\end{verbatim}
-
+
Handlers can send content to the client using the \method{req.write()}
method.
Client data, such as POST requests, can be read by using the
\method{req.read()} function.
-\strong{NOTE:} The directory of the Apache \code{Python*Handler}
-directive in effect is prepended to the \code{sys.path}. If the
-directive was specified in a server config file outside any
-\code{<Directory>}, then the directory is unknown and not prepended.
+\begin{notice}
+ The directory of the Apache \code{Python*Handler}
+ directive in effect is prepended to the \code{sys.path}. If the
+ directive was specified in a server config file outside any
+ \code{<Directory>}, then the directory is unknown and not prepended.
+\end{notice}
An example of a minimalistic handler might be:
\begin{verbatim}
-from mod_python import apache
+ from mod_python import apache
-def requesthandler(req):
- req.content_type = "text/plain"
- req.write("Hello World!")
- return apache.OK
+ def requesthandler(req):
+ req.content_type = "text/plain"
+ req.write("Hello World!")
+ return apache.OK
\end{verbatim}
\section{Overview of a Filter Handler\label{pyapi-filter}}
@@ -210,17 +212,17 @@
like:
\begin{verbatim}
-from mod_python import apache
+ from mod_python import apache
-def outputfilter(filter):
+ def outputfilter(filter):
- s = filter.read()
- while s:
- filter.write(s.upper())
- s = filter.read()
+ s = filter.read()
+ while s:
+ filter.write(s.upper())
+ s = filter.read()
- if s is None:
- filter.close()
+ if s is None:
+ filter.close()
\end{verbatim}
@@ -257,20 +259,20 @@
Apache configuration:
\begin{verbatim}
- PythonConnectionHandler echo
+ PythonConnectionHandler echo
\end{verbatim}
Contents of \filenq{echo.py} file:
\begin{verbatim}
-from mod_python import apache
+ from mod_python import apache
-def connectionhandler(conn):
+ def connectionhandler(conn):
- while 1:
- conn.write(conn.readline())
+ while 1:
+ conn.write(conn.readline())
- return apache.OK
+ return apache.OK
\end{verbatim}
\section{\module{apache} -- Access to Apache Internals.}
@@ -294,7 +296,7 @@
It is best imported like this:
\begin{verbatim}
-from mod_python import apache
+ from mod_python import apache
\end{verbatim}
\module{mod_python.apache} module defines the following functions and
@@ -304,128 +306,128 @@
\subsection{Functions\label{pyapi-apmeth}}
\begin{funcdesc}{log_error}{message\optional{, level, server}}
-An interface to the Apache
-\citetitle[http://dev.apache.org/apidoc/apidoc_ap_log_error.html]{ap_log_error()}
-function. \var{message} is a string with the error message, \var{level} is
-one of the following flags constants:
-
-\begin{verbatim}
-APLOG_EMERG
-APLOG_ALERT
-APLOG_CRIT
-APLOG_ERR
-APLOG_WARNING
-APLOG_NOTICE
-APLOG_INFO
-APLOG_DEBUG
-APLOG_NOERRNO
-\end{verbatim}
-
-\var{server} is a reference to a \member{req.server} object. If
-\var{server} is not specified, then the error will be logged to the
-default error log, otherwise it will be written to the error log for
-the appropriate virtual server. When \var{server} is not specified,
-the setting of LogLevel does not apply, the LogLevel is dictated by
-an httpd compile-time default, usually \code{warn}.
-
-If you have a reference to a request object available, consider using
-\method{req.log_error} intead, it will prepend request-specific
-information such as the source IP of the request to the log entry.
+ An interface to the Apache
+ \citetitle[http://dev.apache.org/apidoc/apidoc_ap_log_error.html]{ap_log_error()}
+ function. \var{message} is a string with the error message, \var{level} is
+ one of the following flags constants:
+
+ \begin{verbatim}
+ APLOG_EMERG
+ APLOG_ALERT
+ APLOG_CRIT
+ APLOG_ERR
+ APLOG_WARNING
+ APLOG_NOTICE
+ APLOG_INFO
+ APLOG_DEBUG
+ APLOG_NOERRNO
+ \end{verbatim}
+
+ \var{server} is a reference to a \member{req.server} object. If
+ \var{server} is not specified, then the error will be logged to the
+ default error log, otherwise it will be written to the error log for
+ the appropriate virtual server. When \var{server} is not specified,
+ the setting of LogLevel does not apply, the LogLevel is dictated by
+ an httpd compile-time default, usually \code{warn}.
+
+ If you have a reference to a request object available, consider using
+ \method{req.log_error} intead, it will prepend request-specific
+ information such as the source IP of the request to the log entry.
\end{funcdesc}
\begin{funcdesc}{allow_methods}{\optional{*args}}
-A convenience function to set values in \member{req.allowed}.
-\member{req.allowed} is a bitmask that is used to construct the
-"Allow:" header. It should be set before returning a
-\code{HTTP_NOT_IMPLEMENTED} error.
-
-Arguments can be one or more of the following:
-\begin{verbatim}
-M_GET
-M_PUT
-M_POST
-M_DELETE
-M_CONNECT
-M_OPTIONS
-M_TRACE
-M_PATCH
-M_PROPFIND
-M_PROPPATCH
-M_MKCOL
-M_COPY
-M_MOVE
-M_LOCK
-M_UNLOCK
-M_VERSION_CONTROL
-M_CHECKOUT
-M_UNCHECKOUT
-M_CHECKIN
-M_UPDATE
-M_LABEL
-M_REPORT
-M_MKWORKSPACE
-M_MKACTIVITY
-M_BASELINE_CONTROL
-M_MERGE
-M_INVALID
-\end{verbatim}
+ A convenience function to set values in \member{req.allowed}.
+ \member{req.allowed} is a bitmask that is used to construct the
+ \samp{Allow:} header. It should be set before returning a
+ \code{HTTP_NOT_IMPLEMENTED} error.
+
+ Arguments can be one or more of the following:
+ \begin{verbatim}
+ M_GET
+ M_PUT
+ M_POST
+ M_DELETE
+ M_CONNECT
+ M_OPTIONS
+ M_TRACE
+ M_PATCH
+ M_PROPFIND
+ M_PROPPATCH
+ M_MKCOL
+ M_COPY
+ M_MOVE
+ M_LOCK
+ M_UNLOCK
+ M_VERSION_CONTROL
+ M_CHECKOUT
+ M_UNCHECKOUT
+ M_CHECKIN
+ M_UPDATE
+ M_LABEL
+ M_REPORT
+ M_MKWORKSPACE
+ M_MKACTIVITY
+ M_BASELINE_CONTROL
+ M_MERGE
+ M_INVALID
+ \end{verbatim}
\end{funcdesc}
\begin{funcdesc}{config_tree}{}
-Returns the server-level configuration tree. This tree does not
-include directives from .htaccess files. This is a \emph{copy} of
-the tree, modifying it has no effect on the actual configuration.
+ Returns the server-level configuration tree. This tree does not
+ include directives from .htaccess files. This is a \emph{copy} of
+ the tree, modifying it has no effect on the actual configuration.
\end{funcdesc}
\begin{funcdesc}{server_root}{}
-Returns the value of ServerRoot.
+ Returns the value of ServerRoot.
\end{funcdesc}
\begin{funcdesc}{make_table}{}
-This function is obsolete and is an alias to \class{table} (see below).
+ This function is obsolete and is an alias to \class{table} (see below).
\end{funcdesc}
\subsection{Table Object (mp_table)\obindex{table}\label{pyapi-mptable}}
\index{table}
\begin{classdesc}{table}{\optional{mapping-or-sequence}}
-Returns a new empty object of type \code{mp_table}. See Section
-\ref{pyapi-mptable} for description of the table object. The
-\var{mapping-or-sequence} will be used to provide initial values for
-the table.
-
-The table object is a wrapper around the Apache APR table. The table
-object behaves very much like a dictionary (including the Python 2.2
-features such as support of the \code{in} operator, etc.), with the
-following differences:
-
-\begin{itemize}
-\item
-Both keys and values must be strings.
-\item
-Key lookups are case-insensitive.
-\item
-Duplicate keys are allowed (see \method{add()} below). When there is
-more than one value for a key, a subscript opration returns a list.
-\end{itemize}
-
-Much of the information that Apache uses is stored in tables. For
-example, \member{req.headers_in} and \member{req.headers_out}.
-
-All the tables that mod_python provides inside the request
-object are actual mappings to the Apache structures, so changing the
-Python table also changes the underlying Apache table.
-
-In addition to normal dictionary-like behavior, the table object also
-has the following method:
+ Returns a new empty object of type \code{mp_table}. See Section
+ \ref{pyapi-mptable} for description of the table object. The
+ \var{mapping-or-sequence} will be used to provide initial values for
+ the table.
+
+ The table object is a wrapper around the Apache APR table. The table
+ object behaves very much like a dictionary (including the Python 2.2
+ features such as support of the \code{in} operator, etc.), with the
+ following differences:
+
+ \begin{itemize}
+ \item
+ Both keys and values must be strings.
+ \item
+ Key lookups are case-insensitive.
+ \item
+ Duplicate keys are allowed (see \method{add()} below). When there is
+ more than one value for a key, a subscript opration returns a list.
+ \end{itemize}
+
+ Much of the information that Apache uses is stored in tables. For
+ example, \member{req.headers_in} and \member{req.headers_out}.
+
+ All the tables that mod_python provides inside the request
+ object are actual mappings to the Apache structures, so changing the
+ Python table also changes the underlying Apache table.
+
+ In addition to normal dictionary-like behavior, the table object also
+ has the following method:
+
+ \begin{methoddesc}[table]{add}{key, val}
+ \function{add()} allows for creating duplicate keys, which is useful
+ when multiple headers, such as \code{Set-Cookie:} are required.
+ \end{methoddesc}
-\begin{methoddesc}[table]{add}{key, val}
-\function{add()} allows for creating duplicate keys, which is useful
-when multiple headers, such as \code{Set-Cookie:} are required.
-\end{methoddesc}
-
-\versionadded{3.0}
+ \versionadded{3.0}
\end{classdesc}
\subsection{Request Object\index{request}\label{pyapi-mprequest}}
@@ -440,527 +442,528 @@
\subsubsection{Request Methods\label{pyapi-mprequest-meth}}
\begin{methoddesc}[request]{add_common_vars}{}
-Calls the Apache \cfunction{ap_add_common_vars()} function. After a
-call to this method, \member{req.subprocess_env} will contain a
-lot of CGI information.
+ Calls the Apache \cfunction{ap_add_common_vars()} function. After a
+ call to this method, \member{req.subprocess_env} will contain a
+ lot of CGI information.
\end{methoddesc}
\begin{methoddesc}[request]{add_handler}{htype, handler\optional{, dir}}
-Allows dynamic handler registration. \var{htype} is a string
-containing the name of any of the apache request (but not filter or
-connection) handler directives,
-e.g. \samp{PythonHandler}. \var{handler} is a string containing the
-name of the module and the handler function. Optional \var{dir} is a
-string containing the name of the directory to be added to the
-pythonpath. If no directory is specified, then, if there is already a
-handler of the same type specified, its directory is inherited,
-otherwise the directory of the presently executing handler is used.
-
-A handler added this way only persists throughout the life of the
-request. It is possible to register more handlers while inside the
-handler of the same type. One has to be careful as to not to create an
-infinite loop this way.
-
-Dynamic handler registration is a useful technique that allows the
-code to dynamically decide what will happen next. A typical example
-might be a \code{PythonAuthenHandler} that will assign different
-\code{PythonHandlers} based on the authorization level, something like:
+ Allows dynamic handler registration. \var{htype} is a string
+ containing the name of any of the apache request (but not filter or
+ connection) handler directives,
+ e.g. \samp{PythonHandler}. \var{handler} is a string containing the
+ name of the module and the handler function. Optional \var{dir} is
+ a string containing the name of the directory to be added to the
+ pythonpath. If no directory is specified, then, if there is already
+ a handler of the same type specified, its directory is inherited,
+ otherwise the directory of the presently executing handler is used.
+
+ A handler added this way only persists throughout the life of the
+ request. It is possible to register more handlers while inside the
+ handler of the same type. One has to be careful as to not to create
+ an infinite loop this way.
+
+ Dynamic handler registration is a useful technique that allows the
+ code to dynamically decide what will happen next. A typical example
+ might be a \code{PythonAuthenHandler} that will assign different
+ \code{PythonHandlers} based on the authorization level, something
+ like:
-\begin{verbatim}
-if manager:
+ \begin{verbatim}
+ if manager:
req.add_handler("PythonHandler", "menu::admin")
-else:
+ else:
req.add_handler("PythonHandler", "menu::basic")
-\end{verbatim}
+ \end{verbatim}
-Note: There is no checking being done on the validity of the handler
-name. If you pass this function an invalid handler it will simply be
-ignored.
+ \begin{notice}
+ There is no checking being done on the validity of the handler
+ name. If you pass this function an invalid handler it will simply be
+ ignored.
+ \end{notice}
\end{methoddesc}
\begin{methoddesc}[request]{allow_methods}{methods\optional{, reset}}
-Adds methods to the \member{req.allowed_methods} list. This list
-will be passed in \code{Allowed:} header if
-\constant{HTTP_METHOD_NOT_ALLOWED} or \constant{HTTP_NOT_IMPLEMENTED}
-is returned to the client. Note that Apache doesn't do anything to
-restrict the methods, this list is only used to construct the
-header. The actual method-restricting logic has to be provided in the
-handler code.
+ Adds methods to the \member{req.allowed_methods} list. This list
+ will be passed in \code{Allowed:} header if
+ \constant{HTTP_METHOD_NOT_ALLOWED} or \constant{HTTP_NOT_IMPLEMENTED}
+ is returned to the client. Note that Apache doesn't do anything to
+ restrict the methods, this list is only used to construct the
+ header. The actual method-restricting logic has to be provided in the
+ handler code.
-\var{methods} is a sequence of strings. If \var{reset} is 1, then
-the list of methods is first cleared.
+ \var{methods} is a sequence of strings. If \var{reset} is 1, then
+ the list of methods is first cleared.
\end{methoddesc}
\begin{methoddesc}[request]{document_root}{}
-Returns DocumentRoot setting.
+ Returns DocumentRoot setting.
\end{methoddesc}
\begin{methoddesc}[request]{get_basic_auth_pw}{}
-Returns a string containing the password when Basic authentication is
-used.
+ Returns a string containing the password when Basic authentication is
+ used.
\end{methoddesc}
\begin{methoddesc}[request]{get_config}{}
-Returns a reference to the table object containing the mod_python
-configuration in effect for this request except for
-\code{Python*Handler} and \code{PythonOption} (The latter can be
-obtained via \method{req.get_options()}. The table has directives as
-keys, and their values, if any, as values.
+ Returns a reference to the table object containing the mod_python
+ configuration in effect for this request except for
+ \code{Python*Handler} and \code{PythonOption} (The latter can be
+ obtained via \method{req.get_options()}. The table has directives as
+ keys, and their values, if any, as values.
\end{methoddesc}
\begin{methoddesc}[request]{get_remote_host}{\optional{type, str_is_ip}}
-This method is used to determine remote client's DNS name or IP
-number. The first call to this function may entail a DNS look up, but
-subsequent calls will use the cached result from the first call.
+ This method is used to determine remote client's DNS name or IP
+ number. The first call to this function may entail a DNS look up, but
+ subsequent calls will use the cached result from the first call.
-The optional \var{type} argument can specify the following:
+ The optional \var{type} argument can specify the following:
-\begin{itemize}
+ \begin{itemize}
-\item
-\code{apache.REMOTE_HOST} Look up the DNS name. Return None if Apache
-directive \code{HostNameLookups} is \code{off} or the hostname cannot
-be determined.
-
-\item
-\code{apache.REMOTE_NAME} \emph{(Default)} Return the DNS name if
-possible, or the IP (as a string in dotted decimal notation)
-otherwise.
+ \item
+ \code{apache.REMOTE_HOST} Look up the DNS name. Return None if Apache
+ directive \code{HostNameLookups} is \code{off} or the hostname cannot
+ be determined.
-\item
-\code{apache.REMOTE_NOLOOKUP} Don't perform a DNS lookup, return an
-IP. Note: if a lookup was performed prior to this call, then the
-cached host name is returned.
+ \item
+ \code{apache.REMOTE_NAME} \emph{(Default)} Return the DNS name if
+ possible, or the IP (as a string in dotted decimal notation)
+ otherwise.
-\item
-\code{apache.REMOTE_DOUBLE_REV} Force a double-reverse lookup. On
-failure, return None.
+ \item
+ \code{apache.REMOTE_NOLOOKUP} Don't perform a DNS lookup, return an
+ IP. Note: if a lookup was performed prior to this call, then the
+ cached host name is returned.
-\end{itemize}
+ \item
+ \code{apache.REMOTE_DOUBLE_REV} Force a double-reverse lookup. On
+ failure, return None.
-If \var{str_is_ip} is \code{None} or unspecified, then the return
-value is a string representing the DNS name or IP address.
+ \end{itemize}
-If the optional \var{str_is_ip} argument is not \code{None}, then the
-return value is an \code{(address, str_is_ip)} tuple, where \var{str_is_ip}
-is non-zero if \code{address} is an IP address string.
+ If \var{str_is_ip} is \code{None} or unspecified, then the return
+ value is a string representing the DNS name or IP address.
-On failure, \code{None} is returned.
+ If the optional \var{str_is_ip} argument is not \code{None}, then the
+ return value is an \code{(address, str_is_ip)} tuple, where \var{str_is_ip}
+ is non-zero if \code{address} is an IP address string.
+
+ On failure, \code{None} is returned.
\end{methoddesc}
\begin{methoddesc}[request]{get_options}{}
-Returns a reference to the table object containing the options set by
-the \code{PythonOption} directives.
+ Returns a reference to the table object containing the options set by
+ the \code{PythonOption} directives.
\end{methoddesc}
\begin{methoddesc}[request]{internal_redirect}{new_uri}
-Internally redirects the request to the \var{new_uri}. \var{new_uri}
-must be a string.
+ Internally redirects the request to the \var{new_uri}. \var{new_uri}
+ must be a string.
-The httpd server handles internal redirection by creating a new
-request object and processing all request phases. Within an internal
-redirect, \code{req.prev} will contain a reference to a request object
-from which it was redirected.
+ The httpd server handles internal redirection by creating a new
+ request object and processing all request phases. Within an internal
+ redirect, \code{req.prev} will contain a reference to a request
+ object from which it was redirected.
\end{methoddesc}
\begin{methoddesc}[request]{read}{\optional{len}}
-Reads at most \var{len} bytes directly from the client, returning a
-string with the data read. If the \var{len} argument is negative or
-ommitted, reads all data given by the client.
-
-This function is affected by the \code{Timeout} Apache configuration
-directive. The read will be aborted and an \exception{IOError} raised
-if the \code{Timeout} is reached while reading client data.
-
-This function relies on the client providing the \code{Content-length}
-header. Absense of the \code{Content-length} header will be treated as
-if \code{Content-length: 0} was supplied.
-
-Incorrect \code{Content-length} may cause the function to try to read
-more data than available, which will make the function block until a
-\code{Timeout} is reached.
+ Reads at most \var{len} bytes directly from the client, returning a
+ string with the data read. If the \var{len} argument is negative or
+ ommitted, reads all data given by the client.
+
+ This function is affected by the \code{Timeout} Apache configuration
+ directive. The read will be aborted and an \exception{IOError}
+ raised if the \code{Timeout} is reached while reading client data.
+
+ This function relies on the client providing the \code{Content-length}
+ header. Absense of the \code{Content-length} header will be treated as
+ if \code{Content-length: 0} was supplied.
+
+ Incorrect \code{Content-length} may cause the function to try to read
+ more data than available, which will make the function block until a
+ \code{Timeout} is reached.
\end{methoddesc}
\begin{methoddesc}[request]{readline}{\optional{len}}
-Like \function{read()} but reads until end of line.
-
-Note that in accordance with the HTTP specification, most clients will
-be terminating lines with "\textbackslash r\textbackslash n" rather
-than simply "\textbackslash n".
+ Like \function{read()} but reads until end of line.
+
+ \begin{notice}
+ In accordance with the HTTP specification, most clients will
+ be terminating lines with \samp{\e r\e n} rather
+ than simply \samp{\e n}.
+ \end{notice}
\end{methoddesc}
\begin{methoddesc}[request]{readlines}{\optional{sizehint}}
-Reads all or up to \var{sizehint} bytes of lines using
-\method{readline} and returns a list of the lines read.
+ Reads all or up to \var{sizehint} bytes of lines using
+ \method{readline} and returns a list of the lines read.
\end{methoddesc}
\begin{methoddesc}[request]{register_cleanup}{callable\optional{, data}}
-Registers a cleanup. Argument \var{callable} can be any callable
-object, the optional argument \var{data} can be any object (default is
-\code{None}). At the very end of the request, just before the actual
-request record is destroyed by Apache, \var{callable} will be called
-with one argument, \var{data}.
-
-It is OK to pass the request object as data, but keep in mind that
-when the cleanup is executed, the request processing is already
-complete, so doing things like writing to the client is completely
-pointless.
-
-If errors are encountered during cleanup processing, they should be in
-error log, but otherwise will not affect request processing in any
-way, which makes cleanup bugs sometimes hard to spot.
+ Registers a cleanup. Argument \var{callable} can be any callable
+ object, the optional argument \var{data} can be any object (default is
+ \code{None}). At the very end of the request, just before the actual
+ request record is destroyed by Apache, \var{callable} will be called
+ with one argument, \var{data}.
+
+ It is OK to pass the request object as data, but keep in mind that
+ when the cleanup is executed, the request processing is already
+ complete, so doing things like writing to the client is completely
+ pointless.
+
+ If errors are encountered during cleanup processing, they should be in
+ error log, but otherwise will not affect request processing in any
+ way, which makes cleanup bugs sometimes hard to spot.
-If the server is shut down before the cleanup had a chance to run,
-it's possible that it will not be executed.
+ If the server is shut down before the cleanup had a chance to run,
+ it's possible that it will not be executed.
\end{methoddesc}
\begin{methoddesc}[request]{sendfile}{path\optional{, offset, len}}
-Sends \var{len} bytes of file \var{path} directly to the client,
-starting at offset \var{offset} using the server's internal
-API. \var{offset} defaults to 0, and \var{len} defaults to -1 (send
-the entire file).
+ Sends \var{len} bytes of file \var{path} directly to the client,
+ starting at offset \var{offset} using the server's internal
+ API. \var{offset} defaults to 0, and \var{len} defaults to -1 (send
+ the entire file).
-This function provides the most efficient way to send a file to the
-client.
+ This function provides the most efficient way to send a file to the
+ client.
\end{methoddesc}
\begin{methoddesc}[request]{write}{string}
-Writes \var{string} directly to the client, then flushes the buffer.
+ Writes \var{string} directly to the client, then flushes the buffer.
\end{methoddesc}
\begin{methoddesc}[request]{set_content_length}{len}
-Sets the value of \member{req.clength} and the "Conent-Length" header
-to len. Note that after the headers have been sent out (which happens
-just before the first byte of the body is written, i.e. first call to
-\member{req.write()}), calling the method is meaningless.
+ Sets the value of \member{req.clength} and the \samp{Conent-Length}
+ header to len. Note that after the headers have been sent out (which
+ happens just before the first byte of the body is written,
+ i.e. first call to \member{req.write()}), calling the method is
+ meaningless.
\end{methoddesc}
\subsubsection{Request Members\label{pyapi-mprequest-mem}}
\begin{memberdesc}[request]{connection}
-A \code{connection} object associated with this request. See
-Connection Object below for details.
-\emph{(Read-Only)}
+ A \code{connection} object associated with this request. See
+ Connection Object below for details.
+ \emph{(Read-Only)}
\end{memberdesc}
\begin{memberdesc}[request]{server}
-A server object associate with this request. See Server Object below
-for details.
-\emph{(Read-Only})
+ A server object associate with this request. See Server Object below
+ for details.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{next}
-If this is an internal redirect, the request object we redirect to.
-\emph{(Read-Only})
+ If this is an internal redirect, the request object we redirect to.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{prev}
-If this is an internal redirect, the request object we redirect from.
-\emph{(Read-Only})
+ If this is an internal redirect, the request object we redirect from.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{main}
-If this is a sub-request, pointer to the main request.
-\emph{(Read-Only})
+ If this is a sub-request, pointer to the main request.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{the_request}
-String containing the first line of the request.
-\emph{(Read-Only})
+ String containing the first line of the request.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{assbackwards}
-Is this an HTTP/0.9 "simple" request?
-\emph{(Read-Only})
+ Is this an HTTP/0.9 ``simple'' request?
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{proxyreq}
-A proxy request: one of \constant{apache.PROXYREQ_*} values.
-\emph{(Read-Only})
+ A proxy request: one of \constant{apache.PROXYREQ_*} values.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{header_only}
-A boolean value indicating HEAD request, as opposed to GET.
-\emph{(Read-Only})
+ A boolean value indicating HEAD request, as opposed to GET.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{protocol}
-Protocol, as given by the client, or "HTTP/0.9". Same as CGI \envvar{SERVER_PROTOCOL}.
-\emph{(Read-Only})
+ Protocol, as given by the client, or \samp{HTTP/0.9}. Same as CGI \envvar{SERVER_PROTOCOL}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{proto_num}
-Integer. Number version of protocol; 1.1 = 1001
-\emph{(Read-Only})
+ Integer. Number version of protocol; 1.1 = 1001
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{hostname}
-String. Host, as set by full URI or Host: header.
-\emph{(Read-Only})
+ String. Host, as set by full URI or Host: header.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{request_time}
-A long integer. When request started.
-\emph{(Read-Only})
+ A long integer. When request started.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{status_line}
-Status line. E.g. "200 OK".
-\emph{(Read-Only})
+ Status line. E.g. \samp{200 OK}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{status}
-Status. One of \constant{apache.HTTP_*} values.
+ Status. One of \constant{apache.HTTP_*} values.
\end{memberdesc}
\begin{memberdesc}[request]{method}
-A string containing the method - 'GET', 'HEAD', 'POST', etc.
-Same as CGI \envvar{REQUEST_METHOD}.
-\emph{(Read-Only})
+ A string containing the method - 'GET', 'HEAD', 'POST', etc.
+ Same as CGI \envvar{REQUEST_METHOD}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{method_number}
-Integer containg the method number.
-\emph{(Read-Only})
+ Integer containg the method number.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{allowed}
-Integer. A bitvector of the allowed methods. Used to construct the
-Allowed: header when responding with
-\constant{HTTP_METHOD_NOT_ALLOWED} or
-\constant{HTTP_NOT_IMPLEMENTED}. This field is for Apache's internal
-use, to set the Allowed: methods use \method{req.allow_methods()}
-method, described in section \ref{pyapi-mprequest-meth}.
-\emph{(Read-Only})
+ Integer. A bitvector of the allowed methods. Used to construct the
+ Allowed: header when responding with
+ \constant{HTTP_METHOD_NOT_ALLOWED} or
+ \constant{HTTP_NOT_IMPLEMENTED}. This field is for Apache's internal
+ use, to set the Allowed: methods use \method{req.allow_methods()}
+ method, described in section \ref{pyapi-mprequest-meth}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{allowed_xmethods}
-Tuple. Allowed extension methods.
-\emph{(Read-Only})
+ Tuple. Allowed extension methods.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{allowed_methods}
-Tuple. List of allowed methods. Used in relation with
-\constant{METHOD_NOT_ALLOWED}. This member can be modified via \method{req.allow_methods()}
-described in section \ref{pyapi-mprequest-meth}.
-\emph{(Read-Only})
+ Tuple. List of allowed methods. Used in relation with
+ \constant{METHOD_NOT_ALLOWED}. This member can be modified via \method{req.allow_methods()}
+ described in section \ref{pyapi-mprequest-meth}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{sent_bodyct}
-Integer. Byte count in stream is for body. (?)
-\emph{(Read-Only})
+ Integer. Byte count in stream is for body. (?)
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{bytes_sent}
-Long integer. Number of bytes sent.
-\emph{(Read-Only})
+ Long integer. Number of bytes sent.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{mtime}
-Long integer. Time the resource was last modified.
-\emph{(Read-Only})
+ Long integer. Time the resource was last modified.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{chunked}
-Boolean value indicating when sending chunked transfer-coding.
-\emph{(Read-Only})
+ Boolean value indicating when sending chunked transfer-coding.
+ \emph{(Read-Only})
\end{memberdesc}
-%\begin{memberdesc}[request]{boundary}
-%String. Multipart/byteranges boundary.
-%\emph{(Read-Only})
-%\end{memberdesc}
-
\begin{memberdesc}[request]{range}
-String. The \code{Range:} header.
-\emph{(Read-Only})
+ String. The \code{Range:} header.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{clength}
-Long integer. The "real" content length.
-\emph{(Read-Only})
+ Long integer. The ``real'' content length.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{remaining}
-Long integer. Bytes left to read. (Only makes sense inside a read
-operation.)
-\emph{(Read-Only})
+ Long integer. Bytes left to read. (Only makes sense inside a read
+ operation.)
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{read_length}
-Long integer. Number of bytes read.
-\emph{(Read-Only})
+ Long integer. Number of bytes read.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{read_body}
-Integer. How the request body should be read.
-\emph{(Read-Only})
+ Integer. How the request body should be read.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{read_chunked}
-Boolean. Read chunked transfer coding.
-\emph{(Read-Only})
+ Boolean. Read chunked transfer coding.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{expecting_100}
-Boolean. Is client waiting for a 100 (\constant{HTTP_CONTINUE}) response.
-\emph{(Read-Only})
+ Boolean. Is client waiting for a 100 (\constant{HTTP_CONTINUE}) response.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{headers_in}
-A table object containing headers sent by the client.
+ A table object containing headers sent by the client.
\end{memberdesc}
\begin{memberdesc}[request]{headers_out}
-A \code{table} object representing the headers to be sent to the
-client.
+ A \code{table} object representing the headers to be sent to the
+ client.
\end{memberdesc}
\begin{memberdesc}[request]{err_headers_out}
-These headers get send with the error response, instead of
-headers_out.
+ These headers get send with the error response, instead of
+ headers_out.
\end{memberdesc}
\begin{memberdesc}[request]{subprocess_env}
-A \code{table} object containing environment information typically usable for CGI.
-You may have to call \member{req.add_common_vars()} first to fill in the information
-you need.
+ A \code{table} object containing environment information typically usable for CGI.
+ You may have to call \member{req.add_common_vars()} first to fill in the information
+ you need.
\end{memberdesc}
\begin{memberdesc}[request]{notes}
-A \code{table} object that could be used to store miscellaneous
-general purpose info that lives for as long as the request lives. If
-you need to pass data between handlers, it's better to simply add
-members to the request object than to use \member{notes}.
+ A \code{table} object that could be used to store miscellaneous
+ general purpose info that lives for as long as the request lives. If
+ you need to pass data between handlers, it's better to simply add
+ members to the request object than to use \member{notes}.
\end{memberdesc}
\begin{memberdesc}[request]{phase}
-The phase currently being being processed, e.g. "PythonHandler".
-\emph{(Read-Only)}
+ The phase currently being being processed, e.g. \samp{PythonHandler}.
+ \emph{(Read-Only)}
\end{memberdesc}
\begin{memberdesc}[request]{interpreter}
-The name of the subinterpreter under which we're running.
-\emph{(Read-Only)}
+ The name of the subinterpreter under which we're running.
+ \emph{(Read-Only)}
\end{memberdesc}
\begin{memberdesc}[request]{content_type}
-String. The content type. Mod_python maintains an internal flag
-(\member{req._content_type_set}) to keep track of whether
-\member{content_type} was set manually from within Python. The
-publisher handler uses this flag in the following way: when
-\member{content_type} isn't explicitely set, it attempts to guess the
-content type by examining the first few bytes of the output.
+ String. The content type. Mod_python maintains an internal flag
+ (\member{req._content_type_set}) to keep track of whether
+ \member{content_type} was set manually from within Python. The
+ publisher handler uses this flag in the following way: when
+ \member{content_type} isn't explicitely set, it attempts to guess the
+ content type by examining the first few bytes of the output.
\end{memberdesc}
\begin{memberdesc}[request]{handler}
-The name of the handler currently being processed. This is the handler
-set by mod_mime, not the mod_python handler. In most cases it will be
-"python-program". \emph{(Read-Only})
+ The name of the handler currently being processed. This is the handler
+ set by mod_mime, not the mod_python handler. In most cases it will be
+ "\samp{python-program}. \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{content_encoding}
-String. Content encoding.
-\emph{(Read-Only})
+ String. Content encoding.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{vlist_validator}
-Integer. Variant list validator (if negotiated).
-\emph{(Read-Only})
+ Integer. Variant list validator (if negotiated).
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{user}
-If an authentication check is made, this will hold the user
-name. Same as CGI \envvar{REMOTE_USER}.
-\emph{(Read-Only})
+ If an authentication check is made, this will hold the user
+ name. Same as CGI \envvar{REMOTE_USER}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{ap_auth_type}
-Authentication type. Same as CGI \envvar{AUTH_TYPE}.
-\emph{(Read-Only})
+ Authentication type. Same as CGI \envvar{AUTH_TYPE}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{no_cache}
-Boolean. No cache if true.
-\emph{(Read-Only})
+ Boolean. No cache if true.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{no_local_copy}
-Boolean. No local copy exists.
-\emph{(Read-Only})
+ Boolean. No local copy exists.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{unparsed_uri}
-The URI without any parsing performed.
-\emph{(Read-Only})
+ The URI without any parsing performed.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{uri}
-The path portion of the URI.
-\emph{(Read-Only})
+ The path portion of the URI.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{filename}
-String. File name being requested.
+ String. File name being requested.
\end{memberdesc}
\begin{memberdesc}[request]{canonical_filename}
-String. The true filename (\member{req.filename} is canonicalized if
-they dont match). \emph{(Read-Only)}
+ String. The true filename (\member{req.filename} is canonicalized if
+ they dont match). \emph{(Read-Only)}
\end{memberdesc}
\begin{memberdesc}[request]{path_info}
-String. What follows after the file name, but is before query args, if
-anything. Same as CGI \envvar{PATH_INFO}.
-\emph{(Read-Only})
+ String. What follows after the file name, but is before query args, if
+ anything. Same as CGI \envvar{PATH_INFO}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{args}
-String. Same as CGI \envvar{QUERY_ARGS}.
-\emph{(Read-Only})
+ String. Same as CGI \envvar{QUERY_ARGS}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{finfo}
-Tuple. A file information structure, analogous to POSIX stat,
-describing the file pointed to by the URI. \code{(mode, ino,
-dev, nlink, uid, gid, size, atime, mtime, ctime, fname,
-name)}. The \code{apache} module defines a set of \constant{FINFO_*}
-constants that should be used to access elements of this
-tuple. Example:
-\begin{verbatim}
-fname = req.finfo[apache.FINFO_FNAME]
-\end{verbatim}
-\emph{(Read-Only})
+ Tuple. A file information structure, analogous to POSIX stat,
+ describing the file pointed to by the URI. \code{(mode, ino,
+ dev, nlink, uid, gid, size, atime, mtime, ctime, fname,
+ name)}. The \code{apache} module defines a set of \constant{FINFO_*}
+ constants that should be used to access elements of this
+ tuple. Example:
+ \begin{verbatim}
+ fname = req.finfo[apache.FINFO_FNAME]
+ \end{verbatim}
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{parsed_uri}
-Tuple. The URI broken down into pieces.
-\code{(scheme, hostinfo, user, password, hostname, port, path, query, fragment)}.
-The \code{apache} module defines a set of \constant{URI_*} constants that
-should be used to access elements of this tuple. Example:
-\begin{verbatim}
-fname = req.parsed_uri[apache.URI_PATH]
-\end{verbatim}
-\emph{(Read-Only})
+ Tuple. The URI broken down into pieces.
+ \code{(scheme, hostinfo, user, password, hostname, port, path, query, fragment)}.
+ The \code{apache} module defines a set of \constant{URI_*} constants that
+ should be used to access elements of this tuple. Example:
+ \begin{verbatim}
+ fname = req.parsed_uri[apache.URI_PATH]
+ \end{verbatim}
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{used_path_info}
-Flag to accept or reject path_info on current request.
-\emph{(Read-Only})
+ Flag to accept or reject path_info on current request.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[request]{eos_sent}
-Boolean. EOS bucket sent.
-\emph{(Read-Only})
+ Boolean. EOS bucket sent.
+ \emph{(Read-Only})
\end{memberdesc}
\subsection{Connection Object (mp_conn)\obindex{connection}\label{pyapi-mpconn}}
@@ -971,105 +974,105 @@
\subsubsection{Connection Methods\label{pyapi-mpconn-meth}}
\begin{methoddesc}[connection]{read}{length}
-Reads \var{length} bytes from the connection. The read blocks
-indefinitely until length bytes has been read. If length is -1, keep
-reading until the socket is closed from the other end (This is known
-as \code{EXHAUSTIVE} mode in the http server code).
+ Reads \var{length} bytes from the connection. The read blocks
+ indefinitely until length bytes has been read. If length is -1, keep
+ reading until the socket is closed from the other end (This is known
+ as \code{EXHAUSTIVE} mode in the http server code).
-This method should only be used inside \emph{Connection Handlers}.
+ This method should only be used inside \emph{Connection Handlers}.
\end{methoddesc}
\begin{methoddesc}[connection]{readline}{\optional{length}}
-Reads a line from the connection or up to \var{length} bytes.
+ Reads a line from the connection or up to \var{length} bytes.
-This method should only be used inside \emph{Connection Handlers}.
+ This method should only be used inside \emph{Connection Handlers}.
\end{methoddesc}
\begin{methoddesc}[connection]{write}{string}
-Writes \var{string} to the client.
+ Writes \var{string} to the client.
-This method should only be used inside \emph{Connection Handlers}.
+ This method should only be used inside \emph{Connection Handlers}.
\end{methoddesc}
\subsubsection{Connection Members\label{pyapi-mpconn-mem}}
\begin{memberdesc}[connection]{base_server}
-A \code{server} object for the physical vhost that this connection came in
-through.
-\emph{(Read-Only})
+ A \code{server} object for the physical vhost that this connection came in
+ through.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{local_addr}
-The (address, port) tuple for the server.
-\emph{(Read-Only})
+ The (address, port) tuple for the server.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{remote_addr}
-The (address, port) tuple for the client.
-\emph{(Read-Only})
+ The (address, port) tuple for the client.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{remote_ip}
-String with the IP of the client. Same as CGI \envvar{REMOTE_ADDR}.
-\emph{(Read-Only})
+ String with the IP of the client. Same as CGI \envvar{REMOTE_ADDR}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{remote_host}
-String. The DNS name of the remote client. None if DNS has not been
-checked, "" (empty string) if no name found. Same as CGI \envvar{REMOTE_HOST}.
-\emph{(Read-Only})
+ String. The DNS name of the remote client. None if DNS has not been
+ checked, \code{""} (empty string) if no name found. Same as CGI \envvar{REMOTE_HOST}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{remote_logname}
-Remote name if using RFC1413 (ident). Same as CGI \envvar{REMOTE_IDENT}.
-\emph{(Read-Only})
+ Remote name if using RFC1413 (ident). Same as CGI \envvar{REMOTE_IDENT}.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{aborted}
-Boolean. True is the connection is aborted.
-\emph{(Read-Only})
+ Boolean. True is the connection is aborted.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{keepalive}
-Integer. 1 means the connection will be kept for the next request, 0 means
-"undecided", -1 means fatal error.
-\emph{(Read-Only})
+ Integer. 1 means the connection will be kept for the next request, 0 means
+ ``undecided'', -1 means ``fatal error''.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{double_reverse}
-Ingeter. 1 means double reverse DNS lookup has been performed, 0 means
-not yet, -1 means yes and it failed.
-\emph{(Read-Only})
+ Ingeter. 1 means double reverse DNS lookup has been performed, 0 means
+ not yet, -1 means yes and it failed.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{keepalives}
-The number of times this connection has been used. (?)
-\emph{(Read-Only})
+ The number of times this connection has been used. (?)
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{local_ip}
-String with the IP of the server.
-\emph{(Read-Only})
+ String with the IP of the server.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{local_host}
-DNS name of the server.
-\emph{(Read-Only})
+ DNS name of the server.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{id}
-Long. A unique connection id.
-\emph{(Read-Only})
+ Long. A unique connection id.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[connection]{notes}
-A \code{table} object containing miscellaneous general purpose info that lives for
-as long as the connection lives.
+ A \code{table} object containing miscellaneous general purpose info that lives for
+ as long as the connection lives.
\end{memberdesc}
\subsection{Filter Object (mp_filter)\obindex{filter}\label{pyapi-mpfilt}}
@@ -1081,67 +1084,67 @@
\subsubsection{Filter Methods\label{pyapi-mpfilt-meth}}
\begin{methoddesc}[filter]{pass_on}{}
-Passes all data throught the filter without any processing.
+ Passes all data throught the filter without any processing.
\end{methoddesc}
\begin{methoddesc}[filter]{read}{\optional{length}}
-Reads at most \var{len} bytes from the next filter, returning a string
-with the data read or None if End Of Stream (EOS) has been reached. A
-filter \emph{must} be closed once the EOS has been encountered.
+ Reads at most \var{len} bytes from the next filter, returning a string
+ with the data read or None if End Of Stream (EOS) has been reached. A
+ filter \emph{must} be closed once the EOS has been encountered.
-If the \var{len} argument is negative or ommitted, reads all data
-currently available.
+ If the \var{len} argument is negative or ommitted, reads all data
+ currently available.
\end{methoddesc}
\begin{methoddesc}[filter]{readline}{\optional{length}}
-Reads a line from the next filter or up to \var{length} bytes.
+ Reads a line from the next filter or up to \var{length} bytes.
\end{methoddesc}
\begin{methoddesc}[filter]{write}{string}
-Writes \var{string} to the next filter.
+ Writes \var{string} to the next filter.
\end{methoddesc}
\begin{methoddesc}[filter]{flush}{}
-Flushes the output by sending a FLUSH bucket.
+ Flushes the output by sending a FLUSH bucket.
\end{methoddesc}
\begin{methoddesc}[filter]{close}{}
-Closes the filter and sends an EOS bucket. Any further IO operations on
-this filter will throw an exception.
+ Closes the filter and sends an EOS bucket. Any further IO operations on
+ this filter will throw an exception.
\end{methoddesc}
\begin{methoddesc}[filter]{disable}{}
-Tells mod_python to ignore the provided handler and just pass the data
-on. Used internally by mod_python to print traceback from exceptions
-encountered in filter handlers to avoid an infinite loop.
+ Tells mod_python to ignore the provided handler and just pass the data
+ on. Used internally by mod_python to print traceback from exceptions
+ encountered in filter handlers to avoid an infinite loop.
\end{methoddesc}
\subsubsection{Filter Members\label{pyapi-mpfilt-mem}}
\begin{memberdesc}[filter]{closed}
-A boolean value indicating whether a filter is closed.
-\emph{(Read-Only})
+ A boolean value indicating whether a filter is closed.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[filter]{name}
-String. The name under which this filter is registered.
-\emph{(Read-Only})
+ String. The name under which this filter is registered.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[filter]{req}
-A reference to the request object.
-\emph{(Read-Only})
+ A reference to the request object.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[filter]{is_input}
-Boolean. True if this is an input filter.
-\emph{(Read-Only})
+ Boolean. True if this is an input filter.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[filter]{handler}
-String. The name of the Python handler for this filter as specified in
-the configuration.
-\emph{(Read-Only})
+ String. The name of the Python handler for this filter as specified in
+ the configuration.
+ \emph{(Read-Only})
\end{memberdesc}
\subsection{Server Object (mp_server)\obindex{server}\label{pyapi-mpserver}}
@@ -1153,103 +1156,103 @@
\subsubsection{Server Methods\label{pyapi-mpsrv-meth}}
\begin{methoddesc}[server]{get_options}{}
-Similar to \code{req.get_options()}, but returns a config pointed to
-by \code{server->module_config} Apache config vector.
+ Similar to \code{req.get_options()}, but returns a config pointed to
+ by \code{server->module_config} Apache config vector.
\end{methoddesc}
\begin{methoddesc}[server]{register_cleanup}{request, callable\optional{, data}}
-Registers a cleanup. Very similar to \function{req.register_cleanup()}, except
-this cleanup will be executed at child termination time. This function
-requires one extra argument - the request object.
+ Registers a cleanup. Very similar to \function{req.register_cleanup()}, except
+ this cleanup will be executed at child termination time. This function
+ requires one extra argument - the request object.
\end{methoddesc}
\subsubsection{Server Members\label{pyapi-mpsrv-mem}}
\begin{memberdesc}[server]{defn_name}
-String. The name of the configuration file where the server definition
-was found.
-\emph{(Read-Only})
+ String. The name of the configuration file where the server definition
+ was found.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{defn_line_number}
-Integer. Line number in the config file where the server definition is
-found.
-\emph{(Read-Only})
+ Integer. Line number in the config file where the server definition is
+ found.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{server_admin}
-Value of the \code{ServerAdmin} directive.
-\emph{(Read-Only})
+ Value of the \code{ServerAdmin} directive.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{server_hostname}
-Value of the \code{ServerName} directive. Same as CGI \envvar{SERVER_NAME}.\emph{(Read-Only})
+ Value of the \code{ServerName} directive. Same as CGI \envvar{SERVER_NAME}.\emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{port}
-Integer. TCP/IP port number. Same as CGI \envvar{SERVER_PORT}.
-\emph{This member appears to be 0 on Apache 2.0, look at req.connection.local_addr instead}
-\emph{(Read-Only})
+ Integer. TCP/IP port number. Same as CGI \envvar{SERVER_PORT}.
+ \emph{This member appears to be 0 on Apache 2.0, look at req.connection.local_addr instead}
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{error_fname}
-The name of the error log file for this server, if any.
-\emph{(Read-Only})
+ The name of the error log file for this server, if any.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{loglevel}
-Integer. Logging level.
-\emph{(Read-Only})
+ Integer. Logging level.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{is_virtual}
-Boolean. True if this is a virtual server.
-\emph{(Read-Only})
+ Boolean. True if this is a virtual server.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{timeout}
-Integer. Value of the \code{Timeout} directive.
-\emph{(Read-Only})
+ Integer. Value of the \code{Timeout} directive.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{keep_alive_timeout}
-Integer. Keepalive timeout.
-\emph{(Read-Only})
+ Integer. Keepalive timeout.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{keep_alive_max}
-Maximum number of requests per keepalive.
-\emph{(Read-Only})
+ Maximum number of requests per keepalive.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{keep_alive}
-Use persistent connections?
-\emph{(Read-Only})
+ Use persistent connections?
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{path}
-String. Path for \code{ServerPath}
-\emph{(Read-Only})
+ String. Path for \code{ServerPath}
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{pathlen}
-Integer. Path length.
-\emph{(Read-Only})
+ Integer. Path length.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{limit_req_line}
-Integer. Limit on size of the HTTP request line.
-\emph{(Read-Only})
+ Integer. Limit on size of the HTTP request line.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{limit_req_fieldsize}
-Integer. Limit on size of any request header field.
-\emph{(Read-Only})
+ Integer. Limit on size of any request header field.
+ \emph{(Read-Only})
\end{memberdesc}
\begin{memberdesc}[server]{limit_req_fields}
-Integer. Limit on number of request header fields.
-\emph{(Read-Only})
+ Integer. Limit on number of request header fields.
+ \emph{(Read-Only})
\end{memberdesc}
\section{\module{util} -- Miscellaneous Utilities\label{pyapi-util}}
@@ -1266,13 +1269,13 @@
The recommended way of using this module is:
\begin{verbatim}
-from mod_python import util
+ from mod_python import util
\end{verbatim}
\begin{seealso}
\seetitle[http://CGI-Spec.Golux.Com/]
- {Common Gateway Interface RFC Project Page}
- {for detailed information on the CGI specification}
+ {Common Gateway Interface RFC Project Page}
+ {for detailed information on the CGI specification}
\end{seealso}
\subsection{FieldStorage class\label{pyapi-util-fstor}}
@@ -1282,160 +1285,166 @@
\module{cgi} \class{FieldStorage}.
\begin{classdesc}{FieldStorage}{req\optional{, keep_blank_values, strict_parsing}}
-This class provides uniform access to HTML form data submitted by the
-client. \var{req} is an instance of the mod_python request object.
-
-The optional argument \var{keep_blank_values} is a flag indicating
-whether blank values in URL encoded form data should be treated as
-blank strings. The default is false, which means that blank values are
-ignored as if they were not included.
-
-The optional argument \var{strict_parsing} is not yet implemented.
-
-During initialization, \class{FieldStorage} class reads all of the
-data provided by the client. Since all data provided by the client is
-consumed at this point, there should be no more than one
-\class{FieldStorage} class instantiated per signle request, nor should
-you make any attempts to read client data before or after
-instantiating a \class{FieldStorage}.
-
-The data read from the client is then parsed into separate fields and
-packaged in \class{Field} objects, one per field. For HTML form inputs
-of type \code{file}, a temporary file is created that can later be
-accessed via the \member{file} attribute of a \class{Field} object.
-
-The \class{FieldStorage} class has a mapping object interface, i.e. it
-can be treated like a dictionary. When used as a mapping, the keys are
-form input names, and the returned dictionary value can be:
+ This class provides uniform access to HTML form data submitted by the
+ client. \var{req} is an instance of the mod_python request object.
-\begin{itemize}
-\item
-An instance of \class{StringField}, containing the form input
-value. This is only when there is a single value corresponding to the
-input name. \class{StringField} is a subclass of \class{str} which
-provides the additional \member{value} attribute for compatibility
-with standard library \module{cgi} module.
-\item
-An instances of a \class{Field} class, if the input is a file upload.
-\item
-A list of \class{StringField} and/or \class{Field} objects. This is
-when multiple values exist, such as for a \code{<select>} HTML form
-element.
-\end{itemize}
-
-Note that unlike the standard library \module{cgi} module
-\class{FieldStorage} class, a \class{Field} object is returned
-\emph{only} when it is a file upload. In all other cases an instance
-the return is an instance of \class{StringField}, which is a subclass
-of \class{str}. This means that you do not need to use the
-\member{.value} attribute to access values of fields in most cases.
-
-In addition to standard mapping object methods, \class{FieldStorage} objects
-have the following attributes:
-
-\begin{memberdesc}{list}
-This is a list of \class{Field} objects, one for each input. Multiple
-inputs with the same name will have multiple elements in this list.
-\end{memberdesc}
+ The optional argument \var{keep_blank_values} is a flag indicating
+ whether blank values in URL encoded form data should be treated as
+ blank strings. The default is false, which means that blank values are
+ ignored as if they were not included.
+
+ The optional argument \var{strict_parsing} is not yet implemented.
+
+ During initialization, \class{FieldStorage} class reads all of the
+ data provided by the client. Since all data provided by the client is
+ consumed at this point, there should be no more than one
+ \class{FieldStorage} class instantiated per signle request, nor should
+ you make any attempts to read client data before or after
+ instantiating a \class{FieldStorage}.
+
+ The data read from the client is then parsed into separate fields and
+ packaged in \class{Field} objects, one per field. For HTML form inputs
+ of type \code{file}, a temporary file is created that can later be
+ accessed via the \member{file} attribute of a \class{Field} object.
+
+ The \class{FieldStorage} class has a mapping object interface, i.e. it
+ can be treated like a dictionary. When used as a mapping, the keys are
+ form input names, and the returned dictionary value can be:
+
+ \begin{itemize}
+ \item
+ An instance of \class{StringField}, containing the form input
+ value. This is only when there is a single value corresponding to the
+ input name. \class{StringField} is a subclass of \class{str} which
+ provides the additional \member{value} attribute for compatibility
+ with standard library \module{cgi} module.
+ \item
+ An instances of a \class{Field} class, if the input is a file upload.
+ \item
+ A list of \class{StringField} and/or \class{Field} objects. This is
+ when multiple values exist, such as for a \code{<select>} HTML form
+ element.
+ \end{itemize}
+
+ \begin{notice}
+ Unlike the standard library \module{cgi} module
+ \class{FieldStorage} class, a \class{Field} object is returned
+ \emph{only} when it is a file upload. In all other cases an instance
+ the return is an instance of \class{StringField}, which is a subclass
+ of \class{str}. This means that you do not need to use the
+ \member{.value} attribute to access values of fields in most cases.
+ \end{notice}
+
+ In addition to standard mapping object methods, \class{FieldStorage} objects
+ have the following attributes:
+
+ \begin{memberdesc}{list}
+ This is a list of \class{Field} objects, one for each input. Multiple
+ inputs with the same name will have multiple elements in this list.
+ \end{memberdesc}
\end{classdesc}
\subsection{Field class\label{pyapi-util-fstor-fld}}
\begin{classdesc}{Field}{}
-This class is used internally by \class{FieldStorage} and is not
-meant to be instantiated by the user. Each instance of a \class{Field}
-class represents an HTML Form input.
-
-\class{Field} instances have the following attributes:
-
-\begin{memberdesc}{name}
-The input name.
-\end{memberdesc}
-
-\begin{memberdesc}{value}
-The input value. This attribute can be used to read data from a file
-upload as well, but one has to excercise caution when dealing with
-large files since when accessed via \member{value}, the whole file is
-read into memory.
-\end{memberdesc}
-
-\begin{memberdesc}{file}
-This is a file object. For file uploads it points to a temporary file.
-For simple values, it is a \class{StringIO} object, so you can read
-simple string values via this attribute instead of using the \member{value}
-attribute as well.
-\end{memberdesc}
-
-\begin{memberdesc}{filename}
-The name of the file as provided by the client.
-\end{memberdesc}
-
-\begin{memberdesc}{type}
-The content-type for this input as provided by the client.
-\end{memberdesc}
-
-\begin{memberdesc}{type_opyions}
-This is what follows the actual content type in the \code{content-type}
-header provided by the client, if anything. This is a dictionary.
-\end{memberdesc}
-
-\begin{memberdesc}{disposition}
-The value of the first part of the \code{content-disposition} header.
-\end{memberdesc}
-
-\begin{memberdesc}{disposition_options}
-The second part (if any) of the \code{content-disposition} header in
-the form of a dictionary.
-\end{memberdesc}
-
-\begin{seealso}
-\seerfc{1867}{Form-based File Upload in HTML}{for a description of
-form-based file uploads}
-\end{seealso}
+ This class is used internally by \class{FieldStorage} and is not
+ meant to be instantiated by the user. Each instance of a \class{Field}
+ class represents an HTML Form input.
+
+ \class{Field} instances have the following attributes:
+
+ \begin{memberdesc}{name}
+ The input name.
+ \end{memberdesc}
+
+ \begin{memberdesc}{value}
+ The input value. This attribute can be used to read data from a file
+ upload as well, but one has to excercise caution when dealing with
+ large files since when accessed via \member{value}, the whole file is
+ read into memory.
+ \end{memberdesc}
+
+ \begin{memberdesc}{file}
+ This is a file object. For file uploads it points to a temporary file.
+ For simple values, it is a \class{StringIO} object, so you can read
+ simple string values via this attribute instead of using the \member{value}
+ attribute as well.
+ \end{memberdesc}
+
+ \begin{memberdesc}{filename}
+ The name of the file as provided by the client.
+ \end{memberdesc}
+
+ \begin{memberdesc}{type}
+ The content-type for this input as provided by the client.
+ \end{memberdesc}
+
+ \begin{memberdesc}{type_opyions}
+ This is what follows the actual content type in the \code{content-type}
+ header provided by the client, if anything. This is a dictionary.
+ \end{memberdesc}
+
+ \begin{memberdesc}{disposition}
+ The value of the first part of the \code{content-disposition} header.
+ \end{memberdesc}
+
+ \begin{memberdesc}{disposition_options}
+ The second part (if any) of the \code{content-disposition} header in
+ the form of a dictionary.
+ \end{memberdesc}
+
+ \begin{seealso}
+ \seerfc{1867}{Form-based File Upload in HTML}{for a description of
+ form-based file uploads}
+ \end{seealso}
\end{classdesc}
\subsection{Other functions\label{pyapi-util-funcs}}
\begin{funcdesc}{parse_qs}{qs\optional{, keep_blank_values, strict_parsing}}
-This functnion is functionally equivalent to the standard library
-\module{cgi} \function{parse_qs}, except that it is written in C and is
-much faster.
-
-Parse a query string given as a string argument (data of type
-\mimetype{application/x-www-form-urlencoded}). Data are
-returned as a dictionary. The dictionary keys are the unique query
-variable names and the values are lists of values for each name.
-
-The optional argument \var{keep_blank_values} is a flag indicating
-whether blank values in URL encoded queries should be treated as blank
-strings. A true value indicates that blanks should be retained as
-blank strings. The default false value indicates that blank values
-are to be ignored and treated as if they were not included.
-
-\strong{Note:} The \var{strict_parsing} argument is not yet implemented.
+ This functnion is functionally equivalent to the standard library
+ \module{cgi} \function{parse_qs}, except that it is written in C and is
+ much faster.
+
+ Parse a query string given as a string argument (data of type
+ \mimetype{application/x-www-form-urlencoded}). Data are
+ returned as a dictionary. The dictionary keys are the unique query
+ variable names and the values are lists of values for each name.
+
+ The optional argument \var{keep_blank_values} is a flag indicating
+ whether blank values in URL encoded queries should be treated as blank
+ strings. A true value indicates that blanks should be retained as
+ blank strings. The default false value indicates that blank values
+ are to be ignored and treated as if they were not included.
+
+ \begin{notice}
+ The \var{strict_parsing} argument is not yet implemented.
+ \end{notice}
\end{funcdesc}
\begin{funcdesc}{parse_qsl}{qs\optional{, keep_blank_values, strict_parsing}}
-This functnion is functionally equivalent to the standard library
-\module{cgi} \function{parse_qsl}, except that it is written in C and is
-much faster.
-
-Parse a query string given as a string argument (data of type
-\mimetype{application/x-www-form-urlencoded}). Data are
-returned as a list of name, value pairs.
-
-The optional argument \var{keep_blank_values} is a flag indicating
-whether blank values in URL encoded queries should be treated as blank
-strings. A true value indicates that blanks should be retained as
-blank strings. The default false value indicates that blank values
-are to be ignored and treated as if they were not included.
-
-\strong{Note:} The \var{strict_parsing} argument is not yet implemented.
+ This functnion is functionally equivalent to the standard library
+ \module{cgi} \function{parse_qsl}, except that it is written in C and is
+ much faster.
+
+ Parse a query string given as a string argument (data of type
+ \mimetype{application/x-www-form-urlencoded}). Data are
+ returned as a list of name, value pairs.
+
+ The optional argument \var{keep_blank_values} is a flag indicating
+ whether blank values in URL encoded queries should be treated as blank
+ strings. A true value indicates that blanks should be retained as
+ blank strings. The default false value indicates that blank values
+ are to be ignored and treated as if they were not included.
+
+ \begin{notice}
+ The \var{strict_parsing} argument is not yet implemented.
+ \end{notice}
\end{funcdesc}
@@ -1448,38 +1457,42 @@
parsing, sending and receiving HTTP Cookies, as defined in the
specification published by Netscape.
-Note that even though there are official IETF RFC's describing
-HTTP State Management Mechanism using cookies, the de facto standard
-supported by most browsers is the original Netscape specification.
-Further, true compliance with IETF standards is actually incompatible
-with many popular browsers, even those that claim to be RFC-compliant.
-
-Therefore, this module supports the current common practice, and is not
-fully RFC compliant.
+\begin{notice}
+ Even though there are official IETF RFC's describing HTTP State
+ Management Mechanism using cookies, the de facto standard supported by
+ most browsers is the original Netscape specification. Further, true
+ compliance with IETF standards is actually incompatible with many
+ popular browsers, even those that claim to be RFC-compliant.
+ Therefore, this module supports the current common practice, and is
+ not fully RFC compliant.
+\end{notice}
\begin{seealso}
\seetitle[http://wp.netscape.com/newsref/std/cookie_spec.html]
- {Persistent Client State - HTTP Cookies}{for the original Netscape specification.}
- \seerfc{2109}{HTTP State Management Mechanism}{for the first IETF RFC on Cookies.}
- \seerfc{2964}{Use of HTTP State Management}{for guidelines on using Cookies.}
- \seerfc{2965}{HTTP State Management Mechanism}{for the latest IETF standard.}
- \seetitle[http://arxiv.org/abs/cs.SE/0105018]
- {HTTP Cookies: Standards, Privacy, and Politics}{by David M. Kristol for an
- excellent overview
- of the complications surrounding standardization of Cookies.}
+ {Persistent Client State - HTTP Cookies}{for the original Netscape specification.}
+ \seerfc{2109}{HTTP State Management Mechanism}{for the first RFC on Cookies.}
+ \seerfc{2964}{Use of HTTP State Management}{for guidelines on using Cookies.}
+ \seerfc{2965}{HTTP State Management Mechanism}{for the latest IETF standard.}
+ \seetitle[http://arxiv.org/abs/cs.SE/0105018]
+ {HTTP Cookies: Standards, Privacy, and Politics}{by David M. Kristol for an
+ excellent overview
+ of the issues surrounding standardization of Cookies.}
\end{seealso}
\subsection{Cookie classes\label{pyapi-cookie-classes}}
\begin{classdesc}{Cookie}{name, value\optional{, attributes}}
-This class is used to construct a single cookie named \var{name}
-and having \var{value} as the value. Additionally, any of the
-attributes defined in the Netscape specification and RFC2109 can by
-supplied as keyword arguments.
-
-Note that in the Standard Python Library Cookie module, this type
-of object is referred to as a Morsel.
+ This class is used to construct a single cookie named \var{name}
+ and having \var{value} as the value. Additionally, any of the
+ attributes defined in the Netscape specification and RFC2109 can by
+ supplied as keyword arguments.
+
+ \begin{notice}
+ Unlike the Python Standard Library Cookie classes, this
+ class represents a single cookie (referred to as \dfn{Morsel} in
+ Python Standard Library).
+ \end{notice}
\end{classdesc}
@@ -1504,36 +1517,37 @@
\subsection{PSP Syntax\label{pyapi-psp-syntax}}
-Inside the document, Python \dfn{code} needs to be surrounded by "<\%"
-and "\%>". Python \dfn{expressions} are enclosed in "<\%=" and
-"\%>".
+Inside the document, Python \dfn{code} needs to be surrounded by
+\samp{<\%} and \samp{\%>}. Python \dfn{expressions} are enclosed in
+\samp{<\%=} and \samp{\%>}.
Here is a primitive PSP page that demonstrated use of both code and
expression embedded in an HTML document:
\begin{verbatim}
-<html>
-<%
-import time
-%>
-Hello world, the time is: <%=time.strftime("%Y-%m-%d, %H:%M:%S")%>
-</html>
+ <html>
+ <%
+ import time
+ %>
+ Hello world, the time is: <%=time.strftime("%Y-%m-%d, %H:%M:%S")%>
+ </html>
\end{verbatim}
-The PSP parser would convert the above page into the following Python code:
+Internally, the PSP parser would translate the above page into the
+following Python code:
\begin{verbatim}
-req.write("""<html>
-""")
-import time
-req.write("""
-Hello world, the time is: """); req.write(str(time.strftime("%Y-%m-%d, %H:%M:%S"))); req.write("""
-</html>
-""")
+ req.write("""<html>
+ """)
+ import time
+ req.write("""
+ Hello world, the time is: """); req.write(str(time.strftime("%Y-%m-%d, %H:%M:%S"))); req.write("""
+ </html>
+ """)
\end{verbatim}
This code, when executed inside a handler would result in a page
-displaying words "Hello world, the time is: " followed by current time.
+displaying words \samp{Hello world, the time is: } followed by current time.
Python code can be used to output parts of the page conditionally or
in loops. Blocks are denoted from within Python code by
@@ -1543,54 +1557,54 @@
Here is an example:
\begin{verbatim}
-<html>
-<%
-for n in range(3):
- # This indent will persist
-%>
- <p>This paragraph will be
-repeated 3 times.</p>
-<%
-# This line will cause the block to end
-%>
-This line will only be shown once.<br>
-</html>
+ <html>
+ <%
+ for n in range(3):
+ # This indent will persist
+ %>
+ <p>This paragraph will be
+ repeated 3 times.</p>
+ <%
+ # This line will cause the block to end
+ %>
+ This line will only be shown once.<br>
+ </html>
\end{verbatim}
-The above will be converted to the following Python code:
+The above will be internally translated to the following Python code:
\begin{verbatim}
-req.write("""<html>
-""")
-for n in range(3):
- # This indent will persist
- req.write("""
- <p>This paragraph will be
-repeated 3 times.</p>
-""")
-# This line will cause the block to end
-req.write("""
-This line will only be shown once.<br>
-</html>
-""")
+ req.write("""<html>
+ """)
+ for n in range(3):
+ # This indent will persist
+ req.write("""
+ <p>This paragraph will be
+ repeated 3 times.</p>
+ """)
+ # This line will cause the block to end
+ req.write("""
+ This line will only be shown once.<br>
+ </html>
+ """)
\end{verbatim}
The parser is also smart enough to figure out the indent if the last
-line of Python ends with ":" (colon). Considering this, and that the
-indent is reset when a newline is encountered inside <\% \%>, the
+line of Python ends with \samp{:} (colon). Considering this, and that the
+indent is reset when a newline is encountered inside \samp{<\% \%>}, the
above page can be written as:
\begin{verbatim}
-<html>
-<%
-for n in range(3):
-%>
- <p>This paragraph will be
-repeated 3 times.</p>
-<%
-%>
-This line will only be shown once.<br>
-</html>
+ <html>
+ <%
+ for n in range(3):
+ %>
+ <p>This paragraph will be
+ repeated 3 times.</p>
+ <%
+ %>
+ This line will only be shown once.<br>
+ </html>
\end{verbatim}
However, the above code can be confusing, thus having descriptive
@@ -1600,15 +1614,15 @@
\begin{funcdesc}{parse}{filename}
-This function will open file named \var{filename}, read and parse its
-content and return a string of resulting Python code.
+ This function will open file named \var{filename}, read and parse its
+ content and return a string of resulting Python code.
\end{funcdesc}
\begin{funcdesc}{parsestring}{string}
-This function will parse contents of \var{string} and return a string
-of resulting Python code.
+ This function will parse contents of \var{string} and return a string
+ of resulting Python code.
\end{funcdesc}
1.14 +65 -54 httpd-python/Doc/modpython5.tex
Index: modpython5.tex
===================================================================
RCS file: /home/cvs/httpd-python/Doc/modpython5.tex,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- modpython5.tex 22 May 2003 21:15:03 -0000 1.13
+++ modpython5.tex 30 Jun 2003 19:52:57 -0000 1.14
@@ -45,17 +45,17 @@
Example:
\begin{verbatim}
-PythonAuthzHandler mypackage.mymodule::checkallowed
+ PythonAuthzHandler mypackage.mymodule::checkallowed
\end{verbatim}
For more information on handlers, see Overview of a Handler.
-Side note: The "::" was chosen for performance reasons. In order for
+Side note: The \samp{::} was chosen for performance reasons. In order for
Python to use objects inside modules, the modules first need to be
-imported. Having the separator as simply a ".", would considerably
+imported. Having the separator as simply a \samp{.}, would considerably
complicate process of sequentially evaluating every word to determine
whether it is a package, module, class etc. Using the (admittedly
-un-Python-like) "::" takes the time consuming work of figuring out
+un-Python-like) \samp{::} takes the time consuming work of figuring out
where the module part ends and the object inside of it begins away
from mod_python resulting in a modest performance gain.
@@ -75,7 +75,8 @@
other phases have been processed. This is useful to make decisions
based upon the input header fields.
-NOTE: When this phase of the request is processed, the URI has not yet
+\begin{notice}
+When this phase of the request is processed, the URI has not yet
been translated into a path name, therefore this directive could never
be executed by Apache if it could specified within \code{<Directory>},
\code{<Location>}, \code{<File>} directives or in an \file{.htaccess}
@@ -87,6 +88,7 @@
will be called for \emph{ALL} requests on this server (not just python
programs), which is an important consideration if performance is a
priority.
+\end{notice}
\indexii{phase}{order} The handlers below are documented in order in
which phases are processed by Apache.
@@ -107,13 +109,15 @@
an actual filename, before the server's default rules (Alias
directives and the like) are followed.
-NOTE: At the time when this phase of the request is being processed,
-the URI has not been translated into a path name, therefore this
-directive will never be executed by Apache if specified within
-\code{<Directory>}, \code{<Location>}, \code{<File>} directives or in
-an \file{.htaccess} file. The only place this can be specified is the
-main configuration file, and the code for it will execute in the
-main interpreter.
+\begin{notice}
+ At the time when this phase of the request is being processed, the
+ URI has not been translated into a path name, therefore this
+ directive will never be executed by Apache if specified within
+ \code{<Directory>}, \code{<Location>}, \code{<File>} directives or
+ in an \file{.htaccess} file. The only place this can be specified is
+ the main configuration file, and the code for it will execute in the
+ main interpreter.
+\end{notice}
\subsection{PythonHeaderParserHandler\label{dir-handlers-hph}}
\index{PythonHeaderParserHandler}
@@ -206,19 +210,21 @@
An example authentication handler might look like this:
\begin{verbatim}
-def authenhandler(req):
+ def authenhandler(req):
- pw = req.get_basic_auth_pw()
- user = req.connection.user
- if user == "spam" and pw == "eggs":
- return apache.OK
- else:
- return apache.HTTP_UNAUTHORIZED
+ pw = req.get_basic_auth_pw()
+ user = req.connection.user
+ if user == "spam" and pw == "eggs":
+ return apache.OK
+ else:
+ return apache.HTTP_UNAUTHORIZED
\end{verbatim}
-\strong{Note:} \code{req.get_basic_auth_pw()} must be called prior to using the
-\code{req.connection.user} value. Apache makes no attempt to decode the
-authentication information unless \code{req.get_basic_auth_pw()} is called.
+\begin{notice}
+ \code{req.get_basic_auth_pw()} must be called prior to using the
+ \code{req.connection.user} value. Apache makes no attempt to decode the
+ authentication information unless \code{req.get_basic_auth_pw()} is called.
+\end{notice}
\subsection{PythonAuthzHandler\label{dir-handlers-auh}}
\index{PythonAuthzHandler}
@@ -342,7 +348,7 @@
Registers an input filter \var{handler} under name
\var{name}. \var{Handler} is a module name optionally followed
\code{::} and a callable object name. If callable object name is
-omited, it will default to "inputfilter". \var{Name} is the name under
+omited, it will default to \samp{inputfilter}. \var{Name} is the name under
which the filter is registered, by convention filter names are usually
in all caps.
@@ -361,7 +367,7 @@
Registers an output filter \var{handler} under name
\var{name}. \var{Handler} is a module name optionally followed
\code{::} and a callable object name. If callable object name is
-omited, it will default to "outputfilter". \var{Name} is the name under
+omited, it will default to \samp{outputfilter}. \var{Name} is the name under
which the filter is registered, by convention filter names are usually
in all caps.
@@ -385,7 +391,7 @@
\var{Handler} is a module name optionally followed \code{::} and a
callable object name. If callable object name is omited, it will
-default to "connectionhandler".
+default to \samp{connectionhandler}.
\section{Other Directives\label{dir-other}}
@@ -455,14 +461,16 @@
The import takes place at child process initialization, so the module
will actually be imported once for every child process spawned.
-Note that at the time when the import takes place, the configuration
-is not completely read yet, so all other directives, including
-PythonInterpreter have no effect on the behavior of modules imported
-by this directive. Because of this limitation, the interpreter must be
-specified explicitely, and must match the name under which subsequent
-requests relying on this operation will execute. If you are not sure
-under what interpreter name a request is running, examine the
-\member{interpreter} member of the request object.
+\begin{notice}
+ At the time when the import takes place, the configuration is not
+ completely read yet, so all other directives, including
+ PythonInterpreter have no effect on the behavior of modules imported
+ by this directive. Because of this limitation, the interpreter must
+ be specified explicitely, and must match the name under which
+ subsequent requests relying on this operation will execute. If you
+ are not sure under what interpreter name a request is running,
+ examine the \member{interpreter} member of the request object.
+\end{notice}
See also Multiple Interpreters.
@@ -496,16 +504,18 @@
PythonInterpPerDirectory, there would be two different interpreters,
one for each directory.
-\strong{Note:} In early phases of the request prior to the URI translation
-(PostReadRequestHandler and TransHandler) the path is not yet known
-because the URI has not been translated. During those phases and with
-PythonInterpPerDirectory on, all python code gets executed in the
-main interpreter. This may not be exactly what you want, but
-unfortunately there is no way around this.
+\begin{notice}
+ In early phases of the request prior to the URI translation
+ (PostReadRequestHandler and TransHandler) the path is not yet known
+ because the URI has not been translated. During those phases and
+ with PythonInterpPerDirectory on, all python code gets executed in
+ the main interpreter. This may not be exactly what you want, but
+ unfortunately there is no way around this.
+\end{notice}
\begin{seealso}
- \seetitle[pyapi-interps.html]{Section \ref{pyapi-interps} Multiple Interpreters}
- {for more information}
+ \seetitle[pyapi-interps.html]{Section \ref{pyapi-interps} Multiple Interpreters}
+ {for more information}
\end{seealso}
\subsection{PythonInterpPerDirective\label{dir-other-ipdv}}
@@ -537,8 +547,8 @@
one for each directive.
\begin{seealso}
- \seetitle[pyapi-interps.html]{Section \ref{pyapi-interps} Multiple Interpreters}
- {for more information}
+ \seetitle[pyapi-interps.html]{Section \ref{pyapi-interps} Multiple Interpreters}
+ {for more information}
\end{seealso}
\subsection{PythonInterpreter\label{dir-other-pi}}
@@ -564,8 +574,8 @@
subinterpreter.
\begin{seealso}
- \seetitle[pyapi-interps.html]{Section \ref{pyapi-interps} Multiple Interpreters}
- {for more information}
+ \seetitle[pyapi-interps.html]{Section \ref{pyapi-interps} Multiple Interpreters}
+ {for more information}
\end{seealso}
\subsection{PythonHandlerModule\label{dir-other-phm}}
@@ -587,14 +597,14 @@
For example, instead of:
\begin{verbatim}
-PythonAutenHandler mymodule
-PythonHandler mymodule
-PythonLogHandler mymodule
+ PythonAutenHandler mymodule
+ PythonHandler mymodule
+ PythonLogHandler mymodule
\end{verbatim}
one can simply say
\begin{verbatim}
-PythonHandlerModule mymodule
+ PythonHandlerModule mymodule
\end{verbatim}
\subsection{PythonAutoReload\label{dir-other-par}}
@@ -671,7 +681,7 @@
in Python list notation, e.g.
\begin{verbatim}
-PythonPath "['/usr/local/lib/python2.0', '/usr/local/lib/site_python', '/some/other/place']"
+ PythonPath "['/usr/local/lib/python2.0', '/usr/local/lib/site_python', '/some/other/place']"
\end{verbatim}
The path specified in this directive will replace the path, not add to
@@ -679,7 +689,7 @@
directory to the path, one can specify something like
\begin{verbatim}
-PythonPath "sys.path+['/mydir']"
+ PythonPath "sys.path+['/mydir']"
\end{verbatim}
Mod_python tries to minimize the number of evals associated with the
@@ -692,6 +702,7 @@
taken. Because of this, you should not rely on the directive as a way
to restore the pythonpath to some value if your code changes it.
-Note that this directive should not be used as a security measure
-since the Python path is easily manipulated from within the scripts.
-
+\begin{notice}
+ This directive should not be used as a security measure since the
+ Python path is easily manipulated from within the scripts.
+\end{notice}
1.14 +76 -74 httpd-python/Doc/modpython6.tex
Index: modpython6.tex
===================================================================
RCS file: /home/cvs/httpd-python/Doc/modpython6.tex,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- modpython6.tex 30 May 2003 17:05:16 -0000 1.13
+++ modpython6.tex 30 Jun 2003 19:52:58 -0000 1.14
@@ -10,10 +10,10 @@
To use the handler, you need the following lines in your configuration
\begin{verbatim}
-<Directory /some/path}
+ <Directory /some/path}
SetHandler python-program
PythonHandler mod_python.publisher
-</Directory>
+ </Directory>
\end{verbatim}
This handler allows access to functions and variables within a module
@@ -21,10 +21,10 @@
\file{hello.py}:
\begin{verbatim}
-""" Publisher example """
+ """ Publisher example """
-def say(req, what="NOTHING"):
- return "I am saying %s" % what
+ def say(req, what="NOTHING"):
+ return "I am saying %s" % what
\end{verbatim}
@@ -47,7 +47,8 @@
attribute. Before importing, the file extension, if any, is
discarded.
-If \class{req.filename} is empty, the module name defaults to "index".
+If \class{req.filename} is empty, the module name defaults to
+\samp{index}.
Once module is imported, the remaining part of the URI up to the
beginning of any query data (a.k.a. PATH_INFO) is used to find an
@@ -56,10 +57,10 @@
to Python object within the module.
If no path_info was given in the URL, the Publisher handler will use
-the default value of "index". If the last element is an object inside
+the default value of \samp{index}. If the last element is an object inside
a module, and the one immediately preceeding it is a directory
(i.e. no module name is given), then the module name will also default
-to "index".
+to \samp{index}.
The traversal will stop and \constant{HTTP_NOTFOUND} will be returned to
the client if:
@@ -67,13 +68,13 @@
\begin{itemize}
\item
-Any of the traversed object's names begin with an underscore
-(\samp{\_}). Use underscores to protect objects that should not be
-accessible from the web.
+ Any of the traversed object's names begin with an underscore
+ (\samp{\_}). Use underscores to protect objects that should not be
+ accessible from the web.
\item
-A module is encountered. Published objects cannot be modules for
-security reasons.
+ A module is encountered. Published objects cannot be modules for
+ security reasons.
\end{itemize}
@@ -83,37 +84,37 @@
For eaxmple, given the following configuration:
\begin{verbatim}
-DocumentRoot /some/dir
+ DocumentRoot /some/dir
-<Directory /some/dir>
- SetHandler python-program
- PythonHandler mod_python.publisher
-</Directory>
+ <Directory /some/dir>
+ SetHandler python-program
+ PythonHandler mod_python.publisher
+ </Directory>
\end{verbatim}
And the following \file{/some/dir/index.py} file:
\begin{verbatim}
-def index(req):
+ def index(req):
- return "We are in index()"
+ return "We are in index()"
-def hello(req):
+ def hello(req):
- return "We are in hello()"
+ return "We are in hello()"
\end{verbatim}
Then:
-http://www.somehost/index/index will return "We are in index()"
+http://www.somehost/index/index will return \samp{We are in index()}
-http://www.somehost/index/ will return "We are in index()"
+http://www.somehost/index/ will return \samp{We are in index()}
-http://www.somehost/index/hello will return "We are in hello()"
+http://www.somehost/index/hello will return \samp{We are in hello()}
-http://www.somehost/hello will return "We are in hello()"
+http://www.somehost/hello will return \samp{We are in hello()}
-http://www.somehost/spam will return "404 Not Found"
+http://www.somehost/spam will return \samp{404 Not Found}
\subsubsection{Argument Matching and Invocation\label{hand-pub-alg-args}}
@@ -173,29 +174,29 @@
Similarly to \method{__auth__}, \method{__access__} can be a constant.
-In the example below, only user "eggs" with password "spam" can access
-the \code{hello} function:
+In the example below, only user \samp{eggs} with password \samp{spam}
+can access the \code{hello} function:
\begin{verbatim}
-__auth_realm__ = "Members only"
+ __auth_realm__ = "Members only"
-def __auth__(req, user, passwd):
+ def __auth__(req, user, passwd):
- if user == "eggs" and passwd == "spam" or \
- user == "joe" and passwd == "eoj":
- return 1
- else:
- return 0
-
-def __access__(req, user):
- if user == "eggs":
- return 1
- else:
- return 0
+ if user == "eggs" and passwd == "spam" or \
+ user == "joe" and passwd == "eoj":
+ return 1
+ else:
+ return 0
+
+ def __access__(req, user):
+ if user == "eggs":
+ return 1
+ else:
+ return 0
-def hello(req):
- return "hello"
+ def hello(req):
+ return "hello"
\end{verbatim}
@@ -203,12 +204,12 @@
\begin{verbatim}
-__auth_realm__ = "Members only"
-__auth__ = {"eggs":"spam", "joe":"eoj"}
-__access__ = ["eggs"]
+ __auth_realm__ = "Members only"
+ __auth__ = {"eggs":"spam", "joe":"eoj"}
+ __access__ = ["eggs"]
-def hello(req):
- return "hello"
+ def hello(req):
+ return "hello"
\end{verbatim}
@@ -217,18 +218,18 @@
the function, e.g.:
\begin{verbatim}
-def sensitive(req):
+ def sensitive(req):
- def __auth__(req, user, password):
- if user == 'spam' and password == 'eggs':
- # let them in
- return 1
- else:
- # no access
- return 0
+ def __auth__(req, user, password):
+ if user == 'spam' and password == 'eggs':
+ # let them in
+ return 1
+ else:
+ # no access
+ return 0
- # something involving sensitive information
- return 'sensitive information`
+ # something involving sensitive information
+ return 'sensitive information`
\end{verbatim}
Note that this technique will also work if \code{__auth__} or
@@ -242,14 +243,15 @@
\code{__access__} list to verify that the authenticated user is
allowed to a particular function.
-\strong{NOTE:} In order for mod_python to access \function{__auth__},
+\begin{notice}In order for mod_python to access \function{__auth__},
the module containing it must first be imported. Therefore, any
module-level code will get executed during the import even if
\function{__auth__} is false. To truly protect a module from
being accessed, use other authentication mechanisms, e.g. the Apache
\code{mod_auth} or with a mod_python \citetitle[dir-handlers-auh.html]
-{PythonAuthenHandler} handler.
-
+ {PythonAuthenHandler} handler.
+\end{notice}
+
\subsection{Form Data}
In the process of matching arguments, the Publisher handler creates an
@@ -274,8 +276,8 @@
To use it, simply add this to your httpd configuration:
\begin{verbatim}
-AddHandler python-program .psp
-PythonHandler mod_python.psp
+ AddHandler python-program .psp
+ PythonHandler mod_python.psp
\end{verbatim}
\section{CGI Handler\label{hand-cgi}}
@@ -284,14 +286,14 @@
CGI handler is a handler that emulates the CGI environment under mod_python.
-Note that this is not a "true" CGI environment in that it is emulated
-at the Python level. \code{stdin} and \code{stdout} are provided by
-substituting \code{sys.stdin} and \code{sys.stdout}, and the environment
-is replaced by a dictionary. The implication is that any outside programs
-called from within this environment via \code{os.system}, etc. will
-not see the environment available to the Python program, nor will they
-be able to read/write from standard input/output with the results expected
-in a "true" CGI environment.
+Note that this is not a \samp{true} CGI environment in that it is
+emulated at the Python level. \code{stdin} and \code{stdout} are
+provided by substituting \code{sys.stdin} and \code{sys.stdout}, and
+the environment is replaced by a dictionary. The implication is that
+any outside programs called from within this environment via
+\code{os.system}, etc. will not see the environment available to the
+Python program, nor will they be able to read/write from standard
+input/output with the results expected in a \samp{true} CGI environment.
The handler is provided as a stepping stone for the migration of
legacy code away from CGI. It is not recommended that you settle on
@@ -305,8 +307,8 @@
To use it, simply add this to your \file{.htaccess} file:
\begin{verbatim}
-SetHandler python-program
-PythonHandler mod_python.cgihandler
+ SetHandler python-program
+ PythonHandler mod_python.cgihandler
\end{verbatim}
As of version 2.7, the cgihandler will properly reload even indirectly