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: Condition Objects, Next: Semaphore Objects, Prev: RLock Objects, Up: threading Condition Objects ----------------- A condition variable is always associated with some kind of lock; this can be passed in or one will be created by default. (Passing one in is useful when several condition variables must share the same lock.) A condition variable has `acquire()' and `release()' methods that call the corresponding methods of the associated lock. It also has a `wait()' method, and `notify()' and `notifyAll()' methods. These three must only be called when the calling thread has acquired the lock. The `wait()' method releases the lock, and then blocks until it is awakened by a `notify()' or `notifyAll()' call for the same condition variable in another thread. Once awakened, it re-acquires the lock and returns. It is also possible to specify a timeout. The `notify()' method wakes up one of the threads waiting for the condition variable, if any are waiting. The `notifyAll()' method wakes up all threads waiting for the condition variable. Note: the `notify()' and `notifyAll()' methods don't release the lock; this means that the thread or threads awakened will not return from their `wait()' call immediately, but only when the thread that called `notify()' or `notifyAll()' finally relinquishes ownership of the lock. Tip: the typical programming style using condition variables uses the lock to synchronize access to some shared state; threads that are interested in a particular change of state call `wait()' repeatedly until they see the desired state, while threads that modify the state call `notify()' or `notifyAll()' when they change the state in such a way that it could possibly be a desired state for one of the waiters. For example, the following code is a generic producer-consumer situation with unlimited buffer capacity: # Consume one item cv.acquire() while not an_item_is_available(): cv.wait() get_an_available_item() cv.release() # Produce one item cv.acquire() make_an_item_available() cv.notify() cv.release() To choose between `notify()' and `notifyAll()', consider whether one state change can be interesting for only one or several waiting threads. E.g. in a typical producer-consumer situation, adding one item to the buffer only needs to wake up one consumer thread. `Condition([lock])' If the LOCK argument is given and not `None', it must be a `Lock' or `RLock' object, and it is used as the underlying lock. Otherwise, a new `RLock' object is created and used as the underlying lock. `acquire(*args)' Acquire the underlying lock. This method calls the corresponding method on the underlying lock; the return value is whatever that method returns. `release()' Release the underlying lock. This method calls the corresponding method on the underlying lock; there is no return value. `wait([timeout])' Wait until notified or until a timeout occurs. This must only be called when the calling thread has acquired the lock. This method releases the underlying lock, and then blocks until it is awakened by a `notify()' or `notifyAll()' call for the same condition variable in another thread, or until the optional timeout occurs. Once awakened or timed out, it re-acquires the lock and returns. When the TIMEOUT argument is present and not `None', it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). When the underlying lock is an `RLock', it is not released using its `release()' method, since this may not actually unlock the lock when it was acquired multiple times recursively. Instead, an internal interface of the `RLock' class is used, which really unlocks it even when it has been recursively acquired several times. Another internal interface is then used to restore the recursion level when the lock is reacquired. `notify()' Wake up a thread waiting on this condition, if any. This must only be called when the calling thread has acquired the lock. This method wakes up one of the threads waiting for the condition variable, if any are waiting; it is a no-op if no threads are waiting. The current implementation wakes up exactly one thread, if any are waiting. However, it's not safe to rely on this behavior. A future, optimized implementation may occasionally wake up more than one thread. Note: the awakened thread does not actually return from its `wait()' call until it can reacquire the lock. Since `notify()' does not release the lock, its caller should. `notifyAll()' Wake up all threads waiting on this condition. This method acts like `notify()', but wakes up all waiting threads instead of one.  File: python-lib.info, Node: Semaphore Objects, Next: Event Objects, Prev: Condition Objects, Up: threading Semaphore Objects ----------------- This is one of the oldest synchronization primitives in the history of computer science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he used `P()' and `V()' instead of `acquire()' and `release()'). A semaphore manages an internal counter which is decremented by each `acquire()' call and incremented by each `release()' call. The counter can never go below zero; when `acquire()' finds that it is zero, it blocks, waiting until some other thread calls `release()'. `Semaphore([value])' The optional argument gives the initial value for the internal counter; it defaults to `1'. `acquire([blocking])' Acquire a semaphore. When invoked without arguments: if the internal counter is larger than zero on entry, decrement it by one and return immediately. If it is zero on entry, block, waiting until some other thread has called `release()' to make it larger than zero. This is done with proper interlocking so that if multiple `acquire()' calls are blocked, `release()' will wake exactly one of them up. The implementation may pick one at random, so the order in which blocked threads are awakened should not be relied on. There is no return value in this case. When invoked with BLOCKING set to true, do the same thing as when called without arguments, and return true. When invoked with BLOCKING set to false, do not block. If a call without an argument would block, return false immediately; otherwise, do the same thing as when called without arguments, and return true. `release()' Release a semaphore, incrementing the internal counter by one. When it was zero on entry and another thread is waiting for it to become larger than zero again, wake up that thread.  File: python-lib.info, Node: Event Objects, Next: Thread Objects, Prev: Semaphore Objects, Up: threading Event Objects ------------- This is one of the simplest mechanisms for communication between threads: one thread signals an event and one or more other threads are waiting for it. An event object manages an internal flag that can be set to true with the `set()' method and reset to false with the `clear()' method. The `wait()' method blocks until the flag is true. `Event()' The internal flag is initially false. `isSet()' Return true if and only if the internal flag is true. `set()' Set the internal flag to true. All threads waiting for it to become true are awakened. Threads that call `wait()' once the flag is true will not block at all. `clear()' Reset the internal flag to false. Subsequently, threads calling `wait()' will block until `set()' is called to set the internal flag to true again. `wait([timeout])' Block until the internal flag is true. If the internal flag is true on entry, return immediately. Otherwise, block until another thread calls `set()' to set the flag to true, or until the optional timeout occurs. When the timeout argument is present and not `None', it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof).  File: python-lib.info, Node: Thread Objects, Prev: Event Objects, Up: threading Thread Objects -------------- This class represents an activity that is run in a separate thread of control. There are two ways to specify the activity: by passing a callable object to the constructor, or by overriding the `run()' method in a subclass. No other methods (except for the constructor) should be overridden in a subclass. In other words, _only_ override the `__init__()' and `run()' methods of this class. Once a thread object is created, its activity must be started by calling the thread's `start()' method. This invokes the `run()' method in a separate thread of control. Once the thread's activity is started, the thread is considered 'alive' and 'active' (these concepts are almost, but not quite exactly, the same; their definition is intentionally somewhat vague). It stops being alive and active when its `run()' method terminates - either normally, or by raising an unhandled exception. The `isAlive()' method tests whether the thread is alive. Other threads can call a thread's `join()' method. This blocks the calling thread until the thread whose `join()' method is called is terminated. A thread has a name. The name can be passed to the constructor, set with the `setName()' method, and retrieved with the `getName()' method. A thread can be flagged as a "daemon thread". The significance of this flag is that the entire Python program exits when only daemon threads are left. The initial value is inherited from the creating thread. The flag can be set with the `setDaemon()' method and retrieved with the `getDaemon()' method. There is a "main thread" object; this corresponds to the initial thread of control in the Python program. It is not a daemon thread. There is the possibility that "dummy thread objects" are created. These are thread objects corresponding to "alien threads". These are threads of control started outside the threading module, e.g. directly from C code. Dummy thread objects have limited functionality; they are always considered alive, active, and daemonic, and cannot be `join()'ed. They are never deleted, since it is impossible to detect the termination of alien threads. `Thread(group=None, target=None, name=None, args=(), kwargs={})' This constructor should always be called with keyword arguments. Arguments are: GROUP Should be `None'; reserved for future extension when a `ThreadGroup' class is implemented. TARGET Callable object to be invoked by the `run()' method. Defaults to `None', meaning nothing is called. NAME The thread name. By default, a unique name is constructed of the form "Thread-N" where N is a small decimal number. ARGS Argument tuple for the target invocation. Defaults to `()'. KWARGS Keyword argument dictionary for the target invocation. Defaults to `{}'. If the subclass overrides the constructor, it must make sure to invoke the base class constructor (`Thread.__init__()') before doing anything else to the thread. `start()' Start the thread's activity. This must be called at most once per thread object. It arranges for the object's `run()' method to be invoked in a separate thread of control. `run()' Method representing the thread's activity. You may override this method in a subclass. The standard `run()' method invokes the callable object passed to the object's constructor as the TARGET argument, if any, with sequential and keyword arguments taken from the ARGS and KWARGS arguments, respectively. `join([timeout])' Wait until the thread terminates. This blocks the calling thread until the thread whose `join()' method is called terminates - either normally or through an unhandled exception - or until the optional timeout occurs. When the TIMEOUT argument is present and not `None', it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). A thread can be `join()'ed many times. A thread cannot join itself because this would cause a deadlock. It is an error to attempt to `join()' a thread before it has been started. `getName()' Return the thread's name. `setName(name)' Set the thread's name. The name is a string used for identification purposes only. It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor. `isAlive()' Return whether the thread is alive. Roughly, a thread is alive from the moment the `start()' method returns until its `run()' method terminates. `isDaemon()' Return the thread's daemon flag. `setDaemon(daemonic)' Set the thread's daemon flag to the Boolean value DAEMONIC. This must be called before `start()' is called. The initial value is inherited from the creating thread. The entire Python program exits when no active non-daemon threads are left.  File: python-lib.info, Node: Queue, Next: mmap, Prev: threading, Up: Optional Operating System Services A synchronized queue class ========================== A synchronized queue class. The `Queue' module implements a multi-producer, multi-consumer FIFO queue. It is especially useful in threads programming when information must be exchanged safely between multiple threads. The `Queue' class in this module implements all the required locking semantics. It depends on the availability of thread support in Python. The `Queue' module defines the following class and exception: `Queue(maxsize)' Constructor for the class. MAXSIZE is an integer that sets the upperbound limit on the number of items that can be placed in the queue. Insertion will block once this size has been reached, until queue items are consumed. If MAXSIZE is less than or equal to zero, the queue size is infinite. `Empty' Exception raised when non-blocking `get()' (or `get_nowait()') is called on a `Queue' object which is empty or locked. `Full' Exception raised when non-blocking `put()' (or `put_nowait()') is called on a `Queue' object which is full or locked. * Menu: * Queue Objects::  File: python-lib.info, Node: Queue Objects, Prev: Queue, Up: Queue Queue Objects ------------- Class `Queue' implements queue objects and has the methods described below. This class can be derived from in order to implement other queue organizations (e.g. stack) but the inheritable interface is not described here. See the source code for details. The public methods are: `qsize()' Return the approximate size of the queue. Because of multithreading semantics, this number is not reliable. `empty()' Return `1' if the queue is empty, `0' otherwise. Because of multithreading semantics, this is not reliable. `full()' Return `1' if the queue is full, `0' otherwise. Because of multithreading semantics, this is not reliable. `put(item[, block])' Put ITEM into the queue. If optional argument BLOCK is 1 (the default), block if necessary until a free slot is available. Otherwise (BLOCK is 0), put ITEM on the queue if a free slot is immediately available, else raise the `Full' exception. `put_nowait(item)' Equivalent to `put(ITEM, 0)'. `get([block])' Remove and return an item from the queue. If optional argument BLOCK is 1 (the default), block if necessary until an item is available. Otherwise (BLOCK is 0), return an item if one is immediately available, else raise the `Empty' exception. `get_nowait()' Equivalent to `get(0)'.  File: python-lib.info, Node: mmap, Next: anydbm, Prev: Queue, Up: Optional Operating System Services Memory-mapped file support ========================== Interface to memory-mapped files for Unix and Windows. Memory-mapped file objects behave like both mutable strings and like file objects. You can use mmap objects in most places where strings are expected; for example, you can use the `re' module to search through a memory-mapped file. Since they're mutable, you can change a single character by doing `obj[INDEX] = 'a'', or change a substring by assigning to a slice: `obj[I1:I2] = '...''. You can also read and write data starting at the current file position, and `seek()' through the file to different positions. A memory-mapped file is created by the following function, which is different on Unix and on Windows. `mmap(fileno, length[, tagname])' *(Windows version)* Maps LENGTH bytes from the file specified by the file handle FILENO, and returns a mmap object. If LENGTH is `0', the maximum length of the map will be the current size of the file when `mmap()' is called. If you wish to map an existing Python file object, use its `fileno()' method to obtain the correct value for the FILENO parameter. The file must be opened for update. TAGNAME, if specified and not `None', is a string giving a tag name for the mapping. Windows allows you to have many different mappings against the same file. If you specify the name of an existing tag, that tag is opened, otherwise a new tag of this name is created. If this parameter is omitted or `None', the mapping is created without a name. Avoiding the use of the tag parameter will assist in keeping your code portable between UNIX and Windows. `mmap(fileno, size[, flags, prot])' *(UNIX version)* Maps LENGTH bytes from the file specified by the file handle FILENO, and returns a mmap object. If you wish to map an existing Python file object, use its `fileno()' method to obtain the correct value for the FILENO parameter. The file must be opened for update. FLAGS specifies the nature of the mapping. `MAP_PRIVATE' creates a private copy-on-write mapping, so changes to the contents of the mmap object will be private to this process, and `MAP_SHARED' creates a mapping that's shared with all other processes mapping the same areas of the file. The default value is `MAP_SHARED'. PROT, if specified, gives the desired memory protection; the two most useful values are `PROT_READ' and `PROT_WRITE', to specify that the pages may be read or written. PROT defaults to `PROT_READ | PROT_WRITE'. Memory-mapped file objects support the following methods: `close()' Close the file. Subsequent calls to other methods of the object will result in an exception being raised. `find(string[, start])' Returns the lowest index in the object where the substring STRING is found. Returns `-1' on failure. START is the index at which the search begins, and defaults to zero. `flush([offset, size])' Flushes changes made to the in-memory copy of a file back to disk. Without use of this call there is no guarantee that changes are written back before the object is destroyed. If OFFSET and SIZE are specified, only changes to the given range of bytes will be flushed to disk; otherwise, the whole extent of the mapping is flushed. `move(DEST, SRC, COUNT)' Copy the COUNT bytes starting at offset SRC to the destination index DEST. `read(NUM)' Return a string containing up to NUM bytes starting from the current file position; the file position is updated to point after the bytes that were returned. `read_byte()' Returns a string of length 1 containing the character at the current file position, and advances the file position by 1. `readline()' Returns a single line, starting at the current file position and up to the next newline. `resize(NEWSIZE)' `seek(pos[, whence])' Set the file's current position. 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). `size()' Return the length of the file, which can be larger than the size of the memory-mapped area. `tell()' Returns the current position of the file pointer. `write(STRING)' Write the bytes in STRING into memory at the current position of the file pointer; the file position is updated to point after the bytes that were written. `write_byte(BYTE)' Write the single-character string BYTE into memory at the current position of the file pointer; the file position is advanced by `1'.  File: python-lib.info, Node: anydbm, Next: dumbdbm, Prev: mmap, Up: Optional Operating System Services Generic access to DBM-style databases ===================================== Generic interface to DBM-style database modules. `anydbm' is a generic interface to variants of the DBM database -- `dbhash' (requires `bsddb'), `gdbm', or `dbm'. If none of these modules is installed, the slow-but-simple implementation in module `dumbdbm' will be used. `open(filename[, flag[, mode]])' Open the database file FILENAME and return a corresponding object. If the database file already exists, the `whichdb' module is used to determine its type and the appropriate module is used; if it does not exist, the first module listed above that can be imported is used. The optional FLAG argument can be `'r'' to open an existing database for reading only, `'w'' to open an existing database for reading and writing, `'c'' to create the database if it doesn't exist, or `'n'', which will always create a new empty database. If not specified, the default value is `'r''. The optional MODE argument is the UNIX mode of the file, used only when the database has to be created. It defaults to octal `0666' (and will be modified by the prevailing umask). `error' A tuple containing the exceptions that can be raised by each of the supported modules, with a unique exception `anydbm.error' as the first item -- the latter is used when `anydbm.error' is raised. The object returned by `open()' supports most of the same functionality as dictionaries; keys and their corresponding values can be stored, retrieved, and deleted, and the `has_key()' and `keys()' methods are available. Keys and values must always be strings. See also: *Note anydbm:: Generic interface to `dbm'-style databases. *Note dbhash:: BSD `db' database interface. *Note dbm:: Standard UNIX database interface. *Note dumbdbm:: Portable implementation of the `dbm' interface. *Note gdbm:: GNU database interface, based on the `dbm' interface. *Note shelve:: General object persistence built on top of the Python `dbm' interface. *Note whichdb:: Utility module used to determine the type of an existing database.  File: python-lib.info, Node: dumbdbm, Next: dbhash, Prev: anydbm, Up: Optional Operating System Services Portable DBM implementation =========================== Portable implementation of the simple DBM interface. A simple and slow database implemented entirely in Python. This should only be used when no other DBM-style database is available. `open(filename[, flag[, mode]])' Open the database file FILENAME and return a corresponding object. The optional FLAG argument can be `'r'' to open an existing database for reading only, `'w'' to open an existing database for reading and writing, `'c'' to create the database if it doesn't exist, or `'n'', which will always create a new empty database. If not specified, the default value is `'r''. The optional MODE argument is the UNIX mode of the file, used only when the database has to be created. It defaults to octal `0666' (and will be modified by the prevailing umask). `error' Raised for errors not reported as `KeyError' errors. See also: *Note anydbm:: Generic interface to `dbm'-style databases. *Note whichdb:: Utility module used to determine the type of an existing database.  File: python-lib.info, Node: dbhash, Next: whichdb, Prev: dumbdbm, Up: Optional Operating System Services DBM-style interface to the BSD database library =============================================== DBM-style interface to the BSD database library. This section was written by Fred L. Drake, Jr. . The `dbhash' module provides a function to open databases using the BSD `db' library. This module mirrors the interface of the other Python database modules that provide access to DBM-style databases. The `bsddb' module is required to use `dbhash'. This module provides an exception and a function: `error' Exception raised on database errors other than `KeyError'. It is a synonym for `bsddb.error'. `open(path, flag[, mode])' Open a `db' database and return the database object. The PATH argument is the name of the database file. The FLAG argument can be `'r'' (the default), `'w'', `'c'' (which creates the database if it doesn't exist), or `'n'' (which always creates a new empty database). For platforms on which the BSD `db' library supports locking, an `l' can be appended to indicate that locking should be used. The optional MODE parameter is used to indicate the UNIX permission bits that should be set if a new database must be created; this will be masked by the current umask value for the process. See also: *Note anydbm:: Generic interface to `dbm'-style databases. *Note bsddb:: Lower-level interface to the BSD `db' library. *Note whichdb:: Utility module used to determine the type of an existing database. * Menu: * Database Objects::  File: python-lib.info, Node: Database Objects, Prev: dbhash, Up: dbhash Database Objects ---------------- The database objects returned by `open()' provide the methods common to all the DBM-style databases. The following methods are available in addition to the standard methods. `first()' It's possible to loop over every key in the database using this method and the `next()' method. The traversal is ordered by the databases internal hash values, and won't be sorted by the key values. This method returns the starting key. `last()' Return the last key in a database traversal. This may be used to begin a reverse-order traversal; see `previous()'. `next(key)' Returns the key that follows KEY in the traversal. The following code prints every key in the database `db', without having to create a list in memory that contains them all: k = db.first() while k != None: print k k = db.next(k) `previous(key)' Return the key that comes before KEY in a forward-traversal of the database. In conjunction with `last()', this may be used to implement a reverse-order traversal. `sync()' This method forces any unwritten data to be written to the disk.  File: python-lib.info, Node: whichdb, Next: bsddb, Prev: dbhash, Up: Optional Operating System Services Guess which DBM module created a database ========================================= Guess which DBM-style module created a given database. The single function in this module attempts to guess which of the several simple database modules available-`dbm', `gdbm', or `dbhash'-should be used to open a given file. `whichdb(filename)' Returns one of the following values: `None' if the file can't be opened because it's unreadable or doesn't exist; the empty string (`''') if the file's format can't be guessed; or a string containing the required module name, such as `'dbm'' or `'gdbm''.  File: python-lib.info, Node: bsddb, Next: zlib, Prev: whichdb, Up: Optional Operating System Services Interface to Berkeley DB library ================================ Interface to Berkeley DB database library This section was written by Skip Montanaro . The `bsddb' module provides an interface to the Berkeley DB library. Users can create hash, btree or record based library files using the appropriate open call. Bsddb objects behave generally like dictionaries. Keys and values must be strings, however, so to use other objects as keys or to store other kinds of objects the user must serialize them somehow, typically using marshal.dumps or pickle.dumps. There are two incompatible versions of the underlying library. Version 1.85 is widely available, but has some known bugs. Version 2 is not quite as widely used, but does offer some improvements. The `bsddb' module uses the 1.85 interface. Starting with Python 2.0, the `configure' script can usually determine the version of the library which is available and build it correctly. If you have difficulty getting `configure' to do the right thing, run it with the `--help' option to get information about additional options that can help. On Windows, you will need to define the `HAVE_DB_185_H' macro if you are building Python from source and using version 2 of the DB library. The `bsddb' module defines the following functions that create objects that access the appropriate type of Berkeley DB file. The first two arguments of each function are the same. For ease of portability, only the first two arguments should be used in most instances. `hashopen(filename[, flag[, mode[, bsize[, ffactor[, nelem[, cachesize[, hash[, lorder]]]]]]]])' Open the hash format file named FILENAME. The optional FLAG identifies the mode used to open the file. It may be `r' (read only), `w' (read-write), `c' (read-write - create if necessary) or `n' (read-write - truncate to zero length). The other arguments are rarely used and are just passed to the low-level `dbopen()' function. Consult the Berkeley DB documentation for their use and interpretation. `btopen(filename[, flag[, mode[, btflags[, cachesize[, maxkeypage[, minkeypage[, psize[, lorder]]]]]]]])' Open the btree format file named FILENAME. The optional FLAG identifies the mode used to open the file. It may be `r' (read only), `w' (read-write), `c' (read-write - create if necessary) or `n' (read-write - truncate to zero length). The other arguments are rarely used and are just passed to the low-level dbopen function. Consult the Berkeley DB documentation for their use and interpretation. `rnopen(filename[, flag[, mode[, rnflags[, cachesize[, psize[, lorder[, reclen[, bval[, bfname]]]]]]]]])' Open a DB record format file named FILENAME. The optional FLAG identifies the mode used to open the file. It may be `r' (read only), `w' (read-write), `c' (read-write - create if necessary) or `n' (read-write - truncate to zero length). The other arguments are rarely used and are just passed to the low-level dbopen function. Consult the Berkeley DB documentation for their use and interpretation. See also: *Note dbhash:: DBM-style interface to the `bsddb' * Menu: * Hash::  File: python-lib.info, Node: Hash, Prev: bsddb, Up: bsddb Hash, BTree and Record Objects ------------------------------ Once instantiated, hash, btree and record objects support the following methods: `close()' Close the underlying file. The object can no longer be accessed. Since there is no open `open' method for these objects, to open the file again a new `bsddb' module open function must be called. `keys()' Return the list of keys contained in the DB file. The order of the list is unspecified and should not be relied on. In particular, the order of the list returned is different for different file formats. `has_key(key)' Return `1' if the DB file contains the argument as a key. `set_location(key)' Set the cursor to the item indicated by KEY and return a tuple containing the key and its value. For binary tree databases (opened using `btopen()'), if KEY does not actually exist in the database, the cursor will point to the next item in sorted order and return that key and value. For other databases, `KeyError' will be raised if KEY is not found in the database. `first()' Set the cursor to the first item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases. `next()' Set the cursor to the next item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases. `previous()' Set the cursor to the first item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases. This is not supported on hashtable databases (those opened with `hashopen()'). `last()' Set the cursor to the last item in the DB file and return it. The order of keys in the file is unspecified. This is not supported on hashtable databases (those opened with `hashopen()'). `sync()' Synchronize the database on disk. Example: >>> import bsddb >>> db = bsddb.btopen('/tmp/spam.db', 'c') >>> for i in range(10): db['%d'%i] = '%d'% (i*i) ... >>> db['3'] '9' >>> db.keys() ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] >>> db.first() ('0', '0') >>> db.next() ('1', '1') >>> db.last() ('9', '81') >>> db.set_location('2') ('2', '4') >>> db.previous() ('1', '1') >>> db.sync() 0  File: python-lib.info, Node: zlib, Next: gzip, Prev: bsddb, Up: Optional Operating System Services Compression compatible with `gzip' ================================== Low-level interface to compression and decompression routines compatible with `gzip'. For applications that require data compression, the functions in this module allow compression and decompression, using the zlib library. The zlib library has its own home page at . Version 1.1.3 is the most recent version as of September 2000; use a later version if one is available. There are known incompatibilities between the Python module and earlier versions of the zlib library. The available exception and functions in this module are: `error' Exception raised on compression and decompression errors. `adler32(string[, value])' Computes a Adler-32 checksum of STRING. (An Adler-32 checksum is almost as reliable as a CRC32 but can be computed much more quickly.) If VALUE is present, it is used as the starting value of the checksum; otherwise, a fixed default value is used. This allows computing a running checksum over the concatenation of several input strings. The algorithm is not cryptographically strong, and should not be used for authentication or digital signatures. `compress(string[, level])' Compresses the data in STRING, returning a string contained compressed data. LEVEL is an integer from `1' to `9' controlling the level of compression; `1' is fastest and produces the least compression, `9' is slowest and produces the most. The default value is `6'. Raises the `error' exception if any error occurs. `compressobj([level])' Returns a compression object, to be used for compressing data streams that won't fit into memory at once. LEVEL is an integer from `1' to `9' controlling the level of compression; `1' is fastest and produces the least compression, `9' is slowest and produces the most. The default value is `6'. `crc32(string[, value])' Computes a CRC (Cyclic Redundancy Check) checksum of STRING. If VALUE is present, it is used as the starting value of the checksum; otherwise, a fixed default value is used. This allows computing a running checksum over the concatenation of several input strings. The algorithm is not cryptographically strong, and should not be used for authentication or digital signatures. `decompress(string[, wbits[, bufsize]])' Decompresses the data in STRING, returning a string containing the uncompressed data. The WBITS parameter controls the size of the window buffer. If BUFSIZE is given, it is used as the initial size of the output buffer. Raises the `error' exception if any error occurs. The absolute value of WBITS is the base two logarithm of the size of the history buffer (the "window size") used when compressing data. Its absolute value should be between 8 and 15 for the most recent versions of the zlib library, larger values resulting in better compression at the expense of greater memory usage. The default value is 15. When WBITS is negative, the standard `gzip' header is suppressed; this is an undocumented feature of the zlib library, used for compatibility with `unzip''s compression file format. BUFSIZE is the initial size of the buffer used to hold decompressed data. If more space is required, the buffer size will be increased as needed, so you don't have to get this value exactly right; tuning it will only save a few calls to `malloc()'. The default size is 16384. `decompressobj([wbits])' Returns a compression object, to be used for decompressing data streams that won't fit into memory at once. The WBITS parameter controls the size of the window buffer. Compression objects support the following methods: `compress(string)' Compress STRING, returning a string containing compressed data for at least part of the data in STRING. This data should be concatenated to the output produced by any preceding calls to the `compress()' method. Some input may be kept in internal buffers for later processing. `flush([mode])' All pending input is processed, and a string containing the remaining compressed output is returned. MODE can be selected from the constants `Z_SYNC_FLUSH', `Z_FULL_FLUSH', or `Z_FINISH', defaulting to `Z_FINISH'. `Z_SYNC_FLUSH' and `Z_FULL_FLUSH' allow compressing further strings of data and are used to allow partial error recovery on decompression, while `Z_FINISH' finishes the compressed stream and prevents compressing any more data. After calling `flush()' with MODE set to `Z_FINISH', the `compress()' method cannot be called again; the only realistic action is to delete the object. Decompression objects support the following methods, and a single attribute: `unused_data' A string which contains any unused data from the last string fed to this decompression object. If the whole string turned out to contain compressed data, this is `""', the empty string. The only way to determine where a string of compressed data ends is by actually decompressing it. This means that when compressed data is contained part of a larger file, you can only find the end of it by reading data and feeding it into a decompression object's `decompress' method until the `unused_data' attribute is no longer the empty string. `decompress(string)' Decompress STRING, returning a string containing the uncompressed data corresponding to at least part of the data in STRING. This data should be concatenated to the output produced by any preceding calls to the `decompress()' method. Some of the input data may be preserved in internal buffers for later processing. `flush()' All pending input is processed, and a string containing the remaining uncompressed output is returned. After calling `flush()', the `decompress()' method cannot be called again; the only realistic action is to delete the object. See also: *Note gzip:: Reading and writing `gzip'-format files. The zlib library home page.  File: python-lib.info, Node: gzip, Next: zipfile, Prev: zlib, Up: Optional Operating System Services Support for `gzip' files ======================== Interfaces for `gzip' compression and decompression using file objects. The data compression provided by the `zlib' module is compatible with that used by the GNU compression program `gzip'. Accordingly, the `gzip' module provides the `GzipFile' class to read and write `gzip'-format files, automatically compressing or decompressing the data so it looks like an ordinary file object. Note that additional file formats which can be decompressed by the `gzip' and `gunzip' programs, such as those produced by `compress' and `pack', are not supported by this module. The module defines the following items: `GzipFile([filename[, mode[, compresslevel[, fileobj]]]])' Constructor for the `GzipFile' class, which simulates most of the methods of a file object, with the exception of the `seek()' and `tell()' methods. At least one of FILEOBJ and FILENAME must be given a non-trivial value. The new class instance is based on FILEOBJ, which can be a regular file, a `StringIO' object, or any other object which simulates a file. It defaults to `None', in which case FILENAME is opened to provide a file object. When FILEOBJ is not `None', the FILENAME argument is only used to be included in the `gzip' file header, which may includes the original filename of the uncompressed file. It defaults to the filename of FILEOBJ, if discernible; otherwise, it defaults to the empty string, and in this case the original filename is not included in the header. The MODE argument can be any of `'r'', `'rb'', `'a'', `'ab'', `'w'', or `'wb'', depending on whether the file will be read or written. The default is the mode of FILEOBJ if discernible; otherwise, the default is `'rb''. Be aware that only the `'rb'', `'ab'', and `'wb'' values should be used for cross-platform portability. The COMPRESSLEVEL argument is an integer from `1' to `9' controlling the level of compression; `1' is fastest and produces the least compression, and `9' is slowest and produces the most compression. The default is `9'. Calling a `GzipFile' object's `close()' method does not close FILEOBJ, since you might wish to append more material after the compressed data. This also allows you to pass a `StringIO' object opened for writing as FILEOBJ, and retrieve the resulting memory buffer using the `StringIO' object's `getvalue()' method. `open(filename[, mode[, compresslevel]])' This is a shorthand for `GzipFile(FILENAME,' `MODE,' `COMPRESSLEVEL)'. The FILENAME argument is required; MODE defaults to `'rb'' and COMPRESSLEVEL defaults to `9'. See also: *Note zlib:: The basic data compression module needed to support the `gzip' file format.  File: python-lib.info, Node: zipfile, Next: readline, Prev: gzip, Up: Optional Operating System Services Work with ZIP archives ====================== Read and write ZIP-format archive files. This module was documented by James C. Ahlstrom . This section was written by James C. Ahlstrom . _Added in Python version 1.6_ The ZIP file format is a common archive and compression standard. This module provides tools to create, read, write, append, and list a ZIP file. Any advanced use of this module will require an understanding of the format, as defined in . This module does not currently handle ZIP files which have appended comments, or multi-disk ZIP files. The available attributes of this module are: `error' The error raised for bad ZIP files. `ZipFile(...)' The class for reading and writing ZIP files. See "" (section *Note ZipFile Objects::) for constructor details. `PyZipFile(...)' Class for creating ZIP archives containing Python libraries. `ZipInfo([filename[, date_time]])' Class used the represent infomation about a member of an archive. Instances of this class are returned by the `getinfo()' and `infolist()' methods of `ZipFile' objects. Most users of the `zipfile' module will not need to create these, but only use those created by this module. FILENAME should be the full name of the archive member, and DATE_TIME should be a tuple containing six fields which describe the time of the last modification to the file; the fields are described in section *Note readline::, "ZipInfo Objects." `is_zipfile(filename)' Returns true if FILENAME is a valid ZIP file based on its magic number, otherwise returns false. This module does not currently handle ZIP files which have appended comments. `ZIP_STORED' The numeric constant for an uncompressed archive member. `ZIP_DEFLATED' The numeric constant for the usual ZIP compression method. This requires the zlib module. No other compression methods are currently supported. See also: `PKZIP Application Note'{Documentation on the ZIP file format by Phil Katz, the creator of the format and algorithms used.} `Info-ZIP Home Page'{ Information about the Info-ZIP project's ZIP archive programs and development libraries.} * Menu: * ZipFile Objects:: * PyZipFile Objects:: * ZipInfo Objects::  File: python-lib.info, Node: ZipFile Objects, Next: PyZipFile Objects, Prev: zipfile, Up: zipfile ZipFile Objects --------------- `ZipFile(filename[, mode[, compression]])' Open a ZIP file named FILENAME. The MODE parameter should be `'r'' to read an existing file, `'w'' to truncate and write a new file, or `'a'' to append to an existing file. For MODE is `'a'' and FILENAME refers to an existing ZIP file, then additional files are added to it. If FILENAME does not refer to a ZIP file, then a new ZIP archive is appended to the file. This is meant for adding a ZIP archive to another file, such as `python.exe'. Using cat myzip.zip >> python.exe also works, and at least `WinZip' can read such files. COMPRESSION is the ZIP compression method to use when writing the archive, and should be `ZIP_STORED' or `ZIP_DEFLATED'; unrecognized values will cause `RuntimeError' to be raised. If `ZIP_DEFLATED' is specified but the `zlib' module is not avaialble, `RuntimeError' is also raised. The default is `ZIP_STORED'. `close()' Close the archive file. You must call `close()' before exiting your program or essential records will not be written. `getinfo(name)' Return a `ZipInfo' object with information about the archive member NAME. `infolist()' Return a list containing a `ZipInfo' object for each member of the archive. The objects are in the same order as their entries in the actual ZIP file on disk if an existing archive was opened. `namelist()' Return a list of archive members by name. `printdir()' Print a table of contents for the archive to `sys.stdout'. `read(name)' Return the bytes of the file in the archive. The archive must be open for read or append. `testzip()' Read all the files in the archive and check their CRC's. Return the name of the first bad file, or else return `None'. `write(filename[, arcname[, compress_type]])' Write the file named FILENAME to the archive, giving it the archive name ARCNAME (by default, this will be the same as FILENAME). If given, COMPRESS_TYPE overrides the value given for the COMPRESSION parameter to the constructor for the new entry. The archive must be open with mode `'w'' or `'a''. `writestr(zinfo, bytes)' Write the string BYTES to the archive; meta-information is given as the `ZipInfo' instance ZINFO. At least the filename, date, and time must be given by ZINFO. The archive must be opened with mode `'w'' or `'a''. The following data attribute is also available: `debug' The level of debug output to use. This may be set from `0' (the default, no output) to `3' (the most output). Debugging information is written to `sys.stdout'.