\section{Standard Module \sectcode{rexec}}
\label{module-rexec}
\stmodindex{rexec}
-\setindexsubitem{(in module rexec)}
+
This module contains the \class{RExec} class, which supports
-\code{r_exec()}, \code{r_eval()}, \code{r_execfile()}, and
-\code{r_import()} methods, which are restricted versions of the standard
-Python functions \code{exec()}, \code{eval()}, \code{execfile()}, and
-the \code{import} statement.
+\method{r_exec()}, \method{r_eval()}, \method{r_execfile()}, and
+\method{r_import()} methods, which are restricted versions of the standard
+Python functions \method{exec()}, \method{eval()}, \method{execfile()}, and
+the \keyword{import} statement.
Code executed in this restricted environment will
only have access to modules and functions that are deemed safe; you
can subclass \class{RExec} to add or remove capabilities as desired.
sockets. However, it does not protect against code using extremely
large amounts of memory or CPU time.
-\begin{funcdesc}{RExec}{\optional{hooks\optional{\, verbose}}}
+\begin{classdesc}{RExec}{\optional{hooks\optional{, verbose}}}
Returns an instance of the \class{RExec} class.
-\var{hooks} is an instance of the \code{RHooks} class or a subclass of it.
-If it is omitted or \code{None}, the default \code{RHooks} class is
+\var{hooks} is an instance of the \class{RHooks} class or a subclass of it.
+If it is omitted or \code{None}, the default \class{RHooks} class is
instantiated.
Whenever the \module{RExec} module searches for a module (even a
built-in one) or reads a module's code, it doesn't actually go out to
If \var{verbose} is true, additional debugging output may be sent to
standard output.
-\end{funcdesc}
+\end{classdesc}
The \class{RExec} class has the following class attributes, which are
-used by the \code{__init__()} method. Changing them on an existing
+used by the \method{__init__()} method. Changing them on an existing
instance won't have any effect; instead, create a subclass of
\class{RExec} and assign them new values in the class definition.
Instances of the new class will then use those new values. All these
\end{datadesc}
\begin{datadesc}{ok_path}
-Contains the directories which will be searched when an \code{import}
+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.
\begin{datadesc}{ok_posix_names}
% Should this be called ok_os_names?
-Contains the names of the functions in the \code{os} module which will be
+Contains the names of the functions in the \module{os} module which will be
available to programs running in the restricted environment. The
value for \class{RExec} is \code{('error',} \code{'fstat',}
\code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',}
\end{datadesc}
\begin{datadesc}{ok_sys_names}
-Contains the names of the functions and variables in the \code{sys}
+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',}
\begin{funcdesc}{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 \code{__main__} module. The value of the expression or
+environment's \module{__main__} module. The value of the expression or
code object will be returned.
\end{funcdesc}
\begin{funcdesc}{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 \code{__main__} module.
+restricted environment's \module{__main__} module.
\end{funcdesc}
\begin{funcdesc}{r_execfile}{filename}
Execute the Python code contained in the file \var{filename} in the
-restricted environment's \code{__main__} module.
+restricted environment's \module{__main__} module.
\end{funcdesc}
-Methods whose names begin with \code{s_} are similar to the functions
-beginning with \code{r_}, but the code will be granted access to
+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}.
+\code{sys.stderr}, and \code{sys.stdout}.
\begin{funcdesc}{s_eval}{code}
\var{code} must be a string containing a Python expression, which will
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}}
-Import the module \var{modulename}, raising an \code{ImportError}
+\begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}}
+Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe.
\end{funcdesc}
\begin{funcdesc}{r_open}{filename\optional{\, mode\optional{\, bufsize}}}
-Method called when \code{open()} is called in the restricted
-environment. The arguments are identical to those of \code{open()},
+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)
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
-\code{r_open()}.
+\method{r_open()}.
\end{funcdesc}
\begin{funcdesc}{r_reload}{module}
Notice that the above code will occasionally forbid a perfectly valid
filename; for example, code in the restricted environment won't be
able to open a file called \file{/tmp/foo/../bar}. To fix this, the
-\code{r_open} method would have to simplify the filename to
+\method{r_open()} method would have to simplify the filename to
\file{/tmp/bar}, which would require splitting apart the filename and
performing various operations on it. In cases where security is at
stake, it may be preferable to write simple code which is sometimes
\section{Standard Module \sectcode{rexec}}
\label{module-rexec}
\stmodindex{rexec}
-\setindexsubitem{(in module rexec)}
+
This module contains the \class{RExec} class, which supports
-\code{r_exec()}, \code{r_eval()}, \code{r_execfile()}, and
-\code{r_import()} methods, which are restricted versions of the standard
-Python functions \code{exec()}, \code{eval()}, \code{execfile()}, and
-the \code{import} statement.
+\method{r_exec()}, \method{r_eval()}, \method{r_execfile()}, and
+\method{r_import()} methods, which are restricted versions of the standard
+Python functions \method{exec()}, \method{eval()}, \method{execfile()}, and
+the \keyword{import} statement.
Code executed in this restricted environment will
only have access to modules and functions that are deemed safe; you
can subclass \class{RExec} to add or remove capabilities as desired.
sockets. However, it does not protect against code using extremely
large amounts of memory or CPU time.
-\begin{funcdesc}{RExec}{\optional{hooks\optional{\, verbose}}}
+\begin{classdesc}{RExec}{\optional{hooks\optional{, verbose}}}
Returns an instance of the \class{RExec} class.
-\var{hooks} is an instance of the \code{RHooks} class or a subclass of it.
-If it is omitted or \code{None}, the default \code{RHooks} class is
+\var{hooks} is an instance of the \class{RHooks} class or a subclass of it.
+If it is omitted or \code{None}, the default \class{RHooks} class is
instantiated.
Whenever the \module{RExec} module searches for a module (even a
built-in one) or reads a module's code, it doesn't actually go out to
If \var{verbose} is true, additional debugging output may be sent to
standard output.
-\end{funcdesc}
+\end{classdesc}
The \class{RExec} class has the following class attributes, which are
-used by the \code{__init__()} method. Changing them on an existing
+used by the \method{__init__()} method. Changing them on an existing
instance won't have any effect; instead, create a subclass of
\class{RExec} and assign them new values in the class definition.
Instances of the new class will then use those new values. All these
\end{datadesc}
\begin{datadesc}{ok_path}
-Contains the directories which will be searched when an \code{import}
+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.
\begin{datadesc}{ok_posix_names}
% Should this be called ok_os_names?
-Contains the names of the functions in the \code{os} module which will be
+Contains the names of the functions in the \module{os} module which will be
available to programs running in the restricted environment. The
value for \class{RExec} is \code{('error',} \code{'fstat',}
\code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',}
\end{datadesc}
\begin{datadesc}{ok_sys_names}
-Contains the names of the functions and variables in the \code{sys}
+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',}
\begin{funcdesc}{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 \code{__main__} module. The value of the expression or
+environment's \module{__main__} module. The value of the expression or
code object will be returned.
\end{funcdesc}
\begin{funcdesc}{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 \code{__main__} module.
+restricted environment's \module{__main__} module.
\end{funcdesc}
\begin{funcdesc}{r_execfile}{filename}
Execute the Python code contained in the file \var{filename} in the
-restricted environment's \code{__main__} module.
+restricted environment's \module{__main__} module.
\end{funcdesc}
-Methods whose names begin with \code{s_} are similar to the functions
-beginning with \code{r_}, but the code will be granted access to
+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}.
+\code{sys.stderr}, and \code{sys.stdout}.
\begin{funcdesc}{s_eval}{code}
\var{code} must be a string containing a Python expression, which will
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}}
-Import the module \var{modulename}, raising an \code{ImportError}
+\begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}}
+Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe.
\end{funcdesc}
\begin{funcdesc}{r_open}{filename\optional{\, mode\optional{\, bufsize}}}
-Method called when \code{open()} is called in the restricted
-environment. The arguments are identical to those of \code{open()},
+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)
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
-\code{r_open()}.
+\method{r_open()}.
\end{funcdesc}
\begin{funcdesc}{r_reload}{module}
Notice that the above code will occasionally forbid a perfectly valid
filename; for example, code in the restricted environment won't be
able to open a file called \file{/tmp/foo/../bar}. To fix this, the
-\code{r_open} method would have to simplify the filename to
+\method{r_open()} method would have to simplify the filename to
\file{/tmp/bar}, which would require splitting apart the filename and
performing various operations on it. In cases where security is at
stake, it may be preferable to write simple code which is sometimes
projects / python / commitdiff