58 lines
2.6 KiB
TeX
58 lines
2.6 KiB
TeX
\section{\module{Bastion} ---
|
|
Restricting access to objects}
|
|
|
|
\declaremodule{standard}{Bastion}
|
|
\modulesynopsis{Providing restricted access to objects.}
|
|
\moduleauthor{Barry Warsaw}{bwarsaw@python.org}
|
|
\versionchanged[Disabled module]{2.3}
|
|
|
|
\begin{notice}[warning]
|
|
The documentation has been left in place to help in reading old code
|
|
that uses the module.
|
|
\end{notice}
|
|
|
|
% I'm concerned that the word 'bastion' won't be understood by people
|
|
% for whom English is a second language, making the module name
|
|
% somewhat mysterious. Thus, the brief definition... --amk
|
|
|
|
According to the dictionary, a bastion is ``a fortified area or
|
|
position'', or ``something that is considered a stronghold.'' It's a
|
|
suitable name for this module, which provides a way to forbid access
|
|
to certain attributes of an object. It must always be used with the
|
|
\refmodule{rexec} module, in order to allow restricted-mode programs
|
|
access to certain safe attributes of an object, while denying access
|
|
to other, unsafe attributes.
|
|
|
|
% I've punted on the issue of documenting keyword arguments for now.
|
|
|
|
\begin{funcdesc}{Bastion}{object\optional{, filter\optional{,
|
|
name\optional{, class}}}}
|
|
Protect the object \var{object}, returning a bastion for the
|
|
object. Any attempt to access one of the object's attributes will
|
|
have to be approved by the \var{filter} function; if the access is
|
|
denied an \exception{AttributeError} exception will be raised.
|
|
|
|
If present, \var{filter} must be a function that accepts a string
|
|
containing an attribute name, and returns true if access to that
|
|
attribute will be permitted; if \var{filter} returns false, the access
|
|
is denied. The default filter denies access to any function beginning
|
|
with an underscore (\character{_}). The bastion's string representation
|
|
will be \samp{<Bastion for \var{name}>} if a value for
|
|
\var{name} is provided; otherwise, \samp{repr(\var{object})} will be
|
|
used.
|
|
|
|
\var{class}, if present, should be a subclass of \class{BastionClass};
|
|
see the code in \file{bastion.py} for the details. Overriding the
|
|
default \class{BastionClass} will rarely be required.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{classdesc}{BastionClass}{getfunc, name}
|
|
Class which actually implements bastion objects. This is the default
|
|
class used by \function{Bastion()}. The \var{getfunc} parameter is a
|
|
function which returns the value of an attribute which should be
|
|
exposed to the restricted execution environment when called with the
|
|
name of the attribute as the only parameter. \var{name} is used to
|
|
construct the \function{repr()} of the \class{BastionClass} instance.
|
|
\end{classdesc}
|