Skip to content

C
cpython
Kaydet (Commit) a8912306 authored tarafından Fred Drake's avatar Fred Drake
Dosyalara gözat
Seçenekler

Logical markup, using {classdesc} as appropriate.

üst f9e1f658
Hide whitespace changes
Inline Side-by-side
Showing with 50 additions and 50 deletions
Doc/lib/librexec.tex
Dosyayı görüntüle @ a8912306
\section{Standard Module \sectcode{rexec}} \section{Standard Module \sectcode{rexec}}
\label{module-rexec} \label{module-rexec}
\stmodindex{rexec} \stmodindex{rexec}
\setindexsubitem{(in module rexec)}
This module contains the \class{RExec} class, which supports This module contains the \class{RExec} class, which supports
\code{r_exec()}, \code{r_eval()}, \code{r_execfile()}, and \method{r_exec()}, \method{r_eval()}, \method{r_execfile()}, and
\code{r_import()} methods, which are restricted versions of the standard \method{r_import()} methods, which are restricted versions of the standard
Python functions \code{exec()}, \code{eval()}, \code{execfile()}, and Python functions \method{exec()}, \method{eval()}, \method{execfile()}, and
the \code{import} statement. the \keyword{import} statement.
Code executed in this restricted environment will Code executed in this restricted environment will
only have access to modules and functions that are deemed safe; you only have access to modules and functions that are deemed safe; you
can subclass \class{RExec} to add or remove capabilities as desired. can subclass \class{RExec} to add or remove capabilities as desired.
...@@ -17,11 +17,11 @@ unsafe operations like reading or writing disk files, or using TCP/IP ...@@ -17,11 +17,11 @@ unsafe operations like reading or writing disk files, or using TCP/IP
sockets. However, it does not protect against code using extremely sockets. However, it does not protect against code using extremely
large amounts of memory or CPU time. 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. Returns an instance of the \class{RExec} class.
\var{hooks} is an instance of the \code{RHooks} class or a subclass of it. \var{hooks} is an instance of the \class{RHooks} class or a subclass of it.
If it is omitted or \code{None}, the default \code{RHooks} class is If it is omitted or \code{None}, the default \class{RHooks} class is
instantiated. instantiated.
Whenever the \module{RExec} module searches for a module (even a 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 built-in one) or reads a module's code, it doesn't actually go out to
...@@ -41,10 +41,10 @@ importing applets from a URL for a directory. ...@@ -41,10 +41,10 @@ importing applets from a URL for a directory.
If \var{verbose} is true, additional debugging output may be sent to If \var{verbose} is true, additional debugging output may be sent to
standard output. standard output.
\end{funcdesc} \end{classdesc}
The \class{RExec} class has the following class attributes, which are 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 instance won't have any effect; instead, create a subclass of
\class{RExec} and assign them new values in the class definition. \class{RExec} and assign them new values in the class definition.
Instances of the new class will then use those new values. All these Instances of the new class will then use those new values. All these
...@@ -75,7 +75,7 @@ class as a starting point. ...@@ -75,7 +75,7 @@ class as a starting point.
\end{datadesc} \end{datadesc}
\begin{datadesc}{ok_path} \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. is performed in the restricted environment.
The value for \class{RExec} is the same as \code{sys.path} (at the time The value for \class{RExec} is the same as \code{sys.path} (at the time
the module is loaded) for unrestricted code. the module is loaded) for unrestricted code.
...@@ -83,7 +83,7 @@ the module is loaded) for unrestricted code. ...@@ -83,7 +83,7 @@ the module is loaded) for unrestricted code.
\begin{datadesc}{ok_posix_names} \begin{datadesc}{ok_posix_names}
% Should this be called ok_os_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 available to programs running in the restricted environment. The
value for \class{RExec} is \code{('error',} \code{'fstat',} value for \class{RExec} is \code{('error',} \code{'fstat',}
\code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',} \code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',}
...@@ -93,7 +93,7 @@ value for \class{RExec} is \code{('error',} \code{'fstat',} ...@@ -93,7 +93,7 @@ value for \class{RExec} is \code{('error',} \code{'fstat',}
\end{datadesc} \end{datadesc}
\begin{datadesc}{ok_sys_names} \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 module which will be available to programs running in the restricted
environment. The value for \class{RExec} is \code{('ps1',} environment. The value for \class{RExec} is \code{('ps1',}
\code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',} \code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',}
...@@ -106,25 +106,25 @@ environment. The value for \class{RExec} is \code{('ps1',} ...@@ -106,25 +106,25 @@ environment. The value for \class{RExec} is \code{('ps1',}
\begin{funcdesc}{r_eval}{code} \begin{funcdesc}{r_eval}{code}
\var{code} must either be a string containing a Python expression, or \var{code} must either be a string containing a Python expression, or
a compiled code object, which will be evaluated in the restricted 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. code object will be returned.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{r_exec}{code} \begin{funcdesc}{r_exec}{code}
\var{code} must either be a string containing one or more lines of \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 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} \end{funcdesc}
\begin{funcdesc}{r_execfile}{filename} \begin{funcdesc}{r_execfile}{filename}
Execute the Python code contained in the file \var{filename} in the 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} \end{funcdesc}
Methods whose names begin with \code{s_} are similar to the functions Methods whose names begin with \samp{s_} are similar to the functions
beginning with \code{r_}, but the code will be granted access to beginning with \samp{r_}, but the code will be granted access to
restricted versions of the standard I/O streams \code{sys.stdin}, 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} \begin{funcdesc}{s_eval}{code}
\var{code} must be a string containing a Python expression, which will \var{code} must be a string containing a Python expression, which will
...@@ -146,19 +146,19 @@ implicitly called by code executing in the restricted environment. ...@@ -146,19 +146,19 @@ implicitly called by code executing in the restricted environment.
Overriding these methods in a subclass is used to change the policies Overriding these methods in a subclass is used to change the policies
enforced by a restricted environment. enforced by a restricted environment.
\begin{funcdesc}{r_import}{modulename\optional{\, globals\, locals\, fromlist}} \begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}}
Import the module \var{modulename}, raising an \code{ImportError} Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe. exception if the module is considered unsafe.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{r_open}{filename\optional{\, mode\optional{\, bufsize}}} \begin{funcdesc}{r_open}{filename\optional{\, mode\optional{\, bufsize}}}
Method called when \code{open()} is called in the restricted Method called when \function{open()} is called in the restricted
environment. The arguments are identical to those of \code{open()}, environment. The arguments are identical to those of \function{open()},
and a file object (or a class instance compatible with file objects) and a file object (or a class instance compatible with file objects)
should be returned. \class{RExec}'s default behaviour is allow opening should be returned. \class{RExec}'s default behaviour is allow opening
any file for reading, but forbidding any attempt to write a file. See any file for reading, but forbidding any attempt to write a file. See
the example below for an implementation of a less restrictive the example below for an implementation of a less restrictive
\code{r_open()}. \method{r_open()}.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{r_reload}{module} \begin{funcdesc}{r_reload}{module}
...@@ -212,7 +212,7 @@ class TmpWriterRExec(rexec.RExec): ...@@ -212,7 +212,7 @@ class TmpWriterRExec(rexec.RExec):
Notice that the above code will occasionally forbid a perfectly valid Notice that the above code will occasionally forbid a perfectly valid
filename; for example, code in the restricted environment won't be 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 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 \file{/tmp/bar}, which would require splitting apart the filename and
performing various operations on it. In cases where security is at performing various operations on it. In cases where security is at
stake, it may be preferable to write simple code which is sometimes stake, it may be preferable to write simple code which is sometimes
......
Doc/librexec.tex
Dosyayı görüntüle @ a8912306
\section{Standard Module \sectcode{rexec}} \section{Standard Module \sectcode{rexec}}
\label{module-rexec} \label{module-rexec}
\stmodindex{rexec} \stmodindex{rexec}
\setindexsubitem{(in module rexec)}
This module contains the \class{RExec} class, which supports This module contains the \class{RExec} class, which supports
\code{r_exec()}, \code{r_eval()}, \code{r_execfile()}, and \method{r_exec()}, \method{r_eval()}, \method{r_execfile()}, and
\code{r_import()} methods, which are restricted versions of the standard \method{r_import()} methods, which are restricted versions of the standard
Python functions \code{exec()}, \code{eval()}, \code{execfile()}, and Python functions \method{exec()}, \method{eval()}, \method{execfile()}, and
the \code{import} statement. the \keyword{import} statement.
Code executed in this restricted environment will Code executed in this restricted environment will
only have access to modules and functions that are deemed safe; you only have access to modules and functions that are deemed safe; you
can subclass \class{RExec} to add or remove capabilities as desired. can subclass \class{RExec} to add or remove capabilities as desired.
...@@ -17,11 +17,11 @@ unsafe operations like reading or writing disk files, or using TCP/IP ...@@ -17,11 +17,11 @@ unsafe operations like reading or writing disk files, or using TCP/IP
sockets. However, it does not protect against code using extremely sockets. However, it does not protect against code using extremely
large amounts of memory or CPU time. 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. Returns an instance of the \class{RExec} class.
\var{hooks} is an instance of the \code{RHooks} class or a subclass of it. \var{hooks} is an instance of the \class{RHooks} class or a subclass of it.
If it is omitted or \code{None}, the default \code{RHooks} class is If it is omitted or \code{None}, the default \class{RHooks} class is
instantiated. instantiated.
Whenever the \module{RExec} module searches for a module (even a 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 built-in one) or reads a module's code, it doesn't actually go out to
...@@ -41,10 +41,10 @@ importing applets from a URL for a directory. ...@@ -41,10 +41,10 @@ importing applets from a URL for a directory.
If \var{verbose} is true, additional debugging output may be sent to If \var{verbose} is true, additional debugging output may be sent to
standard output. standard output.
\end{funcdesc} \end{classdesc}
The \class{RExec} class has the following class attributes, which are 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 instance won't have any effect; instead, create a subclass of
\class{RExec} and assign them new values in the class definition. \class{RExec} and assign them new values in the class definition.
Instances of the new class will then use those new values. All these Instances of the new class will then use those new values. All these
...@@ -75,7 +75,7 @@ class as a starting point. ...@@ -75,7 +75,7 @@ class as a starting point.
\end{datadesc} \end{datadesc}
\begin{datadesc}{ok_path} \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. is performed in the restricted environment.
The value for \class{RExec} is the same as \code{sys.path} (at the time The value for \class{RExec} is the same as \code{sys.path} (at the time
the module is loaded) for unrestricted code. the module is loaded) for unrestricted code.
...@@ -83,7 +83,7 @@ the module is loaded) for unrestricted code. ...@@ -83,7 +83,7 @@ the module is loaded) for unrestricted code.
\begin{datadesc}{ok_posix_names} \begin{datadesc}{ok_posix_names}
% Should this be called ok_os_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 available to programs running in the restricted environment. The
value for \class{RExec} is \code{('error',} \code{'fstat',} value for \class{RExec} is \code{('error',} \code{'fstat',}
\code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',} \code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',}
...@@ -93,7 +93,7 @@ value for \class{RExec} is \code{('error',} \code{'fstat',} ...@@ -93,7 +93,7 @@ value for \class{RExec} is \code{('error',} \code{'fstat',}
\end{datadesc} \end{datadesc}
\begin{datadesc}{ok_sys_names} \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 module which will be available to programs running in the restricted
environment. The value for \class{RExec} is \code{('ps1',} environment. The value for \class{RExec} is \code{('ps1',}
\code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',} \code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',}
...@@ -106,25 +106,25 @@ environment. The value for \class{RExec} is \code{('ps1',} ...@@ -106,25 +106,25 @@ environment. The value for \class{RExec} is \code{('ps1',}
\begin{funcdesc}{r_eval}{code} \begin{funcdesc}{r_eval}{code}
\var{code} must either be a string containing a Python expression, or \var{code} must either be a string containing a Python expression, or
a compiled code object, which will be evaluated in the restricted 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. code object will be returned.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{r_exec}{code} \begin{funcdesc}{r_exec}{code}
\var{code} must either be a string containing one or more lines of \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 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} \end{funcdesc}
\begin{funcdesc}{r_execfile}{filename} \begin{funcdesc}{r_execfile}{filename}
Execute the Python code contained in the file \var{filename} in the 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} \end{funcdesc}
Methods whose names begin with \code{s_} are similar to the functions Methods whose names begin with \samp{s_} are similar to the functions
beginning with \code{r_}, but the code will be granted access to beginning with \samp{r_}, but the code will be granted access to
restricted versions of the standard I/O streams \code{sys.stdin}, 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} \begin{funcdesc}{s_eval}{code}
\var{code} must be a string containing a Python expression, which will \var{code} must be a string containing a Python expression, which will
...@@ -146,19 +146,19 @@ implicitly called by code executing in the restricted environment. ...@@ -146,19 +146,19 @@ implicitly called by code executing in the restricted environment.
Overriding these methods in a subclass is used to change the policies Overriding these methods in a subclass is used to change the policies
enforced by a restricted environment. enforced by a restricted environment.
\begin{funcdesc}{r_import}{modulename\optional{\, globals\, locals\, fromlist}} \begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}}
Import the module \var{modulename}, raising an \code{ImportError} Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe. exception if the module is considered unsafe.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{r_open}{filename\optional{\, mode\optional{\, bufsize}}} \begin{funcdesc}{r_open}{filename\optional{\, mode\optional{\, bufsize}}}
Method called when \code{open()} is called in the restricted Method called when \function{open()} is called in the restricted
environment. The arguments are identical to those of \code{open()}, environment. The arguments are identical to those of \function{open()},
and a file object (or a class instance compatible with file objects) and a file object (or a class instance compatible with file objects)
should be returned. \class{RExec}'s default behaviour is allow opening should be returned. \class{RExec}'s default behaviour is allow opening
any file for reading, but forbidding any attempt to write a file. See any file for reading, but forbidding any attempt to write a file. See
the example below for an implementation of a less restrictive the example below for an implementation of a less restrictive
\code{r_open()}. \method{r_open()}.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{r_reload}{module} \begin{funcdesc}{r_reload}{module}
...@@ -212,7 +212,7 @@ class TmpWriterRExec(rexec.RExec): ...@@ -212,7 +212,7 @@ class TmpWriterRExec(rexec.RExec):
Notice that the above code will occasionally forbid a perfectly valid Notice that the above code will occasionally forbid a perfectly valid
filename; for example, code in the restricted environment won't be 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 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 \file{/tmp/bar}, which would require splitting apart the filename and
performing various operations on it. In cases where security is at performing various operations on it. In cases where security is at
stake, it may be preferable to write simple code which is sometimes stake, it may be preferable to write simple code which is sometimes
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment