svn commit: r472056 - /httpd/mod_python/trunk/Doc/modpython4.tex

[gr...@apache.org]

Author: grahamd
Date: Tue Nov  7 02:34:25 2006
New Revision: 472056

URL: http://svn.apache.org/viewvc?view=rev&rev=472056
Log:
(MODPYTHON-143) Minimal documentation on some, but not all, changes to the
apache.import_module() function. Also corrections to documentation of
request objects functions for registering handlers and filters.


Modified:
    httpd/mod_python/trunk/Doc/modpython4.tex

Modified: httpd/mod_python/trunk/Doc/modpython4.tex
URL: http://svn.apache.org/viewvc/httpd/mod_python/trunk/Doc/modpython4.tex?view=diff&rev=472056&r1=472055&r2=472056
==============================================================================
--- httpd/mod_python/trunk/Doc/modpython4.tex (original)
+++ httpd/mod_python/trunk/Doc/modpython4.tex Tue Nov  7 02:34:25 2006
@@ -346,7 +346,7 @@
   information such as the source IP of the request to the log entry.
 \end{funcdesc}
 
-\begin{funcdesc}{import_module}{module_name\optional{, autoreload=1, log=0, path=None}}
+\begin{funcdesc}{import_module}{module_name\optional{, autoreload=None, log=None, path=None}}
   This function can be used to import modules taking advantage of
   mod_python's internal mechanism which reloads modules automatically
   if they have changed since last import. 
@@ -362,8 +362,31 @@
 
   \begin{verbatim}
     from mod_python import apache
-    mymodule = apache.import_module('mymodule', log=1)
+    mymodule = apache.import_module('mymodule')
   \end{verbatim}
+
+  Note that as of mod_python 3.3, only Python modules contained in a single
+  file are candidates for automatic module reloading. Python packages will
+  never be reloaded. The default arguments for the \var{autoreload} and
+  \var{log} arguments have also been changed to \code{None}, with the
+  arguments effectively now being unnecessary except in exceptional
+  circumstances. When the arguments are left as the default of \code{None},
+  the Apache configuration in scope at the time of the call will always be
+  consulted automatically for any settings for the \code{PythonAutoReload}
+  and \code{PythonDebug} directives.
+
+  With the introduction of mod_python 3.3, the \var{module_name} argument
+  may also now be an absolute path name of an actual Python module
+  contained in a single file. For example:
+
+  \begin{verbatim}
+    from mod_python import apache
+    import os
+    here = os.path.dirname(__file__)
+    path = os.path.join(here, 'mymodule.py')
+    mymodule = apache.import_module(path)
+  \end{verbatim}
+
 \end{funcdesc}
 
 \begin{funcdesc}{allow_methods}{\optional{*args}}
@@ -562,19 +585,15 @@
   connection) handler directives,
   e.g. \samp{PythonHandler}. \var{handler} is a string containing the
   name of the module and the handler function, or the callable object
-  itself.  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. If there is a \code{PythonPath} directive in effect, then
-  \code{sys.path} will be set exactly according to it (no directories
-  added, the \var{dir} argument is ignored).
-  
+  itself. Optional \var{dir} is a string containing the name of the
+  directory to be added to the module search path when looking for the
+  handler. If no directory is specified, then the directory to search
+  in is inherited from the handler which is making the registration,
+
   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.
+  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
@@ -873,10 +892,8 @@
   is a string which would then subsequently be used to identify the filter.
   \var{filter} is a string containing the name of the module and the filter
   function or the callable object itself.  Optional \var{dir} is a string
-  containing the name of the directory to be added to the pythonpath. If
-  there is a \code{PythonPath} directive in effect, then \code{sys.path}
-  will be set exactly according to it (no directories added, the \var{dir}
-  argument is ignored).
+  containing the name of the directory to be added to the module search when
+  looking for the module.
 
   The registration of the filter this way only persists for the life of the
   request. To actually add the filter into the chain of input filters for
@@ -890,10 +907,8 @@
   is a string which would then subsequently be used to identify the filter.
   \var{filter} is a string containing the name of the module and the filter
   function or the callable object itself. Optional \var{dir} is a string
-  containing the name of the directory to be added to the pythonpath. If
-  there is a \code{PythonPath} directive in effect, then \code{sys.path}
-  will be set exactly according to it (no directories added, the \var{dir}
-  argument is ignored).
+  containing the name of the directory to be added to the module search
+  path when looking for the handler.
 
   The registration of the filter this way only persists for the life of the
   request. To actually add the filter into the chain of output filters for