From da70ee1faec9dd8b6db974ac99c34b9ce470fbb0 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Thu, 2 Apr 1998 18:51:30 +0000 Subject: Use methoddesc and memberdesc, as needed. Added description of BastionClass, since it is referred to in the Bastion description as subclassable. --- Doc/lib/libbastion.tex | 17 ++++++++--- Doc/lib/librexec.tex | 77 +++++++++++++++++++++++++------------------------- Doc/libbastion.tex | 17 ++++++++--- Doc/librexec.tex | 77 +++++++++++++++++++++++++------------------------- 4 files changed, 104 insertions(+), 84 deletions(-) diff --git a/Doc/lib/libbastion.tex b/Doc/lib/libbastion.tex index c405c64..b5bec15 100644 --- a/Doc/lib/libbastion.tex +++ b/Doc/lib/libbastion.tex @@ -1,7 +1,6 @@ \section{Standard Module \sectcode{Bastion}} \label{module-Bastion} \stmodindex{Bastion} -\setindexsubitem{(in module Bastion)} % I'm concerned that the word 'bastion' won't be understood by people % for whom English is a second language, making the module name @@ -17,7 +16,8 @@ other, unsafe attributes. % I've punted on the issue of documenting keyword arguments for now. -\begin{funcdesc}{Bastion}{object\optional{, filter, name, class}} +\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 @@ -32,8 +32,17 @@ will be \samp{} if a value for \var{name} is provided; otherwise, \samp{repr(\var{object})} will be used. -\var{class}, if present, would be a subclass of \class{BastionClass}; +\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} diff --git a/Doc/lib/librexec.tex b/Doc/lib/librexec.tex index e301f81..03e8284 100644 --- a/Doc/lib/librexec.tex +++ b/Doc/lib/librexec.tex @@ -50,8 +50,7 @@ instance won't have any effect; instead, create a subclass of Instances of the new class will then use those new values. All these attributes are tuples of strings. -\setindexsubitem{(RExec object attribute)} -\begin{datadesc}{nok_builtin_names} +\begin{memberdesc}{nok_builtin_names} Contains the names of built-in functions which will \emph{not} be available to programs running in the restricted environment. The value for \class{RExec} is \code{('open',} \code{'reload',} @@ -61,9 +60,9 @@ override this variable should probably start with the value from the base class and concatenate additional forbidden functions --- when new dangerous built-in functions are added to Python, they will also be added to this module.) -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ok_builtin_modules} +\begin{memberdesc}{ok_builtin_modules} Contains the names of built-in modules which can be safely imported. The value for \class{RExec} is \code{('audioop',} \code{'array',} \code{'binascii',} \code{'cmath',} \code{'errno',} \code{'imageop',} @@ -72,16 +71,16 @@ The value for \class{RExec} is \code{('audioop',} \code{'array',} \code{'strop',} \code{'struct',} \code{'time')}. A similar remark about overriding this variable applies --- use the value from the base class as a starting point. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ok_path} +\begin{memberdesc}{ok_path} Contains the directories which will be searched when an \keyword{import} is performed in the restricted environment. The value for \class{RExec} is the same as \code{sys.path} (at the time the module is loaded) for unrestricted code. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ok_posix_names} +\begin{memberdesc}{ok_posix_names} % Should this be called ok_os_names? Contains the names of the functions in the \module{os} module which will be available to programs running in the restricted environment. The @@ -90,68 +89,69 @@ value for \class{RExec} is \code{('error',} \code{'fstat',} \code{'times',} \code{'uname',} \code{'getpid',} \code{'getppid',} \code{'getcwd',} \code{'getuid',} \code{'getgid',} \code{'geteuid',} \code{'getegid')}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ok_sys_names} +\begin{memberdesc}{ok_sys_names} Contains the names of the functions and variables in the \module{sys} module which will be available to programs running in the restricted environment. The value for \class{RExec} is \code{('ps1',} \code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',} \code{'exit',} \code{'maxint')}. -\end{datadesc} +\end{memberdesc} + \class{RExec} instances support the following methods: -\setindexsubitem{(RExec object method)} -\begin{funcdesc}{r_eval}{code} +\begin{methoddesc}{r_eval}{code} \var{code} must either be a string containing a Python expression, or a compiled code object, which will be evaluated in the restricted environment's \module{__main__} module. The value of the expression or code object will be returned. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_exec}{code} +\begin{methoddesc}{r_exec}{code} \var{code} must either be a string containing one or more lines of Python code, or a compiled code object, which will be executed in the restricted environment's \module{__main__} module. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_execfile}{filename} +\begin{methoddesc}{r_execfile}{filename} Execute the Python code contained in the file \var{filename} in the restricted environment's \module{__main__} module. -\end{funcdesc} +\end{methoddesc} Methods whose names begin with \samp{s_} are similar to the functions beginning with \samp{r_}, but the code will be granted access to restricted versions of the standard I/O streams \code{sys.stdin}, \code{sys.stderr}, and \code{sys.stdout}. -\begin{funcdesc}{s_eval}{code} +\begin{methoddesc}{s_eval}{code} \var{code} must be a string containing a Python expression, which will be evaluated in the restricted environment. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{s_exec}{code} +\begin{methoddesc}{s_exec}{code} \var{code} must be a string containing one or more lines of Python code, which will be executed in the restricted environment. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{s_execfile}{code} +\begin{methoddesc}{s_execfile}{code} Execute the Python code contained in the file \var{filename} in the restricted environment. -\end{funcdesc} +\end{methoddesc} \class{RExec} objects must also support various methods which will be implicitly called by code executing in the restricted environment. Overriding these methods in a subclass is used to change the policies enforced by a restricted environment. -\begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}} +\begin{methoddesc}{r_import}{modulename\optional{, globals\optional{, + locals\optional{, fromlist}}}} Import the module \var{modulename}, raising an \exception{ImportError} exception if the module is considered unsafe. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_open}{filename\optional{, mode\optional{, bufsize}}} +\begin{methoddesc}{r_open}{filename\optional{, mode\optional{, bufsize}}} Method called when \function{open()} is called in the restricted environment. The arguments are identical to those of \function{open()}, and a file object (or a class instance compatible with file objects) @@ -159,32 +159,33 @@ should be returned. \class{RExec}'s default behaviour is allow opening any file for reading, but forbidding any attempt to write a file. See the example below for an implementation of a less restrictive \method{r_open()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_reload}{module} +\begin{methoddesc}{r_reload}{module} Reload the module object \var{module}, re-parsing and re-initializing it. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_unload}{module} +\begin{methoddesc}{r_unload}{module} Unload the module object \var{module} (i.e., remove it from the restricted environment's \code{sys.modules} dictionary). -\end{funcdesc} +\end{methoddesc} And their equivalents with access to restricted standard I/O streams: -\begin{funcdesc}{s_import}{modulename\optional{, globals, locals, fromlist}} +\begin{methoddesc}{s_import}{modulename\optional{, globals\optional{, + locals\optional{, fromlist}}}} Import the module \var{modulename}, raising an \exception{ImportError} exception if the module is considered unsafe. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{s_reload}{module} +\begin{methoddesc}{s_reload}{module} Reload the module object \var{module}, re-parsing and re-initializing it. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{s_unload}{module} +\begin{methoddesc}{s_unload}{module} Unload the module object \var{module}. % XXX what are the semantics of this? -\end{funcdesc} +\end{methoddesc} \subsection{An example} diff --git a/Doc/libbastion.tex b/Doc/libbastion.tex index c405c64..b5bec15 100644 --- a/Doc/libbastion.tex +++ b/Doc/libbastion.tex @@ -1,7 +1,6 @@ \section{Standard Module \sectcode{Bastion}} \label{module-Bastion} \stmodindex{Bastion} -\setindexsubitem{(in module Bastion)} % I'm concerned that the word 'bastion' won't be understood by people % for whom English is a second language, making the module name @@ -17,7 +16,8 @@ other, unsafe attributes. % I've punted on the issue of documenting keyword arguments for now. -\begin{funcdesc}{Bastion}{object\optional{, filter, name, class}} +\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 @@ -32,8 +32,17 @@ will be \samp{} if a value for \var{name} is provided; otherwise, \samp{repr(\var{object})} will be used. -\var{class}, if present, would be a subclass of \class{BastionClass}; +\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} diff --git a/Doc/librexec.tex b/Doc/librexec.tex index e301f81..03e8284 100644 --- a/Doc/librexec.tex +++ b/Doc/librexec.tex @@ -50,8 +50,7 @@ instance won't have any effect; instead, create a subclass of Instances of the new class will then use those new values. All these attributes are tuples of strings. -\setindexsubitem{(RExec object attribute)} -\begin{datadesc}{nok_builtin_names} +\begin{memberdesc}{nok_builtin_names} Contains the names of built-in functions which will \emph{not} be available to programs running in the restricted environment. The value for \class{RExec} is \code{('open',} \code{'reload',} @@ -61,9 +60,9 @@ override this variable should probably start with the value from the base class and concatenate additional forbidden functions --- when new dangerous built-in functions are added to Python, they will also be added to this module.) -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ok_builtin_modules} +\begin{memberdesc}{ok_builtin_modules} Contains the names of built-in modules which can be safely imported. The value for \class{RExec} is \code{('audioop',} \code{'array',} \code{'binascii',} \code{'cmath',} \code{'errno',} \code{'imageop',} @@ -72,16 +71,16 @@ The value for \class{RExec} is \code{('audioop',} \code{'array',} \code{'strop',} \code{'struct',} \code{'time')}. A similar remark about overriding this variable applies --- use the value from the base class as a starting point. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ok_path} +\begin{memberdesc}{ok_path} Contains the directories which will be searched when an \keyword{import} is performed in the restricted environment. The value for \class{RExec} is the same as \code{sys.path} (at the time the module is loaded) for unrestricted code. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ok_posix_names} +\begin{memberdesc}{ok_posix_names} % Should this be called ok_os_names? Contains the names of the functions in the \module{os} module which will be available to programs running in the restricted environment. The @@ -90,68 +89,69 @@ value for \class{RExec} is \code{('error',} \code{'fstat',} \code{'times',} \code{'uname',} \code{'getpid',} \code{'getppid',} \code{'getcwd',} \code{'getuid',} \code{'getgid',} \code{'geteuid',} \code{'getegid')}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ok_sys_names} +\begin{memberdesc}{ok_sys_names} Contains the names of the functions and variables in the \module{sys} module which will be available to programs running in the restricted environment. The value for \class{RExec} is \code{('ps1',} \code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',} \code{'exit',} \code{'maxint')}. -\end{datadesc} +\end{memberdesc} + \class{RExec} instances support the following methods: -\setindexsubitem{(RExec object method)} -\begin{funcdesc}{r_eval}{code} +\begin{methoddesc}{r_eval}{code} \var{code} must either be a string containing a Python expression, or a compiled code object, which will be evaluated in the restricted environment's \module{__main__} module. The value of the expression or code object will be returned. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_exec}{code} +\begin{methoddesc}{r_exec}{code} \var{code} must either be a string containing one or more lines of Python code, or a compiled code object, which will be executed in the restricted environment's \module{__main__} module. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_execfile}{filename} +\begin{methoddesc}{r_execfile}{filename} Execute the Python code contained in the file \var{filename} in the restricted environment's \module{__main__} module. -\end{funcdesc} +\end{methoddesc} Methods whose names begin with \samp{s_} are similar to the functions beginning with \samp{r_}, but the code will be granted access to restricted versions of the standard I/O streams \code{sys.stdin}, \code{sys.stderr}, and \code{sys.stdout}. -\begin{funcdesc}{s_eval}{code} +\begin{methoddesc}{s_eval}{code} \var{code} must be a string containing a Python expression, which will be evaluated in the restricted environment. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{s_exec}{code} +\begin{methoddesc}{s_exec}{code} \var{code} must be a string containing one or more lines of Python code, which will be executed in the restricted environment. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{s_execfile}{code} +\begin{methoddesc}{s_execfile}{code} Execute the Python code contained in the file \var{filename} in the restricted environment. -\end{funcdesc} +\end{methoddesc} \class{RExec} objects must also support various methods which will be implicitly called by code executing in the restricted environment. Overriding these methods in a subclass is used to change the policies enforced by a restricted environment. -\begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}} +\begin{methoddesc}{r_import}{modulename\optional{, globals\optional{, + locals\optional{, fromlist}}}} Import the module \var{modulename}, raising an \exception{ImportError} exception if the module is considered unsafe. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_open}{filename\optional{, mode\optional{, bufsize}}} +\begin{methoddesc}{r_open}{filename\optional{, mode\optional{, bufsize}}} Method called when \function{open()} is called in the restricted environment. The arguments are identical to those of \function{open()}, and a file object (or a class instance compatible with file objects) @@ -159,32 +159,33 @@ should be returned. \class{RExec}'s default behaviour is allow opening any file for reading, but forbidding any attempt to write a file. See the example below for an implementation of a less restrictive \method{r_open()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_reload}{module} +\begin{methoddesc}{r_reload}{module} Reload the module object \var{module}, re-parsing and re-initializing it. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{r_unload}{module} +\begin{methoddesc}{r_unload}{module} Unload the module object \var{module} (i.e., remove it from the restricted environment's \code{sys.modules} dictionary). -\end{funcdesc} +\end{methoddesc} And their equivalents with access to restricted standard I/O streams: -\begin{funcdesc}{s_import}{modulename\optional{, globals, locals, fromlist}} +\begin{methoddesc}{s_import}{modulename\optional{, globals\optional{, + locals\optional{, fromlist}}}} Import the module \var{modulename}, raising an \exception{ImportError} exception if the module is considered unsafe. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{s_reload}{module} +\begin{methoddesc}{s_reload}{module} Reload the module object \var{module}, re-parsing and re-initializing it. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{s_unload}{module} +\begin{methoddesc}{s_unload}{module} Unload the module object \var{module}. % XXX what are the semantics of this? -\end{funcdesc} +\end{methoddesc} \subsection{An example} -- cgit v0.12