linuxport: Merging in the fruits of my labors (Python VFS)
[xbmc:xbmc-antiquated.git] / xbmc / lib / libPython / Python / Doc / lib / libbastion.tex
1 \section{\module{Bastion} ---
2          Restricting access to objects}
3
4 \declaremodule{standard}{Bastion}
5 \modulesynopsis{Providing restricted access to objects.}
6 \moduleauthor{Barry Warsaw}{bwarsaw@python.org}
7 \versionchanged[Disabled module]{2.3}
8
9 \begin{notice}[warning]
10   The documentation has been left in place to help in reading old code
11   that uses the module.
12 \end{notice}
13
14 % I'm concerned that the word 'bastion' won't be understood by people
15 % for whom English is a second language, making the module name
16 % somewhat mysterious.  Thus, the brief definition... --amk
17
18 According to the dictionary, a bastion is ``a fortified area or
19 position'', or ``something that is considered a stronghold.''  It's a
20 suitable name for this module, which provides a way to forbid access
21 to certain attributes of an object.  It must always be used with the
22 \refmodule{rexec} module, in order to allow restricted-mode programs
23 access to certain safe attributes of an object, while denying access
24 to other, unsafe attributes.
25
26 % I've punted on the issue of documenting keyword arguments for now.
27
28 \begin{funcdesc}{Bastion}{object\optional{, filter\optional{,
29                           name\optional{, class}}}}
30 Protect the object \var{object}, returning a bastion for the
31 object.  Any attempt to access one of the object's attributes will
32 have to be approved by the \var{filter} function; if the access is
33 denied an \exception{AttributeError} exception will be raised.
34
35 If present, \var{filter} must be a function that accepts a string
36 containing an attribute name, and returns true if access to that
37 attribute will be permitted; if \var{filter} returns false, the access
38 is denied.  The default filter denies access to any function beginning
39 with an underscore (\character{_}).  The bastion's string representation
40 will be \samp{<Bastion for \var{name}>} if a value for
41 \var{name} is provided; otherwise, \samp{repr(\var{object})} will be
42 used.
43
44 \var{class}, if present, should be a subclass of \class{BastionClass}; 
45 see the code in \file{bastion.py} for the details.  Overriding the
46 default \class{BastionClass} will rarely be required.
47 \end{funcdesc}
48
49
50 \begin{classdesc}{BastionClass}{getfunc, name}
51 Class which actually implements bastion objects.  This is the default
52 class used by \function{Bastion()}.  The \var{getfunc} parameter is a
53 function which returns the value of an attribute which should be
54 exposed to the restricted execution environment when called with the
55 name of the attribute as the only parameter.  \var{name} is used to
56 construct the \function{repr()} of the \class{BastionClass} instance.
57 \end{classdesc}