« back to all changes in this revision
Viewing changes to Doc/modpython4.tex
- browse files at revision 12
- compare with another revision
- download diff
- download tarball
- view history from revision 12
- Committer: Bazaar Package Importer
- Author(s): Piotr Ożarowski
- Date: 2007-04-12 20:52:05 UTC
- mfrom: (1.2.4 upstream) (1.1.2 etch)
- Revision ID: james.westby@ubuntu.com-20070412205205-j4qlsw3o4tl615iq
Tags: 3.3.1-1
* New upstream release
* Remove configure and mod_python.h files in clean rule to make the diff.gz
file smaller
* Current Python version in libapache2-mod-pythonX.Y package name (Provides:
field) filled in automatically.
* Added XS-Vcs-Browser field
* Remove configure and mod_python.h files in clean rule to make the diff.gz
file smaller
* Current Python version in libapache2-mod-pythonX.Y package name (Provides:
field) filled in automatically.
* Added XS-Vcs-Browser field
- files added:
- Doc/modpython7.tex
- files removed:
- doc-html/blank.gif
- files modified:
- CREDITS
added
removed
Doc/modpython4.tex
346
346
information such as the source IP of the request to the log entry.
347
347
\end{funcdesc}
348
348
349
\begin{funcdesc}{import_module}{module_name\optional{, autoreload=1, log=0, path=None}}
350
This function can be used to import modules taking advantage of
351
mod_python's internal mechanism which reloads modules automatically
352
if they have changed since last import.
353
354
\var{module_name} is a string containing the module name (it can
355
contain dots, e.g. \code{mypackage.mymodule}); \var{autoreload}
356
indicates whether the module should be reloaded if it has changed since
357
last import; when \var{log} is true, a message will be written to
358
the logs when a module is reloaded; \var{path} allows restricting
359
modules to specific paths.
349
\begin{funcdesc}{import_module}{module_name\optional{, autoreload=None, log=None, path=None}}
350
This function can be used to import modules.
351
352
\begin{notice}
353
This function and the module importer were completely reimplemented in
354
mod_python 3.3. If you are using an older version of mod_python do not
355
rely on this documentation and instead refer to the documentation for
356
the specific version you are using as the new importer does not behave
357
exactly the same and has additional features.
358
359
If you are trying to port code from an older version of mod_python to
360
mod_python 3.3 and can't work out why the new importer is not working
361
for you, you can enable the old module importer for specific Python
362
interpreter instances by using:
363
364
\begin{verbatim}
365
PythonOption mod_python.legacy.importer name
366
\end{verbatim}
367
368
where 'name' is the name of the interpreter instance or '*' for it to
369
be applied to all interpreter instances. This option should be placed
370
at global context within the main Apache configuration files.
371
\end{notice}
372
373
When using the \code{apache.import_module()} function, the
374
\var{module_name} should be a string containing either the module name,
375
or a path to the actual code file for the module; where a module is a
376
candidate for automatic module reloading, \var{autoreload} indicates
377
whether the module should be reloaded if it has changed since the last
378
import; when \var{log} is true, a message will be written to the logs
379
when a module is reloaded; \var{path} can be a list specifying additional
380
directories to be searched for modules.
381
382
With the introduction of mod_python 3.3, the default arguments for the
383
\var{autoreload} and \var{log} arguments have been changed to
384
\code{None}, with the arguments effectively now being unnecessary except
385
in special circumstances. When the arguments are left as the default of
386
\code{None}, the Apache configuration in scope at the time of the call
387
will always be consulted automatically for any settings for the
388
\code{PythonAutoReload} and \code{PythonDebug} directives respectively.
360
389
361
390
Example:
362
391
363
392
\begin{verbatim}
364
393
from mod_python import apache
365
mymodule = apache.import_module('mymodule', log=1)
366
\end{verbatim}
394
module = apache.import_module('module_name')
395
\end{verbatim}
396
397
The \code{apache.import_module()} function is not just a wrapper for the
398
standard Python module import mechanism. The purpose of the function and
399
the mod_python module importer in general, is to provide a means of being
400
able to import modules based on their exact location, with modules being
401
distinguished based on their location rather than just the name of the
402
module. Distinguishing modules in this way, rather than by name alone,
403
means that the same module name can be used for handlers and other code
404
in multiple directories and they will not interfere with each other.
405
406
A secondary feature of the module importer is to implement a means of
407
having modules automatically reloaded when the corresponding code file
408
has been changed on disk. Having modules be able to be reloaded in this
409
way means that it is possible to change the code for a web application
410
without having to restart the whole Apache web server. Although this was
411
always the intent of the module importer, prior to mod_python 3.3, its
412
effectiveness was limited. With mod_python 3.3 however, the module
413
reloading feature is much more robust and will correctly reload parent
414
modules even when it was only a child module what was changed.
415
416
When the \code{apache.import_module()} function is called with just the
417
name of the module, as opposed to a path to the actual code file for the
418
module, a search has to be made for the module. The first set of
419
directories that will be checked are those specified by the \var{path}
420
argument if supplied.
421
422
Where the function is called from another module which had previously
423
been imported by the mod_python importer, the next directory which will
424
be checked will be the same directory as the parent module is located.
425
Where that same parent module contains a global data variable called
426
\code{__mp_path__} containing a list of directories, those directories
427
will also be searched.
428
429
Finally, the mod_python module importer will search directories
430
specified by the \code{PythonOption} called \code{mod_python.importer.path}.
431
432
For example:
433
434
\begin{verbatim}
435
PythonOption mod_python.importer.path "['/some/path']"
436
\end{verbatim}
437
438
The argument to the option must be in the form of a Python list. The
439
enclosing quotes are to ensure that Apache interprets the argument as a
440
single value. The list must be self contained and cannot reference any
441
prior value of the option. The list MUST NOT reference \code{sys.path}
442
nor should any directory which also appears in \code{sys.path} be
443
listed in the mod_python module importer search path.
444
445
When searching for the module, a check is made for any code file with the
446
name specified and having a '.py' extension. Because only modules
447
implemented as a single file will be found, packages will not be found
448
nor modules contained within a package.
449
450
In any case where a module cannot be found, control is handed off to the
451
standard Python module importer which will attempt to find the module or
452
package by searching \code{sys.path}.
453
454
Note that only modules found by the mod_python module importer are
455
candidates for automatic module reloading. That is, where the mod_python
456
module importer could not find a module and handed the search off to the
457
standard Python module importer, those modules or packages will not be
458
able to be reloaded.
459
460
Although true Python packages are not candidates for reloading and must
461
be located in a directory listed in \code{sys.path}, another form of
462
packaging up modules such that they can be maintained within their own
463
namespace is supported. When this mechanism is used, these modules will
464
be candidates for reloading when found by the mod_python module importer.
465
466
In this scheme for maintaining a pseudo package, individual modules are
467
still placed into a directory, but the \code{__init__.py} file in the
468
directory has no special meaning and will not be automatically imported
469
as is the case with true Python packages. Instead, any module within the
470
directory must always be explicitly identified when performing an import.
471
472
To import a named module contained within these pseudo packages, rather
473
than using a '.' to distinguish a sub module from the parent, a '/' is
474
used instead. For example:
475
476
\begin{verbatim}
477
from mod_python import apache
478
module = apache.import_module('dirname/module_name')
479
\end{verbatim}
480
481
If an \code{__init__.py} file is present and it was necessary to import
482
it to achieve the same result as importing the root of a true Python
483
package, then \code{__init__} can be used as the module name. For example:
484
485
\begin{verbatim}
486
from mod_python import apache
487
module = apache.import_module('dirname/__init__')
488
\end{verbatim}
489
490
As a true Python package is not being used, if a module in the directory
491
needs to refer to another module in the same directory, it should use
492
just its name, it should not use any form of dotted path name via the
493
root of the package as would be the case for true Python packages.
494
Modules in subdirectories can be imported by using a '/' separated path
495
where the first part of the path is the name of the subdirectory.
496
497
As a new feature in mod_python 3.3, when using the standard Python
498
'import' statement to import a module, if the import is being done from a
499
module which was previously imported by the mod_python module importer,
500
it is equivalent to having called \code{apache.import_module()} directly.
501
502
For example:
503
504
\begin{verbatim}
505
import name
506
\end{verbatim}
507
508
is equivalent to:
509
510
\begin{verbatim}
511
from mod_python import apache
512
name = apache.import_module('name')
513
\end{verbatim}
514
515
It is also possible to use constructs such as:
516
517
\begin{verbatim}
518
import name as module
519
\end{verbatim}
520
521
and:
522
523
\begin{verbatim}
524
from name import value
525
\end{verbatim}
526
527
Although the 'import' statement is used, that it maps through to the
528
\code{apache.import_module()} function ensures that parent/child
529
relationships are maintained correctly and reloading of a parent will
530
still work when only the child has been changed. It also ensures that one
531
will not end up with modules which were separately imported by the
532
mod_python module importer and the standard Python module importer.
533
534
With the reimplementation of the module importer in mod_python 3.3, the
535
\var{module_name} argument may also now be an absolute path name of an
536
actual Python module contained in a single file. On Windows, a drive
537
letter can be supplied if necessary. For example:
538
539
\begin{verbatim}
540
from mod_python import apache
541
name = apache.import_module('/some/path/name.py')
542
\end{verbatim}
543
544
or:
545
546
\begin{verbatim}
547
from mod_python import apache
548
import os
549
here = os.path.dirname(__file__)
550
path = os.path.join(here, 'module.py')
551
module = apache.import_module(path)
552
\end{verbatim}
553
554
Where the file has an extension, that extension must be supplied. Although
555
it is recommended that code files still make use of the '.py' extension,
556
it is not actually a requirement and an alternate extension can be used.
557
For example:
558
559
\begin{verbatim}
560
from mod_python import apache
561
import os
562
here = os.path.dirname(__file__)
563
path = os.path.join(here, 'servlet.mps')
564
servlet = apache.import_module(path)
565
\end{verbatim}
566
567
To avoid the need to use hard coded absolute path names to modules, a few
568
shortcuts are provided. The first of these allow for the use of relative
569
path names with respect to the directory the module performing the
570
import is located within.
571
572
For example:
573
574
\begin{verbatim}
575
from mod_python import apache
576
577
parent = apache.import_module('../module.py')
578
subdir = apache.import_module('./subdir/module.py')
579
\end{verbatim}
580
581
Forward slashes must always be used for the prefixes './' and '../', even
582
on Windows hosts where native pathname use a backslash. This convention
583
of using forward slashes is used as that is what Apache normalizes all
584
paths to internally. If you are using Windows and have been using
585
backward slashes with \code{Directory} directives etc, you are using
586
Apache contrary to what is the accepted norm.
587
588
A further shortcut allows paths to be declared relative to what is
589
regarded as the handler root directory. The handler root directory is the
590
directory context in which the active \code{Python*Handler} directive was
591
specified. If the directive was specified within a \code{Location} or
592
\code{VirtualHost} directive, or at global server scope, the handler root
593
will be the relevant document root for the server.
594
595
To express paths relative to the handler root, the '\textasciitilde/' prefix
596
should be used. A forward slash must again always be used, even on Windows.
597
598
For example:
599
600
\begin{verbatim}
601
from mod_python import apache
602
603
parent = apache.import_module('~/../module.py')
604
subdir = apache.import_module('~/subdir/module.py')
605
\end{verbatim}
606
607
In all cases where a path to the actual code file for a module is given,
608
the \var{path} argument is redundant as there is no need to search
609
through a list of directories to find the module. In these situations,
610
the \var{path} is instead taken to be a list of directories to use as the
611
initial value of the \code{__mp_path__} variable contained in the
612
imported modules instead of an empty path.
613
614
This feature can be used to attach a more restrictive search path to a
615
set of modules rather than using the \code{PythonOption} to set a global
616
search path. To do this, the modules should always be imported through a
617
specific parent module. That module should then always import submodules
618
using paths and supply \code{__mp_path__} as the \var{path} argument to
619
subsequent calls to \code{apache.import_module()} within that module. For
620
example:
621
622
\begin{verbatim}
623
from mod_python import apache
624
625
module1 = apache.import_module('./module1.py', path=__mp_path__)
626
module2 = apache.import_module('./module2.py', path=__mp_path__)
627
\end{verbatim}
628
629
with the module being imported as:
630
631
\begin{verbatim}
632
from mod_python import apache
633
634
parent = apache.import_module('~/modules/parent.py', path=['/some/path'])
635
\end{verbatim}
636
637
The parent module may if required extend the value of \code{__mp_path__}
638
prior to using it. Any such directories will be added to those inherited
639
via the \var{path} argument. For example:
640
641
\begin{verbatim}
642
from mod_python import apache
643
import os
644
645
here = os.path.dirname(__file__)
646
subdir = os.path.join(here, 'subdir')
647
__mp_path__.append(subdir)
648
649
module1 = apache.import_module('./module1.py', path=__mp_path__)
650
module2 = apache.import_module('./module2.py', path=__mp_path__)
651
\end{verbatim}
652
653
In all cases where a search path is being specified which is specific
654
to the mod_python module importer, whether it be specified using the
655
\code{PythonOption} called \code{mod_python.importer.path}, using the
656
\var{path} argument to the \code{apache.import_module()} function or
657
in the \code{__mp_path__} attribute, the prefix '\textasciitilde/'
658
can be used in a path and that path will be taken as being relative
659
to handler root. For example:
660
661
\begin{verbatim}
662
PythonOption mod_python.importer.path "['~/modules']"
663
\end{verbatim}
664
665
If wishing to refer to the handler root directory itself, then
666
'\textasciitilde' can be used and the trailing slash left off. For example:
667
668
\begin{verbatim}
669
PythonOption mod_python.importer.path "['~']"
670
\end{verbatim}
671
672
Note that with the new module importer, as directories associated with
673
\code{Python*Handler} directives are no longer being added automatically
674
to \code{sys.path} and they are instead used directly by the module
675
importer only when required, some existing code which expected to be able
676
to import modules in the handler root directory from a module in a
677
subdirectory may no longer work. In these situations it will be necessary
678
to set the mod_python module importer path to include '\textasciitilde'
679
or list '\textasciitilde' in the \code{__mp_path__} attribute of the module
680
performing the import.
681
682
This trick of listing '\textasciitilde' in the module importer path
683
will not however help in the case where Python packages were previously
684
being placed into the handler root directory. In this case, the Python
685
package should either be moved out of the document tree and the directory
686
where it is located listed against the \code{PythonPath} directive, or the
687
package converted into the pseudo packages that mod_python supports and
688
change the module imports used to access the package.
689
690
Only modules which could be imported by the mod_python module importer
691
will be candidates for automatic reloading when changes are made to the
692
code file on disk. Any modules or packages which were located in a
693
directory listed in \code{sys.path} and which were imported using the
694
standard Python module importer will not be candidates for reloading.
695
696
Even where modules are candidates for module reloading, unless a true
697
value was explicitly supplied as the \var{autoreload} option to the
698
\code{apache.import_module()} function they will only be reloaded if the
699
\code{PythonAutoReload} directive is \code{On}. The default value when
700
the directive is not specified will be \code{On}, so the directive need
701
only be used when wishing to set it to \code{Off} to disable automatic
702
reloading, such as in a production system.
703
704
Where possible, the \code{PythonAutoReload} directive should only be
705
specified in one place and in the root context for a specific Python
706
interpreter instance. If the \code{PythonAutoReload} directive is used in
707
multiple places with different values, or doesn't cover all directories
708
pertaining to a specific Python interpreter instance, then problems can
709
result. This is because requests against some URLs may result in modules
710
being reloaded whereas others may not, even when through each URL the
711
same module may be imported from a common location.
712
713
If absolute certainty is required that module reloading is disabled and
714
that it isn't being enabled through some subset of URLs, the
715
\code{PythonImport} directive should be used to import a special module
716
whenever an Apache child process is being created. This module should
717
include a call to the \code{apache.freeze_modules()} function. This
718
will have the effect of permanently disabling module reloading for the
719
complete life of that Apache child process, irrespective of what value
720
the \code{PythonAutoReload} directive is set to.
721
722
Using the new ability within mod_python 3.3 to have \code{PythonImport}
723
call a specific function within a module after it has been imported,
724
one could actually dispense with creating a module and instead call
725
the function directory out of the \code{mod_python.apache} module.
726
For example:
727
728
\begin{verbatim}
729
PythonImport mod_python.apache::freeze_modules interpreter_name
730
\end{verbatim}
731
732
Where module reloading is being undertaken, unlike the core module
733
importer in versions of mod_python prior to 3.3, they are not reloaded on
734
top of existing modules, but into a completely new module instance. This
735
means that any code that previously relied on state information or data
736
caches to be preserved across reloads will no longer work.
737
738
If it is necessary to transfer such information from an old module to the
739
new module, it is necessary to provide a hook function within modules to
740
transfer across the data that must be preserved. The name of this hook
741
function is \code{__mp_clone__()}. The argument given to the hook
742
function will be an empty module into which the new module will subsequently
743
be loaded.
744
745
When called, the hook function should copy any data from the old module
746
to the new module. In doing this, the code performing the copying should
747
be cognizant of the fact that within a multithreaded Apache MPM that
748
other request handlers could still be trying to access and update the
749
data to be copied. As such, the hook function should ensure that it uses
750
any thread locking mechanisms within the module as appropriate when
751
copying the data. Further, it should copy the actual data locks
752
themselves across to the new module to ensure a clean transition.
753
754
Because copying integral values will result in the data then being
755
separate, it may be necessary to always store data within a dictionary so
756
as to provide a level of indirection which will allow the data to be
757
usable from both module instances while they still exist.
758
759
For example:
760
761
\begin{verbatim}
762
import threading, time
763
764
if not globals().has_key('_lock'):
765
# Initial import of this module.
766
_lock = threading.Lock()
767
_data1 = { 'value1' : 0, 'value2': 0 }
768
_data2 = {}
769
770
def __mp_clone__(module):
771
_lock.acquire()
772
module._lock = _lock
773
module._data1 = _data1
774
module._data2 = _data2
775
_lock.release()
776
\end{verbatim}
777
778
Because the old module is about to be discarded, the data which is
779
transferred should not consist of data objects which are dependent on
780
code within the old module. Data being copied across to the new module
781
should consist of standard Python data types, or be instances of classes
782
contained within modules which themselves are not candidates for
783
reloading. Otherwise, data should be migrated by transforming it into
784
some neutral intermediate state, with the new module transforming it back
785
when its code executes at the time of being imported.
786
787
If these guidelines aren't heeded and data is dependent on code objects
788
within the old module, it will prevent those code objects from being
789
unloaded and if this continues across multiple reloads, then process size
790
may increase over time due to old code objects being retained.
791
792
In any case, if for some reason the hook function fails and an exception
793
is raised then both the old and new modules will be discarded. As a last
794
opportunity to release any resources when this occurs, an extra hook
795
function called \code{__mp_purge__()} can be supplied. This function will
796
be called with no arguments.
797
367
798
\end{funcdesc}
368
799
369
800
\begin{funcdesc}{allow_methods}{\optional{*args}}
412
843
parameter by calling \code{apache.exists_config_define('FOOBAR')}.
413
844
\end{funcdesc}
414
845
415
\begin{methoddesc}[server]{register_cleanup}{handler\optional{, data}}
416
Registers a cleanup. Equivalent to \function{req.register_cleanup()}
417
or \function{req.server.register_cleanup()}, except that a server or request
418
object is not required.
419
\end{methoddesc}
846
\begin{funcdesc}{stat}{fname, wanted}
847
This function returns an instance of an \code{mp_finfo} object
848
describing information related to the file with name \code{fname}.
849
The \code{wanted} argument describes the minimum attributes which
850
should be filled out. The resultant object can be assigned to the
851
\code{req.finfo} attribute.
852
\end{funcdesc}
853
854
\begin{funcdesc}{register_cleanup}{callable\optional{, data}}
855
Registers a cleanup that will be performed at child shutdown time. Equivalent
856
to \function{server.register_cleanup()}, except that a request object is not
857
required.
858
\emph{Warning:} do not pass directly or indirectly a request object in the
859
data parameter. Since the callable will be called at server shutdown time,
860
the request object won't exist anymore and any manipulation of it in the
861
handler will give undefined behaviour.
862
\end{funcdesc}
420
863
421
864
\begin{funcdesc}{config_tree}{}
422
865
Returns the server-level configuration tree. This tree does not
472
915
\end{verbatim}
473
916
\end{funcdesc}
474
917
918
\subsection{Attributes\label{pyapi-apmem}}
919
920
\begin{memberdesc}[apache]{interpreter}
921
The name of the subinterpreter under which we're running.
922
\emph{(Read-Only)}
923
\end{memberdesc}
924
925
\begin{memberdesc}[apache]{main_server}
926
A \code{server} object for the main server.
927
\emph{(Read-Only})
928
\end{memberdesc}
929
475
930
\subsection{Table Object (mp_table)\obindex{table}\label{pyapi-mptable}}
476
931
477
932
\index{table}
537
992
containing the name of any of the apache request (but not filter or
538
993
connection) handler directives,
539
994
e.g. \samp{PythonHandler}. \var{handler} is a string containing the
540
name of the module and the handler function. Optional \var{dir} is
541
a string containing the name of the directory to be added to the
542
pythonpath. If no directory is specified, then, if there is already
543
a handler of the same type specified, its directory is inherited,
544
otherwise the directory of the presently executing handler is
545
used. If there is a \code{PythonPath} directive in effect, then
546
\code{sys.path} will be set exactly according to it (no directories
547
added, the \var{dir} argument is ignored).
548
995
name of the module and the handler function, or the callable object
996
itself. Optional \var{dir} is a string containing the name of the
997
directory to be added to the module search path when looking for the
998
handler. If no directory is specified, then the directory to search
999
in is inherited from the handler which is making the registration,
1000
549
1001
A handler added this way only persists throughout the life of the
550
1002
request. It is possible to register more handlers while inside the
551
handler of the same type. One has to be careful as to not to create
552
an infinite loop this way.
1003
handler of the same type. One has to be careful as to not to create an
1004
infinite loop this way.
553
1005
554
1006
Dynamic handler registration is a useful technique that allows the
555
1007
code to dynamically decide what will happen next. A typical example
568
1020
If you pass this function an invalid handler, an exception will be
569
1021
generated at the time an attempt is made to find the handler.
570
1022
\end{notice}
1023
1024
\end{methoddesc}
1025
1026
\begin{methoddesc}[request]{add_input_filter}{filter_name}
1027
Adds the named filter into the input filter chain for the current request.
1028
The filter should be added before the first attempt to read any data from
1029
the request.
1030
\end{methoddesc}
1031
1032
\begin{methoddesc}[request]{add_output_filter}{filter_name}
1033
Adds the named filter into the output filter chain for the current request.
1034
The filter should be added before the first attempt to write any data for
1035
the response.
1036
1037
Provided that all data written is being buffered and not flushed, this
1038
could be used to add the "CONTENT_LENGTH" filter into the chain of
1039
output filters. The purpose of the "CONTENT_LENGTH" filter is to add a
1040
\code{Content-Length:} header to the response.
1041
1042
\begin{verbatim}
1043
req.add_output_filter("CONTENT_LENGTH")
1044
req.write("content",0)
1045
\end{verbatim}
1046
571
1047
\end{methoddesc}
572
1048
573
1049
\begin{methoddesc}[request]{allow_methods}{methods\optional{, reset}}
583
1059
the list of methods is first cleared.
584
1060
\end{methoddesc}
585
1061
1062
\begin{methoddesc}[request]{auth_name}{}
1063
Returns AuthName setting.
1064
\end{methoddesc}
1065
1066
\begin{methoddesc}[request]{auth_type}{}
1067
Returns AuthType setting.
1068
\end{methoddesc}
1069
1070
\begin{methoddesc}[request]{construct_url}{uri}
1071
This function returns a fully qualified URI string from the path specified
1072
by uri, using the information stored in the request to determine the scheme,
1073
server name and port. The port number is not included in the string if it
1074
is the same as the default port 80.
1075
1076
For example, imagine that the current request is directed to the virtual
1077
server www.modpython.org at port 80. Then supplying \samp{/index.html} will
1078
yield the string \samp{http://www.modpython.org/index.html}.
1079
1080
\end{methoddesc}
1081
1082
\begin{methoddesc}[request]{discard_request_body}{}
1083
Tests for and reads any message body in the request, simply discarding
1084
whatever it receives.
1085
\end{methoddesc}
1086
586
1087
\begin{methoddesc}[request]{document_root}{}
587
1088
Returns DocumentRoot setting.
588
1089
\end{methoddesc}
673
1174
674
1175
\end{methoddesc}
675
1176
676
\begin{methoddesc}{log_error}{message\optional{, level}}
1177
\begin{methoddesc}[request]{log_error}{message\optional{, level}}
677
1178
An interface to the Apache \code{ap_log_rerror}
678
1179
function. \var{message} is a string with the error message,
679
1180
\var{level} is one of the following flags constants:
695
1196
\end{methoddesc}
696
1197
697
1198
\begin{methoddesc}[request]{meets_conditions}{}
698
Calls the Apache \cfunction{ap_meets_conditions()} function which
699
returns a status code. If \var{status} is \constant{apache.OK}, generate
700
the content of the response normally. If not, simply return \var{status}.
701
Note that \member{req.headers_out} should be set prior to calling this
702
function. The same goes for \member{req.status} if the status differs
703
from \constant{apache.OK}.
1199
Calls the Apache \cfunction{ap_meets_conditions()} function which returns
1200
a status code. If \var{status} is \constant{apache.OK}, generate the
1201
content of the response normally. If not, simply return \var{status}.
1202
Note that \var{mtime} (and possibly the ETag header) should be set as
1203
appropriate prior to calling this function. The same goes for
1204
\member{req.status} if the status differs from \constant{apache.OK}.
704
1205
705
1206
Example:
706
1207
\begin{verbatim}
707
1208
...
708
r.headers_out['ETag'] = "1130794f-3774-4584-a4ea-0ab19e684268"
709
r.headers_out['Last-Modified'] = 'Wed, 23 Feb 2005 00:00:00 GMT'
1209
r.headers_out['ETag'] = '"1130794f-3774-4584-a4ea-0ab19e684268"'
710
1210
r.headers_out['Expires'] = 'Mon, 18 Apr 2005 17:30:00 GMT'
1211
r.update_mtime(1000000000)
1212
r.set_last_modified()
711
1213
712
1214
status = r.meets_conditions()
713
1215
if status != apache.OK:
765
1267
\end{methoddesc}
766
1268
767
1269
\begin{methoddesc}[request]{readlines}{\optional{sizehint}}
768
Reads all or up to \var{sizehint} bytes of lines using
769
\method{readline} and returns a list of the lines read.
1270
Reads all lines using \method{readline} and returns a list of the lines read.
1271
If the optional \var{sizehint} parameter is given in, the method will read
1272
at least \var{sizehint} bytes of data, up to the completion of the line in
1273
which the \var{sizehint} bytes limit is reached.
770
1274
\end{methoddesc}
771
1275
772
1276
\begin{methoddesc}[request]{register_cleanup}{callable\optional{, data}}
791
1295
792
1296
\end{methoddesc}
793
1297
1298
\begin{methoddesc}[request]{register_input_filter}{filter_name, filter\optional{, dir}}
1299
1300
Allows dynamic registration of mod_python input filters. \var{filter_name}
1301
is a string which would then subsequently be used to identify the filter.
1302
\var{filter} is a string containing the name of the module and the filter
1303
function or the callable object itself. Optional \var{dir} is a string
1304
containing the name of the directory to be added to the module search when
1305
looking for the module.
1306
1307
The registration of the filter this way only persists for the life of the
1308
request. To actually add the filter into the chain of input filters for
1309
the current request \code{req.add_input_filter()} would be used.
1310
1311
\end{methoddesc}
1312
1313
\begin{methoddesc}[request]{register_output_filter}{filter_name, filter\optional{, dir}}
1314
1315
Allows dynamic registration of mod_python output filters. \var{filter_name}
1316
is a string which would then subsequently be used to identify the filter.
1317
\var{filter} is a string containing the name of the module and the filter
1318
function or the callable object itself. Optional \var{dir} is a string
1319
containing the name of the directory to be added to the module search
1320
path when looking for the handler.
1321
1322
The registration of the filter this way only persists for the life of the
1323
request. To actually add the filter into the chain of output filters for
1324
the current request \code{req.add_output_filter()} would be used.
1325
1326
\end{methoddesc}
1327
794
1328
\begin{methoddesc}[request]{sendfile}{path\optional{, offset, len}}
795
1329
Sends \var{len} bytes of file \var{path} directly to the client,
796
1330
starting at offset \var{offset} using the server's internal
804
1338
client.
805
1339
\end{methoddesc}
806
1340
1341
\begin{methoddesc}[request]{set_etag}{}
1342
Sets the outgoing \samp{ETag} header.
1343
\end{methoddesc}
1344
1345
\begin{methoddesc}[request]{set_last_modified}{}
1346
Sets the outgoing \samp{Last-Modified} header based on value of
1347
\code{mtime} attribute.
1348
\end{methoddesc}
1349
807
1350
\begin{methoddesc}[request]{ssl_var_lookup}{var_name}
808
1351
Looks up the value of the named SSL variable. This method queries
809
1352
the mod_ssl Apache module directly, and may therefore be used in
838
1381
839
1382
\end{methoddesc}
840
1383
1384
\begin{methoddesc}[request]{update_mtime}{dependency_mtime}
1385
If \var{dependency_mtime} is later than the value in the \code{mtime}
1386
attribute, sets the attribute to the new value.
1387
\end{methoddesc}
1388
841
1389
\begin{methoddesc}[request]{write}{string\optional{, flush=1}}
842
1390
Writes \var{string} directly to the client, then flushes the buffer,
843
1391
unless flush is 0.
901
1449
902
1450
\begin{memberdesc}[request]{proxyreq}
903
1451
A proxy request: one of \constant{apache.PROXYREQ_*} values.
904
\emph{(Read-Only})
905
1452
\end{memberdesc}
906
1453
907
1454
\begin{memberdesc}[request]{header_only}
1078
1625
\end{memberdesc}
1079
1626
1080
1627
\begin{memberdesc}[request]{handler}
1081
The name of the handler currently being processed. This is the handler
1082
set by mod_mime, not the mod_python handler. In most cases it will be
1083
"\samp{mod_python}. \emph{(Read-Only})
1628
The symbolic name of the content handler (as in module, not mod_python
1629
handler) that will service the request during the response phase. When
1630
the SetHandler/AddHandler directives are used to trigger mod_python, this
1631
will be set to \samp{mod_python} by mod_mime. A mod_python handler executing
1632
prior to the response phase may also set this to \samp{mod_python} along
1633
with calling \samp{req.add_handler()} to register a mod_python handler
1634
for the response phase.
1635
1636
\begin{verbatim}
1637
def typehandler(req):
1638
if os.path.splitext(req.filename)[1] == ".py":
1639
req.handler = "mod_python"
1640
req.add_handler("PythonHandler", "mod_python.publisher")
1641
return apache.OK
1642
return apache.DECLINED
1643
\end{verbatim}
1644
1084
1645
\end{memberdesc}
1085
1646
1086
1647
\begin{memberdesc}[request]{content_encoding}
1096
1657
\begin{memberdesc}[request]{user}
1097
1658
If an authentication check is made, this will hold the user
1098
1659
name. Same as CGI \envvar{REMOTE_USER}.
1099
\emph{(Read-Only})
1100
1660
\begin{notice}
1101
1661
\method{req.get_basic_auth_pw()} must be called prior to using this value.
1102
1662
\end{notice}
1104
1664
1105
1665
\begin{memberdesc}[request]{ap_auth_type}
1106
1666
Authentication type. Same as CGI \envvar{AUTH_TYPE}.
1107
\emph{(Read-Only})
1108
1667
\end{memberdesc}
1109
1668
1110
1669
\begin{memberdesc}[request]{no_cache}
1111
Boolean. No cache if true.
1112
\emph{(Read-Only})
1670
Boolean. This response cannot be cached.
1113
1671
\end{memberdesc}
1114
1672
1115
1673
\begin{memberdesc}[request]{no_local_copy}
1116
1674
Boolean. No local copy exists.
1117
\emph{(Read-Only})
1118
1675
\end{memberdesc}
1119
1676
1120
1677
\begin{memberdesc}[request]{unparsed_uri}
1124
1681
1125
1682
\begin{memberdesc}[request]{uri}
1126
1683
The path portion of the URI.
1127
\emph{(Read-Only})
1128
1684
\end{memberdesc}
1129
1685
1130
1686
\begin{memberdesc}[request]{filename}
1133
1689
1134
1690
\begin{memberdesc}[request]{canonical_filename}
1135
1691
String. The true filename (\member{req.filename} is canonicalized if
1136
they don't match). \emph{(Read-Only)}
1692
they don't match).
1137
1693
\end{memberdesc}
1138
1694
1139
1695
\begin{memberdesc}[request]{path_info}
1143
1699
1144
1700
\begin{memberdesc}[request]{args}
1145
1701
String. Same as CGI \envvar{QUERY_ARGS}.
1146
\emph{(Read-Only})
1147
1702
\end{memberdesc}
1148
1703
1149
1704
\begin{memberdesc}[request]{finfo}
1150
Tuple. A file information structure, analogous to POSIX stat,
1151
describing the file pointed to by the URI. \code{(mode, ino,
1152
dev, nlink, uid, gid, size, atime, mtime, ctime, fname,
1153
name)}. The \code{apache} module defines a set of \constant{FINFO_*}
1154
constants that should be used to access elements of this
1155
tuple. Example:
1156
\begin{verbatim}
1157
fname = req.finfo[apache.FINFO_FNAME]
1158
\end{verbatim}
1159
\emph{(Read-Only})
1705
A file information object with type \code{mp_finfo}, analogous to the
1706
result of the POSIX stat function, describing the
1707
file pointed to by the URI. The object provides the attributes
1708
\code{fname}, \code{filetype}, \code{valid}, \code{protection},
1709
\code{user}, \code{group}, \code{size}, \code{inode}, \code{device},
1710
\code{nlink}, \code{atime}, \code{mtime}, \code{ctime} and \code{name}.
1711
1712
The attribute may be assigned to using the result of \code{apache.stat()}.
1713
For example:
1714
1715
\begin{verbatim}
1716
if req.finfo.filetype == apache.APR_DIR:
1717
req.filename = posixpath.join(req.filename, 'index.html')
1718
req.finfo = apache.stat(req.filename, apache.APR_FINFO_MIN)
1719
\end{verbatim}
1720
1721
For backward compatability, the object can also be accessed as if it
1722
were a tuple. The \code{apache} module defines a set of \constant{FINFO_*}
1723
constants that should be used to access elements of this tuple.
1724
1725
\begin{verbatim}
1726
user = req.finfo[apache.FINFO_USER]
1727
\end{verbatim}
1160
1728
\end{memberdesc}
1161
1729
1162
1730
\begin{memberdesc}[request]{parsed_uri}
1172
1740
1173
1741
\begin{memberdesc}[request]{used_path_info}
1174
1742
Flag to accept or reject path_info on current request.
1175
\emph{(Read-Only})
1176
1743
\end{memberdesc}
1177
1744
1178
1745
\begin{memberdesc}[request]{eos_sent}
1187
1754
1188
1755
\subsubsection{Connection Methods\label{pyapi-mpconn-meth}}
1189
1756
1757
\begin{methoddesc}[connection]{log_error}{message\optional{, level}}
1758
An interface to the Apache \code{ap_log_cerror}
1759
function. \var{message} is a string with the error message,
1760
\var{level} is one of the following flags constants:
1761
1762
\begin{verbatim}
1763
APLOG_EMERG
1764
APLOG_ALERT
1765
APLOG_CRIT
1766
APLOG_ERR
1767
APLOG_WARNING
1768
APLOG_NOTICE
1769
APLOG_INFO
1770
APLOG_DEBUG
1771
APLOG_NOERRNO
1772
\end{verbatim}
1773
1774
If you need to write to log and do not have a reference to a connection or
1775
request object, use the \function{apache.log_error} function.
1776
\end{methoddesc}
1777
1190
1778
\begin{methoddesc}[connection]{read}{\optional{length}}
1191
1779
Reads at most \var{length} bytes from the client. The read blocks
1192
1780
indefinitely until there is at least one byte to read. If length is
1376
1964
\subsubsection{Server Methods\label{pyapi-mpsrv-meth}}
1377
1965
1378
1966
\begin{methoddesc}[server]{get_config}{}
1379
Similar to \code{req.get_config()}, but returns a config pointed to
1380
by \code{server->module_config} Apache config vector.
1967
Similar to \code{req.get_config()}, but returns a table object holding
1968
only the mod_python configuration defined at global scope within the
1969
Apache configuration. That is, outside of the context of any VirtualHost,
1970
Location, Directory or Files directives.
1381
1971
\end{methoddesc}
1382
1972
1383
1973
\begin{methoddesc}[server]{get_options}{}
1387
1977
Directory or Files directives.
1388
1978
\end{methoddesc}
1389
1979
1980
\begin{methoddesc}[server]{log_error}{message\optional{, level}}
1981
An interface to the Apache \code{ap_log_error}
1982
function. \var{message} is a string with the error message,
1983
\var{level} is one of the following flags constants:
1984
1985
\begin{verbatim}
1986
APLOG_EMERG
1987
APLOG_ALERT
1988
APLOG_CRIT
1989
APLOG_ERR
1990
APLOG_WARNING
1991
APLOG_NOTICE
1992
APLOG_INFO
1993
APLOG_DEBUG
1994
APLOG_NOERRNO
1995
\end{verbatim}
1996
1997
If you need to write to log and do not have a reference to a server or
1998
request object, use the \function{apache.log_error} function.
1999
\end{methoddesc}
2000
1390
2001
\begin{methoddesc}[server]{register_cleanup}{request, callable\optional{, data}}
1391
2002
Registers a cleanup. Very similar to \function{req.register_cleanup()}, except
1392
2003
this cleanup will be executed at child termination time. This function
1393
requires one extra argument - the request object.
2004
requires the request object be supplied to infer the interpreter name.
2005
If you don't have any request object at hand, then you must use the
2006
\function{apache.register_cleanup} variant.
2007
\emph{Warning:} do not pass directly or indirectly a request object in the
2008
data parameter. Since the callable will be called at server shutdown time,
2009
the request object won't exist anymore and any manipulation of it in the
2010
callable will give undefined behaviour.
1394
2011
\end{methoddesc}
1395
2012
1396
2013
\subsubsection{Server Members\label{pyapi-mpsrv-mem}}
1546
2163
consumed at this point, there should be no more than one
1547
2164
\class{FieldStorage} class instantiated per single request, nor should
1548
2165
you make any attempts to read client data before or after
1549
instantiating a \class{FieldStorage}.
2166
instantiating a \class{FieldStorage}. A suggested strategy for dealing
2167
with this is that any handler should first check for the existance of
2168
a \code{form} attribute within the request object. If this exists, it
2169
should be taken to be an existing instance of the \class{FieldStorage}
2170
class and that should be used. If the attribute does not exist
2171
and needs to be created, it should be cached as the \code{form}
2172
attribute of the request object so later handler code can use it.
1550
2173
1551
The data read from the client is then parsed into separate fields and
1552
packaged in \class{Field} objects, one per field. For HTML form inputs
1553
of type \code{file}, a temporary file is created that can later be
1554
accessed via the \member{file} attribute of a \class{Field} object.
2174
When the \class{FieldStorage} class instance is created, the data read
2175
from the client is then parsed into separate fields and packaged in
2176
\class{Field} objects, one per field. For HTML form inputs of type
2177
\code{file}, a temporary file is created that can later be accessed via
2178
the \member{file} attribute of a \class{Field} object.
1555
2179
1556
2180
The \class{FieldStorage} class has a mapping object interface, i.e. it
1557
can be treated like a dictionary. When used as a mapping, the keys are
1558
form input names, and the returned dictionary value can be:
2181
can be treated like a dictionary in most instances, but is not strictly
2182
compatible as is it missing some methods provided by dictionaries and
2183
some methods don't behave entirely like their counterparts, especially
2184
when there is more than one value associated with a form field. When used
2185
as a mapping, the keys are form input names, and the returned dictionary
2186
value can be:
1559
2187
1560
2188
\begin{itemize}
1561
2189
\item
1591
2219
1592
2220
\class{FieldStorage} methods:
1593
2221
2222
\begin{methoddesc}[FieldStorage]{add_field}{name, value}
2223
Adds an additional form field with \var{name} and \var{value}.
2224
If a form field already exists with \var{name}, the \var{value}
2225
will be added to the list of existing values for the form field.
2226
This method should be used for adding additional fields in
2227
preference to adding new fields direct to the list of fields.
2228
2229
If the value associated with a field should be replaced when it
2230
already exists, rather than an additional value being associated
2231
with the field, the dictionary like subscript operator should
2232
be used to set the value, or the existing field deleted altogether
2233
first using the \code{del} operator.
2234
\end{methoddesc}
2235
2236
\begin{methoddesc}[FieldStorage]{clear}{}
2237
Removes all form fields. Individual form fields can be deleted
2238
using the \code{del} operator.
2239
\end{methoddesc}
2240
2241
\begin{methoddesc}[FieldStorage]{get}{name, default}
2242
If there is only one value associated with form field \var{name}, that
2243
single value will be returned. If there are multiple values, a list is
2244
returned holding all values. If no such form field or value exists then
2245
the method returns the value specified by the parameter \var{default}.
2246
A subscript operator is also available which yields the same result
2247
except that an exception will be raised where the form field \var{name}
2248
does not exist.
2249
\end{methoddesc}
2250
1594
2251
\begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}}
1595
2252
Always returns only one value associated with form field
1596
2253
\var{name}. If no such form field or value exists then the method
1606
2263
of one item if only one such value exists.
1607
2264
\end{methoddesc}
1608
2265
2266
\begin{methoddesc}[FieldStorage]{has_key}{name}
2267
Returns \code{True} if \var{name} is a valid form field. The \code{in}
2268
operator is also supported and will call this method.
2269
\end{methoddesc}
2270
2271
\begin{methoddesc}[FieldStorage]{items}{}
2272
Returns a list consisting of tuples for each combination of form
2273
field name and value.
2274
\end{methoddesc}
2275
2276
\begin{methoddesc}[FieldStorage]{keys}{}
2277
This method returns the names of the form fields. The \code{len}
2278
operator is also supported and will return the number of names
2279
which would be returned by this method.
2280
\end{methoddesc}
2281
1609
2282
\end{classdesc}
1610
2283
1611
2284
\subsection{FieldStorage Examples\label{pyapi-util-fstor-examples}}
1811
2484
If this function is called after the headers have already been sent,
1812
2485
an \exception{IOError} is raised.
1813
2486
1814
This function raises \exception{apache.SERVER_RETURN} exception to
1815
abandon any further processing of the handle. If you do not want
1816
this, you can wrap the call to \function{redirect} in a try/except
1817
block catching the \exception{apache.SERVER_RETURN}.
2487
This function raises \exception{apache.SERVER_RETURN} exception with
2488
a value of \constant{apache.DONE} to ensuring that any later phases or
2489
stacked handlers do not run. If you do not want this, you can wrap the
2490
call to \function{redirect} in a try/except block catching the
2491
\exception{apache.SERVER_RETURN}.
1818
2492
\end{funcdesc}
1819
2493
1820
2494
\section{\module{Cookie} -- HTTP State Management\label{pyapi-cookie}}
1868
2542
the cookie. The \class{Cookie} class restricts attribute names to
1869
2543
only valid values, specifically, only the following attributes are
1870
2544
allowed: \code{name, value, version, path, domain, secure, comment,
1871
expires, max_age, commentURL, discard, port, __data__}.
2545
expires, max_age, commentURL, discard, port, httponly, __data__}.
1872
2546
1873
2547
The \code{__data__} attribute is a general-purpose dictionary that
1874
2548
can be used for storing arbitrary values, when necessary (This is
1933
2607
1934
2608
\begin{notice}
1935
2609
Always check the types of objects returned by
1936
\method{SignedCookie.parse()}.If it is an instance of
2610
\method{SignedCookie.parse()}. If it is an instance of
1937
2611
\class{Cookie} (as opposed to \class{SignedCookie}), the
1938
2612
signature verification has failed:
1939
2613
\begin{verbatim}
1994
2668
can be any number of keyword arguments which, will be passed to
1995
2669
\method{parse()} (This is useful for \class{signedCookie} and
1996
2670
\class{MarshalCookie} which require \code{secret} as an additional
1997
argument to \method{parse}).
2671
argument to \method{parse}). The set of cookies found is returned as
2672
a dictionary.
2673
\end{funcdesc}
2674
2675
\begin{funcdesc}{get_cookie}{req, name \optional{, Class, data}}
2676
This is a convenience function for retrieving a single named cookie
2677
from incoming headers. \var{req} is a mod_python \class{Request}
2678
object. \var{name} is the name of the cookie. \var{Class} is a class
2679
whose \method{parse()} method will be used to parse the cookies, it
2680
defaults to \code{Cookie}. \var{Data} can be any number of keyword
2681
arguments which, will be passed to \method{parse()} (This is useful for
2682
\class{signedCookie} and \class{MarshalCookie} which require
2683
\code{secret} as an additional argument to \method{parse}). The cookie
2684
if found is returned, otherwise \code{None} is returned.
1998
2685
\end{funcdesc}
1999
2686
2000
2687
\subsection{Examples\label{pyapi-cookie-example}}
2080
2767
\function{Session()} takes the same arguments as \class{BaseSession}.
2081
2768
2082
2769
This function returns a instance of the default session class. The
2083
the session class to be used can be specified using
2084
\var{PythonOption session value}, where \var{value} is one of
2085
\class{DbmSession}, \class{MemorySession} or \class{FileSession}. Specifying
2086
custom session classes using PythonOption session is not yet supported.
2087
2088
If \var{PythonOption session} is not found, the function queries
2089
the MPM and based on that returns either a new instance of
2090
\class{DbmSession} or \class{MemorySession}.
2091
2092
\class{MemorySession} will be used if the MPM is threaded and not
2093
forked (such is the case on Windows), or if it threaded, forked, but
2094
only one process is allowed (the worker MPM can be configured to run
2095
this way). In all other cases \class{DbmSession} is used.
2770
session class to be used can be specified using \var{PythonOption
2771
mod_python.session.session_type value}, where \var{value} is one of
2772
\class{DbmSession}, \class{MemorySession} or \class{FileSession}.
2773
Specifying custom session classes using \code{PythonOption} session is
2774
not yet supported.
2775
2776
If session type option is not found, the function queries the MPM and
2777
based on that returns either a new instance of \class{DbmSession} or
2778
\class{MemorySession}. \class{MemorySession} will be used if the MPM is
2779
threaded and not forked (such is the case on Windows), or if it threaded,
2780
forked, but only one process is allowed (the worker MPM can be configured
2781
to run this way). In all other cases \class{DbmSession} is used.
2782
2783
Note that on Windows if you are using multiple Python interpreter
2784
instances and you need sessions to be shared between applications
2785
running within the context of the distinct Python interpreter
2786
instances, you must specifically indicate that \class{DbmSession}
2787
should be used, as \class{MemorySession} will only allow a session
2788
to be valid within the context of the same Python interpreter instance.
2789
2790
Also note that the option name \code{mod_python.session.session_type}
2791
only started to be used from mod_python 3.3 onwards. If you need to
2792
retain compatability with older versions of mod_python, you should
2793
use the now obsolete \code{session} option instead.
2096
2794
\end{funcdesc}
2097
2795
2098
2796
\begin{classdesc}{BaseSession}{req\optional{, sid, secret, timeout, lock}}
2114
2812
determined by calling the \method{is_new()} method.
2115
2813
2116
2814
Cookies generated by sessions will have a path attribute which is
2117
calculated by comparing the server \code{DocumentRoot} and the
2118
directory in which the \code{PythonHandler} directive currently in
2119
effect was specified. E.g. if document root is \file{/a/b/c} and
2120
\code{PythonHandler} was specified in \file{/a/b/c/d/e}, the path
2121
will be set to \file{/d/e}. You can force a specific path by using
2122
\code{ApplicationPath} option (\samp{PythonOption ApplicationPath
2123
/my/path} in server configuration).
2815
calculated by comparing the server \code{DocumentRoot} and the directory
2816
in which the \code{PythonHandler} directive currently in effect was
2817
specified. E.g. if document root is \file{/a/b/c} and the directory
2818
\code{PythonHandler} was specified was \file{/a/b/c/d/e}, the path will be
2819
set to \file{/d/e}.
2820
2821
The deduction of the path in this way will only work though where the
2822
\code{Directory} directive is used and the directory is actually within
2823
the document root. If the \code{Location} directive is used or the
2824
directory is outside of the document root, the path will be set to
2825
\file{/}. You can force a specific path by setting the
2826
\code{mod_python.session.application_path} option (\samp{PythonOption
2827
mod_python.session.application_path /my/path} in server configuration).
2828
2829
Note that prior to mod_python 3.3, the option was \code{ApplicationPath}.
2830
If your system needs to be compatible with older versions of mod_python,
2831
you should continue to use the now obsolete option name.
2832
2833
The domain of a cookie is by default not set for a session and as such
2834
the session is only valid for the host which generated it. In order to
2835
have a session which spans across common sub domains, you can specify the
2836
parent domain using the \code{mod_python.session.application_domain}
2837
option (\samp{PythonOption mod_python.session.application_domain
2838
mod_python.org} in server configuration).
2124
2839
2125
2840
When a \var{secret} is provided, \class{BaseSession} will use
2126
2841
\class{SignedCookie} when generating cookies thereby making the
2128
2843
\class{Cookie} (though even if not signed, the session id is
2129
2844
generated to be very difficult to guess).
2130
2845
2131
A session will timeout if it has not been accessed for more than
2132
\var{timeout}, which defaults to 30 minutes. An attempt to load an
2846
A session will timeout if it has not been accessed and a save performed,
2847
within the \var{timeout} period. Upon a save occuring the time of last
2848
access is updated and the period until the session will timeout be reset.
2849
The default \var{timeout} period is 30 minutes. An attempt to load an
2133
2850
expired session will result in a ``new'' session.
2134
2851
2135
2852
The \var{lock} argument (defaults to 1) indicates whether locking
2242
2959
server restarts). By default the session information is stored in a
2243
2960
dbmfile named \file{mp_sess.dbm} and stored in a temporary directory
2244
2961
returned by \code{tempfile.gettempdir()} standard library
2245
function. An alternative directory can be specified with the
2246
\code{PythonOption session_directory} directive.
2247
The path and filename can can be overridden by setting \code{PythonOption
2248
session_dbm filename}.
2962
function. An alternative directory can be specified using
2963
\code{PythonOption mod_python.dbm_session.database_directory
2964
/path/to/directory}. The path and filename can can be overridden by
2965
setting \code{PythonOption mod_python.dbm_session.database_filename
2966
filename}.
2967
2968
Note that the above names for the \code{PythonOption} settings were
2969
changed to these values in mod_python 3.3. If you need to retain
2970
compatability with older versions of mod_python, you should continue
2971
to use the now obsolete \code{session_directory} and \code{session_dbm}
2972
options.
2249
2973
2250
2974
The implementation uses Python \module{anydbm} module, which will
2251
2975
default to \module{dbhash} on most systems. If you need to use a
2271
2995
The session files are saved in a directory named mp_sess in the
2272
2996
temporary directory returned by the \code{tempfile.gettempdir()}
2273
2997
standard library function. An alternate path can be set using
2274
\code{PythonOption session_directory /path/to/directory}. This
2275
directory must exist and be readable and writeable by the apache
2276
process.
2277
2278
Expired session files are periodically removed by the cleanup
2279
mechanism. The behaviour of the cleanup can be controlled using the
2280
\var{fast_cleanup} and \var{verify_cleanup} parameters, as well as
2281
\var{PythonOption session_grace_period} and
2282
\var{PythonOption session_cleanup_time_limit}.
2998
\code{PythonOption mod_python.file_session.database_directory
2999
/path/to/directory}. This directory must exist and be readable and
3000
writeable by the apache process.
3001
3002
Note that the above name for the \code{PythonOption} setting was
3003
changed to these values in mod_python 3.3. If you need to retain
3004
compatability with older versions of mod_python, you should continue
3005
to use the now obsolete \code{session_directory} option.
3006
3007
Expired session files are periodically removed by the cleanup mechanism.
3008
The behaviour of the cleanup can be controlled using the
3009
\var{fast_cleanup} and \var{verify_cleanup} parameters, as well as
3010
\var{PythonOption mod_python.file_session.cleanup_time_limit} and
3011
\var{PythonOption mod_python.file_session.cleanup_grace_period}.
2283
3012
2284
3013
\begin{itemize}
2285
3014
\item
2308
3037
\var{verify_cleanup} = True.
2309
3038
2310
3039
The value of \var{fast_cleanup} can also be set using
2311
\code{PythonOption session_fast_cleanup}.
3040
\code{PythonOption mod_python.file_session.enable_fast_cleanup}.
2312
3041
2313
3042
\item
2314
3043
\var{verify_cleanup}
2328
3057
deleted if all the sessions are not using a the same timeout value.
2329
3058
2330
3059
The value of \var{verify_cleanup} can also be set using
2331
\code{PythonOption session_verify_cleanup}
3060
\code{PythonOption mod_python.file_session.verify_session_timeout}.
2332
3061
2333
3062
\item
2334
\var{PythonOption session_cleanup_time_limit [value]}
3063
\var{PythonOption mod_python.file_session.cleanup_time_limit [value]}
2335
3064
Integer value in seconds. Default is 2 seconds.
2336
3065
2337
3066
Session cleanup could potentially take a long time and be both cpu
2347
3076
is called.
2348
3077
2349
3078
\item
2350
\var{PythonOption session_grace_period [value]}
3079
\var{PythonOption mod_python.file_session.cleanup_grace_period [value]}
2351
3080
Integer value in seconds. Default is 240 seconds. This value is added
2352
3081
to the session timeout in determining if a session file should be
2353
3082
deleted.
2372
3101
This class provides session storage using a global dictionary. This
2373
3102
class provides by far the best performance, but cannot be used in a
2374
3103
multi-process configuration, and also consumes memory for every
2375
active session.
3104
active session. It also cannot be used where multiple Python interpreters
3105
are used within the one Apache process and it is necessary to share
3106
sessions between applications running in the distinct interpreters.
2376
3107
2377
3108
Note that using this class directly is not cross-platform. For best
2378
3109
compatibility across platforms, always use the \function{Session()}
2554
3285
bsd db. You will need to check which implementation \module{anydbm}
2555
3286
defaults to on your system as some dbm libraries impose a limit on
2556
3287
the size of the entry making them unsuitable. Dbm caching can be
2557
enabled via \code{PSPDbmCache} Python option, e.g.:
3288
enabled via \code{mod_python.psp.cache_database_filename} Python
3289
option, e.g.:
2558
3290
2559
3291
\begin{verbatim}
2560
PythonOption PSPDbmCache ``/tmp/pspcache.dbm''
3292
PythonOption mod_python.psp.cache_database_filename ``/tmp/pspcache.dbm''
2561
3293
\end{verbatim}
2562
3294
Note that the dbm cache file is not deleted when the server
2563
3295
restarts.
2566
3298
cached in memory only. There is no option to cache in a dbm file at
2567
3299
this time.
2568
3300
2569
\begin{methoddesc}[PSP]{run}{\optional{vars}}
3301
Note that the above name for the option setting was only changed to
3302
this value in mod_python 3.3. If you need to retain backward compatability
3303
with older versions of mod_python use the \code{PSPDbmCache} option
3304
instead.
3305
3306
\begin{methoddesc}[PSP]{run}{\optional{vars, flush}}
2570
3307
This method will execute the code (produced at object
2571
3308
initialization time by parsing and compiling the PSP
2572
3309
source). Optional argument \var{vars} is a dictionary keyed by
2573
strings that will be passed in as global variables.
3310
strings that will be passed in as global variables. Optional
3311
argument \var{flush} is a boolean flag indicating whether output
3312
should be flushed. The default is not to flush output.
2574
3313
2575
3314
Additionally, the PSP code will be given global variables
2576
3315
\code{req}, \code{psp}, \code{session} and \code{form}. A session
2584
3323
referenced in the code.
2585
3324
2586
3325
The object passed in \code{psp} is an instance of
2587
\class{PSPInstance}.
3326
\class{PSPInterface}.
2588
3327
2589
3328
\end{methoddesc}
2590
3329
2616
3355
2617
3356
\end{classdesc}
2618
3357
2619
\begin{classdesc}{PSPInstance}{}
3358
\begin{classdesc}{PSPInterface}{}
2620
3359
An object of this class is passed as a global variable \code{psp} to
2621
3360
the PSP code. Objects of this class are instantiated internally and
2622
3361
the interface to \method{__init__} is purposely undocumented.
2623
3362
2624
\begin{methoddesc}[PSPInstance]{set_error_page}{filename}
3363
\begin{methoddesc}[PSPInterface]{set_error_page}{filename}
2625
3364
Used to set a psp page to be processed when an exception
2626
3365
occurs. If the path is absolute, it will be appended to document
2627
3366
root, otherwise the file is assumed to exist in the same directory
2630
3369
\code{sys.exc_info()}.
2631
3370
\end{methoddesc}
2632
3371
2633
\begin{methoddesc}[PSPInstance]{apply_data}{object\optional{, **kw}}
3372
\begin{methoddesc}[PSPInterface]{apply_data}{object\optional{, **kw}}
2634
3373
This method will call the callable object \var{object}, passing form
2635
3374
data as keyword arguments, and return the result.
2636
3375
\end{methoddesc}
2637
3376
2638
\begin{methoddesc}[PSPInstance]{redirect}{location\optional{, permanent=0}}
3377
\begin{methoddesc}[PSPInterface]{redirect}{location\optional{, permanent=0}}
2639
3378
This method will redirect the browser to location
2640
3379
\var{location}. If \var{permanent} is true, then
2641
3380
\constant{MOVED_PERMANENTLY} will be sent (as opposed to
Loggerhead is a web-based interface for Breezy
Version: 2.0.1