This is /home/pdm/install/Python-2.1/Doc/lib/python-lib.info, produced by makeinfo version 4.0 from lib.texi. April 15, 2001 2.1  File: python-lib.info, Node: AU_write Objects, Prev: AU_read Objects, Up: sunau AU_write Objects ---------------- AU_write objects, as returned by `open()' above, have the following methods: `setnchannels(n)' Set the number of channels. `setsampwidth(n)' Set the sample width (in bytes.) `setframerate(n)' Set the frame rate. `setnframes(n)' Set the number of frames. This can be later changed, when and if more frames are written. `setcomptype(type, name)' Set the compression type and description. Only `'NONE'' and `'ULAW'' are supported on output. `setparams(tuple)' The TUPLE should be `(NCHANNELS, SAMPWIDTH, FRAMERATE, NFRAMES, COMPTYPE, COMPNAME)', with values valid for the `set*()' methods. Set all parameters. `tell()' Return current position in the file, with the same disclaimer for the `AU_read.tell()' and `AU_read.setpos()' methods. `writeframesraw(data)' Write audio frames, without correcting NFRAMES. `writeframes(data)' Write audio frames and make sure NFRAMES is correct. `close()' Make sure NFRAMES is correct, and close the file. This method is called upon deletion. Note that it is invalid to set any parameters after calling `writeframes()' or `writeframesraw()'.  File: python-lib.info, Node: wave, Next: chunk, Prev: sunau, Up: Multimedia Services Read and write WAV files ======================== This section was written by Moshe Zadka . Provide an interface to the WAV sound format. The `wave' module provides a convenient interface to the WAV sound format. It does not support compression/decompression, but it does support mono/stereo. The `wave' module defines the following function and exception: `open(file[, mode])' If FILE is a string, open the file by that name, other treat it as a seekable file-like object. MODE can be any of ``'r'', `'rb''' Read only mode. ``'w'', `'wb''' Write only mode. Note that it does not allow read/write WAV files. A MODE of `'r'' or `'rb'' returns a `Wave_read' object, while a MODE of `'w'' or `'wb'' returns a `Wave_write' object. If MODE is omitted and a file-like object is passed as FILE, `FILE.mode' is used as the default value for MODE (the `b' flag is still added if necessary). `openfp(file, mode)' A synonym for `open()', maintained for backwards compatibility. `Error' An error raised when something is impossible because it violates the WAV specification or hits an implementation deficiency. * Menu: * Wave_read Objects:: * Wave_write Objects::  File: python-lib.info, Node: Wave_read Objects, Next: Wave_write Objects, Prev: wave, Up: wave Wave_read Objects ----------------- Wave_read objects, as returned by `open()', have the following methods: `close()' Close the stream, and make the instance unusable. This is called automatically on object collection. `getnchannels()' Returns number of audio channels (`1' for mono, `2' for stereo). `getsampwidth()' Returns sample width in bytes. `getframerate()' Returns sampling frequency. `getnframes()' Returns number of audio frames. `getcomptype()' Returns compression type (`'NONE'' is the only supported type). `getcompname()' Human-readable version of `getcomptype()'. Usually `'not compressed'' parallels `'NONE''. `getparams()' Returns a tuple `(NCHANNELS, SAMPWIDTH, FRAMERATE, NFRAMES, COMPTYPE, COMPNAME)', equivalent to output of the `get*()' methods. `readframes(n)' Reads and returns at most N frames of audio, as a string of bytes. `rewind()' Rewind the file pointer to the beginning of the audio stream. The following two methods are defined for compatibility with the `aifc' module, and don't do anything interesting. `getmarkers()' Returns `None'. `getmark(id)' Raise an error. The following two methods define a term "position" which is compatible between them, and is otherwise implementation dependent. `setpos(pos)' Set the file pointer to the specified position. `tell()' Return current file pointer position.  File: python-lib.info, Node: Wave_write Objects, Prev: Wave_read Objects, Up: wave Wave_write Objects ------------------ Wave_write objects, as returned by `open()', have the following methods: `close()' Make sure NFRAMES is correct, and close the file. This method is called upon deletion. `setnchannels(n)' Set the number of channels. `setsampwidth(n)' Set the sample width to N bytes. `setframerate(n)' Set the frame rate to N. `setnframes(n)' Set the number of frames to N. This will be changed later if more frames are written. `setcomptype(type, name)' Set the compression type and description. `setparams(tuple)' The TUPLE should be `(NCHANNELS, SAMPWIDTH, FRAMERATE, NFRAMES, COMPTYPE, COMPNAME)', with values valid for the `set*()' methods. Sets all parameters. `tell()' Return current position in the file, with the same disclaimer for the `Wave_read.tell()' and `Wave_read.setpos()' methods. `writeframesraw(data)' Write audio frames, without correcting NFRAMES. `writeframes(data)' Write audio frames and make sure NFRAMES is correct. Note that it is invalid to set any parameters after calling `writeframes()' or `writeframesraw()', and any attempt to do so will raise `wave.Error'.  File: python-lib.info, Node: chunk, Next: colorsys, Prev: wave, Up: Multimedia Services Read IFF chunked data ===================== Module to read IFF chunks. This module was documented by Sjoerd Mullender . This section was written by Sjoerd Mullender . This module provides an interface for reading files that use EA IFF 85 chunks.(1) This format is used in at least the Audio Interchange File Format (AIFF/AIFF-C) and the Real Media File Format (RMFF). The WAVE audio file format is closely related and can also be read using this module. A chunk has the following structure: Offset Length Contents ------ ----- ----- 0 4 Chunk ID 4 4 Size of chunk in big-endian byte order, not including the header 8 N Data bytes, where N is the size given in the preceding field 8 + N 0 or 1 Pad byte needed if N is odd and chunk alignment is used The ID is a 4-byte string which identifies the type of chunk. The size field (a 32-bit value, encoded using big-endian byte order) gives the size of the chunk data, not including the 8-byte header. Usually an IFF-type file consists of one or more chunks. The proposed usage of the `Chunk' class defined here is to instantiate an instance at the start of each chunk and read from the instance until it reaches the end, after which a new instance can be instantiated. At the end of the file, creating a new instance will fail with a `EOFError' exception. `Chunk(file[, align, bigendian, inclheader])' Class which represents a chunk. The FILE argument is expected to be a file-like object. An instance of this class is specifically allowed. The only method that is needed is `read()'. If the methods `seek()' and `tell()' are present and don't raise an exception, they are also used. If these methods are present and raise an exception, they are expected to not have altered the object. If the optional argument ALIGN is true, chunks are assumed to be aligned on 2-byte boundaries. If ALIGN is false, no alignment is assumed. The default value is true. If the optional argument BIGENDIAN is false, the chunk size is assumed to be in little-endian order. This is needed for WAVE audio files. The default value is true. If the optional argument INCLHEADER is true, the size given in the chunk header includes the size of the header. The default value is false. A `Chunk' object supports the following methods: `getname()' Returns the name (ID) of the chunk. This is the first 4 bytes of the chunk. `getsize()' Returns the size of the chunk. `close()' Close and skip to the end of the chunk. This does not close the underlying file. The remaining methods will raise `IOError' if called after the `close()' method has been called. `isatty()' Returns `0'. `seek(pos[, whence])' Set the chunk's current position. The WHENCE argument is optional and defaults to `0' (absolute file positioning); other values are `1' (seek relative to the current position) and `2' (seek relative to the file's end). There is no return value. If the underlying file does not allow seek, only forward seeks are allowed. `tell()' Return the current position into the chunk. `read([size])' Read at most SIZE bytes from the chunk (less if the read hits the end of the chunk before obtaining SIZE bytes). If the SIZE argument is negative or omitted, read all data until the end of the chunk. The bytes are returned as a string object. An empty string is returned when the end of the chunk is encountered immediately. `skip()' Skip to the end of the chunk. All further calls to `read()' for the chunk will return `'''. If you are not interested in the contents of the chunk, this method should be called so that the file points to the start of the next chunk. ---------- Footnotes ---------- (1) "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic Arts, January 1985.  File: python-lib.info, Node: colorsys, Next: rgbimg, Prev: chunk, Up: Multimedia Services Conversions between color systems ================================= Conversion functions between RGB and other color systems. This section was written by David Ascher . The `colorsys' module defines bidirectional conversions of color values between colors expressed in the RGB (Red Green Blue) color space used in computer monitors and three other coordinate systems: YIQ, HLS (Hue Lightness Saturation) and HSV (Hue Saturation Value). Coordinates in all of these color spaces are floating point values. In the YIQ space, the Y coordinate is between 0 and 1, but the I and Q coordinates can be positive or negative. In all other spaces, the coordinates are all between 0 and 1. More information about color spaces can be found at . The `colorsys' module defines the following functions: `rgb_to_yiq(r, g, b)' Convert the color from RGB coordinates to YIQ coordinates. `yiq_to_rgb(y, i, q)' Convert the color from YIQ coordinates to RGB coordinates. `rgb_to_hls(r, g, b)' Convert the color from RGB coordinates to HLS coordinates. `hls_to_rgb(h, l, s)' Convert the color from HLS coordinates to RGB coordinates. `rgb_to_hsv(r, g, b)' Convert the color from RGB coordinates to HSV coordinates. `hsv_to_rgb(h, s, v)' Convert the color from HSV coordinates to RGB coordinates. Example: >>> import colorsys >>> colorsys.rgb_to_hsv(.3, .4, .2) (0.25, 0.5, 0.4) >>> colorsys.hsv_to_rgb(0.25, 0.5, 0.4) (0.3, 0.4, 0.2)  File: python-lib.info, Node: rgbimg, Next: imghdr, Prev: colorsys, Up: Multimedia Services Read and write "SGI RGB" files ============================== Read and write image files in "SGI RGB" format (the module is _not_ SGI specific though!). The `rgbimg' module allows Python programs to access SGI imglib image files (also known as `.rgb' files). The module is far from complete, but is provided anyway since the functionality that there is enough in some cases. Currently, colormap files are not supported. The module defines the following variables and functions: `error' This exception is raised on all errors, such as unsupported file type, etc. `sizeofimage(file)' This function returns a tuple `(X, Y)' where X and Y are the size of the image in pixels. Only 4 byte RGBA pixels, 3 byte RGB pixels, and 1 byte greyscale pixels are currently supported. `longimagedata(file)' This function reads and decodes the image on the specified file, and returns it as a Python string. The string has 4 byte RGBA pixels. The bottom left pixel is the first in the string. This format is suitable to pass to `gl.lrectwrite()', for instance. `longstoimage(data, x, y, z, file)' This function writes the RGBA data in DATA to image file FILE. X and Y give the size of the image. Z is 1 if the saved image should be 1 byte greyscale, 3 if the saved image should be 3 byte RGB data, or 4 if the saved images should be 4 byte RGBA data. The input data always contains 4 bytes per pixel. These are the formats returned by `gl.lrectread()'. `ttob(flag)' This function sets a global flag which defines whether the scan lines of the image are read or written from bottom to top (flag is zero, compatible with SGI GL) or from top to bottom(flag is one, compatible with X). The default is zero.  File: python-lib.info, Node: imghdr, Next: sndhdr, Prev: rgbimg, Up: Multimedia Services Determine the type of an image ============================== Determine the type of image contained in a file or byte stream. The `imghdr' module determines the type of image contained in a file or byte stream. The `imghdr' module defines the following function: `what(filename[, h])' Tests the image data contained in the file named by FILENAME, and returns a string describing the image type. If optional H is provided, the FILENAME is ignored and H is assumed to contain the byte stream to test. The following image types are recognized, as listed below with the return value from `what()': Value Image format ------ ----- 'rgb' SGI ImgLib Files 'gif' GIF 87a and 89a Files 'pbm' Portable Bitmap Files 'pgm' Portable Graymap Files 'ppm' Portable Pixmap Files 'tiff' TIFF Files 'rast' Sun Raster Files 'xbm' X Bitmap Files 'jpeg' JPEG data in JFIF format 'bmp' BMP files 'png' Portable Network Graphics You can extend the list of file types `imghdr' can recognize by appending to this variable: `tests' A list of functions performing the individual tests. Each function takes two arguments: the byte-stream and an open file-like object. When `what()' is called with a byte-stream, the file-like object will be `None'. The test function should return a string describing the image type if the test succeeded, or `None' if it failed. Example: >>> import imghdr >>> imghdr.what('/tmp/bass.gif') 'gif'  File: python-lib.info, Node: sndhdr, Prev: imghdr, Up: Multimedia Services Determine type of sound file ============================ Determine type of a sound file. This section was written by Fred L. Drake, Jr. . The `sndhdr' provides utility functions which attempt to determine the type of sound data which is in a file. When these functions are able to determine what type of sound data is stored in a file, they return a tuple `(TYPE, SAMPLING_RATE, CHANNELS, FRAMES, BITS_PER_SAMPLE)'. The value for TYPE indicates the data type and will be one of the strings `'aifc'', `'aiff'', `'au'', `'hcom'', `'sndr'', `'sndt'', `'voc'', `'wav'', `'8svx'', `'sb'', `'ub'', or `'ul''. The SAMPLING_RATE will be either the actual value or `0' if unknown or difficult to decode. Similarly, CHANNELS will be either the number of channels or `0' if it cannot be determined or if the value is difficult to decode. The value for FRAMES will be either the number of frames or `-1'. The last item in the tuple, BITS_PER_SAMPLE, will either be the sample size in bits or `'A'' for A-LAW or `'U'' for u-LAW. `what(filename)' Determines the type of sound data stored in the file FILENAME using `whathdr()'. If it succeeds, returns a tuple as described above, otherwise `None' is returned. `whathdr(filename)' Determines the type of sound data stored in a file based on the file header. The name of the file is given by FILENAME. This function returns a tuple as described above on success, or `None'.  File: python-lib.info, Node: Cryptographic Services, Next: Restricted Execution, Prev: Multimedia Services, Up: Top Cryptographic Services ********************** The modules described in this chapter implement various algorithms of a cryptographic nature. They are available at the discretion of the installation. Here's an overview: Hardcore cypherpunks will probably find the cryptographic modules written by Andrew Kuchling of further interest; the package adds built-in modules for DES and IDEA encryption, provides a Python module for reading and decrypting PGP files, and then some. These modules are not distributed with Python but available separately. See the URL or send email to for more information. * Menu: * md5:: * sha:: * mpz:: * rotor::  File: python-lib.info, Node: md5, Next: sha, Prev: Cryptographic Services, Up: Cryptographic Services MD5 message digest algorithm ============================ RSA's MD5 message digest algorithm. This module implements the interface to RSA's MD5 message digest algorithm (see also Internet RFC 1321). Its use is quite straightforward: use `new()' to create an md5 object. You can now feed this object with arbitrary strings using the `update()' method, and at any point you can ask it for the "digest" (a strong kind of 128-bit checksum, a.k.a. "fingerprint") of the concatenation of the strings fed to it so far using the `digest()' method. For example, to obtain the digest of the string `'Nobody inspects the spammish repetition'': >>> import md5 >>> m = md5.new() >>> m.update("Nobody inspects") >>> m.update(" the spammish repetition") >>> m.digest() '\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9' More condensed: >>> md5.new("Nobody inspects the spammish repetition").digest() '\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9' `new([arg])' Return a new md5 object. If ARG is present, the method call `update(ARG)' is made. `md5([arg])' For backward compatibility reasons, this is an alternative name for the `new()' function. An md5 object has the following methods: `update(arg)' Update the md5 object with the string ARG. Repeated calls are equivalent to a single call with the concatenation of all the arguments, i.e. `m.update(a); m.update(b)' is equivalent to `m.update(a+b)'. `digest()' Return the digest of the strings passed to the `update()' method so far. This is a 16-byte string which may contain non-ASCII characters, including null bytes. `hexdigest()' Like `digest()' except the digest is returned as a string of length 32, containing only hexadecimal digits. This may be used to exchange the value safely in email or other non-binary environments. `copy()' Return a copy ("clone") of the md5 object. This can be used to efficiently compute the digests of strings that share a common initial substring. See also: *Note sha:: Similar module implementing the Secure Hash Algorithm (SHA). The SHA algorithm is considered a more secure hash.  File: python-lib.info, Node: sha, Next: mpz, Prev: md5, Up: Cryptographic Services SHA message digest algorithm ============================ NIST's secure hash algorithm, SHA. This section was written by Fred L. Drake, Jr. . This module implements the interface to NIST's secure hash algorithm, known as SHA. It is used in the same way as the `md5' module: use `new()' to create an sha object, then feed this object with arbitrary strings using the `update()' method, and at any point you can ask it for the "digest" of the concatenation of the strings fed to it so far. SHA digests are 160 bits instead of MD5's 128 bits. `new([string])' Return a new sha object. If STRING is present, the method call `update(STRING)' is made. The following values are provided as constants in the module and as attributes of the sha objects returned by `new()': `blocksize' Size of the blocks fed into the hash function; this is always `1'. This size is used to allow an arbitrary string to be hashed. `digestsize' The size of the resulting digest in bytes. This is always `20'. An sha object has the same methods as md5 objects: `update(arg)' Update the sha object with the string ARG. Repeated calls are equivalent to a single call with the concatenation of all the arguments, i.e. `m.update(a); m.update(b)' is equivalent to `m.update(a+b)'. `digest()' Return the digest of the strings passed to the `update()' method so far. This is a 20-byte string which may contain non-ASCII characters, including null bytes. `hexdigest()' Like `digest()' except the digest is returned as a string of length 40, containing only hexadecimal digits. This may be used to exchange the value safely in email or other non-binary environments. `copy()' Return a copy ("clone") of the sha object. This can be used to efficiently compute the digests of strings that share a common initial substring. See also: `Secure Hash Standard'{ The Secure Hash Algorithm is defined by NIST document FIPS PUB 180-1: , published in April of 1995. It is available online as plain text (at least one diagram was omitted) and as PDF at .}  File: python-lib.info, Node: mpz, Next: rotor, Prev: sha, Up: Cryptographic Services GNU arbitrary magnitude integers ================================ Interface to the GNU MP library for arbitrary precision arithmetic. This is an optional module. It is only available when Python is configured to include it, which requires that the GNU MP software is installed. This module implements the interface to part of the GNU MP library, which defines arbitrary precision integer and rational number arithmetic routines. Only the interfaces to the _integer_ (`mpz_*()') routines are provided. If not stated otherwise, the description in the GNU MP documentation can be applied. Support for rational numbers can be implemented in Python. For an example, see the `Rat' module, provided as `Demos/classes/Rat.py' in the Python source distribution. In general, "mpz"-numbers can be used just like other standard Python numbers, e.g., you can use the built-in operators like `+', `*', etc., as well as the standard built-in functions like `abs()', `int()', ..., `divmod()', `pow()'. *Please note:* the _bitwise-xor_ operation has been implemented as a bunch of _and_s, _invert_s and _or_s, because the library lacks an `mpz_xor()' function, and I didn't need one. You create an mpz-number by calling the function `mpz()' (see below for an exact description). An mpz-number is printed like this: `mpz(VALUE)'. `mpz(value)' Create a new mpz-number. VALUE can be an integer, a long, another mpz-number, or even a string. If it is a string, it is interpreted as an array of radix-256 digits, least significant digit first, resulting in a positive number. See also the `binary()' method, described below. `MPZType' The type of the objects returned by `mpz()' and most other functions in this module. A number of _extra_ functions are defined in this module. Non mpz-arguments are converted to mpz-values first, and the functions return mpz-numbers. `powm(base, exponent, modulus)' Return `pow(BASE, EXPONENT) %{} MODULUS'. If `EXPONENT == 0', return `mpz(1)'. In contrast to the C library function, this version can handle negative exponents. `gcd(op1, op2)' Return the greatest common divisor of OP1 and OP2. `gcdext(a, b)' Return a tuple `(G, S, T)', such that `A*S + B*T == G == gcd(A, B)'. `sqrt(op)' Return the square root of OP. The result is rounded towards zero. `sqrtrem(op)' Return a tuple `(ROOT, REMAINDER)', such that `ROOT*ROOT + REMAINDER == OP'. `divm(numerator, denominator, modulus)' Returns a number Q such that `Q * DENOMINATOR %{} MODULUS == NUMERATOR'. One could also implement this function in Python, using `gcdext()'. An mpz-number has one method: `binary()' Convert this mpz-number to a binary string, where the number has been stored as an array of radix-256 digits, least significant digit first. The mpz-number must have a value greater than or equal to zero, otherwise `ValueError' will be raised.  File: python-lib.info, Node: rotor, Prev: mpz, Up: Cryptographic Services Enigma-like encryption and decryption ===================================== Enigma-like encryption and decryption. This module implements a rotor-based encryption algorithm, contributed by Lance Ellinghouse. The design is derived from the Enigma device, a machine used during World War II to encipher messages. A rotor is simply a permutation. For example, if the character `A' is the origin of the rotor, then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on. To encrypt, we choose several different rotors, and set the origins of the rotors to known positions; their initial position is the ciphering key. To encipher a character, we permute the original character by the first rotor, and then apply the second rotor's permutation to the result. We continue until we've applied all the rotors; the resulting character is our ciphertext. We then change the origin of the final rotor by one position, from `A' to `B'; if the final rotor has made a complete revolution, then we rotate the next-to-last rotor by one position, and apply the same procedure recursively. In other words, after enciphering one character, we advance the rotors in the same fashion as a car's odometer. Decoding works in the same way, except we reverse the permutations and apply them in the opposite order. The available functions in this module are: `newrotor(key[, numrotors])' Return a rotor object. KEY is a string containing the encryption key for the object; it can contain arbitrary binary data. The key will be used to randomly generate the rotor permutations and their initial positions. NUMROTORS is the number of rotor permutations in the returned object; if it is omitted, a default value of 6 will be used. Rotor objects have the following methods: `setkey(key)' Sets the rotor's key to KEY. `encrypt(plaintext)' Reset the rotor object to its initial state and encrypt PLAINTEXT, returning a string containing the ciphertext. The ciphertext is always the same length as the original plaintext. `encryptmore(plaintext)' Encrypt PLAINTEXT without resetting the rotor object, and return a string containing the ciphertext. `decrypt(ciphertext)' Reset the rotor object to its initial state and decrypt CIPHERTEXT, returning a string containing the plaintext. The plaintext string will always be the same length as the ciphertext. `decryptmore(ciphertext)' Decrypt CIPHERTEXT without resetting the rotor object, and return a string containing the plaintext. An example usage: >>> import rotor >>> rt = rotor.newrotor('key', 12) >>> rt.encrypt('bar') '\xab4\xf3' >>> rt.encryptmore('bar') '\xef\xfd$' >>> rt.encrypt('bar') '\xab4\xf3' >>> rt.decrypt('\xab4\xf3') 'bar' >>> rt.decryptmore('\xef\xfd$') 'bar' >>> rt.decrypt('\xef\xfd$') 'l(\xcd' >>> del rt The module's code is not an exact simulation of the original Enigma device; it implements the rotor encryption scheme differently from the original. The most important difference is that in the original Enigma, there were only 5 or 6 different rotors in existence, and they were applied twice to each character; the cipher key was the order in which they were placed in the machine. The Python `rotor' module uses the supplied key to initialize a random number generator; the rotor permutations and their initial positions are then randomly generated. The original device only enciphered the letters of the alphabet, while this module can handle any 8-bit binary data; it also produces binary output. This module can also operate with an arbitrary number of rotors. The original Enigma cipher was broken in 1944. The version implemented here is probably a good deal more difficult to crack (especially if you use many rotors), but it won't be impossible for a truly skillful and determined attacker to break the cipher. So if you want to keep the NSA out of your files, this rotor cipher may well be unsafe, but for discouraging casual snooping through your files, it will probably be just fine, and may be somewhat safer than using the UNIX `crypt' command.  File: python-lib.info, Node: Restricted Execution, Next: Python Language Services, Prev: Cryptographic Services, Up: Top Restricted Execution ******************** In general, Python programs have complete access to the underlying operating system throug the various functions and classes, For example, a Python program can open any file for reading and writing by using the `open()' built-in function (provided the underlying OS gives you permission!). This is exactly what you want for most applications. There exists a class of applications for which this "openness" is inappropriate. Take Grail: a web browser that accepts "applets," snippets of Python code, from anywhere on the Internet for execution on the local system. This can be used to improve the user interface of forms, for instance. Since the originator of the code is unknown, it is obvious that it cannot be trusted with the full resources of the local machine. _Restricted execution_ is the basic framework in Python that allows for the segregation of trusted and untrusted code. It is based on the notion that trusted Python code (a _supervisor_) can create a "padded cell' (or environment) with limited permissions, and run the untrusted code within this cell. The untrusted code cannot break out of its cell, and can only interact with sensitive system resources through interfaces defined and managed by the trusted code. The term "restricted execution" is favored over "safe-Python" since true safety is hard to define, and is determined by the way the restricted environment is created. Note that the restricted environments can be nested, with inner cells creating subcells of lesser, but never greater, privilege. An interesting aspect of Python's restricted execution model is that the interfaces presented to untrusted code usually have the same names as those presented to trusted code. Therefore no special interfaces need to be learned to write code designed to run in a restricted environment. And because the exact nature of the padded cell is determined by the supervisor, different restrictions can be imposed, depending on the application. For example, it might be deemed "safe" for untrusted code to read any file within a specified directory, but never to write a file. In this case, the supervisor may redefine the built-in `open()' function so that it raises an exception whenever the MODE parameter is `'w''. It might also perform a `chroot()'-like operation on the FILENAME parameter, such that root is always relative to some safe "sandbox" area of the filesystem. In this case, the untrusted code would still see an built-in `open()' function in its environment, with the same calling interface. The semantics would be identical too, with `IOError's being raised when the supervisor determined that an unallowable parameter is being used. The Python run-time determines whether a particular code block is executing in restricted execution mode based on the identity of the `__builtins__' object in its global variables: if this is (the dictionary of) the standard `__builtin__' module, the code is deemed to be unrestricted, else it is deemed to be restricted. Python code executing in restricted mode faces a number of limitations that are designed to prevent it from escaping from the padded cell. For instance, the function object attribute `func_globals' and the class and instance object attribute `__dict__' are unavailable. Two modules provide the framework for setting up restricted execution environments: See also: Andrew Kuchling, "Restricted Execution HOWTO." Available online at . Grail, an Internet browser written in Python, is available at . More information on the use of Python's restricted execution mode in Grail is available on the Web site. * Menu: * rexec:: * Bastion::  File: python-lib.info, Node: rexec, Next: Bastion, Prev: Restricted Execution, Up: Restricted Execution Restricted execution framework ============================== Basic restricted execution framework. This module contains the `RExec' class, which supports `r_eval()', `r_execfile()', `r_exec()', and `r_import()' methods, which are restricted versions of the standard Python functions `eval()', `execfile()' and the `exec' and `import' statements. Code executed in this restricted environment will only have access to modules and functions that are deemed safe; you can subclass `RExec' to add or remove capabilities as desired. _Note:_ The `RExec' class can prevent code from performing unsafe operations like reading or writing disk files, or using TCP/IP sockets. However, it does not protect against code using extremely large amounts of memory or CPU time. `RExec([hooks[, verbose]])' Returns an instance of the `RExec' class. HOOKS is an instance of the `RHooks' class or a subclass of it. If it is omitted or `None', the default `RHooks' class is instantiated. Whenever the `rexec' module searches for a module (even a built-in one) or reads a module's code, it doesn't actually go out to the file system itself. Rather, it calls methods of an `RHooks' instance that was passed to or created by its constructor. (Actually, the `RExec' object doesn't make these calls -- they are made by a module loader object that's part of the `RExec' object. This allows another level of flexibility, e.g. using packages.) By providing an alternate `RHooks' object, we can control the file system accesses made to import a module, without changing the actual algorithm that controls the order in which those accesses are made. For instance, we could substitute an `RHooks' object that passes all filesystem requests to a file server elsewhere, via some RPC mechanism such as ILU. Grail's applet loader uses this to support importing applets from a URL for a directory. If VERBOSE is true, additional debugging output may be sent to standard output. The `RExec' class has the following class attributes, which are used by the `__init__()' method. Changing them on an existing instance won't have any effect; instead, create a subclass of `RExec' and assign them new values in the class definition. Instances of the new class will then use those new values. All these attributes are tuples of strings. `nok_builtin_names' Contains the names of built-in functions which will _not_ be available to programs running in the restricted environment. The value for `RExec' is `('open',' `'reload',' `'__import__')'. (This gives the exceptions, because by far the majority of built-in functions are harmless. A subclass that wants to 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.) `ok_builtin_modules' Contains the names of built-in modules which can be safely imported. The value for `RExec' is `('audioop',' `'array',' `'binascii',' `'cmath',' `'errno',' `'imageop',' `'marshal',' `'math',' `'md5',' `'operator',' `'parser',' `'regex',' `'rotor',' `'select',' `'strop',' `'struct',' `'time')'. A similar remark about overriding this variable applies -- use the value from the base class as a starting point. `ok_path' Contains the directories which will be searched when an `import' is performed in the restricted environment. The value for `RExec' is the same as `sys.path' (at the time the module is loaded) for unrestricted code. `ok_posix_names' Contains the names of the functions in the `os' module which will be available to programs running in the restricted environment. The value for `RExec' is `('error',' `'fstat',' `'listdir',' `'lstat',' `'readlink',' `'stat',' `'times',' `'uname',' `'getpid',' `'getppid',' `'getcwd',' `'getuid',' `'getgid',' `'geteuid',' `'getegid')'. `ok_sys_names' Contains the names of the functions and variables in the `sys' module which will be available to programs running in the restricted environment. The value for `RExec' is `('ps1',' `'ps2',' `'copyright',' `'version',' `'platform',' `'exit',' `'maxint')'. `RExec' instances support the following methods: `r_eval(code)' CODE must either be a string containing a Python expression, or a compiled code object, which will be evaluated in the restricted environment's `__main__' module. The value of the expression or code object will be returned. `r_exec(code)' 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 `__main__' module. `r_execfile(filename)' Execute the Python code contained in the file FILENAME in the restricted environment's `__main__' module. Methods whose names begin with `s_' are similar to the functions beginning with `r_', but the code will be granted access to restricted versions of the standard I/O streams `sys.stdin', `sys.stderr', and `sys.stdout'. `s_eval(code)' CODE must be a string containing a Python expression, which will be evaluated in the restricted environment. `s_exec(code)' CODE must be a string containing one or more lines of Python code, which will be executed in the restricted environment. `s_execfile(code)' Execute the Python code contained in the file FILENAME in the restricted environment. `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. `r_import(modulename[, globals[, locals[, fromlist]]])' Import the module MODULENAME, raising an `ImportError' exception if the module is considered unsafe. `r_open(filename[, mode[, bufsize]])' Method called when `open()' is called in the restricted environment. The arguments are identical to those of `open()', and a file object (or a class instance compatible with file objects) should be returned. `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 `r_open()'. `r_reload(module)' Reload the module object MODULE, re-parsing and re-initializing it. `r_unload(module)' Unload the module object MODULE (i.e., remove it from the restricted environment's `sys.modules' dictionary). And their equivalents with access to restricted standard I/O streams: `s_import(modulename[, globals[, locals[, fromlist]]])' Import the module MODULENAME, raising an `ImportError' exception if the module is considered unsafe. `s_reload(module)' Reload the module object MODULE, re-parsing and re-initializing it. `s_unload(module)' Unload the module object MODULE. * Menu: * An example::  File: python-lib.info, Node: An example, Prev: rexec, Up: rexec An example ---------- Let us say that we want a slightly more relaxed policy than the standard `RExec' class. For example, if we're willing to allow files in `/tmp' to be written, we can subclass the `RExec' class: class TmpWriterRExec(rexec.RExec): def r_open(self, file, mode='r', buf=-1): if mode in ('r', 'rb'): pass elif mode in ('w', 'wb', 'a', 'ab'): # check filename : must begin with /tmp/ if file[:5]!='/tmp/': raise IOError, "can't write outside /tmp" elif (string.find(file, '/../') >= 0 or file[:3] == '../' or file[-3:] == '/..'): raise IOError, "'..' in filename forbidden" else: raise IOError, "Illegal open() mode" return open(file, mode, buf) 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 `/tmp/foo/../bar'. To fix this, the `r_open()' method would have to simplify the filename to `/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 overly restrictive, instead of more general code that is also more complex and may harbor a subtle security hole.  File: python-lib.info, Node: Bastion, Prev: rexec, Up: Restricted Execution Restricting access to objects ============================= Providing restricted access to objects. This module was documented by Barry Warsaw . According to the dictionary, a bastion is "a fortified area or position", or "something that is considered a stronghold." It's a suitable name for this module, which provides a way to forbid access to certain attributes of an object. It must always be used with the `rexec' module, in order to allow restricted-mode programs access to certain safe attributes of an object, while denying access to other, unsafe attributes. `Bastion(object[, filter[, name[, class]]])' Protect the object OBJECT, returning a bastion for the object. Any attempt to access one of the object's attributes will have to be approved by the FILTER function; if the access is denied an `AttributeError' exception will be raised. If present, FILTER must be a function that accepts a string containing an attribute name, and returns true if access to that attribute will be permitted; if FILTER returns false, the access is denied. The default filter denies access to any function beginning with an underscore (`_'). The bastion's string representation will be `' if a value for NAME is provided; otherwise, `repr(OBJECT)' will be used. CLASS, if present, should be a subclass of `BastionClass'; see the code in `bastion.py' for the details. Overriding the default `BastionClass' will rarely be required. `BastionClass(getfunc, name)' Class which actually implements bastion objects. This is the default class used by `Bastion()'. The 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. NAME is used to construct the `repr()' of the `BastionClass' instance.  File: python-lib.info, Node: Python Language Services, Next: SGI IRIX Specific Services, Prev: Restricted Execution, Up: Top Python Language Services ************************ Python provides a number of modules to assist in working with the Python language. These module support tokenizing, parsing, syntax analysis, bytecode disassembly, and various other facilities. These modules include: * Menu: * parser:: * symbol:: * token:: * keyword:: * tokenize:: * tabnanny:: * pyclbr:: * py_compile:: * compileall:: * dis::