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: gl, Next: DEVICE, Prev: fm, Up: SGI IRIX Specific Services
_Graphics Library_ interface
============================
Functions from the Silicon Graphics _Graphics Library_.
This module provides access to the Silicon Graphics _Graphics
Library_. It is available only on Silicon Graphics machines.
*Warning:* Some illegal calls to the GL library cause the Python
interpreter to dump core. In particular, the use of most GL calls is
unsafe before the first window is opened.
The module is too large to document here in its entirety, but the
following should help you to get started. The parameter conventions
for the C functions are translated to Python as follows:
* All (short, long, unsigned) int values are represented by Python
integers.
* All float and double values are represented by Python floating
point numbers. In most cases, Python integers are also allowed.
* All arrays are represented by one-dimensional Python lists. In
most cases, tuples are also allowed.
* All string and character arguments are represented by Python
strings, for instance, `winopen('Hi There!')' and `rotate(900,
'z')'.
* All (short, long, unsigned) integer arguments or return values
that are only used to specify the length of an array argument are
omitted. For example, the C call
lmdef(deftype, index, np, props)
is translated to Python as
lmdef(deftype, index, props)
* Output arguments are omitted from the argument list; they are
transmitted as function return values instead. If more than one
value must be returned, the return value is a tuple. If the C
function has both a regular return value (that is not omitted
because of the previous rule) and an output argument, the return
value comes first in the tuple. Examples: the C call
getmcolor(i, &red, &green, &blue)
is translated to Python as
red, green, blue = getmcolor(i)
The following functions are non-standard or have special argument
conventions:
`varray(argument)'
Equivalent to but faster than a number of `v3d()' calls. The
ARGUMENT is a list (or tuple) of points. Each point must be a
tuple of coordinates `(X, Y, Z)' or `(X, Y)'. The points may be
2- or 3-dimensional but must all have the same dimension. Float
and int values may be mixed however. The points are always
converted to 3D double precision points by assuming `Z = 0.0' if
necessary (as indicated in the man page), and for each point
`v3d()' is called.
`nvarray()'
Equivalent to but faster than a number of `n3f' and `v3f' calls.
The argument is an array (list or tuple) of pairs of normals and
points. Each pair is a tuple of a point and a normal for that
point. Each point or normal must be a tuple of coordinates `(X,
Y, Z)'. Three coordinates must be given. Float and int values
may be mixed. For each pair, `n3f()' is called for the normal,
and then `v3f()' is called for the point.
`vnarray()'
Similar to `nvarray()' but the pairs have the point first and the
normal second.
`nurbssurface(s_k, t_k, ctl, s_ord, t_ord, type)'
Defines a nurbs surface. The dimensions of `CTL[][]' are computed
as follows: `[len(S_K) - S_ORD]', `[len(T_K) - T_ORD]'.
`nurbscurve(knots, ctlpoints, order, type)'
Defines a nurbs curve. The length of ctlpoints is `len(KNOTS) -
ORDER'.
`pwlcurve(points, type)'
Defines a piecewise-linear curve. POINTS is a list of points.
TYPE must be `N_ST'.
`pick(n)'
`select n'
The only argument to these functions specifies the desired size of
the pick or select buffer.
`endpick()'
`endselect'
These functions have no arguments. They return a list of integers
representing the used part of the pick/select buffer. No method
is provided to detect buffer overrun.
Here is a tiny but complete example GL program in Python:
import gl, GL, time
def main():
gl.foreground()
gl.prefposition(500, 900, 500, 900)
w = gl.winopen('CrissCross')
gl.ortho2(0.0, 400.0, 0.0, 400.0)
gl.color(GL.WHITE)
gl.clear()
gl.color(GL.RED)
gl.bgnline()
gl.v2f(0.0, 0.0)
gl.v2f(400.0, 400.0)
gl.endline()
gl.bgnline()
gl.v2f(400.0, 0.0)
gl.v2f(0.0, 400.0)
gl.endline()
time.sleep(5)
main()
See also:
An interface to OpenGL is also available; see information about
David Ascher's *PyOpenGL* online at
. This may be a better
option if support for SGI hardware from before about 1996 is not
required.
File: python-lib.info, Node: DEVICE, Next: GL, Prev: gl, Up: SGI IRIX Specific Services
Constants used with the `gl' module
===================================
Constants used with the `gl' module.
This modules defines the constants used by the Silicon Graphics
_Graphics Library_ that C programmers find in the header file
`'. Read the module source file for details.
File: python-lib.info, Node: GL, Next: imgfile, Prev: DEVICE, Up: SGI IRIX Specific Services
Constants used with the `gl' module
===================================
Constants used with the `gl' module.
This module contains constants used by the Silicon Graphics
_Graphics Library_ from the C header file `'. Read the module
source file for details.
File: python-lib.info, Node: imgfile, Next: jpeg, Prev: GL, Up: SGI IRIX Specific Services
Support for SGI imglib files
============================
Support for SGI imglib files.
The `imgfile' 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
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.
`getsizes(file)'
This function returns a tuple `(X, Y, Z)' where X and Y are the
size of the image in pixels and Z is the number of bytes per
pixel. Only 3 byte RGB pixels and 1 byte greyscale pixels are
currently supported.
`read(file)'
This function reads and decodes the image on the specified file,
and returns it as a Python string. The string has either 1 byte
greyscale pixels or 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.
`readscaled(file, x, y, filter[, blur])'
This function is identical to read but it returns an image that is
scaled to the given X and Y sizes. If the FILTER and BLUR
parameters are omitted scaling is done by simply dropping or
duplicating pixels, so the result will be less than perfect,
especially for computer-generated images.
Alternatively, you can specify a filter to use to smoothen the
image after scaling. The filter forms supported are `'impulse'',
`'box'', `'triangle'', `'quadratic'' and `'gaussian''. If a filter
is specified BLUR is an optional parameter specifying the
blurriness of the filter. It defaults to `1.0'.
`readscaled()' makes no attempt to keep the aspect ratio correct,
so that is the users' responsibility.
`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.
`write(file, data, x, y, z)'
This function writes the RGB or greyscale data in DATA to image
file FILE. X and Y give the size of the image, Z is 1 for 1 byte
greyscale images or 3 for RGB images (which are stored as 4 byte
values of which only the lower three bytes are used). These are
the formats returned by `gl.lrectread()'.
File: python-lib.info, Node: jpeg, Prev: imgfile, Up: SGI IRIX Specific Services
Read and write JPEG files
=========================
Read and write image files in compressed JPEG format.
The module `jpeg' provides access to the jpeg compressor and
decompressor written by the Independent JPEG Group (IJG). JPEG is a
standard for compressing pictures; it is defined in ISO 10918. For
details on JPEG or the Independent JPEG Group software refer to the
JPEG standard or the documentation provided with the software.
A portable interface to JPEG image files is available with the Python
Imaging Library (PIL) by Fredrik Lundh. Information on PIL is
available at .
The `jpeg' module defines an exception and some functions.
`error'
Exception raised by `compress()' and `decompress()' in case of
errors.
`compress(data, w, h, b)'
Treat data as a pixmap of width W and height H, with B bytes per
pixel. The data is in SGI GL order, so the first pixel is in the
lower-left corner. This means that `gl.lrectread()' return data
can immediately be passed to `compress()'. Currently only 1 byte
and 4 byte pixels are allowed, the former being treated as
greyscale and the latter as RGB color. `compress()' returns a
string that contains the compressed picture, in JFIF format.
`decompress(data)'
Data is a string containing a picture in JFIF format. It returns a
tuple `(DATA, WIDTH, HEIGHT, BYTESPERPIXEL)'. Again, the data is
suitable to pass to `gl.lrectwrite()'.
`setoption(name, value)'
Set various options. Subsequent `compress()' and `decompress()'
calls will use these options. The following options are available:
Option Effect
------ -----
'forcegray' Force output to be grayscale,
even if input is RGB.
'quality' Set the quality of the compressed
image to a value between `0' and
`100' (default is `75'). This
only affects compression.
'optimize' Perform Huffman table
optimization. Takes longer, but
results in smaller compressed
image. This only affects
compression.
'smooth' Perform inter-block smoothing on
uncompressed image. Only useful
for low-quality images. This
only affects decompression.
See also:
`JPEG Still Image Data Compression Standard'{The canonical
reference for the JPEG image format, by Pennebaker and Mitchell.}
`Information Technology - Digital Compression and Coding of
Continuous-tone Still Images - Requirements and Guidelines'{The ISO
standard for JPEG is also published as ITU T.81. This is available
online in PDF form.}
File: python-lib.info, Node: SunOS Specific Services, Next: MS Windows Specific Services, Prev: SGI IRIX Specific Services, Up: Top
SunOS Specific Services
***********************
The modules described in this chapter provide interfaces to features
that are unique to the SunOS operating system (versions 4 and 5; the
latter is also known as Solaris version 2).
* Menu:
* sunaudiodev::
* SUNAUDIODEV::
File: python-lib.info, Node: sunaudiodev, Next: SUNAUDIODEV, Prev: SunOS Specific Services, Up: SunOS Specific Services
Access to Sun audio hardware
============================
Access to Sun audio hardware.
This module allows you to access the Sun audio interface. The Sun
audio hardware is capable of recording and playing back audio data in
u-LAW format with a sample rate of 8K per second. A full description
can be found in the `audio(7I)' manual page.
The module `SUNAUDIODEV'defines constants which may be used with
this module.
This module defines the following variables and functions:
`error'
This exception is raised on all errors. The argument is a string
describing what went wrong.
`open(mode)'
This function opens the audio device and returns a Sun audio device
object. This object can then be used to do I/O on. The MODE
parameter is one of `'r'' for record-only access, `'w'' for
play-only access, `'rw'' for both and `'control'' for access to the
control device. Since only one process is allowed to have the
recorder or player open at the same time it is a good idea to open
the device only for the activity needed. See `audio(7I)' for
details.
As per the manpage, this module first looks in the environment
variable `AUDIODEV' for the base audio device filename. If not
found, it falls back to `/dev/audio'. The control device is
calculated by appending "ctl" to the base audio device.
* Menu:
* Audio Device Objects::
File: python-lib.info, Node: Audio Device Objects, Prev: sunaudiodev, Up: sunaudiodev
Audio Device Objects
--------------------
The audio device objects are returned by `open()' define the
following methods (except `control' objects which only provide
`getinfo()', `setinfo()', `fileno()', and `drain()'):
`close()'
This method explicitly closes the device. It is useful in
situations where deleting the object does not immediately close it
since there are other references to it. A closed device should not
be used again.
`fileno()'
Returns the file descriptor associated with the device. This can
be used to set up `SIGPOLL' notification, as described below.
`drain()'
This method waits until all pending output is processed and then
returns. Calling this method is often not necessary: destroying
the object will automatically close the audio device and this will
do an implicit drain.
`flush()'
This method discards all pending output. It can be used avoid the
slow response to a user's stop request (due to buffering of up to
one second of sound).
`getinfo()'
This method retrieves status information like input and output
volume, etc. and returns it in the form of an audio status object.
This object has no methods but it contains a number of attributes
describing the current device status. The names and meanings of
the attributes are described in `' and in the
`audio(7I)' manual page. Member names are slightly different from
their C counterparts: a status object is only a single structure.
Members of the `play' substructure have `o_' prepended to their
name and members of the `record' structure have `i_'. So, the C
member `play.sample_rate' is accessed as `o_sample_rate',
`record.gain' as `i_gain' and `monitor_gain' plainly as
`monitor_gain'.
`ibufcount()'
This method returns the number of samples that are buffered on the
recording side, i.e. the program will not block on a `read()' call
of so many samples.
`obufcount()'
This method returns the number of samples buffered on the playback
side. Unfortunately, this number cannot be used to determine a
number of samples that can be written without blocking since the
kernel output queue length seems to be variable.
`read(size)'
This method reads SIZE samples from the audio input and returns
them as a Python string. The function blocks until enough data is
available.
`setinfo(status)'
This method sets the audio device status parameters. The STATUS
parameter is an device status object as returned by `getinfo()' and
possibly modified by the program.
`write(samples)'
Write is passed a Python string containing audio samples to be
played. If there is enough buffer space free it will immediately
return, otherwise it will block.
The audio device supports asynchronous notification of various
events, through the SIGPOLL signal. Here's an example of how you might
enable this in Python:
def handle_sigpoll(signum, frame):
print 'I got a SIGPOLL update'
import fcntl, signal, STROPTS
signal.signal(signal.SIGPOLL, handle_sigpoll)
fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)
File: python-lib.info, Node: SUNAUDIODEV, Prev: sunaudiodev, Up: SunOS Specific Services
Constants used with `sunaudiodev'
=================================
Constants for use with `sunaudiodev'.
This is a companion module to `sunaudiodev' which defines useful
symbolic constants like `MIN_GAIN', `MAX_GAIN', `SPEAKER', etc. The
names of the constants are the same names as used in the C include file
`', with the leading string `AUDIO_' stripped.
File: python-lib.info, Node: MS Windows Specific Services, Next: Undocumented Modules, Prev: SunOS Specific Services, Up: Top
MS Windows Specific Services
****************************
This chapter describes modules that are only available on MS Windows
platforms.
* Menu:
* msvcrt - Useful routines from the MS VC++ runtime::
* _winreg - Windows registry access::
* winsound::
File: python-lib.info, Node: msvcrt - Useful routines from the MS VC++ runtime, Next: _winreg - Windows registry access, Prev: MS Windows Specific Services, Up: MS Windows Specific Services
`msvcrt' - Useful routines from the MS VC++ runtime
===================================================
Miscellaneous useful routines from the MS VC++ runtime.
This section was written by Fred L. Drake, Jr. .
These functions provide access to some useful capabilities on Windows
platforms. Some higher-level modules use these functions to build the
Windows implementations of their services. For example, the `getpass'
module uses this in the implementation of the `getpass()' function.
Further documentation on these functions can be found in the Platform
API documentation.
* Menu:
* File Operations::
* Console I/O::
* Other Functions::
File: python-lib.info, Node: File Operations, Next: Console I/O, Prev: msvcrt - Useful routines from the MS VC++ runtime, Up: msvcrt - Useful routines from the MS VC++ runtime
File Operations
---------------
`locking(fd, mode, nbytes)'
Lock part of a file based on file descriptor FD from the C
runtime. Raises `IOError' on failure. The locked region of the
file extends from the current file position for NBYTES bytes, and
may continue beyond the end of the file. MODE must be one of the
`LK_*' constants listed below. Multiple regions in a file may be
locked at the same time, but may not overlap. Adjacent regions
are not merged; they must be unlocked individually.
`LK_LOCK'
`LK_RLCK'
Locks the specified bytes. If the bytes cannot be locked, the
program immediately tries again after 1 second. If, after 10
attempts, the bytes cannot be locked, `IOError' is raised.
`LK_NBLCK'
`LK_NBRLCK'
Locks the specified bytes. If the bytes cannot be locked,
`IOError' is raised.
`LK_UNLCK'
Unlocks the specified bytes, which must have been previously
locked.
`setmode(fd, flags)'
Set the line-end translation mode for the file descriptor FD. To
set it to text mode, FLAGS should be `os.O_TEXT'; for binary, it
should be `os.O_BINARY'.
`open_osfhandle(handle, flags)'
Create a C runtime file descriptor from the file handle HANDLE.
The FLAGS parameter should be a bit-wise OR of `os.O_APPEND',
`os.O_RDONLY', and `os.O_TEXT'. The returned file descriptor may
be used as a parameter to `os.fdopen()' to create a file object.
`get_osfhandle(fd)'
Return the file handle for the file descriptor FD. Raises
`IOError' if FD is not recognized.
File: python-lib.info, Node: Console I/O, Next: Other Functions, Prev: File Operations, Up: msvcrt - Useful routines from the MS VC++ runtime
Console I/O
-----------
`kbhit()'
Return true if a keypress is waiting to be read.
`getch()'
Read a keypress and return the resulting character. Nothing is
echoed to the console. This call will block if a keypress is not
already available, but will not wait for to be pressed.
If the pressed key was a special function key, this will return
`'\000'' or `'\xe0''; the next call will return the keycode. The
keypress cannot be read with this function.
`getche()'
Similar to `getch()', but the keypress will be echoed if it
represents a printable character.
`putch(char)'
Print the character CHAR to the console without buffering.
`ungetch(char)'
Cause the character CHAR to be "pushed back" into the console
buffer; it will be the next character read by `getch()' or
`getche()'.
File: python-lib.info, Node: Other Functions, Prev: Console I/O, Up: msvcrt - Useful routines from the MS VC++ runtime
Other Functions
---------------
`heapmin()'
Force the `malloc()' heap to clean itself up and return unused
blocks to the operating system. This only works on Windows NT.
On failure, this raises `IOError'.
File: python-lib.info, Node: _winreg - Windows registry access, Next: winsound, Prev: msvcrt - Useful routines from the MS VC++ runtime, Up: MS Windows Specific Services
`_winreg' - Windows registry access
===================================
Routines and objects for manipulating the Windows registry.
This section was written by Mark Hammond .
_Added in Python version 2.0_
These functions expose the Windows registry API to Python. Instead
of using an integer as the registry handle, a handle object is used to
ensure that the handles are closed correctly, even if the programmer
neglects to explicitly close them.
This module exposes a very low-level interface to the Windows
registry; it is expected that in the future a new `winreg' module will
be created offering a higher-level interface to the registry API.
This module offers the following functions:
`CloseKey(hkey)'
Closes a previously opened registry key. The hkey argument
specifies a previously opened key.
Note that if HKEY is not closed using this method, (or the
`handle.Close()' closed when the HKEY object is destroyed by
Python.
`ConnectRegistry(computer_name, key)'
Establishes a connection to a predefined registry handle on
another computer, and returns a "handle object"
COMPUTER_NAME is the name of the remote computer, of the form
`\\computername'. If `None', the local computer is used.
KEY is the predefined handle to connect to.
The return value is the handle of the opened key. If the function
fails, an `EnvironmentError' exception is raised.
`CreateKey(key, sub_key)'
Creates or opens the specified key, returning a "handle object"
KEY is an already open key, or one of the predefined `HKEY_*'
constants.
SUB_KEY is a string that names the key this method opens or
creates.
If KEY is one of the predefined keys, SUB_KEY may be `None'. In
that case, the handle returned is the same key handle passed in to
the function.
If the key already exists, this function opens the existing key
The return value is the handle of the opened key. If the function
fails, an `EnvironmentError' exception is raised.
`DeleteKey(key, sub_key)'
Deletes the specified key.
KEY is an already open key, or any one of the predefined `HKEY_*'
constants.
SUB_KEY is a string that must be a subkey of the key identified by
the KEY parameter. This value must not be `None', and the key may
not have subkeys.
_This method can not delete keys with subkeys._
If the method succeeds, the entire key, including all of its
values, is removed. If the method fails, an `EnvironmentError'
exception is raised.
`DeleteValue(key, value)'
Removes a named value from a registry key.
KEY is an already open key, or one of the predefined `HKEY_*'
constants.
VALUE is a string that identifies the value to remove.
`EnumKey(key, index)'
Enumerates subkeys of an open registry key, returning a string.
KEY is an already open key, or any one of the predefined `HKEY_*'
constants.
INDEX is an integer that identifies the index of the key to
retrieve.
The function retrieves the name of one subkey each time it is
called. It is typically called repeatedly until an
`EnvironmentError' exception is raised, indicating, no more values
are available.
`EnumValue(key, index)'
Enumerates values of an open registry key, returning a tuple.
KEY is an already open key, or any one of the predefined `HKEY_*'
constants.
INDEX is an integer that identifies the index of the value to
retrieve.
The function retrieves the name of one subkey each time it is
called. It is typically called repeatedly, until an
`EnvironmentError' exception is raised, indicating no more values.
The result is a tuple of 3 items:
Index Meaning
------ -----
0 A string that identifies the
value name
1 An object that holds the value
data, and whose type depends on
the underlying registry type
2 An integer that identifies the
type of the value data
`FlushKey(key)'
Writes all the attributes of a key to the registry.
KEY is an already open key, or one of the predefined `HKEY_*'
constants.
It is not necessary to call RegFlushKey to change a key. Registry
changes are flushed to disk by the registry using its lazy
flusher. Registry changes are also flushed to disk at system
shutdown. Unlike `CloseKey()', the `FlushKey()' method returns
only when all the data has been written to the registry. An
application should only call `FlushKey()' if it requires absolute
certainty that registry changes are on disk.
_If you don't know whether a `FlushKey()' call is required, it
probably isn't._
`RegLoadKey(key, sub_key, file_name)'
Creates a subkey under the specified key and stores registration
information from a specified file into that subkey.
KEY is an already open key, or any of the predefined `HKEY_*'
constants.
SUB_KEY is a string that identifies the sub_key to load
FILE_NAME is the name of the file to load registry data from.
This file must have been created with the `SaveKey()' function.
Under the file allocation table (FAT) file system, the filename
may not have an extension.
A call to LoadKey() fails if the calling process does not have the
`SE_RESTORE_PRIVILEGE' privilege. Note that privileges are
different than permissions - see the Win32 documentation for more
details.
If KEY is a handle returned by `ConnectRegistry()', then the path
specified in FILENAME is relative to the remote computer.
The Win32 documentation implies KEY must be in the `HKEY_USER' or
`HKEY_LOCAL_MACHINE' tree. This may or may not be true.
`OpenKey(key, sub_key[, res` = 0'][, sam` = `KEY_READ''])'
Opens the specified key, returning a "handle object"
KEY is an already open key, or any one of the predefined `HKEY_*'
constants.
SUB_KEY is a string that identifies the sub_key to open
RES is a reserved integer, and must be zero. The default is zero.
SAM is an integer that specifies an access mask that describes the
desired security access for the key. Default is `KEY_READ'
The result is a new handle to the specified key
If the function fails, `EnvironmentError' is raised.
`OpenKeyEx()'
The functionality of `OpenKeyEx()' is provided via `OpenKey()', by
the use of default arguments.
`QueryInfoKey(key)'
Returns information about a key, as a tuple.
KEY is an already open key, or one of the predefined `HKEY_*'
constants.
The result is a tuple of 3 items:
Index Meaning
------ -----
0 An integer giving the number of
sub keys this key has.
1 An integer giving the number of
values this key has.
2 A long integer giving when the
key was last modified (if
available) as 100's of
nanoseconds since Jan 1, 1600.
`QueryValue(key, sub_key)'
Retrieves the unnamed value for a key, as a string
KEY is an already open key, or one of the predefined `HKEY_*'
constants.
SUB_KEY is a string that holds the name of the subkey with which
the value is associated. If this parameter is `None' or empty, the
function retrieves the value set by the `SetValue()' method for
the key identified by KEY.
Values in the registry have name, type, and data components. This
method retrieves the data for a key's first value that has a NULL
name. But the underlying API call doesn't return the type, Lame
Lame Lame, DO NOT USE THIS!!!
`QueryValueEx(key, value_name)'
Retrieves the type and data for a specified value name associated
with an open registry key.
KEY is an already open key, or one of the predefined `HKEY_*'
constants.
VALUE_NAME is a string indicating the value to query.
The result is a tuple of 2 items:
Index Meaning
------ -----
0 The value of the registry item.
1 An integer giving the registry
type for this value.
`SaveKey(key, file_name)'
Saves the specified key, and all its subkeys to the specified file.
KEY is an already open key, or one of the predefined `HKEY_*'
constants.
FILE_NAME is the name of the file to save registry data to. This
file cannot already exist. If this filename includes an extension,
it cannot be used on file allocation table (FAT) file systems by
the `LoadKey()', `ReplaceKey()' or `RestoreKey()' methods.
If KEY represents a key on a remote computer, the path described
by FILE_NAME is relative to the remote computer. The caller of
this method must possess the `SeBackupPrivilege' security
privilege. Note that privileges are different than permissions -
see the Win32 documentation for more details.
This function passes NULL for SECURITY_ATTRIBUTES to the API.
`SetValue(key, sub_key, type, value)'
Associates a value with a specified key.
KEY is an already open key, or one of the predefined `HKEY_*'
constants.
SUB_KEY is a string that names the subkey with which the value is
associated.
TYPE is an integer that specifies the type of the data. Currently
this must be `REG_SZ', meaning only strings are supported. Use
the `SetValueEx()' function for support for other data types.
VALUE is a string that specifies the new value.
If the key specified by the SUB_KEY parameter does not exist, the
SetValue function creates it.
Value lengths are limited by available memory. Long values (more
than 2048 bytes) should be stored as files with the filenames
stored in the configuration registry. This helps the registry
perform efficiently.
The key identified by the KEY parameter must have been opened with
`KEY_SET_VALUE' access.
`SetValueEx(key, value_name, reserved, type, value)'
Stores data in the value field of an open registry key.
KEY is an already open key, or one of the predefined `HKEY_*'
constants.
SUB_KEY is a string that names the subkey with which the value is
associated.
TYPE is an integer that specifies the type of the data. This
should be one of the following constants defined in this module:
Constant Meaning
------ -----
REG_BINARY Binary data in any form.
REG_DWORD A 32-bit number.
REG_DWORD_LITTLE_ENDIAN A 32-bit number in little-endian
format.
REG_DWORD_BIG_ENDIAN A 32-bit number in big-endian
format.
REG_EXPAND_SZ Null-terminated string containing
references to environment
variables (`%PATH%').
REG_LINK A Unicode symbolic link.
REG_MULTI_SZ A sequence of null-terminated
strings, terminated by two null
characters. (Python handles
this termination automatically.)
REG_NONE No defined value type.
REG_RESOURCE_LIST A device-driver resource list.
REG_SZ A null-terminated string.
RESERVED can be anything - zero is always passed to the API.
VALUE is a string that specifies the new value.
This method can also set additional value and type information for
the specified key. The key identified by the key parameter must
have been opened with `KEY_SET_VALUE' access.
To open the key, use the `CreateKeyEx()' or `OpenKey()' methods.
Value lengths are limited by available memory. Long values (more
than 2048 bytes) should be stored as files with the filenames
stored in the configuration registry. This helps the registry
perform efficiently.
* Menu:
* Registry Handle Objects::
File: python-lib.info, Node: Registry Handle Objects, Prev: _winreg - Windows registry access, Up: _winreg - Windows registry access
Registry Handle Objects
-----------------------
This object wraps a Windows HKEY object, automatically closing it
when the object is destroyed. To guarantee cleanup, you can call either
the `Close()' method on the object, or the `CloseKey()' function.
All registry functions in this module return one of these objects.
All registry functions in this module which accept a handle object
also accept an integer, however, use of the handle object is encouraged.
Handle objects provide semantics for `__nonzero__()' - thus
if handle:
print "Yes"
will print `Yes' if the handle is currently valid (i.e., has not
been closed or detached).
The object also support comparison semantics, so handle objects will
compare true if they both reference the same underlying Windows handle
value.
Handle objects can be converted to an integer (eg, using the builtin
`int()' function, in which case the underlying Windows handle value is
returned. You can also use the `Detach()' method to return the integer
handle, and also disconnect the Windows handle from the handle object.
`Close()'
Closes the underlying Windows handle.
If the handle is already closed, no error is raised.
`Detach()'
Detaches the Windows handle from the handle object.
The result is an integer (or long on 64 bit Windows) that holds
the value of the handle before it is detached. If the handle is
already detached or closed, this will return zero.
After calling this function, the handle is effectively invalidated,
but the handle is not closed. You would call this function when
you need the underlying Win32 handle to exist beyond the lifetime
of the handle object.
File: python-lib.info, Node: winsound, Prev: _winreg - Windows registry access, Up: MS Windows Specific Services
Sound-playing interface for Windows
===================================
Access to the sound-playing machinery for Windows. This module was
documented by Toby Dickenson .
This section was written by Fred L. Drake, Jr. .
_Added in Python version 1.5.2_
The `winsound' module provides access to the basic sound-playing
machinery provided by Windows platforms. It includes two functions and
several constants.
`Beep(frequency, duration)'
Beep the PC's speaker. The FREQUENCY parameter specifies
frequency, in hertz, of the sound, and must be in the range 37
through 32,767. The DURATION parameter specifies the number of
milliseconds the sound should last. If the system is not able to
beep the speaker, `RuntimeError' is raised. *Note:* Under
Windows 95 and 98, the Windows `Beep()' function exists but is
useless (it ignores its arguments). In that case Python simulates
it via direct port manipulation (added in version 2.1). It's
unknown whether that will work on all systems. _Added in Python
version 1.6_
`PlaySound(sound, flags)'
Call the underlying `PlaySound()' function from the Platform API.
The SOUND parameter may be a filename, audio data as a string, or
`None'. Its interpretation depends on the value of FLAGS, which
can be a bit-wise ORed combination of the constants described
below. If the system indicates an error, `RuntimeError' is raised.
`SND_FILENAME'
The SOUND parameter is the name of a WAV file. Do not use with
`SND_ALIAS'.
`SND_ALIAS'
The SOUND parameter is a sound association name from the registry.
If the registry contains no such name, play the system default
sound unless `SND_NODEFAULT' is also specified. If no default
sound is registered, raise `RuntimeError'. Do not use with
`SND_FILENAME'.
All Win32 systems support at least the following; most systems
support many more:
`PlaySound()' NAME Corresponding Control Panel Sound
name
------ -----
'SystemAsterisk' Asterisk
'SystemExclamation' Exclamation
'SystemExit' Exit Windows
'SystemHand' Critical Stop
'SystemQuestion' Question
For example:
import winsound
# Play Windows exit sound.
winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
# Probably play Windows default sound, if any is registered (because
# "*" probably isn't the registered name of any sound).
winsound.PlaySound("*", winsound.SND_ALIAS)
`SND_LOOP'
Play the sound repeatedly. The `SND_ASYNC' flag must also be used
to avoid blocking. Cannot be used with `SND_MEMORY'.
`SND_MEMORY'
The SOUND parameter to `PlaySound()' is a memory image of a WAV
file, as a string.
*Note:* This module does not support playing from a memory image
asynchronously, so a combination of this flag and `SND_ASYNC' will
raise `RuntimeError'.
`SND_PURGE'
Stop playing all instances of the specified sound.
`SND_ASYNC'
Return immediately, allowing sounds to play asynchronously.
`SND_NODEFAULT'
If the specified sound cannot be found, do not play the system
default sound.
`SND_NOSTOP'
Do not interrupt sounds currently playing.
`SND_NOWAIT'
Return immediately if the sound driver is busy.
File: python-lib.info, Node: Undocumented Modules, Next: Reporting Bugs, Prev: MS Windows Specific Services, Up: Top
Undocumented Modules
********************
Here's a quick listing of modules that are currently undocumented,
but that should be documented. Feel free to contribute documentation
for them! (Send via email to .)
The idea and original contents for this chapter were taken from a
posting by Fredrik Lundh; the specific contents of this chapter have
been substantially revised.
* Menu:
* Frameworks::
* Miscellaneous useful utilities::
* Platform specific modules::
* Multimedia::
* Obsolete::
* SGI-specific Extension modules::
File: python-lib.info, Node: Frameworks, Next: Miscellaneous useful utilities, Prev: Undocumented Modules, Up: Undocumented Modules
Frameworks
==========
Frameworks tend to be harder to document, but are well worth the
effort spent.
``Tkinter''
-- Interface to Tcl/Tk for graphical user interfaces; Fredrik Lundh
is working on this one! See at
for on-line reference
material.
``Tkdnd''
-- Drag-and-drop support for `Tkinter'.
``turtle''
-- Turtle graphics in a Tk window.
``test''
-- Regression testing framework. This is used for the Python
regression test, but is useful for other Python libraries as well.
This is a package rather than a single module.
File: python-lib.info, Node: Miscellaneous useful utilities, Next: Platform specific modules, Prev: Frameworks, Up: Undocumented Modules
Miscellaneous useful utilities
==============================
Some of these are very old and/or not very robust; marked with "hmm."
``bdb''
-- A generic Python debugger base class (used by pdb).
``ihooks''
-- Import hook support (for `rexec'; may become obsolete).
File: python-lib.info, Node: Platform specific modules, Next: Multimedia, Prev: Miscellaneous useful utilities, Up: Undocumented Modules
Platform specific modules
=========================
These modules are used to implement the `os.path' module, and are
not documented beyond this mention. There's little need to document
these.
``dospath''
-- Implementation of `os.path' on MS-DOS.
``ntpath''
-- Implementation on `os.path' on Win32, Win64, WinCE, and OS/2
platforms.
``posixpath''
-- Implementation on `os.path' on POSIX.
File: python-lib.info, Node: Multimedia, Next: Obsolete, Prev: Platform specific modules, Up: Undocumented Modules
Multimedia
==========
``audiodev''
-- Platform-independent API for playing audio data.
``sunaudio''
-- Interpret Sun audio headers (may become obsolete or a
tool/demo).
``toaiff''
-- Convert "arbitrary" sound files to AIFF files; should probably
become a tool or demo. Requires the external program `sox'.
File: python-lib.info, Node: Obsolete, Next: SGI-specific Extension modules, Prev: Multimedia, Up: Undocumented Modules
Obsolete
========
These modules are not normally available for import; additional work
must be done to make them available.
Those which are written in Python will be installed into the
directory `lib-old/' installed as part of the standard library. To use
these, the directory must be added to `sys.path', possibly using
`PYTHONPATH'.
Obsolete extension modules written in C are not built by default.
Under UNIX, these must be enabled by uncommenting the appropriate lines
in `Modules/Setup' in the build tree and either rebuilding Python if
the modules are statically linked, or building and installing the
shared object if using dynamically-loaded extensions.
``addpack''
-- Alternate approach to packages. Use the built-in package
support instead.
``cmp''
-- File comparison function. Use the newer `filecmp' instead.
``cmpcache''
-- Caching version of the obsolete `cmp' module. Use the newer
`filecmp' instead.
``codehack''
-- Extract function name or line number from a function code
object (these are now accessible as attributes: `co.co_name',
`func.func_name', `co.co_firstlineno').
``dircmp''
-- Class to build directory diff tools on (may become a demo or
tool). _This is deprecated in Python 2.0. The `filecmp' module
replaces `dircmp'._
``dump''
-- Print python code that reconstructs a variable.
``fmt''
-- Text formatting abstractions (too slow).
``lockfile''
-- Wrapper around FCNTL file locking (use
`fcntl.lockf()'/`flock()' instead; see `fcntl').
``newdir''
-- New `dir()' function (the standard `dir()' is now just as good).
``Para''
-- Helper for `fmt'.
``poly''
-- Polynomials.
``regex''
-- Emacs-style regular expression support; may still be used in
some old code (extension module). Refer to the for documentation.
``regsub''
-- Regular expression based string replacement utilities, for use
with `regex' (extension module). Refer to the for documentation.
``tb''
-- Print tracebacks, with a dump of local variables (use
`pdb.pm()' or `traceback' instead).
``timing''
-- Measure time intervals to high resolution (use `time.clock()'
instead). (This is an extension module.)
``tzparse''
-- Parse a timezone specification (unfinished; may disappear in the
future, and does not work when the `TZ' environment variable is
not set).
``util''
-- Useful functions that don't fit elsewhere.
``whatsound''
-- Recognize sound files; use `sndhdr' instead.
``zmod''
-- Compute properties of mathematical "fields."
The following modules are obsolete, but are likely to re-surface as
tools or scripts:
``find''
-- Find files matching pattern in directory tree.
``grep''
-- `grep' implementation in Python.
``packmail''
-- Create a self-unpacking UNIX shell archive.
The following modules were documented in previous versions of this
manual, but are now considered obsolete. The source for the
documentation is still available as part of the documentation source
archive.
``ni''
-- Import modules in "packages." Basic package support is now
built in. The built-in support is very similar to what is
provided in this module.
``rand''
-- Old interface to the random number generator.
``soundex''
-- Algorithm for collapsing names which sound similar to a shared
key. The specific algorithm doesn't seem to match any published
algorithm. (This is an extension module.)
File: python-lib.info, Node: SGI-specific Extension modules, Prev: Obsolete, Up: Undocumented Modules
SGI-specific Extension modules
==============================
The following are SGI specific, and may be out of touch with the
current version of reality.
``cl''
-- Interface to the SGI compression library.
``sv''
-- Interface to the "simple video" board on SGI Indigo (obsolete
hardware).