Doc/libbastion.tex

   1 \section{Standard Module \module{Bastion}}
   2 \label{module-Bastion}
   3 \stmodindex{Bastion}
   4
   5 % I'm concerned that the word 'bastion' won't be understood by people
   6 % for whom English is a second language, making the module name
   7 % somewhat mysterious.  Thus, the brief definition... --amk
   8
   9 According to the dictionary, a bastion is ``a fortified area or
  10 position'', or ``something that is considered a stronghold.''  It's a
  11 suitable name for this module, which provides a way to forbid access
  12 to certain attributes of an object.  It must always be used with the
  13 \module{rexec} module, in order to allow restricted-mode programs access
  14 to certain safe attributes of an object, while denying access to
  15 other, unsafe attributes.
  16
  17 % I've punted on the issue of documenting keyword arguments for now.
  18
  19 \begin{funcdesc}{Bastion}{object\optional{, filter\optional{,
  20                           name\optional{, class}}}}
  21 Protect the object \var{object}, returning a bastion for the
  22 object.  Any attempt to access one of the object's attributes will
  23 have to be approved by the \var{filter} function; if the access is
  24 denied an \exception{AttributeError} exception will be raised.
  25
  26 If present, \var{filter} must be a function that accepts a string
  27 containing an attribute name, and returns true if access to that
  28 attribute will be permitted; if \var{filter} returns false, the access
  29 is denied.  The default filter denies access to any function beginning
  30 with an underscore (\samp{_}).  The bastion's string representation
  31 will be \samp{<Bastion for \var{name}>} if a value for
  32 \var{name} is provided; otherwise, \samp{repr(\var{object})} will be
  33 used.
  34
  35 \var{class}, if present, should be a subclass of \class{BastionClass};
  36 see the code in \file{bastion.py} for the details.  Overriding the
  37 default \class{BastionClass} will rarely be required.
  38 \end{funcdesc}
  39
  40
  41 \begin{classdesc}{BastionClass}{getfunc, name}
  42 Class which actually implements bastion objects.  This is the default
  43 class used by \function{Bastion()}.  The \var{getfunc} parameter is a
  44 function which returns the value of an attribute which should be
  45 exposed to the restricted execution environment when called with the
  46 name of the attribute as the only parameter.  \var{name} is used to
  47 construct the \function{repr()} of the \class{BastionClass} instance.
  48 \end{classdesc}