Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/librexec.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 376ee174ecd0
children cffd091f56d0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{rexec} ---
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
2 Restricted execution framework}
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8275
diff changeset
4 \declaremodule{standard}{rexec}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8275
diff changeset
5 \modulesynopsis{Basic restricted execution framework.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8275
diff changeset
6
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
7
4259
dbb76095adee Added bastion and (dummy) rexec docs
Guido van Rossum <guido@python.org>
parents:
diff changeset
8
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
9 This module contains the \class{RExec} class, which supports
8275
7b25006579f4 exec is a statement, not a function!
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
10 \method{r_eval()}, \method{r_execfile()}, \method{r_exec()}, and
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
11 \method{r_import()} methods, which are restricted versions of the standard
8275
7b25006579f4 exec is a statement, not a function!
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
12 Python functions \method{eval()}, \method{execfile()} and
7b25006579f4 exec is a statement, not a function!
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
13 the \keyword{exec} and \keyword{import} statements.
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
14 Code executed in this restricted environment will
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
15 only have access to modules and functions that are deemed safe; you
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
16 can subclass \class{RExec} to add or remove capabilities as desired.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
17
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
18 \note{The \class{RExec} class can prevent code from performing
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
19 unsafe operations like reading or writing disk files, or using TCP/IP
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
20 sockets. However, it does not protect against code using extremely
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
21 large amounts of memory or processor time.}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
22
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
23 \begin{classdesc}{RExec}{\optional{hooks\optional{, verbose}}}
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
24 Returns an instance of the \class{RExec} class.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
25
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
26 \var{hooks} is an instance of the \class{RHooks} class or a subclass of it.
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
27 If it is omitted or \code{None}, the default \class{RHooks} class is
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
28 instantiated.
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
29 Whenever the \module{rexec} module searches for a module (even a
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
30 built-in one) or reads a module's code, it doesn't actually go out to
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
31 the file system itself. Rather, it calls methods of an \class{RHooks}
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
32 instance that was passed to or created by its constructor. (Actually,
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
33 the \class{RExec} object doesn't make these calls --- they are made by
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
34 a module loader object that's part of the \class{RExec} object. This
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18225
diff changeset
35 allows another level of flexibility, which can be useful when changing
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18225
diff changeset
36 the mechanics of \keyword{import} within the restricted environment.)
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
37
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
38 By providing an alternate \class{RHooks} object, we can control the
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
39 file system accesses made to import a module, without changing the
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
40 actual algorithm that controls the order in which those accesses are
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
41 made. For instance, we could substitute an \class{RHooks} object that
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
42 passes all filesystem requests to a file server elsewhere, via some
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
43 RPC mechanism such as ILU. Grail's applet loader uses this to support
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
44 importing applets from a URL for a directory.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
45
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
46 If \var{verbose} is true, additional debugging output may be sent to
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
47 standard output.
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
48 \end{classdesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
49
18225
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
50 It is important to be aware that code running in a restricted
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
51 environment can still call the \function{sys.exit()} function. To
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
52 disallow restricted code from exiting the interpreter, always protect
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
53 calls that cause restricted code to run with a
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
54 \keyword{try}/\keyword{except} statement that catches the
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
55 \exception{SystemExit} exception. Removing the \function{sys.exit()}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
56 function from the restricted environment is not sufficient --- the
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
57 restricted code could still use \code{raise SystemExit}. Removing
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
58 \exception{SystemExit} is not a reasonable option; some library code
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
59 makes use of this and would break were it not available.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
60
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
61
18225
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
62 \begin{seealso}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
63 \seetitle[http://grail.sourceforge.net/]{Grail Home Page}{Grail is a
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
64 Web browser written entirely in Python. It uses the
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
65 \module{rexec} module as a foundation for supporting
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
66 Python applets, and can be used as an example usage of
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
67 this module.}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
68 \end{seealso}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
69
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
70
18225
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
71 \subsection{RExec Objects \label{rexec-objects}}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
72
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
73 \class{RExec} instances support the following methods:
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
74
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
75 \begin{methoddesc}{r_eval}{code}
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
76 \var{code} must either be a string containing a Python expression, or
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
77 a compiled code object, which will be evaluated in the restricted
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
78 environment's \module{__main__} module. The value of the expression or
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
79 code object will be returned.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
80 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
81
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
82 \begin{methoddesc}{r_exec}{code}
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
83 \var{code} must either be a string containing one or more lines of
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
84 Python code, or a compiled code object, which will be executed in the
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
85 restricted environment's \module{__main__} module.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
86 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
87
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
88 \begin{methoddesc}{r_execfile}{filename}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
89 Execute the Python code contained in the file \var{filename} in the
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
90 restricted environment's \module{__main__} module.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
91 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
92
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
93 Methods whose names begin with \samp{s_} are similar to the functions
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
94 beginning with \samp{r_}, but the code will be granted access to
7454
1b4a2e38ab5e "streans" --> "streams" (AMK)
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
95 restricted versions of the standard I/O streams \code{sys.stdin},
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
96 \code{sys.stderr}, and \code{sys.stdout}.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
97
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
98 \begin{methoddesc}{s_eval}{code}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
99 \var{code} must be a string containing a Python expression, which will
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
100 be evaluated in the restricted environment.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
101 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
102
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
103 \begin{methoddesc}{s_exec}{code}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
104 \var{code} must be a string containing one or more lines of Python code,
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
105 which will be executed in the restricted environment.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
106 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
107
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
108 \begin{methoddesc}{s_execfile}{code}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
109 Execute the Python code contained in the file \var{filename} in the
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
110 restricted environment.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
111 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
112
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
113 \class{RExec} objects must also support various methods which will be
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
114 implicitly called by code executing in the restricted environment.
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
115 Overriding these methods in a subclass is used to change the policies
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
116 enforced by a restricted environment.
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
117
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
118 \begin{methoddesc}{r_import}{modulename\optional{, globals\optional{,
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
119 locals\optional{, fromlist}}}}
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
120 Import the module \var{modulename}, raising an \exception{ImportError}
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
121 exception if the module is considered unsafe.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
122 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
123
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
124 \begin{methoddesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
125 Method called when \function{open()} is called in the restricted
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
126 environment. The arguments are identical to those of \function{open()},
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
127 and a file object (or a class instance compatible with file objects)
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
128 should be returned. \class{RExec}'s default behaviour is allow opening
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
129 any file for reading, but forbidding any attempt to write a file. See
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
130 the example below for an implementation of a less restrictive
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
131 \method{r_open()}.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
132 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
133
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
134 \begin{methoddesc}{r_reload}{module}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
135 Reload the module object \var{module}, re-parsing and re-initializing it.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
136 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
137
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
138 \begin{methoddesc}{r_unload}{module}
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18225
diff changeset
139 Unload the module object \var{module} (remove it from the
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
140 restricted environment's \code{sys.modules} dictionary).
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
141 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
142
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
143 And their equivalents with access to restricted standard I/O streams:
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
144
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
145 \begin{methoddesc}{s_import}{modulename\optional{, globals\optional{,
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
146 locals\optional{, fromlist}}}}
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
147 Import the module \var{modulename}, raising an \exception{ImportError}
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
148 exception if the module is considered unsafe.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
149 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
150
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
151 \begin{methoddesc}{s_reload}{module}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
152 Reload the module object \var{module}, re-parsing and re-initializing it.
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
153 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
154
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
155 \begin{methoddesc}{s_unload}{module}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
156 Unload the module object \var{module}.
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
157 % XXX what are the semantics of this?
7794
375a901065c1 Use methoddesc and memberdesc, as needed.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
158 \end{methoddesc}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
159
18225
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
160
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
161 \subsection{Defining restricted environments \label{rexec-extension}}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
162
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
163 The \class{RExec} class has the following class attributes, which are
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
164 used by the \method{__init__()} method. Changing them on an existing
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
165 instance won't have any effect; instead, create a subclass of
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
166 \class{RExec} and assign them new values in the class definition.
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
167 Instances of the new class will then use those new values. All these
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
168 attributes are tuples of strings.
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
169
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
170 \begin{memberdesc}{nok_builtin_names}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
171 Contains the names of built-in functions which will \emph{not} be
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
172 available to programs running in the restricted environment. The
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
173 value for \class{RExec} is \code{('open', 'reload', '__import__')}.
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
174 (This gives the exceptions, because by far the majority of built-in
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
175 functions are harmless. A subclass that wants to override this
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
176 variable should probably start with the value from the base class and
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
177 concatenate additional forbidden functions --- when new dangerous
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
178 built-in functions are added to Python, they will also be added to
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
179 this module.)
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
180 \end{memberdesc}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
181
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
182 \begin{memberdesc}{ok_builtin_modules}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
183 Contains the names of built-in modules which can be safely imported.
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
184 The value for \class{RExec} is \code{('audioop', 'array', 'binascii',
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
185 'cmath', 'errno', 'imageop', 'marshal', 'math', 'md5', 'operator',
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
186 'parser', 'regex', 'rotor', 'select', 'sha', '_sre', 'strop',
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
187 'struct', 'time')}. A similar remark about overriding this variable
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
188 applies --- use the value from the base class as a starting point.
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
189 \end{memberdesc}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
190
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
191 \begin{memberdesc}{ok_path}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
192 Contains the directories which will be searched when an \keyword{import}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
193 is performed in the restricted environment.
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
194 The value for \class{RExec} is the same as \code{sys.path} (at the time
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
195 the module is loaded) for unrestricted code.
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
196 \end{memberdesc}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
197
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
198 \begin{memberdesc}{ok_posix_names}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
199 % Should this be called ok_os_names?
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
200 Contains the names of the functions in the \refmodule{os} module which will be
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
201 available to programs running in the restricted environment. The
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
202 value for \class{RExec} is \code{('error', 'fstat', 'listdir',
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
203 'lstat', 'readlink', 'stat', 'times', 'uname', 'getpid', 'getppid',
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
204 'getcwd', 'getuid', 'getgid', 'geteuid', 'getegid')}.
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
205 \end{memberdesc}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
206
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
207 \begin{memberdesc}{ok_sys_names}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
208 Contains the names of the functions and variables in the \refmodule{sys}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
209 module which will be available to programs running in the restricted
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
210 environment. The value for \class{RExec} is \code{('ps1', 'ps2',
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
211 'copyright', 'version', 'platform', 'exit', 'maxint')}.
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
212 \end{memberdesc}
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
213
aa8e238ab0ad Re-organize a little, clean up some markup.
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
214
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
215 \subsection{An example}
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
216
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
217 Let us say that we want a slightly more relaxed policy than the
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
218 standard \class{RExec} class. For example, if we're willing to allow
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
219 files in \file{/tmp} to be written, we can subclass the \class{RExec}
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
220 class:
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
221
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
222 \begin{verbatim}
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
223 class TmpWriterRExec(rexec.RExec):
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
224 def r_open(self, file, mode='r', buf=-1):
4492
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
225 if mode in ('r', 'rb'):
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
226 pass
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
227 elif mode in ('w', 'wb', 'a', 'ab'):
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
228 # check filename : must begin with /tmp/
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
229 if file[:5]!='/tmp/':
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
230 raise IOError, "can't write outside /tmp"
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
231 elif (string.find(file, '/../') >= 0 or
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
232 file[:3] == '../' or file[-3:] == '/..'):
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
233 raise IOError, "'..' in filename forbidden"
ae75d4a1f5dd Done with this for 1.4.
Guido van Rossum <guido@python.org>
parents: 4433
diff changeset
234 else: raise IOError, "Illegal open() mode"
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
235 return open(file, mode, buf)
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
236 \end{verbatim}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 4492
diff changeset
237 %
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
238 Notice that the above code will occasionally forbid a perfectly valid
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
239 filename; for example, code in the restricted environment won't be
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
240 able to open a file called \file{/tmp/foo/../bar}. To fix this, the
7685
afdcbef17ec0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7454
diff changeset
241 \method{r_open()} method would have to simplify the filename to
4433
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
242 \file{/tmp/bar}, which would require splitting apart the filename and
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
243 performing various operations on it. In cases where security is at
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
244 stake, it may be preferable to write simple code which is sometimes
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
245 overly restrictive, instead of more general code that is also more
340adfaa9854 Actual text submitted by AMK.
Guido van Rossum <guido@python.org>
parents: 4259
diff changeset
246 complex and may harbor a subtle security hole.