IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Initial checkin of the 2.6 and 3.0 doc trees.

Browse Source
This commit is contained in:
Georg Brandl
2007-08-02 09:06:31 +00:00
parent 0a42ade463
commit 92c411dc90
839 changed files with 256023 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
Doc-3k/library/__builtin__.rst Normal file
View File

@@ -0,0 +1,41 @@
:mod:`__builtin__` --- Built-in objects
=======================================
.. module:: __builtin__
:synopsis: The module that provides the built-in namespace.
This module provides direct access to all 'built-in' identifiers of Python; for
example, ``__builtin__.open`` is the full name for the built-in function
:func:`open`. See chapter :ref:`builtin`, "Built-in Objects."
This module is not normally accessed explicitly by most applications, but can be
useful in modules that provide objects with the same name as a built-in value,
but in which the built-in of that name is also needed. For example, in a module
that wants to implement an :func:`open` function that wraps the built-in
:func:`open`, this module can be used directly::
import __builtin__
def open(path):
f = __builtin__.open(path, 'r')
return UpperCaser(f)
class UpperCaser:
'''Wrapper around a file that converts output to upper-case.'''
def __init__(self, f):
self._f = f
def read(self, count=-1):
return self._f.read(count).upper()
# ...
As an implementation detail, most modules have the name ``__builtins__`` (note
the ``'s'``) made available as part of their globals. The value of
``__builtins__`` is normally either this module or the value of this modules's
:attr:`__dict__` attribute. Since this is an implementation detail, it may not
be used by alternate implementations of Python.

61
Doc-3k/library/__future__.rst Normal file
View File

@@ -0,0 +1,61 @@
:mod:`__future__` --- Future statement definitions
==================================================
.. module:: __future__
:synopsis: Future statement definitions
:mod:`__future__` is a real module, and serves three purposes:
* To avoid confusing existing tools that analyze import statements and expect to
find the modules they're importing.
* To ensure that future_statements run under releases prior to 2.1 at least
yield runtime exceptions (the import of :mod:`__future__` will fail, because
there was no module of that name prior to 2.1).
* To document when incompatible changes were introduced, and when they will be
--- or were --- made mandatory. This is a form of executable documentation, and
can be inspected programatically via importing :mod:`__future__` and examining
its contents.
Each statement in :file:`__future__.py` is of the form::
FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
CompilerFlag ")"
where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
5-tuples of the same form as ``sys.version_info``::
(PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
PY_MINOR_VERSION, # the 1; an int
PY_MICRO_VERSION, # the 0; an int
PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
PY_RELEASE_SERIAL # the 3; an int
)
*OptionalRelease* records the first release in which the feature was accepted.
In the case of a *MandatoryRelease* that has not yet occurred,
*MandatoryRelease* predicts the release in which the feature will become part of
the language.
Else *MandatoryRelease* records when the feature became part of the language; in
releases at or after that, modules no longer need a future statement to use the
feature in question, but may continue to use such imports.
*MandatoryRelease* may also be ``None``, meaning that a planned feature got
dropped.
Instances of class :class:`_Feature` have two corresponding methods,
:meth:`getOptionalRelease` and :meth:`getMandatoryRelease`.
*CompilerFlag* is the (bitfield) flag that should be passed in the fourth
argument to the builtin function :func:`compile` to enable the feature in
dynamically compiled code. This flag is stored in the :attr:`compiler_flag`
attribute on :class:`_Feature` instances.
No feature description will ever be deleted from :mod:`__future__`.

17
Doc-3k/library/__main__.rst Normal file
View File

@@ -0,0 +1,17 @@
:mod:`__main__` --- Top-level script environment
================================================
.. module:: __main__
:synopsis: The environment where the top-level script is run.
This module represents the (otherwise anonymous) scope in which the
interpreter's main program executes --- commands read either from standard
input, from a script file, or from an interactive prompt. It is this
environment in which the idiomatic "conditional script" stanza causes a script
to run::
if __name__ == "__main__":
main()

420
Doc-3k/library/_winreg.rst Normal file
View File

@@ -0,0 +1,420 @@
:mod:`_winreg` -- Windows registry access
=========================================
.. module:: _winreg
:platform: Windows
:synopsis: Routines and objects for manipulating the Windows registry.
.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
.. versionadded:: 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:
.. function:: 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 via
:meth:`handle.Close`), it is closed when the *hkey* object is destroyed by
Python.
.. function:: ConnectRegistry(computer_name, key)
Establishes a connection to a predefined registry handle on another computer,
and returns a :dfn:`handle object`
*computer_name* is the name of the remote computer, of the form
``r"\\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
:exc:`EnvironmentError` exception is raised.
.. function:: CreateKey(key, sub_key)
Creates or opens the specified key, returning a :dfn:`handle object`
*key* is an already open key, or one of the predefined :const:`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
:exc:`EnvironmentError` exception is raised.
.. function:: DeleteKey(key, sub_key)
Deletes the specified key.
*key* is an already open key, or any one of the predefined :const:`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 :exc:`EnvironmentError` exception is raised.
.. function:: DeleteValue(key, value)
Removes a named value from a registry key.
*key* is an already open key, or one of the predefined :const:`HKEY_\*`
constants.
*value* is a string that identifies the value to remove.
.. function:: 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 :const:`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 :exc:`EnvironmentError` exception is
raised, indicating, no more values are available.
.. function:: 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 :const:`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 :exc:`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 |
+-------+--------------------------------------------+
.. function:: FlushKey(key)
Writes all the attributes of a key to the registry.
*key* is an already open key, or one of the predefined :const:`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 :func:`CloseKey`, the
:func:`FlushKey` method returns only when all the data has been written to the
registry. An application should only call :func:`FlushKey` if it requires
absolute certainty that registry changes are on disk.
.. note::
If you don't know whether a :func:`FlushKey` call is required, it probably
isn't.
.. function:: 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 :const:`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 :func:`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
:const:`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 :func:`ConnectRegistry`, then the path
specified in *fileName* is relative to the remote computer.
The Win32 documentation implies *key* must be in the :const:`HKEY_USER` or
:const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true.
.. function:: OpenKey(key, sub_key[, res\ ``= 0``][, sam\ ``= KEY_READ``])
Opens the specified key, returning a :dfn:`handle object`
*key* is an already open key, or any one of the predefined :const:`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 :const:`KEY_READ`
The result is a new handle to the specified key.
If the function fails, :exc:`EnvironmentError` is raised.
.. function:: OpenKeyEx()
The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the
use of default arguments.
.. function:: QueryInfoKey(key)
Returns information about a key, as a tuple.
*key* is an already open key, or one of the predefined :const:`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. |
+-------+---------------------------------------------+
.. function:: 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 :const:`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 :func:`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!!!
.. function:: 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 :const:`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. |
+-------+-----------------------------------------+
.. function:: 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 :const:`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 :meth:`LoadKey`, :meth:`ReplaceKey`
or :meth:`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 :const:`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.
.. function:: SetValue(key, sub_key, type, value)
Associates a value with a specified key.
*key* is an already open key, or one of the predefined :const:`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
:const:`REG_SZ`, meaning only strings are supported. Use the :func:`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
:const:`KEY_SET_VALUE` access.
.. function:: 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 :const:`HKEY_\*`
constants.
*value_name* 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 |
+==================================+=============================================+
| :const:`REG_BINARY` | Binary data in any form. |
+----------------------------------+---------------------------------------------+
| :const:`REG_DWORD` | A 32-bit number. |
+----------------------------------+---------------------------------------------+
| :const:`REG_DWORD_LITTLE_ENDIAN` | A 32-bit number in little-endian format. |
+----------------------------------+---------------------------------------------+
| :const:`REG_DWORD_BIG_ENDIAN` | A 32-bit number in big-endian format. |
+----------------------------------+---------------------------------------------+
| :const:`REG_EXPAND_SZ` | Null-terminated string containing |
| | references to environment variables |
| | (``%PATH%``). |
+----------------------------------+---------------------------------------------+
| :const:`REG_LINK` | A Unicode symbolic link. |
+----------------------------------+---------------------------------------------+
| :const:`REG_MULTI_SZ` | A sequence of null-terminated strings, |
| | terminated by two null characters. (Python |
| | handles this termination automatically.) |
+----------------------------------+---------------------------------------------+
| :const:`REG_NONE` | No defined value type. |
+----------------------------------+---------------------------------------------+
| :const:`REG_RESOURCE_LIST` | A device-driver resource list. |
+----------------------------------+---------------------------------------------+
| :const:`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
:const:`KEY_SET_VALUE` access.
To open the key, use the :func:`CreateKeyEx` or :func:`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.
.. _handle-object:
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
:meth:`Close` method on the object, or the :func:`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 :meth:`__bool__` - thus ::
if handle:
print "Yes"
will print ``Yes`` if the handle is currently valid (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 (e.g., using the builtin
:func:`int` function), in which case the underlying Windows handle value is
returned. You can also use the :meth:`Detach` method to return the integer
handle, and also disconnect the Windows handle from the handle object.
.. method:: PyHKEY.Close()
Closes the underlying Windows handle.
If the handle is already closed, no error is raised.
.. method:: PyHKEY.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.

225
Doc-3k/library/aifc.rst Normal file
View File

@@ -0,0 +1,225 @@
:mod:`aifc` --- Read and write AIFF and AIFC files
==================================================
.. module:: aifc
:synopsis: Read and write audio files in AIFF or AIFC format.
.. index::
single: Audio Interchange File Format
single: AIFF
single: AIFF-C
This module provides support for reading and writing AIFF and AIFF-C files.
AIFF is Audio Interchange File Format, a format for storing digital audio
samples in a file. AIFF-C is a newer version of the format that includes the
ability to compress the audio data.
**Caveat:** Some operations may only work under IRIX; these will raise
:exc:`ImportError` when attempting to import the :mod:`cl` module, which is only
available on IRIX.
Audio files have a number of parameters that describe the audio data. The
sampling rate or frame rate is the number of times per second the sound is
sampled. The number of channels indicate if the audio is mono, stereo, or
quadro. Each frame consists of one sample per channel. The sample size is the
size in bytes of each sample. Thus a frame consists of
*nchannels*\**samplesize* bytes, and a second's worth of audio consists of
*nchannels*\**samplesize*\**framerate* bytes.
For example, CD quality audio has a sample size of two bytes (16 bits), uses two
channels (stereo) and has a frame rate of 44,100 frames/second. This gives a
frame size of 4 bytes (2\*2), and a second's worth occupies 2\*2\*44100 bytes
(176,400 bytes).
Module :mod:`aifc` defines the following function:
.. function:: open(file[, mode])
Open an AIFF or AIFF-C file and return an object instance with methods that are
described below. The argument *file* is either a string naming a file or a file
object. *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for
reading, or ``'w'`` or ``'wb'`` when the file must be opened for writing. If
omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used. When
used for writing, the file object should be seekable, unless you know ahead of
time how many samples you are going to write in total and use
:meth:`writeframesraw` and :meth:`setnframes`.
Objects returned by :func:`open` when a file is opened for reading have the
following methods:
.. method:: aifc.getnchannels()
Return the number of audio channels (1 for mono, 2 for stereo).
.. method:: aifc.getsampwidth()
Return the size in bytes of individual samples.
.. method:: aifc.getframerate()
Return the sampling rate (number of audio frames per second).
.. method:: aifc.getnframes()
Return the number of audio frames in the file.
.. method:: aifc.getcomptype()
Return a four-character string describing the type of compression used in the
audio file. For AIFF files, the returned value is ``'NONE'``.
.. method:: aifc.getcompname()
Return a human-readable description of the type of compression used in the audio
file. For AIFF files, the returned value is ``'not compressed'``.
.. method:: aifc.getparams()
Return a tuple consisting of all of the above values in the above order.
.. method:: aifc.getmarkers()
Return a list of markers in the audio file. A marker consists of a tuple of
three elements. The first is the mark ID (an integer), the second is the mark
position in frames from the beginning of the data (an integer), the third is the
name of the mark (a string).
.. method:: aifc.getmark(id)
Return the tuple as described in :meth:`getmarkers` for the mark with the given
*id*.
.. method:: aifc.readframes(nframes)
Read and return the next *nframes* frames from the audio file. The returned
data is a string containing for each frame the uncompressed samples of all
channels.
.. method:: aifc.rewind()
Rewind the read pointer. The next :meth:`readframes` will start from the
beginning.
.. method:: aifc.setpos(pos)
Seek to the specified frame number.
.. method:: aifc.tell()
Return the current frame number.
.. method:: aifc.close()
Close the AIFF file. After calling this method, the object can no longer be
used.
Objects returned by :func:`open` when a file is opened for writing have all the
above methods, except for :meth:`readframes` and :meth:`setpos`. In addition
the following methods exist. The :meth:`get\*` methods can only be called after
the corresponding :meth:`set\*` methods have been called. Before the first
:meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the
number of frames must be filled in.
.. method:: aifc.aiff()
Create an AIFF file. The default is that an AIFF-C file is created, unless the
name of the file ends in ``'.aiff'`` in which case the default is an AIFF file.
.. method:: aifc.aifc()
Create an AIFF-C file. The default is that an AIFF-C file is created, unless
the name of the file ends in ``'.aiff'`` in which case the default is an AIFF
file.
.. method:: aifc.setnchannels(nchannels)
Specify the number of channels in the audio file.
.. method:: aifc.setsampwidth(width)
Specify the size in bytes of audio samples.
.. method:: aifc.setframerate(rate)
Specify the sampling frequency in frames per second.
.. method:: aifc.setnframes(nframes)
Specify the number of frames that are to be written to the audio file. If this
parameter is not set, or not set correctly, the file needs to support seeking.
.. method:: aifc.setcomptype(type, name)
.. index::
single: u-LAW
single: A-LAW
single: G.722
Specify the compression type. If not specified, the audio data will not be
compressed. In AIFF files, compression is not possible. The name parameter
should be a human-readable description of the compression type, the type
parameter should be a four-character string. Currently the following
compression types are supported: NONE, ULAW, ALAW, G722.
.. method:: aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)
Set all the above parameters at once. The argument is a tuple consisting of the
various parameters. This means that it is possible to use the result of a
:meth:`getparams` call as argument to :meth:`setparams`.
.. method:: aifc.setmark(id, pos, name)
Add a mark with the given id (larger than 0), and the given name at the given
position. This method can be called at any time before :meth:`close`.
.. method:: aifc.tell()
Return the current write position in the output file. Useful in combination
with :meth:`setmark`.
.. method:: aifc.writeframes(data)
Write data to the output file. This method can only be called after the audio
file parameters have been set.
.. method:: aifc.writeframesraw(data)
Like :meth:`writeframes`, except that the header of the audio file is not
updated.
.. method:: aifc.close()
Close the AIFF file. The header of the file is updated to reflect the actual
size of the audio data. After calling this method, the object can no longer be
used.

27
Doc-3k/library/allos.rst Normal file
View File

@@ -0,0 +1,27 @@
.. _allos:
*********************************
Generic Operating System Services
*********************************
The modules described in this chapter provide interfaces to operating system
features that are available on (almost) all operating systems, such as files and
a clock. The interfaces are generally modeled after the Unix or C interfaces,
but they are available on most other systems as well. Here's an overview:
.. toctree::
os.rst
time.rst
optparse.rst
getopt.rst
logging.rst
getpass.rst
curses.rst
curses.ascii.rst
curses.panel.rst
platform.rst
errno.rst
ctypes.rst

96
Doc-3k/library/anydbm.rst Normal file
View File

@@ -0,0 +1,96 @@
:mod:`anydbm` --- Generic access to DBM-style databases
=======================================================
.. module:: anydbm
:synopsis: Generic interface to DBM-style database modules.
.. index::
module: dbhash
module: bsddb
module: gdbm
module: dbm
module: dumbdbm
:mod:`anydbm` is a generic interface to variants of the DBM database ---
:mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`. If none of
these modules is installed, the slow-but-simple implementation in module
:mod:`dumbdbm` will be used.
.. function:: open(filename[, flag[, mode]])
Open the database file *filename* and return a corresponding object.
If the database file already exists, the :mod:`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).
.. exception:: error
A tuple containing the exceptions that can be raised by each of the supported
modules, with a unique exception :exc:`anydbm.error` as the first item --- the
latter is used when :exc:`anydbm.error` is raised.
The object returned by :func:`open` supports most of the same functionality as
dictionaries; keys and their corresponding values can be stored, retrieved, and
deleted, and the :meth:`has_key` and :meth:`keys` methods are available. Keys
and values must always be strings.
The following example records some hostnames and a corresponding title, and
then prints out the contents of the database::
import anydbm
# Open database, creating it if necessary.
db = anydbm.open('cache', 'c')
# Record some values
db['www.python.org'] = 'Python Website'
db['www.cnn.com'] = 'Cable News Network'
# Loop through contents. Other dictionary methods
# such as .keys(), .values() also work.
for k, v in db.iteritems():
print k, '\t', v
# Storing a non-string key or value will raise an exception (most
# likely a TypeError).
db['www.yahoo.com'] = 4
# Close when done.
db.close()
.. seealso::
Module :mod:`dbhash`
BSD ``db`` database interface.
Module :mod:`dbm`
Standard Unix database interface.
Module :mod:`dumbdbm`
Portable implementation of the ``dbm`` interface.
Module :mod:`gdbm`
GNU database interface, based on the ``dbm`` interface.
Module :mod:`shelve`
General object persistence built on top of the Python ``dbm`` interface.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.

18
Doc-3k/library/archiving.rst Normal file
View File

@@ -0,0 +1,18 @@
.. _archiving:
******************************
Data Compression and Archiving
******************************
The modules described in this chapter support data compression with the zlib,
gzip, and bzip2 algorithms, and the creation of ZIP- and tar-format archives.
.. toctree::
zlib.rst
gzip.rst
bz2.rst
zipfile.rst
tarfile.rst

273
Doc-3k/library/array.rst Normal file
View File

@@ -0,0 +1,273 @@
:mod:`array` --- Efficient arrays of numeric values
===================================================
.. module:: array
:synopsis: Efficient arrays of uniformly typed numeric values.
.. index:: single: arrays
This module defines an object type which can efficiently represent an array of
basic values: characters, integers, floating point numbers. Arrays are sequence
types and behave very much like lists, except that the type of objects stored in
them is constrained. The type is specified at object creation time by using a
:dfn:`type code`, which is a single character. The following type codes are
defined:
+-----------+----------------+-------------------+-----------------------+
| Type code | C Type | Python Type | Minimum size in bytes |
+===========+================+===================+=======================+
| ``'c'`` | char | character | 1 |
+-----------+----------------+-------------------+-----------------------+
| ``'b'`` | signed char | int | 1 |
+-----------+----------------+-------------------+-----------------------+
| ``'B'`` | unsigned char | int | 1 |
+-----------+----------------+-------------------+-----------------------+
| ``'u'`` | Py_UNICODE | Unicode character | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'h'`` | signed short | int | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'H'`` | unsigned short | int | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'i'`` | signed int | int | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'I'`` | unsigned int | long | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'l'`` | signed long | int | 4 |
+-----------+----------------+-------------------+-----------------------+
| ``'L'`` | unsigned long | long | 4 |
+-----------+----------------+-------------------+-----------------------+
| ``'f'`` | float | float | 4 |
+-----------+----------------+-------------------+-----------------------+
| ``'d'`` | double | float | 8 |
+-----------+----------------+-------------------+-----------------------+
The actual representation of values is determined by the machine architecture
(strictly speaking, by the C implementation). The actual size can be accessed
through the :attr:`itemsize` attribute. The values stored for ``'L'`` and
``'I'`` items will be represented as Python long integers when retrieved,
because Python's plain integer type cannot represent the full range of C's
unsigned (long) integers.
The module defines the following type:
.. function:: array(typecode[, initializer])
Return a new array whose items are restricted by *typecode*, and initialized
from the optional *initializer* value, which must be a list, string, or iterable
over elements of the appropriate type.
.. versionchanged:: 2.4
Formerly, only lists or strings were accepted.
If given a list or string, the initializer is passed to the new array's
:meth:`fromlist`, :meth:`fromstring`, or :meth:`fromunicode` method (see below)
to add initial items to the array. Otherwise, the iterable initializer is
passed to the :meth:`extend` method.
.. data:: ArrayType
Obsolete alias for :func:`array`.
Array objects support the ordinary sequence operations of indexing, slicing,
concatenation, and multiplication. When using slice assignment, the assigned
value must be an array object with the same type code; in all other cases,
:exc:`TypeError` is raised. Array objects also implement the buffer interface,
and may be used wherever buffer objects are supported.
The following data items and methods are also supported:
.. attribute:: array.typecode
The typecode character used to create the array.
.. attribute:: array.itemsize
The length in bytes of one array item in the internal representation.
.. method:: array.append(x)
Append a new item with value *x* to the end of the array.
.. method:: array.buffer_info()
Return a tuple ``(address, length)`` giving the current memory address and the
length in elements of the buffer used to hold array's contents. The size of the
memory buffer in bytes can be computed as ``array.buffer_info()[1] *
array.itemsize``. This is occasionally useful when working with low-level (and
inherently unsafe) I/O interfaces that require memory addresses, such as certain
:cfunc:`ioctl` operations. The returned numbers are valid as long as the array
exists and no length-changing operations are applied to it.
.. note::
When using array objects from code written in C or C++ (the only way to
effectively make use of this information), it makes more sense to use the buffer
interface supported by array objects. This method is maintained for backward
compatibility and should be avoided in new code. The buffer interface is
documented in the Python/C API Reference Manual (XXX reference:
../api/newTypes.html).
.. method:: array.byteswap()
"Byteswap" all items of the array. This is only supported for values which are
1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
raised. It is useful when reading data from a file written on a machine with a
different byte order.
.. method:: array.count(x)
Return the number of occurrences of *x* in the array.
.. method:: array.extend(iterable)
Append items from *iterable* to the end of the array. If *iterable* is another
array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
be raised. If *iterable* is not an array, it must be iterable and its elements
must be the right type to be appended to the array.
.. versionchanged:: 2.4
Formerly, the argument could only be another array.
.. method:: array.fromfile(f, n)
Read *n* items (as machine values) from the file object *f* and append them to
the end of the array. If less than *n* items are available, :exc:`EOFError` is
raised, but the items that were available are still inserted into the array.
*f* must be a real built-in file object; something else with a :meth:`read`
method won't do.
.. method:: array.fromlist(list)
Append items from the list. This is equivalent to ``for x in list:
a.append(x)`` except that if there is a type error, the array is unchanged.
.. method:: array.fromstring(s)
Appends items from the string, interpreting the string as an array of machine
values (as if it had been read from a file using the :meth:`fromfile` method).
.. method:: array.fromunicode(s)
Extends this array with data from the given unicode string. The array must be a
type ``'u'`` array; otherwise a :exc:`ValueError` is raised. Use
``array.fromstring(ustr.decode(enc))`` to append Unicode data to an array of
some other type.
.. method:: array.index(x)
Return the smallest *i* such that *i* is the index of the first occurrence of
*x* in the array.
.. method:: array.insert(i, x)
Insert a new item with value *x* in the array before position *i*. Negative
values are treated as being relative to the end of the array.
.. method:: array.pop([i])
Removes the item with the index *i* from the array and returns it. The optional
argument defaults to ``-1``, so that by default the last item is removed and
returned.
.. method:: array.read(f, n)
.. deprecated:: 1.5.1
Use the :meth:`fromfile` method.
Read *n* items (as machine values) from the file object *f* and append them to
the end of the array. If less than *n* items are available, :exc:`EOFError` is
raised, but the items that were available are still inserted into the array.
*f* must be a real built-in file object; something else with a :meth:`read`
method won't do.
.. method:: array.remove(x)
Remove the first occurrence of *x* from the array.
.. method:: array.reverse()
Reverse the order of the items in the array.
.. method:: array.tofile(f)
Write all items (as machine values) to the file object *f*.
.. method:: array.tolist()
Convert the array to an ordinary list with the same items.
.. method:: array.tostring()
Convert the array to an array of machine values and return the string
representation (the same sequence of bytes that would be written to a file by
the :meth:`tofile` method.)
.. method:: array.tounicode()
Convert the array to a unicode string. The array must be a type ``'u'`` array;
otherwise a :exc:`ValueError` is raised. Use ``array.tostring().decode(enc)`` to
obtain a unicode string from an array of some other type.
.. method:: array.write(f)
.. deprecated:: 1.5.1
Use the :meth:`tofile` method.
Write all items (as machine values) to the file object *f*.
When an array object is printed or converted to a string, it is represented as
``array(typecode, initializer)``. The *initializer* is omitted if the array is
empty, otherwise it is a string if the *typecode* is ``'c'``, otherwise it is a
list of numbers. The string is guaranteed to be able to be converted back to an
array with the same type and value using reverse quotes (``````), so long as the
:func:`array` function has been imported using ``from array import array``.
Examples::
array('l')
array('c', 'hello world')
array('u', u'hello \textbackslash u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])
.. seealso::
Module :mod:`struct`
Packing and unpacking of heterogeneous binary data.
Module :mod:`xdrlib`
Packing and unpacking of External Data Representation (XDR) data as used in some
remote procedure call systems.
`The Numerical Python Manual <http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm>`_
The Numeric Python extension (NumPy) defines another array type; see
http://numpy.sourceforge.net/ for further information about Numerical Python.
(A PDF version of the NumPy manual is available at
http://numpy.sourceforge.net/numdoc/numdoc.pdf).

62
Doc-3k/library/ast.rst Normal file
View File

@@ -0,0 +1,62 @@
.. % XXX Label can't be _ast?
.. % XXX Where should this section/chapter go?
.. _ast:
*********************
Abstract Syntax Trees
*********************
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. versionadded:: 2.5
The ``_ast`` module helps Python applications to process trees of the Python
abstract syntax grammar. The Python compiler currently provides read-only access
to such trees, meaning that applications can only create a tree for a given
piece of Python source code; generating byte code from a (potentially modified)
tree is not supported. The abstract syntax itself might change with each Python
release; this module helps to find out programmatically what the current grammar
looks like.
An abstract syntax tree can be generated by passing ``_ast.PyCF_ONLY_AST`` as a
flag to the :func:`compile` builtin function. The result will be a tree of
objects whose classes all inherit from ``_ast.AST``.
The actual classes are derived from the ``Parser/Python.asdl`` file, which is
reproduced below. There is one class defined for each left-hand side symbol in
the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition,
there is one class defined for each constructor on the right-hand side; these
classes inherit from the classes for the left-hand side trees. For example,
``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with
alternatives (aka "sums"), the left-hand side class is abstract: only instances
of specific constructor nodes are ever created.
Each concrete class has an attribute ``_fields`` which gives the names of all
child nodes.
Each instance of a concrete class has one attribute for each child node, of the
type as defined in the grammar. For example, ``_ast.BinOp`` instances have an
attribute ``left`` of type ``_ast.expr``. Instances of ``_ast.expr`` and
``_ast.stmt`` subclasses also have lineno and col_offset attributes. The lineno
is the line number of source text (1 indexed so the first line is line 1) and
the col_offset is the utf8 byte offset of the first token that generated the
node. The utf8 offset is recorded because the parser uses utf8 internally.
If these attributes are marked as optional in the grammar (using a question
mark), the value might be ``None``. If the attributes can have zero-or-more
values (marked with an asterisk), the values are represented as Python lists.
Abstract Grammar
================
The module defines a string constant ``__version__`` which is the decimal
subversion revision number of the file shown below.
The abstract grammar is currently defined as follows:
.. XXX includefile ../../Parser/Python.asdl

288
Doc-3k/library/asttable.rst Normal file
View File

@@ -0,0 +1,288 @@
+-----------------------+--------------------+---------------------------------+
| Node type | Attribute | Value |
+=======================+====================+=================================+
| :class:`Add` | :attr:`left` | left operand |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | right operand |
+-----------------------+--------------------+---------------------------------+
| :class:`And` | :attr:`nodes` | list of operands |
+-----------------------+--------------------+---------------------------------+
| :class:`AssAttr` | | *attribute as target of |
| | | assignment* |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr` | expression on the left-hand |
| | | side of the dot |
+-----------------------+--------------------+---------------------------------+
| | :attr:`attrname` | the attribute name, a string |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | XXX |
+-----------------------+--------------------+---------------------------------+
| :class:`AssList` | :attr:`nodes` | list of list elements being |
| | | assigned to |
+-----------------------+--------------------+---------------------------------+
| :class:`AssName` | :attr:`name` | name being assigned to |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | XXX |
+-----------------------+--------------------+---------------------------------+
| :class:`AssTuple` | :attr:`nodes` | list of tuple elements being |
| | | assigned to |
+-----------------------+--------------------+---------------------------------+
| :class:`Assert` | :attr:`test` | the expression to be tested |
+-----------------------+--------------------+---------------------------------+
| | :attr:`fail` | the value of the |
| | | :exc:`AssertionError` |
+-----------------------+--------------------+---------------------------------+
| :class:`Assign` | :attr:`nodes` | a list of assignment targets, |
| | | one per equal sign |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr` | the value being assigned |
+-----------------------+--------------------+---------------------------------+
| :class:`AugAssign` | :attr:`node` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`op` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Bitand` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Bitor` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Bitxor` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Break` | | |
+-----------------------+--------------------+---------------------------------+
| :class:`CallFunc` | :attr:`node` | expression for the callee |
+-----------------------+--------------------+---------------------------------+
| | :attr:`args` | a list of arguments |
+-----------------------+--------------------+---------------------------------+
| | :attr:`star_args` | the extended \*-arg value |
+-----------------------+--------------------+---------------------------------+
| | :attr:`dstar_args` | the extended \*\*-arg value |
+-----------------------+--------------------+---------------------------------+
| :class:`Class` | :attr:`name` | the name of the class, a string |
+-----------------------+--------------------+---------------------------------+
| | :attr:`bases` | a list of base classes |
+-----------------------+--------------------+---------------------------------+
| | :attr:`doc` | doc string, a string or |
| | | ``None`` |
+-----------------------+--------------------+---------------------------------+
| | :attr:`code` | the body of the class statement |
+-----------------------+--------------------+---------------------------------+
| :class:`Compare` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`ops` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Const` | :attr:`value` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Continue` | | |
+-----------------------+--------------------+---------------------------------+
| :class:`Decorators` | :attr:`nodes` | List of function decorator |
| | | expressions |
+-----------------------+--------------------+---------------------------------+
| :class:`Dict` | :attr:`items` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Discard` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Div` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Ellipsis` | | |
+-----------------------+--------------------+---------------------------------+
| :class:`Expression` | :attr:`node` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Exec` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`locals` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`globals` | |
+-----------------------+--------------------+---------------------------------+
| :class:`FloorDiv` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`For` | :attr:`assign` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`list` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`else_` | |
+-----------------------+--------------------+---------------------------------+
| :class:`From` | :attr:`modname` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`names` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Function` | :attr:`decorators` | :class:`Decorators` or ``None`` |
+-----------------------+--------------------+---------------------------------+
| | :attr:`name` | name used in def, a string |
+-----------------------+--------------------+---------------------------------+
| | :attr:`argnames` | list of argument names, as |
| | | strings |
+-----------------------+--------------------+---------------------------------+
| | :attr:`defaults` | list of default values |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | xxx |
+-----------------------+--------------------+---------------------------------+
| | :attr:`doc` | doc string, a string or |
| | | ``None`` |
+-----------------------+--------------------+---------------------------------+
| | :attr:`code` | the body of the function |
+-----------------------+--------------------+---------------------------------+
| :class:`GenExpr` | :attr:`code` | |
+-----------------------+--------------------+---------------------------------+
| :class:`GenExprFor` | :attr:`assign` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`iter` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`ifs` | |
+-----------------------+--------------------+---------------------------------+
| :class:`GenExprIf` | :attr:`test` | |
+-----------------------+--------------------+---------------------------------+
| :class:`GenExprInner` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`quals` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Getattr` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`attrname` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Global` | :attr:`names` | |
+-----------------------+--------------------+---------------------------------+
| :class:`If` | :attr:`tests` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`else_` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Import` | :attr:`names` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Invert` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Keyword` | :attr:`name` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Lambda` | :attr:`argnames` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`defaults` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`code` | |
+-----------------------+--------------------+---------------------------------+
| :class:`LeftShift` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`List` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`ListComp` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`quals` | |
+-----------------------+--------------------+---------------------------------+
| :class:`ListCompFor` | :attr:`assign` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`list` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`ifs` | |
+-----------------------+--------------------+---------------------------------+
| :class:`ListCompIf` | :attr:`test` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Mod` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Module` | :attr:`doc` | doc string, a string or |
| | | ``None`` |
+-----------------------+--------------------+---------------------------------+
| | :attr:`node` | body of the module, a |
| | | :class:`Stmt` |
+-----------------------+--------------------+---------------------------------+
| :class:`Mul` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Name` | :attr:`name` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Not` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Or` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Pass` | | |
+-----------------------+--------------------+---------------------------------+
| :class:`Power` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Print` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`dest` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Printnl` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`dest` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Raise` | :attr:`expr1` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr2` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr3` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Return` | :attr:`value` | |
+-----------------------+--------------------+---------------------------------+
| :class:`RightShift` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Slice` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`lower` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`upper` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Sliceobj` | :attr:`nodes` | list of statements |
+-----------------------+--------------------+---------------------------------+
| :class:`Stmt` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Sub` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Subscript` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`subs` | |
+-----------------------+--------------------+---------------------------------+
| :class:`TryExcept` | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`handlers` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`else_` | |
+-----------------------+--------------------+---------------------------------+
| :class:`TryFinally` | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`final` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Tuple` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`UnaryAdd` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`UnarySub` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`While` | :attr:`test` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`else_` | |
+-----------------------+--------------------+---------------------------------+
| :class:`With` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`vars` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Yield` | :attr:`value` | |
+-----------------------+--------------------+---------------------------------+

284
Doc-3k/library/asynchat.rst Normal file
View File

@@ -0,0 +1,284 @@
:mod:`asynchat` --- Asynchronous socket command/response handler
================================================================
.. module:: asynchat
:synopsis: Support for asynchronous command/response protocols.
.. moduleauthor:: Sam Rushing <rushing@nightmare.com>
.. sectionauthor:: Steve Holden <sholden@holdenweb.com>
This module builds on the :mod:`asyncore` infrastructure, simplifying
asynchronous clients and servers and making it easier to handle protocols whose
elements are terminated by arbitrary strings, or are of variable length.
:mod:`asynchat` defines the abstract class :class:`async_chat` that you
subclass, providing implementations of the :meth:`collect_incoming_data` and
:meth:`found_terminator` methods. It uses the same asynchronous loop as
:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher` and
:class:`asynchat.async_chat`, can freely be mixed in the channel map. Typically
an :class:`asyncore.dispatcher` server channel generates new
:class:`asynchat.async_chat` channel objects as it receives incoming connection
requests.
.. class:: async_chat()
This class is an abstract subclass of :class:`asyncore.dispatcher`. To make
practical use of the code you must subclass :class:`async_chat`, providing
meaningful :meth:`collect_incoming_data` and :meth:`found_terminator` methods.
The :class:`asyncore.dispatcher` methods can be used, although not all make
sense in a message/response context.
Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of events
that are generated by an analysis of socket conditions after a :cfunc:`select`
call. Once the polling loop has been started the :class:`async_chat` object's
methods are called by the event-processing framework with no action on the part
of the programmer.
Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to define a
first-in-first-out queue (fifo) of *producers*. A producer need have only one
method, :meth:`more`, which should return data to be transmitted on the channel.
The producer indicates exhaustion (*i.e.* that it contains no more data) by
having its :meth:`more` method return the empty string. At this point the
:class:`async_chat` object removes the producer from the fifo and starts using
the next producer, if any. When the producer fifo is empty the
:meth:`handle_write` method does nothing. You use the channel object's
:meth:`set_terminator` method to describe how to recognize the end of, or an
important breakpoint in, an incoming transmission from the remote endpoint.
To build a functioning :class:`async_chat` subclass your input methods
:meth:`collect_incoming_data` and :meth:`found_terminator` must handle the data
that the channel receives asynchronously. The methods are described below.
.. method:: async_chat.close_when_done()
Pushes a ``None`` on to the producer fifo. When this producer is popped off the
fifo it causes the channel to be closed.
.. method:: async_chat.collect_incoming_data(data)
Called with *data* holding an arbitrary amount of received data. The default
method, which must be overridden, raises a :exc:`NotImplementedError` exception.
.. method:: async_chat.discard_buffers()
In emergencies this method will discard any data held in the input and/or output
buffers and the producer fifo.
.. method:: async_chat.found_terminator()
Called when the incoming data stream matches the termination condition set by
:meth:`set_terminator`. The default method, which must be overridden, raises a
:exc:`NotImplementedError` exception. The buffered input data should be
available via an instance attribute.
.. method:: async_chat.get_terminator()
Returns the current terminator for the channel.
.. method:: async_chat.handle_close()
Called when the channel is closed. The default method silently closes the
channel's socket.
.. method:: async_chat.handle_read()
Called when a read event fires on the channel's socket in the asynchronous loop.
The default method checks for the termination condition established by
:meth:`set_terminator`, which can be either the appearance of a particular
string in the input stream or the receipt of a particular number of characters.
When the terminator is found, :meth:`handle_read` calls the
:meth:`found_terminator` method after calling :meth:`collect_incoming_data` with
any data preceding the terminating condition.
.. method:: async_chat.handle_write()
Called when the application may write data to the channel. The default method
calls the :meth:`initiate_send` method, which in turn will call
:meth:`refill_buffer` to collect data from the producer fifo associated with the
channel.
.. method:: async_chat.push(data)
Creates a :class:`simple_producer` object (*see below*) containing the data and
pushes it on to the channel's ``producer_fifo`` to ensure its transmission. This
is all you need to do to have the channel write the data out to the network,
although it is possible to use your own producers in more complex schemes to
implement encryption and chunking, for example.
.. method:: async_chat.push_with_producer(producer)
Takes a producer object and adds it to the producer fifo associated with the
channel. When all currently-pushed producers have been exhausted the channel
will consume this producer's data by calling its :meth:`more` method and send
the data to the remote endpoint.
.. method:: async_chat.readable()
Should return ``True`` for the channel to be included in the set of channels
tested by the :cfunc:`select` loop for readability.
.. method:: async_chat.refill_buffer()
Refills the output buffer by calling the :meth:`more` method of the producer at
the head of the fifo. If it is exhausted then the producer is popped off the
fifo and the next producer is activated. If the current producer is, or becomes,
``None`` then the channel is closed.
.. method:: async_chat.set_terminator(term)
Sets the terminating condition to be recognised on the channel. ``term`` may be
any of three types of value, corresponding to three different ways to handle
incoming protocol data.
+-----------+---------------------------------------------+
| term | Description |
+===========+=============================================+
| *string* | Will call :meth:`found_terminator` when the |
| | string is found in the input stream |
+-----------+---------------------------------------------+
| *integer* | Will call :meth:`found_terminator` when the |
| | indicated number of characters have been |
| | received |
+-----------+---------------------------------------------+
| ``None`` | The channel continues to collect data |
| | forever |
+-----------+---------------------------------------------+
Note that any data following the terminator will be available for reading by the
channel after :meth:`found_terminator` is called.
.. method:: async_chat.writable()
Should return ``True`` as long as items remain on the producer fifo, or the
channel is connected and the channel's output buffer is non-empty.
asynchat - Auxiliary Classes and Functions
------------------------------------------
.. class:: simple_producer(data[, buffer_size=512])
A :class:`simple_producer` takes a chunk of data and an optional buffer size.
Repeated calls to its :meth:`more` method yield successive chunks of the data no
larger than *buffer_size*.
.. method:: simple_producer.more()
Produces the next chunk of information from the producer, or returns the empty
string.
.. class:: fifo([list=None])
Each channel maintains a :class:`fifo` holding data which has been pushed by the
application but not yet popped for writing to the channel. A :class:`fifo` is a
list used to hold data and/or producers until they are required. If the *list*
argument is provided then it should contain producers or data items to be
written to the channel.
.. method:: fifo.is_empty()
Returns ``True`` iff the fifo is empty.
.. method:: fifo.first()
Returns the least-recently :meth:`push`\ ed item from the fifo.
.. method:: fifo.push(data)
Adds the given data (which may be a string or a producer object) to the producer
fifo.
.. method:: fifo.pop()
If the fifo is not empty, returns ``True, first()``, deleting the popped item.
Returns ``False, None`` for an empty fifo.
The :mod:`asynchat` module also defines one utility function, which may be of
use in network and textual analysis operations.
.. function:: find_prefix_at_end(haystack, needle)
Returns ``True`` if string *haystack* ends with any non-empty prefix of string
*needle*.
.. _asynchat-example:
asynchat Example
----------------
The following partial example shows how HTTP requests can be read with
:class:`async_chat`. A web server might create an :class:`http_request_handler`
object for each incoming client connection. Notice that initially the channel
terminator is set to match the blank line at the end of the HTTP headers, and a
flag indicates that the headers are being read.
Once the headers have been read, if the request is of type POST (indicating that
further data are present in the input stream) then the ``Content-Length:``
header is used to set a numeric terminator to read the right amount of data from
the channel.
The :meth:`handle_request` method is called once all relevant input has been
marshalled, after setting the channel terminator to ``None`` to ensure that any
extraneous data sent by the web client are ignored. ::
class http_request_handler(asynchat.async_chat):
def __init__(self, conn, addr, sessions, log):
asynchat.async_chat.__init__(self, conn=conn)
self.addr = addr
self.sessions = sessions
self.ibuffer = []
self.obuffer = ""
self.set_terminator("\r\n\r\n")
self.reading_headers = True
self.handling = False
self.cgi_data = None
self.log = log
def collect_incoming_data(self, data):
"""Buffer the data"""
self.ibuffer.append(data)
def found_terminator(self):
if self.reading_headers:
self.reading_headers = False
self.parse_headers("".join(self.ibuffer))
self.ibuffer = []
if self.op.upper() == "POST":
clen = self.headers.getheader("content-length")
self.set_terminator(int(clen))
else:
self.handling = True
self.set_terminator(None)
self.handle_request()
elif not self.handling:
self.set_terminator(None) # browsers sometimes over-send
self.cgi_data = parse(self.headers, "".join(self.ibuffer))
self.handling = True
self.ibuffer = []
self.handle_request()

269
Doc-3k/library/asyncore.rst Normal file
View File

@@ -0,0 +1,269 @@
:mod:`asyncore` --- Asynchronous socket handler
===============================================
.. module:: asyncore
:synopsis: A base class for developing asynchronous socket handling services.
.. moduleauthor:: Sam Rushing <rushing@nightmare.com>
.. sectionauthor:: Christopher Petrilli <petrilli@amber.org>
.. sectionauthor:: Steve Holden <sholden@holdenweb.com>
This module provides the basic infrastructure for writing asynchronous socket
service clients and servers.
.. % Heavily adapted from original documentation by Sam Rushing.
There are only two ways to have a program on a single processor do "more than
one thing at a time." Multi-threaded programming is the simplest and most
popular way to do it, but there is another very different technique, that lets
you have nearly all the advantages of multi-threading, without actually using
multiple threads. It's really only practical if your program is largely I/O
bound. If your program is processor bound, then pre-emptive scheduled threads
are probably what you really need. Network servers are rarely processor bound,
however.
If your operating system supports the :cfunc:`select` system call in its I/O
library (and nearly all do), then you can use it to juggle multiple
communication channels at once; doing other work while your I/O is taking place
in the "background." Although this strategy can seem strange and complex,
especially at first, it is in many ways easier to understand and control than
multi-threaded programming. The :mod:`asyncore` module solves many of the
difficult problems for you, making the task of building sophisticated high-
performance network servers and clients a snap. For "conversational"
applications and protocols the companion :mod:`asynchat` module is invaluable.
The basic idea behind both modules is to create one or more network *channels*,
instances of class :class:`asyncore.dispatcher` and
:class:`asynchat.async_chat`. Creating the channels adds them to a global map,
used by the :func:`loop` function if you do not provide it with your own *map*.
Once the initial channel(s) is(are) created, calling the :func:`loop` function
activates channel service, which continues until the last channel (including any
that have been added to the map during asynchronous service) is closed.
.. function:: loop([timeout[, use_poll[, map[,count]]]])
Enter a polling loop that terminates after count passes or all open channels
have been closed. All arguments are optional. The *count* parameter defaults
to None, resulting in the loop terminating only when all channels have been
closed. The *timeout* argument sets the timeout parameter for the appropriate
:func:`select` or :func:`poll` call, measured in seconds; the default is 30
seconds. The *use_poll* parameter, if true, indicates that :func:`poll` should
be used in preference to :func:`select` (the default is ``False``).
The *map* parameter is a dictionary whose items are the channels to watch. As
channels are closed they are deleted from their map. If *map* is omitted, a
global map is used. Channels (instances of :class:`asyncore.dispatcher`,
:class:`asynchat.async_chat` and subclasses thereof) can freely be mixed in the
map.
.. class:: dispatcher()
The :class:`dispatcher` class is a thin wrapper around a low-level socket
object. To make it more useful, it has a few methods for event-handling which
are called from the asynchronous loop. Otherwise, it can be treated as a
normal non-blocking socket object.
Two class attributes can be modified, to improve performance, or possibly even
to conserve memory.
.. data:: ac_in_buffer_size
The asynchronous input buffer size (default ``4096``).
.. data:: ac_out_buffer_size
The asynchronous output buffer size (default ``4096``).
The firing of low-level events at certain times or in certain connection states
tells the asynchronous loop that certain higher-level events have taken place.
For example, if we have asked for a socket to connect to another host, we know
that the connection has been made when the socket becomes writable for the first
time (at this point you know that you may write to it with the expectation of
success). The implied higher-level events are:
+----------------------+----------------------------------------+
| Event | Description |
+======================+========================================+
| ``handle_connect()`` | Implied by the first write event |
+----------------------+----------------------------------------+
| ``handle_close()`` | Implied by a read event with no data |
| | available |
+----------------------+----------------------------------------+
| ``handle_accept()`` | Implied by a read event on a listening |
| | socket |
+----------------------+----------------------------------------+
During asynchronous processing, each mapped channel's :meth:`readable` and
:meth:`writable` methods are used to determine whether the channel's socket
should be added to the list of channels :cfunc:`select`\ ed or :cfunc:`poll`\ ed
for read and write events.
Thus, the set of channel events is larger than the basic socket events. The full
set of methods that can be overridden in your subclass follows:
.. method:: dispatcher.handle_read()
Called when the asynchronous loop detects that a :meth:`read` call on the
channel's socket will succeed.
.. method:: dispatcher.handle_write()
Called when the asynchronous loop detects that a writable socket can be written.
Often this method will implement the necessary buffering for performance. For
example::
def handle_write(self):
sent = self.send(self.buffer)
self.buffer = self.buffer[sent:]
.. method:: dispatcher.handle_expt()
Called when there is out of band (OOB) data for a socket connection. This will
almost never happen, as OOB is tenuously supported and rarely used.
.. method:: dispatcher.handle_connect()
Called when the active opener's socket actually makes a connection. Might send a
"welcome" banner, or initiate a protocol negotiation with the remote endpoint,
for example.
.. method:: dispatcher.handle_close()
Called when the socket is closed.
.. method:: dispatcher.handle_error()
Called when an exception is raised and not otherwise handled. The default
version prints a condensed traceback.
.. method:: dispatcher.handle_accept()
Called on listening channels (passive openers) when a connection can be
established with a new remote endpoint that has issued a :meth:`connect` call
for the local endpoint.
.. method:: dispatcher.readable()
Called each time around the asynchronous loop to determine whether a channel's
socket should be added to the list on which read events can occur. The default
method simply returns ``True``, indicating that by default, all channels will
be interested in read events.
.. method:: dispatcher.writable()
Called each time around the asynchronous loop to determine whether a channel's
socket should be added to the list on which write events can occur. The default
method simply returns ``True``, indicating that by default, all channels will
be interested in write events.
In addition, each channel delegates or extends many of the socket methods. Most
of these are nearly identical to their socket partners.
.. method:: dispatcher.create_socket(family, type)
This is identical to the creation of a normal socket, and will use the same
options for creation. Refer to the :mod:`socket` documentation for information
on creating sockets.
.. method:: dispatcher.connect(address)
As with the normal socket object, *address* is a tuple with the first element
the host to connect to, and the second the port number.
.. method:: dispatcher.send(data)
Send *data* to the remote end-point of the socket.
.. method:: dispatcher.recv(buffer_size)
Read at most *buffer_size* bytes from the socket's remote end-point. An empty
string implies that the channel has been closed from the other end.
.. method:: dispatcher.listen(backlog)
Listen for connections made to the socket. The *backlog* argument specifies the
maximum number of queued connections and should be at least 1; the maximum value
is system-dependent (usually 5).
.. method:: dispatcher.bind(address)
Bind the socket to *address*. The socket must not already be bound. (The
format of *address* depends on the address family --- see above.) To mark the
socket as re-usable (setting the :const:`SO_REUSEADDR` option), call the
:class:`dispatcher` object's :meth:`set_reuse_addr` method.
.. method:: dispatcher.accept()
Accept a connection. The socket must be bound to an address and listening for
connections. The return value is a pair ``(conn, address)`` where *conn* is a
*new* socket object usable to send and receive data on the connection, and
*address* is the address bound to the socket on the other end of the connection.
.. method:: dispatcher.close()
Close the socket. All future operations on the socket object will fail. The
remote end-point will receive no more data (after queued data is flushed).
Sockets are automatically closed when they are garbage-collected.
.. _asyncore-example:
asyncore Example basic HTTP client
----------------------------------
Here is a very basic HTTP client that uses the :class:`dispatcher` class to
implement its socket handling::
import asyncore, socket
class http_client(asyncore.dispatcher):
def __init__(self, host, path):
asyncore.dispatcher.__init__(self)
self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
self.connect( (host, 80) )
self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % path
def handle_connect(self):
pass
def handle_close(self):
self.close()
def handle_read(self):
print self.recv(8192)
def writable(self):
return (len(self.buffer) > 0)
def handle_write(self):
sent = self.send(self.buffer)
self.buffer = self.buffer[sent:]
c = http_client('www.python.org', '/')
asyncore.loop()

105
Doc-3k/library/atexit.rst Normal file
View File

@@ -0,0 +1,105 @@
:mod:`atexit` --- Exit handlers
===============================
.. module:: atexit
:synopsis: Register and execute cleanup functions.
.. moduleauthor:: Skip Montanaro <skip@mojam.com>
.. sectionauthor:: Skip Montanaro <skip@mojam.com>
.. versionadded:: 2.0
The :mod:`atexit` module defines functions to register and unregister cleanup
functions. Functions thus registered are automatically executed upon normal
interpreter termination.
Note: the functions registered via this module are not called when the program
is killed by a signal, when a Python fatal internal error is detected, or when
:func:`os._exit` is called.
.. function:: register(func[, *args[, **kargs]])
Register *func* as a function to be executed at termination. Any optional
arguments that are to be passed to *func* must be passed as arguments to
:func:`register`.
At normal program termination (for instance, if :func:`sys.exit` is called or
the main module's execution completes), all functions registered are called in
last in, first out order. The assumption is that lower level modules will
normally be imported before higher level modules and thus must be cleaned up
later.
If an exception is raised during execution of the exit handlers, a traceback is
printed (unless :exc:`SystemExit` is raised) and the exception information is
saved. After all exit handlers have had a chance to run the last exception to
be raised is re-raised.
.. versionchanged:: 2.6
This function now returns *func* which makes it possible to use it as a
decorator without binding the original name to ``None``.
.. function:: unregister(func)
Remove a function *func* from the list of functions to be run at interpreter-
shutdown. After calling :func:`unregister`, *func* is guaranteed not to be
called when the interpreter shuts down.
.. versionadded:: 3.0
.. seealso::
Module :mod:`readline`
Useful example of :mod:`atexit` to read and write :mod:`readline` history files.
.. _atexit-example:
:mod:`atexit` Example
---------------------
The following simple example demonstrates how a module can initialize a counter
from a file when it is imported and save the counter's updated value
automatically when the program terminates without relying on the application
making an explicit call into this module at termination. ::
try:
_count = int(open("/tmp/counter").read())
except IOError:
_count = 0
def incrcounter(n):
global _count
_count = _count + n
def savecounter():
open("/tmp/counter", "w").write("%d" % _count)
import atexit
atexit.register(savecounter)
Positional and keyword arguments may also be passed to :func:`register` to be
passed along to the registered function when it is called::
def goodbye(name, adjective):
print 'Goodbye, %s, it was %s to meet you.' % (name, adjective)
import atexit
atexit.register(goodbye, 'Donny', 'nice')
# or:
atexit.register(goodbye, adjective='nice', name='Donny')
Usage as a decorator::
import atexit
@atexit.register
def goodbye():
print "You are now leaving the Python sector."
This obviously only works with functions that don't take arguments.

266
Doc-3k/library/audioop.rst Normal file
View File

@@ -0,0 +1,266 @@
:mod:`audioop` --- Manipulate raw audio data
============================================
.. module:: audioop
:synopsis: Manipulate raw audio data.
The :mod:`audioop` module contains some useful operations on sound fragments.
It operates on sound fragments consisting of signed integer samples 8, 16 or 32
bits wide, stored in Python strings. This is the same format as used by the
:mod:`al` and :mod:`sunaudiodev` modules. All scalar items are integers, unless
specified otherwise.
.. index::
single: Intel/DVI ADPCM
single: ADPCM, Intel/DVI
single: a-LAW
single: u-LAW
This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings.
.. % This para is mostly here to provide an excuse for the index entries...
A few of the more complicated operations only take 16-bit samples, otherwise the
sample size (in bytes) is always a parameter of the operation.
The module defines the following variables and functions:
.. exception:: error
This exception is raised on all errors, such as unknown number of bytes per
sample, etc.
.. function:: add(fragment1, fragment2, width)
Return a fragment which is the addition of the two samples passed as parameters.
*width* is the sample width in bytes, either ``1``, ``2`` or ``4``. Both
fragments should have the same length.
.. function:: adpcm2lin(adpcmfragment, width, state)
Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See the
description of :func:`lin2adpcm` for details on ADPCM coding. Return a tuple
``(sample, newstate)`` where the sample has the width specified in *width*.
.. function:: alaw2lin(fragment, width)
Convert sound fragments in a-LAW encoding to linearly encoded sound fragments.
a-LAW encoding always uses 8 bits samples, so *width* refers only to the sample
width of the output fragment here.
.. versionadded:: 2.5
.. function:: avg(fragment, width)
Return the average over all samples in the fragment.
.. function:: avgpp(fragment, width)
Return the average peak-peak value over all samples in the fragment. No
filtering is done, so the usefulness of this routine is questionable.
.. function:: bias(fragment, width, bias)
Return a fragment that is the original fragment with a bias added to each
sample.
.. function:: cross(fragment, width)
Return the number of zero crossings in the fragment passed as an argument.
.. function:: findfactor(fragment, reference)
Return a factor *F* such that ``rms(add(fragment, mul(reference, -F)))`` is
minimal, i.e., return the factor with which you should multiply *reference* to
make it match as well as possible to *fragment*. The fragments should both
contain 2-byte samples.
The time taken by this routine is proportional to ``len(fragment)``.
.. function:: findfit(fragment, reference)
Try to match *reference* as well as possible to a portion of *fragment* (which
should be the longer fragment). This is (conceptually) done by taking slices
out of *fragment*, using :func:`findfactor` to compute the best match, and
minimizing the result. The fragments should both contain 2-byte samples.
Return a tuple ``(offset, factor)`` where *offset* is the (integer) offset into
*fragment* where the optimal match started and *factor* is the (floating-point)
factor as per :func:`findfactor`.
.. function:: findmax(fragment, length)
Search *fragment* for a slice of length *length* samples (not bytes!) with
maximum energy, i.e., return *i* for which ``rms(fragment[i*2:(i+length)*2])``
is maximal. The fragments should both contain 2-byte samples.
The routine takes time proportional to ``len(fragment)``.
.. function:: getsample(fragment, width, index)
Return the value of sample *index* from the fragment.
.. function:: lin2adpcm(fragment, width, state)
Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an adaptive
coding scheme, whereby each 4 bit number is the difference between one sample
and the next, divided by a (varying) step. The Intel/DVI ADPCM algorithm has
been selected for use by the IMA, so it may well become a standard.
*state* is a tuple containing the state of the coder. The coder returns a tuple
``(adpcmfrag, newstate)``, and the *newstate* should be passed to the next call
of :func:`lin2adpcm`. In the initial call, ``None`` can be passed as the state.
*adpcmfrag* is the ADPCM coded fragment packed 2 4-bit values per byte.
.. function:: lin2alaw(fragment, width)
Convert samples in the audio fragment to a-LAW encoding and return this as a
Python string. a-LAW is an audio encoding format whereby you get a dynamic
range of about 13 bits using only 8 bit samples. It is used by the Sun audio
hardware, among others.
.. versionadded:: 2.5
.. function:: lin2lin(fragment, width, newwidth)
Convert samples between 1-, 2- and 4-byte formats.
.. function:: lin2ulaw(fragment, width)
Convert samples in the audio fragment to u-LAW encoding and return this as a
Python string. u-LAW is an audio encoding format whereby you get a dynamic
range of about 14 bits using only 8 bit samples. It is used by the Sun audio
hardware, among others.
.. function:: minmax(fragment, width)
Return a tuple consisting of the minimum and maximum values of all samples in
the sound fragment.
.. function:: max(fragment, width)
Return the maximum of the *absolute value* of all samples in a fragment.
.. function:: maxpp(fragment, width)
Return the maximum peak-peak value in the sound fragment.
.. function:: mul(fragment, width, factor)
Return a fragment that has all samples in the original fragment multiplied by
the floating-point value *factor*. Overflow is silently ignored.
.. function:: ratecv(fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]])
Convert the frame rate of the input fragment.
*state* is a tuple containing the state of the converter. The converter returns
a tuple ``(newfragment, newstate)``, and *newstate* should be passed to the next
call of :func:`ratecv`. The initial call should pass ``None`` as the state.
The *weightA* and *weightB* arguments are parameters for a simple digital filter
and default to ``1`` and ``0`` respectively.
.. function:: reverse(fragment, width)
Reverse the samples in a fragment and returns the modified fragment.
.. function:: rms(fragment, width)
Return the root-mean-square of the fragment, i.e. ::
XXX: translate this math
\catcode`_=8
\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
This is a measure of the power in an audio signal.
.. function:: tomono(fragment, width, lfactor, rfactor)
Convert a stereo fragment to a mono fragment. The left channel is multiplied by
*lfactor* and the right channel by *rfactor* before adding the two channels to
give a mono signal.
.. function:: tostereo(fragment, width, lfactor, rfactor)
Generate a stereo fragment from a mono fragment. Each pair of samples in the
stereo fragment are computed from the mono sample, whereby left channel samples
are multiplied by *lfactor* and right channel samples by *rfactor*.
.. function:: ulaw2lin(fragment, width)
Convert sound fragments in u-LAW encoding to linearly encoded sound fragments.
u-LAW encoding always uses 8 bits samples, so *width* refers only to the sample
width of the output fragment here.
Note that operations such as :func:`mul` or :func:`max` make no distinction
between mono and stereo fragments, i.e. all samples are treated equal. If this
is a problem the stereo fragment should be split into two mono fragments first
and recombined later. Here is an example of how to do that::
def mul_stereo(sample, width, lfactor, rfactor):
lsample = audioop.tomono(sample, width, 1, 0)
rsample = audioop.tomono(sample, width, 0, 1)
lsample = audioop.mul(sample, width, lfactor)
rsample = audioop.mul(sample, width, rfactor)
lsample = audioop.tostereo(lsample, width, 1, 0)
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
If you use the ADPCM coder to build network packets and you want your protocol
to be stateless (i.e. to be able to tolerate packet loss) you should not only
transmit the data but also the state. Note that you should send the *initial*
state (the one you passed to :func:`lin2adpcm`) along to the decoder, not the
final state (as returned by the coder). If you want to use
:func:`struct.struct` to store the state in binary you can code the first
element (the predicted value) in 16 bits and the second (the delta index) in 8.
The ADPCM coders have never been tried against other ADPCM coders, only against
themselves. It could well be that I misinterpreted the standards in which case
they will not be interoperable with the respective standards.
The :func:`find\*` routines might look a bit funny at first sight. They are
primarily meant to do echo cancellation. A reasonably fast way to do this is to
pick the most energetic piece of the output sample, locate that in the input
sample and subtract the whole output sample from the input sample::
def echocancel(outputdata, inputdata):
pos = audioop.findmax(outputdata, 800) # one tenth second
out_test = outputdata[pos*2:]
in_test = inputdata[pos*2:]
ipos, factor = audioop.findfit(in_test, out_test)
# Optional (for better cancellation):
# factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
# out_test)
prefill = '\0'*(pos+ipos)*2
postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
return audioop.add(inputdata, outputdata, 2)

172
Doc-3k/library/base64.rst Normal file
View File

@@ -0,0 +1,172 @@
:mod:`base64` --- RFC 3548: Base16, Base32, Base64 Data Encodings
=================================================================
.. module:: base64
:synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings
.. index::
pair: base64; encoding
single: MIME; base64 encoding
This module provides data encoding and decoding as specified in :rfc:`3548`.
This standard defines the Base16, Base32, and Base64 algorithms for encoding and
decoding arbitrary binary strings into text strings that can be safely sent by
email, used as parts of URLs, or included as part of an HTTP POST request. The
encoding algorithm is not the same as the :program:`uuencode` program.
There are two interfaces provided by this module. The modern interface supports
encoding and decoding string objects using all three alphabets. The legacy
interface provides for encoding and decoding to and from file-like objects as
well as strings, but only using the Base64 standard alphabet.
The modern interface, which was introduced in Python 2.4, provides:
.. function:: b64encode(s[, altchars])
Encode a string use Base64.
*s* is the string to encode. Optional *altchars* must be a string of at least
length 2 (additional characters are ignored) which specifies an alternative
alphabet for the ``+`` and ``/`` characters. This allows an application to e.g.
generate URL or filesystem safe Base64 strings. The default is ``None``, for
which the standard Base64 alphabet is used.
The encoded string is returned.
.. function:: b64decode(s[, altchars])
Decode a Base64 encoded string.
*s* is the string to decode. Optional *altchars* must be a string of at least
length 2 (additional characters are ignored) which specifies the alternative
alphabet used instead of the ``+`` and ``/`` characters.
The decoded string is returned. A :exc:`TypeError` is raised if *s* were
incorrectly padded or if there are non-alphabet characters present in the
string.
.. function:: standard_b64encode(s)
Encode string *s* using the standard Base64 alphabet.
.. function:: standard_b64decode(s)
Decode string *s* using the standard Base64 alphabet.
.. function:: urlsafe_b64encode(s)
Encode string *s* using a URL-safe alphabet, which substitutes ``-`` instead of
``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet.
.. function:: urlsafe_b64decode(s)
Decode string *s* using a URL-safe alphabet, which substitutes ``-`` instead of
``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet.
.. function:: b32encode(s)
Encode a string using Base32. *s* is the string to encode. The encoded string
is returned.
.. function:: b32decode(s[, casefold[, map01]])
Decode a Base32 encoded string.
*s* is the string to decode. Optional *casefold* is a flag specifying whether a
lowercase alphabet is acceptable as input. For security purposes, the default
is ``False``.
:rfc:`3548` allows for optional mapping of the digit 0 (zero) to the letter O
(oh), and for optional mapping of the digit 1 (one) to either the letter I (eye)
or letter L (el). The optional argument *map01* when not ``None``, specifies
which letter the digit 1 should be mapped to (when *map01* is not ``None``, the
digit 0 is always mapped to the letter O). For security purposes the default is
``None``, so that 0 and 1 are not allowed in the input.
The decoded string is returned. A :exc:`TypeError` is raised if *s* were
incorrectly padded or if there are non-alphabet characters present in the
string.
.. function:: b16encode(s)
Encode a string using Base16.
*s* is the string to encode. The encoded string is returned.
.. function:: b16decode(s[, casefold])
Decode a Base16 encoded string.
*s* is the string to decode. Optional *casefold* is a flag specifying whether a
lowercase alphabet is acceptable as input. For security purposes, the default
is ``False``.
The decoded string is returned. A :exc:`TypeError` is raised if *s* were
incorrectly padded or if there are non-alphabet characters present in the
string.
The legacy interface:
.. function:: decode(input, output)
Decode the contents of the *input* file and write the resulting binary data to
the *output* file. *input* and *output* must either be file objects or objects
that mimic the file object interface. *input* will be read until
``input.read()`` returns an empty string.
.. function:: decodestring(s)
Decode the string *s*, which must contain one or more lines of base64 encoded
data, and return a string containing the resulting binary data.
.. function:: encode(input, output)
Encode the contents of the *input* file and write the resulting base64 encoded
data to the *output* file. *input* and *output* must either be file objects or
objects that mimic the file object interface. *input* will be read until
``input.read()`` returns an empty string. :func:`encode` returns the encoded
data plus a trailing newline character (``'\n'``).
.. function:: encodestring(s)
Encode the string *s*, which can contain arbitrary binary data, and return a
string containing one or more lines of base64-encoded data.
:func:`encodestring` returns a string containing one or more lines of
base64-encoded data always including an extra trailing newline (``'\n'``).
An example usage of the module::
>>> import base64
>>> encoded = base64.b64encode('data to be encoded')
>>> encoded
'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
'data to be encoded'
.. seealso::
Module :mod:`binascii`
Support module containing ASCII-to-binary and binary-to-ASCII conversions.
:rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the
base64 encoding.

254
Doc-3k/library/basehttpserver.rst Normal file
View File

@@ -0,0 +1,254 @@
:mod:`BaseHTTPServer` --- Basic HTTP server
===========================================
.. module:: BaseHTTPServer
:synopsis: Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer).
.. index::
pair: WWW; server
pair: HTTP; protocol
single: URL
single: httpd
.. index::
module: SimpleHTTPServer
module: CGIHTTPServer
This module defines two classes for implementing HTTP servers (Web servers).
Usually, this module isn't used directly, but is used as a basis for building
functioning Web servers. See the :mod:`SimpleHTTPServer` and
:mod:`CGIHTTPServer` modules.
The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer`
subclass. It creates and listens at the HTTP socket, dispatching the requests
to a handler. Code to create and run the server looks like this::
def run(server_class=BaseHTTPServer.HTTPServer,
handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
server_address = ('', 8000)
httpd = server_class(server_address, handler_class)
httpd.serve_forever()
.. class:: HTTPServer(server_address, RequestHandlerClass)
This class builds on the :class:`TCPServer` class by storing the server address
as instance variables named :attr:`server_name` and :attr:`server_port`. The
server is accessible by the handler, typically through the handler's
:attr:`server` instance variable.
.. class:: BaseHTTPRequestHandler(request, client_address, server)
This class is used to handle the HTTP requests that arrive at the server. By
itself, it cannot respond to any actual HTTP requests; it must be subclassed to
handle each request method (e.g. GET or POST). :class:`BaseHTTPRequestHandler`
provides a number of class and instance variables, and methods for use by
subclasses.
The handler will parse the request and the headers, then call a method specific
to the request type. The method name is constructed from the request. For
example, for the request method ``SPAM``, the :meth:`do_SPAM` method will be
called with no arguments. All of the relevant information is stored in instance
variables of the handler. Subclasses should not need to override or extend the
:meth:`__init__` method.
:class:`BaseHTTPRequestHandler` has the following instance variables:
.. attribute:: BaseHTTPRequestHandler.client_address
Contains a tuple of the form ``(host, port)`` referring to the client's address.
.. attribute:: BaseHTTPRequestHandler.command
Contains the command (request type). For example, ``'GET'``.
.. attribute:: BaseHTTPRequestHandler.path
Contains the request path.
.. attribute:: BaseHTTPRequestHandler.request_version
Contains the version string from the request. For example, ``'HTTP/1.0'``.
.. attribute:: BaseHTTPRequestHandler.headers
Holds an instance of the class specified by the :attr:`MessageClass` class
variable. This instance parses and manages the headers in the HTTP request.
.. attribute:: BaseHTTPRequestHandler.rfile
Contains an input stream, positioned at the start of the optional input data.
.. attribute:: BaseHTTPRequestHandler.wfile
Contains the output stream for writing a response back to the client. Proper
adherence to the HTTP protocol must be used when writing to this stream.
:class:`BaseHTTPRequestHandler` has the following class variables:
.. attribute:: BaseHTTPRequestHandler.server_version
Specifies the server software version. You may want to override this. The
format is multiple whitespace-separated strings, where each string is of the
form name[/version]. For example, ``'BaseHTTP/0.2'``.
.. attribute:: BaseHTTPRequestHandler.sys_version
Contains the Python system version, in a form usable by the
:attr:`version_string` method and the :attr:`server_version` class variable. For
example, ``'Python/1.4'``.
.. attribute:: BaseHTTPRequestHandler.error_message_format
Specifies a format string for building an error response to the client. It uses
parenthesized, keyed format specifiers, so the format operand must be a
dictionary. The *code* key should be an integer, specifying the numeric HTTP
error code value. *message* should be a string containing a (detailed) error
message of what occurred, and *explain* should be an explanation of the error
code number. Default *message* and *explain* values can found in the *responses*
class variable.
.. attribute:: BaseHTTPRequestHandler.protocol_version
This specifies the HTTP protocol version used in responses. If set to
``'HTTP/1.1'``, the server will permit HTTP persistent connections; however,
your server *must* then include an accurate ``Content-Length`` header (using
:meth:`send_header`) in all of its responses to clients. For backwards
compatibility, the setting defaults to ``'HTTP/1.0'``.
.. attribute:: BaseHTTPRequestHandler.MessageClass
.. index:: single: Message (in module mimetools)
Specifies a :class:`rfc822.Message`\ -like class to parse HTTP headers.
Typically, this is not overridden, and it defaults to
:class:`mimetools.Message`.
.. attribute:: BaseHTTPRequestHandler.responses
This variable contains a mapping of error code integers to two-element tuples
containing a short and long message. For example, ``{code: (shortmessage,
longmessage)}``. The *shortmessage* is usually used as the *message* key in an
error response, and *longmessage* as the *explain* key (see the
:attr:`error_message_format` class variable).
A :class:`BaseHTTPRequestHandler` instance has the following methods:
.. method:: BaseHTTPRequestHandler.handle()
Calls :meth:`handle_one_request` once (or, if persistent connections are
enabled, multiple times) to handle incoming HTTP requests. You should never need
to override it; instead, implement appropriate :meth:`do_\*` methods.
.. method:: BaseHTTPRequestHandler.handle_one_request()
This method will parse and dispatch the request to the appropriate :meth:`do_\*`
method. You should never need to override it.
.. method:: BaseHTTPRequestHandler.send_error(code[, message])
Sends and logs a complete error reply to the client. The numeric *code*
specifies the HTTP error code, with *message* as optional, more specific text. A
complete set of headers is sent, followed by text composed using the
:attr:`error_message_format` class variable.
.. method:: BaseHTTPRequestHandler.send_response(code[, message])
Sends a response header and logs the accepted request. The HTTP response line is
sent, followed by *Server* and *Date* headers. The values for these two headers
are picked up from the :meth:`version_string` and :meth:`date_time_string`
methods, respectively.
.. method:: BaseHTTPRequestHandler.send_header(keyword, value)
Writes a specific HTTP header to the output stream. *keyword* should specify the
header keyword, with *value* specifying its value.
.. method:: BaseHTTPRequestHandler.end_headers()
Sends a blank line, indicating the end of the HTTP headers in the response.
.. method:: BaseHTTPRequestHandler.log_request([code[, size]])
Logs an accepted (successful) request. *code* should specify the numeric HTTP
code associated with the response. If a size of the response is available, then
it should be passed as the *size* parameter.
.. method:: BaseHTTPRequestHandler.log_error(...)
Logs an error when a request cannot be fulfilled. By default, it passes the
message to :meth:`log_message`, so it takes the same arguments (*format* and
additional values).
.. method:: BaseHTTPRequestHandler.log_message(format, ...)
Logs an arbitrary message to ``sys.stderr``. This is typically overridden to
create custom error logging mechanisms. The *format* argument is a standard
printf-style format string, where the additional arguments to
:meth:`log_message` are applied as inputs to the formatting. The client address
and current date and time are prefixed to every message logged.
.. method:: BaseHTTPRequestHandler.version_string()
Returns the server software's version string. This is a combination of the
:attr:`server_version` and :attr:`sys_version` class variables.
.. method:: BaseHTTPRequestHandler.date_time_string([timestamp])
Returns the date and time given by *timestamp* (which must be in the format
returned by :func:`time.time`), formatted for a message header. If *timestamp*
is omitted, it uses the current date and time.
The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``.
.. versionadded:: 2.5
The *timestamp* parameter.
.. method:: BaseHTTPRequestHandler.log_date_time_string()
Returns the current date and time, formatted for logging.
.. method:: BaseHTTPRequestHandler.address_string()
Returns the client address, formatted for logging. A name lookup is performed on
the client's IP address.
.. seealso::
Module :mod:`CGIHTTPServer`
Extended request handler that supports CGI scripts.
Module :mod:`SimpleHTTPServer`
Basic request handler that limits response to files actually under the document
root.

161
Doc-3k/library/binascii.rst Normal file
View File

@@ -0,0 +1,161 @@
:mod:`binascii` --- Convert between binary and ASCII
====================================================
.. module:: binascii
:synopsis: Tools for converting between binary and various ASCII-encoded binary
representations.
.. index::
module: uu
module: base64
module: binhex
The :mod:`binascii` module contains a number of methods to convert between
binary and various ASCII-encoded binary representations. Normally, you will not
use these functions directly but use wrapper modules like :mod:`uu`,
:mod:`base64`, or :mod:`binhex` instead. The :mod:`binascii` module contains
low-level functions written in C for greater speed that are used by the higher-
level modules.
The :mod:`binascii` module defines the following functions:
.. function:: a2b_uu(string)
Convert a single line of uuencoded data back to binary and return the binary
data. Lines normally contain 45 (binary) bytes, except for the last line. Line
data may be followed by whitespace.
.. function:: b2a_uu(data)
Convert binary data to a line of ASCII characters, the return value is the
converted line, including a newline char. The length of *data* should be at most
45.
.. function:: a2b_base64(string)
Convert a block of base64 data back to binary and return the binary data. More
than one line may be passed at a time.
.. function:: b2a_base64(data)
Convert binary data to a line of ASCII characters in base64 coding. The return
value is the converted line, including a newline char. The length of *data*
should be at most 57 to adhere to the base64 standard.
.. function:: a2b_qp(string[, header])
Convert a block of quoted-printable data back to binary and return the binary
data. More than one line may be passed at a time. If the optional argument
*header* is present and true, underscores will be decoded as spaces.
.. function:: b2a_qp(data[, quotetabs, istext, header])
Convert binary data to a line(s) of ASCII characters in quoted-printable
encoding. The return value is the converted line(s). If the optional argument
*quotetabs* is present and true, all tabs and spaces will be encoded. If the
optional argument *istext* is present and true, newlines are not encoded but
trailing whitespace will be encoded. If the optional argument *header* is
present and true, spaces will be encoded as underscores per RFC1522. If the
optional argument *header* is present and false, newline characters will be
encoded as well; otherwise linefeed conversion might corrupt the binary data
stream.
.. function:: a2b_hqx(string)
Convert binhex4 formatted ASCII data to binary, without doing RLE-decompression.
The string should contain a complete number of binary bytes, or (in case of the
last portion of the binhex4 data) have the remaining bits zero.
.. function:: rledecode_hqx(data)
Perform RLE-decompression on the data, as per the binhex4 standard. The
algorithm uses ``0x90`` after a byte as a repeat indicator, followed by a count.
A count of ``0`` specifies a byte value of ``0x90``. The routine returns the
decompressed data, unless data input data ends in an orphaned repeat indicator,
in which case the :exc:`Incomplete` exception is raised.
.. function:: rlecode_hqx(data)
Perform binhex4 style RLE-compression on *data* and return the result.
.. function:: b2a_hqx(data)
Perform hexbin4 binary-to-ASCII translation and return the resulting string. The
argument should already be RLE-coded, and have a length divisible by 3 (except
possibly the last fragment).
.. function:: crc_hqx(data, crc)
Compute the binhex4 crc value of *data*, starting with an initial *crc* and
returning the result.
.. function:: crc32(data[, crc])
Compute CRC-32, the 32-bit checksum of data, starting with an initial crc. This
is consistent with the ZIP file checksum. Since the algorithm is designed for
use as a checksum algorithm, it is not suitable for use as a general hash
algorithm. Use as follows::
print binascii.crc32("hello world")
# Or, in two pieces:
crc = binascii.crc32("hello")
crc = binascii.crc32(" world", crc)
print crc
.. function:: b2a_hex(data)
hexlify(data)
Return the hexadecimal representation of the binary *data*. Every byte of
*data* is converted into the corresponding 2-digit hex representation. The
resulting string is therefore twice as long as the length of *data*.
.. function:: a2b_hex(hexstr)
unhexlify(hexstr)
Return the binary data represented by the hexadecimal string *hexstr*. This
function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even number
of hexadecimal digits (which can be upper or lower case), otherwise a
:exc:`TypeError` is raised.
.. exception:: Error
Exception raised on errors. These are usually programming errors.
.. exception:: Incomplete
Exception raised on incomplete data. These are usually not programming errors,
but may be handled by reading a little more data and trying again.
.. seealso::
Module :mod:`base64`
Support for base64 encoding used in MIME email messages.
Module :mod:`binhex`
Support for the binhex format used on the Macintosh.
Module :mod:`uu`
Support for UU encoding used on Unix.
Module :mod:`quopri`
Support for quoted-printable encoding used in MIME email messages.

59
Doc-3k/library/binhex.rst Normal file
View File

@@ -0,0 +1,59 @@
:mod:`binhex` --- Encode and decode binhex4 files
=================================================
.. module:: binhex
:synopsis: Encode and decode files in binhex4 format.
This module encodes and decodes files in binhex4 format, a format allowing
representation of Macintosh files in ASCII. On the Macintosh, both forks of a
file and the finder information are encoded (or decoded), on other platforms
only the data fork is handled.
The :mod:`binhex` module defines the following functions:
.. function:: binhex(input, output)
Convert a binary file with filename *input* to binhex file *output*. The
*output* parameter can either be a filename or a file-like object (any object
supporting a :meth:`write` and :meth:`close` method).
.. function:: hexbin(input[, output])
Decode a binhex file *input*. *input* may be a filename or a file-like object
supporting :meth:`read` and :meth:`close` methods. The resulting file is written
to a file named *output*, unless the argument is omitted in which case the
output filename is read from the binhex file.
The following exception is also defined:
.. exception:: Error
Exception raised when something can't be encoded using the binhex format (for
example, a filename is too long to fit in the filename field), or when input is
not properly encoded binhex data.
.. seealso::
Module :mod:`binascii`
Support module containing ASCII-to-binary and binary-to-ASCII conversions.
.. _binhex-notes:
Notes
-----
There is an alternative, more powerful interface to the coder and decoder, see
the source for details.
If you code or decode textfiles on non-Macintosh platforms they will still use
the Macintosh newline convention (carriage-return as end of line).
As of this writing, :func:`hexbin` appears to not work in all cases.

92
Doc-3k/library/bisect.rst Normal file
View File

@@ -0,0 +1,92 @@
:mod:`bisect` --- Array bisection algorithm
===========================================
.. module:: bisect
:synopsis: Array bisection algorithms for binary searching.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. % LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an
.. % example based on the PyModules FAQ entry by Aaron Watters
.. % <arw@pythonpros.com>.
This module provides support for maintaining a list in sorted order without
having to sort the list after each insertion. For long lists of items with
expensive comparison operations, this can be an improvement over the more common
approach. The module is called :mod:`bisect` because it uses a basic bisection
algorithm to do its work. The source code may be most useful as a working
example of the algorithm (the boundary conditions are already right!).
The following functions are provided:
.. function:: bisect_left(list, item[, lo[, hi]])
Locate the proper insertion point for *item* in *list* to maintain sorted order.
The parameters *lo* and *hi* may be used to specify a subset of the list which
should be considered; by default the entire list is used. If *item* is already
present in *list*, the insertion point will be before (to the left of) any
existing entries. The return value is suitable for use as the first parameter
to ``list.insert()``. This assumes that *list* is already sorted.
.. versionadded:: 2.1
.. function:: bisect_right(list, item[, lo[, hi]])
Similar to :func:`bisect_left`, but returns an insertion point which comes after
(to the right of) any existing entries of *item* in *list*.
.. versionadded:: 2.1
.. function:: bisect(...)
Alias for :func:`bisect_right`.
.. function:: insort_left(list, item[, lo[, hi]])
Insert *item* in *list* in sorted order. This is equivalent to
``list.insert(bisect.bisect_left(list, item, lo, hi), item)``. This assumes
that *list* is already sorted.
.. versionadded:: 2.1
.. function:: insort_right(list, item[, lo[, hi]])
Similar to :func:`insort_left`, but inserting *item* in *list* after any
existing entries of *item*.
.. versionadded:: 2.1
.. function:: insort(...)
Alias for :func:`insort_right`.
Examples
--------
.. _bisect-example:
The :func:`bisect` function is generally useful for categorizing numeric data.
This example uses :func:`bisect` to look up a letter grade for an exam total
(say) based on a set of ordered numeric breakpoints: 85 and up is an 'A', 75..84
is a 'B', etc. ::
>>> grades = "FEDCBA"
>>> breakpoints = [30, 44, 66, 75, 85]
>>> from bisect import bisect
>>> def grade(total):
... return grades[bisect(breakpoints, total)]
...
>>> grade(66)
'C'
>>> map(grade, [33, 99, 77, 44, 12, 88])
['E', 'A', 'B', 'D', 'F', 'A']

195
Doc-3k/library/bsddb.rst Normal file
View File

@@ -0,0 +1,195 @@
:mod:`bsddb` --- Interface to Berkeley DB library
=================================================
.. module:: bsddb
:synopsis: Interface to Berkeley DB database library
.. sectionauthor:: Skip Montanaro <skip@mojam.com>
The :mod:`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
:func:`marshal.dumps` or :func:`pickle.dumps`.
The :mod:`bsddb` module requires a Berkeley DB library version from 3.3 thru
4.5.
.. seealso::
http://pybsddb.sourceforge.net/
The website with documentation for the :mod:`bsddb.db` Python Berkeley DB
interface that closely mirrors the object oriented interface provided in
Berkeley DB 3 and 4.
http://www.oracle.com/database/berkeley-db/
The Berkeley DB library.
A more modern DB, DBEnv and DBSequence object interface is available in the
:mod:`bsddb.db` module which closely matches the Berkeley DB C API documented at
the above URLs. Additional features provided by the :mod:`bsddb.db` API include
fine tuning, transactions, logging, and multiprocess concurrent database access.
The following is a description of the legacy :mod:`bsddb` interface compatible
with the old Python bsddb module. Starting in Python 2.5 this interface should
be safe for multithreaded access. The :mod:`bsddb.db` API is recommended for
threading users as it provides better control.
The :mod:`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.
.. function:: hashopen(filename[, flag[, mode[, pgsize[, ffactor[, nelem[, cachesize[, lorder[, hflags]]]]]]]])
Open the hash format file named *filename*. Files never intended to be
preserved on disk may be created by passing ``None`` as the *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;
the default) or ``'n'`` (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level :cfunc:`dbopen`
function. Consult the Berkeley DB documentation for their use and
interpretation.
.. function:: btopen(filename[, flag[, mode[, btflags[, cachesize[, maxkeypage[, minkeypage[, pgsize[, lorder]]]]]]]])
Open the btree format file named *filename*. Files never intended to be
preserved on disk may be created by passing ``None`` as the *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;
the default) 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.
.. function:: rnopen(filename[, flag[, mode[, rnflags[, cachesize[, pgsize[, lorder[, rlen[, delim[, source[, pad]]]]]]]]]])
Open a DB record format file named *filename*. Files never intended to be
preserved on disk may be created by passing ``None`` as the *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;
the default) 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.
.. seealso::
Module :mod:`dbhash`
DBM-style interface to the :mod:`bsddb`
.. _bsddb-objects:
Hash, BTree and Record Objects
------------------------------
Once instantiated, hash, btree and record objects support the same methods as
dictionaries. In addition, they support the methods listed below.
.. versionchanged:: 2.3.1
Added dictionary methods.
.. method:: bsddbobject.close()
Close the underlying file. The object can no longer be accessed. Since there
is no open :meth:`open` method for these objects, to open the file again a new
:mod:`bsddb` module open function must be called.
.. method:: bsddbobject.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.
.. method:: bsddbobject.has_key(key)
Return ``1`` if the DB file contains the argument as a key.
.. method:: bsddbobject.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 :func:`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,
:exc:`KeyError` will be raised if *key* is not found in the database.
.. method:: bsddbobject.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. This
method raises :exc:`bsddb.error` if the database is empty.
.. method:: bsddbobject.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.
.. method:: bsddbobject.previous()
Set the cursor to the previous 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 :func:`hashopen`).
.. method:: bsddbobject.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 :func:`hashopen`). This method raises :exc:`bsddb.error` if the
database is empty.
.. method:: bsddbobject.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')
>>> for k, v in db.iteritems():
... print k, v
0 0
1 1
2 4
3 9
4 16
5 25
6 36
7 49
8 64
9 81
>>> '8' in db
True
>>> db.sync()
0

181
Doc-3k/library/bz2.rst Normal file
View File

@@ -0,0 +1,181 @@
:mod:`bz2` --- Compression compatible with :program:`bzip2`
===========================================================
.. module:: bz2
:synopsis: Interface to compression and decompression routines compatible with bzip2.
.. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
.. versionadded:: 2.3
This module provides a comprehensive interface for the bz2 compression library.
It implements a complete file interface, one-shot (de)compression functions, and
types for sequential (de)compression.
Here is a resume of the features offered by the bz2 module:
* :class:`BZ2File` class implements a complete file interface, including
:meth:`readline`, :meth:`readlines`, :meth:`writelines`, :meth:`seek`, etc;
* :class:`BZ2File` class implements emulated :meth:`seek` support;
* :class:`BZ2File` class implements universal newline support;
* :class:`BZ2File` class offers an optimized line iteration using the readahead
algorithm borrowed from file objects;
* Sequential (de)compression supported by :class:`BZ2Compressor` and
:class:`BZ2Decompressor` classes;
* One-shot (de)compression supported by :func:`compress` and :func:`decompress`
functions;
* Thread safety uses individual locking mechanism;
* Complete inline documentation;
(De)compression of files
------------------------
Handling of compressed files is offered by the :class:`BZ2File` class.
.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])
Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
or writing. When opened for writing, the file will be created if it doesn't
exist, and truncated otherwise. If *buffering* is given, ``0`` means unbuffered,
and larger numbers specify the buffer size; the default is ``0``. If
*compresslevel* is given, it must be a number between ``1`` and ``9``; the
default is ``9``. Add a ``'U'`` to mode to open the file for input with
universal newline support. Any line ending in the input file will be seen as a
``'\n'`` in Python. Also, a file so opened gains the attribute
:attr:`newlines`; the value for this attribute is one of ``None`` (no newline
read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the newline
types seen. Universal newlines are available only when reading. Instances
support iteration in the same way as normal :class:`file` instances.
.. method:: BZ2File.close()
Close the file. Sets data attribute :attr:`closed` to true. A closed file cannot
be used for further I/O operations. :meth:`close` may be called more than once
without error.
.. method:: BZ2File.read([size])
Read at most *size* uncompressed bytes, returned as a string. If the *size*
argument is negative or omitted, read until EOF is reached.
.. method:: BZ2File.readline([size])
Return the next line from the file, as a string, retaining newline. A non-
negative *size* argument limits the maximum number of bytes to return (an
incomplete line may be returned then). Return an empty string at EOF.
.. method:: BZ2File.readlines([size])
Return a list of lines read. The optional *size* argument, if given, is an
approximate bound on the total number of bytes in the lines returned.
.. method:: BZ2File.seek(offset[, whence])
Move to new file position. Argument *offset* is a byte count. Optional argument
*whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start of file; offset
should be ``>= 0``); other values are ``os.SEEK_CUR`` or ``1`` (move relative to
current position; offset can be positive or negative), and ``os.SEEK_END`` or
``2`` (move relative to end of file; offset is usually negative, although many
platforms allow seeking beyond the end of a file).
Note that seeking of bz2 files is emulated, and depending on the parameters the
operation may be extremely slow.
.. method:: BZ2File.tell()
Return the current file position, an integer (may be a long integer).
.. method:: BZ2File.write(data)
Write string *data* to file. Note that due to buffering, :meth:`close` may be
needed before the file on disk reflects the data written.
.. method:: BZ2File.writelines(sequence_of_strings)
Write the sequence of strings to the file. Note that newlines are not added. The
sequence can be any iterable object producing strings. This is equivalent to
calling write() for each string.
Sequential (de)compression
--------------------------
Sequential compression and decompression is done using the classes
:class:`BZ2Compressor` and :class:`BZ2Decompressor`.
.. class:: BZ2Compressor([compresslevel])
Create a new compressor object. This object may be used to compress data
sequentially. If you want to compress data in one shot, use the :func:`compress`
function instead. The *compresslevel* parameter, if given, must be a number
between ``1`` and ``9``; the default is ``9``.
.. method:: BZ2Compressor.compress(data)
Provide more data to the compressor object. It will return chunks of compressed
data whenever possible. When you've finished providing data to compress, call
the :meth:`flush` method to finish the compression process, and return what is
left in internal buffers.
.. method:: BZ2Compressor.flush()
Finish the compression process and return what is left in internal buffers. You
must not use the compressor object after calling this method.
.. class:: BZ2Decompressor()
Create a new decompressor object. This object may be used to decompress data
sequentially. If you want to decompress data in one shot, use the
:func:`decompress` function instead.
.. method:: BZ2Decompressor.decompress(data)
Provide more data to the decompressor object. It will return chunks of
decompressed data whenever possible. If you try to decompress data after the end
of stream is found, :exc:`EOFError` will be raised. If any data was found after
the end of stream, it'll be ignored and saved in :attr:`unused_data` attribute.
One-shot (de)compression
------------------------
One-shot compression and decompression is provided through the :func:`compress`
and :func:`decompress` functions.
.. function:: compress(data[, compresslevel])
Compress *data* in one shot. If you want to compress data sequentially, use an
instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, if
given, must be a number between ``1`` and ``9``; the default is ``9``.
.. function:: decompress(data)
Decompress *data* in one shot. If you want to decompress data sequentially, use
an instance of :class:`BZ2Decompressor` instead.

324
Doc-3k/library/calendar.rst Normal file
View File

@@ -0,0 +1,324 @@
:mod:`calendar` --- General calendar-related functions
======================================================
.. module:: calendar
:synopsis: Functions for working with calendars, including some emulation of the Unix cal
program.
.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
This module allows you to output calendars like the Unix :program:`cal` program,
and provides additional useful functions related to the calendar. By default,
these calendars have Monday as the first day of the week, and Sunday as the last
(the European convention). Use :func:`setfirstweekday` to set the first day of
the week to Sunday (6) or to any other weekday. Parameters that specify dates
are given as integers.
Most of these functions and classses rely on the :mod:`datetime` module which
uses an idealized calendar, the current Gregorian calendar indefinitely extended
in both directions. This matches the definition of the "proleptic Gregorian"
calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
it's the base calendar for all computations.
.. class:: Calendar([firstweekday])
Creates a :class:`Calendar` object. *firstweekday* is an integer specifying the
first day of the week. ``0`` is Monday (the default), ``6`` is Sunday.
A :class:`Calendar` object provides several methods that can be used for
preparing the calendar data for formatting. This class doesn't do any formatting
itself. This is the job of subclasses.
.. versionadded:: 2.5
:class:`Calendar` instances have the following methods:
.. method:: Calendar.iterweekdays(weekday)
Return an iterator for the week day numbers that will be used for one week. The
first number from the iterator will be the same as the number returned by
:meth:`firstweekday`.
.. method:: Calendar.itermonthdates(year, month)
Return an iterator for the month *month* (1-12) in the year *year*. This
iterator will return all days (as :class:`datetime.date` objects) for the month
and all days before the start of the month or after the end of the month that
are required to get a complete week.
.. method:: Calendar.itermonthdays2(year, month)
Return an iterator for the month *month* in the year *year* similar to
:meth:`itermonthdates`. Days returned will be tuples consisting of a day number
and a week day number.
.. method:: Calendar.itermonthdays(year, month)
Return an iterator for the month *month* in the year *year* similar to
:meth:`itermonthdates`. Days returned will simply be day numbers.
.. method:: Calendar.monthdatescalendar(year, month)
Return a list of the weeks in the month *month* of the *year* as full weeks.
Weeks are lists of seven :class:`datetime.date` objects.
.. method:: Calendar.monthdays2calendar(year, month)
Return a list of the weeks in the month *month* of the *year* as full weeks.
Weeks are lists of seven tuples of day numbers and weekday numbers.
.. method:: Calendar.monthdayscalendar(year, month)
Return a list of the weeks in the month *month* of the *year* as full weeks.
Weeks are lists of seven day numbers.
.. method:: Calendar.yeardatescalendar(year, month[, width])
Return the data for the specified year ready for formatting. The return value is
a list of month rows. Each month row contains up to *width* months (defaulting
to 3). Each month contains between 4 and 6 weeks and each week contains 1--7
days. Days are :class:`datetime.date` objects.
.. method:: Calendar.yeardays2calendar(year, month[, width])
Return the data for the specified year ready for formatting (similar to
:meth:`yeardatescalendar`). Entries in the week lists are tuples of day numbers
and weekday numbers. Day numbers outside this month are zero.
.. method:: Calendar.yeardayscalendar(year, month[, width])
Return the data for the specified year ready for formatting (similar to
:meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
numbers outside this month are zero.
.. class:: TextCalendar([firstweekday])
This class can be used to generate plain text calendars.
.. versionadded:: 2.5
:class:`TextCalendar` instances have the following methods:
.. method:: TextCalendar.formatmonth(theyear, themonth[, w[, l]])
Return a month's calendar in a multi-line string. If *w* is provided, it
specifies the width of the date columns, which are centered. If *l* is given, it
specifies the number of lines that each week will use. Depends on the first
weekday as set by :func:`setfirstweekday`.
.. method:: TextCalendar.prmonth(theyear, themonth[, w[, l]])
Print a month's calendar as returned by :meth:`formatmonth`.
.. method:: TextCalendar.formatyear(theyear, themonth[, w[, l[, c[, m]]]])
Return a *m*-column calendar for an entire year as a multi-line string. Optional
parameters *w*, *l*, and *c* are for date column width, lines per week, and
number of spaces between month columns, respectively. Depends on the first
weekday as set by :meth:`setfirstweekday`. The earliest year for which a
calendar can be generated is platform-dependent.
.. method:: TextCalendar.pryear(theyear[, w[, l[, c[, m]]]])
Print the calendar for an entire year as returned by :meth:`formatyear`.
.. class:: HTMLCalendar([firstweekday])
This class can be used to generate HTML calendars.
.. versionadded:: 2.5
:class:`HTMLCalendar` instances have the following methods:
.. method:: HTMLCalendar.formatmonth(theyear, themonth[, withyear])
Return a month's calendar as an HTML table. If *withyear* is true the year will
be included in the header, otherwise just the month name will be used.
.. method:: HTMLCalendar.formatyear(theyear, themonth[, width])
Return a year's calendar as an HTML table. *width* (defaulting to 3) specifies
the number of months per row.
.. method:: HTMLCalendar.formatyearpage(theyear, themonth[, width[, css[, encoding]]])
Return a year's calendar as a complete HTML page. *width* (defaulting to 3)
specifies the number of months per row. *css* is the name for the cascading
style sheet to be used. :const:`None` can be passed if no style sheet should be
used. *encoding* specifies the encoding to be used for the output (defaulting to
the system default encoding).
.. class:: LocaleTextCalendar([firstweekday[, locale]])
This subclass of :class:`TextCalendar` can be passed a locale name in the
constructor and will return month and weekday names in the specified locale. If
this locale includes an encoding all strings containing month and weekday names
will be returned as unicode.
.. versionadded:: 2.5
.. class:: LocaleHTMLCalendar([firstweekday[, locale]])
This subclass of :class:`HTMLCalendar` can be passed a locale name in the
constructor and will return month and weekday names in the specified locale. If
this locale includes an encoding all strings containing month and weekday names
will be returned as unicode.
.. versionadded:: 2.5
For simple text calendars this module provides the following functions.
.. function:: setfirstweekday(weekday)
Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The
values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`,
:const:`FRIDAY`, :const:`SATURDAY`, and :const:`SUNDAY` are provided for
convenience. For example, to set the first weekday to Sunday::
import calendar
calendar.setfirstweekday(calendar.SUNDAY)
.. versionadded:: 2.0
.. function:: firstweekday()
Returns the current setting for the weekday to start each week.
.. versionadded:: 2.0
.. function:: isleap(year)
Returns :const:`True` if *year* is a leap year, otherwise :const:`False`.
.. function:: leapdays(y1, y2)
Returns the number of leap years in the range [*y1*...*y2*), where *y1* and *y2*
are years.
.. versionchanged:: 2.0
This function didn't work for ranges spanning a century change in Python 1.5.2.
.. function:: weekday(year, month, day)
Returns the day of the week (``0`` is Monday) for *year* (``1970``\ --...),
*month* (``1``\ --\ ``12``), *day* (``1``\ --\ ``31``).
.. function:: weekheader(n)
Return a header containing abbreviated weekday names. *n* specifies the width in
characters for one weekday.
.. function:: monthrange(year, month)
Returns weekday of first day of the month and number of days in month, for the
specified *year* and *month*.
.. function:: monthcalendar(year, month)
Returns a matrix representing a month's calendar. Each row represents a week;
days outside of the month a represented by zeros. Each week begins with Monday
unless set by :func:`setfirstweekday`.
.. function:: prmonth(theyear, themonth[, w[, l]])
Prints a month's calendar as returned by :func:`month`.
.. function:: month(theyear, themonth[, w[, l]])
Returns a month's calendar in a multi-line string using the :meth:`formatmonth`
of the :class:`TextCalendar` class.
.. versionadded:: 2.0
.. function:: prcal(year[, w[, l[c]]])
Prints the calendar for an entire year as returned by :func:`calendar`.
.. function:: calendar(year[, w[, l[c]]])
Returns a 3-column calendar for an entire year as a multi-line string using the
:meth:`formatyear` of the :class:`TextCalendar` class.
.. versionadded:: 2.0
.. function:: timegm(tuple)
An unrelated but handy function that takes a time tuple such as returned by the
:func:`gmtime` function in the :mod:`time` module, and returns the corresponding
Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In
fact, :func:`time.gmtime` and :func:`timegm` are each others' inverse.
.. versionadded:: 2.0
The :mod:`calendar` module exports the following data attributes:
.. data:: day_name
An array that represents the days of the week in the current locale.
.. data:: day_abbr
An array that represents the abbreviated days of the week in the current locale.
.. data:: month_name
An array that represents the months of the year in the current locale. This
follows normal convention of January being month number 1, so it has a length of
13 and ``month_name[0]`` is the empty string.
.. data:: month_abbr
An array that represents the abbreviated months of the year in the current
locale. This follows normal convention of January being month number 1, so it
has a length of 13 and ``month_abbr[0]`` is the empty string.
.. seealso::
Module :mod:`datetime`
Object-oriented interface to dates and times with similar functionality to the
:mod:`time` module.
Module :mod:`time`
Low-level time related functions.

562
Doc-3k/library/cgi.rst Normal file
View File

@@ -0,0 +1,562 @@
:mod:`cgi` --- Common Gateway Interface support.
================================================
.. module:: cgi
.. index::
pair: WWW; server
pair: CGI; protocol
pair: HTTP; protocol
pair: MIME; headers
single: URL
.. index:: single: Common Gateway Interface
Support module for Common Gateway Interface (CGI) scripts.
.. %
This module defines a number of utilities for use by CGI scripts written in
Python.
Introduction
------------
.. _cgi-intro:
A CGI script is invoked by an HTTP server, usually to process user input
submitted through an HTML ``<FORM>`` or ``<ISINDEX>`` element.
Most often, CGI scripts live in the server's special :file:`cgi-bin` directory.
The HTTP server places all sorts of information about the request (such as the
client's hostname, the requested URL, the query string, and lots of other
goodies) in the script's shell environment, executes the script, and sends the
script's output back to the client.
The script's input is connected to the client too, and sometimes the form data
is read this way; at other times the form data is passed via the "query string"
part of the URL. This module is intended to take care of the different cases
and provide a simpler interface to the Python script. It also provides a number
of utilities that help in debugging scripts, and the latest addition is support
for file uploads from a form (if your browser supports it).
The output of a CGI script should consist of two sections, separated by a blank
line. The first section contains a number of headers, telling the client what
kind of data is following. Python code to generate a minimal header section
looks like this::
print "Content-Type: text/html" # HTML is following
print # blank line, end of headers
The second section is usually HTML, which allows the client software to display
nicely formatted text with header, in-line images, etc. Here's Python code that
prints a simple piece of HTML::
print "<TITLE>CGI script output</TITLE>"
print "<H1>This is my first CGI script</H1>"
print "Hello, world!"
Using the cgi module
--------------------
.. _using the cgi module:
Begin by writing ``import cgi``. Do not use ``from cgi import *`` --- the
module defines all sorts of names for its own use or for backward compatibility
that you don't want in your namespace.
When you write a new script, consider adding the line::
import cgitb; cgitb.enable()
This activates a special exception handler that will display detailed reports in
the Web browser if any errors occur. If you'd rather not show the guts of your
program to users of your script, you can have the reports saved to files
instead, with a line like this::
import cgitb; cgitb.enable(display=0, logdir="/tmp")
It's very helpful to use this feature during script development. The reports
produced by :mod:`cgitb` provide information that can save you a lot of time in
tracking down bugs. You can always remove the ``cgitb`` line later when you
have tested your script and are confident that it works correctly.
To get at submitted form data, it's best to use the :class:`FieldStorage` class.
The other classes defined in this module are provided mostly for backward
compatibility. Instantiate it exactly once, without arguments. This reads the
form contents from standard input or the environment (depending on the value of
various environment variables set according to the CGI standard). Since it may
consume standard input, it should be instantiated only once.
The :class:`FieldStorage` instance can be indexed like a Python dictionary, and
also supports the standard dictionary methods :meth:`has_key` and :meth:`keys`.
The built-in :func:`len` is also supported. Form fields containing empty
strings are ignored and do not appear in the dictionary; to keep such values,
provide a true value for the optional *keep_blank_values* keyword parameter when
creating the :class:`FieldStorage` instance.
For instance, the following code (which assumes that the
:mailheader:`Content-Type` header and blank line have already been printed)
checks that the fields ``name`` and ``addr`` are both set to a non-empty
string::
form = cgi.FieldStorage()
if not (form.has_key("name") and form.has_key("addr")):
print "<H1>Error</H1>"
print "Please fill in the name and addr fields."
return
print "<p>name:", form["name"].value
print "<p>addr:", form["addr"].value
...further form processing here...
Here the fields, accessed through ``form[key]``, are themselves instances of
:class:`FieldStorage` (or :class:`MiniFieldStorage`, depending on the form
encoding). The :attr:`value` attribute of the instance yields the string value
of the field. The :meth:`getvalue` method returns this string value directly;
it also accepts an optional second argument as a default to return if the
requested key is not present.
If the submitted form data contains more than one field with the same name, the
object retrieved by ``form[key]`` is not a :class:`FieldStorage` or
:class:`MiniFieldStorage` instance but a list of such instances. Similarly, in
this situation, ``form.getvalue(key)`` would return a list of strings. If you
expect this possibility (when your HTML form contains multiple fields with the
same name), use the :func:`getlist` function, which always returns a list of
values (so that you do not need to special-case the single item case). For
example, this code concatenates any number of username fields, separated by
commas::
value = form.getlist("username")
usernames = ",".join(value)
If a field represents an uploaded file, accessing the value via the
:attr:`value` attribute or the :func:`getvalue` method reads the entire file in
memory as a string. This may not be what you want. You can test for an uploaded
file by testing either the :attr:`filename` attribute or the :attr:`file`
attribute. You can then read the data at leisure from the :attr:`file`
attribute::
fileitem = form["userfile"]
if fileitem.file:
# It's an uploaded file; count lines
linecount = 0
while 1:
line = fileitem.file.readline()
if not line: break
linecount = linecount + 1
The file upload draft standard entertains the possibility of uploading multiple
files from one field (using a recursive :mimetype:`multipart/\*` encoding).
When this occurs, the item will be a dictionary-like :class:`FieldStorage` item.
This can be determined by testing its :attr:`type` attribute, which should be
:mimetype:`multipart/form-data` (or perhaps another MIME type matching
:mimetype:`multipart/\*`). In this case, it can be iterated over recursively
just like the top-level form object.
When a form is submitted in the "old" format (as the query string or as a single
data part of type :mimetype:`application/x-www-form-urlencoded`), the items will
actually be instances of the class :class:`MiniFieldStorage`. In this case, the
:attr:`list`, :attr:`file`, and :attr:`filename` attributes are always ``None``.
Higher Level Interface
----------------------
.. versionadded:: 2.2
The previous section explains how to read CGI form data using the
:class:`FieldStorage` class. This section describes a higher level interface
which was added to this class to allow one to do it in a more readable and
intuitive way. The interface doesn't make the techniques described in previous
sections obsolete --- they are still useful to process file uploads efficiently,
for example.
.. % XXX: Is this true ?
The interface consists of two simple methods. Using the methods you can process
form data in a generic way, without the need to worry whether only one or more
values were posted under one name.
In the previous section, you learned to write following code anytime you
expected a user to post more than one value under one name::
item = form.getvalue("item")
if isinstance(item, list):
# The user is requesting more than one item.
else:
# The user is requesting only one item.
This situation is common for example when a form contains a group of multiple
checkboxes with the same name::
<input type="checkbox" name="item" value="1" />
<input type="checkbox" name="item" value="2" />
In most situations, however, there's only one form control with a particular
name in a form and then you expect and need only one value associated with this
name. So you write a script containing for example this code::
user = form.getvalue("user").upper()
The problem with the code is that you should never expect that a client will
provide valid input to your scripts. For example, if a curious user appends
another ``user=foo`` pair to the query string, then the script would crash,
because in this situation the ``getvalue("user")`` method call returns a list
instead of a string. Calling the :meth:`toupper` method on a list is not valid
(since lists do not have a method of this name) and results in an
:exc:`AttributeError` exception.
Therefore, the appropriate way to read form data values was to always use the
code which checks whether the obtained value is a single value or a list of
values. That's annoying and leads to less readable scripts.
A more convenient approach is to use the methods :meth:`getfirst` and
:meth:`getlist` provided by this higher level interface.
.. method:: FieldStorage.getfirst(name[, default])
This method always returns only one value associated with form field *name*.
The method returns only the first value in case that more values were posted
under such name. Please note that the order in which the values are received
may vary from browser to browser and should not be counted on. [#]_ If no such
form field or value exists then the method returns the value specified by the
optional parameter *default*. This parameter defaults to ``None`` if not
specified.
.. method:: FieldStorage.getlist(name)
This method always returns a list of values associated with form field *name*.
The method returns an empty list if no such form field or value exists for
*name*. It returns a list consisting of one item if only one such value exists.
Using these methods you can write nice compact code::
import cgi
form = cgi.FieldStorage()
user = form.getfirst("user", "").upper() # This way it's safe.
for item in form.getlist("item"):
do_something(item)
Old classes
-----------
These classes, present in earlier versions of the :mod:`cgi` module, are still
supported for backward compatibility. New applications should use the
:class:`FieldStorage` class.
:class:`SvFormContentDict` stores single value form content as dictionary; it
assumes each field name occurs in the form only once.
:class:`FormContentDict` stores multiple value form content as a dictionary (the
form items are lists of values). Useful if your form contains multiple fields
with the same name.
Other classes (:class:`FormContent`, :class:`InterpFormContentDict`) are present
for backwards compatibility with really old applications only. If you still use
these and would be inconvenienced when they disappeared from a next version of
this module, drop me a note.
Functions
---------
.. _functions in cgi module:
These are useful if you want more control, or if you want to employ some of the
algorithms implemented in this module in other circumstances.
.. function:: parse(fp[, keep_blank_values[, strict_parsing]])
Parse a query in the environment or from a file (the file defaults to
``sys.stdin``). The *keep_blank_values* and *strict_parsing* parameters are
passed to :func:`parse_qs` unchanged.
.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing]])
Parse a query string given as a string argument (data of type
:mimetype:`application/x-www-form-urlencoded`). Data are returned as a
dictionary. The dictionary keys are the unique query variable names and the
values are lists of values for each name.
The optional argument *keep_blank_values* is a flag indicating whether blank
values in URL encoded queries should be treated as blank strings. A true value
indicates that blanks should be retained as blank strings. The default false
value indicates that blank values are to be ignored and treated as if they were
not included.
The optional argument *strict_parsing* is a flag indicating what to do with
parsing errors. If false (the default), errors are silently ignored. If true,
errors raise a :exc:`ValueError` exception.
Use the :func:`urllib.urlencode` function to convert such dictionaries into
query strings.
.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing]])
Parse a query string given as a string argument (data of type
:mimetype:`application/x-www-form-urlencoded`). Data are returned as a list of
name, value pairs.
The optional argument *keep_blank_values* is a flag indicating whether blank
values in URL encoded queries should be treated as blank strings. A true value
indicates that blanks should be retained as blank strings. The default false
value indicates that blank values are to be ignored and treated as if they were
not included.
The optional argument *strict_parsing* is a flag indicating what to do with
parsing errors. If false (the default), errors are silently ignored. If true,
errors raise a :exc:`ValueError` exception.
Use the :func:`urllib.urlencode` function to convert such lists of pairs into
query strings.
.. function:: parse_multipart(fp, pdict)
Parse input of type :mimetype:`multipart/form-data` (for file uploads).
Arguments are *fp* for the input file and *pdict* for a dictionary containing
other parameters in the :mailheader:`Content-Type` header.
Returns a dictionary just like :func:`parse_qs` keys are the field names, each
value is a list of values for that field. This is easy to use but not much good
if you are expecting megabytes to be uploaded --- in that case, use the
:class:`FieldStorage` class instead which is much more flexible.
Note that this does not parse nested multipart parts --- use
:class:`FieldStorage` for that.
.. function:: parse_header(string)
Parse a MIME header (such as :mailheader:`Content-Type`) into a main value and a
dictionary of parameters.
.. function:: test()
Robust test CGI script, usable as main program. Writes minimal HTTP headers and
formats all information provided to the script in HTML form.
.. function:: print_environ()
Format the shell environment in HTML.
.. function:: print_form(form)
Format a form in HTML.
.. function:: print_directory()
Format the current directory in HTML.
.. function:: print_environ_usage()
Print a list of useful (used by CGI) environment variables in HTML.
.. function:: escape(s[, quote])
Convert the characters ``'&'``, ``'<'`` and ``'>'`` in string *s* to HTML-safe
sequences. Use this if you need to display text that might contain such
characters in HTML. If the optional flag *quote* is true, the quotation mark
character (``'"'``) is also translated; this helps for inclusion in an HTML
attribute value, as in ``<A HREF="...">``. If the value to be quoted might
include single- or double-quote characters, or both, consider using the
:func:`quoteattr` function in the :mod:`xml.sax.saxutils` module instead.
.. _cgi-security:
Caring about security
---------------------
.. index:: pair: CGI; security
There's one important rule: if you invoke an external program (via the
:func:`os.system` or :func:`os.popen` functions. or others with similar
functionality), make very sure you don't pass arbitrary strings received from
the client to the shell. This is a well-known security hole whereby clever
hackers anywhere on the Web can exploit a gullible CGI script to invoke
arbitrary shell commands. Even parts of the URL or field names cannot be
trusted, since the request doesn't have to come from your form!
To be on the safe side, if you must pass a string gotten from a form to a shell
command, you should make sure the string contains only alphanumeric characters,
dashes, underscores, and periods.
Installing your CGI script on a Unix system
-------------------------------------------
Read the documentation for your HTTP server and check with your local system
administrator to find the directory where CGI scripts should be installed;
usually this is in a directory :file:`cgi-bin` in the server tree.
Make sure that your script is readable and executable by "others"; the Unix file
mode should be ``0755`` octal (use ``chmod 0755 filename``). Make sure that the
first line of the script contains ``#!`` starting in column 1 followed by the
pathname of the Python interpreter, for instance::
#!/usr/local/bin/python
Make sure the Python interpreter exists and is executable by "others".
Make sure that any files your script needs to read or write are readable or
writable, respectively, by "others" --- their mode should be ``0644`` for
readable and ``0666`` for writable. This is because, for security reasons, the
HTTP server executes your script as user "nobody", without any special
privileges. It can only read (write, execute) files that everybody can read
(write, execute). The current directory at execution time is also different (it
is usually the server's cgi-bin directory) and the set of environment variables
is also different from what you get when you log in. In particular, don't count
on the shell's search path for executables (:envvar:`PATH`) or the Python module
search path (:envvar:`PYTHONPATH`) to be set to anything interesting.
If you need to load modules from a directory which is not on Python's default
module search path, you can change the path in your script, before importing
other modules. For example::
import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")
(This way, the directory inserted last will be searched first!)
Instructions for non-Unix systems will vary; check your HTTP server's
documentation (it will usually have a section on CGI scripts).
Testing your CGI script
-----------------------
Unfortunately, a CGI script will generally not run when you try it from the
command line, and a script that works perfectly from the command line may fail
mysteriously when run from the server. There's one reason why you should still
test your script from the command line: if it contains a syntax error, the
Python interpreter won't execute it at all, and the HTTP server will most likely
send a cryptic error to the client.
Assuming your script has no syntax errors, yet it does not work, you have no
choice but to read the next section.
Debugging CGI scripts
---------------------
.. index:: pair: CGI; debugging
First of all, check for trivial installation errors --- reading the section
above on installing your CGI script carefully can save you a lot of time. If
you wonder whether you have understood the installation procedure correctly, try
installing a copy of this module file (:file:`cgi.py`) as a CGI script. When
invoked as a script, the file will dump its environment and the contents of the
form in HTML form. Give it the right mode etc, and send it a request. If it's
installed in the standard :file:`cgi-bin` directory, it should be possible to
send it a request by entering a URL into your browser of the form::
http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
If this gives an error of type 404, the server cannot find the script -- perhaps
you need to install it in a different directory. If it gives another error,
there's an installation problem that you should fix before trying to go any
further. If you get a nicely formatted listing of the environment and form
content (in this example, the fields should be listed as "addr" with value "At
Home" and "name" with value "Joe Blow"), the :file:`cgi.py` script has been
installed correctly. If you follow the same procedure for your own script, you
should now be able to debug it.
The next step could be to call the :mod:`cgi` module's :func:`test` function
from your script: replace its main code with the single statement ::
cgi.test()
This should produce the same results as those gotten from installing the
:file:`cgi.py` file itself.
When an ordinary Python script raises an unhandled exception (for whatever
reason: of a typo in a module name, a file that can't be opened, etc.), the
Python interpreter prints a nice traceback and exits. While the Python
interpreter will still do this when your CGI script raises an exception, most
likely the traceback will end up in one of the HTTP server's log files, or be
discarded altogether.
Fortunately, once you have managed to get your script to execute *some* code,
you can easily send tracebacks to the Web browser using the :mod:`cgitb` module.
If you haven't done so already, just add the line::
import cgitb; cgitb.enable()
to the top of your script. Then try running it again; when a problem occurs,
you should see a detailed report that will likely make apparent the cause of the
crash.
If you suspect that there may be a problem in importing the :mod:`cgitb` module,
you can use an even more robust approach (which only uses built-in modules)::
import sys
sys.stderr = sys.stdout
print "Content-Type: text/plain"
print
...your code here...
This relies on the Python interpreter to print the traceback. The content type
of the output is set to plain text, which disables all HTML processing. If your
script works, the raw HTML will be displayed by your client. If it raises an
exception, most likely after the first two lines have been printed, a traceback
will be displayed. Because no HTML interpretation is going on, the traceback
will be readable.
Common problems and solutions
-----------------------------
* Most HTTP servers buffer the output from CGI scripts until the script is
completed. This means that it is not possible to display a progress report on
the client's display while the script is running.
* Check the installation instructions above.
* Check the HTTP server's log files. (``tail -f logfile`` in a separate window
may be useful!)
* Always check a script for syntax errors first, by doing something like
``python script.py``.
* If your script does not have any syntax errors, try adding ``import cgitb;
cgitb.enable()`` to the top of the script.
* When invoking external programs, make sure they can be found. Usually, this
means using absolute path names --- :envvar:`PATH` is usually not set to a very
useful value in a CGI script.
* When reading or writing external files, make sure they can be read or written
by the userid under which your CGI script will be running: this is typically the
userid under which the web server is running, or some explicitly specified
userid for a web server's ``suexec`` feature.
* Don't try to give a CGI script a set-uid mode. This doesn't work on most
systems, and is a security liability as well.
.. rubric:: Footnotes
.. [#] Note that some recent versions of the HTML specification do state what order the
field values should be supplied in, but knowing whether a request was received
from a conforming browser, or even from a browser at all, is tedious and error-
prone.

73
Doc-3k/library/cgihttpserver.rst Normal file
View File

@@ -0,0 +1,73 @@
:mod:`CGIHTTPServer` --- CGI-capable HTTP request handler
=========================================================
.. module:: CGIHTTPServer
:synopsis: This module provides a request handler for HTTP servers which can run CGI
scripts.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`CGIHTTPServer` module defines a request-handler class, interface
compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler` and inherits
behavior from :class:`SimpleHTTPServer.SimpleHTTPRequestHandler` but can also
run CGI scripts.
.. note::
This module can run CGI scripts on Unix and Windows systems; on Mac OS it will
only be able to run Python scripts within the same process as itself.
.. note::
CGI scripts run by the :class:`CGIHTTPRequestHandler` class cannot execute
redirects (HTTP code 302), because code 200 (script output follows) is sent
prior to execution of the CGI script. This pre-empts the status code.
The :mod:`CGIHTTPServer` module defines the following class:
.. class:: CGIHTTPRequestHandler(request, client_address, server)
This class is used to serve either files or output of CGI scripts from the
current directory and below. Note that mapping HTTP hierarchic structure to
local directory structure is exactly as in
:class:`SimpleHTTPServer.SimpleHTTPRequestHandler`.
The class will however, run the CGI script, instead of serving it as a file, if
it guesses it to be a CGI script. Only directory-based CGI are used --- the
other common server configuration is to treat special extensions as denoting CGI
scripts.
The :func:`do_GET` and :func:`do_HEAD` functions are modified to run CGI scripts
and serve the output, instead of serving files, if the request leads to
somewhere below the ``cgi_directories`` path.
The :class:`CGIHTTPRequestHandler` defines the following data member:
.. attribute:: CGIHTTPRequestHandler.cgi_directories
This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to treat
as containing CGI scripts.
The :class:`CGIHTTPRequestHandler` defines the following methods:
.. method:: CGIHTTPRequestHandler.do_POST()
This method serves the ``'POST'`` request type, only allowed for CGI scripts.
Error 501, "Can only POST to CGI scripts", is output when trying to POST to a
non-CGI url.
Note that CGI scripts will be run with UID of user nobody, for security reasons.
Problems with the CGI script will be translated to error 403.
For example usage, see the implementation of the :func:`test` function.
.. seealso::
Module :mod:`BaseHTTPServer`
Base class implementation for Web server and request handler.

64
Doc-3k/library/cgitb.rst Normal file
View File

@@ -0,0 +1,64 @@
:mod:`cgitb` --- Traceback manager for CGI scripts
==================================================
.. module:: cgitb
:synopsis: Configurable traceback handler for CGI scripts.
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. versionadded:: 2.2
.. index::
single: CGI; exceptions
single: CGI; tracebacks
single: exceptions; in CGI scripts
single: tracebacks; in CGI scripts
The :mod:`cgitb` module provides a special exception handler for Python scripts.
(Its name is a bit misleading. It was originally designed to display extensive
traceback information in HTML for CGI scripts. It was later generalized to also
display this information in plain text.) After this module is activated, if an
uncaught exception occurs, a detailed, formatted report will be displayed. The
report includes a traceback showing excerpts of the source code for each level,
as well as the values of the arguments and local variables to currently running
functions, to help you debug the problem. Optionally, you can save this
information to a file instead of sending it to the browser.
To enable this feature, simply add one line to the top of your CGI script::
import cgitb; cgitb.enable()
The options to the :func:`enable` function control whether the report is
displayed in the browser and whether the report is logged to a file for later
analysis.
.. function:: enable([display[, logdir[, context[, format]]]])
.. index:: single: excepthook() (in module sys)
This function causes the :mod:`cgitb` module to take over the interpreter's
default handling for exceptions by setting the value of :attr:`sys.excepthook`.
The optional argument *display* defaults to ``1`` and can be set to ``0`` to
suppress sending the traceback to the browser. If the argument *logdir* is
present, the traceback reports are written to files. The value of *logdir*
should be a directory where these files will be placed. The optional argument
*context* is the number of lines of context to display around the current line
of source code in the traceback; this defaults to ``5``. If the optional
argument *format* is ``"html"``, the output is formatted as HTML. Any other
value forces plain text output. The default value is ``"html"``.
.. function:: handler([info])
This function handles an exception using the default settings (that is, show a
report in the browser, but don't log to a file). This can be used when you've
caught an exception and want to report it using :mod:`cgitb`. The optional
*info* argument should be a 3-tuple containing an exception type, exception
value, and traceback object, exactly like the tuple returned by
:func:`sys.exc_info`. If the *info* argument is not supplied, the current
exception is obtained from :func:`sys.exc_info`.

130
Doc-3k/library/chunk.rst Normal file
View File

@@ -0,0 +1,130 @@
:mod:`chunk` --- Read IFF chunked data
======================================
.. module:: chunk
:synopsis: Module to read IFF chunks.
.. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org>
.. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org>
.. index::
single: Audio Interchange File Format
single: AIFF
single: AIFF-C
single: Real Media File Format
single: RMFF
This module provides an interface for reading files that use EA IFF 85 chunks.
[#]_ 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 :class:`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 :exc:`EOFError` exception.
.. class:: 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 :meth:`read`. If the methods :meth:`seek` and
:meth:`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 :class:`Chunk` object supports the following methods:
.. method:: Chunk.getname()
Returns the name (ID) of the chunk. This is the first 4 bytes of the chunk.
.. method:: Chunk.getsize()
Returns the size of the chunk.
.. method:: Chunk.close()
Close and skip to the end of the chunk. This does not close the underlying
file.
The remaining methods will raise :exc:`IOError` if called after the
:meth:`close` method has been called.
.. method:: Chunk.isatty()
Returns ``False``.
.. method:: Chunk.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.
.. method:: Chunk.tell()
Return the current position into the chunk.
.. method:: 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.
.. method:: Chunk.skip()
Skip to the end of the chunk. All further calls to :meth:`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.
.. rubric:: Footnotes
.. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic
Arts, January 1985.

155
Doc-3k/library/cmath.rst Normal file
View File

@@ -0,0 +1,155 @@
:mod:`cmath` --- Mathematical functions for complex numbers
===========================================================
.. module:: cmath
:synopsis: Mathematical functions for complex numbers.
This module is always available. It provides access to mathematical functions
for complex numbers. The functions in this module accept integers, floating-
point numbers or complex numbers as arguments. They will also accept any Python
object that has either a :meth:`__complex__` or a :meth:`__float__` method:
these methods are used to convert the object to a complex or floating-point
number, respectively, and the function is then applied to the result of the
conversion.
The functions are:
.. function:: acos(x)
Return the arc cosine of *x*. There are two branch cuts: One extends right from
1 along the real axis to ∞, continuous from below. The other extends left from
-1 along the real axis to -∞, continuous from above.
.. function:: acosh(x)
Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
from 1 along the real axis to -∞, continuous from above.
.. function:: asin(x)
Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
.. function:: asinh(x)
Return the hyperbolic arc sine of *x*. There are two branch cuts, extending left
from ±``1j`` to ±-∞``j``, both continuous from above. These branch cuts should
be considered a bug to be corrected in a future release. The correct branch cuts
should extend along the imaginary axis, one from ``1j`` up to ∞``j`` and
continuous from the right, and one from -\ ``1j`` down to -∞``j`` and continuous
from the left.
.. function:: atan(x)
Return the arc tangent of *x*. There are two branch cuts: One extends from
``1j`` along the imaginary axis to ∞``j``, continuous from the left. The other
extends from -\ ``1j`` along the imaginary axis to -∞``j``, continuous from the
left. (This should probably be changed so the upper cut becomes continuous from
the other side.)
.. function:: atanh(x)
Return the hyperbolic arc tangent of *x*. There are two branch cuts: One extends
from 1 along the real axis to ∞, continuous from above. The other extends from
-1 along the real axis to -∞, continuous from above. (This should probably be
changed so the right cut becomes continuous from the other side.)
.. function:: cos(x)
Return the cosine of *x*.
.. function:: cosh(x)
Return the hyperbolic cosine of *x*.
.. function:: exp(x)
Return the exponential value ``e**x``.
.. function:: log(x[, base])
Returns the logarithm of *x* to the given *base*. If the *base* is not
specified, returns the natural logarithm of *x*. There is one branch cut, from 0
along the negative real axis to -∞, continuous from above.
.. versionchanged:: 2.4
*base* argument added.
.. function:: log10(x)
Return the base-10 logarithm of *x*. This has the same branch cut as
:func:`log`.
.. function:: sin(x)
Return the sine of *x*.
.. function:: sinh(x)
Return the hyperbolic sine of *x*.
.. function:: sqrt(x)
Return the square root of *x*. This has the same branch cut as :func:`log`.
.. function:: tan(x)
Return the tangent of *x*.
.. function:: tanh(x)
Return the hyperbolic tangent of *x*.
The module also defines two mathematical constants:
.. data:: pi
The mathematical constant *pi*, as a real.
.. data:: e
The mathematical constant *e*, as a real.
.. index:: module: math
Note that the selection of functions is similar, but not identical, to that in
module :mod:`math`. The reason for having two modules is that some users aren't
interested in complex numbers, and perhaps don't even know what they are. They
would rather have ``math.sqrt(-1)`` raise an exception than return a complex
number. Also note that the functions defined in :mod:`cmath` always return a
complex number, even if the answer can be expressed as a real number (in which
case the complex number has an imaginary part of zero).
A note on branch cuts: They are curves along which the given function fails to
be continuous. They are a necessary feature of many complex functions. It is
assumed that if you need to compute with complex functions, you will understand
about branch cuts. Consult almost any (not too elementary) book on complex
variables for enlightenment. For information of the proper choice of branch
cuts for numerical purposes, a good reference should be the following:
.. seealso::
Kahan, W: Branch cuts for complex elementary functions; or, Much ado about
nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art
in numerical analysis. Clarendon Press (1987) pp165-211.

202
Doc-3k/library/cmd.rst Normal file
View File

@@ -0,0 +1,202 @@
:mod:`cmd` --- Support for line-oriented command interpreters
=============================================================
.. module:: cmd
:synopsis: Build line-oriented command interpreters.
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
The :class:`Cmd` class provides a simple framework for writing line-oriented
command interpreters. These are often useful for test harnesses, administrative
tools, and prototypes that will later be wrapped in a more sophisticated
interface.
.. class:: Cmd([completekey[, stdin[, stdout]]])
A :class:`Cmd` instance or subclass instance is a line-oriented interpreter
framework. There is no good reason to instantiate :class:`Cmd` itself; rather,
it's useful as a superclass of an interpreter class you define yourself in order
to inherit :class:`Cmd`'s methods and encapsulate action methods.
The optional argument *completekey* is the :mod:`readline` name of a completion
key; it defaults to :kbd:`Tab`. If *completekey* is not :const:`None` and
:mod:`readline` is available, command completion is done automatically.
The optional arguments *stdin* and *stdout* specify the input and output file
objects that the Cmd instance or subclass instance will use for input and
output. If not specified, they will default to *sys.stdin* and *sys.stdout*.
.. versionchanged:: 2.3
The *stdin* and *stdout* parameters were added.
.. _cmd-objects:
Cmd Objects
-----------
A :class:`Cmd` instance has the following methods:
.. method:: Cmd.cmdloop([intro])
Repeatedly issue a prompt, accept input, parse an initial prefix off the
received input, and dispatch to action methods, passing them the remainder of
the line as argument.
The optional argument is a banner or intro string to be issued before the first
prompt (this overrides the :attr:`intro` class member).
If the :mod:`readline` module is loaded, input will automatically inherit
:program:`bash`\ -like history-list editing (e.g. :kbd:`Control-P` scrolls back
to the last command, :kbd:`Control-N` forward to the next one, :kbd:`Control-F`
moves the cursor to the right non-destructively, :kbd:`Control-B` moves the
cursor to the left non-destructively, etc.).
An end-of-file on input is passed back as the string ``'EOF'``.
An interpreter instance will recognize a command name ``foo`` if and only if it
has a method :meth:`do_foo`. As a special case, a line beginning with the
character ``'?'`` is dispatched to the method :meth:`do_help`. As another
special case, a line beginning with the character ``'!'`` is dispatched to the
method :meth:`do_shell` (if such a method is defined).
This method will return when the :meth:`postcmd` method returns a true value.
The *stop* argument to :meth:`postcmd` is the return value from the command's
corresponding :meth:`do_\*` method.
If completion is enabled, completing commands will be done automatically, and
completing of commands args is done by calling :meth:`complete_foo` with
arguments *text*, *line*, *begidx*, and *endidx*. *text* is the string prefix
we are attempting to match: all returned matches must begin with it. *line* is
the current input line with leading whitespace removed, *begidx* and *endidx*
are the beginning and ending indexes of the prefix text, which could be used to
provide different completion depending upon which position the argument is in.
All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`. This
method, called with an argument ``'bar'``, invokes the corresponding method
:meth:`help_bar`. With no argument, :meth:`do_help` lists all available help
topics (that is, all commands with corresponding :meth:`help_\*` methods), and
also lists any undocumented commands.
.. method:: Cmd.onecmd(str)
Interpret the argument as though it had been typed in response to the prompt.
This may be overridden, but should not normally need to be; see the
:meth:`precmd` and :meth:`postcmd` methods for useful execution hooks. The
return value is a flag indicating whether interpretation of commands by the
interpreter should stop. If there is a :meth:`do_\*` method for the command
*str*, the return value of that method is returned, otherwise the return value
from the :meth:`default` method is returned.
.. method:: Cmd.emptyline()
Method called when an empty line is entered in response to the prompt. If this
method is not overridden, it repeats the last nonempty command entered.
.. method:: Cmd.default(line)
Method called on an input line when the command prefix is not recognized. If
this method is not overridden, it prints an error message and returns.
.. method:: Cmd.completedefault(text, line, begidx, endidx)
Method called to complete an input line when no command-specific
:meth:`complete_\*` method is available. By default, it returns an empty list.
.. method:: Cmd.precmd(line)
Hook method executed just before the command line *line* is interpreted, but
after the input prompt is generated and issued. This method is a stub in
:class:`Cmd`; it exists to be overridden by subclasses. The return value is
used as the command which will be executed by the :meth:`onecmd` method; the
:meth:`precmd` implementation may re-write the command or simply return *line*
unchanged.
.. method:: Cmd.postcmd(stop, line)
Hook method executed just after a command dispatch is finished. This method is
a stub in :class:`Cmd`; it exists to be overridden by subclasses. *line* is the
command line which was executed, and *stop* is a flag which indicates whether
execution will be terminated after the call to :meth:`postcmd`; this will be the
return value of the :meth:`onecmd` method. The return value of this method will
be used as the new value for the internal flag which corresponds to *stop*;
returning false will cause interpretation to continue.
.. method:: Cmd.preloop()
Hook method executed once when :meth:`cmdloop` is called. This method is a stub
in :class:`Cmd`; it exists to be overridden by subclasses.
.. method:: Cmd.postloop()
Hook method executed once when :meth:`cmdloop` is about to return. This method
is a stub in :class:`Cmd`; it exists to be overridden by subclasses.
Instances of :class:`Cmd` subclasses have some public instance variables:
.. attribute:: Cmd.prompt
The prompt issued to solicit input.
.. attribute:: Cmd.identchars
The string of characters accepted for the command prefix.
.. attribute:: Cmd.lastcmd
The last nonempty command prefix seen.
.. attribute:: Cmd.intro
A string to issue as an intro or banner. May be overridden by giving the
:meth:`cmdloop` method an argument.
.. attribute:: Cmd.doc_header
The header to issue if the help output has a section for documented commands.
.. attribute:: Cmd.misc_header
The header to issue if the help output has a section for miscellaneous help
topics (that is, there are :meth:`help_\*` methods without corresponding
:meth:`do_\*` methods).
.. attribute:: Cmd.undoc_header
The header to issue if the help output has a section for undocumented commands
(that is, there are :meth:`do_\*` methods without corresponding :meth:`help_\*`
methods).
.. attribute:: Cmd.ruler
The character used to draw separator lines under the help-message headers. If
empty, no ruler line is drawn. It defaults to ``'='``.
.. attribute:: Cmd.use_rawinput
A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`input` to
display a prompt and read the next command; if false, :meth:`sys.stdout.write`
and :meth:`sys.stdin.readline` are used. (This means that by importing
:mod:`readline`, on systems that support it, the interpreter will automatically
support :program:`Emacs`\ -like line editing and command-history keystrokes.)

167
Doc-3k/library/code.rst Normal file
View File

@@ -0,0 +1,167 @@
:mod:`code` --- Interpreter base classes
========================================
.. module:: code
The ``code`` module provides facilities to implement read-eval-print loops in
Python. Two classes and convenience functions are included which can be used to
build applications which provide an interactive interpreter prompt.
.. class:: InteractiveInterpreter([locals])
This class deals with parsing and interpreter state (the user's namespace); it
does not deal with input buffering or prompting or input file naming (the
filename is always passed in explicitly). The optional *locals* argument
specifies the dictionary in which code will be executed; it defaults to a newly
created dictionary with key ``'__name__'`` set to ``'__console__'`` and key
``'__doc__'`` set to ``None``.
.. class:: InteractiveConsole([locals[, filename]])
Closely emulate the behavior of the interactive Python interpreter. This class
builds on :class:`InteractiveInterpreter` and adds prompting using the familiar
``sys.ps1`` and ``sys.ps2``, and input buffering.
.. function:: interact([banner[, readfunc[, local]]])
Convenience function to run a read-eval-print loop. This creates a new instance
of :class:`InteractiveConsole` and sets *readfunc* to be used as the
:meth:`raw_input` method, if provided. If *local* is provided, it is passed to
the :class:`InteractiveConsole` constructor for use as the default namespace for
the interpreter loop. The :meth:`interact` method of the instance is then run
with *banner* passed as the banner to use, if provided. The console object is
discarded after use.
.. function:: compile_command(source[, filename[, symbol]])
This function is useful for programs that want to emulate Python's interpreter
main loop (a.k.a. the read-eval-print loop). The tricky part is to determine
when the user has entered an incomplete command that can be completed by
entering more text (as opposed to a complete command or a syntax error). This
function *almost* always makes the same decision as the real interpreter main
loop.
*source* is the source string; *filename* is the optional filename from which
source was read, defaulting to ``'<input>'``; and *symbol* is the optional
grammar start symbol, which should be either ``'single'`` (the default) or
``'eval'``.
Returns a code object (the same as ``compile(source, filename, symbol)``) if the
command is complete and valid; ``None`` if the command is incomplete; raises
:exc:`SyntaxError` if the command is complete and contains a syntax error, or
raises :exc:`OverflowError` or :exc:`ValueError` if the command contains an
invalid literal.
.. _interpreter-objects:
Interactive Interpreter Objects
-------------------------------
.. method:: InteractiveInterpreter.runsource(source[, filename[, symbol]])
Compile and run some source in the interpreter. Arguments are the same as for
:func:`compile_command`; the default for *filename* is ``'<input>'``, and for
*symbol* is ``'single'``. One several things can happen:
* The input is incorrect; :func:`compile_command` raised an exception
(:exc:`SyntaxError` or :exc:`OverflowError`). A syntax traceback will be
printed by calling the :meth:`showsyntaxerror` method. :meth:`runsource`
returns ``False``.
* The input is incomplete, and more input is required; :func:`compile_command`
returned ``None``. :meth:`runsource` returns ``True``.
* The input is complete; :func:`compile_command` returned a code object. The
code is executed by calling the :meth:`runcode` (which also handles run-time
exceptions, except for :exc:`SystemExit`). :meth:`runsource` returns ``False``.
The return value can be used to decide whether to use ``sys.ps1`` or ``sys.ps2``
to prompt the next line.
.. method:: InteractiveInterpreter.runcode(code)
Execute a code object. When an exception occurs, :meth:`showtraceback` is called
to display a traceback. All exceptions are caught except :exc:`SystemExit`,
which is allowed to propagate.
A note about :exc:`KeyboardInterrupt`: this exception may occur elsewhere in
this code, and may not always be caught. The caller should be prepared to deal
with it.
.. method:: InteractiveInterpreter.showsyntaxerror([filename])
Display the syntax error that just occurred. This does not display a stack
trace because there isn't one for syntax errors. If *filename* is given, it is
stuffed into the exception instead of the default filename provided by Python's
parser, because it always uses ``'<string>'`` when reading from a string. The
output is written by the :meth:`write` method.
.. method:: InteractiveInterpreter.showtraceback()
Display the exception that just occurred. We remove the first stack item
because it is within the interpreter object implementation. The output is
written by the :meth:`write` method.
.. method:: InteractiveInterpreter.write(data)
Write a string to the standard error stream (``sys.stderr``). Derived classes
should override this to provide the appropriate output handling as needed.
.. _console-objects:
Interactive Console Objects
---------------------------
The :class:`InteractiveConsole` class is a subclass of
:class:`InteractiveInterpreter`, and so offers all the methods of the
interpreter objects as well as the following additions.
.. method:: InteractiveConsole.interact([banner])
Closely emulate the interactive Python console. The optional banner argument
specify the banner to print before the first interaction; by default it prints a
banner similar to the one printed by the standard Python interpreter, followed
by the class name of the console object in parentheses (so as not to confuse
this with the real interpreter -- since it's so close!).
.. method:: InteractiveConsole.push(line)
Push a line of source text to the interpreter. The line should not have a
trailing newline; it may have internal newlines. The line is appended to a
buffer and the interpreter's :meth:`runsource` method is called with the
concatenated contents of the buffer as source. If this indicates that the
command was executed or invalid, the buffer is reset; otherwise, the command is
incomplete, and the buffer is left as it was after the line was appended. The
return value is ``True`` if more input is required, ``False`` if the line was
dealt with in some way (this is the same as :meth:`runsource`).
.. method:: InteractiveConsole.resetbuffer()
Remove any unhandled source text from the input buffer.
.. method:: InteractiveConsole.raw_input([prompt])
Write a prompt and read a line. The returned line does not include the trailing
newline. When the user enters the EOF key sequence, :exc:`EOFError` is raised.
The base implementation reads from ``sys.stdin``; a subclass may replace this
with a different implementation.

1236
Doc-3k/library/codecs.rst Normal file
View File

File diff suppressed because it is too large Load Diff

94
Doc-3k/library/codeop.rst Normal file
View File

@@ -0,0 +1,94 @@
:mod:`codeop` --- Compile Python code
=====================================
.. module:: codeop
:synopsis: Compile (possibly incomplete) Python code.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. sectionauthor:: Michael Hudson <mwh@python.net>
.. % LaTeXed from excellent doc-string.
The :mod:`codeop` module provides utilities upon which the Python read-eval-
print loop can be emulated, as is done in the :mod:`code` module. As a result,
you probably don't want to use the module directly; if you want to include such
a loop in your program you probably want to use the :mod:`code` module instead.
There are two parts to this job:
#. Being able to tell if a line of input completes a Python statement: in
short, telling whether to print '``>>>``' or '``...``' next.
#. Remembering which future statements the user has entered, so subsequent
input can be compiled with these in effect.
The :mod:`codeop` module provides a way of doing each of these things, and a way
of doing them both.
To do just the former:
.. function:: compile_command(source[, filename[, symbol]])
Tries to compile *source*, which should be a string of Python code and return a
code object if *source* is valid Python code. In that case, the filename
attribute of the code object will be *filename*, which defaults to
``'<input>'``. Returns ``None`` if *source* is *not* valid Python code, but is a
prefix of valid Python code.
If there is a problem with *source*, an exception will be raised.
:exc:`SyntaxError` is raised if there is invalid Python syntax, and
:exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
The *symbol* argument determines whether *source* is compiled as a statement
(``'single'``, the default) or as an expression (``'eval'``). Any other value
will cause :exc:`ValueError` to be raised.
**Caveat:** It is possible (but not likely) that the parser stops parsing with a
successful outcome before reaching the end of the source; in this case, trailing
symbols may be ignored instead of causing an error. For example, a backslash
followed by two newlines may be followed by arbitrary garbage. This will be
fixed once the API for the parser is better.
.. class:: Compile()
Instances of this class have :meth:`__call__` methods identical in signature to
the built-in function :func:`compile`, but with the difference that if the
instance compiles program text containing a :mod:`__future__` statement, the
instance 'remembers' and compiles all subsequent program texts with the
statement in force.
.. class:: CommandCompiler()
Instances of this class have :meth:`__call__` methods identical in signature to
:func:`compile_command`; the difference is that if the instance compiles program
text containing a ``__future__`` statement, the instance 'remembers' and
compiles all subsequent program texts with the statement in force.
A note on version compatibility: the :class:`Compile` and
:class:`CommandCompiler` are new in Python 2.2. If you want to enable the
future-tracking features of 2.2 but also retain compatibility with 2.1 and
earlier versions of Python you can either write ::
try:
from codeop import CommandCompiler
compile_command = CommandCompiler()
del CommandCompiler
except ImportError:
from codeop import compile_command
which is a low-impact change, but introduces possibly unwanted global state into
your program, or you can write::
try:
from codeop import CommandCompiler
except ImportError:
def CommandCompiler():
from codeop import compile_command
return compile_command
and then call ``CommandCompiler`` every time you need a fresh compiler object.

408
Doc-3k/library/collections.rst Normal file
View File

@@ -0,0 +1,408 @@
:mod:`collections` --- High-performance container datatypes
===========================================================
.. module:: collections
:synopsis: High-performance datatypes
.. moduleauthor:: Raymond Hettinger <python@rcn.com>
.. sectionauthor:: Raymond Hettinger <python@rcn.com>
.. versionadded:: 2.4
This module implements high-performance container datatypes. Currently, there
are two datatypes, deque and defaultdict, and one datatype factory function,
:func:`NamedTuple`. Future additions may include balanced trees and ordered
dictionaries.
.. versionchanged:: 2.5
Added defaultdict.
.. versionchanged:: 2.6
Added NamedTuple.
.. _deque-objects:
:class:`deque` objects
----------------------
.. class:: deque([iterable])
Returns a new deque object initialized left-to-right (using :meth:`append`) with
data from *iterable*. If *iterable* is not specified, the new deque is empty.
Deques are a generalization of stacks and queues (the name is pronounced "deck"
and is short for "double-ended queue"). Deques support thread-safe, memory
efficient appends and pops from either side of the deque with approximately the
same ``O(1)`` performance in either direction.
Though :class:`list` objects support similar operations, they are optimized for
fast fixed-length operations and incur ``O(n)`` memory movement costs for
``pop(0)`` and ``insert(0, v)`` operations which change both the size and
position of the underlying data representation.
.. versionadded:: 2.4
Deque objects support the following methods:
.. method:: deque.append(x)
Add *x* to the right side of the deque.
.. method:: deque.appendleft(x)
Add *x* to the left side of the deque.
.. method:: deque.clear()
Remove all elements from the deque leaving it with length 0.
.. method:: deque.extend(iterable)
Extend the right side of the deque by appending elements from the iterable
argument.
.. method:: deque.extendleft(iterable)
Extend the left side of the deque by appending elements from *iterable*. Note,
the series of left appends results in reversing the order of elements in the
iterable argument.
.. method:: deque.pop()
Remove and return an element from the right side of the deque. If no elements
are present, raises an :exc:`IndexError`.
.. method:: deque.popleft()
Remove and return an element from the left side of the deque. If no elements are
present, raises an :exc:`IndexError`.
.. method:: deque.remove(value)
Removed the first occurrence of *value*. If not found, raises a
:exc:`ValueError`.
.. versionadded:: 2.5
.. method:: deque.rotate(n)
Rotate the deque *n* steps to the right. If *n* is negative, rotate to the
left. Rotating one step to the right is equivalent to:
``d.appendleft(d.pop())``.
In addition to the above, deques support iteration, pickling, ``len(d)``,
``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing with
the :keyword:`in` operator, and subscript references such as ``d[-1]``.
Example::
>>> from collections import deque
>>> d = deque('ghi') # make a new deque with three items
>>> for elem in d: # iterate over the deque's elements
... print elem.upper()
G
H
I
>>> d.append('j') # add a new entry to the right side
>>> d.appendleft('f') # add a new entry to the left side
>>> d # show the representation of the deque
deque(['f', 'g', 'h', 'i', 'j'])
>>> d.pop() # return and remove the rightmost item
'j'
>>> d.popleft() # return and remove the leftmost item
'f'
>>> list(d) # list the contents of the deque
['g', 'h', 'i']
>>> d[0] # peek at leftmost item
'g'
>>> d[-1] # peek at rightmost item
'i'
>>> list(reversed(d)) # list the contents of a deque in reverse
['i', 'h', 'g']
>>> 'h' in d # search the deque
True
>>> d.extend('jkl') # add multiple elements at once
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])
>>> d.rotate(1) # right rotation
>>> d
deque(['l', 'g', 'h', 'i', 'j', 'k'])
>>> d.rotate(-1) # left rotation
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])
>>> deque(reversed(d)) # make a new deque in reverse order
deque(['l', 'k', 'j', 'i', 'h', 'g'])
>>> d.clear() # empty the deque
>>> d.pop() # cannot pop from an empty deque
Traceback (most recent call last):
File "<pyshell#6>", line 1, in -toplevel-
d.pop()
IndexError: pop from an empty deque
>>> d.extendleft('abc') # extendleft() reverses the input order
>>> d
deque(['c', 'b', 'a'])
.. _deque-recipes:
Recipes
^^^^^^^
This section shows various approaches to working with deques.
The :meth:`rotate` method provides a way to implement :class:`deque` slicing and
deletion. For example, a pure python implementation of ``del d[n]`` relies on
the :meth:`rotate` method to position elements to be popped::
def delete_nth(d, n):
d.rotate(-n)
d.popleft()
d.rotate(n)
To implement :class:`deque` slicing, use a similar approach applying
:meth:`rotate` to bring a target element to the left side of the deque. Remove
old entries with :meth:`popleft`, add new entries with :meth:`extend`, and then
reverse the rotation.
With minor variations on that approach, it is easy to implement Forth style
stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
``rot``, and ``roll``.
A roundrobin task server can be built from a :class:`deque` using
:meth:`popleft` to select the current task and :meth:`append` to add it back to
the tasklist if the input stream is not exhausted::
def roundrobin(*iterables):
pending = deque(iter(i) for i in iterables)
while pending:
task = pending.popleft()
try:
yield next(task)
except StopIteration:
continue
pending.append(task)
>>> for value in roundrobin('abc', 'd', 'efgh'):
... print value
a
d
e
b
f
c
g
h
Multi-pass data reduction algorithms can be succinctly expressed and efficiently
coded by extracting elements with multiple calls to :meth:`popleft`, applying
the reduction function, and calling :meth:`append` to add the result back to the
queue.
For example, building a balanced binary tree of nested lists entails reducing
two adjacent nodes into one by grouping them in a list::
def maketree(iterable):
d = deque(iterable)
while len(d) > 1:
pair = [d.popleft(), d.popleft()]
d.append(pair)
return list(d)
>>> print maketree('abcdefgh')
[[[['a', 'b'], ['c', 'd']], [['e', 'f'], ['g', 'h']]]]
.. _defaultdict-objects:
:class:`defaultdict` objects
----------------------------
.. class:: defaultdict([default_factory[, ...]])
Returns a new dictionary-like object. :class:`defaultdict` is a subclass of the
builtin :class:`dict` class. It overrides one method and adds one writable
instance variable. The remaining functionality is the same as for the
:class:`dict` class and is not documented here.
The first argument provides the initial value for the :attr:`default_factory`
attribute; it defaults to ``None``. All remaining arguments are treated the same
as if they were passed to the :class:`dict` constructor, including keyword
arguments.
.. versionadded:: 2.5
:class:`defaultdict` objects support the following method in addition to the
standard :class:`dict` operations:
.. method:: defaultdict.__missing__(key)
If the :attr:`default_factory` attribute is ``None``, this raises an
:exc:`KeyError` exception with the *key* as argument.
If :attr:`default_factory` is not ``None``, it is called without arguments to
provide a default value for the given *key*, this value is inserted in the
dictionary for the *key*, and returned.
If calling :attr:`default_factory` raises an exception this exception is
propagated unchanged.
This method is called by the :meth:`__getitem__` method of the :class:`dict`
class when the requested key is not found; whatever it returns or raises is then
returned or raised by :meth:`__getitem__`.
:class:`defaultdict` objects support the following instance variable:
.. attribute:: defaultdict.default_factory
This attribute is used by the :meth:`__missing__` method; it is initialized from
the first argument to the constructor, if present, or to ``None``, if absent.
.. _defaultdict-examples:
:class:`defaultdict` Examples
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using :class:`list` as the :attr:`default_factory`, it is easy to group a
sequence of key-value pairs into a dictionary of lists::
>>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
>>> d = defaultdict(list)
>>> for k, v in s:
d[k].append(v)
>>> d.items()
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
When each key is encountered for the first time, it is not already in the
mapping; so an entry is automatically created using the :attr:`default_factory`
function which returns an empty :class:`list`. The :meth:`list.append`
operation then attaches the value to the new list. When keys are encountered
again, the look-up proceeds normally (returning the list for that key) and the
:meth:`list.append` operation adds another value to the list. This technique is
simpler and faster than an equivalent technique using :meth:`dict.setdefault`::
>>> d = {}
>>> for k, v in s:
d.setdefault(k, []).append(v)
>>> d.items()
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
Setting the :attr:`default_factory` to :class:`int` makes the
:class:`defaultdict` useful for counting (like a bag or multiset in other
languages)::
>>> s = 'mississippi'
>>> d = defaultdict(int)
>>> for k in s:
d[k] += 1
>>> d.items()
[('i', 4), ('p', 2), ('s', 4), ('m', 1)]
When a letter is first encountered, it is missing from the mapping, so the
:attr:`default_factory` function calls :func:`int` to supply a default count of
zero. The increment operation then builds up the count for each letter.
The function :func:`int` which always returns zero is just a special case of
constant functions. A faster and more flexible way to create constant functions
is to use a lambda function which can supply any constant value (not just
zero)::
>>> def constant_factory(value):
... return lambda: value
>>> d = defaultdict(constant_factory('<missing>'))
>>> d.update(name='John', action='ran')
>>> '%(name)s %(action)s to %(object)s' % d
'John ran to <missing>'
Setting the :attr:`default_factory` to :class:`set` makes the
:class:`defaultdict` useful for building a dictionary of sets::
>>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
>>> d = defaultdict(set)
>>> for k, v in s:
d[k].add(v)
>>> d.items()
[('blue', set([2, 4])), ('red', set([1, 3]))]
.. _named-tuple-factory:
:func:`NamedTuple` datatype factory function
--------------------------------------------
.. function:: NamedTuple(typename, fieldnames)
Returns a new tuple subclass named *typename*. The new subclass is used to
create tuple-like objects that have fields accessable by attribute lookup as
well as being indexable and iterable. Instances of the subclass also have a
helpful docstring (with typename and fieldnames) and a helpful :meth:`__repr__`
method which lists the tuple contents in a ``name=value`` format.
.. versionadded:: 2.6
The *fieldnames* are specified in a single string and are separated by spaces.
Any valid Python identifier may be used for a field name.
Example::
>>> Point = NamedTuple('Point', 'x y')
>>> Point.__doc__ # docstring for the new datatype
'Point(x, y)'
>>> p = Point(11, y=22) # instantiate with positional or keyword arguments
>>> p[0] + p[1] # works just like the tuple (11, 22)
33
>>> x, y = p # unpacks just like a tuple
>>> x, y
(11, 22)
>>> p.x + p.y # fields also accessable by name
33
>>> p # readable __repr__ with name=value style
Point(x=11, y=22)
The use cases are the same as those for tuples. The named factories assign
meaning to each tuple position and allow for more readable, self-documenting
code. Named tuples can also be used to assign field names to tuples returned
by the :mod:`csv` or :mod:`sqlite3` modules. For example::
from itertools import starmap
import csv
EmployeeRecord = NamedTuple('EmployeeRecord', 'name age title department paygrade')
for record in starmap(EmployeeRecord, csv.reader(open("employees.csv", "rb"))):
print record
To cast an individual record stored as :class:`list`, :class:`tuple`, or some
other iterable type, use the star-operator to unpack the values::
>>> Color = NamedTuple('Color', 'name code')
>>> m = dict(red=1, green=2, blue=3)
>>> print Color(*m.popitem())
Color(name='blue', code=3)

60
Doc-3k/library/colorsys.rst Normal file
View File

@@ -0,0 +1,60 @@
:mod:`colorsys` --- Conversions between color systems
=====================================================
.. module:: colorsys
:synopsis: Conversion functions between RGB and other color systems.
.. sectionauthor:: David Ascher <da@python.net>
The :mod:`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
http://www.poynton.com/ColorFAQ.html.
The :mod:`colorsys` module defines the following functions:
.. function:: rgb_to_yiq(r, g, b)
Convert the color from RGB coordinates to YIQ coordinates.
.. function:: yiq_to_rgb(y, i, q)
Convert the color from YIQ coordinates to RGB coordinates.
.. function:: rgb_to_hls(r, g, b)
Convert the color from RGB coordinates to HLS coordinates.
.. function:: hls_to_rgb(h, l, s)
Convert the color from HLS coordinates to RGB coordinates.
.. function:: rgb_to_hsv(r, g, b)
Convert the color from RGB coordinates to HSV coordinates.
.. function:: 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)

53
Doc-3k/library/commands.rst Normal file
View File

@@ -0,0 +1,53 @@
:mod:`commands` --- Utilities for running commands
==================================================
.. module:: commands
:platform: Unix
:synopsis: Utility functions for running external commands.
.. sectionauthor:: Sue Williams <sbw@provis.com>
The :mod:`commands` module contains wrapper functions for :func:`os.popen` which
take a system command as a string and return any output generated by the command
and, optionally, the exit status.
The :mod:`subprocess` module provides more powerful facilities for spawning new
processes and retrieving their results. Using the :mod:`subprocess` module is
preferable to using the :mod:`commands` module.
The :mod:`commands` module defines the following functions:
.. function:: getstatusoutput(cmd)
Execute the string *cmd* in a shell with :func:`os.popen` and return a 2-tuple
``(status, output)``. *cmd* is actually run as ``{ cmd ; } 2>&1``, so that the
returned output will contain output or error messages. A trailing newline is
stripped from the output. The exit status for the command can be interpreted
according to the rules for the C function :cfunc:`wait`.
.. function:: getoutput(cmd)
Like :func:`getstatusoutput`, except the exit status is ignored and the return
value is a string containing the command's output.
Example::
>>> import commands
>>> commands.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> commands.getstatusoutput('cat /bin/junk')
(256, 'cat: /bin/junk: No such file or directory')
>>> commands.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')
>>> commands.getoutput('ls /bin/ls')
'/bin/ls'
.. seealso::
Module :mod:`subprocess`
Module for spawning and managing subprocesses.

57
Doc-3k/library/compileall.rst Normal file
View File

@@ -0,0 +1,57 @@
:mod:`compileall` --- Byte-compile Python libraries
===================================================
.. module:: compileall
:synopsis: Tools for byte-compiling all Python source files in a directory tree.
This module provides some utility functions to support installing Python
libraries. These functions compile Python source files in a directory tree,
allowing users without permission to write to the libraries to take advantage of
cached byte-code files.
The source file for this module may also be used as a script to compile Python
sources in directories named on the command line or in ``sys.path``.
.. function:: compile_dir(dir[, maxlevels[, ddir[, force[, rx[, quiet]]]]])
Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
files along the way. The *maxlevels* parameter is used to limit the depth of
the recursion; it defaults to ``10``. If *ddir* is given, it is used as the
base path from which the filenames used in error messages will be generated.
If *force* is true, modules are re-compiled even if the timestamps are up to
date.
If *rx* is given, it specifies a regular expression of file names to exclude
from the search; that expression is searched for in the full path.
If *quiet* is true, nothing is printed to the standard output in normal
operation.
.. function:: compile_path([skip_curdir[, maxlevels[, force]]])
Byte-compile all the :file:`.py` files found along ``sys.path``. If
*skip_curdir* is true (the default), the current directory is not included in
the search. The *maxlevels* and *force* parameters default to ``0`` and are
passed to the :func:`compile_dir` function.
To force a recompile of all the :file:`.py` files in the :file:`Lib/`
subdirectory and all its subdirectories::
import compileall
compileall.compile_dir('Lib/', force=True)
# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True)
.. seealso::
Module :mod:`py_compile`
Byte-compile a single source file.

361
Doc-3k/library/configparser.rst Normal file
View File

@@ -0,0 +1,361 @@
:mod:`ConfigParser` --- Configuration file parser
=================================================
.. module:: ConfigParser
:synopsis: Configuration file parser.
.. moduleauthor:: Ken Manheimer <klm@zope.com>
.. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
.. sectionauthor:: Christopher G. Petrilli <petrilli@amber.org>
.. index::
pair: .ini; file
pair: configuration; file
single: ini file
single: Windows ini file
This module defines the class :class:`ConfigParser`. The :class:`ConfigParser`
class implements a basic configuration file parser language which provides a
structure similar to what you would find on Microsoft Windows INI files. You
can use this to write Python programs which can be customized by end users
easily.
.. warning::
This library does *not* interpret or write the value-type prefixes used in the
Windows Registry extended version of INI syntax.
The configuration file consists of sections, led by a ``[section]`` header and
followed by ``name: value`` entries, with continuations in the style of
:rfc:`822`; ``name=value`` is also accepted. Note that leading whitespace is
removed from values. The optional values can contain format strings which refer
to other values in the same section, or values in a special ``DEFAULT`` section.
Additional defaults can be provided on initialization and retrieval. Lines
beginning with ``'#'`` or ``';'`` are ignored and may be used to provide
comments.
For example::
[My Section]
foodir: %(dir)s/whatever
dir=frob
would resolve the ``%(dir)s`` to the value of ``dir`` (``frob`` in this case).
All reference expansions are done on demand.
Default values can be specified by passing them into the :class:`ConfigParser`
constructor as a dictionary. Additional defaults may be passed into the
:meth:`get` method which will override all others.
Sections are normally stored in a builtin dictionary. An alternative dictionary
type can be passed to the :class:`ConfigParser` constructor. For example, if a
dictionary type is passed that sorts its keys, the sections will be sorted on
write-back, as will be the keys within each section.
.. class:: RawConfigParser([defaults[, dict_type]])
The basic configuration object. When *defaults* is given, it is initialized
into the dictionary of intrinsic defaults. When *dict_type* is given, it will
be used to create the dictionary objects for the list of sections, for the
options within a section, and for the default values. This class does not
support the magical interpolation behavior.
.. versionadded:: 2.3
.. versionchanged:: 2.6
*dict_type* was added.
.. class:: ConfigParser([defaults])
Derived class of :class:`RawConfigParser` that implements the magical
interpolation feature and adds optional arguments to the :meth:`get` and
:meth:`items` methods. The values in *defaults* must be appropriate for the
``%()s`` string interpolation. Note that *__name__* is an intrinsic default;
its value is the section name, and will override any value provided in
*defaults*.
All option names used in interpolation will be passed through the
:meth:`optionxform` method just like any other option name reference. For
example, using the default implementation of :meth:`optionxform` (which converts
option names to lower case), the values ``foo %(bar)s`` and ``foo %(BAR)s`` are
equivalent.
.. class:: SafeConfigParser([defaults])
Derived class of :class:`ConfigParser` that implements a more-sane variant of
the magical interpolation feature. This implementation is more predictable as
well. New applications should prefer this version if they don't need to be
compatible with older versions of Python.
.. % XXX Need to explain what's safer/more predictable about it.
.. versionadded:: 2.3
.. exception:: NoSectionError
Exception raised when a specified section is not found.
.. exception:: DuplicateSectionError
Exception raised if :meth:`add_section` is called with the name of a section
that is already present.
.. exception:: NoOptionError
Exception raised when a specified option is not found in the specified section.
.. exception:: InterpolationError
Base class for exceptions raised when problems occur performing string
interpolation.
.. exception:: InterpolationDepthError
Exception raised when string interpolation cannot be completed because the
number of iterations exceeds :const:`MAX_INTERPOLATION_DEPTH`. Subclass of
:exc:`InterpolationError`.
.. exception:: InterpolationMissingOptionError
Exception raised when an option referenced from a value does not exist. Subclass
of :exc:`InterpolationError`.
.. versionadded:: 2.3
.. exception:: InterpolationSyntaxError
Exception raised when the source text into which substitutions are made does not
conform to the required syntax. Subclass of :exc:`InterpolationError`.
.. versionadded:: 2.3
.. exception:: MissingSectionHeaderError
Exception raised when attempting to parse a file which has no section headers.
.. exception:: ParsingError
Exception raised when errors occur attempting to parse a file.
.. data:: MAX_INTERPOLATION_DEPTH
The maximum depth for recursive interpolation for :meth:`get` when the *raw*
parameter is false. This is relevant only for the :class:`ConfigParser` class.
.. seealso::
Module :mod:`shlex`
Support for a creating Unix shell-like mini-languages which can be used as an
alternate format for application configuration files.
.. _rawconfigparser-objects:
RawConfigParser Objects
-----------------------
:class:`RawConfigParser` instances have the following methods:
.. method:: RawConfigParser.defaults()
Return a dictionary containing the instance-wide defaults.
.. method:: RawConfigParser.sections()
Return a list of the sections available; ``DEFAULT`` is not included in the
list.
.. method:: RawConfigParser.add_section(section)
Add a section named *section* to the instance. If a section by the given name
already exists, :exc:`DuplicateSectionError` is raised.
.. method:: RawConfigParser.has_section(section)
Indicates whether the named section is present in the configuration. The
``DEFAULT`` section is not acknowledged.
.. method:: RawConfigParser.options(section)
Returns a list of options available in the specified *section*.
.. method:: RawConfigParser.has_option(section, option)
If the given section exists, and contains the given option, return
:const:`True`; otherwise return :const:`False`.
.. versionadded:: 1.6
.. method:: RawConfigParser.read(filenames)
Attempt to read and parse a list of filenames, returning a list of filenames
which were successfully parsed. If *filenames* is a string or Unicode string,
it is treated as a single filename. If a file named in *filenames* cannot be
opened, that file will be ignored. This is designed so that you can specify a
list of potential configuration file locations (for example, the current
directory, the user's home directory, and some system-wide directory), and all
existing configuration files in the list will be read. If none of the named
files exist, the :class:`ConfigParser` instance will contain an empty dataset.
An application which requires initial values to be loaded from a file should
load the required file or files using :meth:`readfp` before calling :meth:`read`
for any optional files::
import ConfigParser, os
config = ConfigParser.ConfigParser()
config.readfp(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
.. versionchanged:: 2.4
Returns list of successfully parsed filenames.
.. method:: RawConfigParser.readfp(fp[, filename])
Read and parse configuration data from the file or file-like object in *fp*
(only the :meth:`readline` method is used). If *filename* is omitted and *fp*
has a :attr:`name` attribute, that is used for *filename*; the default is
``<???>``.
.. method:: RawConfigParser.get(section, option)
Get an *option* value for the named *section*.
.. method:: RawConfigParser.getint(section, option)
A convenience method which coerces the *option* in the specified *section* to an
integer.
.. method:: RawConfigParser.getfloat(section, option)
A convenience method which coerces the *option* in the specified *section* to a
floating point number.
.. method:: RawConfigParser.getboolean(section, option)
A convenience method which coerces the *option* in the specified *section* to a
Boolean value. Note that the accepted values for the option are ``"1"``,
``"yes"``, ``"true"``, and ``"on"``, which cause this method to return ``True``,
and ``"0"``, ``"no"``, ``"false"``, and ``"off"``, which cause it to return
``False``. These string values are checked in a case-insensitive manner. Any
other value will cause it to raise :exc:`ValueError`.
.. method:: RawConfigParser.items(section)
Return a list of ``(name, value)`` pairs for each option in the given *section*.
.. method:: RawConfigParser.set(section, option, value)
If the given section exists, set the given option to the specified value;
otherwise raise :exc:`NoSectionError`. While it is possible to use
:class:`RawConfigParser` (or :class:`ConfigParser` with *raw* parameters set to
true) for *internal* storage of non-string values, full functionality (including
interpolation and output to files) can only be achieved using string values.
.. versionadded:: 1.6
.. method:: RawConfigParser.write(fileobject)
Write a representation of the configuration to the specified file object. This
representation can be parsed by a future :meth:`read` call.
.. versionadded:: 1.6
.. method:: RawConfigParser.remove_option(section, option)
Remove the specified *option* from the specified *section*. If the section does
not exist, raise :exc:`NoSectionError`. If the option existed to be removed,
return :const:`True`; otherwise return :const:`False`.
.. versionadded:: 1.6
.. method:: RawConfigParser.remove_section(section)
Remove the specified *section* from the configuration. If the section in fact
existed, return ``True``. Otherwise return ``False``.
.. method:: RawConfigParser.optionxform(option)
Transforms the option name *option* as found in an input file or as passed in by
client code to the form that should be used in the internal structures. The
default implementation returns a lower-case version of *option*; subclasses may
override this or client code can set an attribute of this name on instances to
affect this behavior. Setting this to :func:`str`, for example, would make
option names case sensitive.
.. _configparser-objects:
ConfigParser Objects
--------------------
The :class:`ConfigParser` class extends some methods of the
:class:`RawConfigParser` interface, adding some optional arguments.
.. method:: ConfigParser.get(section, option[, raw[, vars]])
Get an *option* value for the named *section*. All the ``'%'`` interpolations
are expanded in the return values, based on the defaults passed into the
constructor, as well as the options *vars* provided, unless the *raw* argument
is true.
.. method:: ConfigParser.items(section[, raw[, vars]])
Return a list of ``(name, value)`` pairs for each option in the given *section*.
Optional arguments have the same meaning as for the :meth:`get` method.
.. versionadded:: 2.3
.. _safeconfigparser-objects:
SafeConfigParser Objects
------------------------
The :class:`SafeConfigParser` class implements the same extended interface as
:class:`ConfigParser`, with the following addition:
.. method:: SafeConfigParser.set(section, option, value)
If the given section exists, set the given option to the specified value;
otherwise raise :exc:`NoSectionError`. *value* must be a string (:class:`str`
or :class:`unicode`); if not, :exc:`TypeError` is raised.
.. versionadded:: 2.4

42
Doc-3k/library/constants.rst Normal file
View File

@@ -0,0 +1,42 @@
Built-in Constants
==================
A small number of constants live in the built-in namespace. They are:
.. data:: False
The false value of the :class:`bool` type.
.. versionadded:: 2.3
.. data:: True
The true value of the :class:`bool` type.
.. versionadded:: 2.3
.. data:: None
The sole value of :attr:`types.NoneType`. ``None`` is frequently used to
represent the absence of a value, as when default arguments are not passed to a
function.
.. data:: NotImplemented
Special value which can be returned by the "rich comparison" special methods
(:meth:`__eq__`, :meth:`__lt__`, and friends), to indicate that the comparison
is not implemented with respect to the other type.
.. data:: Ellipsis
The same as ``...``. Special value used mostly in conjunction with extended
slicing syntax for user-defined container data types.
.. % XXX Someone who understands extended slicing should fill in here.

121
Doc-3k/library/contextlib.rst Normal file
View File

@@ -0,0 +1,121 @@
:mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts.
=========================================================================
.. module:: contextlib
:synopsis: Utilities for with-statement contexts.
.. versionadded:: 2.5
This module provides utilities for common tasks involving the :keyword:`with`
statement.
Functions provided:
.. function:: contextmanager(func)
This function is a decorator that can be used to define a factory function for
:keyword:`with` statement context managers, without needing to create a class or
separate :meth:`__enter__` and :meth:`__exit__` methods.
A simple example (this is not recommended as a real way of generating HTML!)::
from __future__ import with_statement
from contextlib import contextmanager
@contextmanager
def tag(name):
print "<%s>" % name
yield
print "</%s>" % name
>>> with tag("h1"):
... print "foo"
...
<h1>
foo
</h1>
The function being decorated must return a generator-iterator when called. This
iterator must yield exactly one value, which will be bound to the targets in the
:keyword:`with` statement's :keyword:`as` clause, if any.
At the point where the generator yields, the block nested in the :keyword:`with`
statement is executed. The generator is then resumed after the block is exited.
If an unhandled exception occurs in the block, it is reraised inside the
generator at the point where the yield occurred. Thus, you can use a
:keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` statement to trap
the error (if any), or ensure that some cleanup takes place. If an exception is
trapped merely in order to log it or to perform some action (rather than to
suppress it entirely), the generator must reraise that exception. Otherwise the
generator context manager will indicate to the :keyword:`with` statement that
the exception has been handled, and execution will resume with the statement
immediately following the :keyword:`with` statement.
.. function:: nested(mgr1[, mgr2[, ...]])
Combine multiple context managers into a single nested context manager.
Code like this::
from contextlib import nested
with nested(A, B, C) as (X, Y, Z):
do_something()
is equivalent to this::
with A as X:
with B as Y:
with C as Z:
do_something()
Note that if the :meth:`__exit__` method of one of the nested context managers
indicates an exception should be suppressed, no exception information will be
passed to any remaining outer context managers. Similarly, if the
:meth:`__exit__` method of one of the nested managers raises an exception, any
previous exception state will be lost; the new exception will be passed to the
:meth:`__exit__` methods of any remaining outer context managers. In general,
:meth:`__exit__` methods should avoid raising exceptions, and in particular they
should not re-raise a passed-in exception.
.. _context-closing:
.. function:: closing(thing)
Return a context manager that closes *thing* upon completion of the block. This
is basically equivalent to::
from contextlib import contextmanager
@contextmanager
def closing(thing):
try:
yield thing
finally:
thing.close()
And lets you write code like this::
from __future__ import with_statement
from contextlib import closing
import urllib
with closing(urllib.urlopen('http://www.python.org')) as page:
for line in page:
print line
without needing to explicitly close ``page``. Even if an error occurs,
``page.close()`` will be called when the :keyword:`with` block is exited.
.. seealso::
:pep:`0343` - The "with" statement
The specification, background, and examples for the Python :keyword:`with`
statement.

288
Doc-3k/library/cookie.rst Normal file
View File

@@ -0,0 +1,288 @@
:mod:`Cookie` --- HTTP state management
=======================================
.. module:: Cookie
:synopsis: Support for HTTP state management (cookies).
.. moduleauthor:: Timothy O'Malley <timo@alum.mit.edu>
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`Cookie` module defines classes for abstracting the concept of
cookies, an HTTP state management mechanism. It supports both simple string-only
cookies, and provides an abstraction for having any serializable data-type as
cookie value.
The module formerly strictly applied the parsing rules described in the
:rfc:`2109` and :rfc:`2068` specifications. It has since been discovered that
MSIE 3.0x doesn't follow the character rules outlined in those specs. As a
result, the parsing rules used are a bit less strict.
.. exception:: CookieError
Exception failing because of :rfc:`2109` invalidity: incorrect attributes,
incorrect :mailheader:`Set-Cookie` header, etc.
.. class:: BaseCookie([input])
This class is a dictionary-like object whose keys are strings and whose values
are :class:`Morsel` instances. Note that upon setting a key to a value, the
value is first converted to a :class:`Morsel` containing the key and the value.
If *input* is given, it is passed to the :meth:`load` method.
.. class:: SimpleCookie([input])
This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
and :meth:`value_encode` to be the identity and :func:`str` respectively.
.. class:: SerialCookie([input])
This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
and :meth:`value_encode` to be the :func:`pickle.loads` and
:func:`pickle.dumps`.
.. deprecated:: 2.3
Reading pickled values from untrusted cookie data is a huge security hole, as
pickle strings can be crafted to cause arbitrary code to execute on your server.
It is supported for backwards compatibility only, and may eventually go away.
.. class:: SmartCookie([input])
This class derives from :class:`BaseCookie`. It overrides :meth:`value_decode`
to be :func:`pickle.loads` if it is a valid pickle, and otherwise the value
itself. It overrides :meth:`value_encode` to be :func:`pickle.dumps` unless it
is a string, in which case it returns the value itself.
.. deprecated:: 2.3
The same security warning from :class:`SerialCookie` applies here.
A further security note is warranted. For backwards compatibility, the
:mod:`Cookie` module exports a class named :class:`Cookie` which is just an
alias for :class:`SmartCookie`. This is probably a mistake and will likely be
removed in a future version. You should not use the :class:`Cookie` class in
your applications, for the same reason why you should not use the
:class:`SerialCookie` class.
.. seealso::
Module :mod:`cookielib`
HTTP cookie handling for web *clients*. The :mod:`cookielib` and :mod:`Cookie`
modules do not depend on each other.
:rfc:`2109` - HTTP State Management Mechanism
This is the state management specification implemented by this module.
.. _cookie-objects:
Cookie Objects
--------------
.. method:: BaseCookie.value_decode(val)
Return a decoded value from a string representation. Return value can be any
type. This method does nothing in :class:`BaseCookie` --- it exists so it can be
overridden.
.. method:: BaseCookie.value_encode(val)
Return an encoded value. *val* can be any type, but return value must be a
string. This method does nothing in :class:`BaseCookie` --- it exists so it can
be overridden
In general, it should be the case that :meth:`value_encode` and
:meth:`value_decode` are inverses on the range of *value_decode*.
.. method:: BaseCookie.output([attrs[, header[, sep]]])
Return a string representation suitable to be sent as HTTP headers. *attrs* and
*header* are sent to each :class:`Morsel`'s :meth:`output` method. *sep* is used
to join the headers together, and is by default the combination ``'\r\n'``
(CRLF).
.. versionchanged:: 2.5
The default separator has been changed from ``'\n'`` to match the cookie
specification.
.. method:: BaseCookie.js_output([attrs])
Return an embeddable JavaScript snippet, which, if run on a browser which
supports JavaScript, will act the same as if the HTTP headers was sent.
The meaning for *attrs* is the same as in :meth:`output`.
.. method:: BaseCookie.load(rawdata)
If *rawdata* is a string, parse it as an ``HTTP_COOKIE`` and add the values
found there as :class:`Morsel`\ s. If it is a dictionary, it is equivalent to::
for k, v in rawdata.items():
cookie[k] = v
.. _morsel-objects:
Morsel Objects
--------------
.. class:: Morsel()
Abstract a key/value pair, which has some :rfc:`2109` attributes.
Morsels are dictionary-like objects, whose set of keys is constant --- the valid
:rfc:`2109` attributes, which are
* ``expires``
* ``path``
* ``comment``
* ``domain``
* ``max-age``
* ``secure``
* ``version``
The keys are case-insensitive.
.. attribute:: Morsel.value
The value of the cookie.
.. attribute:: Morsel.coded_value
The encoded value of the cookie --- this is what should be sent.
.. attribute:: Morsel.key
The name of the cookie.
.. method:: Morsel.set(key, value, coded_value)
Set the *key*, *value* and *coded_value* members.
.. method:: Morsel.isReservedKey(K)
Whether *K* is a member of the set of keys of a :class:`Morsel`.
.. method:: Morsel.output([attrs[, header]])
Return a string representation of the Morsel, suitable to be sent as an HTTP
header. By default, all the attributes are included, unless *attrs* is given, in
which case it should be a list of attributes to use. *header* is by default
``"Set-Cookie:"``.
.. method:: Morsel.js_output([attrs])
Return an embeddable JavaScript snippet, which, if run on a browser which
supports JavaScript, will act the same as if the HTTP header was sent.
The meaning for *attrs* is the same as in :meth:`output`.
.. method:: Morsel.OutputString([attrs])
Return a string representing the Morsel, without any surrounding HTTP or
JavaScript.
The meaning for *attrs* is the same as in :meth:`output`.
.. _cookie-example:
Example
-------
The following example demonstrates how to use the :mod:`Cookie` module. ::
>>> import Cookie
>>> C = Cookie.SimpleCookie()
>>> C = Cookie.SerialCookie()
>>> C = Cookie.SmartCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print C # generate HTTP headers
Set-Cookie: sugar=wafer
Set-Cookie: fig=newton
>>> print C.output() # same thing
Set-Cookie: sugar=wafer
Set-Cookie: fig=newton
>>> C = Cookie.SmartCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print C.output(header="Cookie:")
Cookie: rocky=road; Path=/cookie
>>> print C.output(attrs=[], header="Cookie:")
Cookie: rocky=road
>>> C = Cookie.SmartCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print C
Set-Cookie: vienna=finger
Set-Cookie: chips=ahoy
>>> C = Cookie.SmartCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print C
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = Cookie.SmartCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print C
Set-Cookie: oreo=doublestuff; Path=/
>>> C = Cookie.SmartCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = Cookie.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number=7
Set-Cookie: string=seven
>>> C = Cookie.SerialCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number="I7\012."
Set-Cookie: string="S'seven'\012p1\012."
>>> C = Cookie.SmartCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number="I7\012."
Set-Cookie: string=seven

768
Doc-3k/library/cookielib.rst Normal file
View File

@@ -0,0 +1,768 @@
:mod:`cookielib` --- Cookie handling for HTTP clients
=====================================================
.. module:: cookielib
.. moduleauthor:: John J. Lee <jjl@pobox.com>
.. sectionauthor:: John J. Lee <jjl@pobox.com>
.. versionadded:: 2.4
The :mod:`cookielib` module defines classes for automatic handling of HTTP
cookies. It is useful for accessing web sites that require small pieces of data
-- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a
web server, and then returned to the server in later HTTP requests.
Both the regular Netscape cookie protocol and the protocol defined by
:rfc:`2965` are handled. RFC 2965 handling is switched off by default.
:rfc:`2109` cookies are parsed as Netscape cookies and subsequently treated
either as Netscape or RFC 2965 cookies according to the 'policy' in effect.
Note that the great majority of cookies on the Internet are Netscape cookies.
:mod:`cookielib` attempts to follow the de-facto Netscape cookie protocol (which
differs substantially from that set out in the original Netscape specification),
including taking note of the ``max-age`` and ``port`` cookie-attributes
introduced with RFC 2965.
.. note::
The various named parameters found in :mailheader:`Set-Cookie` and
:mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are
conventionally referred to as :dfn:`attributes`. To distinguish them from
Python attributes, the documentation for this module uses the term
:dfn:`cookie-attribute` instead
.
The module defines the following exception:
.. exception:: LoadError
Instances of :class:`FileCookieJar` raise this exception on failure to load
cookies from a file.
.. note::
For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
:exc:`LoadError` is a subclass of :exc:`IOError`
.
The following classes are provided:
.. class:: CookieJar(policy=None)
*policy* is an object implementing the :class:`CookiePolicy` interface.
The :class:`CookieJar` class stores HTTP cookies. It extracts cookies from HTTP
requests, and returns them in HTTP responses. :class:`CookieJar` instances
automatically expire contained cookies when necessary. Subclasses are also
responsible for storing and retrieving cookies from a file or database.
.. class:: FileCookieJar(filename, delayload=None, policy=None)
*policy* is an object implementing the :class:`CookiePolicy` interface. For the
other arguments, see the documentation for the corresponding attributes.
A :class:`CookieJar` which can load cookies from, and perhaps save cookies to, a
file on disk. Cookies are **NOT** loaded from the named file until either the
:meth:`load` or :meth:`revert` method is called. Subclasses of this class are
documented in section :ref:`file-cookie-jar-classes`.
.. class:: CookiePolicy()
This class is responsible for deciding whether each cookie should be accepted
from / returned to the server.
.. class:: DefaultCookiePolicy( blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False )
Constructor arguments should be passed as keyword arguments only.
*blocked_domains* is a sequence of domain names that we never accept cookies
from, nor return cookies to. *allowed_domains* if not :const:`None`, this is a
sequence of the only domains for which we accept and return cookies. For all
other arguments, see the documentation for :class:`CookiePolicy` and
:class:`DefaultCookiePolicy` objects.
:class:`DefaultCookiePolicy` implements the standard accept / reject rules for
Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (ie. cookies
received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of
1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling
is turned off or :attr:`rfc2109_as_netscape` is True, RFC 2109 cookies are
'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by setting
the :attr:`version` attribute of the :class:`Cookie` instance to 0.
:class:`DefaultCookiePolicy` also provides some parameters to allow some fine-
tuning of policy.
.. class:: Cookie()
This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not
expected that users of :mod:`cookielib` construct their own :class:`Cookie`
instances. Instead, if necessary, call :meth:`make_cookies` on a
:class:`CookieJar` instance.
.. seealso::
Module :mod:`urllib2`
URL opening with automatic cookie handling.
Module :mod:`Cookie`
HTTP cookie classes, principally useful for server-side code. The
:mod:`cookielib` and :mod:`Cookie` modules do not depend on each other.
http://wwwsearch.sf.net/ClientCookie/
Extensions to this module, including a class for reading Microsoft Internet
Explorer cookies on Windows.
http://www.netscape.com/newsref/std/cookie_spec.html
The specification of the original Netscape cookie protocol. Though this is
still the dominant protocol, the 'Netscape cookie protocol' implemented by all
the major browsers (and :mod:`cookielib`) only bears a passing resemblance to
the one sketched out in ``cookie_spec.html``.
:rfc:`2109` - HTTP State Management Mechanism
Obsoleted by RFC 2965. Uses :mailheader:`Set-Cookie` with version=1.
:rfc:`2965` - HTTP State Management Mechanism
The Netscape protocol with the bugs fixed. Uses :mailheader:`Set-Cookie2` in
place of :mailheader:`Set-Cookie`. Not widely used.
http://kristol.org/cookie/errata.html
Unfinished errata to RFC 2965.
:rfc:`2964` - Use of HTTP State Management
.. _cookie-jar-objects:
CookieJar and FileCookieJar Objects
-----------------------------------
:class:`CookieJar` objects support the iterator protocol for iterating over
contained :class:`Cookie` objects.
:class:`CookieJar` has the following methods:
.. method:: CookieJar.add_cookie_header(request)
Add correct :mailheader:`Cookie` header to *request*.
If policy allows (ie. the :attr:`rfc2965` and :attr:`hide_cookie2` attributes of
the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false
respectively), the :mailheader:`Cookie2` header is also added when appropriate.
The *request* object (usually a :class:`urllib2.Request` instance) must support
the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`get_type`,
:meth:`unverifiable`, :meth:`get_origin_req_host`, :meth:`has_header`,
:meth:`get_header`, :meth:`header_items`, and :meth:`add_unredirected_header`,as
documented by :mod:`urllib2`.
.. method:: CookieJar.extract_cookies(response, request)
Extract cookies from HTTP *response* and store them in the :class:`CookieJar`,
where allowed by policy.
The :class:`CookieJar` will look for allowable :mailheader:`Set-Cookie` and
:mailheader:`Set-Cookie2` headers in the *response* argument, and store cookies
as appropriate (subject to the :meth:`CookiePolicy.set_ok` method's approval).
The *response* object (usually the result of a call to :meth:`urllib2.urlopen`,
or similar) should support an :meth:`info` method, which returns an object with
a :meth:`getallmatchingheaders` method (usually a :class:`mimetools.Message`
instance).
The *request* object (usually a :class:`urllib2.Request` instance) must support
the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`unverifiable`, and
:meth:`get_origin_req_host`, as documented by :mod:`urllib2`. The request is
used to set default values for cookie-attributes as well as for checking that
the cookie is allowed to be set.
.. method:: CookieJar.set_policy(policy)
Set the :class:`CookiePolicy` instance to be used.
.. method:: CookieJar.make_cookies(response, request)
Return sequence of :class:`Cookie` objects extracted from *response* object.
See the documentation for :meth:`extract_cookies` for the interfaces required of
the *response* and *request* arguments.
.. method:: CookieJar.set_cookie_if_ok(cookie, request)
Set a :class:`Cookie` if policy says it's OK to do so.
.. method:: CookieJar.set_cookie(cookie)
Set a :class:`Cookie`, without checking with policy to see whether or not it
should be set.
.. method:: CookieJar.clear([domain[, path[, name]]])
Clear some cookies.
If invoked without arguments, clear all cookies. If given a single argument,
only cookies belonging to that *domain* will be removed. If given two arguments,
cookies belonging to the specified *domain* and URL *path* are removed. If
given three arguments, then the cookie with the specified *domain*, *path* and
*name* is removed.
Raises :exc:`KeyError` if no matching cookie exists.
.. method:: CookieJar.clear_session_cookies()
Discard all session cookies.
Discards all contained cookies that have a true :attr:`discard` attribute
(usually because they had either no ``max-age`` or ``expires`` cookie-attribute,
or an explicit ``discard`` cookie-attribute). For interactive browsers, the end
of a session usually corresponds to closing the browser window.
Note that the :meth:`save` method won't save session cookies anyway, unless you
ask otherwise by passing a true *ignore_discard* argument.
:class:`FileCookieJar` implements the following additional methods:
.. method:: FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)
Save cookies to a file.
This base class raises :exc:`NotImplementedError`. Subclasses may leave this
method unimplemented.
*filename* is the name of file in which to save cookies. If *filename* is not
specified, :attr:`self.filename` is used (whose default is the value passed to
the constructor, if any); if :attr:`self.filename` is :const:`None`,
:exc:`ValueError` is raised.
*ignore_discard*: save even cookies set to be discarded. *ignore_expires*: save
even cookies that have expired
The file is overwritten if it already exists, thus wiping all the cookies it
contains. Saved cookies can be restored later using the :meth:`load` or
:meth:`revert` methods.
.. method:: FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)
Load cookies from a file.
Old cookies are kept unless overwritten by newly loaded ones.
Arguments are as for :meth:`save`.
The named file must be in the format understood by the class, or
:exc:`LoadError` will be raised. Also, :exc:`IOError` may be raised, for
example if the file does not exist.
.. note::
For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
:exc:`LoadError` is a subclass of :exc:`IOError`.
.. method:: FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)
Clear all cookies and reload cookies from a saved file.
:meth:`revert` can raise the same exceptions as :meth:`load`. If there is a
failure, the object's state will not be altered.
:class:`FileCookieJar` instances have the following public attributes:
.. attribute:: FileCookieJar.filename
Filename of default file in which to keep cookies. This attribute may be
assigned to.
.. attribute:: FileCookieJar.delayload
If true, load cookies lazily from disk. This attribute should not be assigned
to. This is only a hint, since this only affects performance, not behaviour
(unless the cookies on disk are changing). A :class:`CookieJar` object may
ignore it. None of the :class:`FileCookieJar` classes included in the standard
library lazily loads cookies.
.. _file-cookie-jar-classes:
FileCookieJar subclasses and co-operation with web browsers
-----------------------------------------------------------
The following :class:`CookieJar` subclasses are provided for reading and writing
. Further :class:`CookieJar` subclasses, including one that reads Microsoft
Internet Explorer cookies, are available at
http://wwwsearch.sf.net/ClientCookie/.
.. class:: MozillaCookieJar(filename, delayload=None, policy=None)
A :class:`FileCookieJar` that can load from and save cookies to disk in the
Mozilla ``cookies.txt`` file format (which is also used by the Lynx and Netscape
browsers).
.. note::
This loses information about RFC 2965 cookies, and also about newer or non-
standard cookie-attributes such as ``port``.
.. warning::
Back up your cookies before saving if you have cookies whose loss / corruption
would be inconvenient (there are some subtleties which may lead to slight
changes in the file over a load / save round-trip).
Also note that cookies saved while Mozilla is running will get clobbered by
Mozilla.
.. class:: LWPCookieJar(filename, delayload=None, policy=None)
A :class:`FileCookieJar` that can load from and save cookies to disk in format
compatible with the libwww-perl library's ``Set-Cookie3`` file format. This is
convenient if you want to store cookies in a human-readable file.
.. _cookie-policy-objects:
CookiePolicy Objects
--------------------
Objects implementing the :class:`CookiePolicy` interface have the following
methods:
.. method:: CookiePolicy.set_ok(cookie, request)
Return boolean value indicating whether cookie should be accepted from server.
*cookie* is a :class:`cookielib.Cookie` instance. *request* is an object
implementing the interface defined by the documentation for
:meth:`CookieJar.extract_cookies`.
.. method:: CookiePolicy.return_ok(cookie, request)
Return boolean value indicating whether cookie should be returned to server.
*cookie* is a :class:`cookielib.Cookie` instance. *request* is an object
implementing the interface defined by the documentation for
:meth:`CookieJar.add_cookie_header`.
.. method:: CookiePolicy.domain_return_ok(domain, request)
Return false if cookies should not be returned, given cookie domain.
This method is an optimization. It removes the need for checking every cookie
with a particular domain (which might involve reading many files). Returning
true from :meth:`domain_return_ok` and :meth:`path_return_ok` leaves all the
work to :meth:`return_ok`.
If :meth:`domain_return_ok` returns true for the cookie domain,
:meth:`path_return_ok` is called for the cookie path. Otherwise,
:meth:`path_return_ok` and :meth:`return_ok` are never called for that cookie
domain. If :meth:`path_return_ok` returns true, :meth:`return_ok` is called
with the :class:`Cookie` object itself for a full check. Otherwise,
:meth:`return_ok` is never called for that cookie path.
Note that :meth:`domain_return_ok` is called for every *cookie* domain, not just
for the *request* domain. For example, the function might be called with both
``".example.com"`` and ``"www.example.com"`` if the request domain is
``"www.example.com"``. The same goes for :meth:`path_return_ok`.
The *request* argument is as documented for :meth:`return_ok`.
.. method:: CookiePolicy.path_return_ok(path, request)
Return false if cookies should not be returned, given cookie path.
See the documentation for :meth:`domain_return_ok`.
In addition to implementing the methods above, implementations of the
:class:`CookiePolicy` interface must also supply the following attributes,
indicating which protocols should be used, and how. All of these attributes may
be assigned to.
.. attribute:: CookiePolicy.netscape
Implement Netscape protocol.
.. attribute:: CookiePolicy.rfc2965
Implement RFC 2965 protocol.
.. attribute:: CookiePolicy.hide_cookie2
Don't add :mailheader:`Cookie2` header to requests (the presence of this header
indicates to the server that we understand RFC 2965 cookies).
The most useful way to define a :class:`CookiePolicy` class is by subclassing
from :class:`DefaultCookiePolicy` and overriding some or all of the methods
above. :class:`CookiePolicy` itself may be used as a 'null policy' to allow
setting and receiving any and all cookies (this is unlikely to be useful).
.. _default-cookie-policy-objects:
DefaultCookiePolicy Objects
---------------------------
Implements the standard rules for accepting and returning cookies.
Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is switched
off by default.
The easiest way to provide your own policy is to override this class and call
its methods in your overridden implementations before adding your own additional
checks::
import cookielib
class MyCookiePolicy(cookielib.DefaultCookiePolicy):
def set_ok(self, cookie, request):
if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request):
return False
if i_dont_want_to_store_this_cookie(cookie):
return False
return True
In addition to the features required to implement the :class:`CookiePolicy`
interface, this class allows you to block and allow domains from setting and
receiving cookies. There are also some strictness switches that allow you to
tighten up the rather loose Netscape protocol rules a little bit (at the cost of
blocking some benign cookies).
A domain blacklist and whitelist is provided (both off by default). Only domains
not in the blacklist and present in the whitelist (if the whitelist is active)
participate in cookie setting and returning. Use the *blocked_domains*
constructor argument, and :meth:`blocked_domains` and
:meth:`set_blocked_domains` methods (and the corresponding argument and methods
for *allowed_domains*). If you set a whitelist, you can turn it off again by
setting it to :const:`None`.
Domains in block or allow lists that do not start with a dot must equal the
cookie domain to be matched. For example, ``"example.com"`` matches a blacklist
entry of ``"example.com"``, but ``"www.example.com"`` does not. Domains that do
start with a dot are matched by more specific domains too. For example, both
``"www.example.com"`` and ``"www.coyote.example.com"`` match ``".example.com"``
(but ``"example.com"`` itself does not). IP addresses are an exception, and
must match exactly. For example, if blocked_domains contains ``"192.168.1.2"``
and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not.
:class:`DefaultCookiePolicy` implements the following additional methods:
.. method:: DefaultCookiePolicy.blocked_domains()
Return the sequence of blocked domains (as a tuple).
.. method:: DefaultCookiePolicy.set_blocked_domains(blocked_domains)
Set the sequence of blocked domains.
.. method:: DefaultCookiePolicy.is_blocked(domain)
Return whether *domain* is on the blacklist for setting or receiving cookies.
.. method:: DefaultCookiePolicy.allowed_domains()
Return :const:`None`, or the sequence of allowed domains (as a tuple).
.. method:: DefaultCookiePolicy.set_allowed_domains(allowed_domains)
Set the sequence of allowed domains, or :const:`None`.
.. method:: DefaultCookiePolicy.is_not_allowed(domain)
Return whether *domain* is not on the whitelist for setting or receiving
cookies.
:class:`DefaultCookiePolicy` instances have the following attributes, which are
all initialised from the constructor arguments of the same name, and which may
all be assigned to.
.. attribute:: DefaultCookiePolicy.rfc2109_as_netscape
If true, request that the :class:`CookieJar` instance downgrade RFC 2109 cookies
(ie. cookies received in a :mailheader:`Set-Cookie` header with a version
cookie-attribute of 1) to Netscape cookies by setting the version attribute of
the :class:`Cookie` instance to 0. The default value is :const:`None`, in which
case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned
off. Therefore, RFC 2109 cookies are downgraded by default.
.. versionadded:: 2.5
General strictness switches:
.. attribute:: DefaultCookiePolicy.strict_domain
Don't allow sites to set two-component domains with country-code top-level
domains like ``.co.uk``, ``.gov.uk``, ``.co.nz``.etc. This is far from perfect
and isn't guaranteed to work!
RFC 2965 protocol strictness switches:
.. attribute:: DefaultCookiePolicy.strict_rfc2965_unverifiable
Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable
transaction is one resulting from a redirect or a request for an image hosted on
another site). If this is false, cookies are *never* blocked on the basis of
verifiability
Netscape protocol strictness switches:
.. attribute:: DefaultCookiePolicy.strict_ns_unverifiable
apply RFC 2965 rules on unverifiable transactions even to Netscape cookies
.. attribute:: DefaultCookiePolicy.strict_ns_domain
Flags indicating how strict to be with domain-matching rules for Netscape
cookies. See below for acceptable values.
.. attribute:: DefaultCookiePolicy.strict_ns_set_initial_dollar
Ignore cookies in Set-Cookie: headers that have names starting with ``'$'``.
.. attribute:: DefaultCookiePolicy.strict_ns_set_path
Don't allow setting cookies whose path doesn't path-match request URI.
:attr:`strict_ns_domain` is a collection of flags. Its value is constructed by
or-ing together (for example, ``DomainStrictNoDots|DomainStrictNonDomain`` means
both flags are set).
.. attribute:: DefaultCookiePolicy.DomainStrictNoDots
When setting cookies, the 'host prefix' must not contain a dot (eg.
``www.foo.bar.com`` can't set a cookie for ``.bar.com``, because ``www.foo``
contains a dot).
.. attribute:: DefaultCookiePolicy.DomainStrictNonDomain
Cookies that did not explicitly specify a ``domain`` cookie-attribute can only
be returned to a domain equal to the domain that set the cookie (eg.
``spam.example.com`` won't be returned cookies from ``example.com`` that had no
``domain`` cookie-attribute).
.. attribute:: DefaultCookiePolicy.DomainRFC2965Match
When setting cookies, require a full RFC 2965 domain-match.
The following attributes are provided for convenience, and are the most useful
combinations of the above flags:
.. attribute:: DefaultCookiePolicy.DomainLiberal
Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
off).
.. attribute:: DefaultCookiePolicy.DomainStrict
Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``.
.. _cookie-objects:
Cookie Objects
--------------
:class:`Cookie` instances have Python attributes roughly corresponding to the
standard cookie-attributes specified in the various cookie standards. The
correspondence is not one-to-one, because there are complicated rules for
assigning default values, because the ``max-age`` and ``expires`` cookie-
attributes contain equivalent information, and because RFC 2109 cookies may be
'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape) cookies.
Assignment to these attributes should not be necessary other than in rare
circumstances in a :class:`CookiePolicy` method. The class does not enforce
internal consistency, so you should know what you're doing if you do that.
.. attribute:: Cookie.version
Integer or :const:`None`. Netscape cookies have :attr:`version` 0. RFC 2965 and
RFC 2109 cookies have a ``version`` cookie-attribute of 1. However, note that
:mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
case :attr:`version` is 0.
.. attribute:: Cookie.name
Cookie name (a string).
.. attribute:: Cookie.value
Cookie value (a string), or :const:`None`.
.. attribute:: Cookie.port
String representing a port or a set of ports (eg. '80', or '80,8080'), or
:const:`None`.
.. attribute:: Cookie.path
Cookie path (a string, eg. ``'/acme/rocket_launchers'``).
.. attribute:: Cookie.secure
True if cookie should only be returned over a secure connection.
.. attribute:: Cookie.expires
Integer expiry date in seconds since epoch, or :const:`None`. See also the
:meth:`is_expired` method.
.. attribute:: Cookie.discard
True if this is a session cookie.
.. attribute:: Cookie.comment
String comment from the server explaining the function of this cookie, or
:const:`None`.
.. attribute:: Cookie.comment_url
URL linking to a comment from the server explaining the function of this cookie,
or :const:`None`.
.. attribute:: Cookie.rfc2109
True if this cookie was received as an RFC 2109 cookie (ie. the cookie arrived
in a :mailheader:`Set-Cookie` header, and the value of the Version cookie-
attribute in that header was 1). This attribute is provided because
:mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
case :attr:`version` is 0.
.. versionadded:: 2.5
.. attribute:: Cookie.port_specified
True if a port or set of ports was explicitly specified by the server (in the
:mailheader:`Set-Cookie` / :mailheader:`Set-Cookie2` header).
.. attribute:: Cookie.domain_specified
True if a domain was explicitly specified by the server.
.. attribute:: Cookie.domain_initial_dot
True if the domain explicitly specified by the server began with a dot
(``'.'``).
Cookies may have additional non-standard cookie-attributes. These may be
accessed using the following methods:
.. method:: Cookie.has_nonstandard_attr(name)
Return true if cookie has the named cookie-attribute.
.. method:: Cookie.get_nonstandard_attr(name, default=None)
If cookie has the named cookie-attribute, return its value. Otherwise, return
*default*.
.. method:: Cookie.set_nonstandard_attr(name, value)
Set the value of the named cookie-attribute.
The :class:`Cookie` class also defines the following method:
.. method:: Cookie.is_expired([now=:const:`None`])
True if cookie has passed the time at which the server requested it should
expire. If *now* is given (in seconds since the epoch), return whether the
cookie has expired at the specified time.
.. _cookielib-examples:
Examples
--------
The first example shows the most common usage of :mod:`cookielib`::
import cookielib, urllib2
cj = cookielib.CookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx
cookies (assumes Unix/Netscape convention for location of the cookies file)::
import os, cookielib, urllib2
cj = cookielib.MozillaCookieJar()
cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
The next example illustrates the use of :class:`DefaultCookiePolicy`. Turn on
RFC 2965 cookies, be more strict about domains when setting and returning
Netscape cookies, and block some domains from setting cookies or having them
returned::
import urllib2
from cookielib import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
rfc2965=True, strict_ns_domain=Policy.DomainStrict,
blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

85
Doc-3k/library/copy.rst Normal file
View File

@@ -0,0 +1,85 @@
:mod:`copy` --- Shallow and deep copy operations
================================================
.. module:: copy
:synopsis: Shallow and deep copy operations.
.. index::
single: copy() (in copy)
single: deepcopy() (in copy)
This module provides generic (shallow and deep) copying operations.
Interface summary::
import copy
x = copy.copy(y) # make a shallow copy of y
x = copy.deepcopy(y) # make a deep copy of y
For module specific errors, :exc:`copy.error` is raised.
.. %
The difference between shallow and deep copying is only relevant for compound
objects (objects that contain other objects, like lists or class instances):
* A *shallow copy* constructs a new compound object and then (to the extent
possible) inserts *references* into it to the objects found in the original.
* A *deep copy* constructs a new compound object and then, recursively, inserts
*copies* into it of the objects found in the original.
Two problems often exist with deep copy operations that don't exist with shallow
copy operations:
* Recursive objects (compound objects that, directly or indirectly, contain a
reference to themselves) may cause a recursive loop.
* Because deep copy copies *everything* it may copy too much, e.g.,
administrative data structures that should be shared even between copies.
The :func:`deepcopy` function avoids these problems by:
* keeping a "memo" dictionary of objects already copied during the current
copying pass; and
* letting user-defined classes override the copying operation or the set of
components copied.
This module does not copy types like module, method, stack trace, stack frame,
file, socket, window, array, or any similar types. It does "copy" functions and
classes (shallow and deeply), by returning the original object unchanged; this
is compatible with the way these are treated by the :mod:`pickle` module.
.. versionchanged:: 2.5
Added copying functions.
.. index:: module: pickle
Classes can use the same interfaces to control copying that they use to control
pickling. See the description of module :mod:`pickle` for information on these
methods. The :mod:`copy` module does not use the :mod:`copy_reg` registration
module.
.. index::
single: __copy__() (copy protocol)
single: __deepcopy__() (copy protocol)
In order for a class to define its own copy implementation, it can define
special methods :meth:`__copy__` and :meth:`__deepcopy__`. The former is called
to implement the shallow copy operation; no additional arguments are passed.
The latter is called to implement the deep copy operation; it is passed one
argument, the memo dictionary. If the :meth:`__deepcopy__` implementation needs
to make a deep copy of a component, it should call the :func:`deepcopy` function
with the component as first argument and the memo dictionary as second argument.
.. seealso::
Module :mod:`pickle`
Discussion of the special methods used to support object state retrieval and
restoration.

42
Doc-3k/library/copy_reg.rst Normal file
View File

@@ -0,0 +1,42 @@
:mod:`copy_reg` --- Register :mod:`pickle` support functions
============================================================
.. module:: copy_reg
:synopsis: Register pickle support functions.
.. index::
module: pickle
module: cPickle
module: copy
The :mod:`copy_reg` module provides support for the :mod:`pickle` and
:mod:`cPickle` modules. The :mod:`copy` module is likely to use this in the
future as well. It provides configuration information about object constructors
which are not classes. Such constructors may be factory functions or class
instances.
.. function:: constructor(object)
Declares *object* to be a valid constructor. If *object* is not callable (and
hence not valid as a constructor), raises :exc:`TypeError`.
.. function:: pickle(type, function[, constructor])
Declares that *function* should be used as a "reduction" function for objects of
type *type*; *type* must not be a "classic" class object. (Classic classes are
handled differently; see the documentation for the :mod:`pickle` module for
details.) *function* should return either a string or a tuple containing two or
three elements.
The optional *constructor* parameter, if provided, is a callable object which
can be used to reconstruct the object when called with the tuple of arguments
returned by *function* at pickling time. :exc:`TypeError` will be raised if
*object* is a class or *constructor* is not callable.
See the :mod:`pickle` module for more details on the interface expected of
*function* and *constructor*.

66
Doc-3k/library/crypt.rst Normal file
View File

@@ -0,0 +1,66 @@
:mod:`crypt` --- Function to check Unix passwords
=================================================
.. module:: crypt
:platform: Unix
:synopsis: The crypt() function used to check Unix passwords.
.. moduleauthor:: Steven D. Majewski <sdm7g@virginia.edu>
.. sectionauthor:: Steven D. Majewski <sdm7g@virginia.edu>
.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
.. index::
single: crypt(3)
pair: cipher; DES
This module implements an interface to the :manpage:`crypt(3)` routine, which is
a one-way hash function based upon a modified DES algorithm; see the Unix man
page for further details. Possible uses include allowing Python scripts to
accept typed passwords from the user, or attempting to crack Unix passwords with
a dictionary.
.. index:: single: crypt(3)
Notice that the behavior of this module depends on the actual implementation of
the :manpage:`crypt(3)` routine in the running system. Therefore, any
extensions available on the current implementation will also be available on
this module.
.. function:: crypt(word, salt)
*word* will usually be a user's password as typed at a prompt or in a graphical
interface. *salt* is usually a random two-character string which will be used
to perturb the DES algorithm in one of 4096 ways. The characters in *salt* must
be in the set ``[./a-zA-Z0-9]``. Returns the hashed password as a string, which
will be composed of characters from the same alphabet as the salt (the first two
characters represent the salt itself).
.. index:: single: crypt(3)
Since a few :manpage:`crypt(3)` extensions allow different values, with
different sizes in the *salt*, it is recommended to use the full crypted
password as salt when checking for a password.
A simple example illustrating typical use::
import crypt, getpass, pwd
def raw_input(prompt):
import sys
sys.stdout.write(prompt)
sys.stdout.flush()
return sys.stdin.readline()
def login():
username = raw_input('Python login:')
cryptedpasswd = pwd.getpwnam(username)[1]
if cryptedpasswd:
if cryptedpasswd == 'x' or cryptedpasswd == '*':
raise "Sorry, currently no support for shadow passwords"
cleartext = getpass.getpass()
return crypt.crypt(cleartext, cryptedpasswd) == cryptedpasswd
else:
return 1

30
Doc-3k/library/crypto.rst Normal file
View File

@@ -0,0 +1,30 @@
.. _crypto:
**********************
Cryptographic Services
**********************
.. index:: single: cryptography
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:
.. toctree::
hashlib.rst
hmac.rst
.. index::
pair: AES; algorithm
single: cryptography
single: Kuchling, Andrew
Hardcore cypherpunks will probably find the cryptographic modules written by
A.M. Kuchling of further interest; the package contains modules for various
encryption algorithms, most notably AES. These modules are not distributed with
Python but available separately. See the URL
http://www.amk.ca/python/code/crypto.html for more information.

531
Doc-3k/library/csv.rst Normal file
View File

@@ -0,0 +1,531 @@
:mod:`csv` --- CSV File Reading and Writing
===========================================
.. module:: csv
:synopsis: Write and read tabular data to and from delimited files.
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
.. versionadded:: 2.3
.. index::
single: csv
pair: data; tabular
The so-called CSV (Comma Separated Values) format is the most common import and
export format for spreadsheets and databases. There is no "CSV standard", so
the format is operationally defined by the many applications which read and
write it. The lack of a standard means that subtle differences often exist in
the data produced and consumed by different applications. These differences can
make it annoying to process CSV files from multiple sources. Still, while the
delimiters and quoting characters vary, the overall format is similar enough
that it is possible to write a single module which can efficiently manipulate
such data, hiding the details of reading and writing the data from the
programmer.
The :mod:`csv` module implements classes to read and write tabular data in CSV
format. It allows programmers to say, "write this data in the format preferred
by Excel," or "read data from this file which was generated by Excel," without
knowing the precise details of the CSV format used by Excel. Programmers can
also describe the CSV formats understood by other applications or define their
own special-purpose CSV formats.
The :mod:`csv` module's :class:`reader` and :class:`writer` objects read and
write sequences. Programmers can also read and write data in dictionary form
using the :class:`DictReader` and :class:`DictWriter` classes.
.. note::
This version of the :mod:`csv` module doesn't support Unicode input. Also,
there are currently some issues regarding ASCII NUL characters. Accordingly,
all input should be UTF-8 or printable ASCII to be safe; see the examples in
section :ref:`csv-examples`. These restrictions will be removed in the future.
.. seealso::
.. % \seemodule{array}{Arrays of uniformly types numeric values.}
:pep:`305` - CSV File API
The Python Enhancement Proposal which proposed this addition to Python.
.. _csv-contents:
Module Contents
---------------
The :mod:`csv` module defines the following functions:
.. function:: reader(csvfile[, dialect=``'excel'``][, fmtparam])
Return a reader object which will iterate over lines in the given *csvfile*.
*csvfile* can be any object which supports the iterator protocol and returns a
string each time its :meth:`next` method is called --- file objects and list
objects are both suitable. If *csvfile* is a file object, it must be opened
with the 'b' flag on platforms where that makes a difference. An optional
*dialect* parameter can be given which is used to define a set of parameters
specific to a particular CSV dialect. It may be an instance of a subclass of
the :class:`Dialect` class or one of the strings returned by the
:func:`list_dialects` function. The other optional *fmtparam* keyword arguments
can be given to override individual formatting parameters in the current
dialect. For full details about the dialect and formatting parameters, see
section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters".
All data read are returned as strings. No automatic data type conversion is
performed.
.. versionchanged:: 2.5
The parser is now stricter with respect to multi-line quoted fields. Previously,
if a line ended within a quoted field without a terminating newline character, a
newline would be inserted into the returned field. This behavior caused problems
when reading files which contained carriage return characters within fields.
The behavior was changed to return the field without inserting newlines. As a
consequence, if newlines embedded within fields are important, the input should
be split into lines in a manner which preserves the newline characters.
.. function:: writer(csvfile[, dialect=``'excel'``][, fmtparam])
Return a writer object responsible for converting the user's data into delimited
strings on the given file-like object. *csvfile* can be any object with a
:func:`write` method. If *csvfile* is a file object, it must be opened with the
'b' flag on platforms where that makes a difference. An optional *dialect*
parameter can be given which is used to define a set of parameters specific to a
particular CSV dialect. It may be an instance of a subclass of the
:class:`Dialect` class or one of the strings returned by the
:func:`list_dialects` function. The other optional *fmtparam* keyword arguments
can be given to override individual formatting parameters in the current
dialect. For full details about the dialect and formatting parameters, see
section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters". To make it
as easy as possible to interface with modules which implement the DB API, the
value :const:`None` is written as the empty string. While this isn't a
reversible transformation, it makes it easier to dump SQL NULL data values to
CSV files without preprocessing the data returned from a ``cursor.fetch*`` call.
All other non-string data are stringified with :func:`str` before being written.
.. function:: register_dialect(name[, dialect][, fmtparam])
Associate *dialect* with *name*. *name* must be a string or Unicode object. The
dialect can be specified either by passing a sub-class of :class:`Dialect`, or
by *fmtparam* keyword arguments, or both, with keyword arguments overriding
parameters of the dialect. For full details about the dialect and formatting
parameters, see section :ref:`csv-fmt-params`, "Dialects and Formatting
Parameters".
.. function:: unregister_dialect(name)
Delete the dialect associated with *name* from the dialect registry. An
:exc:`Error` is raised if *name* is not a registered dialect name.
.. function:: get_dialect(name)
Return the dialect associated with *name*. An :exc:`Error` is raised if *name*
is not a registered dialect name.
.. function:: list_dialects()
Return the names of all registered dialects.
.. function:: field_size_limit([new_limit])
Returns the current maximum field size allowed by the parser. If *new_limit* is
given, this becomes the new limit.
.. versionadded:: 2.5
The :mod:`csv` module defines the following classes:
.. class:: DictReader(csvfile[, fieldnames=:const:`None`,[, restkey=:const:`None`[, restval=:const:`None`[, dialect=``'excel'``[, *args, **kwds]]]]])
Create an object which operates like a regular reader but maps the information
read into a dict whose keys are given by the optional *fieldnames* parameter.
If the *fieldnames* parameter is omitted, the values in the first row of the
*csvfile* will be used as the fieldnames. If the row read has fewer fields than
the fieldnames sequence, the value of *restval* will be used as the default
value. If the row read has more fields than the fieldnames sequence, the
remaining data is added as a sequence keyed by the value of *restkey*. If the
row read has fewer fields than the fieldnames sequence, the remaining keys take
the value of the optional *restval* parameter. Any other optional or keyword
arguments are passed to the underlying :class:`reader` instance.
.. class:: DictWriter(csvfile, fieldnames[, restval=""[, extrasaction=``'raise'``[, dialect=``'excel'``[, *args, **kwds]]]])
Create an object which operates like a regular writer but maps dictionaries onto
output rows. The *fieldnames* parameter identifies the order in which values in
the dictionary passed to the :meth:`writerow` method are written to the
*csvfile*. The optional *restval* parameter specifies the value to be written
if the dictionary is missing a key in *fieldnames*. If the dictionary passed to
the :meth:`writerow` method contains a key not found in *fieldnames*, the
optional *extrasaction* parameter indicates what action to take. If it is set
to ``'raise'`` a :exc:`ValueError` is raised. If it is set to ``'ignore'``,
extra values in the dictionary are ignored. Any other optional or keyword
arguments are passed to the underlying :class:`writer` instance.
Note that unlike the :class:`DictReader` class, the *fieldnames* parameter of
the :class:`DictWriter` is not optional. Since Python's :class:`dict` objects
are not ordered, there is not enough information available to deduce the order
in which the row should be written to the *csvfile*.
.. class:: Dialect
The :class:`Dialect` class is a container class relied on primarily for its
attributes, which are used to define the parameters for a specific
:class:`reader` or :class:`writer` instance.
.. class:: excel()
The :class:`excel` class defines the usual properties of an Excel-generated CSV
file. It is registered with the dialect name ``'excel'``.
.. class:: excel_tab()
The :class:`excel_tab` class defines the usual properties of an Excel-generated
TAB-delimited file. It is registered with the dialect name ``'excel-tab'``.
.. class:: Sniffer()
The :class:`Sniffer` class is used to deduce the format of a CSV file.
The :class:`Sniffer` class provides two methods:
.. method:: Sniffer.sniff(sample[,delimiters=None])
Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the
parameters found. If the optional *delimiters* parameter is given, it is
interpreted as a string containing possible valid delimiter characters.
.. method:: Sniffer.has_header(sample)
Analyze the sample text (presumed to be in CSV format) and return :const:`True`
if the first row appears to be a series of column headers.
The :mod:`csv` module defines the following constants:
.. data:: QUOTE_ALL
Instructs :class:`writer` objects to quote all fields.
.. data:: QUOTE_MINIMAL
Instructs :class:`writer` objects to only quote those fields which contain
special characters such as *delimiter*, *quotechar* or any of the characters in
*lineterminator*.
.. data:: QUOTE_NONNUMERIC
Instructs :class:`writer` objects to quote all non-numeric fields.
Instructs the reader to convert all non-quoted fields to type *float*.
.. data:: QUOTE_NONE
Instructs :class:`writer` objects to never quote fields. When the current
*delimiter* occurs in output data it is preceded by the current *escapechar*
character. If *escapechar* is not set, the writer will raise :exc:`Error` if
any characters that require escaping are encountered.
Instructs :class:`reader` to perform no special processing of quote characters.
The :mod:`csv` module defines the following exception:
.. exception:: Error
Raised by any of the functions when an error is detected.
.. _csv-fmt-params:
Dialects and Formatting Parameters
----------------------------------
To make it easier to specify the format of input and output records, specific
formatting parameters are grouped together into dialects. A dialect is a
subclass of the :class:`Dialect` class having a set of specific methods and a
single :meth:`validate` method. When creating :class:`reader` or
:class:`writer` objects, the programmer can specify a string or a subclass of
the :class:`Dialect` class as the dialect parameter. In addition to, or instead
of, the *dialect* parameter, the programmer can also specify individual
formatting parameters, which have the same names as the attributes defined below
for the :class:`Dialect` class.
Dialects support the following attributes:
.. attribute:: Dialect.delimiter
A one-character string used to separate fields. It defaults to ``','``.
.. attribute:: Dialect.doublequote
Controls how instances of *quotechar* appearing inside a field should be
themselves be quoted. When :const:`True`, the character is doubled. When
:const:`False`, the *escapechar* is used as a prefix to the *quotechar*. It
defaults to :const:`True`.
On output, if *doublequote* is :const:`False` and no *escapechar* is set,
:exc:`Error` is raised if a *quotechar* is found in a field.
.. attribute:: Dialect.escapechar
A one-character string used by the writer to escape the *delimiter* if *quoting*
is set to :const:`QUOTE_NONE` and the *quotechar* if *doublequote* is
:const:`False`. On reading, the *escapechar* removes any special meaning from
the following character. It defaults to :const:`None`, which disables escaping.
.. attribute:: Dialect.lineterminator
The string used to terminate lines produced by the :class:`writer`. It defaults
to ``'\r\n'``.
.. note::
The :class:`reader` is hard-coded to recognise either ``'\r'`` or ``'\n'`` as
end-of-line, and ignores *lineterminator*. This behavior may change in the
future.
.. attribute:: Dialect.quotechar
A one-character string used to quote fields containing special characters, such
as the *delimiter* or *quotechar*, or which contain new-line characters. It
defaults to ``'"'``.
.. attribute:: Dialect.quoting
Controls when quotes should be generated by the writer and recognised by the
reader. It can take on any of the :const:`QUOTE_\*` constants (see section
:ref:`csv-contents`) and defaults to :const:`QUOTE_MINIMAL`.
.. attribute:: Dialect.skipinitialspace
When :const:`True`, whitespace immediately following the *delimiter* is ignored.
The default is :const:`False`.
Reader Objects
--------------
Reader objects (:class:`DictReader` instances and objects returned by the
:func:`reader` function) have the following public methods:
.. method:: csv reader.next()
Return the next row of the reader's iterable object as a list, parsed according
to the current dialect.
Reader objects have the following public attributes:
.. attribute:: csv reader.dialect
A read-only description of the dialect in use by the parser.
.. attribute:: csv reader.line_num
The number of lines read from the source iterator. This is not the same as the
number of records returned, as records can span multiple lines.
.. versionadded:: 2.5
Writer Objects
--------------
:class:`Writer` objects (:class:`DictWriter` instances and objects returned by
the :func:`writer` function) have the following public methods. A *row* must be
a sequence of strings or numbers for :class:`Writer` objects and a dictionary
mapping fieldnames to strings or numbers (by passing them through :func:`str`
first) for :class:`DictWriter` objects. Note that complex numbers are written
out surrounded by parens. This may cause some problems for other programs which
read CSV files (assuming they support complex numbers at all).
.. method:: csv writer.writerow(row)
Write the *row* parameter to the writer's file object, formatted according to
the current dialect.
.. method:: csv writer.writerows(rows)
Write all the *rows* parameters (a list of *row* objects as described above) to
the writer's file object, formatted according to the current dialect.
Writer objects have the following public attribute:
.. attribute:: csv writer.dialect
A read-only description of the dialect in use by the writer.
.. _csv-examples:
Examples
--------
The simplest example of reading a CSV file::
import csv
reader = csv.reader(open("some.csv", "rb"))
for row in reader:
print row
Reading a file with an alternate format::
import csv
reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
for row in reader:
print row
The corresponding simplest possible writing example is::
import csv
writer = csv.writer(open("some.csv", "wb"))
writer.writerows(someiterable)
Registering a new dialect::
import csv
csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
reader = csv.reader(open("passwd", "rb"), 'unixpwd')
A slightly more advanced use of the reader --- catching and reporting errors::
import csv, sys
filename = "some.csv"
reader = csv.reader(open(filename, "rb"))
try:
for row in reader:
print row
except csv.Error as e:
sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
And while the module doesn't directly support parsing strings, it can easily be
done::
import csv
for row in csv.reader(['one,two,three']):
print row
The :mod:`csv` module doesn't directly support reading and writing Unicode, but
it is 8-bit-clean save for some problems with ASCII NUL characters. So you can
write functions or classes that handle the encoding and decoding for you as long
as you avoid encodings like UTF-16 that use NULs. UTF-8 is recommended.
:func:`unicode_csv_reader` below is a generator that wraps :class:`csv.reader`
to handle Unicode CSV data (a list of Unicode strings). :func:`utf_8_encoder`
is a generator that encodes the Unicode strings as UTF-8, one string (or row) at
a time. The encoded strings are parsed by the CSV reader, and
:func:`unicode_csv_reader` decodes the UTF-8-encoded cells back into Unicode::
import csv
def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs):
# csv.py doesn't do Unicode; encode temporarily as UTF-8:
csv_reader = csv.reader(utf_8_encoder(unicode_csv_data),
dialect=dialect, **kwargs)
for row in csv_reader:
# decode UTF-8 back to Unicode, cell by cell:
yield [unicode(cell, 'utf-8') for cell in row]
def utf_8_encoder(unicode_csv_data):
for line in unicode_csv_data:
yield line.encode('utf-8')
For all other encodings the following :class:`UnicodeReader` and
:class:`UnicodeWriter` classes can be used. They take an additional *encoding*
parameter in their constructor and make sure that the data passes the real
reader or writer encoded as UTF-8::
import csv, codecs, cStringIO
class UTF8Recoder:
"""
Iterator that reads an encoded stream and reencodes the input to UTF-8
"""
def __init__(self, f, encoding):
self.reader = codecs.getreader(encoding)(f)
def __iter__(self):
return self
def __next__(self):
return next(self.reader).encode("utf-8")
class UnicodeReader:
"""
A CSV reader which will iterate over lines in the CSV file "f",
which is encoded in the given encoding.
"""
def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
f = UTF8Recoder(f, encoding)
self.reader = csv.reader(f, dialect=dialect, **kwds)
def __next__(self):
row = next(self.reader)
return [unicode(s, "utf-8") for s in row]
def __iter__(self):
return self
class UnicodeWriter:
"""
A CSV writer which will write rows to CSV file "f",
which is encoded in the given encoding.
"""
def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
# Redirect output to a queue
self.queue = cStringIO.StringIO()
self.writer = csv.writer(self.queue, dialect=dialect, **kwds)
self.stream = f
self.encoder = codecs.getincrementalencoder(encoding)()
def writerow(self, row):
self.writer.writerow([s.encode("utf-8") for s in row])
# Fetch UTF-8 output from the queue ...
data = self.queue.getvalue()
data = data.decode("utf-8")
# ... and reencode it into the target encoding
data = self.encoder.encode(data)
# write to the target stream
self.stream.write(data)
# empty queue
self.queue.truncate(0)
def writerows(self, rows):
for row in rows:
self.writerow(row)

2364
Doc-3k/library/ctypes.rst Normal file
View File

File diff suppressed because it is too large Load Diff

228
Doc-3k/library/curses.ascii.rst Normal file
View File

@@ -0,0 +1,228 @@
:mod:`curses.ascii` --- Utilities for ASCII characters
======================================================
.. module:: curses.ascii
:synopsis: Constants and set-membership functions for ASCII characters.
.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
.. sectionauthor:: Eric S. Raymond <esr@thyrsus.com>
.. versionadded:: 1.6
The :mod:`curses.ascii` module supplies name constants for ASCII characters and
functions to test membership in various ASCII character classes. The constants
supplied are names for control characters as follows:
+--------------+----------------------------------------------+
| Name | Meaning |
+==============+==============================================+
| :const:`NUL` | |
+--------------+----------------------------------------------+
| :const:`SOH` | Start of heading, console interrupt |
+--------------+----------------------------------------------+
| :const:`STX` | Start of text |
+--------------+----------------------------------------------+
| :const:`ETX` | End of text |
+--------------+----------------------------------------------+
| :const:`EOT` | End of transmission |
+--------------+----------------------------------------------+
| :const:`ENQ` | Enquiry, goes with :const:`ACK` flow control |
+--------------+----------------------------------------------+
| :const:`ACK` | Acknowledgement |
+--------------+----------------------------------------------+
| :const:`BEL` | Bell |
+--------------+----------------------------------------------+
| :const:`BS` | Backspace |
+--------------+----------------------------------------------+
| :const:`TAB` | Tab |
+--------------+----------------------------------------------+
| :const:`HT` | Alias for :const:`TAB`: "Horizontal tab" |
+--------------+----------------------------------------------+
| :const:`LF` | Line feed |
+--------------+----------------------------------------------+
| :const:`NL` | Alias for :const:`LF`: "New line" |
+--------------+----------------------------------------------+
| :const:`VT` | Vertical tab |
+--------------+----------------------------------------------+
| :const:`FF` | Form feed |
+--------------+----------------------------------------------+
| :const:`CR` | Carriage return |
+--------------+----------------------------------------------+
| :const:`SO` | Shift-out, begin alternate character set |
+--------------+----------------------------------------------+
| :const:`SI` | Shift-in, resume default character set |
+--------------+----------------------------------------------+
| :const:`DLE` | Data-link escape |
+--------------+----------------------------------------------+
| :const:`DC1` | XON, for flow control |
+--------------+----------------------------------------------+
| :const:`DC2` | Device control 2, block-mode flow control |
+--------------+----------------------------------------------+
| :const:`DC3` | XOFF, for flow control |
+--------------+----------------------------------------------+
| :const:`DC4` | Device control 4 |
+--------------+----------------------------------------------+
| :const:`NAK` | Negative acknowledgement |
+--------------+----------------------------------------------+
| :const:`SYN` | Synchronous idle |
+--------------+----------------------------------------------+
| :const:`ETB` | End transmission block |
+--------------+----------------------------------------------+
| :const:`CAN` | Cancel |
+--------------+----------------------------------------------+
| :const:`EM` | End of medium |
+--------------+----------------------------------------------+
| :const:`SUB` | Substitute |
+--------------+----------------------------------------------+
| :const:`ESC` | Escape |
+--------------+----------------------------------------------+
| :const:`FS` | File separator |
+--------------+----------------------------------------------+
| :const:`GS` | Group separator |
+--------------+----------------------------------------------+
| :const:`RS` | Record separator, block-mode terminator |
+--------------+----------------------------------------------+
| :const:`US` | Unit separator |
+--------------+----------------------------------------------+
| :const:`SP` | Space |
+--------------+----------------------------------------------+
| :const:`DEL` | Delete |
+--------------+----------------------------------------------+
Note that many of these have little practical significance in modern usage. The
mnemonics derive from teleprinter conventions that predate digital computers.
The module supplies the following functions, patterned on those in the standard
C library:
.. function:: isalnum(c)
Checks for an ASCII alphanumeric character; it is equivalent to ``isalpha(c) or
isdigit(c)``.
.. function:: isalpha(c)
Checks for an ASCII alphabetic character; it is equivalent to ``isupper(c) or
islower(c)``.
.. function:: isascii(c)
Checks for a character value that fits in the 7-bit ASCII set.
.. function:: isblank(c)
Checks for an ASCII whitespace character.
.. function:: iscntrl(c)
Checks for an ASCII control character (in the range 0x00 to 0x1f).
.. function:: isdigit(c)
Checks for an ASCII decimal digit, ``'0'`` through ``'9'``. This is equivalent
to ``c in string.digits``.
.. function:: isgraph(c)
Checks for ASCII any printable character except space.
.. function:: islower(c)
Checks for an ASCII lower-case character.
.. function:: isprint(c)
Checks for any ASCII printable character including space.
.. function:: ispunct(c)
Checks for any printable ASCII character which is not a space or an alphanumeric
character.
.. function:: isspace(c)
Checks for ASCII white-space characters; space, line feed, carriage return, form
feed, horizontal tab, vertical tab.
.. function:: isupper(c)
Checks for an ASCII uppercase letter.
.. function:: isxdigit(c)
Checks for an ASCII hexadecimal digit. This is equivalent to ``c in
string.hexdigits``.
.. function:: isctrl(c)
Checks for an ASCII control character (ordinal values 0 to 31).
.. function:: ismeta(c)
Checks for a non-ASCII character (ordinal values 0x80 and above).
These functions accept either integers or strings; when the argument is a
string, it is first converted using the built-in function :func:`ord`.
Note that all these functions check ordinal bit values derived from the first
character of the string you pass in; they do not actually know anything about
the host machine's character encoding. For functions that know about the
character encoding (and handle internationalization properly) see the
:mod:`string` module.
The following two functions take either a single-character string or integer
byte value; they return a value of the same type.
.. function:: ascii(c)
Return the ASCII value corresponding to the low 7 bits of *c*.
.. function:: ctrl(c)
Return the control character corresponding to the given character (the character
bit value is bitwise-anded with 0x1f).
.. function:: alt(c)
Return the 8-bit character corresponding to the given ASCII character (the
character bit value is bitwise-ored with 0x80).
The following function takes either a single-character string or integer value;
it returns a string.
.. function:: unctrl(c)
Return a string representation of the ASCII character *c*. If *c* is printable,
this string is the character itself. If the character is a control character
(0x00-0x1f) the string consists of a caret (``'^'``) followed by the
corresponding uppercase letter. If the character is an ASCII delete (0x7f) the
string is ``'^?'``. If the character has its meta bit (0x80) set, the meta bit
is stripped, the preceding rules applied, and ``'!'`` prepended to the result.
.. data:: controlnames
A 33-element string array that contains the ASCII mnemonics for the thirty-two
ASCII control characters from 0 (NUL) to 0x1f (US), in order, plus the mnemonic
``SP`` for the space character.

119
Doc-3k/library/curses.panel.rst Normal file
View File

@@ -0,0 +1,119 @@
:mod:`curses.panel` --- A panel stack extension for curses.
===========================================================
.. module:: curses.panel
:synopsis: A panel stack extension that adds depth to curses windows.
.. sectionauthor:: A.M. Kuchling <amk@amk.ca>
Panels are windows with the added feature of depth, so they can be stacked on
top of each other, and only the visible portions of each window will be
displayed. Panels can be added, moved up or down in the stack, and removed.
.. _cursespanel-functions:
Functions
---------
The module :mod:`curses.panel` defines the following functions:
.. function:: bottom_panel()
Returns the bottom panel in the panel stack.
.. function:: new_panel(win)
Returns a panel object, associating it with the given window *win*. Be aware
that you need to keep the returned panel object referenced explicitly. If you
don't, the panel object is garbage collected and removed from the panel stack.
.. function:: top_panel()
Returns the top panel in the panel stack.
.. function:: update_panels()
Updates the virtual screen after changes in the panel stack. This does not call
:func:`curses.doupdate`, so you'll have to do this yourself.
.. _curses-panel-objects:
Panel Objects
-------------
Panel objects, as returned by :func:`new_panel` above, are windows with a
stacking order. There's always a window associated with a panel which determines
the content, while the panel methods are responsible for the window's depth in
the panel stack.
Panel objects have the following methods:
.. method:: Panel.above()
Returns the panel above the current panel.
.. method:: Panel.below()
Returns the panel below the current panel.
.. method:: Panel.bottom()
Push the panel to the bottom of the stack.
.. method:: Panel.hidden()
Returns true if the panel is hidden (not visible), false otherwise.
.. method:: Panel.hide()
Hide the panel. This does not delete the object, it just makes the window on
screen invisible.
.. method:: Panel.move(y, x)
Move the panel to the screen coordinates ``(y, x)``.
.. method:: Panel.replace(win)
Change the window associated with the panel to the window *win*.
.. method:: Panel.set_userptr(obj)
Set the panel's user pointer to *obj*. This is used to associate an arbitrary
piece of data with the panel, and can be any Python object.
.. method:: Panel.show()
Display the panel (which might have been hidden).
.. method:: Panel.top()
Push panel to the top of the stack.
.. method:: Panel.userptr()
Returns the user pointer for the panel. This might be any Python object.
.. method:: Panel.window()
Returns the window object associated with the panel.

1679
Doc-3k/library/curses.rst Normal file
View File

File diff suppressed because it is too large Load Diff

20
Doc-3k/library/custominterp.rst Normal file
View File

@@ -0,0 +1,20 @@
.. _custominterp:
**************************
Custom Python Interpreters
**************************
The modules described in this chapter allow writing interfaces similar to
Python's interactive interpreter. If you want a Python interpreter that
supports some special feature in addition to the Python language, you should
look at the :mod:`code` module. (The :mod:`codeop` module is lower-level, used
to support compiling a possibly-incomplete chunk of Python code.)
The full list of modules described in this chapter is:
.. toctree::
code.rst
codeop.rst

32
Doc-3k/library/datatypes.rst Normal file
View File

@@ -0,0 +1,32 @@
.. _datatypes:
**********
Data Types
**********
The modules described in this chapter provide a variety of specialized data
types such as dates and times, fixed-type arrays, heap queues, synchronized
queues, and sets.
The following modules are documented in this chapter:
.. toctree::
datetime.rst
calendar.rst
collections.rst
heapq.rst
bisect.rst
array.rst
sched.rst
mutex.rst
queue.rst
weakref.rst
userdict.rst
types.rst
new.rst
copy.rst
pprint.rst
repr.rst

1363
Doc-3k/library/datetime.rst Normal file
View File

File diff suppressed because it is too large Load Diff

98
Doc-3k/library/dbhash.rst Normal file
View File

@@ -0,0 +1,98 @@
:mod:`dbhash` --- DBM-style interface to the BSD database library
=================================================================
.. module:: dbhash
:synopsis: DBM-style interface to the BSD database library.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. index:: module: bsddb
The :mod:`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 :mod:`bsddb` module is
required to use :mod:`dbhash`.
This module provides an exception and a function:
.. exception:: error
Exception raised on database errors other than :exc:`KeyError`. It is a synonym
for :exc:`bsddb.error`.
.. function:: 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.
.. seealso::
Module :mod:`anydbm`
Generic interface to ``dbm``\ -style databases.
Module :mod:`bsddb`
Lower-level interface to the BSD ``db`` library.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.
.. _dbhash-objects:
Database Objects
----------------
The database objects returned by :func:`open` provide the methods common to all
the DBM-style databases and mapping objects. The following methods are
available in addition to the standard methods.
.. method:: dbhash.first()
It's possible to loop over every key/value pair in the database using this
method and the :meth:`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.
.. method:: dbhash.last()
Return the last key/value pair in a database traversal. This may be used to
begin a reverse-order traversal; see :meth:`previous`.
.. method:: dbhash.next()
Returns the key next key/value pair in a database traversal. The following code
prints every key in the database ``db``, without having to create a list in
memory that contains them all::
print db.first()
for i in range(1, len(db)):
print db.next()
.. method:: dbhash.previous()
Returns the previous key/value pair in a forward-traversal of the database. In
conjunction with :meth:`last`, this may be used to implement a reverse-order
traversal.
.. method:: dbhash.sync()
This method forces any unwritten data to be written to the disk.

73
Doc-3k/library/dbm.rst Normal file
View File

@@ -0,0 +1,73 @@
:mod:`dbm` --- Simple "database" interface
==========================================
.. module:: dbm
:platform: Unix
:synopsis: The standard "database" interface, based on ndbm.
The :mod:`dbm` module provides an interface to the Unix (``n``)``dbm`` library.
Dbm objects behave like mappings (dictionaries), except that keys and values are
always strings. Printing a dbm object doesn't print the keys and values, and the
:meth:`items` and :meth:`values` methods are not supported.
This module can be used with the "classic" ndbm interface, the BSD DB
compatibility interface, or the GNU GDBM compatibility interface. On Unix, the
:program:`configure` script will attempt to locate the appropriate header file
to simplify building this module.
The module defines the following:
.. exception:: error
Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised for
general mapping errors like specifying an incorrect key.
.. data:: library
Name of the ``ndbm`` implementation library used.
.. function:: open(filename[, flag[, mode]])
Open a dbm database and return a dbm object. The *filename* argument is the
name of the database file (without the :file:`.dir` or :file:`.pag` extensions;
note that the BSD DB implementation of the interface will append the extension
:file:`.db` and only create one file).
The optional *flag* argument must be one of these values:
+---------+-------------------------------------------+
| Value | Meaning |
+=========+===========================================+
| ``'r'`` | Open existing database for reading only |
| | (default) |
+---------+-------------------------------------------+
| ``'w'`` | Open existing database for reading and |
| | writing |
+---------+-------------------------------------------+
| ``'c'`` | Open database for reading and writing, |
| | creating it if it doesn't exist |
+---------+-------------------------------------------+
| ``'n'`` | Always create a new, empty database, open |
| | for reading and writing |
+---------+-------------------------------------------+
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``.
.. seealso::
Module :mod:`anydbm`
Generic interface to ``dbm``\ -style databases.
Module :mod:`gdbm`
Similar interface to the GNU GDBM library.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.

1295
Doc-3k/library/decimal.rst Normal file
View File

File diff suppressed because it is too large Load Diff

22
Doc-3k/library/development.rst Normal file
View File

@@ -0,0 +1,22 @@
.. _development:
*****************
Development Tools
*****************
The modules described in this chapter help you write software. For example, the
:mod:`pydoc` module takes a module and generates documentation based on the
module's contents. The :mod:`doctest` and :mod:`unittest` modules contains
frameworks for writing unit tests that automatically exercise code and verify
that the expected output is produced.
The list of modules described in this chapter is:
.. toctree::
pydoc.rst
doctest.rst
unittest.rst
test.rst

644
Doc-3k/library/difflib.rst Normal file
View File

@@ -0,0 +1,644 @@
:mod:`difflib` --- Helpers for computing deltas
===============================================
.. module:: difflib
:synopsis: Helpers for computing differences between objects.
.. moduleauthor:: Tim Peters <tim_one@users.sourceforge.net>
.. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net>
.. % LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>.
.. versionadded:: 2.1
.. class:: SequenceMatcher
This is a flexible class for comparing pairs of sequences of any type, so long
as the sequence elements are hashable. The basic algorithm predates, and is a
little fancier than, an algorithm published in the late 1980's by Ratcliff and
Obershelp under the hyperbolic name "gestalt pattern matching." The idea is to
find the longest contiguous matching subsequence that contains no "junk"
elements (the Ratcliff and Obershelp algorithm doesn't address junk). The same
idea is then applied recursively to the pieces of the sequences to the left and
to the right of the matching subsequence. This does not yield minimal edit
sequences, but does tend to yield matches that "look right" to people.
**Timing:** The basic Ratcliff-Obershelp algorithm is cubic time in the worst
case and quadratic time in the expected case. :class:`SequenceMatcher` is
quadratic time for the worst case and has expected-case behavior dependent in a
complicated way on how many elements the sequences have in common; best case
time is linear.
.. class:: Differ
This is a class for comparing sequences of lines of text, and producing human-
readable differences or deltas. Differ uses :class:`SequenceMatcher` both to
compare sequences of lines, and to compare sequences of characters within
similar (near-matching) lines.
Each line of a :class:`Differ` delta begins with a two-letter code:
+----------+-------------------------------------------+
| Code | Meaning |
+==========+===========================================+
| ``'- '`` | line unique to sequence 1 |
+----------+-------------------------------------------+
| ``'+ '`` | line unique to sequence 2 |
+----------+-------------------------------------------+
| ``' '`` | line common to both sequences |
+----------+-------------------------------------------+
| ``'? '`` | line not present in either input sequence |
+----------+-------------------------------------------+
Lines beginning with '``?``' attempt to guide the eye to intraline differences,
and were not present in either input sequence. These lines can be confusing if
the sequences contain tab characters.
.. class:: HtmlDiff
This class can be used to create an HTML table (or a complete HTML file
containing the table) showing a side by side, line by line comparison of text
with inter-line and intra-line change highlights. The table can be generated in
either full or contextual difference mode.
The constructor for this class is:
.. function:: __init__([tabsize][, wrapcolumn][, linejunk][, charjunk])
Initializes instance of :class:`HtmlDiff`.
*tabsize* is an optional keyword argument to specify tab stop spacing and
defaults to ``8``.
*wrapcolumn* is an optional keyword to specify column number where lines are
broken and wrapped, defaults to ``None`` where lines are not wrapped.
*linejunk* and *charjunk* are optional keyword arguments passed into ``ndiff()``
(used by :class:`HtmlDiff` to generate the side by side HTML differences). See
``ndiff()`` documentation for argument default values and descriptions.
The following methods are public:
.. function:: make_file(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
Compares *fromlines* and *tolines* (lists of strings) and returns a string which
is a complete HTML file containing a table showing line by line differences with
inter-line and intra-line changes highlighted.
*fromdesc* and *todesc* are optional keyword arguments to specify from/to file
column header strings (both default to an empty string).
*context* and *numlines* are both optional keyword arguments. Set *context* to
``True`` when contextual differences are to be shown, else the default is
``False`` to show the full files. *numlines* defaults to ``5``. When *context*
is ``True`` *numlines* controls the number of context lines which surround the
difference highlights. When *context* is ``False`` *numlines* controls the
number of lines which are shown before a difference highlight when using the
"next" hyperlinks (setting to zero would cause the "next" hyperlinks to place
the next difference highlight at the top of the browser without any leading
context).
.. function:: make_table(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
Compares *fromlines* and *tolines* (lists of strings) and returns a string which
is a complete HTML table showing line by line differences with inter-line and
intra-line changes highlighted.
The arguments for this method are the same as those for the :meth:`make_file`
method.
:file:`Tools/scripts/diff.py` is a command-line front-end to this class and
contains a good example of its use.
.. versionadded:: 2.4
.. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
Compare *a* and *b* (lists of strings); return a delta (a generator generating
the delta lines) in context diff format.
Context diffs are a compact way of showing just the lines that have changed plus
a few lines of context. The changes are shown in a before/after style. The
number of context lines is set by *n* which defaults to three.
By default, the diff control lines (those with ``***`` or ``---``) are created
with a trailing newline. This is helpful so that inputs created from
:func:`file.readlines` result in diffs that are suitable for use with
:func:`file.writelines` since both the inputs and outputs have trailing
newlines.
For inputs that do not have trailing newlines, set the *lineterm* argument to
``""`` so that the output will be uniformly newline free.
The context diff format normally has a header for filenames and modification
times. Any or all of these may be specified using strings for *fromfile*,
*tofile*, *fromfiledate*, and *tofiledate*. The modification times are normally
expressed in the format returned by :func:`time.ctime`. If not specified, the
strings default to blanks.
:file:`Tools/scripts/diff.py` is a command-line front-end for this function.
.. versionadded:: 2.3
.. function:: get_close_matches(word, possibilities[, n][, cutoff])
Return a list of the best "good enough" matches. *word* is a sequence for which
close matches are desired (typically a string), and *possibilities* is a list of
sequences against which to match *word* (typically a list of strings).
Optional argument *n* (default ``3``) is the maximum number of close matches to
return; *n* must be greater than ``0``.
Optional argument *cutoff* (default ``0.6``) is a float in the range [0, 1].
Possibilities that don't score at least that similar to *word* are ignored.
The best (no more than *n*) matches among the possibilities are returned in a
list, sorted by similarity score, most similar first. ::
>>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
['apple', 'ape']
>>> import keyword
>>> get_close_matches('wheel', keyword.kwlist)
['while']
>>> get_close_matches('apple', keyword.kwlist)
[]
>>> get_close_matches('accept', keyword.kwlist)
['except']
.. function:: ndiff(a, b[, linejunk][, charjunk])
Compare *a* and *b* (lists of strings); return a :class:`Differ`\ -style delta
(a generator generating the delta lines).
Optional keyword parameters *linejunk* and *charjunk* are for filter functions
(or ``None``):
*linejunk*: A function that accepts a single string argument, and returns true
if the string is junk, or false if not. The default is (``None``), starting with
Python 2.3. Before then, the default was the module-level function
:func:`IS_LINE_JUNK`, which filters out lines without visible characters, except
for at most one pound character (``'#'``). As of Python 2.3, the underlying
:class:`SequenceMatcher` class does a dynamic analysis of which lines are so
frequent as to constitute noise, and this usually works better than the pre-2.3
default.
*charjunk*: A function that accepts a character (a string of length 1), and
returns if the character is junk, or false if not. The default is module-level
function :func:`IS_CHARACTER_JUNK`, which filters out whitespace characters (a
blank or tab; note: bad idea to include newline in this!).
:file:`Tools/scripts/ndiff.py` is a command-line front-end to this function. ::
>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
... 'ore\ntree\nemu\n'.splitlines(1))
>>> print ''.join(diff),
- one
? ^
+ ore
? ^
- two
- three
? -
+ tree
+ emu
.. function:: restore(sequence, which)
Return one of the two sequences that generated a delta.
Given a *sequence* produced by :meth:`Differ.compare` or :func:`ndiff`, extract
lines originating from file 1 or 2 (parameter *which*), stripping off line
prefixes.
Example::
>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
... 'ore\ntree\nemu\n'.splitlines(1))
>>> diff = list(diff) # materialize the generated delta into a list
>>> print ''.join(restore(diff, 1)),
one
two
three
>>> print ''.join(restore(diff, 2)),
ore
tree
emu
.. function:: unified_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
Compare *a* and *b* (lists of strings); return a delta (a generator generating
the delta lines) in unified diff format.
Unified diffs are a compact way of showing just the lines that have changed plus
a few lines of context. The changes are shown in a inline style (instead of
separate before/after blocks). The number of context lines is set by *n* which
defaults to three.
By default, the diff control lines (those with ``---``, ``+++``, or ``@@``) are
created with a trailing newline. This is helpful so that inputs created from
:func:`file.readlines` result in diffs that are suitable for use with
:func:`file.writelines` since both the inputs and outputs have trailing
newlines.
For inputs that do not have trailing newlines, set the *lineterm* argument to
``""`` so that the output will be uniformly newline free.
The context diff format normally has a header for filenames and modification
times. Any or all of these may be specified using strings for *fromfile*,
*tofile*, *fromfiledate*, and *tofiledate*. The modification times are normally
expressed in the format returned by :func:`time.ctime`. If not specified, the
strings default to blanks.
:file:`Tools/scripts/diff.py` is a command-line front-end for this function.
.. versionadded:: 2.3
.. function:: IS_LINE_JUNK(line)
Return true for ignorable lines. The line *line* is ignorable if *line* is
blank or contains a single ``'#'``, otherwise it is not ignorable. Used as a
default for parameter *linejunk* in :func:`ndiff` before Python 2.3.
.. function:: IS_CHARACTER_JUNK(ch)
Return true for ignorable characters. The character *ch* is ignorable if *ch*
is a space or tab, otherwise it is not ignorable. Used as a default for
parameter *charjunk* in :func:`ndiff`.
.. seealso::
`Pattern Matching: The Gestalt Approach <http://www.ddj.com/184407970?pgno=5>`_
Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. This
was published in `Dr. Dobb's Journal <http://www.ddj.com/>`_ in July, 1988.
.. _sequence-matcher:
SequenceMatcher Objects
-----------------------
The :class:`SequenceMatcher` class has this constructor:
.. class:: SequenceMatcher([isjunk[, a[, b]]])
Optional argument *isjunk* must be ``None`` (the default) or a one-argument
function that takes a sequence element and returns true if and only if the
element is "junk" and should be ignored. Passing ``None`` for *isjunk* is
equivalent to passing ``lambda x: 0``; in other words, no elements are ignored.
For example, pass::
lambda x: x in " \t"
if you're comparing lines as sequences of characters, and don't want to synch up
on blanks or hard tabs.
The optional arguments *a* and *b* are sequences to be compared; both default to
empty strings. The elements of both sequences must be hashable.
:class:`SequenceMatcher` objects have the following methods:
.. method:: SequenceMatcher.set_seqs(a, b)
Set the two sequences to be compared.
:class:`SequenceMatcher` computes and caches detailed information about the
second sequence, so if you want to compare one sequence against many sequences,
use :meth:`set_seq2` to set the commonly used sequence once and call
:meth:`set_seq1` repeatedly, once for each of the other sequences.
.. method:: SequenceMatcher.set_seq1(a)
Set the first sequence to be compared. The second sequence to be compared is
not changed.
.. method:: SequenceMatcher.set_seq2(b)
Set the second sequence to be compared. The first sequence to be compared is
not changed.
.. method:: SequenceMatcher.find_longest_match(alo, ahi, blo, bhi)
Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``.
If *isjunk* was omitted or ``None``, :meth:`get_longest_match` returns ``(i, j,
k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo <= i <= i+k <=
ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j', k')`` meeting those
conditions, the additional conditions ``k >= k'``, ``i <= i'``, and if ``i ==
i'``, ``j <= j'`` are also met. In other words, of all maximal matching blocks,
return one that starts earliest in *a*, and of all those maximal matching blocks
that start earliest in *a*, return the one that starts earliest in *b*. ::
>>> s = SequenceMatcher(None, " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
(0, 4, 5)
If *isjunk* was provided, first the longest matching block is determined as
above, but with the additional restriction that no junk element appears in the
block. Then that block is extended as far as possible by matching (only) junk
elements on both sides. So the resulting block never matches on junk except as
identical junk happens to be adjacent to an interesting match.
Here's the same example as before, but considering blanks to be junk. That
prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the second
sequence directly. Instead only the ``'abcd'`` can match, and matches the
leftmost ``'abcd'`` in the second sequence::
>>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
(1, 0, 4)
If no blocks match, this returns ``(alo, blo, 0)``.
.. method:: SequenceMatcher.get_matching_blocks()
Return list of triples describing matching subsequences. Each triple is of the
form ``(i, j, n)``, and means that ``a[i:i+n] == b[j:j+n]``. The triples are
monotonically increasing in *i* and *j*.
The last triple is a dummy, and has the value ``(len(a), len(b), 0)``. It is
the only triple with ``n == 0``. If ``(i, j, n)`` and ``(i', j', n')`` are
adjacent triples in the list, and the second is not the last triple in the list,
then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent triples always
describe non-adjacent equal blocks.
.. % Explain why a dummy is used!
.. versionchanged:: 2.5
The guarantee that adjacent triples always describe non-adjacent blocks was
implemented.
::
>>> s = SequenceMatcher(None, "abxcd", "abcd")
>>> s.get_matching_blocks()
[(0, 0, 2), (3, 2, 2), (5, 4, 0)]
.. method:: SequenceMatcher.get_opcodes()
Return list of 5-tuples describing how to turn *a* into *b*. Each tuple is of
the form ``(tag, i1, i2, j1, j2)``. The first tuple has ``i1 == j1 == 0``, and
remaining tuples have *i1* equal to the *i2* from the preceding tuple, and,
likewise, *j1* equal to the previous *j2*.
The *tag* values are strings, with these meanings:
+---------------+---------------------------------------------+
| Value | Meaning |
+===============+=============================================+
| ``'replace'`` | ``a[i1:i2]`` should be replaced by |
| | ``b[j1:j2]``. |
+---------------+---------------------------------------------+
| ``'delete'`` | ``a[i1:i2]`` should be deleted. Note that |
| | ``j1 == j2`` in this case. |
+---------------+---------------------------------------------+
| ``'insert'`` | ``b[j1:j2]`` should be inserted at |
| | ``a[i1:i1]``. Note that ``i1 == i2`` in |
| | this case. |
+---------------+---------------------------------------------+
| ``'equal'`` | ``a[i1:i2] == b[j1:j2]`` (the sub-sequences |
| | are equal). |
+---------------+---------------------------------------------+
For example::
>>> a = "qabxcd"
>>> b = "abycdf"
>>> s = SequenceMatcher(None, a, b)
>>> for tag, i1, i2, j1, j2 in s.get_opcodes():
... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))
delete a[0:1] (q) b[0:0] ()
equal a[1:3] (ab) b[0:2] (ab)
replace a[3:4] (x) b[2:3] (y)
equal a[4:6] (cd) b[3:5] (cd)
insert a[6:6] () b[5:6] (f)
.. method:: SequenceMatcher.get_grouped_opcodes([n])
Return a generator of groups with up to *n* lines of context.
Starting with the groups returned by :meth:`get_opcodes`, this method splits out
smaller change clusters and eliminates intervening ranges which have no changes.
The groups are returned in the same format as :meth:`get_opcodes`.
.. versionadded:: 2.3
.. method:: SequenceMatcher.ratio()
Return a measure of the sequences' similarity as a float in the range [0, 1].
Where T is the total number of elements in both sequences, and M is the number
of matches, this is 2.0\*M / T. Note that this is ``1.0`` if the sequences are
identical, and ``0.0`` if they have nothing in common.
This is expensive to compute if :meth:`get_matching_blocks` or
:meth:`get_opcodes` hasn't already been called, in which case you may want to
try :meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an upper bound.
.. method:: SequenceMatcher.quick_ratio()
Return an upper bound on :meth:`ratio` relatively quickly.
This isn't defined beyond that it is an upper bound on :meth:`ratio`, and is
faster to compute.
.. method:: SequenceMatcher.real_quick_ratio()
Return an upper bound on :meth:`ratio` very quickly.
This isn't defined beyond that it is an upper bound on :meth:`ratio`, and is
faster to compute than either :meth:`ratio` or :meth:`quick_ratio`.
The three methods that return the ratio of matching to total characters can give
different results due to differing levels of approximation, although
:meth:`quick_ratio` and :meth:`real_quick_ratio` are always at least as large as
:meth:`ratio`::
>>> s = SequenceMatcher(None, "abcd", "bcde")
>>> s.ratio()
0.75
>>> s.quick_ratio()
0.75
>>> s.real_quick_ratio()
1.0
.. _sequencematcher-examples:
SequenceMatcher Examples
------------------------
This example compares two strings, considering blanks to be "junk:" ::
>>> s = SequenceMatcher(lambda x: x == " ",
... "private Thread currentThread;",
... "private volatile Thread currentThread;")
:meth:`ratio` returns a float in [0, 1], measuring the similarity of the
sequences. As a rule of thumb, a :meth:`ratio` value over 0.6 means the
sequences are close matches::
>>> print round(s.ratio(), 3)
0.866
If you're only interested in where the sequences match,
:meth:`get_matching_blocks` is handy::
>>> for block in s.get_matching_blocks():
... print "a[%d] and b[%d] match for %d elements" % block
a[0] and b[0] match for 8 elements
a[8] and b[17] match for 6 elements
a[14] and b[23] match for 15 elements
a[29] and b[38] match for 0 elements
Note that the last tuple returned by :meth:`get_matching_blocks` is always a
dummy, ``(len(a), len(b), 0)``, and this is the only case in which the last
tuple element (number of elements matched) is ``0``.
If you want to know how to change the first sequence into the second, use
:meth:`get_opcodes`::
>>> for opcode in s.get_opcodes():
... print "%6s a[%d:%d] b[%d:%d]" % opcode
equal a[0:8] b[0:8]
insert a[8:8] b[8:17]
equal a[8:14] b[17:23]
equal a[14:29] b[23:38]
See also the function :func:`get_close_matches` in this module, which shows how
simple code building on :class:`SequenceMatcher` can be used to do useful work.
.. _differ-objects:
Differ Objects
--------------
Note that :class:`Differ`\ -generated deltas make no claim to be **minimal**
diffs. To the contrary, minimal diffs are often counter-intuitive, because they
synch up anywhere possible, sometimes accidental matches 100 pages apart.
Restricting synch points to contiguous matches preserves some notion of
locality, at the occasional cost of producing a longer diff.
The :class:`Differ` class has this constructor:
.. class:: Differ([linejunk[, charjunk]])
Optional keyword parameters *linejunk* and *charjunk* are for filter functions
(or ``None``):
*linejunk*: A function that accepts a single string argument, and returns true
if the string is junk. The default is ``None``, meaning that no line is
considered junk.
*charjunk*: A function that accepts a single character argument (a string of
length 1), and returns true if the character is junk. The default is ``None``,
meaning that no character is considered junk.
:class:`Differ` objects are used (deltas generated) via a single method:
.. method:: Differ.compare(a, b)
Compare two sequences of lines, and generate the delta (a sequence of lines).
Each sequence must contain individual single-line strings ending with newlines.
Such sequences can be obtained from the :meth:`readlines` method of file-like
objects. The delta generated also consists of newline-terminated strings, ready
to be printed as-is via the :meth:`writelines` method of a file-like object.
.. _differ-examples:
Differ Example
--------------
This example compares two texts. First we set up the texts, sequences of
individual single-line strings ending with newlines (such sequences can also be
obtained from the :meth:`readlines` method of file-like objects)::
>>> text1 = ''' 1. Beautiful is better than ugly.
... 2. Explicit is better than implicit.
... 3. Simple is better than complex.
... 4. Complex is better than complicated.
... '''.splitlines(1)
>>> len(text1)
4
>>> text1[0][-1]
'\n'
>>> text2 = ''' 1. Beautiful is better than ugly.
... 3. Simple is better than complex.
... 4. Complicated is better than complex.
... 5. Flat is better than nested.
... '''.splitlines(1)
Next we instantiate a Differ object::
>>> d = Differ()
Note that when instantiating a :class:`Differ` object we may pass functions to
filter out line and character "junk." See the :meth:`Differ` constructor for
details.
Finally, we compare the two::
>>> result = list(d.compare(text1, text2))
``result`` is a list of strings, so let's pretty-print it::
>>> from pprint import pprint
>>> pprint(result)
[' 1. Beautiful is better than ugly.\n',
'- 2. Explicit is better than implicit.\n',
'- 3. Simple is better than complex.\n',
'+ 3. Simple is better than complex.\n',
'? ++ \n',
'- 4. Complex is better than complicated.\n',
'? ^ ---- ^ \n',
'+ 4. Complicated is better than complex.\n',
'? ++++ ^ ^ \n',
'+ 5. Flat is better than nested.\n']
As a single multi-line string it looks like this::
>>> import sys
>>> sys.stdout.writelines(result)
1. Beautiful is better than ugly.
- 2. Explicit is better than implicit.
- 3. Simple is better than complex.
+ 3. Simple is better than complex.
? ++
- 4. Complex is better than complicated.
? ^ ---- ^
+ 4. Complicated is better than complex.
? ++++ ^ ^
+ 5. Flat is better than nested.

56
Doc-3k/library/dircache.rst Normal file
View File

@@ -0,0 +1,56 @@
:mod:`dircache` --- Cached directory listings
=============================================
.. module:: dircache
:synopsis: Return directory listing, with cache mechanism.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`dircache` module defines a function for reading directory listing
using a cache, and cache invalidation using the *mtime* of the directory.
Additionally, it defines a function to annotate directories by appending a
slash.
The :mod:`dircache` module defines the following functions:
.. function:: reset()
Resets the directory cache.
.. function:: listdir(path)
Return a directory listing of *path*, as gotten from :func:`os.listdir`. Note
that unless *path* changes, further call to :func:`listdir` will not re-read the
directory structure.
Note that the list returned should be regarded as read-only. (Perhaps a future
version should change it to return a tuple?)
.. function:: opendir(path)
Same as :func:`listdir`. Defined for backwards compatibility.
.. function:: annotate(head, list)
Assume *list* is a list of paths relative to *head*, and append, in place, a
``'/'`` to each path which points to a directory.
::
>>> import dircache
>>> a = dircache.listdir('/')
>>> a = a[:] # Copy the return value so we can change 'a'
>>> a
['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
>>> dircache.annotate('/', a)
>>> a
['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
linuz']

781
Doc-3k/library/dis.rst Normal file
View File

@@ -0,0 +1,781 @@
:mod:`dis` --- Disassembler for Python byte code
================================================
.. module:: dis
:synopsis: Disassembler for Python byte code.
The :mod:`dis` module supports the analysis of Python byte code by disassembling
it. Since there is no Python assembler, this module defines the Python assembly
language. The Python byte code which this module takes as an input is defined
in the file :file:`Include/opcode.h` and used by the compiler and the
interpreter.
Example: Given the function :func:`myfunc`::
def myfunc(alist):
return len(alist)
the following command can be used to get the disassembly of :func:`myfunc`::
>>> dis.dis(myfunc)
2 0 LOAD_GLOBAL 0 (len)
3 LOAD_FAST 0 (alist)
6 CALL_FUNCTION 1
9 RETURN_VALUE
(The "2" is a line number).
The :mod:`dis` module defines the following functions and constants:
.. function:: dis([bytesource])
Disassemble the *bytesource* object. *bytesource* can denote either a module, a
class, a method, a function, or a code object. For a module, it disassembles
all functions. For a class, it disassembles all methods. For a single code
sequence, it prints one line per byte code instruction. If no object is
provided, it disassembles the last traceback.
.. function:: distb([tb])
Disassembles the top-of-stack function of a traceback, using the last traceback
if none was passed. The instruction causing the exception is indicated.
.. function:: disassemble(code[, lasti])
Disassembles a code object, indicating the last instruction if *lasti* was
provided. The output is divided in the following columns:
#. the line number, for the first instruction of each line
#. the current instruction, indicated as ``-->``,
#. a labelled instruction, indicated with ``>>``,
#. the address of the instruction,
#. the operation code name,
#. operation parameters, and
#. interpretation of the parameters in parentheses.
The parameter interpretation recognizes local and global variable names,
constant values, branch targets, and compare operators.
.. function:: disco(code[, lasti])
A synonym for disassemble. It is more convenient to type, and kept for
compatibility with earlier Python releases.
.. data:: opname
Sequence of operation names, indexable using the byte code.
.. data:: opmap
Dictionary mapping byte codes to operation names.
.. data:: cmp_op
Sequence of all compare operation names.
.. data:: hasconst
Sequence of byte codes that have a constant parameter.
.. data:: hasfree
Sequence of byte codes that access a free variable.
.. data:: hasname
Sequence of byte codes that access an attribute by name.
.. data:: hasjrel
Sequence of byte codes that have a relative jump target.
.. data:: hasjabs
Sequence of byte codes that have an absolute jump target.
.. data:: haslocal
Sequence of byte codes that access a local variable.
.. data:: hascompare
Sequence of byte codes of Boolean operations.
.. _bytecodes:
Python Byte Code Instructions
-----------------------------
The Python compiler currently generates the following byte code instructions.
.. opcode:: STOP_CODE ()
Indicates end-of-code to the compiler, not used by the interpreter.
.. opcode:: NOP ()
Do nothing code. Used as a placeholder by the bytecode optimizer.
.. opcode:: POP_TOP ()
Removes the top-of-stack (TOS) item.
.. opcode:: ROT_TWO ()
Swaps the two top-most stack items.
.. opcode:: ROT_THREE ()
Lifts second and third stack item one position up, moves top down to position
three.
.. opcode:: ROT_FOUR ()
Lifts second, third and forth stack item one position up, moves top down to
position four.
.. opcode:: DUP_TOP ()
Duplicates the reference on top of the stack.
Unary Operations take the top of the stack, apply the operation, and push the
result back on the stack.
.. opcode:: UNARY_POSITIVE ()
Implements ``TOS = +TOS``.
.. opcode:: UNARY_NEGATIVE ()
Implements ``TOS = -TOS``.
.. opcode:: UNARY_NOT ()
Implements ``TOS = not TOS``.
.. opcode:: UNARY_INVERT ()
Implements ``TOS = ~TOS``.
.. opcode:: GET_ITER ()
Implements ``TOS = iter(TOS)``.
Binary operations remove the top of the stack (TOS) and the second top-most
stack item (TOS1) from the stack. They perform the operation, and put the
result back on the stack.
.. opcode:: BINARY_POWER ()
Implements ``TOS = TOS1 ** TOS``.
.. opcode:: BINARY_MULTIPLY ()
Implements ``TOS = TOS1 * TOS``.
.. opcode:: BINARY_FLOOR_DIVIDE ()
Implements ``TOS = TOS1 // TOS``.
.. opcode:: BINARY_TRUE_DIVIDE ()
Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is in
effect.
.. opcode:: BINARY_MODULO ()
Implements ``TOS = TOS1 % TOS``.
.. opcode:: BINARY_ADD ()
Implements ``TOS = TOS1 + TOS``.
.. opcode:: BINARY_SUBTRACT ()
Implements ``TOS = TOS1 - TOS``.
.. opcode:: BINARY_SUBSCR ()
Implements ``TOS = TOS1[TOS]``.
.. opcode:: BINARY_LSHIFT ()
Implements ``TOS = TOS1 << TOS``.
.. opcode:: BINARY_RSHIFT ()
Implements ``TOS = TOS1 >> TOS``.
.. opcode:: BINARY_AND ()
Implements ``TOS = TOS1 & TOS``.
.. opcode:: BINARY_XOR ()
Implements ``TOS = TOS1 ^ TOS``.
.. opcode:: BINARY_OR ()
Implements ``TOS = TOS1 | TOS``.
In-place operations are like binary operations, in that they remove TOS and
TOS1, and push the result back on the stack, but the operation is done in-place
when TOS1 supports it, and the resulting TOS may be (but does not have to be)
the original TOS1.
.. opcode:: INPLACE_POWER ()
Implements in-place ``TOS = TOS1 ** TOS``.
.. opcode:: INPLACE_MULTIPLY ()
Implements in-place ``TOS = TOS1 * TOS``.
.. opcode:: INPLACE_FLOOR_DIVIDE ()
Implements in-place ``TOS = TOS1 // TOS``.
.. opcode:: INPLACE_TRUE_DIVIDE ()
Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import
division`` is in effect.
.. opcode:: INPLACE_MODULO ()
Implements in-place ``TOS = TOS1 % TOS``.
.. opcode:: INPLACE_ADD ()
Implements in-place ``TOS = TOS1 + TOS``.
.. opcode:: INPLACE_SUBTRACT ()
Implements in-place ``TOS = TOS1 - TOS``.
.. opcode:: INPLACE_LSHIFT ()
Implements in-place ``TOS = TOS1 << TOS``.
.. opcode:: INPLACE_RSHIFT ()
Implements in-place ``TOS = TOS1 >> TOS``.
.. opcode:: INPLACE_AND ()
Implements in-place ``TOS = TOS1 & TOS``.
.. opcode:: INPLACE_XOR ()
Implements in-place ``TOS = TOS1 ^ TOS``.
.. opcode:: INPLACE_OR ()
Implements in-place ``TOS = TOS1 | TOS``.
The slice opcodes take up to three parameters.
.. opcode:: SLICE+0 ()
Implements ``TOS = TOS[:]``.
.. opcode:: SLICE+1 ()
Implements ``TOS = TOS1[TOS:]``.
.. opcode:: SLICE+2 ()
Implements ``TOS = TOS1[:TOS]``.
.. opcode:: SLICE+3 ()
Implements ``TOS = TOS2[TOS1:TOS]``.
Slice assignment needs even an additional parameter. As any statement, they put
nothing on the stack.
.. opcode:: STORE_SLICE+0 ()
Implements ``TOS[:] = TOS1``.
.. opcode:: STORE_SLICE+1 ()
Implements ``TOS1[TOS:] = TOS2``.
.. opcode:: STORE_SLICE+2 ()
Implements ``TOS1[:TOS] = TOS2``.
.. opcode:: STORE_SLICE+3 ()
Implements ``TOS2[TOS1:TOS] = TOS3``.
.. opcode:: DELETE_SLICE+0 ()
Implements ``del TOS[:]``.
.. opcode:: DELETE_SLICE+1 ()
Implements ``del TOS1[TOS:]``.
.. opcode:: DELETE_SLICE+2 ()
Implements ``del TOS1[:TOS]``.
.. opcode:: DELETE_SLICE+3 ()
Implements ``del TOS2[TOS1:TOS]``.
.. opcode:: STORE_SUBSCR ()
Implements ``TOS1[TOS] = TOS2``.
.. opcode:: DELETE_SUBSCR ()
Implements ``del TOS1[TOS]``.
Miscellaneous opcodes.
.. opcode:: PRINT_EXPR ()
Implements the expression statement for the interactive mode. TOS is removed
from the stack and printed. In non-interactive mode, an expression statement is
terminated with ``POP_STACK``.
.. opcode:: BREAK_LOOP ()
Terminates a loop due to a :keyword:`break` statement.
.. opcode:: CONTINUE_LOOP (target)
Continues a loop due to a :keyword:`continue` statement. *target* is the
address to jump to (which should be a ``FOR_ITER`` instruction).
.. opcode:: SET_ADD ()
Calls ``set.add(TOS1, TOS)``. Used to implement set comprehensions.
.. opcode:: LIST_APPEND ()
Calls ``list.append(TOS1, TOS)``. Used to implement list comprehensions.
.. opcode:: LOAD_LOCALS ()
Pushes a reference to the locals of the current scope on the stack. This is used
in the code for a class definition: After the class body is evaluated, the
locals are passed to the class definition.
.. opcode:: RETURN_VALUE ()
Returns with TOS to the caller of the function.
.. opcode:: YIELD_VALUE ()
Pops ``TOS`` and yields it from a generator.
.. opcode:: IMPORT_STAR ()
Loads all symbols not starting with ``'_'`` directly from the module TOS to the
local namespace. The module is popped after loading all names. This opcode
implements ``from module import *``.
.. opcode:: POP_BLOCK ()
Removes one block from the block stack. Per frame, there is a stack of blocks,
denoting nested loops, try statements, and such.
.. opcode:: END_FINALLY ()
Terminates a :keyword:`finally` clause. The interpreter recalls whether the
exception has to be re-raised, or whether the function returns, and continues
with the outer-next block.
.. opcode:: BUILD_CLASS ()
Creates a new class object. TOS is the methods dictionary, TOS1 the tuple of
the names of the base classes, and TOS2 the class name.
All of the following opcodes expect arguments. An argument is two bytes, with
the more significant byte last.
.. opcode:: STORE_NAME (namei)
Implements ``name = TOS``. *namei* is the index of *name* in the attribute
:attr:`co_names` of the code object. The compiler tries to use ``STORE_LOCAL``
or ``STORE_GLOBAL`` if possible.
.. opcode:: DELETE_NAME (namei)
Implements ``del name``, where *namei* is the index into :attr:`co_names`
attribute of the code object.
.. opcode:: UNPACK_SEQUENCE (count)
Unpacks TOS into *count* individual values, which are put onto the stack right-
to-left.
.. % \begin{opcodedesc}{UNPACK_LIST}{count}
.. % This opcode is obsolete.
.. % \end{opcodedesc}
.. % \begin{opcodedesc}{UNPACK_ARG}{count}
.. % This opcode is obsolete.
.. % \end{opcodedesc}
.. opcode:: DUP_TOPX (count)
Duplicate *count* items, keeping them in the same order. Due to implementation
limits, *count* should be between 1 and 5 inclusive.
.. opcode:: STORE_ATTR (namei)
Implements ``TOS.name = TOS1``, where *namei* is the index of name in
:attr:`co_names`.
.. opcode:: DELETE_ATTR (namei)
Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`.
.. opcode:: STORE_GLOBAL (namei)
Works as ``STORE_NAME``, but stores the name as a global.
.. opcode:: DELETE_GLOBAL (namei)
Works as ``DELETE_NAME``, but deletes a global name.
.. % \begin{opcodedesc}{UNPACK_VARARG}{argc}
.. % This opcode is obsolete.
.. % \end{opcodedesc}
.. opcode:: LOAD_CONST (consti)
Pushes ``co_consts[consti]`` onto the stack.
.. opcode:: LOAD_NAME (namei)
Pushes the value associated with ``co_names[namei]`` onto the stack.
.. opcode:: BUILD_TUPLE (count)
Creates a tuple consuming *count* items from the stack, and pushes the resulting
tuple onto the stack.
.. opcode:: BUILD_LIST (count)
Works as ``BUILD_TUPLE``, but creates a list.
.. opcode:: BUILD_SET (count)
Works as ``BUILD_TUPLE``, but creates a set.
.. opcode:: BUILD_MAP (zero)
Pushes a new empty dictionary object onto the stack. The argument is ignored
and set to zero by the compiler.
.. opcode:: LOAD_ATTR (namei)
Replaces TOS with ``getattr(TOS, co_names[namei])``.
.. opcode:: COMPARE_OP (opname)
Performs a Boolean operation. The operation name can be found in
``cmp_op[opname]``.
.. opcode:: IMPORT_NAME (namei)
Imports the module ``co_names[namei]``. The module object is pushed onto the
stack. The current namespace is not affected: for a proper import statement, a
subsequent ``STORE_FAST`` instruction modifies the namespace.
.. opcode:: IMPORT_FROM (namei)
Loads the attribute ``co_names[namei]`` from the module found in TOS. The
resulting object is pushed onto the stack, to be subsequently stored by a
``STORE_FAST`` instruction.
.. opcode:: JUMP_FORWARD (delta)
Increments byte code counter by *delta*.
.. opcode:: JUMP_IF_TRUE (delta)
If TOS is true, increment the byte code counter by *delta*. TOS is left on the
stack.
.. opcode:: JUMP_IF_FALSE (delta)
If TOS is false, increment the byte code counter by *delta*. TOS is not
changed.
.. opcode:: JUMP_ABSOLUTE (target)
Set byte code counter to *target*.
.. opcode:: FOR_ITER (delta)
``TOS`` is an iterator. Call its :meth:`__next__` method. If this yields a new
value, push it on the stack (leaving the iterator below it). If the iterator
indicates it is exhausted ``TOS`` is popped, and the byte code counter is
incremented by *delta*.
.. % \begin{opcodedesc}{FOR_LOOP}{delta}
.. % This opcode is obsolete.
.. % \end{opcodedesc}
.. % \begin{opcodedesc}{LOAD_LOCAL}{namei}
.. % This opcode is obsolete.
.. % \end{opcodedesc}
.. opcode:: LOAD_GLOBAL (namei)
Loads the global named ``co_names[namei]`` onto the stack.
.. % \begin{opcodedesc}{SET_FUNC_ARGS}{argc}
.. % This opcode is obsolete.
.. % \end{opcodedesc}
.. opcode:: SETUP_LOOP (delta)
Pushes a block for a loop onto the block stack. The block spans from the
current instruction with a size of *delta* bytes.
.. opcode:: SETUP_EXCEPT (delta)
Pushes a try block from a try-except clause onto the block stack. *delta* points
to the first except block.
.. opcode:: SETUP_FINALLY (delta)
Pushes a try block from a try-except clause onto the block stack. *delta* points
to the finally block.
.. opcode:: LOAD_FAST (var_num)
Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
.. opcode:: STORE_FAST (var_num)
Stores TOS into the local ``co_varnames[var_num]``.
.. opcode:: DELETE_FAST (var_num)
Deletes local ``co_varnames[var_num]``.
.. opcode:: LOAD_CLOSURE (i)
Pushes a reference to the cell contained in slot *i* of the cell and free
variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is
less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i -
len(co_cellvars)]``.
.. opcode:: LOAD_DEREF (i)
Loads the cell contained in slot *i* of the cell and free variable storage.
Pushes a reference to the object the cell contains on the stack.
.. opcode:: STORE_DEREF (i)
Stores TOS into the cell contained in slot *i* of the cell and free variable
storage.
.. opcode:: SET_LINENO (lineno)
This opcode is obsolete.
.. opcode:: RAISE_VARARGS (argc)
Raises an exception. *argc* indicates the number of parameters to the raise
statement, ranging from 0 to 3. The handler will find the traceback as TOS2,
the parameter as TOS1, and the exception as TOS.
.. opcode:: CALL_FUNCTION (argc)
Calls a function. The low byte of *argc* indicates the number of positional
parameters, the high byte the number of keyword parameters. On the stack, the
opcode finds the keyword parameters first. For each keyword argument, the value
is on top of the key. Below the keyword parameters, the positional parameters
are on the stack, with the right-most parameter on top. Below the parameters,
the function object to call is on the stack.
.. opcode:: MAKE_FUNCTION (argc)
Pushes a new function object on the stack. TOS is the code associated with the
function. The function object is defined to have *argc* default parameters,
which are found below TOS.
.. opcode:: MAKE_CLOSURE (argc)
Creates a new function object, sets its *__closure__* slot, and pushes it on the
stack. TOS is the code associated with the function. If the code object has N
free variables, the next N items on the stack are the cells for these variables.
The function also has *argc* default parameters, where are found before the
cells.
.. opcode:: BUILD_SLICE (argc)
.. index:: builtin: slice
Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2,
``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
pushed. See the ``slice()`` built-in function for more information.
.. opcode:: EXTENDED_ARG (ext)
Prefixes any opcode which has an argument too big to fit into the default two
bytes. *ext* holds two additional bytes which, taken together with the
subsequent opcode's argument, comprise a four-byte argument, *ext* being the two
most-significant bytes.
.. opcode:: CALL_FUNCTION_VAR (argc)
Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
on the stack contains the variable argument list, followed by keyword and
positional arguments.
.. opcode:: CALL_FUNCTION_KW (argc)
Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
on the stack contains the keyword arguments dictionary, followed by explicit
keyword and positional arguments.
.. opcode:: CALL_FUNCTION_VAR_KW (argc)
Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top
element on the stack contains the keyword arguments dictionary, followed by the
variable-arguments tuple, followed by explicit keyword and positional arguments.
.. opcode:: HAVE_ARGUMENT ()
This is not really an opcode. It identifies the dividing line between opcodes
which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>=
HAVE_ARGUMENT``.

36
Doc-3k/library/distutils.rst Normal file
View File

@@ -0,0 +1,36 @@
:mod:`distutils` --- Building and installing Python modules
===========================================================
.. module:: distutils
:synopsis: Support for building and installing Python modules into an existing Python
installation.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
The :mod:`distutils` package provides support for building and installing
additional modules into a Python installation. The new modules may be either
100%-pure Python, or may be extension modules written in C, or may be
collections of Python packages which include modules coded in both Python and C.
This package is discussed in two separate documents which are included in the
Python documentation package. To learn about distributing new modules using the
:mod:`distutils` facilities, read Distributing Python Modules (XXX reference:
../dist/dist.html); this includes documentation needed to extend distutils. To
learn about installing Python modules, whether or not the author made use of the
:mod:`distutils` package, read Installing Python Modules (XXX reference:
../inst/inst.html).
.. seealso::
`Distributing Python Modules <../dist/dist.html>`_
The manual for developers and packagers of Python modules. This describes how
to prepare :mod:`distutils`\ -based packages so that they may be easily
installed into an existing Python installation.
`Installing Python Modules <../inst/inst.html>`_
An "administrators" manual which includes information on installing modules into
an existing Python installation. You do not need to be a Python programmer to
read this manual.

111
Doc-3k/library/dl.rst Normal file
View File

@@ -0,0 +1,111 @@
:mod:`dl` --- Call C functions in shared objects
================================================
.. module:: dl
:platform: Unix
:synopsis: Call C functions in shared objects.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. % ?????????? Anyone????????????
The :mod:`dl` module defines an interface to the :cfunc:`dlopen` function, which
is the most common interface on Unix platforms for handling dynamically linked
libraries. It allows the program to call arbitrary functions in such a library.
.. warning::
The :mod:`dl` module bypasses the Python type system and error handling. If
used incorrectly it may cause segmentation faults, crashes or other incorrect
behaviour.
.. note::
This module will not work unless ``sizeof(int) == sizeof(long) == sizeof(char
*)`` If this is not the case, :exc:`SystemError` will be raised on import.
The :mod:`dl` module defines the following function:
.. function:: open(name[, mode\ ``= RTLD_LAZY``])
Open a shared object file, and return a handle. Mode signifies late binding
(:const:`RTLD_LAZY`) or immediate binding (:const:`RTLD_NOW`). Default is
:const:`RTLD_LAZY`. Note that some systems do not support :const:`RTLD_NOW`.
Return value is a :class:`dlobject`.
The :mod:`dl` module defines the following constants:
.. data:: RTLD_LAZY
Useful as an argument to :func:`open`.
.. data:: RTLD_NOW
Useful as an argument to :func:`open`. Note that on systems which do not
support immediate binding, this constant will not appear in the module. For
maximum portability, use :func:`hasattr` to determine if the system supports
immediate binding.
The :mod:`dl` module defines the following exception:
.. exception:: error
Exception raised when an error has occurred inside the dynamic loading and
linking routines.
Example::
>>> import dl, time
>>> a=dl.open('/lib/libc.so.6')
>>> a.call('time'), time.time()
(929723914, 929723914.498)
This example was tried on a Debian GNU/Linux system, and is a good example of
the fact that using this module is usually a bad alternative.
.. _dl-objects:
Dl Objects
----------
Dl objects, as returned by :func:`open` above, have the following methods:
.. method:: dl.close()
Free all resources, except the memory.
.. method:: dl.sym(name)
Return the pointer for the function named *name*, as a number, if it exists in
the referenced shared object, otherwise ``None``. This is useful in code like::
>>> if a.sym('time'):
... a.call('time')
... else:
... time.time()
(Note that this function will return a non-zero number, as zero is the *NULL*
pointer)
.. method:: dl.call(name[, arg1[, arg2...]])
Call the function named *name* in the referenced shared object. The arguments
must be either Python integers, which will be passed as is, Python strings, to
which a pointer will be passed, or ``None``, which will be passed as *NULL*.
Note that strings should only be passed to functions as :ctype:`const char\*`,
as Python will not like its string mutated.
There must be at most 10 arguments, and arguments not given will be treated as
``None``. The function's return value must be a C :ctype:`long`, which is a
Python integer.

1871
Doc-3k/library/doctest.rst Normal file
View File

File diff suppressed because it is too large Load Diff

97
Doc-3k/library/docxmlrpcserver.rst Normal file
View File

@@ -0,0 +1,97 @@
:mod:`DocXMLRPCServer` --- Self-documenting XML-RPC server
==========================================================
.. module:: DocXMLRPCServer
:synopsis: Self-documenting XML-RPC server implementation.
.. moduleauthor:: Brian Quinlan <brianq@activestate.com>
.. sectionauthor:: Brian Quinlan <brianq@activestate.com>
.. versionadded:: 2.3
The :mod:`DocXMLRPCServer` module extends the classes found in
:mod:`SimpleXMLRPCServer` to serve HTML documentation in response to HTTP GET
requests. Servers can either be free standing, using :class:`DocXMLRPCServer`,
or embedded in a CGI environment, using :class:`DocCGIXMLRPCRequestHandler`.
.. class:: DocXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding[, bind_and_activate]]]]])
Create a new server instance. All parameters have the same meaning as for
:class:`SimpleXMLRPCServer.SimpleXMLRPCServer`; *requestHandler* defaults to
:class:`DocXMLRPCRequestHandler`.
.. class:: DocCGIXMLRPCRequestHandler()
Create a new instance to handle XML-RPC requests in a CGI environment.
.. class:: DocXMLRPCRequestHandler()
Create a new request handler instance. This request handler supports XML-RPC
POST requests, documentation GET requests, and modifies logging so that the
*logRequests* parameter to the :class:`DocXMLRPCServer` constructor parameter is
honored.
.. _doc-xmlrpc-servers:
DocXMLRPCServer Objects
-----------------------
The :class:`DocXMLRPCServer` class is derived from
:class:`SimpleXMLRPCServer.SimpleXMLRPCServer` and provides a means of creating
self-documenting, stand alone XML-RPC servers. HTTP POST requests are handled as
XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
HTML documentation. This allows a server to provide its own web-based
documentation.
.. method:: DocXMLRPCServer.set_server_title(server_title)
Set the title used in the generated HTML documentation. This title will be used
inside the HTML "title" element.
.. method:: DocXMLRPCServer.set_server_name(server_name)
Set the name used in the generated HTML documentation. This name will appear at
the top of the generated documentation inside a "h1" element.
.. method:: DocXMLRPCServer.set_server_documentation(server_documentation)
Set the description used in the generated HTML documentation. This description
will appear as a paragraph, below the server name, in the documentation.
DocCGIXMLRPCRequestHandler
--------------------------
The :class:`DocCGIXMLRPCRequestHandler` class is derived from
:class:`SimpleXMLRPCServer.CGIXMLRPCRequestHandler` and provides a means of
creating self-documenting, XML-RPC CGI scripts. HTTP POST requests are handled
as XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
HTML documentation. This allows a server to provide its own web-based
documentation.
.. method:: DocCGIXMLRPCRequestHandler.set_server_title(server_title)
Set the title used in the generated HTML documentation. This title will be used
inside the HTML "title" element.
.. method:: DocCGIXMLRPCRequestHandler.set_server_name(server_name)
Set the name used in the generated HTML documentation. This name will appear at
the top of the generated documentation inside a "h1" element.
.. method:: DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)
Set the description used in the generated HTML documentation. This description
will appear as a paragraph, below the server name, in the documentation.

81
Doc-3k/library/dumbdbm.rst Normal file
View File

@@ -0,0 +1,81 @@
:mod:`dumbdbm` --- Portable DBM implementation
==============================================
.. module:: dumbdbm
:synopsis: Portable implementation of the simple DBM interface.
.. index:: single: databases
.. note::
The :mod:`dumbdbm` module is intended as a last resort fallback for the
:mod:`anydbm` module when no more robust module is available. The :mod:`dumbdbm`
module is not written for speed and is not nearly as heavily used as the other
database modules.
The :mod:`dumbdbm` module provides a persistent dictionary-like interface which
is written entirely in Python. Unlike other modules such as :mod:`gdbm` and
:mod:`bsddb`, no external library is required. As with other persistent
mappings, the keys and values must always be strings.
The module defines the following:
.. exception:: error
Raised on dumbdbm-specific errors, such as I/O errors. :exc:`KeyError` is
raised for general mapping errors like specifying an incorrect key.
.. function:: open(filename[, flag[, mode]])
Open a dumbdbm database and return a dumbdbm object. The *filename* argument is
the basename of the database file (without any specific extensions). When a
dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
are created.
The optional *flag* argument is currently ignored; the database is always opened
for update, and will be created if it does not exist.
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).
.. versionchanged:: 2.2
The *mode* argument was ignored in earlier versions.
.. seealso::
Module :mod:`anydbm`
Generic interface to ``dbm``\ -style databases.
Module :mod:`dbm`
Similar interface to the DBM/NDBM library.
Module :mod:`gdbm`
Similar interface to the GNU GDBM library.
Module :mod:`shelve`
Persistence module which stores non-string data.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.
.. _dumbdbm-objects:
Dumbdbm Objects
---------------
In addition to the methods provided by the :class:`UserDict.DictMixin` class,
:class:`dumbdbm` objects provide the following methods.
.. method:: dumbdbm.sync()
Synchronize the on-disk directory and data files. This method is called by the
:meth:`sync` method of :class:`Shelve` objects.

23
Doc-3k/library/dummy_thread.rst Normal file
View File

@@ -0,0 +1,23 @@
:mod:`dummy_thread` --- Drop-in replacement for the :mod:`thread` module
========================================================================
.. module:: dummy_thread
:synopsis: Drop-in replacement for the thread module.
This module provides a duplicate interface to the :mod:`thread` module. It is
meant to be imported when the :mod:`thread` module is not provided on a
platform.
Suggested usage is::
try:
import thread as _thread
except ImportError:
import dummy_thread as _thread
Be careful to not use this module where deadlock might occur from a thread
being created that blocks waiting for another thread to be created. This often
occurs with blocking I/O.

23
Doc-3k/library/dummy_threading.rst Normal file
View File

@@ -0,0 +1,23 @@
:mod:`dummy_threading` --- Drop-in replacement for the :mod:`threading` module
==============================================================================
.. module:: dummy_threading
:synopsis: Drop-in replacement for the threading module.
This module provides a duplicate interface to the :mod:`threading` module. It
is meant to be imported when the :mod:`thread` module is not provided on a
platform.
Suggested usage is::
try:
import threading as _threading
except ImportError:
import dummy_threading as _threading
Be careful to not use this module where deadlock might occur from a thread
being created that blocks waiting for another thread to be created. This often
occurs with blocking I/O.

246
Doc-3k/library/email.charset.rst Normal file
View File

@@ -0,0 +1,246 @@
.. module:: email.charset
:synopsis: Character Sets
This module provides a class :class:`Charset` for representing character sets
and character set conversions in email messages, as well as a character set
registry and several convenience methods for manipulating this registry.
Instances of :class:`Charset` are used in several other modules within the
:mod:`email` package.
Import this class from the :mod:`email.charset` module.
.. versionadded:: 2.2.2
.. class:: Charset([input_charset])
Map character sets to their email properties.
This class provides information about the requirements imposed on email for a
specific character set. It also provides convenience routines for converting
between character sets, given the availability of the applicable codecs. Given
a character set, it will do its best to provide information on how to use that
character set in an email message in an RFC-compliant way.
Certain character sets must be encoded with quoted-printable or base64 when used
in email headers or bodies. Certain character sets must be converted outright,
and are not allowed in email.
Optional *input_charset* is as described below; it is always coerced to lower
case. After being alias normalized it is also used as a lookup into the
registry of character sets to find out the header encoding, body encoding, and
output conversion codec to be used for the character set. For example, if
*input_charset* is ``iso-8859-1``, then headers and bodies will be encoded using
quoted-printable and no output conversion codec is necessary. If
*input_charset* is ``euc-jp``, then headers will be encoded with base64, bodies
will not be encoded, but output text will be converted from the ``euc-jp``
character set to the ``iso-2022-jp`` character set.
:class:`Charset` instances have the following data attributes:
.. data:: input_charset
The initial character set specified. Common aliases are converted to their
*official* email names (e.g. ``latin_1`` is converted to ``iso-8859-1``).
Defaults to 7-bit ``us-ascii``.
.. data:: header_encoding
If the character set must be encoded before it can be used in an email header,
this attribute will be set to ``Charset.QP`` (for quoted-printable),
``Charset.BASE64`` (for base64 encoding), or ``Charset.SHORTEST`` for the
shortest of QP or BASE64 encoding. Otherwise, it will be ``None``.
.. data:: body_encoding
Same as *header_encoding*, but describes the encoding for the mail message's
body, which indeed may be different than the header encoding.
``Charset.SHORTEST`` is not allowed for *body_encoding*.
.. data:: output_charset
Some character sets must be converted before they can be used in email headers
or bodies. If the *input_charset* is one of them, this attribute will contain
the name of the character set output will be converted to. Otherwise, it will
be ``None``.
.. data:: input_codec
The name of the Python codec used to convert the *input_charset* to Unicode. If
no conversion codec is necessary, this attribute will be ``None``.
.. data:: output_codec
The name of the Python codec used to convert Unicode to the *output_charset*.
If no conversion codec is necessary, this attribute will have the same value as
the *input_codec*.
:class:`Charset` instances also have the following methods:
.. method:: Charset.get_body_encoding()
Return the content transfer encoding used for body encoding.
This is either the string ``quoted-printable`` or ``base64`` depending on the
encoding used, or it is a function, in which case you should call the function
with a single argument, the Message object being encoded. The function should
then set the :mailheader:`Content-Transfer-Encoding` header itself to whatever
is appropriate.
Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, returns
the string ``base64`` if *body_encoding* is ``BASE64``, and returns the string
``7bit`` otherwise.
.. method:: Charset.convert(s)
Convert the string *s* from the *input_codec* to the *output_codec*.
.. method:: Charset.to_splittable(s)
Convert a possibly multibyte string to a safely splittable format. *s* is the
string to split.
Uses the *input_codec* to try and convert the string to Unicode, so it can be
safely split on character boundaries (even for multibyte characters).
Returns the string as-is if it isn't known how to convert *s* to Unicode with
the *input_charset*.
Characters that could not be converted to Unicode will be replaced with the
Unicode replacement character ``'U+FFFD'``.
.. method:: Charset.from_splittable(ustr[, to_output])
Convert a splittable string back into an encoded string. *ustr* is a Unicode
string to "unsplit".
This method uses the proper codec to try and convert the string from Unicode
back into an encoded format. Return the string as-is if it is not Unicode, or
if it could not be converted from Unicode.
Characters that could not be converted from Unicode will be replaced with an
appropriate character (usually ``'?'``).
If *to_output* is ``True`` (the default), uses *output_codec* to convert to an
encoded format. If *to_output* is ``False``, it uses *input_codec*.
.. method:: Charset.get_output_charset()
Return the output character set.
This is the *output_charset* attribute if that is not ``None``, otherwise it is
*input_charset*.
.. method:: Charset.encoded_header_len()
Return the length of the encoded header string, properly calculating for quoted-
printable or base64 encoding.
.. method:: Charset.header_encode(s[, convert])
Header-encode the string *s*.
If *convert* is ``True``, the string will be converted from the input charset to
the output charset automatically. This is not useful for multibyte character
sets, which have line length issues (multibyte characters must be split on a
character, not a byte boundary); use the higher-level :class:`Header` class to
deal with these issues (see :mod:`email.header`). *convert* defaults to
``False``.
The type of encoding (base64 or quoted-printable) will be based on the
*header_encoding* attribute.
.. method:: Charset.body_encode(s[, convert])
Body-encode the string *s*.
If *convert* is ``True`` (the default), the string will be converted from the
input charset to output charset automatically. Unlike :meth:`header_encode`,
there are no issues with byte boundaries and multibyte charsets in email bodies,
so this is usually pretty safe.
The type of encoding (base64 or quoted-printable) will be based on the
*body_encoding* attribute.
The :class:`Charset` class also provides a number of methods to support standard
operations and built-in functions.
.. method:: Charset.__str__()
Returns *input_charset* as a string coerced to lower case. :meth:`__repr__` is
an alias for :meth:`__str__`.
.. method:: Charset.__eq__(other)
This method allows you to compare two :class:`Charset` instances for equality.
.. method:: Header.__ne__(other)
This method allows you to compare two :class:`Charset` instances for inequality.
The :mod:`email.charset` module also provides the following functions for adding
new entries to the global character set, alias, and codec registries:
.. function:: add_charset(charset[, header_enc[, body_enc[, output_charset]]])
Add character properties to the global registry.
*charset* is the input character set, and must be the canonical name of a
character set.
Optional *header_enc* and *body_enc* is either ``Charset.QP`` for quoted-
printable, ``Charset.BASE64`` for base64 encoding, ``Charset.SHORTEST`` for the
shortest of quoted-printable or base64 encoding, or ``None`` for no encoding.
``SHORTEST`` is only valid for *header_enc*. The default is ``None`` for no
encoding.
Optional *output_charset* is the character set that the output should be in.
Conversions will proceed from input charset, to Unicode, to the output charset
when the method :meth:`Charset.convert` is called. The default is to output in
the same character set as the input.
Both *input_charset* and *output_charset* must have Unicode codec entries in the
module's character set-to-codec mapping; use :func:`add_codec` to add codecs the
module does not know about. See the :mod:`codecs` module's documentation for
more information.
The global character set registry is kept in the module global dictionary
``CHARSETS``.
.. function:: add_alias(alias, canonical)
Add a character set alias. *alias* is the alias name, e.g. ``latin-1``.
*canonical* is the character set's canonical name, e.g. ``iso-8859-1``.
The global charset alias registry is kept in the module global dictionary
``ALIASES``.
.. function:: add_codec(charset, codecname)
Add a codec that map characters in the given character set to and from Unicode.
*charset* is the canonical name of a character set. *codecname* is the name of a
Python codec, as appropriate for the second argument to the :func:`unicode`
built-in, or to the :meth:`encode` method of a Unicode string.

54
Doc-3k/library/email.encoders.rst Normal file
View File

@@ -0,0 +1,54 @@
.. module:: email.encoders
:synopsis: Encoders for email message payloads.
When creating :class:`Message` objects from scratch, you often need to encode
the payloads for transport through compliant mail servers. This is especially
true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages containing
binary data.
The :mod:`email` package provides some convenient encodings in its
:mod:`encoders` module. These encoders are actually used by the
:class:`MIMEAudio` and :class:`MIMEImage` class constructors to provide default
encodings. All encoder functions take exactly one argument, the message object
to encode. They usually extract the payload, encode it, and reset the payload
to this newly encoded value. They should also set the
:mailheader:`Content-Transfer-Encoding` header as appropriate.
Here are the encoding functions provided:
.. function:: encode_quopri(msg)
Encodes the payload into quoted-printable form and sets the
:mailheader:`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_.
This is a good encoding to use when most of your payload is normal printable
data, but contains a few unprintable characters.
.. function:: encode_base64(msg)
Encodes the payload into base64 form and sets the
:mailheader:`Content-Transfer-Encoding` header to ``base64``. This is a good
encoding to use when most of your payload is unprintable data since it is a more
compact form than quoted-printable. The drawback of base64 encoding is that it
renders the text non-human readable.
.. function:: encode_7or8bit(msg)
This doesn't actually modify the message's payload, but it does set the
:mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` as
appropriate, based on the payload data.
.. function:: encode_noop(msg)
This does nothing; it doesn't even set the
:mailheader:`Content-Transfer-Encoding` header.
.. rubric:: Footnotes
.. [#] Note that encoding with :meth:`encode_quopri` also encodes all tabs and space
characters in the data.

88
Doc-3k/library/email.errors.rst Normal file
View File

@@ -0,0 +1,88 @@
.. module:: email.errors
:synopsis: The exception classes used by the email package.
The following exception classes are defined in the :mod:`email.errors` module:
.. exception:: MessageError()
This is the base class for all exceptions that the :mod:`email` package can
raise. It is derived from the standard :exc:`Exception` class and defines no
additional methods.
.. exception:: MessageParseError()
This is the base class for exceptions thrown by the :class:`Parser` class. It
is derived from :exc:`MessageError`.
.. exception:: HeaderParseError()
Raised under some error conditions when parsing the :rfc:`2822` headers of a
message, this class is derived from :exc:`MessageParseError`. It can be raised
from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
Situations where it can be raised include finding an envelope header after the
first :rfc:`2822` header of the message, finding a continuation line before the
first :rfc:`2822` header is found, or finding a line in the headers which is
neither a header or a continuation line.
.. exception:: BoundaryError()
Raised under some error conditions when parsing the :rfc:`2822` headers of a
message, this class is derived from :exc:`MessageParseError`. It can be raised
from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
Situations where it can be raised include not being able to find the starting or
terminating boundary in a :mimetype:`multipart/\*` message when strict parsing
is used.
.. exception:: MultipartConversionError()
Raised when a payload is added to a :class:`Message` object using
:meth:`add_payload`, but the payload is already a scalar and the message's
:mailheader:`Content-Type` main type is not either :mimetype:`multipart` or
missing. :exc:`MultipartConversionError` multiply inherits from
:exc:`MessageError` and the built-in :exc:`TypeError`.
Since :meth:`Message.add_payload` is deprecated, this exception is rarely raised
in practice. However the exception may also be raised if the :meth:`attach`
method is called on an instance of a class derived from
:class:`MIMENonMultipart` (e.g. :class:`MIMEImage`).
Here's the list of the defects that the :class:`FeedParser` can find while
parsing messages. Note that the defects are added to the message where the
problem was found, so for example, if a message nested inside a
:mimetype:`multipart/alternative` had a malformed header, that nested message
object would have a defect, but the containing messages would not.
All defect classes are subclassed from :class:`email.errors.MessageDefect`, but
this class is *not* an exception!
.. versionadded:: 2.4
All the defect classes were added.
* :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart,
but had no :mimetype:`boundary` parameter.
* :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the
:mailheader:`Content-Type` header was never found.
* :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation
line as its first header line.
* :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the
middle of a header block.
* :class:`MalformedHeaderDefect` -- A header was found that was missing a colon,
or was otherwise malformed.
* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
:mimetype:`multipart`, but no subparts were found. Note that when a message has
this defect, its :meth:`is_multipart` method may return false even though its
content type claims to be :mimetype:`multipart`.

120
Doc-3k/library/email.generator.rst Normal file
View File

@@ -0,0 +1,120 @@
.. module:: email.generator
:synopsis: Generate flat text email messages from a message structure.
One of the most common tasks is to generate the flat text of the email message
represented by a message object structure. You will need to do this if you want
to send your message via the :mod:`smtplib` module or the :mod:`nntplib` module,
or print the message on the console. Taking a message object structure and
producing a flat text document is the job of the :class:`Generator` class.
Again, as with the :mod:`email.parser` module, you aren't limited to the
functionality of the bundled generator; you could write one from scratch
yourself. However the bundled generator knows how to generate most email in a
standards-compliant way, should handle MIME and non-MIME email messages just
fine, and is designed so that the transformation from flat text, to a message
structure via the :class:`Parser` class, and back to flat text, is idempotent
(the input is identical to the output).
Here are the public methods of the :class:`Generator` class, imported from the
:mod:`email.generator` module:
.. class:: Generator(outfp[, mangle_from_[, maxheaderlen]])
The constructor for the :class:`Generator` class takes a file-like object called
*outfp* for an argument. *outfp* must support the :meth:`write` method and be
usable as the output file in a Python extended print statement.
Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in
front of any line in the body that starts exactly as ``From``, i.e. ``From``
followed by a space at the beginning of the line. This is the only guaranteed
portable way to avoid having such lines be mistaken for a Unix mailbox format
envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD
<http://www.jwz.org/doc/content-length.html>`_ for details). *mangle_from_*
defaults to ``True``, but you might want to set this to ``False`` if you are not
writing Unix mailbox format files.
Optional *maxheaderlen* specifies the longest length for a non-continued header.
When a header line is longer than *maxheaderlen* (in characters, with tabs
expanded to 8 spaces), the header will be split as defined in the
:mod:`email.header.Header` class. Set to zero to disable header wrapping. The
default is 78, as recommended (but not required) by :rfc:`2822`.
The other public :class:`Generator` methods are:
.. method:: Generator.flatten(msg[, unixfrom])
Print the textual representation of the message object structure rooted at *msg*
to the output file specified when the :class:`Generator` instance was created.
Subparts are visited depth-first and the resulting text will be properly MIME
encoded.
Optional *unixfrom* is a flag that forces the printing of the envelope header
delimiter before the first :rfc:`2822` header of the root message object. If
the root object has no envelope header, a standard one is crafted. By default,
this is set to ``False`` to inhibit the printing of the envelope delimiter.
Note that for subparts, no envelope header is ever printed.
.. versionadded:: 2.2.2
.. method:: Generator.clone(fp)
Return an independent clone of this :class:`Generator` instance with the exact
same options.
.. versionadded:: 2.2.2
.. method:: Generator.write(s)
Write the string *s* to the underlying file object, i.e. *outfp* passed to
:class:`Generator`'s constructor. This provides just enough file-like API for
:class:`Generator` instances to be used in extended print statements.
As a convenience, see the methods :meth:`Message.as_string` and
``str(aMessage)``, a.k.a. :meth:`Message.__str__`, which simplify the generation
of a formatted string representation of a message object. For more detail, see
:mod:`email.message`.
The :mod:`email.generator` module also provides a derived class, called
:class:`DecodedGenerator` which is like the :class:`Generator` base class,
except that non-\ :mimetype:`text` parts are substituted with a format string
representing the part.
.. class:: DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]])
This class, derived from :class:`Generator` walks through all the subparts of a
message. If the subpart is of main type :mimetype:`text`, then it prints the
decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are
as with the :class:`Generator` base class.
If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format
string that is used instead of the message payload. *fmt* is expanded with the
following keywords, ``%(keyword)s`` format:
* ``type`` -- Full MIME type of the non-\ :mimetype:`text` part
* ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part
* ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part
* ``filename`` -- Filename of the non-\ :mimetype:`text` part
* ``description`` -- Description associated with the non-\ :mimetype:`text` part
* ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part
The default value for *fmt* is ``None``, meaning ::
[Non-text (%(type)s) part of message omitted, filename %(filename)s]
.. versionadded:: 2.2.2
.. versionchanged:: 2.5
The previously deprecated method :meth:`__call__` was removed.

168
Doc-3k/library/email.header.rst Normal file
View File

@@ -0,0 +1,168 @@
.. module:: email.header
:synopsis: Representing non-ASCII headers
:rfc:`2822` is the base standard that describes the format of email messages.
It derives from the older :rfc:`822` standard which came into widespread use at
a time when most email was composed of ASCII characters only. :rfc:`2822` is a
specification written assuming email contains only 7-bit ASCII characters.
Of course, as email has been deployed worldwide, it has become
internationalized, such that language specific character sets can now be used in
email messages. The base standard still requires email messages to be
transferred using only 7-bit ASCII characters, so a slew of RFCs have been
written describing how to encode email containing non-ASCII characters into
:rfc:`2822`\ -compliant format. These RFCs include :rfc:`2045`, :rfc:`2046`,
:rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports these standards
in its :mod:`email.header` and :mod:`email.charset` modules.
If you want to include non-ASCII characters in your email headers, say in the
:mailheader:`Subject` or :mailheader:`To` fields, you should use the
:class:`Header` class and assign the field in the :class:`Message` object to an
instance of :class:`Header` instead of using a string for the header value.
Import the :class:`Header` class from the :mod:`email.header` module. For
example::
>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> print msg.as_string()
Subject: =?iso-8859-1?q?p=F6stal?=
Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
character? We did this by creating a :class:`Header` instance and passing in
the character set that the byte string was encoded in. When the subsequent
:class:`Message` instance was flattened, the :mailheader:`Subject` field was
properly :rfc:`2047` encoded. MIME-aware mail readers would show this header
using the embedded ISO-8859-1 character.
.. versionadded:: 2.2.2
Here is the :class:`Header` class description:
.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
Create a MIME-compliant header that can contain strings in different character
sets.
Optional *s* is the initial header value. If ``None`` (the default), the
initial header value is not set. You can later append to the header with
:meth:`append` method calls. *s* may be a byte string or a Unicode string, but
see the :meth:`append` documentation for semantics.
Optional *charset* serves two purposes: it has the same meaning as the *charset*
argument to the :meth:`append` method. It also sets the default character set
for all subsequent :meth:`append` calls that omit the *charset* argument. If
*charset* is not provided in the constructor (the default), the ``us-ascii``
character set is used both as *s*'s initial charset and as the default for
subsequent :meth:`append` calls.
The maximum line length can be specified explicit via *maxlinelen*. For
splitting the first line to a shorter value (to account for the field header
which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of the
field in *header_name*. The default *maxlinelen* is 76, and the default value
for *header_name* is ``None``, meaning it is not taken into account for the
first line of a long, split header.
Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace,
and is usually either a space or a hard tab character. This character will be
prepended to continuation lines.
Optional *errors* is passed straight through to the :meth:`append` method.
.. method:: Header.append(s[, charset[, errors]])
Append the string *s* to the MIME header.
Optional *charset*, if given, should be a :class:`Charset` instance (see
:mod:`email.charset`) or the name of a character set, which will be converted to
a :class:`Charset` instance. A value of ``None`` (the default) means that the
*charset* given in the constructor is used.
*s* may be a byte string or a Unicode string. If it is a byte string (i.e.
``isinstance(s, str)`` is true), then *charset* is the encoding of that byte
string, and a :exc:`UnicodeError` will be raised if the string cannot be decoded
with that character set.
If *s* is a Unicode string, then *charset* is a hint specifying the character
set of the characters in the string. In this case, when producing an
:rfc:`2822`\ -compliant header using :rfc:`2047` rules, the Unicode string will
be encoded using the following charsets in order: ``us-ascii``, the *charset*
hint, ``utf-8``. The first character set to not provoke a :exc:`UnicodeError`
is used.
Optional *errors* is passed through to any :func:`unicode` or
:func:`ustr.encode` call, and defaults to "strict".
.. method:: Header.encode([splitchars])
Encode a message header into an RFC-compliant format, possibly wrapping long
lines and encapsulating non-ASCII parts in base64 or quoted-printable encodings.
Optional *splitchars* is a string containing characters to split long ASCII
lines on, in rough support of :rfc:`2822`'s *highest level syntactic breaks*.
This doesn't affect :rfc:`2047` encoded lines.
The :class:`Header` class also provides a number of methods to support standard
operators and built-in functions.
.. method:: Header.__str__()
A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``.
.. method:: Header.__unicode__()
A helper for the built-in :func:`unicode` function. Returns the header as a
Unicode string.
.. method:: Header.__eq__(other)
This method allows you to compare two :class:`Header` instances for equality.
.. method:: Header.__ne__(other)
This method allows you to compare two :class:`Header` instances for inequality.
The :mod:`email.header` module also provides the following convenient functions.
.. function:: decode_header(header)
Decode a message header value without converting the character set. The header
value is in *header*.
This function returns a list of ``(decoded_string, charset)`` pairs containing
each of the decoded parts of the header. *charset* is ``None`` for non-encoded
parts of the header, otherwise a lower case string containing the name of the
character set specified in the encoded string.
Here's an example::
>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[('p\xf6stal', 'iso-8859-1')]
.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
Create a :class:`Header` instance from a sequence of pairs as returned by
:func:`decode_header`.
:func:`decode_header` takes a header value string and returns a sequence of
pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
the character set.
This function takes one of those sequence of pairs and returns a :class:`Header`
instance. Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in
the :class:`Header` constructor.

62
Doc-3k/library/email.iterators.rst Normal file
View File

@@ -0,0 +1,62 @@
.. module:: email.iterators
:synopsis: Iterate over a message object tree.
Iterating over a message object tree is fairly easy with the
:meth:`Message.walk` method. The :mod:`email.iterators` module provides some
useful higher level iterations over message object trees.
.. function:: body_line_iterator(msg[, decode])
This iterates over all the payloads in all the subparts of *msg*, returning the
string payloads line-by-line. It skips over all the subpart headers, and it
skips over any subpart with a payload that isn't a Python string. This is
somewhat equivalent to reading the flat text representation of the message from
a file using :meth:`readline`, skipping over all the intervening headers.
Optional *decode* is passed through to :meth:`Message.get_payload`.
.. function:: typed_subpart_iterator(msg[, maintype[, subtype]])
This iterates over all the subparts of *msg*, returning only those subparts that
match the MIME type specified by *maintype* and *subtype*.
Note that *subtype* is optional; if omitted, then subpart MIME type matching is
done only with the main type. *maintype* is optional too; it defaults to
:mimetype:`text`.
Thus, by default :func:`typed_subpart_iterator` returns each subpart that has a
MIME type of :mimetype:`text/\*`.
The following function has been added as a useful debugging tool. It should
*not* be considered part of the supported public interface for the package.
.. function:: _structure(msg[, fp[, level]])
Prints an indented representation of the content types of the message object
structure. For example::
>>> msg = email.message_from_file(somefile)
>>> _structure(msg)
multipart/mixed
text/plain
text/plain
multipart/digest
message/rfc822
text/plain
message/rfc822
text/plain
message/rfc822
text/plain
message/rfc822
text/plain
message/rfc822
text/plain
text/plain
Optional *fp* is a file-like object to print the output to. It must be suitable
for Python's extended print statement. *level* is used internally.

545
Doc-3k/library/email.message.rst Normal file
View File

@@ -0,0 +1,545 @@
.. module:: email.message
:synopsis: The base class representing email messages.
The central class in the :mod:`email` package is the :class:`Message` class,
imported from the :mod:`email.message` module. It is the base class for the
:mod:`email` object model. :class:`Message` provides the core functionality for
setting and querying header fields, and for accessing message bodies.
Conceptually, a :class:`Message` object consists of *headers* and *payloads*.
Headers are :rfc:`2822` style field names and values where the field name and
value are separated by a colon. The colon is not part of either the field name
or the field value.
Headers are stored and returned in case-preserving form but are matched case-
insensitively. There may also be a single envelope header, also known as the
*Unix-From* header or the ``From_`` header. The payload is either a string in
the case of simple message objects or a list of :class:`Message` objects for
MIME container documents (e.g. :mimetype:`multipart/\*` and
:mimetype:`message/rfc822`).
:class:`Message` objects provide a mapping style interface for accessing the
message headers, and an explicit interface for accessing both the headers and
the payload. It provides convenience methods for generating a flat text
representation of the message object tree, for accessing commonly used header
parameters, and for recursively walking over the object tree.
Here are the methods of the :class:`Message` class:
.. class:: Message()
The constructor takes no arguments.
.. method:: Message.as_string([unixfrom])
Return the entire message flatten as a string. When optional *unixfrom* is
``True``, the envelope header is included in the returned string. *unixfrom*
defaults to ``False``.
Note that this method is provided as a convenience and may not always format the
message the way you want. For example, by default it mangles lines that begin
with ``From``. For more flexibility, instantiate a :class:`Generator` instance
and use its :meth:`flatten` method directly. For example::
from cStringIO import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=False, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()
.. method:: Message.__str__()
Equivalent to :meth:`as_string(unixfrom=True)`.
.. method:: Message.is_multipart()
Return ``True`` if the message's payload is a list of sub-\ :class:`Message`
objects, otherwise return ``False``. When :meth:`is_multipart` returns False,
the payload should be a string object.
.. method:: Message.set_unixfrom(unixfrom)
Set the message's envelope header to *unixfrom*, which should be a string.
.. method:: Message.get_unixfrom()
Return the message's envelope header. Defaults to ``None`` if the envelope
header was never set.
.. method:: Message.attach(payload)
Add the given *payload* to the current payload, which must be ``None`` or a list
of :class:`Message` objects before the call. After the call, the payload will
always be a list of :class:`Message` objects. If you want to set the payload to
a scalar object (e.g. a string), use :meth:`set_payload` instead.
.. method:: Message.get_payload([i[, decode]])
Return a reference the current payload, which will be a list of :class:`Message`
objects when :meth:`is_multipart` is ``True``, or a string when
:meth:`is_multipart` is ``False``. If the payload is a list and you mutate the
list object, you modify the message's payload in place.
With optional argument *i*, :meth:`get_payload` will return the *i*-th element
of the payload, counting from zero, if :meth:`is_multipart` is ``True``. An
:exc:`IndexError` will be raised if *i* is less than 0 or greater than or equal
to the number of items in the payload. If the payload is a string (i.e.
:meth:`is_multipart` is ``False``) and *i* is given, a :exc:`TypeError` is
raised.
Optional *decode* is a flag indicating whether the payload should be decoded or
not, according to the :mailheader:`Content-Transfer-Encoding` header. When
``True`` and the message is not a multipart, the payload will be decoded if this
header's value is ``quoted-printable`` or ``base64``. If some other encoding is
used, or :mailheader:`Content-Transfer-Encoding` header is missing, or if the
payload has bogus base64 data, the payload is returned as-is (undecoded). If
the message is a multipart and the *decode* flag is ``True``, then ``None`` is
returned. The default for *decode* is ``False``.
.. method:: Message.set_payload(payload[, charset])
Set the entire message object's payload to *payload*. It is the client's
responsibility to ensure the payload invariants. Optional *charset* sets the
message's default character set; see :meth:`set_charset` for details.
.. versionchanged:: 2.2.2
*charset* argument added.
.. method:: Message.set_charset(charset)
Set the character set of the payload to *charset*, which can either be a
:class:`Charset` instance (see :mod:`email.charset`), a string naming a
character set, or ``None``. If it is a string, it will be converted to a
:class:`Charset` instance. If *charset* is ``None``, the ``charset`` parameter
will be removed from the :mailheader:`Content-Type` header. Anything else will
generate a :exc:`TypeError`.
The message will be assumed to be of type :mimetype:`text/\*` encoded with
*charset.input_charset*. It will be converted to *charset.output_charset* and
encoded properly, if needed, when generating the plain text representation of
the message. MIME headers (:mailheader:`MIME-Version`,
:mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will be
added as needed.
.. versionadded:: 2.2.2
.. method:: Message.get_charset()
Return the :class:`Charset` instance associated with the message's payload.
.. versionadded:: 2.2.2
The following methods implement a mapping-like interface for accessing the
message's :rfc:`2822` headers. Note that there are some semantic differences
between these methods and a normal mapping (i.e. dictionary) interface. For
example, in a dictionary there are no duplicate keys, but here there may be
duplicate message headers. Also, in dictionaries there is no guaranteed order
to the keys returned by :meth:`keys`, but in a :class:`Message` object, headers
are always returned in the order they appeared in the original message, or were
added to the message later. Any header deleted and then re-added are always
appended to the end of the header list.
These semantic differences are intentional and are biased toward maximal
convenience.
Note that in all cases, any envelope header present in the message is not
included in the mapping interface.
.. method:: Message.__len__()
Return the total number of headers, including duplicates.
.. method:: Message.__contains__(name)
Return true if the message object has a field named *name*. Matching is done
case-insensitively and *name* should not include the trailing colon. Used for
the ``in`` operator, e.g.::
if 'message-id' in myMessage:
print 'Message-ID:', myMessage['message-id']
.. method:: Message.__getitem__(name)
Return the value of the named header field. *name* should not include the colon
field separator. If the header is missing, ``None`` is returned; a
:exc:`KeyError` is never raised.
Note that if the named field appears more than once in the message's headers,
exactly which of those field values will be returned is undefined. Use the
:meth:`get_all` method to get the values of all the extant named headers.
.. method:: Message.__setitem__(name, val)
Add a header to the message with field name *name* and value *val*. The field
is appended to the end of the message's existing fields.
Note that this does *not* overwrite or delete any existing header with the same
name. If you want to ensure that the new header is the only one present in the
message with field name *name*, delete the field first, e.g.::
del msg['subject']
msg['subject'] = 'Python roolz!'
.. method:: Message.__delitem__(name)
Delete all occurrences of the field with name *name* from the message's headers.
No exception is raised if the named field isn't present in the headers.
.. method:: Message.has_key(name)
Return true if the message contains a header field named *name*, otherwise
return false.
.. method:: Message.keys()
Return a list of all the message's header field names.
.. method:: Message.values()
Return a list of all the message's field values.
.. method:: Message.items()
Return a list of 2-tuples containing all the message's field headers and values.
.. method:: Message.get(name[, failobj])
Return the value of the named header field. This is identical to
:meth:`__getitem__` except that optional *failobj* is returned if the named
header is missing (defaults to ``None``).
Here are some additional useful methods:
.. method:: Message.get_all(name[, failobj])
Return a list of all the values for the field named *name*. If there are no such
named headers in the message, *failobj* is returned (defaults to ``None``).
.. method:: Message.add_header(_name, _value, **_params)
Extended header setting. This method is similar to :meth:`__setitem__` except
that additional header parameters can be provided as keyword arguments. *_name*
is the header field to add and *_value* is the *primary* value for the header.
For each item in the keyword argument dictionary *_params*, the key is taken as
the parameter name, with underscores converted to dashes (since dashes are
illegal in Python identifiers). Normally, the parameter will be added as
``key="value"`` unless the value is ``None``, in which case only the key will be
added.
Here's an example::
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
This will add a header that looks like ::
Content-Disposition: attachment; filename="bud.gif"
.. method:: Message.replace_header(_name, _value)
Replace a header. Replace the first header found in the message that matches
*_name*, retaining header order and field name case. If no matching header was
found, a :exc:`KeyError` is raised.
.. versionadded:: 2.2.2
.. method:: Message.get_content_type()
Return the message's content type. The returned string is coerced to lower case
of the form :mimetype:`maintype/subtype`. If there was no
:mailheader:`Content-Type` header in the message the default type as given by
:meth:`get_default_type` will be returned. Since according to :rfc:`2045`,
messages always have a default type, :meth:`get_content_type` will always return
a value.
:rfc:`2045` defines a message's default type to be :mimetype:`text/plain` unless
it appears inside a :mimetype:`multipart/digest` container, in which case it
would be :mimetype:`message/rfc822`. If the :mailheader:`Content-Type` header
has an invalid type specification, :rfc:`2045` mandates that the default type be
:mimetype:`text/plain`.
.. versionadded:: 2.2.2
.. method:: Message.get_content_maintype()
Return the message's main content type. This is the :mimetype:`maintype` part
of the string returned by :meth:`get_content_type`.
.. versionadded:: 2.2.2
.. method:: Message.get_content_subtype()
Return the message's sub-content type. This is the :mimetype:`subtype` part of
the string returned by :meth:`get_content_type`.
.. versionadded:: 2.2.2
.. method:: Message.get_default_type()
Return the default content type. Most messages have a default content type of
:mimetype:`text/plain`, except for messages that are subparts of
:mimetype:`multipart/digest` containers. Such subparts have a default content
type of :mimetype:`message/rfc822`.
.. versionadded:: 2.2.2
.. method:: Message.set_default_type(ctype)
Set the default content type. *ctype* should either be :mimetype:`text/plain`
or :mimetype:`message/rfc822`, although this is not enforced. The default
content type is not stored in the :mailheader:`Content-Type` header.
.. versionadded:: 2.2.2
.. method:: Message.get_params([failobj[, header[, unquote]]])
Return the message's :mailheader:`Content-Type` parameters, as a list. The
elements of the returned list are 2-tuples of key/value pairs, as split on the
``'='`` sign. The left hand side of the ``'='`` is the key, while the right
hand side is the value. If there is no ``'='`` sign in the parameter the value
is the empty string, otherwise the value is as described in :meth:`get_param`
and is unquoted if optional *unquote* is ``True`` (the default).
Optional *failobj* is the object to return if there is no
:mailheader:`Content-Type` header. Optional *header* is the header to search
instead of :mailheader:`Content-Type`.
.. versionchanged:: 2.2.2
*unquote* argument added.
.. method:: Message.get_param(param[, failobj[, header[, unquote]]])
Return the value of the :mailheader:`Content-Type` header's parameter *param* as
a string. If the message has no :mailheader:`Content-Type` header or if there
is no such parameter, then *failobj* is returned (defaults to ``None``).
Optional *header* if given, specifies the message header to use instead of
:mailheader:`Content-Type`.
Parameter keys are always compared case insensitively. The return value can
either be a string, or a 3-tuple if the parameter was :rfc:`2231` encoded. When
it's a 3-tuple, the elements of the value are of the form ``(CHARSET, LANGUAGE,
VALUE)``. Note that both ``CHARSET`` and ``LANGUAGE`` can be ``None``, in which
case you should consider ``VALUE`` to be encoded in the ``us-ascii`` charset.
You can usually ignore ``LANGUAGE``.
If your application doesn't care whether the parameter was encoded as in
:rfc:`2231`, you can collapse the parameter value by calling
:func:`email.Utils.collapse_rfc2231_value`, passing in the return value from
:meth:`get_param`. This will return a suitably decoded Unicode string whn the
value is a tuple, or the original string unquoted if it isn't. For example::
rawparam = msg.get_param('foo')
param = email.Utils.collapse_rfc2231_value(rawparam)
In any case, the parameter value (either the returned string, or the ``VALUE``
item in the 3-tuple) is always unquoted, unless *unquote* is set to ``False``.
.. versionchanged:: 2.2.2
*unquote* argument added, and 3-tuple return value possible.
.. method:: Message.set_param(param, value[, header[, requote[, charset[, language]]]])
Set a parameter in the :mailheader:`Content-Type` header. If the parameter
already exists in the header, its value will be replaced with *value*. If the
:mailheader:`Content-Type` header as not yet been defined for this message, it
will be set to :mimetype:`text/plain` and the new parameter value will be
appended as per :rfc:`2045`.
Optional *header* specifies an alternative header to :mailheader:`Content-Type`,
and all parameters will be quoted as necessary unless optional *requote* is
``False`` (the default is ``True``).
If optional *charset* is specified, the parameter will be encoded according to
:rfc:`2231`. Optional *language* specifies the RFC 2231 language, defaulting to
the empty string. Both *charset* and *language* should be strings.
.. versionadded:: 2.2.2
.. method:: Message.del_param(param[, header[, requote]])
Remove the given parameter completely from the :mailheader:`Content-Type`
header. The header will be re-written in place without the parameter or its
value. All values will be quoted as necessary unless *requote* is ``False``
(the default is ``True``). Optional *header* specifies an alternative to
:mailheader:`Content-Type`.
.. versionadded:: 2.2.2
.. method:: Message.set_type(type[, header][, requote])
Set the main type and subtype for the :mailheader:`Content-Type` header. *type*
must be a string in the form :mimetype:`maintype/subtype`, otherwise a
:exc:`ValueError` is raised.
This method replaces the :mailheader:`Content-Type` header, keeping all the
parameters in place. If *requote* is ``False``, this leaves the existing
header's quoting as is, otherwise the parameters will be quoted (the default).
An alternative header can be specified in the *header* argument. When the
:mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` header is
also added.
.. versionadded:: 2.2.2
.. method:: Message.get_filename([failobj])
Return the value of the ``filename`` parameter of the
:mailheader:`Content-Disposition` header of the message. If the header does not
have a ``filename`` parameter, this method falls back to looking for the
``name`` parameter. If neither is found, or the header is missing, then
*failobj* is returned. The returned string will always be unquoted as per
:meth:`Utils.unquote`.
.. method:: Message.get_boundary([failobj])
Return the value of the ``boundary`` parameter of the :mailheader:`Content-Type`
header of the message, or *failobj* if either the header is missing, or has no
``boundary`` parameter. The returned string will always be unquoted as per
:meth:`Utils.unquote`.
.. method:: Message.set_boundary(boundary)
Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
*boundary*. :meth:`set_boundary` will always quote *boundary* if necessary. A
:exc:`HeaderParseError` is raised if the message object has no
:mailheader:`Content-Type` header.
Note that using this method is subtly different than deleting the old
:mailheader:`Content-Type` header and adding a new one with the new boundary via
:meth:`add_header`, because :meth:`set_boundary` preserves the order of the
:mailheader:`Content-Type` header in the list of headers. However, it does *not*
preserve any continuation lines which may have been present in the original
:mailheader:`Content-Type` header.
.. method:: Message.get_content_charset([failobj])
Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
coerced to lower case. If there is no :mailheader:`Content-Type` header, or if
that header has no ``charset`` parameter, *failobj* is returned.
Note that this method differs from :meth:`get_charset` which returns the
:class:`Charset` instance for the default encoding of the message body.
.. versionadded:: 2.2.2
.. method:: Message.get_charsets([failobj])
Return a list containing the character set names in the message. If the message
is a :mimetype:`multipart`, then the list will contain one element for each
subpart in the payload, otherwise, it will be a list of length 1.
Each item in the list will be a string which is the value of the ``charset``
parameter in the :mailheader:`Content-Type` header for the represented subpart.
However, if the subpart has no :mailheader:`Content-Type` header, no ``charset``
parameter, or is not of the :mimetype:`text` main MIME type, then that item in
the returned list will be *failobj*.
.. method:: Message.walk()
The :meth:`walk` method is an all-purpose generator which can be used to iterate
over all the parts and subparts of a message object tree, in depth-first
traversal order. You will typically use :meth:`walk` as the iterator in a
``for`` loop; each iteration returns the next subpart.
Here's an example that prints the MIME type of every part of a multipart message
structure::
>>> for part in msg.walk():
... print part.get_content_type()
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
.. versionchanged:: 2.5
The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
:meth:`get_subtype` were removed.
:class:`Message` objects can also optionally contain two instance attributes,
which can be used when generating the plain text of a MIME message.
.. data:: preamble
The format of a MIME document allows for some text between the blank line
following the headers, and the first multipart boundary string. Normally, this
text is never visible in a MIME-aware mail reader because it falls outside the
standard MIME armor. However, when viewing the raw text of the message, or when
viewing the message in a non-MIME aware reader, this text can become visible.
The *preamble* attribute contains this leading extra-armor text for MIME
documents. When the :class:`Parser` discovers some text after the headers but
before the first boundary string, it assigns this text to the message's
*preamble* attribute. When the :class:`Generator` is writing out the plain text
representation of a MIME message, and it finds the message has a *preamble*
attribute, it will write this text in the area between the headers and the first
boundary. See :mod:`email.parser` and :mod:`email.generator` for details.
Note that if the message object has no preamble, the *preamble* attribute will
be ``None``.
.. data:: epilogue
The *epilogue* attribute acts the same way as the *preamble* attribute, except
that it contains text that appears between the last boundary and the end of the
message.
.. versionchanged:: 2.5
You do not need to set the epilogue to the empty string in order for the
:class:`Generator` to print a newline at the end of the file.
.. data:: defects
The *defects* attribute contains a list of all the problems found when parsing
this message. See :mod:`email.errors` for a detailed description of the
possible parsing defects.
.. versionadded:: 2.4

171
Doc-3k/library/email.mime.rst Normal file
View File

@@ -0,0 +1,171 @@
.. module:: email.mime.text
Ordinarily, you get a message object structure by passing a file or some text to
a parser, which parses the text and returns the root message object. However
you can also build a complete message structure from scratch, or even individual
:class:`Message` objects by hand. In fact, you can also take an existing
structure and add new :class:`Message` objects, move them around, etc. This
makes a very convenient interface for slicing-and-dicing MIME messages.
You can create a new object structure by creating :class:`Message` instances,
adding attachments and all the appropriate headers manually. For MIME messages
though, the :mod:`email` package provides some convenient subclasses to make
things easier.
Here are the classes:
.. class:: MIMEBase(_maintype, _subtype, **_params)
Module: :mod:`email.mime.base`
This is the base class for all the MIME-specific subclasses of :class:`Message`.
Ordinarily you won't create instances specifically of :class:`MIMEBase`,
although you could. :class:`MIMEBase` is provided primarily as a convenient
base class for more specific MIME-aware subclasses.
*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is a parameter
key/value dictionary and is passed directly to :meth:`Message.add_header`.
The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
(based on *_maintype*, *_subtype*, and *_params*), and a
:mailheader:`MIME-Version` header (always set to ``1.0``).
.. class:: MIMENonMultipart()
Module: :mod:`email.mime.nonmultipart`
A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
messages that are not :mimetype:`multipart`. The primary purpose of this class
is to prevent the use of the :meth:`attach` method, which only makes sense for
:mimetype:`multipart` messages. If :meth:`attach` is called, a
:exc:`MultipartConversionError` exception is raised.
.. versionadded:: 2.2.2
.. class:: MIMEMultipart([subtype[, boundary[, _subparts[, _params]]]])
Module: :mod:`email.mime.multipart`
A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
messages that are :mimetype:`multipart`. Optional *_subtype* defaults to
:mimetype:`mixed`, but can be used to specify the subtype of the message. A
:mailheader:`Content-Type` header of :mimetype:`multipart/`*_subtype* will be
added to the message object. A :mailheader:`MIME-Version` header will also be
added.
Optional *boundary* is the multipart boundary string. When ``None`` (the
default), the boundary is calculated when needed.
*_subparts* is a sequence of initial subparts for the payload. It must be
possible to convert this sequence to a list. You can always attach new subparts
to the message by using the :meth:`Message.attach` method.
Additional parameters for the :mailheader:`Content-Type` header are taken from
the keyword arguments, or passed into the *_params* argument, which is a keyword
dictionary.
.. versionadded:: 2.2.2
.. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])
Module: :mod:`email.mime.application`
A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is
used to represent MIME message objects of major type :mimetype:`application`.
*_data* is a string containing the raw byte data. Optional *_subtype* specifies
the MIME subtype and defaults to :mimetype:`octet-stream`.
Optional *_encoder* is a callable (i.e. function) which will perform the actual
encoding of the data for transport. This callable takes one argument, which is
the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and
:meth:`set_payload` to change the payload to encoded form. It should also add
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
*_params* are passed straight through to the base class constructor.
.. versionadded:: 2.5
.. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])
Module: :mod:`email.mime.audio`
A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to
create MIME message objects of major type :mimetype:`audio`. *_audiodata* is a
string containing the raw audio data. If this data can be decoded by the
standard Python module :mod:`sndhdr`, then the subtype will be automatically
included in the :mailheader:`Content-Type` header. Otherwise you can explicitly
specify the audio subtype via the *_subtype* parameter. If the minor type could
not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
Optional *_encoder* is a callable (i.e. function) which will perform the actual
encoding of the audio data for transport. This callable takes one argument,
which is the :class:`MIMEAudio` instance. It should use :meth:`get_payload` and
:meth:`set_payload` to change the payload to encoded form. It should also add
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
*_params* are passed straight through to the base class constructor.
.. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])
Module: :mod:`email.mime.image`
A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to
create MIME message objects of major type :mimetype:`image`. *_imagedata* is a
string containing the raw image data. If this data can be decoded by the
standard Python module :mod:`imghdr`, then the subtype will be automatically
included in the :mailheader:`Content-Type` header. Otherwise you can explicitly
specify the image subtype via the *_subtype* parameter. If the minor type could
not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
Optional *_encoder* is a callable (i.e. function) which will perform the actual
encoding of the image data for transport. This callable takes one argument,
which is the :class:`MIMEImage` instance. It should use :meth:`get_payload` and
:meth:`set_payload` to change the payload to encoded form. It should also add
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
*_params* are passed straight through to the :class:`MIMEBase` constructor.
.. class:: MIMEMessage(_msg[, _subtype])
Module: :mod:`email.mime.message`
A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used
to create MIME objects of main type :mimetype:`message`. *_msg* is used as the
payload, and must be an instance of class :class:`Message` (or a subclass
thereof), otherwise a :exc:`TypeError` is raised.
Optional *_subtype* sets the subtype of the message; it defaults to
:mimetype:`rfc822`.
.. class:: MIMEText(_text[, _subtype[, _charset]])
Module: :mod:`email.mime.text`
A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to
create MIME objects of major type :mimetype:`text`. *_text* is the string for
the payload. *_subtype* is the minor type and defaults to :mimetype:`plain`.
*_charset* is the character set of the text and is passed as a parameter to the
:class:`MIMENonMultipart` constructor; it defaults to ``us-ascii``. No guessing
or encoding is performed on the text data.
.. versionchanged:: 2.4
The previously deprecated *_encoding* argument has been removed. Encoding
happens implicitly based on the *_charset* argument.

217
Doc-3k/library/email.parser.rst Normal file
View File

@@ -0,0 +1,217 @@
.. module:: email.parser
:synopsis: Parse flat text email messages to produce a message object structure.
Message object structures can be created in one of two ways: they can be created
from whole cloth by instantiating :class:`Message` objects and stringing them
together via :meth:`attach` and :meth:`set_payload` calls, or they can be
created by parsing a flat text representation of the email message.
The :mod:`email` package provides a standard parser that understands most email
document structures, including MIME documents. You can pass the parser a string
or a file object, and the parser will return to you the root :class:`Message`
instance of the object structure. For simple, non-MIME messages the payload of
this root object will likely be a string containing the text of the message.
For MIME messages, the root object will return ``True`` from its
:meth:`is_multipart` method, and the subparts can be accessed via the
:meth:`get_payload` and :meth:`walk` methods.
There are actually two parser interfaces available for use, the classic
:class:`Parser` API and the incremental :class:`FeedParser` API. The classic
:class:`Parser` API is fine if you have the entire text of the message in memory
as a string, or if the entire message lives in a file on the file system.
:class:`FeedParser` is more appropriate for when you're reading the message from
a stream which might block waiting for more input (e.g. reading an email message
from a socket). The :class:`FeedParser` can consume and parse the message
incrementally, and only returns the root object when you close the parser [#]_.
Note that the parser can be extended in limited ways, and of course you can
implement your own parser completely from scratch. There is no magical
connection between the :mod:`email` package's bundled parser and the
:class:`Message` class, so your custom parser can create message object trees
any way it finds necessary.
FeedParser API
^^^^^^^^^^^^^^
.. versionadded:: 2.4
The :class:`FeedParser`, imported from the :mod:`email.feedparser` module,
provides an API that is conducive to incremental parsing of email messages, such
as would be necessary when reading the text of an email message from a source
that can block (e.g. a socket). The :class:`FeedParser` can of course be used
to parse an email message fully contained in a string or a file, but the classic
:class:`Parser` API may be more convenient for such use cases. The semantics
and results of the two parser APIs are identical.
The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch
of text until there's no more to feed it, then close the parser to retrieve the
root message object. The :class:`FeedParser` is extremely accurate when parsing
standards-compliant messages, and it does a very good job of parsing non-
compliant messages, providing information about how a message was deemed broken.
It will populate a message object's *defects* attribute with a list of any
problems it found in a message. See the :mod:`email.errors` module for the list
of defects that it can find.
Here is the API for the :class:`FeedParser`:
.. class:: FeedParser([_factory])
Create a :class:`FeedParser` instance. Optional *_factory* is a no-argument
callable that will be called whenever a new message object is needed. It
defaults to the :class:`email.message.Message` class.
.. method:: FeedParser.feed(data)
Feed the :class:`FeedParser` some more data. *data* should be a string
containing one or more lines. The lines can be partial and the
:class:`FeedParser` will stitch such partial lines together properly. The lines
in the string can have any of the common three line endings, carriage return,
newline, or carriage return and newline (they can even be mixed).
.. method:: FeedParser.close()
Closing a :class:`FeedParser` completes the parsing of all previously fed data,
and returns the root message object. It is undefined what happens if you feed
more data to a closed :class:`FeedParser`.
Parser class API
^^^^^^^^^^^^^^^^
The :class:`Parser` class, imported from the :mod:`email.parser` module,
provides an API that can be used to parse a message when the complete contents
of the message are available in a string or file. The :mod:`email.parser`
module also provides a second class, called :class:`HeaderParser` which can be
used if you're only interested in the headers of the message.
:class:`HeaderParser` can be much faster in these situations, since it does not
attempt to parse the message body, instead setting the payload to the raw body
as a string. :class:`HeaderParser` has the same API as the :class:`Parser`
class.
.. class:: Parser([_class])
The constructor for the :class:`Parser` class takes an optional argument
*_class*. This must be a callable factory (such as a function or a class), and
it is used whenever a sub-message object needs to be created. It defaults to
:class:`Message` (see :mod:`email.message`). The factory will be called without
arguments.
The optional *strict* flag is ignored.
.. deprecated:: 2.4
Because the :class:`Parser` class is a backward compatible API wrapper around
the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is effectively non-
strict. You should simply stop passing a *strict* flag to the :class:`Parser`
constructor.
.. versionchanged:: 2.2.2
The *strict* flag was added.
.. versionchanged:: 2.4
The *strict* flag was deprecated.
The other public :class:`Parser` methods are:
.. method:: Parser.parse(fp[, headersonly])
Read all the data from the file-like object *fp*, parse the resulting text, and
return the root message object. *fp* must support both the :meth:`readline` and
the :meth:`read` methods on file-like objects.
The text contained in *fp* must be formatted as a block of :rfc:`2822` style
headers and header continuation lines, optionally preceded by a envelope header.
The header block is terminated either by the end of the data or by a blank line.
Following the header block is the body of the message (which may contain MIME-
encoded subparts).
Optional *headersonly* is as with the :meth:`parse` method.
.. versionchanged:: 2.2.2
The *headersonly* flag was added.
.. method:: Parser.parsestr(text[, headersonly])
Similar to the :meth:`parse` method, except it takes a string object instead of
a file-like object. Calling this method on a string is exactly equivalent to
wrapping *text* in a :class:`StringIO` instance first and calling :meth:`parse`.
Optional *headersonly* is a flag specifying whether to stop parsing after
reading the headers or not. The default is ``False``, meaning it parses the
entire contents of the file.
.. versionchanged:: 2.2.2
The *headersonly* flag was added.
Since creating a message object structure from a string or a file object is such
a common task, two functions are provided as a convenience. They are available
in the top-level :mod:`email` package namespace.
.. function:: message_from_string(s[, _class[, strict]])
Return a message object structure from a string. This is exactly equivalent to
``Parser().parsestr(s)``. Optional *_class* and *strict* are interpreted as
with the :class:`Parser` class constructor.
.. versionchanged:: 2.2.2
The *strict* flag was added.
.. function:: message_from_file(fp[, _class[, strict]])
Return a message object structure tree from an open file object. This is
exactly equivalent to ``Parser().parse(fp)``. Optional *_class* and *strict*
are interpreted as with the :class:`Parser` class constructor.
.. versionchanged:: 2.2.2
The *strict* flag was added.
Here's an example of how you might use this at an interactive Python prompt::
>>> import email
>>> msg = email.message_from_string(myString)
Additional notes
^^^^^^^^^^^^^^^^
Here are some notes on the parsing semantics:
* Most non-\ :mimetype:`multipart` type messages are parsed as a single message
object with a string payload. These objects will return ``False`` for
:meth:`is_multipart`. Their :meth:`get_payload` method will return a string
object.
* All :mimetype:`multipart` type messages will be parsed as a container message
object with a list of sub-message objects for their payload. The outer
container message will return ``True`` for :meth:`is_multipart` and their
:meth:`get_payload` method will return the list of :class:`Message` subparts.
* Most messages with a content type of :mimetype:`message/\*` (e.g.
:mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
parsed as container object containing a list payload of length 1. Their
:meth:`is_multipart` method will return ``True``. The single element in the
list payload will be a sub-message object.
* Some non-standards compliant messages may not be internally consistent about
their :mimetype:`multipart`\ -edness. Such messages may have a
:mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
:meth:`is_multipart` method may return ``False``. If such messages were parsed
with the :class:`FeedParser`, they will have an instance of the
:class:`MultipartInvariantViolationDefect` class in their *defects* attribute
list. See :mod:`email.errors` for details.
.. rubric:: Footnotes
.. [#] As of email package version 3.0, introduced in Python 2.4, the classic
:class:`Parser` was re-implemented in terms of the :class:`FeedParser`, so the
semantics and results are identical between the two parsers.

415
Doc-3k/library/email.rst Normal file
View File

@@ -0,0 +1,415 @@
.. % Copyright (C) 2001-2007 Python Software Foundation
.. % Author: barry@python.org (Barry Warsaw)
:mod:`email` --- An email and MIME handling package
===================================================
.. module:: email
:synopsis: Package supporting the parsing, manipulating, and generating email messages,
including MIME documents.
.. moduleauthor:: Barry A. Warsaw <barry@python.org>
.. sectionauthor:: Barry A. Warsaw <barry@python.org>
.. versionadded:: 2.2
The :mod:`email` package is a library for managing email messages, including
MIME and other :rfc:`2822`\ -based message documents. It subsumes most of the
functionality in several older standard modules such as :mod:`rfc822`,
:mod:`mimetools`, :mod:`multifile`, and other non-standard packages such as
:mod:`mimecntl`. It is specifically *not* designed to do any sending of email
messages to SMTP (:rfc:`2821`), NNTP, or other servers; those are functions of
modules such as :mod:`smtplib` and :mod:`nntplib`. The :mod:`email` package
attempts to be as RFC-compliant as possible, supporting in addition to
:rfc:`2822`, such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`,
and :rfc:`2231`.
The primary distinguishing feature of the :mod:`email` package is that it splits
the parsing and generating of email messages from the internal *object model*
representation of email. Applications using the :mod:`email` package deal
primarily with objects; you can add sub-objects to messages, remove sub-objects
from messages, completely re-arrange the contents, etc. There is a separate
parser and a separate generator which handles the transformation from flat text
to the object model, and then back to flat text again. There are also handy
subclasses for some common MIME object types, and a few miscellaneous utilities
that help with such common tasks as extracting and parsing message field values,
creating RFC-compliant dates, etc.
The following sections describe the functionality of the :mod:`email` package.
The ordering follows a progression that should be common in applications: an
email message is read as flat text from a file or other source, the text is
parsed to produce the object structure of the email message, this structure is
manipulated, and finally, the object tree is rendered back into flat text.
It is perfectly feasible to create the object structure out of whole cloth ---
i.e. completely from scratch. From there, a similar progression can be taken as
above.
Also included are detailed specifications of all the classes and modules that
the :mod:`email` package provides, the exception classes you might encounter
while using the :mod:`email` package, some auxiliary utilities, and a few
examples. For users of the older :mod:`mimelib` package, or previous versions
of the :mod:`email` package, a section on differences and porting is provided.
.. seealso::
Module :mod:`smtplib`
SMTP protocol client
Module :mod:`nntplib`
NNTP protocol client
Representing an email message
-----------------------------
.. include:: email.message.rst
Parsing email messages
----------------------
.. include:: email.parser.rst
Generating MIME documents
-------------------------
.. include:: email.generator.rst
Creating email and MIME objects from scratch
--------------------------------------------
.. include:: email.mime.rst
Internationalized headers
-------------------------
.. include:: email.header.rst
Representing character sets
---------------------------
.. include:: email.charset.rst
Encoders
--------
.. include:: email.encoders.rst
Exception and Defect classes
----------------------------
.. include:: email.errors.rst
Miscellaneous utilities
-----------------------
.. include:: email.util.rst
Iterators
---------
.. include:: email.iterators.rst
.. _email-pkg-history:
Package History
---------------
This table describes the release history of the email package, corresponding to
the version of Python that the package was released with. For purposes of this
document, when you see a note about change or added versions, these refer to the
Python version the change was made in, *not* the email package version. This
table also describes the Python compatibility of each version of the package.
+---------------+------------------------------+-----------------------+
| email version | distributed with | compatible with |
+===============+==============================+=======================+
| :const:`1.x` | Python 2.2.0 to Python 2.2.1 | *no longer supported* |
+---------------+------------------------------+-----------------------+
| :const:`2.5` | Python 2.2.2+ and Python 2.3 | Python 2.1 to 2.5 |
+---------------+------------------------------+-----------------------+
| :const:`3.0` | Python 2.4 | Python 2.3 to 2.5 |
+---------------+------------------------------+-----------------------+
| :const:`4.0` | Python 2.5 | Python 2.3 to 2.5 |
+---------------+------------------------------+-----------------------+
Here are the major differences between :mod:`email` version 4 and version 3:
* All modules have been renamed according to :pep:`8` standards. For example,
the version 3 module :mod:`email.Message` was renamed to :mod:`email.message` in
version 4.
* A new subpackage :mod:`email.mime` was added and all the version 3
:mod:`email.MIME\*` modules were renamed and situated into the :mod:`email.mime`
subpackage. For example, the version 3 module :mod:`email.MIMEText` was renamed
to :mod:`email.mime.text`.
*Note that the version 3 names will continue to work until Python 2.6*.
* The :mod:`email.mime.application` module was added, which contains the
:class:`MIMEApplication` class.
* Methods that were deprecated in version 3 have been removed. These include
:meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
* Fixes have been added for :rfc:`2231` support which can change some of the
return types for :func:`Message.get_param` and friends. Under some
circumstances, values which used to return a 3-tuple now return simple strings
(specifically, if all extended parameter segments were unencoded, there is no
language and charset designation expected, so the return type is now a simple
string). Also, %-decoding used to be done for both encoded and unencoded
segments; this decoding is now done only for encoded segments.
Here are the major differences between :mod:`email` version 3 and version 2:
* The :class:`FeedParser` class was introduced, and the :class:`Parser` class
was implemented in terms of the :class:`FeedParser`. All parsing therefore is
non-strict, and parsing will make a best effort never to raise an exception.
Problems found while parsing messages are stored in the message's *defect*
attribute.
* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
have been removed. These include the *_encoder* argument to the
:class:`MIMEText` constructor, the :meth:`Message.add_payload` method, the
:func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decode`
and :func:`Utils.encode`.
* New :exc:`DeprecationWarning`\ s have been added to:
:meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
argument to the :class:`Parser` class. These are expected to be removed in
future versions.
* Support for Pythons earlier than 2.3 has been removed.
Here are the differences between :mod:`email` version 2 and version 1:
* The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
* The pickle format for :class:`Message` instances has changed. Since this was
never (and still isn't) formally defined, this isn't considered a backward
incompatibility. However if your application pickles and unpickles
:class:`Message` instances, be aware that in :mod:`email` version 2,
:class:`Message` instances now have private variables *_charset* and
*_default_type*.
* Several methods in the :class:`Message` class have been deprecated, or their
signatures changed. Also, many new methods have been added. See the
documentation for the :class:`Message` class for details. The changes should be
completely backward compatible.
* The object structure has changed in the face of :mimetype:`message/rfc822`
content types. In :mod:`email` version 1, such a type would be represented by a
scalar payload, i.e. the container message's :meth:`is_multipart` returned
false, :meth:`get_payload` was not a list object, but a single :class:`Message`
instance.
This structure was inconsistent with the rest of the package, so the object
representation for :mimetype:`message/rfc822` content types was changed. In
:mod:`email` version 2, the container *does* return ``True`` from
:meth:`is_multipart`, and :meth:`get_payload` returns a list containing a single
:class:`Message` item.
Note that this is one place that backward compatibility could not be completely
maintained. However, if you're already testing the return type of
:meth:`get_payload`, you should be fine. You just need to make sure your code
doesn't do a :meth:`set_payload` with a :class:`Message` instance on a container
with a content type of :mimetype:`message/rfc822`.
* The :class:`Parser` constructor's *strict* argument was added, and its
:meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument. The
*strict* flag was also added to functions :func:`email.message_from_file` and
:func:`email.message_from_string`.
* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten`
instead. The :class:`Generator` class has also grown the :meth:`clone` method.
* The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was
added.
* The intermediate base classes :class:`MIMENonMultipart` and
:class:`MIMEMultipart` have been added, and interposed in the class hierarchy
for most of the other MIME-related derived classes.
* The *_encoder* argument to the :class:`MIMEText` constructor has been
deprecated. Encoding now happens implicitly based on the *_charset* argument.
* The following functions in the :mod:`email.Utils` module have been deprecated:
:func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following
functions have been added to the module: :func:`make_msgid`,
:func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`.
* The non-public function :func:`email.Iterators._structure` was added.
Differences from :mod:`mimelib`
-------------------------------
The :mod:`email` package was originally prototyped as a separate library called
`mimelib <http://mimelib.sf.net/>`_. Changes have been made so that method names
are more consistent, and some methods or modules have either been added or
removed. The semantics of some of the methods have also changed. For the most
part, any functionality available in :mod:`mimelib` is still available in the
:mod:`email` package, albeit often in a different way. Backward compatibility
between the :mod:`mimelib` package and the :mod:`email` package was not a
priority.
Here is a brief description of the differences between the :mod:`mimelib` and
the :mod:`email` packages, along with hints on how to port your applications.
Of course, the most visible difference between the two packages is that the
package name has been changed to :mod:`email`. In addition, the top-level
package has the following differences:
* :func:`messageFromString` has been renamed to :func:`message_from_string`.
* :func:`messageFromFile` has been renamed to :func:`message_from_file`.
The :class:`Message` class has the following differences:
* The method :meth:`asString` was renamed to :meth:`as_string`.
* The method :meth:`ismultipart` was renamed to :meth:`is_multipart`.
* The :meth:`get_payload` method has grown a *decode* optional argument.
* The method :meth:`getall` was renamed to :meth:`get_all`.
* The method :meth:`addheader` was renamed to :meth:`add_header`.
* The method :meth:`gettype` was renamed to :meth:`get_type`.
* The method :meth:`getmaintype` was renamed to :meth:`get_main_type`.
* The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
* The method :meth:`getparams` was renamed to :meth:`get_params`. Also, whereas
:meth:`getparams` returned a list of strings, :meth:`get_params` returns a list
of 2-tuples, effectively the key/value pairs of the parameters, split on the
``'='`` sign.
* The method :meth:`getparam` was renamed to :meth:`get_param`.
* The method :meth:`getcharsets` was renamed to :meth:`get_charsets`.
* The method :meth:`getfilename` was renamed to :meth:`get_filename`.
* The method :meth:`getboundary` was renamed to :meth:`get_boundary`.
* The method :meth:`setboundary` was renamed to :meth:`set_boundary`.
* The method :meth:`getdecodedpayload` was removed. To get similar
functionality, pass the value 1 to the *decode* flag of the get_payload()
method.
* The method :meth:`getpayloadastext` was removed. Similar functionality is
supported by the :class:`DecodedGenerator` class in the :mod:`email.generator`
module.
* The method :meth:`getbodyastext` was removed. You can get similar
functionality by creating an iterator with :func:`typed_subpart_iterator` in the
:mod:`email.iterators` module.
The :class:`Parser` class has no differences in its public interface. It does
have some additional smarts to recognize :mimetype:`message/delivery-status`
type messages, which it represents as a :class:`Message` instance containing
separate :class:`Message` subparts for each header block in the delivery status
notification [#]_.
The :class:`Generator` class has no differences in its public interface. There
is a new class in the :mod:`email.generator` module though, called
:class:`DecodedGenerator` which provides most of the functionality previously
available in the :meth:`Message.getpayloadastext` method.
The following modules and classes have been changed:
* The :class:`MIMEBase` class constructor arguments *_major* and *_minor* have
changed to *_maintype* and *_subtype* respectively.
* The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor*
argument has been renamed to *_subtype*.
* The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor*
argument has been renamed to *_subtype*.
* The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note
that an earlier version of :mod:`mimelib` called this class/module ``RFC822``,
but that clashed with the Python standard library module :mod:`rfc822` on some
case-insensitive file systems.
Also, the :class:`MIMEMessage` class now represents any kind of MIME message
with main type :mimetype:`message`. It takes an optional argument *_subtype*
which is used to set the MIME subtype. *_subtype* defaults to
:mimetype:`rfc822`.
:mod:`mimelib` provided some utility functions in its :mod:`address` and
:mod:`date` modules. All of these functions have been moved to the
:mod:`email.utils` module.
The ``MsgReader`` class/module has been removed. Its functionality is most
closely supported in the :func:`body_line_iterator` function in the
:mod:`email.iterators` module.
Examples
--------
Here are a few examples of how to use the :mod:`email` package to read, write,
and send simple email messages, as well as more complex MIME messages.
First, let's see how to create and send a simple text message:
.. include:: ../includes/email-simple.py
:literal:
Here's an example of how to send a MIME message containing a bunch of family
pictures that may be residing in a directory:
.. include:: ../includes/email-mime.py
:literal:
Here's an example of how to send the entire contents of a directory as an email
message: [#]_
.. include:: ../includes/email-dir.py
:literal:
And finally, here's an example of how to unpack a MIME message like the one
above, into a directory of files:
.. include:: ../includes/email-unpack.py
:literal:
.. rubric:: Footnotes
.. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`.
.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples.

163
Doc-3k/library/email.util.rst Normal file
View File

@@ -0,0 +1,163 @@
.. module:: email.utils
:synopsis: Miscellaneous email package utilities.
There are several useful utilities provided in the :mod:`email.utils` module:
.. function:: quote(str)
Return a new string with backslashes in *str* replaced by two backslashes, and
double quotes replaced by backslash-double quote.
.. function:: unquote(str)
Return a new string which is an *unquoted* version of *str*. If *str* ends and
begins with double quotes, they are stripped off. Likewise if *str* ends and
begins with angle brackets, they are stripped off.
.. function:: parseaddr(address)
Parse address -- which should be the value of some address-containing field such
as :mailheader:`To` or :mailheader:`Cc` -- into its constituent *realname* and
*email address* parts. Returns a tuple of that information, unless the parse
fails, in which case a 2-tuple of ``('', '')`` is returned.
.. function:: formataddr(pair)
The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form ``(realname,
email_address)`` and returns the string value suitable for a :mailheader:`To` or
:mailheader:`Cc` header. If the first element of *pair* is false, then the
second element is returned unmodified.
.. function:: getaddresses(fieldvalues)
This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
*fieldvalues* is a sequence of header field values as might be returned by
:meth:`Message.get_all`. Here's a simple example that gets all the recipients
of a message::
from email.utils import getaddresses
tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
.. function:: parsedate(date)
Attempts to parse a date according to the rules in :rfc:`2822`. however, some
mailers don't follow that format as specified, so :func:`parsedate` tries to
guess correctly in such cases. *date* is a string containing an :rfc:`2822`
date, such as ``"Mon, 20 Nov 1995 19:12:08 -0500"``. If it succeeds in parsing
the date, :func:`parsedate` returns a 9-tuple that can be passed directly to
:func:`time.mktime`; otherwise ``None`` will be returned. Note that indexes 6,
7, and 8 of the result tuple are not usable.
.. function:: parsedate_tz(date)
Performs the same function as :func:`parsedate`, but returns either ``None`` or
a 10-tuple; the first 9 elements make up a tuple that can be passed directly to
:func:`time.mktime`, and the tenth is the offset of the date's timezone from UTC
(which is the official term for Greenwich Mean Time) [#]_. If the input string
has no timezone, the last element of the tuple returned is ``None``. Note that
indexes 6, 7, and 8 of the result tuple are not usable.
.. function:: mktime_tz(tuple)
Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC timestamp. It
the timezone item in the tuple is ``None``, assume local time. Minor
deficiency: :func:`mktime_tz` interprets the first 8 elements of *tuple* as a
local time and then compensates for the timezone difference. This may yield a
slight error around changes in daylight savings time, though not worth worrying
about for common use.
.. function:: formatdate([timeval[, localtime][, usegmt]])
Returns a date string as per :rfc:`2822`, e.g.::
Fri, 09 Nov 2001 01:08:47 -0000
Optional *timeval* if given is a floating point time value as accepted by
:func:`time.gmtime` and :func:`time.localtime`, otherwise the current time is
used.
Optional *localtime* is a flag that when ``True``, interprets *timeval*, and
returns a date relative to the local timezone instead of UTC, properly taking
daylight savings time into account. The default is ``False`` meaning UTC is
used.
Optional *usegmt* is a flag that when ``True``, outputs a date string with the
timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. This is
needed for some protocols (such as HTTP). This only applies when *localtime* is
``False``.
.. versionadded:: 2.4
.. function:: make_msgid([idstring])
Returns a string suitable for an :rfc:`2822`\ -compliant
:mailheader:`Message-ID` header. Optional *idstring* if given, is a string used
to strengthen the uniqueness of the message id.
.. function:: decode_rfc2231(s)
Decode the string *s* according to :rfc:`2231`.
.. function:: encode_rfc2231(s[, charset[, language]])
Encode the string *s* according to :rfc:`2231`. Optional *charset* and
*language*, if given is the character set name and language name to use. If
neither is given, *s* is returned as-is. If *charset* is given but *language*
is not, the string is encoded using the empty string for *language*.
.. function:: collapse_rfc2231_value(value[, errors[, fallback_charset]])
When a header parameter is encoded in :rfc:`2231` format,
:meth:`Message.get_param` may return a 3-tuple containing the character set,
language, and value. :func:`collapse_rfc2231_value` turns this into a unicode
string. Optional *errors* is passed to the *errors* argument of the built-in
:func:`unicode` function; it defaults to ``replace``. Optional
*fallback_charset* specifies the character set to use if the one in the
:rfc:`2231` header is not known by Python; it defaults to ``us-ascii``.
For convenience, if the *value* passed to :func:`collapse_rfc2231_value` is not
a tuple, it should be a string and it is returned unquoted.
.. function:: decode_params(params)
Decode parameters list according to :rfc:`2231`. *params* is a sequence of
2-tuples containing elements of the form ``(content-type, string-value)``.
.. versionchanged:: 2.4
The :func:`dump_address_pair` function has been removed; use :func:`formataddr`
instead.
.. versionchanged:: 2.4
The :func:`decode` function has been removed; use the
:meth:`Header.decode_header` method instead.
.. versionchanged:: 2.4
The :func:`encode` function has been removed; use the :meth:`Header.encode`
method instead.
.. rubric:: Footnotes
.. [#] Note that the sign of the timezone offset is the opposite of the sign of the
``time.timezone`` variable for the same timezone; the latter variable follows
the POSIX standard while this module follows :rfc:`2822`.

636
Doc-3k/library/errno.rst Normal file
View File

@@ -0,0 +1,636 @@
:mod:`errno` --- Standard errno system symbols
==============================================
.. module:: errno
:synopsis: Standard errno system symbols.
This module makes available standard ``errno`` system symbols. The value of each
symbol is the corresponding integer value. The names and descriptions are
borrowed from :file:`linux/include/errno.h`, which should be pretty all-
inclusive.
.. data:: errorcode
Dictionary providing a mapping from the errno value to the string name in the
underlying system. For instance, ``errno.errorcode[errno.EPERM]`` maps to
``'EPERM'``.
To translate a numeric error code to an error message, use :func:`os.strerror`.
Of the following list, symbols that are not used on the current platform are not
defined by the module. The specific list of defined symbols is available as
``errno.errorcode.keys()``. Symbols available can include:
.. data:: EPERM
Operation not permitted
.. data:: ENOENT
No such file or directory
.. data:: ESRCH
No such process
.. data:: EINTR
Interrupted system call
.. data:: EIO
I/O error
.. data:: ENXIO
No such device or address
.. data:: E2BIG
Arg list too long
.. data:: ENOEXEC
Exec format error
.. data:: EBADF
Bad file number
.. data:: ECHILD
No child processes
.. data:: EAGAIN
Try again
.. data:: ENOMEM
Out of memory
.. data:: EACCES
Permission denied
.. data:: EFAULT
Bad address
.. data:: ENOTBLK
Block device required
.. data:: EBUSY
Device or resource busy
.. data:: EEXIST
File exists
.. data:: EXDEV
Cross-device link
.. data:: ENODEV
No such device
.. data:: ENOTDIR
Not a directory
.. data:: EISDIR
Is a directory
.. data:: EINVAL
Invalid argument
.. data:: ENFILE
File table overflow
.. data:: EMFILE
Too many open files
.. data:: ENOTTY
Not a typewriter
.. data:: ETXTBSY
Text file busy
.. data:: EFBIG
File too large
.. data:: ENOSPC
No space left on device
.. data:: ESPIPE
Illegal seek
.. data:: EROFS
Read-only file system
.. data:: EMLINK
Too many links
.. data:: EPIPE
Broken pipe
.. data:: EDOM
Math argument out of domain of func
.. data:: ERANGE
Math result not representable
.. data:: EDEADLK
Resource deadlock would occur
.. data:: ENAMETOOLONG
File name too long
.. data:: ENOLCK
No record locks available
.. data:: ENOSYS
Function not implemented
.. data:: ENOTEMPTY
Directory not empty
.. data:: ELOOP
Too many symbolic links encountered
.. data:: EWOULDBLOCK
Operation would block
.. data:: ENOMSG
No message of desired type
.. data:: EIDRM
Identifier removed
.. data:: ECHRNG
Channel number out of range
.. data:: EL2NSYNC
Level 2 not synchronized
.. data:: EL3HLT
Level 3 halted
.. data:: EL3RST
Level 3 reset
.. data:: ELNRNG
Link number out of range
.. data:: EUNATCH
Protocol driver not attached
.. data:: ENOCSI
No CSI structure available
.. data:: EL2HLT
Level 2 halted
.. data:: EBADE
Invalid exchange
.. data:: EBADR
Invalid request descriptor
.. data:: EXFULL
Exchange full
.. data:: ENOANO
No anode
.. data:: EBADRQC
Invalid request code
.. data:: EBADSLT
Invalid slot
.. data:: EDEADLOCK
File locking deadlock error
.. data:: EBFONT
Bad font file format
.. data:: ENOSTR
Device not a stream
.. data:: ENODATA
No data available
.. data:: ETIME
Timer expired
.. data:: ENOSR
Out of streams resources
.. data:: ENONET
Machine is not on the network
.. data:: ENOPKG
Package not installed
.. data:: EREMOTE
Object is remote
.. data:: ENOLINK
Link has been severed
.. data:: EADV
Advertise error
.. data:: ESRMNT
Srmount error
.. data:: ECOMM
Communication error on send
.. data:: EPROTO
Protocol error
.. data:: EMULTIHOP
Multihop attempted
.. data:: EDOTDOT
RFS specific error
.. data:: EBADMSG
Not a data message
.. data:: EOVERFLOW
Value too large for defined data type
.. data:: ENOTUNIQ
Name not unique on network
.. data:: EBADFD
File descriptor in bad state
.. data:: EREMCHG
Remote address changed
.. data:: ELIBACC
Can not access a needed shared library
.. data:: ELIBBAD
Accessing a corrupted shared library
.. data:: ELIBSCN
.lib section in a.out corrupted
.. data:: ELIBMAX
Attempting to link in too many shared libraries
.. data:: ELIBEXEC
Cannot exec a shared library directly
.. data:: EILSEQ
Illegal byte sequence
.. data:: ERESTART
Interrupted system call should be restarted
.. data:: ESTRPIPE
Streams pipe error
.. data:: EUSERS
Too many users
.. data:: ENOTSOCK
Socket operation on non-socket
.. data:: EDESTADDRREQ
Destination address required
.. data:: EMSGSIZE
Message too long
.. data:: EPROTOTYPE
Protocol wrong type for socket
.. data:: ENOPROTOOPT
Protocol not available
.. data:: EPROTONOSUPPORT
Protocol not supported
.. data:: ESOCKTNOSUPPORT
Socket type not supported
.. data:: EOPNOTSUPP
Operation not supported on transport endpoint
.. data:: EPFNOSUPPORT
Protocol family not supported
.. data:: EAFNOSUPPORT
Address family not supported by protocol
.. data:: EADDRINUSE
Address already in use
.. data:: EADDRNOTAVAIL
Cannot assign requested address
.. data:: ENETDOWN
Network is down
.. data:: ENETUNREACH
Network is unreachable
.. data:: ENETRESET
Network dropped connection because of reset
.. data:: ECONNABORTED
Software caused connection abort
.. data:: ECONNRESET
Connection reset by peer
.. data:: ENOBUFS
No buffer space available
.. data:: EISCONN
Transport endpoint is already connected
.. data:: ENOTCONN
Transport endpoint is not connected
.. data:: ESHUTDOWN
Cannot send after transport endpoint shutdown
.. data:: ETOOMANYREFS
Too many references: cannot splice
.. data:: ETIMEDOUT
Connection timed out
.. data:: ECONNREFUSED
Connection refused
.. data:: EHOSTDOWN
Host is down
.. data:: EHOSTUNREACH
No route to host
.. data:: EALREADY
Operation already in progress
.. data:: EINPROGRESS
Operation now in progress
.. data:: ESTALE
Stale NFS file handle
.. data:: EUCLEAN
Structure needs cleaning
.. data:: ENOTNAM
Not a XENIX named type file
.. data:: ENAVAIL
No XENIX semaphores available
.. data:: EISNAM
Is a named type file
.. data:: EREMOTEIO
Remote I/O error
.. data:: EDQUOT
Quota exceeded

474
Doc-3k/library/exceptions.rst Normal file
View File

@@ -0,0 +1,474 @@
Built-in Exceptions
===================
.. module:: exceptions
:synopsis: Standard exception classes.
Exceptions should be class objects. The exceptions are defined in the module
:mod:`exceptions`. This module never needs to be imported explicitly: the
exceptions are provided in the built-in namespace as well as the
:mod:`exceptions` module.
.. index::
statement: try
statement: except
For class exceptions, in a :keyword:`try` statement with an :keyword:`except`
clause that mentions a particular class, that clause also handles any exception
classes derived from that class (but not exception classes from which *it* is
derived). Two exception classes that are not related via subclassing are never
equivalent, even if they have the same name.
.. index:: statement: raise
The built-in exceptions listed below can be generated by the interpreter or
built-in functions. Except where mentioned, they have an "associated value"
indicating the detailed cause of the error. This may be a string or a tuple
containing several items of information (e.g., an error code and a string
explaining the code). The associated value is the second argument to the
:keyword:`raise` statement. If the exception class is derived from the standard
root class :exc:`BaseException`, the associated value is present as the
exception instance's :attr:`args` attribute.
User code can raise built-in exceptions. This can be used to test an exception
handler or to report an error condition "just like" the situation in which the
interpreter raises the same exception; but beware that there is nothing to
prevent user code from raising an inappropriate error.
The built-in exception classes can be sub-classed to define new exceptions;
programmers are encouraged to at least derive new exceptions from the
:exc:`Exception` class and not :exc:`BaseException`. More information on
defining exceptions is available in the Python Tutorial (XXX reference:
../tut/tut.html) under the heading "User-defined Exceptions."
The following exceptions are only used as base classes for other exceptions.
.. exception:: BaseException
The base class for all built-in exceptions. It is not meant to be directly
inherited by user-defined classes (for that use :exc:`Exception`). If
:func:`str` or :func:`unicode` is called on an instance of this class, the
representation of the argument(s) to the instance are returned or the emptry
string when there were no arguments. All arguments are stored in :attr:`args`
as a tuple.
.. versionadded:: 2.5
.. exception:: Exception
All built-in, non-system-exiting exceptions are derived from this class. All
user-defined exceptions should also be derived from this class.
.. versionchanged:: 2.5
Changed to inherit from :exc:`BaseException`.
.. exception:: ArithmeticError
The base class for those built-in exceptions that are raised for various
arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`,
:exc:`FloatingPointError`.
.. exception:: LookupError
The base class for the exceptions that are raised when a key or index used on a
mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. This can be
raised directly by :func:`sys.setdefaultencoding`.
.. exception:: EnvironmentError
The base class for exceptions that can occur outside the Python system:
:exc:`IOError`, :exc:`OSError`. When exceptions of this type are created with a
2-tuple, the first item is available on the instance's :attr:`errno` attribute
(it is assumed to be an error number), and the second item is available on the
:attr:`strerror` attribute (it is usually the associated error message). The
tuple itself is also available on the :attr:`args` attribute.
.. versionadded:: 1.5.2
When an :exc:`EnvironmentError` exception is instantiated with a 3-tuple, the
first two items are available as above, while the third item is available on the
:attr:`filename` attribute. However, for backwards compatibility, the
:attr:`args` attribute contains only a 2-tuple of the first two constructor
arguments.
The :attr:`filename` attribute is ``None`` when this exception is created with
other than 3 arguments. The :attr:`errno` and :attr:`strerror` attributes are
also ``None`` when the instance was created with other than 2 or 3 arguments.
In this last case, :attr:`args` contains the verbatim constructor arguments as a
tuple.
The following exceptions are the exceptions that are actually raised.
.. exception:: AssertionError
.. index:: statement: assert
Raised when an :keyword:`assert` statement fails.
.. exception:: AttributeError
Raised when an attribute reference or assignment fails. (When an object does
not support attribute references or attribute assignments at all,
:exc:`TypeError` is raised.)
.. % xref to attribute reference?
.. exception:: EOFError
Raised when attempting to read beyond the end of a file. (N.B.: the :meth:`read`
and :meth:`readline` methods of file objects return an empty string when they
hit EOF.)
.. % XXXJH xrefs here
.. % XXXJH xrefs here
.. exception:: FloatingPointError
Raised when a floating point operation fails. This exception is always defined,
but can only be raised when Python is configured with the
:option:`--with-fpectl` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
defined in the :file:`pyconfig.h` file.
.. exception:: GeneratorExit
Raise when a generator's :meth:`close` method is called.
.. versionadded:: 2.5
.. versionchanged:: 3.0
Changed to inherit from Exception instead of StandardError.
.. exception:: IOError
Raised when an I/O operation (such as a :keyword:`print` statement, the built-in
:func:`open` function or a method of a file object) fails for an I/O-related
reason, e.g., "file not found" or "disk full".
.. % XXXJH xrefs here
This class is derived from :exc:`EnvironmentError`. See the discussion above
for more information on exception instance attributes.
.. exception:: ImportError
Raised when an :keyword:`import` statement fails to find the module definition
or when a ``from ... import`` fails to find a name that is to be imported.
.. % XXXJH xref to import statement?
.. exception:: IndexError
Raised when a sequence subscript is out of range. (Slice indices are silently
truncated to fall in the allowed range; if an index is not a plain integer,
:exc:`TypeError` is raised.)
.. % XXXJH xref to sequences
.. exception:: KeyError
Raised when a mapping (dictionary) key is not found in the set of existing keys.
.. % XXXJH xref to mapping objects?
.. exception:: KeyboardInterrupt
Raised when the user hits the interrupt key (normally :kbd:`Control-C` or
:kbd:`Delete`). During execution, a check for interrupts is made regularly. The
exception inherits from :exc:`BaseException` so as to not be accidentally caught
by code that catches :exc:`Exception` and thus prevent the interpreter from
exiting.
.. % XXX(hylton) xrefs here
.. versionchanged:: 2.5
Changed to inherit from :exc:`BaseException`.
.. exception:: MemoryError
Raised when an operation runs out of memory but the situation may still be
rescued (by deleting some objects). The associated value is a string indicating
what kind of (internal) operation ran out of memory. Note that because of the
underlying memory management architecture (C's :cfunc:`malloc` function), the
interpreter may not always be able to completely recover from this situation; it
nevertheless raises an exception so that a stack traceback can be printed, in
case a run-away program was the cause.
.. exception:: NameError
Raised when a local or global name is not found. This applies only to
unqualified names. The associated value is an error message that includes the
name that could not be found.
.. exception:: NotImplementedError
This exception is derived from :exc:`RuntimeError`. In user defined base
classes, abstract methods should raise this exception when they require derived
classes to override the method.
.. versionadded:: 1.5.2
.. exception:: OSError
This class is derived from :exc:`EnvironmentError` and is used primarily as the
:mod:`os` module's ``os.error`` exception. See :exc:`EnvironmentError` above for
a description of the possible associated values.
.. % xref for os module
.. versionadded:: 1.5.2
.. exception:: OverflowError
Raised when the result of an arithmetic operation is too large to be
represented. This cannot occur for long integers (which would rather raise
:exc:`MemoryError` than give up). Because of the lack of standardization of
floating point exception handling in C, most floating point operations also
aren't checked. For plain integers, all operations that can overflow are
checked except left shift, where typical applications prefer to drop bits than
raise an exception.
.. % XXXJH reference to long's and/or int's?
.. exception:: ReferenceError
This exception is raised when a weak reference proxy, created by the
:func:`weakref.proxy` function, is used to access an attribute of the referent
after it has been garbage collected. For more information on weak references,
see the :mod:`weakref` module.
.. versionadded:: 2.2
Previously known as the :exc:`weakref.ReferenceError` exception.
.. exception:: RuntimeError
Raised when an error is detected that doesn't fall in any of the other
categories. The associated value is a string indicating what precisely went
wrong. (This exception is mostly a relic from a previous version of the
interpreter; it is not used very much any more.)
.. exception:: StopIteration
Raised by builtin :func:`next` and an iterator's :meth:`__next__` method to
signal that there are no further values.
.. versionadded:: 2.2
.. versionchanged:: 3.0
Changed to inherit from Exception instead of StandardError.
.. exception:: SyntaxError
Raised when the parser encounters a syntax error. This may occur in an
:keyword:`import` statement, in a call to the built-in functions :func:`exec`,
:func:`execfile`, :func:`eval` or :func:`input`, or when reading the initial
script or standard input (also interactively).
.. % XXXJH xref to these functions?
Instances of this class have attributes :attr:`filename`, :attr:`lineno`,
:attr:`offset` and :attr:`text` for easier access to the details. :func:`str`
of the exception instance returns only the message.
.. exception:: SystemError
Raised when the interpreter finds an internal error, but the situation does not
look so serious to cause it to abandon all hope. The associated value is a
string indicating what went wrong (in low-level terms).
You should report this to the author or maintainer of your Python interpreter.
Be sure to report the version of the Python interpreter (``sys.version``; it is
also printed at the start of an interactive Python session), the exact error
message (the exception's associated value) and if possible the source of the
program that triggered the error.
.. exception:: SystemExit
This exception is raised by the :func:`sys.exit` function. When it is not
handled, the Python interpreter exits; no stack traceback is printed. If the
associated value is a plain integer, it specifies the system exit status (passed
to C's :cfunc:`exit` function); if it is ``None``, the exit status is zero; if
it has another type (such as a string), the object's value is printed and the
exit status is one.
.. % XXX(hylton) xref to module sys?
Instances have an attribute :attr:`code` which is set to the proposed exit
status or error message (defaulting to ``None``). Also, this exception derives
directly from :exc:`BaseException` and not :exc:`Exception`, since it is not
technically an error.
A call to :func:`sys.exit` is translated into an exception so that clean-up
handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be
executed, and so that a debugger can execute a script without running the risk
of losing control. The :func:`os._exit` function can be used if it is
absolutely positively necessary to exit immediately (for example, in the child
process after a call to :func:`fork`).
The exception inherits from :exc:`BaseException` instead of :exc:`Exception` so
that it is not accidentally caught by code that catches :exc:`Exception`. This
allows the exception to properly propagate up and cause the interpreter to exit.
.. versionchanged:: 2.5
Changed to inherit from :exc:`BaseException`.
.. exception:: TypeError
Raised when an operation or function is applied to an object of inappropriate
type. The associated value is a string giving details about the type mismatch.
.. exception:: UnboundLocalError
Raised when a reference is made to a local variable in a function or method, but
no value has been bound to that variable. This is a subclass of
:exc:`NameError`.
.. versionadded:: 2.0
.. exception:: UnicodeError
Raised when a Unicode-related encoding or decoding error occurs. It is a
subclass of :exc:`ValueError`.
.. versionadded:: 2.0
.. exception:: UnicodeEncodeError
Raised when a Unicode-related error occurs during encoding. It is a subclass of
:exc:`UnicodeError`.
.. versionadded:: 2.3
.. exception:: UnicodeDecodeError
Raised when a Unicode-related error occurs during decoding. It is a subclass of
:exc:`UnicodeError`.
.. versionadded:: 2.3
.. exception:: UnicodeTranslateError
Raised when a Unicode-related error occurs during translating. It is a subclass
of :exc:`UnicodeError`.
.. versionadded:: 2.3
.. exception:: ValueError
Raised when a built-in operation or function receives an argument that has the
right type but an inappropriate value, and the situation is not described by a
more precise exception such as :exc:`IndexError`.
.. exception:: WindowsError
Raised when a Windows-specific error occurs or when the error number does not
correspond to an :cdata:`errno` value. The :attr:`winerror` and
:attr:`strerror` values are created from the return values of the
:cfunc:`GetLastError` and :cfunc:`FormatMessage` functions from the Windows
Platform API. The :attr:`errno` value maps the :attr:`winerror` value to
corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`.
.. versionadded:: 2.0
.. versionchanged:: 2.5
Previous versions put the :cfunc:`GetLastError` codes into :attr:`errno`.
.. exception:: ZeroDivisionError
Raised when the second argument of a division or modulo operation is zero. The
associated value is a string indicating the type of the operands and the
operation.
The following exceptions are used as warning categories; see the :mod:`warnings`
module for more information.
.. exception:: Warning
Base class for warning categories.
.. exception:: UserWarning
Base class for warnings generated by user code.
.. exception:: DeprecationWarning
Base class for warnings about deprecated features.
.. exception:: PendingDeprecationWarning
Base class for warnings about features which will be deprecated in the future.
.. exception:: SyntaxWarning
Base class for warnings about dubious syntax
.. exception:: RuntimeWarning
Base class for warnings about dubious runtime behavior.
.. exception:: FutureWarning
Base class for warnings about constructs that will change semantically in the
future.
.. exception:: ImportWarning
Base class for warnings about probable mistakes in module imports.
.. versionadded:: 2.5
.. exception:: UnicodeWarning
Base class for warnings related to Unicode.
.. versionadded:: 2.5
The class hierarchy for built-in exceptions is:
.. XXX includefile ../../Lib/test/exception_hierarchy.txt

157
Doc-3k/library/fcntl.rst Normal file
View File

@@ -0,0 +1,157 @@
:mod:`fcntl` --- The :func:`fcntl` and :func:`ioctl` system calls
=================================================================
.. module:: fcntl
:platform: Unix
:synopsis: The fcntl() and ioctl() system calls.
.. sectionauthor:: Jaap Vermeulen
.. index::
pair: UNIX@Unix; file control
pair: UNIX@Unix; I/O control
This module performs file control and I/O control on file descriptors. It is an
interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
All functions in this module take a file descriptor *fd* as their first
argument. This can be an integer file descriptor, such as returned by
``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself, which
provides a :meth:`fileno` which returns a genuine file descriptor.
The module defines the following functions:
.. function:: fcntl(fd, op[, arg])
Perform the requested operation on file descriptor *fd* (file objects providing
a :meth:`fileno` method are accepted as well). The operation is defined by *op*
and is operating system dependent. These codes are also found in the
:mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer
value ``0``. When present, it can either be an integer value, or a string.
With the argument missing or an integer value, the return value of this function
is the integer return value of the C :cfunc:`fcntl` call. When the argument is
a string it represents a binary structure, e.g. created by :func:`struct.pack`.
The binary data is copied to a buffer whose address is passed to the C
:cfunc:`fcntl` call. The return value after a successful call is the contents
of the buffer, converted to a string object. The length of the returned string
will be the same as the length of the *arg* argument. This is limited to 1024
bytes. If the information returned in the buffer by the operating system is
larger than 1024 bytes, this is most likely to result in a segmentation
violation or a more subtle data corruption.
If the :cfunc:`fcntl` fails, an :exc:`IOError` is raised.
.. function:: ioctl(fd, op[, arg[, mutate_flag]])
This function is identical to the :func:`fcntl` function, except that the
operations are typically defined in the library module :mod:`termios` and the
argument handling is even more complicated.
The parameter *arg* can be one of an integer, absent (treated identically to the
integer ``0``), an object supporting the read-only buffer interface (most likely
a plain Python string) or an object supporting the read-write buffer interface.
In all but the last case, behaviour is as for the :func:`fcntl` function.
If a mutable buffer is passed, then the behaviour is determined by the value of
the *mutate_flag* parameter.
If it is false, the buffer's mutability is ignored and behaviour is as for a
read-only buffer, except that the 1024 byte limit mentioned above is avoided --
so long as the buffer you pass is as least as long as what the operating system
wants to put there, things should work.
If *mutate_flag* is true, then the buffer is (in effect) passed to the
underlying :func:`ioctl` system call, the latter's return code is passed back to
the calling Python, and the buffer's new contents reflect the action of the
:func:`ioctl`. This is a slight simplification, because if the supplied buffer
is less than 1024 bytes long it is first copied into a static buffer 1024 bytes
long which is then passed to :func:`ioctl` and copied back into the supplied
buffer.
If *mutate_flag* is not supplied, then from Python 2.5 it defaults to true,
which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
version portability is a priority.
An example::
>>> import array, fcntl, struct, termios, os
>>> os.getpgrp()
13341
>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0]
13341
>>> buf = array.array('h', [0])
>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
>>> buf
array('h', [13341])
.. function:: flock(fd, op)
Perform the lock operation *op* on file descriptor *fd* (file objects providing
a :meth:`fileno` method are accepted as well). See the Unix manual
:manpage:`flock(3)` for details. (On some systems, this function is emulated
using :cfunc:`fcntl`.)
.. function:: lockf(fd, operation, [length, [start, [whence]]])
This is essentially a wrapper around the :func:`fcntl` locking calls. *fd* is
the file descriptor of the file to lock or unlock, and *operation* is one of the
following values:
* :const:`LOCK_UN` -- unlock
* :const:`LOCK_SH` -- acquire a shared lock
* :const:`LOCK_EX` -- acquire an exclusive lock
When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be bit-
wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition. If
:const:`LOCK_NB` is used and the lock cannot be acquired, an :exc:`IOError` will
be raised and the exception will have an *errno* attribute set to
:const:`EACCES` or :const:`EAGAIN` (depending on the operating system; for
portability, check for both values). On at least some systems, :const:`LOCK_EX`
can only be used if the file descriptor refers to a file opened for writing.
*length* is the number of bytes to lock, *start* is the byte offset at which the
lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`,
specifically:
* :const:`0` -- relative to the start of the file (:const:`SEEK_SET`)
* :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`)
* :const:`2` -- relative to the end of the file (:const:`SEEK_END`)
The default for *start* is 0, which means to start at the beginning of the file.
The default for *length* is 0 which means to lock to the end of the file. The
default for *whence* is also 0.
Examples (all on a SVR4 compliant system)::
import struct, fcntl, os
f = open(...)
rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
Note that in the first example the return value variable *rv* will hold an
integer value; in the second example it will hold a string value. The structure
lay-out for the *lockdata* variable is system dependent --- therefore using the
:func:`flock` call may be better.
.. seealso::
Module :mod:`os`
If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present in the
:mod:`os` module, the :func:`os.open` function provides a more platform-
independent alternative to the :func:`lockf` and :func:`flock` functions.

152
Doc-3k/library/filecmp.rst Normal file
View File

@@ -0,0 +1,152 @@
:mod:`filecmp` --- File and Directory Comparisons
=================================================
.. module:: filecmp
:synopsis: Compare files efficiently.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`filecmp` module defines functions to compare files and directories,
with various optional time/correctness trade-offs.
The :mod:`filecmp` module defines the following functions:
.. function:: cmp(f1, f2[, shallow])
Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
``False`` otherwise.
Unless *shallow* is given and is false, files with identical :func:`os.stat`
signatures are taken to be equal.
Files that were compared using this function will not be compared again unless
their :func:`os.stat` signature changes.
Note that no external programs are called from this function, giving it
portability and efficiency.
.. function:: cmpfiles(dir1, dir2, common[, shallow])
Returns three lists of file names: *match*, *mismatch*, *errors*. *match*
contains the list of files match in both directories, *mismatch* includes the
names of those that don't, and *errros* lists the names of files which could not
be compared. Files may be listed in *errors* because the user may lack
permission to read them or many other reasons, but always that the comparison
could not be done for some reason.
The *common* parameter is a list of file names found in both directories. The
*shallow* parameter has the same meaning and default value as for
:func:`filecmp.cmp`.
Example::
>>> import filecmp
>>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
True
>>> filecmp.cmp('libundoc.tex', 'lib.tex')
False
.. _dircmp-objects:
The :class:`dircmp` class
-------------------------
:class:`dircmp` instances are built using this constructor:
.. class:: dircmp(a, b[, ignore[, hide]])
Construct a new directory comparison object, to compare the directories *a* and
*b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',
'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
os.pardir]``.
The :class:`dircmp` class provides the following methods:
.. method:: dircmp.report()
Print (to ``sys.stdout``) a comparison between *a* and *b*.
.. method:: dircmp.report_partial_closure()
Print a comparison between *a* and *b* and common immediate subdirectories.
.. method:: dircmp.report_full_closure()
Print a comparison between *a* and *b* and common subdirectories (recursively).
The :class:`dircmp` offers a number of interesting attributes that may be used
to get various bits of information about the directory trees being compared.
Note that via :meth:`__getattr__` hooks, all attributes are computed lazily, so
there is no speed penalty if only those attributes which are lightweight to
compute are used.
.. attribute:: dircmp.left_list
Files and subdirectories in *a*, filtered by *hide* and *ignore*.
.. attribute:: dircmp.right_list
Files and subdirectories in *b*, filtered by *hide* and *ignore*.
.. attribute:: dircmp.common
Files and subdirectories in both *a* and *b*.
.. attribute:: dircmp.left_only
Files and subdirectories only in *a*.
.. attribute:: dircmp.right_only
Files and subdirectories only in *b*.
.. attribute:: dircmp.common_dirs
Subdirectories in both *a* and *b*.
.. attribute:: dircmp.common_files
Files in both *a* and *b*
.. attribute:: dircmp.common_funny
Names in both *a* and *b*, such that the type differs between the directories,
or names for which :func:`os.stat` reports an error.
.. attribute:: dircmp.same_files
Files which are identical in both *a* and *b*.
.. attribute:: dircmp.diff_files
Files which are in both *a* and *b*, whose contents differ.
.. attribute:: dircmp.funny_files
Files which are in both *a* and *b*, but could not be compared.
.. attribute:: dircmp.subdirs
A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.

18
Doc-3k/library/fileformats.rst Normal file
View File

@@ -0,0 +1,18 @@
.. _fileformats:
************
File Formats
************
The modules described in this chapter parse various miscellaneous file formats
that aren't markup languages or are related to e-mail.
.. toctree::
csv.rst
configparser.rst
robotparser.rst
netrc.rst
xdrlib.rst

184
Doc-3k/library/fileinput.rst Normal file
View File

@@ -0,0 +1,184 @@
:mod:`fileinput` --- Iterate over lines from multiple input streams
===================================================================
.. module:: fileinput
.. moduleauthor:: Guido van Rossum <guido@python.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
This module implements a helper class and functions to quickly write a loop over
standard input or a list of files.
The typical use is::
import fileinput
for line in fileinput.input():
process(line)
This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting
to ``sys.stdin`` if the list is empty. If a filename is ``'-'``, it is also
replaced by ``sys.stdin``. To specify an alternative list of filenames, pass it
as the first argument to :func:`input`. A single file name is also allowed.
All files are opened in text mode by default, but you can override this by
specifying the *mode* parameter in the call to :func:`input` or
:class:`FileInput()`. If an I/O error occurs during opening or reading a file,
:exc:`IOError` is raised.
If ``sys.stdin`` is used more than once, the second and further use will return
no lines, except perhaps for interactive use, or if it has been explicitly reset
(e.g. using ``sys.stdin.seek(0)``).
Empty files are opened and immediately closed; the only time their presence in
the list of filenames is noticeable at all is when the last file opened is
empty.
It is possible that the last line of a file does not end in a newline character;
lines are returned including the trailing newline when it is present.
You can control how files are opened by providing an opening hook via the
*openhook* parameter to :func:`input` or :class:`FileInput()`. The hook must be
a function that takes two arguments, *filename* and *mode*, and returns an
accordingly opened file-like object. Two useful hooks are already provided by
this module.
The following function is the primary interface of this module:
.. function:: input([files[, inplace[, backup[, mode[, openhook]]]]])
Create an instance of the :class:`FileInput` class. The instance will be used
as global state for the functions of this module, and is also returned to use
during iteration. The parameters to this function will be passed along to the
constructor of the :class:`FileInput` class.
.. versionchanged:: 2.5
Added the *mode* and *openhook* parameters.
The following functions use the global state created by :func:`input`; if there
is no active state, :exc:`RuntimeError` is raised.
.. function:: filename()
Return the name of the file currently being read. Before the first line has
been read, returns ``None``.
.. function:: fileno()
Return the integer "file descriptor" for the current file. When no file is
opened (before the first line and between files), returns ``-1``.
.. versionadded:: 2.5
.. function:: lineno()
Return the cumulative line number of the line that has just been read. Before
the first line has been read, returns ``0``. After the last line of the last
file has been read, returns the line number of that line.
.. function:: filelineno()
Return the line number in the current file. Before the first line has been
read, returns ``0``. After the last line of the last file has been read,
returns the line number of that line within the file.
.. function:: isfirstline()
Returns true if the line just read is the first line of its file, otherwise
returns false.
.. function:: isstdin()
Returns true if the last line was read from ``sys.stdin``, otherwise returns
false.
.. function:: nextfile()
Close the current file so that the next iteration will read the first line from
the next file (if any); lines not read from the file will not count towards the
cumulative line count. The filename is not changed until after the first line
of the next file has been read. Before the first line has been read, this
function has no effect; it cannot be used to skip the first file. After the
last line of the last file has been read, this function has no effect.
.. function:: close()
Close the sequence.
The class which implements the sequence behavior provided by the module is
available for subclassing as well:
.. class:: FileInput([files[, inplace[, backup[, mode[, openhook]]]]])
Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
:meth:`fileno`, :meth:`lineno`, :meth:`fileline`, :meth:`isfirstline`,
:meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the functions
of the same name in the module. In addition it has a :meth:`readline` method
which returns the next input line, and a :meth:`__getitem__` method which
implements the sequence behavior. The sequence must be accessed in strictly
sequential order; random access and :meth:`readline` cannot be mixed.
With *mode* you can specify which file mode will be passed to :func:`open`. It
must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``.
The *openhook*, when given, must be a function that takes two arguments,
*filename* and *mode*, and returns an accordingly opened file-like object. You
cannot use *inplace* and *openhook* together.
.. versionchanged:: 2.5
Added the *mode* and *openhook* parameters.
**Optional in-place filtering:** if the keyword argument ``inplace=1`` is passed
to :func:`input` or to the :class:`FileInput` constructor, the file is moved to
a backup file and standard output is directed to the input file (if a file of
the same name as the backup file already exists, it will be replaced silently).
This makes it possible to write a filter that rewrites its input file in place.
If the keyword argument ``backup='.<some extension>'`` is also given, it
specifies the extension for the backup file, and the backup file remains around;
by default, the extension is ``'.bak'`` and it is deleted when the output file
is closed. In-place filtering is disabled when standard input is read.
**Caveat:** The current implementation does not work for MS-DOS 8+3 filesystems.
The two following opening hooks are provided by this module:
.. function:: hook_compressed(filename, mode)
Transparently opens files compressed with gzip and bzip2 (recognized by the
extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2`
modules. If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is
opened normally (ie, using :func:`open` without any decompression).
Usage example: ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed)``
.. versionadded:: 2.5
.. function:: hook_encoded(encoding)
Returns a hook which opens each file with :func:`codecs.open`, using the given
*encoding* to read the file.
Usage example: ``fi =
fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))``
.. note::
With this hook, :class:`FileInput` might return Unicode strings depending on the
specified *encoding*.
.. versionadded:: 2.5

38
Doc-3k/library/filesys.rst Normal file
View File

@@ -0,0 +1,38 @@
.. _filesys:
*************************
File and Directory Access
*************************
The modules described in this chapter deal with disk files and directories. For
example, there are modules for reading the properties of files, manipulating
paths in a portable way, and creating temporary files. The full list of modules
in this chapter is:
.. toctree::
os.path.rst
fileinput.rst
stat.rst
statvfs.rst
filecmp.rst
tempfile.rst
glob.rst
fnmatch.rst
linecache.rst
shutil.rst
dircache.rst
Also see section :ref:`bltin-file-objects` for a description of Python's built-
in file objects.
.. % XXX can this be included in the seealso environment? --amk
.. seealso::
Module :mod:`os`
Operating system interfaces, including functions to work with files at a lower
level than the built-in file object.

91
Doc-3k/library/fnmatch.rst Normal file
View File

@@ -0,0 +1,91 @@
:mod:`fnmatch` --- Unix filename pattern matching
=================================================
.. module:: fnmatch
:synopsis: Unix shell style filename pattern matching.
.. index:: single: filenames; wildcard expansion
.. index:: module: re
This module provides support for Unix shell-style wildcards, which are *not* the
same as regular expressions (which are documented in the :mod:`re` module). The
special characters used in shell-style wildcards are:
+------------+------------------------------------+
| Pattern | Meaning |
+============+====================================+
| ``*`` | matches everything |
+------------+------------------------------------+
| ``?`` | matches any single character |
+------------+------------------------------------+
| ``[seq]`` | matches any character in *seq* |
+------------+------------------------------------+
| ``[!seq]`` | matches any character not in *seq* |
+------------+------------------------------------+
.. index:: module: glob
Note that the filename separator (``'/'`` on Unix) is *not* special to this
module. See module :mod:`glob` for pathname expansion (:mod:`glob` uses
:func:`fnmatch` to match pathname segments). Similarly, filenames starting with
a period are not special for this module, and are matched by the ``*`` and ``?``
patterns.
.. function:: fnmatch(filename, pattern)
Test whether the *filename* string matches the *pattern* string, returning true
or false. If the operating system is case-insensitive, then both parameters
will be normalized to all lower- or upper-case before the comparison is
performed. If you require a case-sensitive comparison regardless of whether
that's standard for your operating system, use :func:`fnmatchcase` instead.
This example will print all file names in the current directory with the
extension ``.txt``::
import fnmatch
import os
for file in os.listdir('.'):
if fnmatch.fnmatch(file, '*.txt'):
print file
.. function:: fnmatchcase(filename, pattern)
Test whether *filename* matches *pattern*, returning true or false; the
comparison is case-sensitive.
.. function:: filter(names, pattern)
Return the subset of the list of *names* that match *pattern*. It is the same as
``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
.. versionadded:: 2.2
.. function:: translate(pattern)
Return the shell-style *pattern* converted to a regular expression.
Example::
>>> import fnmatch, re
>>>
>>> regex = fnmatch.translate('*.txt')
>>> regex
'.*\\.txt$'
>>> reobj = re.compile(regex)
>>> print reobj.match('foobar.txt')
<_sre.SRE_Match object at 0x...>
.. seealso::
Module :mod:`glob`
Unix shell-style path expansion.

350
Doc-3k/library/formatter.rst Normal file
View File

@@ -0,0 +1,350 @@
:mod:`formatter` --- Generic output formatting
==============================================
.. module:: formatter
:synopsis: Generic output formatter and device interface.
.. index:: single: HTMLParser (class in htmllib)
This module supports two interface definitions, each with multiple
implementations. The *formatter* interface is used by the :class:`HTMLParser`
class of the :mod:`htmllib` module, and the *writer* interface is required by
the formatter interface.
Formatter objects transform an abstract flow of formatting events into specific
output events on writer objects. Formatters manage several stack structures to
allow various properties of a writer object to be changed and restored; writers
need not be able to handle relative changes nor any sort of "change back"
operation. Specific writer properties which may be controlled via formatter
objects are horizontal alignment, font, and left margin indentations. A
mechanism is provided which supports providing arbitrary, non-exclusive style
settings to a writer as well. Additional interfaces facilitate formatting
events which are not reversible, such as paragraph separation.
Writer objects encapsulate device interfaces. Abstract devices, such as file
formats, are supported as well as physical devices. The provided
implementations all work with abstract devices. The interface makes available
mechanisms for setting the properties which formatter objects manage and
inserting data into the output.
.. _formatter-interface:
The Formatter Interface
-----------------------
Interfaces to create formatters are dependent on the specific formatter class
being instantiated. The interfaces described below are the required interfaces
which all formatters must support once initialized.
One data element is defined at the module level:
.. data:: AS_IS
Value which can be used in the font specification passed to the ``push_font()``
method described below, or as the new value to any other ``push_property()``
method. Pushing the ``AS_IS`` value allows the corresponding ``pop_property()``
method to be called without having to track whether the property was changed.
The following attributes are defined for formatter instance objects:
.. attribute:: formatter.writer
The writer instance with which the formatter interacts.
.. method:: formatter.end_paragraph(blanklines)
Close any open paragraphs and insert at least *blanklines* before the next
paragraph.
.. method:: formatter.add_line_break()
Add a hard line break if one does not already exist. This does not break the
logical paragraph.
.. method:: formatter.add_hor_rule(*args, **kw)
Insert a horizontal rule in the output. A hard break is inserted if there is
data in the current paragraph, but the logical paragraph is not broken. The
arguments and keywords are passed on to the writer's :meth:`send_line_break`
method.
.. method:: formatter.add_flowing_data(data)
Provide data which should be formatted with collapsed whitespace. Whitespace
from preceding and successive calls to :meth:`add_flowing_data` is considered as
well when the whitespace collapse is performed. The data which is passed to
this method is expected to be word-wrapped by the output device. Note that any
word-wrapping still must be performed by the writer object due to the need to
rely on device and font information.
.. method:: formatter.add_literal_data(data)
Provide data which should be passed to the writer unchanged. Whitespace,
including newline and tab characters, are considered legal in the value of
*data*.
.. method:: formatter.add_label_data(format, counter)
Insert a label which should be placed to the left of the current left margin.
This should be used for constructing bulleted or numbered lists. If the
*format* value is a string, it is interpreted as a format specification for
*counter*, which should be an integer. The result of this formatting becomes the
value of the label; if *format* is not a string it is used as the label value
directly. The label value is passed as the only argument to the writer's
:meth:`send_label_data` method. Interpretation of non-string label values is
dependent on the associated writer.
Format specifications are strings which, in combination with a counter value,
are used to compute label values. Each character in the format string is copied
to the label value, with some characters recognized to indicate a transform on
the counter value. Specifically, the character ``'1'`` represents the counter
value formatter as an Arabic number, the characters ``'A'`` and ``'a'``
represent alphabetic representations of the counter value in upper and lower
case, respectively, and ``'I'`` and ``'i'`` represent the counter value in Roman
numerals, in upper and lower case. Note that the alphabetic and roman
transforms require that the counter value be greater than zero.
.. method:: formatter.flush_softspace()
Send any pending whitespace buffered from a previous call to
:meth:`add_flowing_data` to the associated writer object. This should be called
before any direct manipulation of the writer object.
.. method:: formatter.push_alignment(align)
Push a new alignment setting onto the alignment stack. This may be
:const:`AS_IS` if no change is desired. If the alignment value is changed from
the previous setting, the writer's :meth:`new_alignment` method is called with
the *align* value.
.. method:: formatter.pop_alignment()
Restore the previous alignment.
.. method:: formatter.push_font((size, italic, bold, teletype))
Change some or all font properties of the writer object. Properties which are
not set to :const:`AS_IS` are set to the values passed in while others are
maintained at their current settings. The writer's :meth:`new_font` method is
called with the fully resolved font specification.
.. method:: formatter.pop_font()
Restore the previous font.
.. method:: formatter.push_margin(margin)
Increase the number of left margin indentations by one, associating the logical
tag *margin* with the new indentation. The initial margin level is ``0``.
Changed values of the logical tag must be true values; false values other than
:const:`AS_IS` are not sufficient to change the margin.
.. method:: formatter.pop_margin()
Restore the previous margin.
.. method:: formatter.push_style(*styles)
Push any number of arbitrary style specifications. All styles are pushed onto
the styles stack in order. A tuple representing the entire stack, including
:const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method.
.. method:: formatter.pop_style([n\ ``= 1``])
Pop the last *n* style specifications passed to :meth:`push_style`. A tuple
representing the revised stack, including :const:`AS_IS` values, is passed to
the writer's :meth:`new_styles` method.
.. method:: formatter.set_spacing(spacing)
Set the spacing style for the writer.
.. method:: formatter.assert_line_data([flag\ ``= 1``])
Inform the formatter that data has been added to the current paragraph out-of-
band. This should be used when the writer has been manipulated directly. The
optional *flag* argument can be set to false if the writer manipulations
produced a hard line break at the end of the output.
.. _formatter-impls:
Formatter Implementations
-------------------------
Two implementations of formatter objects are provided by this module. Most
applications may use one of these classes without modification or subclassing.
.. class:: NullFormatter([writer])
A formatter which does nothing. If *writer* is omitted, a :class:`NullWriter`
instance is created. No methods of the writer are called by
:class:`NullFormatter` instances. Implementations should inherit from this
class if implementing a writer interface but don't need to inherit any
implementation.
.. class:: AbstractFormatter(writer)
The standard formatter. This implementation has demonstrated wide applicability
to many writers, and may be used directly in most circumstances. It has been
used to implement a full-featured World Wide Web browser.
.. _writer-interface:
The Writer Interface
--------------------
Interfaces to create writers are dependent on the specific writer class being
instantiated. The interfaces described below are the required interfaces which
all writers must support once initialized. Note that while most applications can
use the :class:`AbstractFormatter` class as a formatter, the writer must
typically be provided by the application.
.. method:: writer.flush()
Flush any buffered output or device control events.
.. method:: writer.new_alignment(align)
Set the alignment style. The *align* value can be any object, but by convention
is a string or ``None``, where ``None`` indicates that the writer's "preferred"
alignment should be used. Conventional *align* values are ``'left'``,
``'center'``, ``'right'``, and ``'justify'``.
.. method:: writer.new_font(font)
Set the font style. The value of *font* will be ``None``, indicating that the
device's default font should be used, or a tuple of the form ``(``*size*,
*italic*, *bold*, *teletype*``)``. Size will be a string indicating the size of
font that should be used; specific strings and their interpretation must be
defined by the application. The *italic*, *bold*, and *teletype* values are
Boolean values specifying which of those font attributes should be used.
.. method:: writer.new_margin(margin, level)
Set the margin level to the integer *level* and the logical tag to *margin*.
Interpretation of the logical tag is at the writer's discretion; the only
restriction on the value of the logical tag is that it not be a false value for
non-zero values of *level*.
.. method:: writer.new_spacing(spacing)
Set the spacing style to *spacing*.
.. method:: writer.new_styles(styles)
Set additional styles. The *styles* value is a tuple of arbitrary values; the
value :const:`AS_IS` should be ignored. The *styles* tuple may be interpreted
either as a set or as a stack depending on the requirements of the application
and writer implementation.
.. method:: writer.send_line_break()
Break the current line.
.. method:: writer.send_paragraph(blankline)
Produce a paragraph separation of at least *blankline* blank lines, or the
equivalent. The *blankline* value will be an integer. Note that the
implementation will receive a call to :meth:`send_line_break` before this call
if a line break is needed; this method should not include ending the last line
of the paragraph. It is only responsible for vertical spacing between
paragraphs.
.. method:: writer.send_hor_rule(*args, **kw)
Display a horizontal rule on the output device. The arguments to this method
are entirely application- and writer-specific, and should be interpreted with
care. The method implementation may assume that a line break has already been
issued via :meth:`send_line_break`.
.. method:: writer.send_flowing_data(data)
Output character data which may be word-wrapped and re-flowed as needed. Within
any sequence of calls to this method, the writer may assume that spans of
multiple whitespace characters have been collapsed to single space characters.
.. method:: writer.send_literal_data(data)
Output character data which has already been formatted for display. Generally,
this should be interpreted to mean that line breaks indicated by newline
characters should be preserved and no new line breaks should be introduced. The
data may contain embedded newline and tab characters, unlike data provided to
the :meth:`send_formatted_data` interface.
.. method:: writer.send_label_data(data)
Set *data* to the left of the current left margin, if possible. The value of
*data* is not restricted; treatment of non-string values is entirely
application- and writer-dependent. This method will only be called at the
beginning of a line.
.. _writer-impls:
Writer Implementations
----------------------
Three implementations of the writer object interface are provided as examples by
this module. Most applications will need to derive new writer classes from the
:class:`NullWriter` class.
.. class:: NullWriter()
A writer which only provides the interface definition; no actions are taken on
any methods. This should be the base class for all writers which do not need to
inherit any implementation methods.
.. class:: AbstractWriter()
A writer which can be used in debugging formatters, but not much else. Each
method simply announces itself by printing its name and arguments on standard
output.
.. class:: DumbWriter([file[, maxcol\ ``= 72``]])
Simple writer class which writes output on the file object passed in as *file*
or, if *file* is omitted, on standard output. The output is simply word-wrapped
to the number of columns specified by *maxcol*. This class is suitable for
reflowing a sequence of paragraphs.

120
Doc-3k/library/fpectl.rst Normal file
View File

@@ -0,0 +1,120 @@
:mod:`fpectl` --- Floating point exception control
==================================================
.. module:: fpectl
:platform: Unix
:synopsis: Provide control for floating point exception handling.
.. moduleauthor:: Lee Busby <busby1@llnl.gov>
.. sectionauthor:: Lee Busby <busby1@llnl.gov>
.. note::
The :mod:`fpectl` module is not built by default, and its usage is discouraged
and may be dangerous except in the hands of experts. See also the section
:ref:`fpectl-limitations` on limitations for more details.
.. index:: single: IEEE-754
Most computers carry out floating point operations in conformance with the so-
called IEEE-754 standard. On any real computer, some floating point operations
produce results that cannot be expressed as a normal floating point value. For
example, try ::
>>> import math
>>> math.exp(1000)
inf
>>> math.exp(1000) / math.exp(1000)
nan
(The example above will work on many platforms. DEC Alpha may be one exception.)
"Inf" is a special, non-numeric value in IEEE-754 that stands for "infinity",
and "nan" means "not a number." Note that, other than the non-numeric results,
nothing special happened when you asked Python to carry out those calculations.
That is in fact the default behaviour prescribed in the IEEE-754 standard, and
if it works for you, stop reading now.
In some circumstances, it would be better to raise an exception and stop
processing at the point where the faulty operation was attempted. The
:mod:`fpectl` module is for use in that situation. It provides control over
floating point units from several hardware manufacturers, allowing the user to
turn on the generation of :const:`SIGFPE` whenever any of the IEEE-754
exceptions Division by Zero, Overflow, or Invalid Operation occurs. In tandem
with a pair of wrapper macros that are inserted into the C code comprising your
python system, :const:`SIGFPE` is trapped and converted into the Python
:exc:`FloatingPointError` exception.
The :mod:`fpectl` module defines the following functions and may raise the given
exception:
.. function:: turnon_sigfpe()
Turn on the generation of :const:`SIGFPE`, and set up an appropriate signal
handler.
.. function:: turnoff_sigfpe()
Reset default handling of floating point exceptions.
.. exception:: FloatingPointError
After :func:`turnon_sigfpe` has been executed, a floating point operation that
raises one of the IEEE-754 exceptions Division by Zero, Overflow, or Invalid
operation will in turn raise this standard Python exception.
.. _fpectl-example:
Example
-------
The following example demonstrates how to start up and test operation of the
:mod:`fpectl` module. ::
>>> import fpectl
>>> import fpetest
>>> fpectl.turnon_sigfpe()
>>> fpetest.test()
overflow PASS
FloatingPointError: Overflow
div by 0 PASS
FloatingPointError: Division by zero
[ more output from test elided ]
>>> import math
>>> math.exp(1000)
Traceback (most recent call last):
File "<stdin>", line 1, in ?
FloatingPointError: in math_1
.. _fpectl-limitations:
Limitations and other considerations
------------------------------------
Setting up a given processor to trap IEEE-754 floating point errors currently
requires custom code on a per-architecture basis. You may have to modify
:mod:`fpectl` to control your particular hardware.
Conversion of an IEEE-754 exception to a Python exception requires that the
wrapper macros ``PyFPE_START_PROTECT`` and ``PyFPE_END_PROTECT`` be inserted
into your code in an appropriate fashion. Python itself has been modified to
support the :mod:`fpectl` module, but many other codes of interest to numerical
analysts have not.
The :mod:`fpectl` module is not thread-safe.
.. seealso::
Some files in the source distribution may be interesting in learning more about
how this module operates. The include file :file:`Include/pyfpe.h` discusses the
implementation of this module at some length. :file:`Modules/fpetestmodule.c`
gives several examples of use. Many additional examples can be found in
:file:`Objects/floatobject.c`.

56
Doc-3k/library/fpformat.rst Normal file
View File

@@ -0,0 +1,56 @@
:mod:`fpformat` --- Floating point conversions
==============================================
.. module:: fpformat
:synopsis: General floating point formatting functions.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`fpformat` module defines functions for dealing with floating point
numbers representations in 100% pure Python.
.. note::
This module is unneeded: everything here could be done via the ``%`` string
interpolation operator.
The :mod:`fpformat` module defines the following functions and an exception:
.. function:: fix(x, digs)
Format *x* as ``[-]ddd.ddd`` with *digs* digits after the point and at least one
digit before. If ``digs <= 0``, the decimal point is suppressed.
*x* can be either a number or a string that looks like one. *digs* is an
integer.
Return value is a string.
.. function:: sci(x, digs)
Format *x* as ``[-]d.dddE[+-]ddd`` with *digs* digits after the point and
exactly one digit before. If ``digs <= 0``, one digit is kept and the point is
suppressed.
*x* can be either a real number, or a string that looks like one. *digs* is an
integer.
Return value is a string.
.. exception:: NotANumber
Exception raised when a string passed to :func:`fix` or :func:`sci` as the *x*
parameter does not look like a number. This is a subclass of :exc:`ValueError`
when the standard exceptions are strings. The exception value is the improperly
formatted string that caused the exception to be raised.
Example::
>>> import fpformat
>>> fpformat.fix(1.23, 1)
'1.2'

18
Doc-3k/library/frameworks.rst Normal file
View File

@@ -0,0 +1,18 @@
.. _frameworks:
******************
Program Frameworks
******************
The modules described in this chapter are frameworks that will largely dictate
the structure of your program. Currently the modules described here are all
oriented toward writing command-line interfaces.
The full list of modules described in this chapter is:
.. toctree::
cmd.rst
shlex.rst

320
Doc-3k/library/ftplib.rst Normal file
View File

@@ -0,0 +1,320 @@
:mod:`ftplib` --- FTP protocol client
=====================================
.. module:: ftplib
:synopsis: FTP protocol client (requires sockets).
.. index::
pair: FTP; protocol
single: FTP; ftplib (standard module)
This module defines the class :class:`FTP` and a few related items. The
:class:`FTP` class implements the client side of the FTP protocol. You can use
this to write Python programs that perform a variety of automated FTP jobs, such
as mirroring other ftp servers. It is also used by the module :mod:`urllib` to
handle URLs that use FTP. For more information on FTP (File Transfer Protocol),
see Internet :rfc:`959`.
Here's a sample session using the :mod:`ftplib` module::
>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
>>> ftp.login() # user anonymous, passwd anonymous@
>>> ftp.retrlines('LIST') # list directory contents
total 24418
drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 .
dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
-rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX
.
.
.
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
'226 Transfer complete.'
>>> ftp.quit()
The module defines the following items:
.. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]])
Return a new instance of the :class:`FTP` class. When *host* is given, the
method call ``connect(host)`` is made. When *user* is given, additionally the
method call ``login(user, passwd, acct)`` is made (where *passwd* and *acct*
default to the empty string when not given). The optional *timeout* parameter
specifies a timeout in seconds for the connection attempt (if is not specified,
or passed as None, the global default timeout setting will be used).
.. versionchanged:: 2.6
*timeout* was added.
.. data:: all_errors
The set of all exceptions (as a tuple) that methods of :class:`FTP` instances
may raise as a result of problems with the FTP connection (as opposed to
programming errors made by the caller). This set includes the four exceptions
listed below as well as :exc:`socket.error` and :exc:`IOError`.
.. exception:: error_reply
Exception raised when an unexpected reply is received from the server.
.. exception:: error_temp
Exception raised when an error code in the range 400--499 is received.
.. exception:: error_perm
Exception raised when an error code in the range 500--599 is received.
.. exception:: error_proto
Exception raised when a reply is received from the server that does not begin
with a digit in the range 1--5.
.. seealso::
Module :mod:`netrc`
Parser for the :file:`.netrc` file format. The file :file:`.netrc` is typically
used by FTP clients to load user authentication information before prompting the
user.
.. index:: single: ftpmirror.py
The file :file:`Tools/scripts/ftpmirror.py` in the Python source distribution is
a script that can mirror FTP sites, or portions thereof, using the :mod:`ftplib`
module. It can be used as an extended example that applies this module.
.. _ftp-objects:
FTP Objects
-----------
Several methods are available in two flavors: one for handling text files and
another for binary files. These are named for the command which is used
followed by ``lines`` for the text version or ``binary`` for the binary version.
:class:`FTP` instances have the following methods:
.. method:: FTP.set_debuglevel(level)
Set the instance's debugging level. This controls the amount of debugging
output printed. The default, ``0``, produces no debugging output. A value of
``1`` produces a moderate amount of debugging output, generally a single line
per request. A value of ``2`` or higher produces the maximum amount of
debugging output, logging each line sent and received on the control connection.
.. method:: FTP.connect(host[, port[, timeout]])
Connect to the given host and port. The default port number is ``21``, as
specified by the FTP protocol specification. It is rarely needed to specify a
different port number. This function should be called only once for each
instance; it should not be called at all if a host was given when the instance
was created. All other methods can only be used after a connection has been
made.
The optional *timeout* parameter specifies a timeout in seconds for the
connection attempt. If is not specified, or passed as None, the object timeout
is used (the timeout that you passed when instantiating the class); if the
object timeout is also None, the global default timeout setting will be used.
.. versionchanged:: 2.6
*timeout* was added.
.. method:: FTP.getwelcome()
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help information
that may be relevant to the user.)
.. method:: FTP.login([user[, passwd[, acct]]])
Log in as the given *user*. The *passwd* and *acct* parameters are optional and
default to the empty string. If no *user* is specified, it defaults to
``'anonymous'``. If *user* is ``'anonymous'``, the default *passwd* is
``'anonymous@'``. This function should be called only once for each instance,
after a connection has been established; it should not be called at all if a
host and user were given when the instance was created. Most FTP commands are
only allowed after the client has logged in.
.. method:: FTP.abort()
Abort a file transfer that is in progress. Using this does not always work, but
it's worth a try.
.. method:: FTP.sendcmd(command)
Send a simple command string to the server and return the response string.
.. method:: FTP.voidcmd(command)
Send a simple command string to the server and handle the response. Return
nothing if a response code in the range 200--299 is received. Raise an exception
otherwise.
.. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
Retrieve a file in binary transfer mode. *command* should be an appropriate
``RETR`` command: ``'RETR filename'``. The *callback* function is called for
each block of data received, with a single string argument giving the data
block. The optional *maxblocksize* argument specifies the maximum chunk size to
read on the low-level socket object created to do the actual transfer (which
will also be the largest size of the data blocks passed to *callback*). A
reasonable default is chosen. *rest* means the same thing as in the
:meth:`transfercmd` method.
.. method:: FTP.retrlines(command[, callback])
Retrieve a file or directory listing in ASCII transfer mode. *command* should be
an appropriate ``RETR`` command (see :meth:`retrbinary`) or a ``LIST`` command
(usually just the string ``'LIST'``). The *callback* function is called for
each line, with the trailing CRLF stripped. The default *callback* prints the
line to ``sys.stdout``.
.. method:: FTP.set_pasv(boolean)
Enable "passive" mode if *boolean* is true, other disable passive mode. (In
Python 2.0 and before, passive mode was off by default; in Python 2.1 and later,
it is on by default.)
.. method:: FTP.storbinary(command, file[, blocksize])
Store a file in binary transfer mode. *command* should be an appropriate
``STOR`` command: ``"STOR filename"``. *file* is an open file object which is
read until EOF using its :meth:`read` method in blocks of size *blocksize* to
provide the data to be stored. The *blocksize* argument defaults to 8192.
.. versionchanged:: 2.1
default for *blocksize* added.
.. method:: FTP.storlines(command, file)
Store a file in ASCII transfer mode. *command* should be an appropriate
``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the
open file object *file* using its :meth:`readline` method to provide the data to
be stored.
.. method:: FTP.transfercmd(cmd[, rest])
Initiate a transfer over the data connection. If the transfer is active, send a
``EPRT`` or ``PORT`` command and the transfer command specified by *cmd*, and
accept the connection. If the server is passive, send a ``EPSV`` or ``PASV``
command, connect to it, and start the transfer command. Either way, return the
socket for the connection.
If optional *rest* is given, a ``REST`` command is sent to the server, passing
*rest* as an argument. *rest* is usually a byte offset into the requested file,
telling the server to restart sending the file's bytes at the requested offset,
skipping over the initial bytes. Note however that RFC 959 requires only that
*rest* be a string containing characters in the printable range from ASCII code
33 to ASCII code 126. The :meth:`transfercmd` method, therefore, converts
*rest* to a string, but no check is performed on the string's contents. If the
server does not recognize the ``REST`` command, an :exc:`error_reply` exception
will be raised. If this happens, simply call :meth:`transfercmd` without a
*rest* argument.
.. method:: FTP.ntransfercmd(cmd[, rest])
Like :meth:`transfercmd`, but returns a tuple of the data connection and the
expected size of the data. If the expected size could not be computed, ``None``
will be returned as the expected size. *cmd* and *rest* means the same thing as
in :meth:`transfercmd`.
.. method:: FTP.nlst(argument[, ...])
Return a list of files as returned by the ``NLST`` command. The optional
*argument* is a directory to list (default is the current server directory).
Multiple arguments can be used to pass non-standard options to the ``NLST``
command.
.. method:: FTP.dir(argument[, ...])
Produce a directory listing as returned by the ``LIST`` command, printing it to
standard output. The optional *argument* is a directory to list (default is the
current server directory). Multiple arguments can be used to pass non-standard
options to the ``LIST`` command. If the last argument is a function, it is used
as a *callback* function as for :meth:`retrlines`; the default prints to
``sys.stdout``. This method returns ``None``.
.. method:: FTP.rename(fromname, toname)
Rename file *fromname* on the server to *toname*.
.. method:: FTP.delete(filename)
Remove the file named *filename* from the server. If successful, returns the
text of the response, otherwise raises :exc:`error_perm` on permission errors or
:exc:`error_reply` on other errors.
.. method:: FTP.cwd(pathname)
Set the current directory on the server.
.. method:: FTP.mkd(pathname)
Create a new directory on the server.
.. method:: FTP.pwd()
Return the pathname of the current directory on the server.
.. method:: FTP.rmd(dirname)
Remove the directory named *dirname* on the server.
.. method:: FTP.size(filename)
Request the size of the file named *filename* on the server. On success, the
size of the file is returned as an integer, otherwise ``None`` is returned.
Note that the ``SIZE`` command is not standardized, but is supported by many
common server implementations.
.. method:: FTP.quit()
Send a ``QUIT`` command to the server and close the connection. This is the
"polite" way to close a connection, but it may raise an exception of the server
reponds with an error to the ``QUIT`` command. This implies a call to the
:meth:`close` method which renders the :class:`FTP` instance useless for
subsequent calls (see below).
.. method:: FTP.close()
Close the connection unilaterally. This should not be applied to an already
closed connection such as after a successful call to :meth:`quit`. After this
call the :class:`FTP` instance should not be used any more (after a call to
:meth:`close` or :meth:`quit` you cannot reopen the connection by issuing
another :meth:`login` method).

1203
Doc-3k/library/functions.rst Normal file
View File

File diff suppressed because it is too large Load Diff

149
Doc-3k/library/functools.rst Normal file
View File

@@ -0,0 +1,149 @@
:mod:`functools` --- Higher order functions and operations on callable objects.
===============================================================================
.. module:: functools
.. moduleauthor:: Peter Harris <scav@blueyonder.co.uk>
.. moduleauthor:: Raymond Hettinger <python@rcn.com>
.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
.. sectionauthor:: Peter Harris <scav@blueyonder.co.uk>
.. % standard library, in Python
.. versionadded:: 2.5
The :mod:`functools` module is for higher-order functions: functions that act on
or return other functions. In general, any callable object can be treated as a
function for the purposes of this module.
The :mod:`functools` module defines the following function:
.. function:: partial(func[,*args][, **keywords])
Return a new :class:`partial` object which when called will behave like *func*
called with the positional arguments *args* and keyword arguments *keywords*. If
more arguments are supplied to the call, they are appended to *args*. If
additional keyword arguments are supplied, they extend and override *keywords*.
Roughly equivalent to::
def partial(func, *args, **keywords):
def newfunc(*fargs, **fkeywords):
newkeywords = keywords.copy()
newkeywords.update(fkeywords)
return func(*(args + fargs), **newkeywords)
newfunc.func = func
newfunc.args = args
newfunc.keywords = keywords
return newfunc
The :func:`partial` is used for partial function application which "freezes"
some portion of a function's arguments and/or keywords resulting in a new object
with a simplified signature. For example, :func:`partial` can be used to create
a callable that behaves like the :func:`int` function where the *base* argument
defaults to two::
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
18
.. function:: reduce(function, sequence[, initializer])
Apply *function* of two arguments cumulatively to the items of *sequence*, from
left to right, so as to reduce the sequence to a single value. For example,
``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates ``((((1+2)+3)+4)+5)``.
The left argument, *x*, is the accumulated value and the right argument, *y*, is
the update value from the *sequence*. If the optional *initializer* is present,
it is placed before the items of the sequence in the calculation, and serves as
a default when the sequence is empty. If *initializer* is not given and
*sequence* contains only one item, the first item is returned.
.. function:: update_wrapper(wrapper, wrapped[, assigned][, updated])
Update a *wrapper* function to look like the *wrapped* function. The optional
arguments are tuples to specify which attributes of the original function are
assigned directly to the matching attributes on the wrapper function and which
attributes of the wrapper function are updated with the corresponding attributes
from the original function. The default values for these arguments are the
module level constants *WRAPPER_ASSIGNMENTS* (which assigns to the wrapper
function's *__name__*, *__module__* and *__doc__*, the documentation string) and
*WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the
instance dictionary).
The main intended use for this function is in decorator functions which wrap the
decorated function and return the wrapper. If the wrapper function is not
updated, the metadata of the returned function will reflect the wrapper
definition rather than the original function definition, which is typically less
than helpful.
.. function:: wraps(wrapped[, assigned][, updated])
This is a convenience function for invoking ``partial(update_wrapper,
wrapped=wrapped, assigned=assigned, updated=updated)`` as a function decorator
when defining a wrapper function. For example::
>>> def my_decorator(f):
... @wraps(f)
... def wrapper(*args, **kwds):
... print 'Calling decorated function'
... return f(*args, **kwds)
... return wrapper
...
>>> @my_decorator
... def example():
... """Docstring"""
... print 'Called example function'
...
>>> example()
Calling decorated function
Called example function
>>> example.__name__
'example'
>>> example.__doc__
'Docstring'
Without the use of this decorator factory, the name of the example function
would have been ``'wrapper'``, and the docstring of the original :func:`example`
would have been lost.
.. _partial-objects:
:class:`partial` Objects
------------------------
:class:`partial` objects are callable objects created by :func:`partial`. They
have three read-only attributes:
.. attribute:: callable.func
A callable object or function. Calls to the :class:`partial` object will be
forwarded to :attr:`func` with new arguments and keywords.
.. attribute:: tuple.args
The leftmost positional arguments that will be prepended to the positional
arguments provided to a :class:`partial` object call.
.. attribute:: dict.keywords
The keyword arguments that will be supplied when the :class:`partial` object is
called.
:class:`partial` objects are like :class:`function` objects in that they are
callable, weak referencable, and can have attributes. There are some important
differences. For instance, the :attr:`__name__` and :attr:`__doc__` attributes
are not created automatically. Also, :class:`partial` objects defined in
classes behave like static methods and do not transform into bound methods
during instance attribute look-up.

211
Doc-3k/library/gc.rst Normal file
View File

@@ -0,0 +1,211 @@
:mod:`gc` --- Garbage Collector interface
=========================================
.. module:: gc
:synopsis: Interface to the cycle-detecting garbage collector.
.. moduleauthor:: Neil Schemenauer <nas@arctrix.com>
.. sectionauthor:: Neil Schemenauer <nas@arctrix.com>
This module provides an interface to the optional garbage collector. It
provides the ability to disable the collector, tune the collection frequency,
and set debugging options. It also provides access to unreachable objects that
the collector found but cannot free. Since the collector supplements the
reference counting already used in Python, you can disable the collector if you
are sure your program does not create reference cycles. Automatic collection
can be disabled by calling ``gc.disable()``. To debug a leaking program call
``gc.set_debug(gc.DEBUG_LEAK)``. Notice that this includes
``gc.DEBUG_SAVEALL``, causing garbage-collected objects to be saved in
gc.garbage for inspection.
The :mod:`gc` module provides the following functions:
.. function:: enable()
Enable automatic garbage collection.
.. function:: disable()
Disable automatic garbage collection.
.. function:: isenabled()
Returns true if automatic collection is enabled.
.. function:: collect([generation])
With no arguments, run a full collection. The optional argument *generation*
may be an integer specifying which generation to collect (from 0 to 2). A
:exc:`ValueError` is raised if the generation number is invalid. The number of
unreachable objects found is returned.
.. versionchanged:: 2.5
The optional *generation* argument was added.
.. function:: set_debug(flags)
Set the garbage collection debugging flags. Debugging information will be
written to ``sys.stderr``. See below for a list of debugging flags which can be
combined using bit operations to control debugging.
.. function:: get_debug()
Return the debugging flags currently set.
.. function:: get_objects()
Returns a list of all objects tracked by the collector, excluding the list
returned.
.. versionadded:: 2.2
.. function:: set_threshold(threshold0[, threshold1[, threshold2]])
Set the garbage collection thresholds (the collection frequency). Setting
*threshold0* to zero disables collection.
The GC classifies objects into three generations depending on how many
collection sweeps they have survived. New objects are placed in the youngest
generation (generation ``0``). If an object survives a collection it is moved
into the next older generation. Since generation ``2`` is the oldest
generation, objects in that generation remain there after a collection. In
order to decide when to run, the collector keeps track of the number object
allocations and deallocations since the last collection. When the number of
allocations minus the number of deallocations exceeds *threshold0*, collection
starts. Initially only generation ``0`` is examined. If generation ``0`` has
been examined more than *threshold1* times since generation ``1`` has been
examined, then generation ``1`` is examined as well. Similarly, *threshold2*
controls the number of collections of generation ``1`` before collecting
generation ``2``.
.. function:: get_count()
Return the current collection counts as a tuple of ``(count0, count1,
count2)``.
.. versionadded:: 2.5
.. function:: get_threshold()
Return the current collection thresholds as a tuple of ``(threshold0,
threshold1, threshold2)``.
.. function:: get_referrers(*objs)
Return the list of objects that directly refer to any of objs. This function
will only locate those containers which support garbage collection; extension
types which do refer to other objects but do not support garbage collection will
not be found.
Note that objects which have already been dereferenced, but which live in cycles
and have not yet been collected by the garbage collector can be listed among the
resulting referrers. To get only currently live objects, call :func:`collect`
before calling :func:`get_referrers`.
Care must be taken when using objects returned by :func:`get_referrers` because
some of them could still be under construction and hence in a temporarily
invalid state. Avoid using :func:`get_referrers` for any purpose other than
debugging.
.. versionadded:: 2.2
.. function:: get_referents(*objs)
Return a list of objects directly referred to by any of the arguments. The
referents returned are those objects visited by the arguments' C-level
:attr:`tp_traverse` methods (if any), and may not be all objects actually
directly reachable. :attr:`tp_traverse` methods are supported only by objects
that support garbage collection, and are only required to visit objects that may
be involved in a cycle. So, for example, if an integer is directly reachable
from an argument, that integer object may or may not appear in the result list.
.. versionadded:: 2.3
The following variable is provided for read-only access (you can mutate its
value but should not rebind it):
.. data:: garbage
A list of objects which the collector found to be unreachable but could not be
freed (uncollectable objects). By default, this list contains only objects with
:meth:`__del__` methods. [#]_ Objects that have :meth:`__del__` methods and are
part of a reference cycle cause the entire reference cycle to be uncollectable,
including objects not necessarily in the cycle but reachable only from it.
Python doesn't collect such cycles automatically because, in general, it isn't
possible for Python to guess a safe order in which to run the :meth:`__del__`
methods. If you know a safe order, you can force the issue by examining the
*garbage* list, and explicitly breaking cycles due to your objects within the
list. Note that these objects are kept alive even so by virtue of being in the
*garbage* list, so they should be removed from *garbage* too. For example,
after breaking cycles, do ``del gc.garbage[:]`` to empty the list. It's
generally better to avoid the issue by not creating cycles containing objects
with :meth:`__del__` methods, and *garbage* can be examined in that case to
verify that no such cycles are being created.
If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added to
this list rather than freed.
The following constants are provided for use with :func:`set_debug`:
.. data:: DEBUG_STATS
Print statistics during collection. This information can be useful when tuning
the collection frequency.
.. data:: DEBUG_COLLECTABLE
Print information on collectable objects found.
.. data:: DEBUG_UNCOLLECTABLE
Print information of uncollectable objects found (objects which are not
reachable but cannot be freed by the collector). These objects will be added to
the ``garbage`` list.
.. data:: DEBUG_INSTANCES
When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print
information about instance objects found.
.. data:: DEBUG_OBJECTS
When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print
information about objects other than instance objects found.
.. data:: DEBUG_SAVEALL
When set, all unreachable objects found will be appended to *garbage* rather
than being freed. This can be useful for debugging a leaking program.
.. data:: DEBUG_LEAK
The debugging flags necessary for the collector to print information about a
leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE |
DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL``).
.. rubric:: Footnotes
.. [#] Prior to Python 2.2, the list contained all instance objects in unreachable
cycles, not only those with :meth:`__del__` methods.

104
Doc-3k/library/gdbm.rst Normal file
View File

@@ -0,0 +1,104 @@
:mod:`gdbm` --- GNU's reinterpretation of dbm
=============================================
.. module:: gdbm
:platform: Unix
:synopsis: GNU's reinterpretation of dbm.
.. index:: module: dbm
This module is quite similar to the :mod:`dbm` module, but uses ``gdbm`` instead
to provide some additional functionality. Please note that the file formats
created by ``gdbm`` and ``dbm`` are incompatible.
The :mod:`gdbm` module provides an interface to the GNU DBM library. ``gdbm``
objects behave like mappings (dictionaries), except that keys and values are
always strings. Printing a ``gdbm`` object doesn't print the keys and values,
and the :meth:`items` and :meth:`values` methods are not supported.
The module defines the following constant and functions:
.. exception:: error
Raised on ``gdbm``\ -specific errors, such as I/O errors. :exc:`KeyError` is
raised for general mapping errors like specifying an incorrect key.
.. function:: open(filename, [flag, [mode]])
Open a ``gdbm`` database and return a ``gdbm`` object. The *filename* argument
is the name of the database file.
The optional *flag* argument can be ``'r'`` (to open an existing database for
reading only --- default), ``'w'`` (to open an existing database for reading and
writing), ``'c'`` (which creates the database if it doesn't exist), or ``'n'``
(which always creates a new empty database).
The following additional characters may be appended to the flag to control how
the database is opened:
* ``'f'`` --- Open the database in fast mode. Writes to the database will not
be synchronized.
* ``'s'`` --- Synchronized mode. This will cause changes to the database will be
immediately written to the file.
* ``'u'`` --- Do not lock database.
Not all flags are valid for all versions of ``gdbm``. The module constant
``open_flags`` is a string of supported flag characters. The exception
:exc:`error` is raised if an invalid flag is specified.
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``.
In addition to the dictionary-like methods, ``gdbm`` objects have the following
methods:
.. function:: firstkey()
It's possible to loop over every key in the database using this method and the
:meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal hash
values, and won't be sorted by the key values. This method returns the starting
key.
.. function:: nextkey(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.firstkey()
while k != None:
print k
k = db.nextkey(k)
.. function:: reorganize()
If you have carried out a lot of deletions and would like to shrink the space
used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm``
will not shorten the length of a database file except by using this
reorganization; otherwise, deleted file space will be kept and reused as new
(key, value) pairs are added.
.. function:: sync()
When the database has been opened in fast mode, this method forces any
unwritten data to be written to the disk.
.. seealso::
Module :mod:`anydbm`
Generic interface to ``dbm``\ -style databases.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.

147
Doc-3k/library/getopt.rst Normal file
View File

@@ -0,0 +1,147 @@
:mod:`getopt` --- Parser for command line options
=================================================
.. module:: getopt
:synopsis: Portable parser for command line options; support both short and long option
names.
This module helps scripts to parse the command line arguments in ``sys.argv``.
It supports the same conventions as the Unix :cfunc:`getopt` function (including
the special meanings of arguments of the form '``-``' and '``-``\ ``-``'). Long
options similar to those supported by GNU software may be used as well via an
optional third argument. This module provides a single function and an
exception:
.. % That's to fool latex2html into leaving the two hyphens alone!
.. function:: getopt(args, options[, long_options])
Parses command line options and parameter list. *args* is the argument list to
be parsed, without the leading reference to the running program. Typically, this
means ``sys.argv[1:]``. *options* is the string of option letters that the
script wants to recognize, with options that require an argument followed by a
colon (``':'``; i.e., the same format that Unix :cfunc:`getopt` uses).
.. note::
Unlike GNU :cfunc:`getopt`, after a non-option argument, all further arguments
are considered also non-options. This is similar to the way non-GNU Unix systems
work.
*long_options*, if specified, must be a list of strings with the names of the
long options which should be supported. The leading ``'-``\ ``-'`` characters
should not be included in the option name. Long options which require an
argument should be followed by an equal sign (``'='``). To accept only long
options, *options* should be an empty string. Long options on the command line
can be recognized so long as they provide a prefix of the option name that
matches exactly one of the accepted options. For example, if *long_options* is
``['foo', 'frob']``, the option :option:`--fo` will match as :option:`--foo`,
but :option:`--f` will not match uniquely, so :exc:`GetoptError` will be raised.
The return value consists of two elements: the first is a list of ``(option,
value)`` pairs; the second is the list of program arguments left after the
option list was stripped (this is a trailing slice of *args*). Each option-and-
value pair returned has the option as its first element, prefixed with a hyphen
for short options (e.g., ``'-x'``) or two hyphens for long options (e.g.,
``'-``\ ``-long-option'``), and the option argument as its second element, or an
empty string if the option has no argument. The options occur in the list in
the same order in which they were found, thus allowing multiple occurrences.
Long and short options may be mixed.
.. function:: gnu_getopt(args, options[, long_options])
This function works like :func:`getopt`, except that GNU style scanning mode is
used by default. This means that option and non-option arguments may be
intermixed. The :func:`getopt` function stops processing options as soon as a
non-option argument is encountered.
If the first character of the option string is '+', or if the environment
variable POSIXLY_CORRECT is set, then option processing stops as soon as a non-
option argument is encountered.
.. versionadded:: 2.3
.. exception:: GetoptError
This is raised when an unrecognized option is found in the argument list or when
an option requiring an argument is given none. The argument to the exception is
a string indicating the cause of the error. For long options, an argument given
to an option which does not require one will also cause this exception to be
raised. The attributes :attr:`msg` and :attr:`opt` give the error message and
related option; if there is no specific option to which the exception relates,
:attr:`opt` is an empty string.
.. versionchanged:: 1.6
Introduced :exc:`GetoptError` as a synonym for :exc:`error`.
.. exception:: error
Alias for :exc:`GetoptError`; for backward compatibility.
An example using only Unix style options::
>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
Using long option names is equally easy::
>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
... 'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
'')]
>>> args
['a1', 'a2']
In a script, typical usage is something like this::
import getopt, sys
def main():
try:
opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
except getopt.GetoptError as err:
# print help information and exit:
print str(err) # will print something like "option -a not recognized"
usage()
sys.exit(2)
output = None
verbose = False
for o, a in opts:
if o == "-v":
verbose = True
elif o in ("-h", "--help"):
usage()
sys.exit()
elif o in ("-o", "--output"):
output = a
else:
assert False, "unhandled option"
# ...
if __name__ == "__main__":
main()
.. seealso::
Module :mod:`optparse`
More object-oriented command line option parsing.

38
Doc-3k/library/getpass.rst Normal file
View File

@@ -0,0 +1,38 @@
:mod:`getpass` --- Portable password input
==========================================
.. module:: getpass
:synopsis: Portable reading of passwords and retrieval of the userid.
.. moduleauthor:: Piers Lauder <piers@cs.su.oz.au>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. % Windows (& Mac?) support by Guido van Rossum.
The :mod:`getpass` module provides two functions:
.. function:: getpass([prompt[, stream]])
Prompt the user for a password without echoing. The user is prompted using the
string *prompt*, which defaults to ``'Password: '``. On Unix, the prompt is
written to the file-like object *stream*, which defaults to ``sys.stdout`` (this
argument is ignored on Windows).
Availability: Macintosh, Unix, Windows.
.. versionchanged:: 2.5
The *stream* parameter was added.
.. function:: getuser()
Return the "login name" of the user. Availability: Unix, Windows.
This function checks the environment variables :envvar:`LOGNAME`,
:envvar:`USER`, :envvar:`LNAME` and :envvar:`USERNAME`, in order, and returns
the value of the first one which is set to a non-empty string. If none are set,
the login name from the password database is returned on systems which support
the :mod:`pwd` module, otherwise, an exception is raised.

765
Doc-3k/library/gettext.rst Normal file
View File

@@ -0,0 +1,765 @@
:mod:`gettext` --- Multilingual internationalization services
=============================================================
.. module:: gettext
:synopsis: Multilingual internationalization services.
.. moduleauthor:: Barry A. Warsaw <barry@zope.com>
.. sectionauthor:: Barry A. Warsaw <barry@zope.com>
The :mod:`gettext` module provides internationalization (I18N) and localization
(L10N) services for your Python modules and applications. It supports both the
GNU ``gettext`` message catalog API and a higher level, class-based API that may
be more appropriate for Python files. The interface described below allows you
to write your module and application messages in one natural language, and
provide a catalog of translated messages for running under different natural
languages.
Some hints on localizing your Python modules and applications are also given.
GNU :program:`gettext` API
--------------------------
The :mod:`gettext` module defines the following API, which is very similar to
the GNU :program:`gettext` API. If you use this API you will affect the
translation of your entire application globally. Often this is what you want if
your application is monolingual, with the choice of language dependent on the
locale of your user. If you are localizing a Python module, or if your
application needs to switch languages on the fly, you probably want to use the
class-based API instead.
.. function:: bindtextdomain(domain[, localedir])
Bind the *domain* to the locale directory *localedir*. More concretely,
:mod:`gettext` will look for binary :file:`.mo` files for the given domain using
the path (on Unix): :file:`localedir/language/LC_MESSAGES/domain.mo`, where
*languages* is searched for in the environment variables :envvar:`LANGUAGE`,
:envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and :envvar:`LANG` respectively.
If *localedir* is omitted or ``None``, then the current binding for *domain* is
returned. [#]_
.. function:: bind_textdomain_codeset(domain[, codeset])
Bind the *domain* to *codeset*, changing the encoding of strings returned by the
:func:`gettext` family of functions. If *codeset* is omitted, then the current
binding is returned.
.. versionadded:: 2.4
.. function:: textdomain([domain])
Change or query the current global domain. If *domain* is ``None``, then the
current global domain is returned, otherwise the global domain is set to
*domain*, which is returned.
.. function:: gettext(message)
Return the localized translation of *message*, based on the current global
domain, language, and locale directory. This function is usually aliased as
:func:`_` in the local namespace (see examples below).
.. function:: lgettext(message)
Equivalent to :func:`gettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
.. versionadded:: 2.4
.. function:: dgettext(domain, message)
Like :func:`gettext`, but look the message up in the specified *domain*.
.. function:: ldgettext(domain, message)
Equivalent to :func:`dgettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
.. versionadded:: 2.4
.. function:: ngettext(singular, plural, n)
Like :func:`gettext`, but consider plural forms. If a translation is found,
apply the plural formula to *n*, and return the resulting message (some
languages have more than two plural forms). If no translation is found, return
*singular* if *n* is 1; return *plural* otherwise.
The Plural formula is taken from the catalog header. It is a C or Python
expression that has a free variable *n*; the expression evaluates to the index
of the plural in the catalog. See the GNU gettext documentation for the precise
syntax to be used in :file:`.po` files and the formulas for a variety of
languages.
.. versionadded:: 2.3
.. function:: lngettext(singular, plural, n)
Equivalent to :func:`ngettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
.. versionadded:: 2.4
.. function:: dngettext(domain, singular, plural, n)
Like :func:`ngettext`, but look the message up in the specified *domain*.
.. versionadded:: 2.3
.. function:: ldngettext(domain, singular, plural, n)
Equivalent to :func:`dngettext`, but the translation is returned in the
preferred system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
.. versionadded:: 2.4
Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but
this was deemed not useful and so it is currently unimplemented.
Here's an example of typical usage for this API::
import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print _('This is a translatable string.')
Class-based API
---------------
The class-based API of the :mod:`gettext` module gives you more flexibility and
greater convenience than the GNU :program:`gettext` API. It is the recommended
way of localizing your Python applications and modules. :mod:`gettext` defines
a "translations" class which implements the parsing of GNU :file:`.mo` format
files, and has methods for returning either standard 8-bit strings or Unicode
strings. Instances of this "translations" class can also install themselves in
the built-in namespace as the function :func:`_`.
.. function:: find(domain[, localedir[, languages[, all]]])
This function implements the standard :file:`.mo` file search algorithm. It
takes a *domain*, identical to what :func:`textdomain` takes. Optional
*localedir* is as in :func:`bindtextdomain` Optional *languages* is a list of
strings, where each string is a language code.
If *localedir* is not given, then the default system locale directory is used.
[#]_ If *languages* is not given, then the following environment variables are
searched: :envvar:`LANGUAGE`, :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and
:envvar:`LANG`. The first one returning a non-empty value is used for the
*languages* variable. The environment variables should contain a colon separated
list of languages, which will be split on the colon to produce the expected list
of language code strings.
:func:`find` then expands and normalizes the languages, and then iterates
through them, searching for an existing file built of these components:
:file:`localedir/language/LC_MESSAGES/domain.mo`
The first such file name that exists is returned by :func:`find`. If no such
file is found, then ``None`` is returned. If *all* is given, it returns a list
of all file names, in the order in which they appear in the languages list or
the environment variables.
.. function:: translation(domain[, localedir[, languages[, class_[, fallback[, codeset]]]]])
Return a :class:`Translations` instance based on the *domain*, *localedir*, and
*languages*, which are first passed to :func:`find` to get a list of the
associated :file:`.mo` file paths. Instances with identical :file:`.mo` file
names are cached. The actual class instantiated is either *class_* if provided,
otherwise :class:`GNUTranslations`. The class's constructor must take a single
file object argument. If provided, *codeset* will change the charset used to
encode translated strings.
If multiple files are found, later files are used as fallbacks for earlier ones.
To allow setting the fallback, :func:`copy.copy` is used to clone each
translation object from the cache; the actual instance data is still shared with
the cache.
If no :file:`.mo` file is found, this function raises :exc:`IOError` if
*fallback* is false (which is the default), and returns a
:class:`NullTranslations` instance if *fallback* is true.
.. versionchanged:: 2.4
Added the *codeset* parameter.
.. function:: install(domain[, localedir[, unicode [, codeset[, names]]]])
This installs the function :func:`_` in Python's builtin namespace, based on
*domain*, *localedir*, and *codeset* which are passed to the function
:func:`translation`. The *unicode* flag is passed to the resulting translation
object's :meth:`install` method.
For the *names* parameter, please see the description of the translation
object's :meth:`install` method.
As seen below, you usually mark the strings in your application that are
candidates for translation, by wrapping them in a call to the :func:`_`
function, like this::
print _('This string will be translated.')
For convenience, you want the :func:`_` function to be installed in Python's
builtin namespace, so it is easily accessible in all modules of your
application.
.. versionchanged:: 2.4
Added the *codeset* parameter.
.. versionchanged:: 2.5
Added the *names* parameter.
The :class:`NullTranslations` class
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Translation classes are what actually implement the translation of original
source file message strings to translated message strings. The base class used
by all translation classes is :class:`NullTranslations`; this provides the basic
interface you can use to write your own specialized translation classes. Here
are the methods of :class:`NullTranslations`:
.. method:: NullTranslations.__init__([fp])
Takes an optional file object *fp*, which is ignored by the base class.
Initializes "protected" instance variables *_info* and *_charset* which are set
by derived classes, as well as *_fallback*, which is set through
:meth:`add_fallback`. It then calls ``self._parse(fp)`` if *fp* is not
``None``.
.. method:: NullTranslations._parse(fp)
No-op'd in the base class, this method takes file object *fp*, and reads the
data from the file, initializing its message catalog. If you have an
unsupported message catalog file format, you should override this method to
parse your format.
.. method:: NullTranslations.add_fallback(fallback)
Add *fallback* as the fallback object for the current translation object. A
translation object should consult the fallback if it cannot provide a
translation for a given message.
.. method:: NullTranslations.gettext(message)
If a fallback has been set, forward :meth:`gettext` to the fallback. Otherwise,
return the translated message. Overridden in derived classes.
.. method:: NullTranslations.lgettext(message)
If a fallback has been set, forward :meth:`lgettext` to the fallback. Otherwise,
return the translated message. Overridden in derived classes.
.. versionadded:: 2.4
.. method:: NullTranslations.ugettext(message)
If a fallback has been set, forward :meth:`ugettext` to the fallback. Otherwise,
return the translated message as a Unicode string. Overridden in derived
classes.
.. method:: NullTranslations.ngettext(singular, plural, n)
If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
return the translated message. Overridden in derived classes.
.. versionadded:: 2.3
.. method:: NullTranslations.lngettext(singular, plural, n)
If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
return the translated message. Overridden in derived classes.
.. versionadded:: 2.4
.. method:: NullTranslations.ungettext(singular, plural, n)
If a fallback has been set, forward :meth:`ungettext` to the fallback.
Otherwise, return the translated message as a Unicode string. Overridden in
derived classes.
.. versionadded:: 2.3
.. method:: NullTranslations.info()
Return the "protected" :attr:`_info` variable.
.. method:: NullTranslations.charset()
Return the "protected" :attr:`_charset` variable.
.. method:: NullTranslations.output_charset()
Return the "protected" :attr:`_output_charset` variable, which defines the
encoding used to return translated messages.
.. versionadded:: 2.4
.. method:: NullTranslations.set_output_charset(charset)
Change the "protected" :attr:`_output_charset` variable, which defines the
encoding used to return translated messages.
.. versionadded:: 2.4
.. method:: NullTranslations.install([unicode [, names]])
If the *unicode* flag is false, this method installs :meth:`self.gettext` into
the built-in namespace, binding it to ``_``. If *unicode* is true, it binds
:meth:`self.ugettext` instead. By default, *unicode* is false.
If the *names* parameter is given, it must be a sequence containing the names of
functions you want to install in the builtin namespace in addition to :func:`_`.
Supported names are ``'gettext'`` (bound to :meth:`self.gettext` or
:meth:`self.ugettext` according to the *unicode* flag), ``'ngettext'`` (bound to
:meth:`self.ngettext` or :meth:`self.ungettext` according to the *unicode*
flag), ``'lgettext'`` and ``'lngettext'``.
Note that this is only one way, albeit the most convenient way, to make the
:func:`_` function available to your application. Because it affects the entire
application globally, and specifically the built-in namespace, localized modules
should never install :func:`_`. Instead, they should use this code to make
:func:`_` available to their module::
import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext
This puts :func:`_` only in the module's global namespace and so only affects
calls within this module.
.. versionchanged:: 2.5
Added the *names* parameter.
The :class:`GNUTranslations` class
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :mod:`gettext` module provides one additional class derived from
:class:`NullTranslations`: :class:`GNUTranslations`. This class overrides
:meth:`_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files
in both big-endian and little-endian format. It also coerces both message ids
and message strings to Unicode.
:class:`GNUTranslations` parses optional meta-data out of the translation
catalog. It is convention with GNU :program:`gettext` to include meta-data as
the translation for the empty string. This meta-data is in :rfc:`822`\ -style
``key: value`` pairs, and should contain the ``Project-Id-Version`` key. If the
key ``Content-Type`` is found, then the ``charset`` property is used to
initialize the "protected" :attr:`_charset` instance variable, defaulting to
``None`` if not found. If the charset encoding is specified, then all message
ids and message strings read from the catalog are converted to Unicode using
this encoding. The :meth:`ugettext` method always returns a Unicode, while the
:meth:`gettext` returns an encoded 8-bit string. For the message id arguments
of both methods, either Unicode strings or 8-bit strings containing only US-
ASCII characters are acceptable. Note that the Unicode version of the methods
(i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended interface to
use for internationalized Python programs.
The entire set of key/value pairs are placed into a dictionary and set as the
"protected" :attr:`_info` instance variable.
If the :file:`.mo` file's magic number is invalid, or if other problems occur
while reading the file, instantiating a :class:`GNUTranslations` class can raise
:exc:`IOError`.
The following methods are overridden from the base class implementation:
.. method:: GNUTranslations.gettext(message)
Look up the *message* id in the catalog and return the corresponding message
string, as an 8-bit string encoded with the catalog's charset encoding, if
known. If there is no entry in the catalog for the *message* id, and a fallback
has been set, the look up is forwarded to the fallback's :meth:`gettext` method.
Otherwise, the *message* id is returned.
.. method:: GNUTranslations.lgettext(message)
Equivalent to :meth:`gettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:meth:`set_output_charset`.
.. versionadded:: 2.4
.. method:: GNUTranslations.ugettext(message)
Look up the *message* id in the catalog and return the corresponding message
string, as a Unicode string. If there is no entry in the catalog for the
*message* id, and a fallback has been set, the look up is forwarded to the
fallback's :meth:`ugettext` method. Otherwise, the *message* id is returned.
.. method:: GNUTranslations.ngettext(singular, plural, n)
Do a plural-forms lookup of a message id. *singular* is used as the message id
for purposes of lookup in the catalog, while *n* is used to determine which
plural form to use. The returned message string is an 8-bit string encoded with
the catalog's charset encoding, if known.
If the message id is not found in the catalog, and a fallback is specified, the
request is forwarded to the fallback's :meth:`ngettext` method. Otherwise, when
*n* is 1 *singular* is returned, and *plural* is returned in all other cases.
.. versionadded:: 2.3
.. method:: GNUTranslations.lngettext(singular, plural, n)
Equivalent to :meth:`gettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:meth:`set_output_charset`.
.. versionadded:: 2.4
.. method:: GNUTranslations.ungettext(singular, plural, n)
Do a plural-forms lookup of a message id. *singular* is used as the message id
for purposes of lookup in the catalog, while *n* is used to determine which
plural form to use. The returned message string is a Unicode string.
If the message id is not found in the catalog, and a fallback is specified, the
request is forwarded to the fallback's :meth:`ungettext` method. Otherwise,
when *n* is 1 *singular* is returned, and *plural* is returned in all other
cases.
Here is an example::
n = len(os.listdir('.'))
cat = GNUTranslations(somefile)
message = cat.ungettext(
'There is %(num)d file in this directory',
'There are %(num)d files in this directory',
n) % {'num': n}
.. versionadded:: 2.3
Solaris message catalog support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Solaris operating system defines its own binary :file:`.mo` file format, but
since no documentation can be found on this format, it is not supported at this
time.
The Catalog constructor
^^^^^^^^^^^^^^^^^^^^^^^
.. index:: single: GNOME
GNOME uses a version of the :mod:`gettext` module by James Henstridge, but this
version has a slightly different API. Its documented usage was::
import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print _('hello world')
For compatibility with this older module, the function :func:`Catalog` is an
alias for the :func:`translation` function described above.
One difference between this module and Henstridge's: his catalog objects
supported access through a mapping API, but this appears to be unused and so is
not currently supported.
Internationalizing your programs and modules
--------------------------------------------
Internationalization (I18N) refers to the operation by which a program is made
aware of multiple languages. Localization (L10N) refers to the adaptation of
your program, once internationalized, to the local language and cultural habits.
In order to provide multilingual messages for your Python programs, you need to
take the following steps:
#. prepare your program or module by specially marking translatable strings
#. run a suite of tools over your marked files to generate raw messages catalogs
#. create language specific translations of the message catalogs
#. use the :mod:`gettext` module so that message strings are properly translated
In order to prepare your code for I18N, you need to look at all the strings in
your files. Any string that needs to be translated should be marked by wrapping
it in ``_('...')`` --- that is, a call to the function :func:`_`. For example::
filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()
In this example, the string ``'writing a log message'`` is marked as a candidate
for translation, while the strings ``'mylog.txt'`` and ``'w'`` are not.
The Python distribution comes with two tools which help you generate the message
catalogs once you've prepared your source code. These may or may not be
available from a binary distribution, but they can be found in a source
distribution, in the :file:`Tools/i18n` directory.
The :program:`pygettext` [#]_ program scans all your Python source code looking
for the strings you previously marked as translatable. It is similar to the GNU
:program:`gettext` program except that it understands all the intricacies of
Python source code, but knows nothing about C or C++ source code. You don't
need GNU ``gettext`` unless you're also going to be translating C code (such as
C extension modules).
:program:`pygettext` generates textual Uniforum-style human readable message
catalog :file:`.pot` files, essentially structured human readable files which
contain every marked string in the source code, along with a placeholder for the
translation strings. :program:`pygettext` is a command line script that supports
a similar command line interface as :program:`xgettext`; for details on its use,
run::
pygettext.py --help
Copies of these :file:`.pot` files are then handed over to the individual human
translators who write language-specific versions for every supported natural
language. They send you back the filled in language-specific versions as a
:file:`.po` file. Using the :program:`msgfmt.py` [#]_ program (in the
:file:`Tools/i18n` directory), you take the :file:`.po` files from your
translators and generate the machine-readable :file:`.mo` binary catalog files.
The :file:`.mo` files are what the :mod:`gettext` module uses for the actual
translation processing during run-time.
How you use the :mod:`gettext` module in your code depends on whether you are
internationalizing a single module or your entire application. The next two
sections will discuss each case.
Localizing your module
^^^^^^^^^^^^^^^^^^^^^^
If you are localizing your module, you must take care not to make global
changes, e.g. to the built-in namespace. You should not use the GNU ``gettext``
API but instead the class-based API.
Let's say your module is called "spam" and the module's various natural language
translation :file:`.mo` files reside in :file:`/usr/share/locale` in GNU
:program:`gettext` format. Here's what you would put at the top of your
module::
import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.lgettext
If your translators were providing you with Unicode strings in their :file:`.po`
files, you'd instead do::
import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.ugettext
Localizing your application
^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are localizing your application, you can install the :func:`_` function
globally into the built-in namespace, usually in the main driver file of your
application. This will let all your application-specific files just use
``_('...')`` without having to explicitly install it in each file.
In the simple case then, you need only add the following bit of code to the main
driver file of your application::
import gettext
gettext.install('myapplication')
If you need to set the locale directory or the *unicode* flag, you can pass
these into the :func:`install` function::
import gettext
gettext.install('myapplication', '/usr/share/locale', unicode=1)
Changing languages on the fly
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If your program needs to support many languages at the same time, you may want
to create multiple translation instances and then switch between them
explicitly, like so::
import gettext
lang1 = gettext.translation('myapplication', languages=['en'])
lang2 = gettext.translation('myapplication', languages=['fr'])
lang3 = gettext.translation('myapplication', languages=['de'])
# start by using language1
lang1.install()
# ... time goes by, user selects language 2
lang2.install()
# ... more time goes by, user selects language 3
lang3.install()
Deferred translations
^^^^^^^^^^^^^^^^^^^^^
In most coding situations, strings are translated where they are coded.
Occasionally however, you need to mark strings for translation, but defer actual
translation until later. A classic example is::
animals = ['mollusk',
'albatross',
'rat',
'penguin',
'python',
]
# ...
for a in animals:
print a
Here, you want to mark the strings in the ``animals`` list as being
translatable, but you don't actually want to translate them until they are
printed.
Here is one way you can handle this situation::
def _(message): return message
animals = [_('mollusk'),
_('albatross'),
_('rat'),
_('penguin'),
_('python'),
]
del _
# ...
for a in animals:
print _(a)
This works because the dummy definition of :func:`_` simply returns the string
unchanged. And this dummy definition will temporarily override any definition
of :func:`_` in the built-in namespace (until the :keyword:`del` command). Take
care, though if you have a previous definition of :func:`_` in the local
namespace.
Note that the second use of :func:`_` will not identify "a" as being
translatable to the :program:`pygettext` program, since it is not a string.
Another way to handle this is with the following example::
def N_(message): return message
animals = [N_('mollusk'),
N_('albatross'),
N_('rat'),
N_('penguin'),
N_('python'),
]
# ...
for a in animals:
print _(a)
In this case, you are marking translatable strings with the function :func:`N_`,
[#]_ which won't conflict with any definition of :func:`_`. However, you will
need to teach your message extraction program to look for translatable strings
marked with :func:`N_`. :program:`pygettext` and :program:`xpot` both support
this through the use of command line switches.
:func:`gettext` vs. :func:`lgettext`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In Python 2.4 the :func:`lgettext` family of functions were introduced. The
intention of these functions is to provide an alternative which is more
compliant with the current implementation of GNU gettext. Unlike
:func:`gettext`, which returns strings encoded with the same codeset used in the
translation file, :func:`lgettext` will return strings encoded with the
preferred system encoding, as returned by :func:`locale.getpreferredencoding`.
Also notice that Python 2.4 introduces new functions to explicitly choose the
codeset used in translated strings. If a codeset is explicitly set, even
:func:`lgettext` will return translated strings in the requested codeset, as
would be expected in the GNU gettext implementation.
Acknowledgements
----------------
The following people contributed code, feedback, design suggestions, previous
implementations, and valuable experience to the creation of this module:
* Peter Funk
* James Henstridge
* Juan David Ibáñez Palomar
* Marc-André Lemburg
* Martin von Löwis
* François Pinard
* Barry Warsaw
* Gustavo Niemeyer
.. rubric:: Footnotes
.. [#] The default locale directory is system dependent; for example, on RedHat Linux
it is :file:`/usr/share/locale`, but on Solaris it is :file:`/usr/lib/locale`.
The :mod:`gettext` module does not try to support these system dependent
defaults; instead its default is :file:`sys.prefix/share/locale`. For this
reason, it is always best to call :func:`bindtextdomain` with an explicit
absolute path at the start of your application.
.. [#] See the footnote for :func:`bindtextdomain` above.
.. [#] François Pinard has written a program called :program:`xpot` which does a
similar job. It is available as part of his :program:`po-utils` package at http
://po-utils.progiciels-bpi.ca/.
.. [#] :program:`msgfmt.py` is binary compatible with GNU :program:`msgfmt` except that
it provides a simpler, all-Python implementation. With this and
:program:`pygettext.py`, you generally won't need to install the GNU
:program:`gettext` package to internationalize your Python applications.
.. [#] The choice of :func:`N_` here is totally arbitrary; it could have just as easily
been :func:`MarkThisStringForTranslation`.

54
Doc-3k/library/glob.rst Normal file
View File

@@ -0,0 +1,54 @@
:mod:`glob` --- Unix style pathname pattern expansion
=====================================================
.. module:: glob
:synopsis: Unix shell style pathname pattern expansion.
.. index:: single: filenames; pathname expansion
The :mod:`glob` module finds all the pathnames matching a specified pattern
according to the rules used by the Unix shell. No tilde expansion is done, but
``*``, ``?``, and character ranges expressed with ``[]`` will be correctly
matched. This is done by using the :func:`os.listdir` and
:func:`fnmatch.fnmatch` functions in concert, and not by actually invoking a
subshell. (For tilde and shell variable expansion, use
:func:`os.path.expanduser` and :func:`os.path.expandvars`.)
.. function:: glob(pathname)
Return a possibly-empty list of path names that match *pathname*, which must be
a string containing a path specification. *pathname* can be either absolute
(like :file:`/usr/src/Python-1.5/Makefile`) or relative (like
:file:`../../Tools/\*/\*.gif`), and can contain shell-style wildcards. Broken
symlinks are included in the results (as in the shell).
.. function:: iglob(pathname)
Return an iterator which yields the same values as :func:`glob` without actually
storing them all simultaneously.
.. versionadded:: 2.5
For example, consider a directory containing only the following files:
:file:`1.gif`, :file:`2.txt`, and :file:`card.gif`. :func:`glob` will produce
the following results. Notice how any leading components of the path are
preserved. ::
>>> import glob
>>> glob.glob('./[0-9].*')
['./1.gif', './2.txt']
>>> glob.glob('*.gif')
['1.gif', 'card.gif']
>>> glob.glob('?.gif')
['1.gif']
.. seealso::
Module :mod:`fnmatch`
Shell-style filename (not path) expansion

63
Doc-3k/library/grp.rst Normal file
View File

@@ -0,0 +1,63 @@
:mod:`grp` --- The group database
=================================
.. module:: grp
:platform: Unix
:synopsis: The group database (getgrnam() and friends).
This module provides access to the Unix group database. It is available on all
Unix versions.
Group database entries are reported as a tuple-like object, whose attributes
correspond to the members of the ``group`` structure (Attribute field below, see
``<pwd.h>``):
+-------+-----------+---------------------------------+
| Index | Attribute | Meaning |
+=======+===========+=================================+
| 0 | gr_name | the name of the group |
+-------+-----------+---------------------------------+
| 1 | gr_passwd | the (encrypted) group password; |
| | | often empty |
+-------+-----------+---------------------------------+
| 2 | gr_gid | the numerical group ID |
+-------+-----------+---------------------------------+
| 3 | gr_mem | all the group member's user |
| | | names |
+-------+-----------+---------------------------------+
The gid is an integer, name and password are strings, and the member list is a
list of strings. (Note that most users are not explicitly listed as members of
the group they are in according to the password database. Check both databases
to get complete membership information.)
It defines the following items:
.. function:: getgrgid(gid)
Return the group database entry for the given numeric group ID. :exc:`KeyError`
is raised if the entry asked for cannot be found.
.. function:: getgrnam(name)
Return the group database entry for the given group name. :exc:`KeyError` is
raised if the entry asked for cannot be found.
.. function:: getgrall()
Return a list of all available group entries, in arbitrary order.
.. seealso::
Module :mod:`pwd`
An interface to the user database, similar to this.
Module :mod:`spwd`
An interface to the shadow password database, similar to this.

Some files were not shown because too many files have changed in this diff Show More